@rpgjs/client 5.0.0-alpha.9 → 5.0.0-beta.10

package/dist/RpgClientEngine.js

@@ -0,0 +1,1442 @@
+import { inject } from "./core/inject.js";
+import { WebSocketToken } from "./services/AbstractSocket.js";
+import { getCanMoveValue } from "./utils/readPropValue.js";
+import { SaveClientService } from "./services/save.js";
+import { RpgGui } from "./Gui/Gui.js";
+import __ce_component from "./components/scenes/canvas.ce.js";
+import { LoadMapToken } from "./services/loadMap.js";
+import { RpgSound } from "./Sound.js";
+import { RpgResource } from "./Resource.js";
+import { load } from "./node_modules/.pnpm/@signe_sync@3.0.1/node_modules/@signe/sync/dist/index.js";
+import { RpgClientMap } from "./Game/Map.js";
+import { AnimationManager } from "./Game/AnimationManager.js";
+import { GlobalConfigToken } from "./module.js";
+import { PrebuiltComponentAnimations } from "./components/animations/index.js";
+import __ce_component$1 from "./components/dynamics/text.ce.js";
+import __ce_component$2 from "./components/dynamics/bar.ce.js";
+import __ce_component$3 from "./components/dynamics/shape.ce.js";
+import __ce_component$4 from "./components/dynamics/image.ce.js";
+import { NotificationManager } from "./Gui/NotificationManager.js";
+import { Howl, bootstrapCanvas, signal, trigger } from "canvasengine";
+import { Direction, ModulesToken, PredictionController, normalizeLightingState } from "@rpgjs/common";
+import { BehaviorSubject, combineLatest, filter, lastValueFrom, switchMap, take } from "rxjs";
+import * as PIXI from "pixi.js";
+//#region src/RpgClientEngine.ts
+var RpgClientEngine = class {
+	constructor(context) {
+		this.context = context;
+		this.stopProcessingInput = false;
+		this.width = signal("100%");
+		this.height = signal("100%");
+		this.spritesheets = /* @__PURE__ */ new Map();
+		this.sounds = /* @__PURE__ */ new Map();
+		this.componentAnimations = [];
+		this.particleSettings = { emitters: [] };
+		this.playerIdSignal = signal(null);
+		this.spriteComponentsBehind = signal([]);
+		this.spriteComponentsInFront = signal([]);
+		this.spriteComponents = /* @__PURE__ */ new Map();
+		this.cameraFollowTargetId = signal(null);
+		this.mapShakeTrigger = trigger();
+		this.controlsReady = signal(void 0);
+		this.gamePause = signal(false);
+		this.predictionEnabled = false;
+		this.SERVER_CORRECTION_THRESHOLD = 30;
+		this.inputFrameCounter = 0;
+		this.pendingPredictionFrames = [];
+		this.lastClientPhysicsStepAt = 0;
+		this.frameOffset = 0;
+		this.rtt = 0;
+		this.pingInterval = null;
+		this.PING_INTERVAL_MS = 5e3;
+		this.lastInputTime = 0;
+		this.MOVE_PATH_RESEND_INTERVAL_MS = 120;
+		this.MAX_MOVE_TRAJECTORY_POINTS = 240;
+		this.lastMovePathSentAt = 0;
+		this.lastMovePathSentFrame = 0;
+		this.mapLoadCompleted$ = new BehaviorSubject(false);
+		this.playerIdReceived$ = new BehaviorSubject(false);
+		this.playersReceived$ = new BehaviorSubject(false);
+		this.eventsReceived$ = new BehaviorSubject(false);
+		this.sceneResetQueued = false;
+		this.tickSubscriptions = [];
+		this.notificationManager = new NotificationManager();
+		this.webSocket = inject(WebSocketToken);
+		this.guiService = inject(RpgGui);
+		this.loadMapService = inject(LoadMapToken);
+		this.hooks = inject(ModulesToken);
+		this.globalConfig = inject(GlobalConfigToken);
+		if (!this.globalConfig) this.globalConfig = {};
+		if (!this.globalConfig.box) this.globalConfig.box = {
+			styles: {
+				backgroundColor: "#1a1a2e",
+				backgroundOpacity: .9
+			},
+			sounds: {}
+		};
+		this.addComponentAnimation({
+			id: "animation",
+			component: PrebuiltComponentAnimations.Animation
+		});
+		this.registerSpriteComponent("rpg:text", __ce_component$1);
+		this.registerSpriteComponent("rpg:hpBar", __ce_component$2);
+		this.registerSpriteComponent("rpg:spBar", __ce_component$2);
+		this.registerSpriteComponent("rpg:bar", __ce_component$2);
+		this.registerSpriteComponent("rpg:shape", __ce_component$3);
+		this.registerSpriteComponent("rpg:image", __ce_component$4);
+		this.predictionEnabled = this.globalConfig?.prediction?.enabled !== false;
+		this.initializePredictionController();
+	}
+	/**
+	* Assigns a CanvasEngine KeyboardControls instance to the dependency injection context
+	* 
+	* This method registers a KeyboardControls instance from CanvasEngine into the DI container,
+	* making it available for injection throughout the application. The particularity is that
+	* this method is automatically called when a sprite is displayed on the map, allowing the
+	* controls to be automatically associated with the active sprite.
+	* 
+	* ## Design
+	* 
+	* - The instance is stored in the DI context under the `KeyboardControls` token
+	* - It's automatically assigned when a sprite component mounts (in `character.ce`)
+	* - The controls instance comes from the CanvasEngine component's directives
+	* - Once registered, it can be retrieved using `inject(KeyboardControls)` from anywhere
+	* 
+	* @param controlInstance - The CanvasEngine KeyboardControls instance to register
+	* 
+	* @example
+	* ```ts
+	* // The method is automatically called when a sprite is displayed:
+	* // client.setKeyboardControls(element.directives.controls)
+	* 
+	* // Later, retrieve and use the controls instance:
+	* import { Input, inject, KeyboardControls } from '@rpgjs/client'
+	* 
+	* const controls = inject(KeyboardControls)
+	* const control = controls.getControl(Input.Enter)
+	* 
+	* if (control) {
+	*   console.log(control.actionName) // 'action'
+	* }
+	* ```
+	*/
+	setKeyboardControls(controlInstance) {
+		const currentValues = this.context.values["inject:KeyboardControls"];
+		this.context.values["inject:KeyboardControls"] = {
+			...currentValues,
+			values: new Map([["__default__", controlInstance]])
+		};
+		this.controlsReady.set(void 0);
+	}
+	async start() {
+		this.sceneMap = new RpgClientMap();
+		this.sceneMap.configureClientPrediction(this.predictionEnabled);
+		this.sceneMap.loadPhysic();
+		this.selector = document.body.querySelector("#rpg");
+		const bootstrapOptions = this.globalConfig?.bootstrapCanvasOptions;
+		const { app, canvasElement } = await bootstrapCanvas(this.selector, __ce_component, bootstrapOptions);
+		this.canvasApp = app;
+		this.canvasElement = canvasElement;
+		this.renderer = app.renderer;
+		this.tick = canvasElement?.propObservables?.context["tick"].observable;
+		const inputCheckSubscription = this.tick.subscribe(() => {
+			if (Date.now() - this.lastInputTime > 100) {
+				const player = this.getCurrentPlayer();
+				if (!player) return;
+				this.sceneMap.stopMovement(player);
+			}
+		});
+		this.tickSubscriptions.push(inputCheckSubscription);
+		this.hooks.callHooks("client-spritesheets-load", this).subscribe();
+		this.hooks.callHooks("client-spritesheetResolver-load", this).subscribe();
+		this.hooks.callHooks("client-sounds-load", this).subscribe();
+		this.hooks.callHooks("client-soundResolver-load", this).subscribe();
+		RpgSound.init(this);
+		RpgResource.init(this);
+		this.hooks.callHooks("client-gui-load", this).subscribe();
+		this.hooks.callHooks("client-particles-load", this).subscribe();
+		this.hooks.callHooks("client-componentAnimations-load", this).subscribe();
+		this.hooks.callHooks("client-sprite-load", this).subscribe();
+		await lastValueFrom(this.hooks.callHooks("client-engine-onStart", this));
+		this.resizeHandler = () => {
+			this.hooks.callHooks("client-engine-onWindowResize", this).subscribe();
+		};
+		window.addEventListener("resize", this.resizeHandler);
+		const tickSubscription = this.tick.subscribe((tick) => {
+			this.stepClientPhysicsTick();
+			this.flushPendingPredictedStates();
+			this.flushPendingMovePath();
+			this.hooks.callHooks("client-engine-onStep", this, tick).subscribe();
+			if (tick % 60 === 0) {
+				const now = Date.now();
+				this.prediction?.cleanup(now);
+				this.prediction?.tryApplyPendingSnapshot();
+			}
+		});
+		this.tickSubscriptions.push(tickSubscription);
+		await this.webSocket.connection(() => {
+			inject(SaveClientService).initialize();
+			this.initListeners();
+			this.guiService._initialize();
+			this.startPingPong();
+		});
+	}
+	prepareSyncPayload(data) {
+		const payload = { ...data ?? {} };
+		delete payload.ack;
+		delete payload.timestamp;
+		const myId = this.playerIdSignal();
+		const players = payload.players;
+		if (this.predictionEnabled && !!this.prediction?.hasPendingInputs() && myId && players && players[myId]) {
+			const localPatch = { ...players[myId] };
+			delete localPatch.x;
+			delete localPatch.y;
+			delete localPatch.direction;
+			delete localPatch._frames;
+			payload.players = {
+				...players,
+				[myId]: localPatch
+			};
+		}
+		return payload;
+	}
+	normalizeAckWithSyncState(ack, syncData) {
+		const myId = this.playerIdSignal();
+		if (!myId) return ack;
+		const localPatch = syncData?.players?.[myId];
+		if (typeof localPatch?.x !== "number" || typeof localPatch?.y !== "number") return ack;
+		return {
+			...ack,
+			x: localPatch.x,
+			y: localPatch.y,
+			direction: localPatch.direction ?? ack.direction
+		};
+	}
+	initListeners() {
+		this.webSocket.on("sync", (data) => {
+			if (data.pId) {
+				this.playerIdSignal.set(data.pId);
+				this.playerIdReceived$.next(true);
+			}
+			if (this.sceneResetQueued) {
+				this.sceneMap.reset();
+				this.sceneMap.loadPhysic();
+				this.sceneResetQueued = false;
+			}
+			this.hooks.callHooks("client-sceneMap-onChanges", this.sceneMap, { partial: data }).subscribe();
+			const ack = data?.ack;
+			const normalizedAck = ack && typeof ack.frame === "number" ? this.normalizeAckWithSyncState(ack, data) : void 0;
+			const payload = this.prepareSyncPayload(data);
+			load(this.sceneMap, payload, true);
+			if (normalizedAck) this.applyServerAck(normalizedAck);
+			for (const playerId in payload.players ?? {}) {
+				const player = payload.players[playerId];
+				if (!player._param) continue;
+				for (const param in player._param) this.sceneMap.players()[playerId]._param()[param] = player._param[param];
+			}
+			const players = payload.players || this.sceneMap.players();
+			if (players && Object.keys(players).length > 0) this.playersReceived$.next(true);
+			if ((payload.events || this.sceneMap.events()) !== void 0) this.eventsReceived$.next(true);
+		});
+		this.webSocket.on("pong", (data) => {
+			const now = Date.now();
+			this.rtt = now - data.clientTime;
+			const estimatedTicksInFlight = Math.floor(this.rtt / 2 / (1e3 / 60));
+			const estimatedServerTickNow = data.serverTick + estimatedTicksInFlight;
+			if (this.inputFrameCounter > 0) this.frameOffset = estimatedServerTickNow - data.clientFrame;
+			console.debug(`[Ping/Pong] RTT: ${this.rtt}ms, ServerTick: ${data.serverTick}, FrameOffset: ${this.frameOffset}`);
+		});
+		this.webSocket.on("changeMap", (data) => {
+			this.sceneResetQueued = true;
+			this.sceneMap.clearLightSpots();
+			this.cameraFollowTargetId.set(null);
+			const transferToken = typeof data?.transferToken === "string" ? data.transferToken : void 0;
+			this.loadScene(data.mapId, transferToken);
+		});
+		this.webSocket.on("showComponentAnimation", (data) => {
+			const { params, object, position, id } = data;
+			if (!object && position === void 0) throw new Error("Please provide an object or x and y coordinates");
+			const player = object ? this.sceneMap.getObjectById(object) : void 0;
+			this.getComponentAnimation(id).displayEffect(params, player || position);
+		});
+		this.webSocket.on("notification", (data) => {
+			this.notificationManager.add(data);
+		});
+		this.webSocket.on("setAnimation", (data) => {
+			const { animationName, nbTimes, object, graphic, restoreAnimationName, restoreGraphics } = data;
+			const player = object ? this.sceneMap.getObjectById(object) : void 0;
+			if (!player) return;
+			const restoreOptions = {
+				restoreAnimationName,
+				restoreGraphics
+			};
+			if (graphic !== void 0) player.setAnimation(animationName, graphic, nbTimes, restoreOptions);
+			else player.setAnimation(animationName, nbTimes, restoreOptions);
+		});
+		this.webSocket.on("playSound", (data) => {
+			const { soundId, volume, loop } = data;
+			this.playSound(soundId, {
+				volume,
+				loop
+			});
+		});
+		this.webSocket.on("stopSound", (data) => {
+			const { soundId } = data;
+			this.stopSound(soundId);
+		});
+		this.webSocket.on("stopAllSounds", () => {
+			this.stopAllSounds();
+		});
+		this.webSocket.on("cameraFollow", (data) => {
+			const { targetId, smoothMove } = data;
+			this.setCameraFollow(targetId, smoothMove);
+		});
+		this.webSocket.on("flash", (data) => {
+			const { object, type, duration, cycles, alpha, tint } = data;
+			const sprite = object ? this.sceneMap.getObjectById(object) : void 0;
+			if (sprite && typeof sprite.flash === "function") sprite.flash({
+				type,
+				duration,
+				cycles,
+				alpha,
+				tint
+			});
+		});
+		this.webSocket.on("shakeMap", (data) => {
+			const { intensity, duration, frequency, direction } = data || {};
+			this.mapShakeTrigger.start({
+				intensity,
+				duration,
+				frequency,
+				direction
+			});
+		});
+		this.webSocket.on("weatherState", (data) => {
+			const raw = data && typeof data === "object" && "value" in data ? data.value : data;
+			if (raw === null) {
+				this.sceneMap.weatherState.set(null);
+				return;
+			}
+			if (!raw || ![
+				"rain",
+				"snow",
+				"fog",
+				"cloud"
+			].includes(raw.effect)) return;
+			this.sceneMap.weatherState.set({
+				effect: raw.effect,
+				preset: raw.preset,
+				params: raw.params,
+				transitionMs: raw.transitionMs,
+				durationMs: raw.durationMs,
+				startedAt: raw.startedAt,
+				seed: raw.seed
+			});
+		});
+		this.webSocket.on("lightingState", (data) => {
+			const raw = data && typeof data === "object" && "value" in data ? data.value : data;
+			this.sceneMap.lightingState.set(normalizeLightingState(raw));
+		});
+		this.webSocket.on("open", () => {
+			this.hooks.callHooks("client-engine-onConnected", this, this.socket).subscribe();
+			this.startPingPong();
+		});
+		this.webSocket.on("close", () => {
+			this.hooks.callHooks("client-engine-onDisconnected", this, this.socket).subscribe();
+			this.stopPingPong();
+		});
+		this.webSocket.on("error", (error) => {
+			this.hooks.callHooks("client-engine-onConnectError", this, error, this.socket).subscribe();
+		});
+	}
+	/**
+	* Start periodic ping/pong for client-server synchronization
+	* 
+	* Sends ping requests to the server to measure round-trip time (RTT) and
+	* calculate the frame offset between client and server ticks.
+	* 
+	* ## Design
+	* 
+	* - Sends ping every 5 seconds
+	* - Measures RTT for latency compensation
+	* - Calculates frame offset to map client frames to server ticks
+	* - Used for accurate server reconciliation
+	* 
+	* @example
+	* ```ts
+	* // Called automatically when connection opens
+	* this.startPingPong();
+	* ```
+	*/
+	startPingPong() {
+		this.stopPingPong();
+		this.sendPing();
+		this.pingInterval = setInterval(() => {
+			this.sendPing();
+		}, this.PING_INTERVAL_MS);
+	}
+	/**
+	* Stop periodic ping/pong
+	* 
+	* Stops the ping interval when disconnecting or changing maps.
+	* 
+	* @example
+	* ```ts
+	* // Called automatically when connection closes
+	* this.stopPingPong();
+	* ```
+	*/
+	stopPingPong() {
+		if (this.pingInterval) {
+			clearInterval(this.pingInterval);
+			this.pingInterval = null;
+		}
+	}
+	/**
+	* Send a ping request to the server
+	* 
+	* Sends current client time and frame counter to the server,
+	* which will respond with its server tick for synchronization.
+	* 
+	* @example
+	* ```ts
+	* // Send a ping to measure RTT
+	* this.sendPing();
+	* ```
+	*/
+	sendPing() {
+		const clientTime = Date.now();
+		const clientFrame = this.getPhysicsTick();
+		this.webSocket.emit("ping", {
+			clientTime,
+			clientFrame
+		});
+	}
+	async loadScene(mapId, transferToken) {
+		await lastValueFrom(this.hooks.callHooks("client-sceneMap-onBeforeLoading", this.sceneMap));
+		this.clearClientPredictionStates();
+		this.mapLoadCompleted$.next(false);
+		this.playerIdReceived$.next(false);
+		this.playersReceived$.next(false);
+		this.eventsReceived$.next(false);
+		if (this.onAfterLoadingSubscription) this.onAfterLoadingSubscription.unsubscribe();
+		this.setupOnAfterLoadingObserver();
+		this.webSocket.updateProperties({
+			room: mapId,
+			query: transferToken ? { transferToken } : void 0
+		});
+		await this.webSocket.reconnect(() => {
+			inject(SaveClientService).initialize();
+			this.initListeners();
+			this.guiService._initialize();
+		});
+		const res = await this.loadMapService.load(mapId);
+		this.sceneMap.data.set(res);
+		if (this.playerIdSignal()) this.playerIdReceived$.next(true);
+		const players = this.sceneMap.players();
+		if (players && Object.keys(players).length > 0) this.playersReceived$.next(true);
+		if (this.sceneMap.events() !== void 0) this.eventsReceived$.next(true);
+		this.mapLoadCompleted$.next(true);
+		this.sceneMap.configureClientPrediction(this.predictionEnabled);
+		this.sceneMap.loadPhysic();
+	}
+	addSpriteSheet(spritesheetClass, id) {
+		this.spritesheets.set(id || spritesheetClass.id, spritesheetClass);
+		return spritesheetClass;
+	}
+	/**
+	* Set a resolver function for spritesheets
+	* 
+	* The resolver is called when a spritesheet is requested but not found in the cache.
+	* It can be synchronous (returns directly) or asynchronous (returns a Promise).
+	* The resolved spritesheet is automatically cached for future use.
+	* 
+	* @param resolver - Function that takes a spritesheet ID and returns a spritesheet or Promise of spritesheet
+	* 
+	* @example
+	* ```ts
+	* // Synchronous resolver
+	* engine.setSpritesheetResolver((id) => {
+	*   if (id === 'dynamic-sprite') {
+	*     return { id: 'dynamic-sprite', image: 'path/to/image.png', framesWidth: 32, framesHeight: 32 };
+	*   }
+	*   return undefined;
+	* });
+	* 
+	* // Asynchronous resolver (loading from API)
+	* engine.setSpritesheetResolver(async (id) => {
+	*   const response = await fetch(`/api/spritesheets/${id}`);
+	*   const data = await response.json();
+	*   return data;
+	* });
+	* ```
+	*/
+	setSpritesheetResolver(resolver) {
+		this.spritesheetResolver = resolver;
+	}
+	/**
+	* Get a spritesheet by ID, using resolver if not found in cache
+	* 
+	* This method first checks if the spritesheet exists in the cache.
+	* If not found and a resolver is set, it calls the resolver to create the spritesheet.
+	* The resolved spritesheet is automatically cached for future use.
+	* 
+	* @param id - The spritesheet ID or legacy tile ID to retrieve
+	* @returns The spritesheet if found or created, or undefined if not found and no resolver
+	* @returns Promise<any> if the resolver is asynchronous
+	* 
+	* @example
+	* ```ts
+	* // Synchronous usage
+	* const spritesheet = engine.getSpriteSheet('my-sprite');
+	* 
+	* // Asynchronous usage (when resolver returns Promise)
+	* const spritesheet = await engine.getSpriteSheet('dynamic-sprite');
+	* ```
+	*/
+	getSpriteSheet(id) {
+		if (this.spritesheets.has(id)) return this.spritesheets.get(id);
+		if (this.spritesheetResolver) {
+			const result = this.spritesheetResolver(id);
+			if (result instanceof Promise) return result.then((spritesheet) => {
+				if (spritesheet) this.spritesheets.set(id, spritesheet);
+				return spritesheet;
+			});
+			else {
+				if (result) this.spritesheets.set(id, result);
+				return result;
+			}
+		}
+	}
+	/**
+	* Add a sound to the engine
+	* 
+	* Adds a sound to the engine's sound cache. The sound can be:
+	* - A simple object with `id` and `src` properties
+	* - A Howler instance
+	* - An object with a `play()` method
+	* 
+	* If the sound has a `src` property, a Howler instance will be created automatically.
+	* 
+	* @param sound - The sound object or Howler instance
+	* @param id - Optional sound ID (if not provided, uses sound.id)
+	* @returns The added sound
+	* 
+	* @example
+	* ```ts
+	* // Simple sound object
+	* engine.addSound({ id: 'click', src: 'click.mp3' });
+	* 
+	* // With explicit ID
+	* engine.addSound({ src: 'music.mp3' }, 'background-music');
+	* ```
+	*/
+	addSound(sound, id) {
+		const soundId = id || sound.id;
+		if (!soundId) {
+			console.warn("Sound added without an ID. It will not be retrievable.");
+			return sound;
+		}
+		if (sound.src && typeof sound.src === "string") {
+			const howlOptions = {
+				src: [sound.src],
+				loop: sound.loop || false,
+				volume: sound.volume !== void 0 ? sound.volume : 1
+			};
+			const howl = new Howl.Howl(howlOptions);
+			this.sounds.set(soundId, howl);
+			return howl;
+		}
+		if (sound && typeof sound.play === "function") {
+			this.sounds.set(soundId, sound);
+			return sound;
+		}
+		this.sounds.set(soundId, sound);
+		return sound;
+	}
+	/**
+	* Set a resolver function for sounds
+	* 
+	* The resolver is called when a sound is requested but not found in the cache.
+	* It can be synchronous (returns directly) or asynchronous (returns a Promise).
+	* The resolved sound is automatically cached for future use.
+	* 
+	* @param resolver - Function that takes a sound ID and returns a sound or Promise of sound
+	* 
+	* @example
+	* ```ts
+	* // Synchronous resolver
+	* engine.setSoundResolver((id) => {
+	*   if (id === 'dynamic-sound') {
+	*     return { id: 'dynamic-sound', src: 'path/to/sound.mp3' };
+	*   }
+	*   return undefined;
+	* });
+	* 
+	* // Asynchronous resolver (loading from API)
+	* engine.setSoundResolver(async (id) => {
+	*   const response = await fetch(`/api/sounds/${id}`);
+	*   const data = await response.json();
+	*   return data;
+	* });
+	* ```
+	*/
+	setSoundResolver(resolver) {
+		this.soundResolver = resolver;
+	}
+	/**
+	* Get a sound by ID, using resolver if not found in cache
+	* 
+	* This method first checks if the sound exists in the cache.
+	* If not found and a resolver is set, it calls the resolver to create the sound.
+	* The resolved sound is automatically cached for future use.
+	* 
+	* @param id - The sound ID to retrieve
+	* @returns The sound if found or created, or undefined if not found and no resolver
+	* @returns Promise<any> if the resolver is asynchronous
+	* 
+	* @example
+	* ```ts
+	* // Synchronous usage
+	* const sound = engine.getSound('my-sound');
+	* 
+	* // Asynchronous usage (when resolver returns Promise)
+	* const sound = await engine.getSound('dynamic-sound');
+	* ```
+	*/
+	getSound(id) {
+		if (this.sounds.has(id)) return this.sounds.get(id);
+		if (this.soundResolver) {
+			const result = this.soundResolver(id);
+			if (result instanceof Promise) return result.then((sound) => {
+				if (sound) this.sounds.set(id, sound);
+				return sound;
+			});
+			else {
+				if (result) this.sounds.set(id, result);
+				return result;
+			}
+		}
+	}
+	/**
+	* Play a sound by its ID
+	* 
+	* This method retrieves a sound from the cache or resolver and plays it.
+	* If the sound is not found, it will attempt to resolve it using the soundResolver.
+	* Uses Howler.js for audio playback instead of native Audio elements.
+	* 
+	* @param soundId - The sound ID to play
+	* @param options - Optional sound configuration
+	* @param options.volume - Volume level (0.0 to 1.0, overrides sound default)
+	* @param options.loop - Whether the sound should loop (overrides sound default)
+	* 
+	* @example
+	* ```ts
+	* // Play a sound synchronously
+	* engine.playSound('item-pickup');
+	* 
+	* // Play a sound with volume and loop
+	* engine.playSound('background-music', { volume: 0.5, loop: true });
+	* 
+	* // Play a sound asynchronously (when resolver returns Promise)
+	* await engine.playSound('dynamic-sound', { volume: 0.8 });
+	* ```
+	*/
+	async playSound(soundId, options) {
+		const sound = await this.getSound(soundId);
+		if (sound && sound.play) {
+			const howlSoundId = sound._sounds?.[0]?._id;
+			if (options?.volume !== void 0) if (howlSoundId !== void 0) sound.volume(Math.max(0, Math.min(1, options.volume)), howlSoundId);
+			else sound.volume(Math.max(0, Math.min(1, options.volume)));
+			if (options?.loop !== void 0) if (howlSoundId !== void 0) sound.loop(options.loop, howlSoundId);
+			else sound.loop(options.loop);
+			if (howlSoundId !== void 0) sound.play(howlSoundId);
+			else sound.play();
+		} else if (sound && sound.src) {
+			const howlOptions = {
+				src: [sound.src],
+				loop: options?.loop !== void 0 ? options.loop : sound.loop || false,
+				volume: options?.volume !== void 0 ? Math.max(0, Math.min(1, options.volume)) : sound.volume !== void 0 ? sound.volume : 1
+			};
+			const howl = new Howl.Howl(howlOptions);
+			this.sounds.set(soundId, howl);
+			howl.play();
+		} else console.warn(`Sound with id "${soundId}" not found or cannot be played`);
+	}
+	/**
+	* Stop a sound that is currently playing
+	* 
+	* This method stops a sound that was previously started with `playSound()`.
+	* 
+	* @param soundId - The sound ID to stop
+	* 
+	* @example
+	* ```ts
+	* // Start a looping sound
+	* engine.playSound('background-music', { loop: true });
+	* 
+	* // Later, stop it
+	* engine.stopSound('background-music');
+	* ```
+	*/
+	stopSound(soundId) {
+		const sound = this.sounds.get(soundId);
+		if (sound && sound.stop) sound.stop();
+		else console.warn(`Sound with id "${soundId}" not found or cannot be stopped`);
+	}
+	/**
+	* Stop all currently playing sounds
+	* 
+	* This method stops all sounds that are currently playing.
+	* Useful when changing maps to prevent sound overlap.
+	* 
+	* @example
+	* ```ts
+	* // Stop all sounds
+	* engine.stopAllSounds();
+	* ```
+	*/
+	stopAllSounds() {
+		this.sounds.forEach((sound) => {
+			if (sound && sound.stop) sound.stop();
+		});
+	}
+	/**
+	* Set the camera to follow a specific sprite
+	* 
+	* This method changes which sprite the camera viewport should follow.
+	* The camera will smoothly animate to the target sprite if smoothMove options are provided.
+	* 
+	* ## Design
+	* 
+	* The camera follow target is stored in a signal that is read by sprite components.
+	* Each sprite checks if it should be followed by comparing its ID with the target ID.
+	* When smoothMove options are provided, the viewport animation is handled by CanvasEngine's
+	* viewport system.
+	* 
+	* @param targetId - The ID of the sprite to follow. Set to null to follow the current player
+	* @param smoothMove - Animation options. Can be a boolean (default: true) or an object with time and ease
+	* @param smoothMove.time - Duration of the animation in milliseconds (optional)
+	* @param smoothMove.ease - Easing function name from https://easings.net (optional)
+	* 
+	* @example
+	* ```ts
+	* // Follow another player with default smooth animation
+	* engine.setCameraFollow(otherPlayerId, true);
+	* 
+	* // Follow an event with custom smooth animation
+	* engine.setCameraFollow(eventId, {
+	*   time: 1000,
+	*   ease: "easeInOutQuad"
+	* });
+	* 
+	* // Follow without animation (instant)
+	* engine.setCameraFollow(targetId, false);
+	* 
+	* // Return to following current player
+	* engine.setCameraFollow(null);
+	* ```
+	*/
+	setCameraFollow(targetId, smoothMove) {
+		this.cameraFollowTargetId.set(targetId);
+		if (typeof smoothMove === "object" && smoothMove !== null) {}
+	}
+	addParticle(particle) {
+		this.particleSettings.emitters.push(particle);
+		return particle;
+	}
+	/**
+	* Add a component to render behind sprites
+	* Components added with this method will be displayed with a lower z-index than the sprite
+	* 
+	* Supports multiple formats:
+	* 1. Direct component: `ShadowComponent`
+	* 2. Configuration object: `{ component: LightHalo, props: {...} }`
+	* 3. With dynamic props: `{ component: LightHalo, props: (object) => {...} }`
+	* 4. With dependencies: `{ component: HealthBar, dependencies: (object) => [object.hp, object.param.maxHp] }`
+	* 
+	* Components with dependencies will only be displayed when all dependencies are resolved (!= undefined).
+	* The object (sprite) is passed to the dependencies function to allow sprite-specific dependency resolution.
+	* 
+	* @param component - The component to add behind sprites, or a configuration object
+	* @param component.component - The component function to render
+	* @param component.props - Static props object or function that receives the sprite object and returns props
+	* @param component.dependencies - Function that receives the sprite object and returns an array of Signals
+	* @returns The added component or configuration
+	* 
+	* @example
+	* ```ts
+	* // Add a shadow component behind all sprites
+	* engine.addSpriteComponentBehind(ShadowComponent);
+	* 
+	* // Add a component with static props
+	* engine.addSpriteComponentBehind({ 
+	*   component: LightHalo, 
+	*   props: { radius: 30 } 
+	* });
+	* 
+	* // Add a component with dynamic props and dependencies
+	* engine.addSpriteComponentBehind({ 
+	*   component: HealthBar, 
+	*   props: (object) => ({ hp: object.hp(), maxHp: object.param.maxHp() }),
+	*   dependencies: (object) => [object.hp, object.param.maxHp]
+	* });
+	* ```
+	*/
+	addSpriteComponentBehind(component) {
+		this.spriteComponentsBehind.update((components) => [...components, component]);
+		return component;
+	}
+	/**
+	* Add a component to render in front of sprites
+	* Components added with this method will be displayed with a higher z-index than the sprite
+	* 
+	* Supports multiple formats:
+	* 1. Direct component: `HealthBarComponent`
+	* 2. Configuration object: `{ component: StatusIndicator, props: {...} }`
+	* 3. With dynamic props: `{ component: HealthBar, props: (object) => {...} }`
+	* 4. With dependencies: `{ component: HealthBar, dependencies: (object) => [object.hp, object.param.maxHp] }`
+	* 
+	* Components with dependencies will only be displayed when all dependencies are resolved (!= undefined).
+	* The object (sprite) is passed to the dependencies function to allow sprite-specific dependency resolution.
+	* 
+	* @param component - The component to add in front of sprites, or a configuration object
+	* @param component.component - The component function to render
+	* @param component.props - Static props object or function that receives the sprite object and returns props
+	* @param component.dependencies - Function that receives the sprite object and returns an array of Signals
+	* @returns The added component or configuration
+	* 
+	* @example
+	* ```ts
+	* // Add a health bar component in front of all sprites
+	* engine.addSpriteComponentInFront(HealthBarComponent);
+	* 
+	* // Add a component with static props
+	* engine.addSpriteComponentInFront({ 
+	*   component: StatusIndicator, 
+	*   props: { type: 'poison' } 
+	* });
+	* 
+	* // Add a component with dynamic props and dependencies
+	* engine.addSpriteComponentInFront({ 
+	*   component: HealthBar, 
+	*   props: (object) => ({ hp: object.hp(), maxHp: object.param.maxHp() }),
+	*   dependencies: (object) => [object.hp, object.param.maxHp]
+	* });
+	* ```
+	*/
+	addSpriteComponentInFront(component) {
+		this.spriteComponentsInFront.update((components) => [...components, component]);
+		return component;
+	}
+	/**
+	* Register a reusable sprite component that can be addressed by the server.
+	*
+	* Server-side component definitions only carry the component id and
+	* serializable props. The client registry maps that id to the CanvasEngine
+	* component that performs the actual rendering.
+	*
+	* @param id - Stable component id used by server component definitions
+	* @param component - CanvasEngine component to render for this id
+	* @returns The registered component
+	*
+	* @example
+	* ```ts
+	* engine.registerSpriteComponent('guildBadge', GuildBadgeComponent);
+	* ```
+	*/
+	registerSpriteComponent(id, component) {
+		this.spriteComponents.set(id, component);
+		return component;
+	}
+	/**
+	* Get a reusable sprite component by id.
+	*
+	* @param id - Component id registered on the client
+	* @returns The CanvasEngine component, or undefined when missing
+	*/
+	getSpriteComponent(id) {
+		return this.spriteComponents.get(id);
+	}
+	/**
+	* Add a component animation to the engine
+	* 
+	* Component animations are temporary visual effects that can be displayed
+	* on sprites or objects, such as hit indicators, spell effects, or status animations.
+	* 
+	* @param componentAnimation - The component animation configuration
+	* @param componentAnimation.id - Unique identifier for the animation
+	* @param componentAnimation.component - The component function to render
+	* @returns The added component animation configuration
+	* 
+	* @example
+	* ```ts
+	* // Add a hit animation component
+	* engine.addComponentAnimation({
+	*   id: 'hit',
+	*   component: HitComponent
+	* });
+	* 
+	* // Add an explosion effect component
+	* engine.addComponentAnimation({
+	*   id: 'explosion',
+	*   component: ExplosionComponent
+	* });
+	* ```
+	*/
+	addComponentAnimation(componentAnimation) {
+		const instance = new AnimationManager();
+		this.componentAnimations.push({
+			id: componentAnimation.id,
+			component: componentAnimation.component,
+			instance,
+			current: instance.current
+		});
+		return componentAnimation;
+	}
+	/**
+	* Get a component animation by its ID
+	* 
+	* Retrieves the EffectManager instance for a specific component animation,
+	* which can be used to display the animation on sprites or objects.
+	* 
+	* @param id - The unique identifier of the component animation
+	* @returns The EffectManager instance for the animation
+	* @throws Error if the component animation is not found
+	* 
+	* @example
+	* ```ts
+	* // Get the hit animation and display it
+	* const hitAnimation = engine.getComponentAnimation('hit');
+	* hitAnimation.displayEffect({ text: "Critical!" }, player);
+	* ```
+	*/
+	getComponentAnimation(id) {
+		const componentAnimation = this.componentAnimations.find((componentAnimation) => componentAnimation.id === id);
+		if (!componentAnimation) throw new Error(`Component animation with id ${id} not found`);
+		return componentAnimation.instance;
+	}
+	/**
+	* Start a transition
+	* 
+	* Convenience method to display a transition by its ID using the GUI system.
+	* 
+	* @param id - The unique identifier of the transition to start
+	* @param props - Props to pass to the transition component
+	* 
+	* @example
+	* ```ts
+	* // Start a fade transition
+	* engine.startTransition('fade', { duration: 1000, color: 'black' });
+	* 
+	* // Start with onFinish callback
+	* engine.startTransition('fade', {
+	*   duration: 1000,
+	*   onFinish: () => console.log('Fade complete')
+	* });
+	*
+	* // Wait until the transition component calls onFinish
+	* await engine.startTransition('fade', { duration: 1000 });
+	* ```
+	*/
+	startTransition(id, props = {}) {
+		if (!this.guiService.exists(id)) throw new Error(`Transition with id ${id} not found. Make sure to add it using engine.addTransition() or in your module's transitions property.`);
+		return new Promise((resolve) => {
+			let finished = false;
+			const finish = (data) => {
+				if (finished) return;
+				finished = true;
+				props?.onFinish?.(data);
+				resolve();
+			};
+			this.guiService.display(id, {
+				...props,
+				onFinish: finish
+			});
+		});
+	}
+	async processInput({ input }) {
+		if (this.stopProcessingInput) return;
+		const currentPlayer = this.sceneMap.getCurrentPlayer();
+		if (!(!currentPlayer || getCanMoveValue(currentPlayer))) {
+			this.interruptCurrentPlayerMovement(currentPlayer);
+			return;
+		}
+		const timestamp = Date.now();
+		let frame;
+		let tick;
+		if (this.predictionEnabled && this.prediction) {
+			const meta = this.prediction.recordInput(input, timestamp);
+			frame = meta.frame;
+			tick = meta.tick;
+		} else {
+			frame = ++this.inputFrameCounter;
+			tick = this.getPhysicsTick();
+		}
+		this.inputFrameCounter = frame;
+		this.hooks.callHooks("client-engine-onInput", this, {
+			input,
+			playerId: this.playerId
+		}).subscribe();
+		const bodyReady = this.ensureCurrentPlayerBody();
+		if (currentPlayer && bodyReady) {
+			currentPlayer.changeDirection(input);
+			this.sceneMap.moveBody(currentPlayer, input);
+			if (this.predictionEnabled && this.prediction) {
+				this.pendingPredictionFrames.push(frame);
+				if (this.pendingPredictionFrames.length > 240) this.pendingPredictionFrames = this.pendingPredictionFrames.slice(-240);
+			}
+		}
+		this.emitMovePacket(input, frame, tick, timestamp, true);
+		this.lastInputTime = Date.now();
+	}
+	processAction({ action }) {
+		if (this.stopProcessingInput) return;
+		const currentPlayer = this.sceneMap.getCurrentPlayer();
+		if (!(!currentPlayer || getCanMoveValue(currentPlayer))) return;
+		this.hooks.callHooks("client-engine-onInput", this, {
+			input: "action",
+			playerId: this.playerId
+		}).subscribe();
+		this.webSocket.emit("action", { action });
+	}
+	get PIXI() {
+		return PIXI;
+	}
+	get socket() {
+		return this.webSocket;
+	}
+	get playerId() {
+		return this.playerIdSignal();
+	}
+	get scene() {
+		return this.sceneMap;
+	}
+	getPhysicsTick() {
+		return this.sceneMap?.getTick?.() ?? 0;
+	}
+	ensureCurrentPlayerBody() {
+		const player = this.sceneMap?.getCurrentPlayer();
+		const myId = this.playerIdSignal();
+		if (!player || !myId) return false;
+		if (!player.id) player.id = myId;
+		if (this.sceneMap.getBody(myId)) return true;
+		try {
+			this.sceneMap.loadPhysic();
+		} catch (error) {
+			console.error("[RPGJS] Unable to initialize client physics before input:", error);
+			return false;
+		}
+		return !!this.sceneMap.getBody(myId);
+	}
+	stepClientPhysicsTick() {
+		if (!this.predictionEnabled || !this.sceneMap) return;
+		const now = Date.now();
+		if (this.lastClientPhysicsStepAt === 0) this.lastClientPhysicsStepAt = now;
+		const deltaMs = Math.max(1, Math.min(100, now - this.lastClientPhysicsStepAt));
+		this.lastClientPhysicsStepAt = now;
+		this.sceneMap.stepClientPhysics(deltaMs);
+	}
+	flushPendingPredictedStates() {
+		if (!this.predictionEnabled || !this.prediction || this.pendingPredictionFrames.length === 0) return;
+		const state = this.getLocalPlayerState();
+		while (this.pendingPredictionFrames.length > 0) {
+			const frame = this.pendingPredictionFrames.shift();
+			if (typeof frame === "number") this.prediction.attachPredictedState(frame, state);
+		}
+	}
+	buildPendingMoveTrajectory() {
+		if (!this.predictionEnabled || !this.prediction) return [];
+		const pendingInputs = this.prediction.getPendingInputs();
+		const trajectory = [];
+		for (const entry of pendingInputs) {
+			const state = entry.state;
+			if (!state) continue;
+			if (typeof state.x !== "number" || typeof state.y !== "number") continue;
+			trajectory.push({
+				frame: entry.frame,
+				tick: entry.tick,
+				timestamp: entry.timestamp,
+				input: entry.direction,
+				x: state.x,
+				y: state.y,
+				direction: state.direction ?? entry.direction
+			});
+		}
+		if (trajectory.length > this.MAX_MOVE_TRAJECTORY_POINTS) return trajectory.slice(-this.MAX_MOVE_TRAJECTORY_POINTS);
+		return trajectory;
+	}
+	emitMovePacket(input, frame, tick, timestamp, force = false) {
+		const trajectory = this.buildPendingMoveTrajectory();
+		const latestTrajectoryFrame = trajectory.length > 0 ? trajectory[trajectory.length - 1].frame : frame;
+		if (!force && latestTrajectoryFrame <= this.lastMovePathSentFrame && timestamp - this.lastMovePathSentAt < this.MOVE_PATH_RESEND_INTERVAL_MS) return;
+		this.webSocket.emit("move", {
+			input,
+			timestamp,
+			frame,
+			tick,
+			trajectory
+		});
+		this.lastMovePathSentAt = timestamp;
+		this.lastMovePathSentFrame = Math.max(this.lastMovePathSentFrame, latestTrajectoryFrame, frame);
+	}
+	flushPendingMovePath() {
+		if (!this.predictionEnabled || !this.prediction) return;
+		const player = this.sceneMap?.getCurrentPlayer?.();
+		if (player && !getCanMoveValue(player)) {
+			this.interruptCurrentPlayerMovement(player);
+			return;
+		}
+		const pendingInputs = this.prediction.getPendingInputs();
+		if (pendingInputs.length === 0) return;
+		const latest = pendingInputs[pendingInputs.length - 1];
+		if (!latest) return;
+		const now = Date.now();
+		if (now - this.lastMovePathSentAt < this.MOVE_PATH_RESEND_INTERVAL_MS) return;
+		this.emitMovePacket(latest.direction, latest.frame, latest.tick, now, false);
+	}
+	getLocalPlayerState() {
+		const currentPlayer = this.sceneMap?.getCurrentPlayer();
+		if (!currentPlayer) return {
+			x: 0,
+			y: 0,
+			direction: Direction.Down
+		};
+		const topLeft = this.sceneMap.getBodyPosition(currentPlayer.id, "top-left");
+		return {
+			x: topLeft?.x ?? currentPlayer.x(),
+			y: topLeft?.y ?? currentPlayer.y(),
+			direction: currentPlayer.direction()
+		};
+	}
+	applyAuthoritativeState(state) {
+		const player = this.sceneMap?.getCurrentPlayer();
+		if (!player) return;
+		const hitbox = typeof player.hitbox === "function" ? player.hitbox() : player.hitbox;
+		const width = hitbox?.w ?? 0;
+		const height = hitbox?.h ?? 0;
+		if (!this.sceneMap.updateHitbox(player.id, state.x, state.y, width, height)) this.sceneMap.setBodyPosition(player.id, state.x, state.y, "top-left");
+		player.x.set(Math.round(state.x));
+		player.y.set(Math.round(state.y));
+		if (state.direction) player.changeDirection(state.direction);
+	}
+	initializePredictionController() {
+		if (!this.predictionEnabled) {
+			this.prediction = void 0;
+			this.sceneMap?.configureClientPrediction?.(false);
+			return;
+		}
+		const configuredTtl = this.globalConfig?.prediction?.historyTtlMs;
+		const historyTtlMs = typeof configuredTtl === "number" ? configuredTtl : 1e4;
+		const configuredMaxEntries = this.globalConfig?.prediction?.maxHistoryEntries;
+		const maxHistoryEntries = typeof configuredMaxEntries === "number" ? configuredMaxEntries : Math.max(600, Math.ceil(historyTtlMs / 16) + 120);
+		this.sceneMap?.configureClientPrediction?.(true);
+		this.prediction = new PredictionController({
+			correctionThreshold: this.globalConfig?.prediction?.correctionThreshold ?? this.SERVER_CORRECTION_THRESHOLD,
+			historyTtlMs,
+			maxHistoryEntries,
+			getPhysicsTick: () => this.getPhysicsTick(),
+			getCurrentState: () => this.getLocalPlayerState(),
+			setAuthoritativeState: (state) => this.applyAuthoritativeState(state)
+		});
+	}
+	getCurrentPlayer() {
+		return this.sceneMap.getCurrentPlayer();
+	}
+	emitSceneMapHook(hookName, ...args) {
+		this.hooks.callHooks(`client-sceneMap-${hookName}`, ...args).subscribe();
+	}
+	/**
+	* Setup RxJS observer to wait for all conditions before calling onAfterLoading hook
+	* 
+	* This method uses RxJS `combineLatest` to wait for all conditions to be met,
+	* regardless of the order in which they arrive:
+	* 1. The map loading is completed (loadMapService.load is finished)
+	* 2. We received a player ID (pId)
+	* 3. Players array has at least one element
+	* 4. Events property is present in the sync data
+	* 
+	* Once all conditions are met, it uses `switchMap` to call the onAfterLoading hook once.
+	* 
+	* ## Design
+	* 
+	* Uses BehaviorSubjects to track each condition state, allowing events to arrive
+	* in any order. The `combineLatest` operator waits until all observables emit `true`,
+	* then `take(1)` ensures the hook is called only once, and `switchMap` handles
+	* the hook execution.
+	* 
+	* @example
+	* ```ts
+	* // Called automatically in loadScene to setup the observer
+	* this.setupOnAfterLoadingObserver();
+	* ```
+	*/
+	setupOnAfterLoadingObserver() {
+		this.onAfterLoadingSubscription = combineLatest([
+			this.mapLoadCompleted$.pipe(filter((completed) => completed === true)),
+			this.playerIdReceived$.pipe(filter((received) => received === true)),
+			this.playersReceived$.pipe(filter((received) => received === true)),
+			this.eventsReceived$.pipe(filter((received) => received === true))
+		]).pipe(take(1), switchMap(() => {
+			return this.hooks.callHooks("client-sceneMap-onAfterLoading", this.sceneMap);
+		})).subscribe();
+	}
+	/**
+	* Clear client prediction states for cleanup
+	* 
+	* Removes old prediction states and input history to prevent memory leaks.
+	* Should be called when changing maps or disconnecting.
+	* 
+	* @example
+	* ```ts
+	* // Clear prediction states when changing maps
+	* engine.clearClientPredictionStates();
+	* ```
+	*/
+	clearClientPredictionStates() {
+		this.initializePredictionController();
+		this.frameOffset = 0;
+		this.inputFrameCounter = 0;
+		this.pendingPredictionFrames = [];
+		this.lastClientPhysicsStepAt = 0;
+		this.lastMovePathSentAt = 0;
+		this.lastMovePathSentFrame = 0;
+	}
+	/**
+	* Stop local movement immediately and discard pending predicted movement.
+	*
+	* Use this before a blocking action such as an A-RPG attack, dialog, dash
+	* startup, or any client-side state where already buffered movement inputs
+	* must not be replayed after server reconciliation.
+	*
+	* @param player - Player object to stop. Defaults to the current player.
+	* @returns `true` when a player was found and interrupted.
+	*
+	* @example
+	* ```ts
+	* engine.interruptCurrentPlayerMovement();
+	* ```
+	*/
+	interruptCurrentPlayerMovement(player = this.sceneMap?.getCurrentPlayer?.()) {
+		if (!player) return false;
+		this.sceneMap?.stopMovement?.(player);
+		this.prediction?.clearPendingInputs();
+		this.pendingPredictionFrames = [];
+		this.lastInputTime = 0;
+		this.lastMovePathSentAt = Date.now();
+		this.lastMovePathSentFrame = this.inputFrameCounter;
+		return true;
+	}
+	/**
+	* Trigger a flash animation on a sprite
+	* 
+	* This method allows you to trigger a flash effect on any sprite from client-side code.
+	* The flash can be configured with various options including type (alpha, tint, or both),
+	* duration, cycles, and color.
+	* 
+	* ## Design
+	* 
+	* The flash is applied directly to the sprite object using its flash trigger.
+	* This is useful for client-side visual feedback, UI interactions, or local effects
+	* that don't need to be synchronized with the server.
+	* 
+	* @param spriteId - The ID of the sprite to flash. If not provided, flashes the current player
+	* @param options - Flash configuration options
+	* @param options.type - Type of flash effect: 'alpha' (opacity), 'tint' (color), or 'both' (default: 'alpha')
+	* @param options.duration - Duration of the flash animation in milliseconds (default: 300)
+	* @param options.cycles - Number of flash cycles (flash on/off) (default: 1)
+	* @param options.alpha - Alpha value when flashing, from 0 to 1 (default: 0.3)
+	* @param options.tint - Tint color when flashing as hex value or color name (default: 0xffffff - white)
+	* 
+	* @example
+	* ```ts
+	* // Flash the current player with default settings
+	* engine.flash();
+	* 
+	* // Flash a specific sprite with red tint
+	* engine.flash('sprite-id', { type: 'tint', tint: 0xff0000 });
+	* 
+	* // Flash with both alpha and tint for dramatic effect
+	* engine.flash(undefined, { 
+	*   type: 'both', 
+	*   alpha: 0.5, 
+	*   tint: 0xff0000,
+	*   duration: 200,
+	*   cycles: 2
+	* });
+	* 
+	* // Quick damage flash on current player
+	* engine.flash(undefined, { 
+	*   type: 'tint', 
+	*   tint: 'red', 
+	*   duration: 150,
+	*   cycles: 1
+	* });
+	* ```
+	*/
+	flash(spriteId, options) {
+		const targetId = spriteId || this.playerId;
+		if (!targetId) return;
+		const sprite = this.sceneMap.getObjectById(targetId);
+		if (sprite && typeof sprite.flash === "function") sprite.flash(options);
+	}
+	applyServerAck(ack) {
+		if (this.predictionEnabled && this.prediction) {
+			const result = this.prediction.applyServerAck({
+				frame: ack.frame,
+				serverTick: ack.serverTick,
+				state: typeof ack.x === "number" && typeof ack.y === "number" ? {
+					x: ack.x,
+					y: ack.y,
+					direction: ack.direction
+				} : void 0
+			});
+			if (result.state && result.needsReconciliation) this.reconcilePrediction(result.state, result.pendingInputs);
+			return;
+		}
+		if (typeof ack.x !== "number" || typeof ack.y !== "number") return;
+		const player = this.getCurrentPlayer();
+		const myId = this.playerIdSignal();
+		if (!player || !myId) return;
+		const hitbox = typeof player.hitbox === "function" ? player.hitbox() : player.hitbox;
+		const width = hitbox?.w ?? 0;
+		const height = hitbox?.h ?? 0;
+		if (!this.sceneMap.updateHitbox(myId, ack.x, ack.y, width, height)) this.sceneMap.setBodyPosition(myId, ack.x, ack.y, "top-left");
+		player.x.set(Math.round(ack.x));
+		player.y.set(Math.round(ack.y));
+		if (ack.direction) player.changeDirection(ack.direction);
+	}
+	reconcilePrediction(authoritativeState, pendingInputs) {
+		const player = this.getCurrentPlayer();
+		if (!player) return;
+		if (!getCanMoveValue(player)) {
+			this.interruptCurrentPlayerMovement(player);
+			return;
+		}
+		this.sceneMap.stopMovement(player);
+		this.applyAuthoritativeState(authoritativeState);
+		if (!pendingInputs.length) return;
+		const replayInputs = pendingInputs.slice(-600);
+		for (const entry of replayInputs) {
+			if (!entry?.direction) continue;
+			this.sceneMap.moveBody(player, entry.direction);
+			this.sceneMap.stepPredictionTick();
+			this.prediction?.attachPredictedState(entry.frame, this.getLocalPlayerState());
+		}
+	}
+	/**
+	* Replay unacknowledged inputs from a given frame to resimulate client prediction
+	* after applying server authority at a certain frame.
+	* 
+	* @param startFrame - The last server-acknowledged frame
+	* 
+	* @example
+	* ```ts
+	* // After applying a server correction at frame N
+	* this.replayUnackedInputsFromFrame(N);
+	* ```
+	*/
+	async replayUnackedInputsFromFrame(_startFrame) {}
+	/**
+	* Clear all client resources and reset state
+	* 
+	* This method should be called to clean up all client-side resources when
+	* shutting down or resetting the client engine. It:
+	* - Destroys the PIXI renderer
+	* - Stops all sounds
+	* - Cleans up subscriptions and event listeners
+	* - Resets scene map
+	* - Stops ping/pong interval
+	* - Clears prediction states
+	* 
+	* ## Design
+	* 
+	* This method is used primarily in testing environments to ensure clean
+	* state between tests. In production, the client engine typically persists
+	* for the lifetime of the application.
+	* 
+	* @example
+	* ```ts
+	* // In test cleanup
+	* afterEach(() => {
+	*   clientEngine.clear();
+	* });
+	* ```
+	*/
+	clear() {
+		try {
+			for (const subscription of this.tickSubscriptions) if (subscription && typeof subscription.unsubscribe === "function") subscription.unsubscribe();
+			this.tickSubscriptions = [];
+			if (this.pingInterval) {
+				clearInterval(this.pingInterval);
+				this.pingInterval = null;
+			}
+			if (this.onAfterLoadingSubscription && typeof this.onAfterLoadingSubscription.unsubscribe === "function") {
+				this.onAfterLoadingSubscription.unsubscribe();
+				this.onAfterLoadingSubscription = void 0;
+			}
+			if (this.canvasElement) try {
+				if (typeof this.canvasElement.destroy === "function") this.canvasElement.destroy();
+				this.canvasElement = void 0;
+			} catch (error) {}
+			if (this.sceneMap && typeof this.sceneMap.reset === "function") this.sceneMap.reset(true);
+			this.stopAllSounds();
+			if (this.resizeHandler && typeof window !== "undefined") {
+				window.removeEventListener("resize", this.resizeHandler);
+				this.resizeHandler = void 0;
+			}
+			const rendererStillExists = this.renderer && typeof this.renderer.destroy === "function";
+			if (this.canvasApp && typeof this.canvasApp.destroy === "function") {
+				try {
+					if (this.canvasApp.ticker) {
+						if (typeof this.canvasApp.ticker.stop === "function") this.canvasApp.ticker.stop();
+						if (typeof this.canvasApp.ticker.removeAll === "function") this.canvasApp.ticker.removeAll();
+					}
+					if (this.renderer && this.renderer.ticker) {
+						if (typeof this.renderer.ticker.stop === "function") this.renderer.ticker.stop();
+						if (typeof this.renderer.ticker.removeAll === "function") this.renderer.ticker.removeAll();
+					}
+					if (this.canvasApp.canvas && this.canvasApp.canvas.parentNode) this.canvasApp.canvas.parentNode.removeChild(this.canvasApp.canvas);
+					this.canvasApp.destroy(true);
+				} catch (error) {}
+				this.canvasApp = void 0;
+				this.renderer = null;
+			} else if (rendererStillExists) {
+				try {
+					if (this.renderer.ticker) {
+						if (typeof this.renderer.ticker.stop === "function") this.renderer.ticker.stop();
+						if (typeof this.renderer.ticker.removeAll === "function") this.renderer.ticker.removeAll();
+					}
+					this.renderer.destroy(true);
+				} catch (error) {}
+				this.renderer = null;
+			}
+			if (this.prediction) this.prediction = void 0;
+			this.playerIdSignal.set(null);
+			this.cameraFollowTargetId.set(null);
+			this.spriteComponentsBehind.set([]);
+			this.spriteComponentsInFront.set([]);
+			this.spritesheets.clear();
+			this.sounds.clear();
+			this.componentAnimations = [];
+			this.particleSettings.emitters = [];
+			this.stopProcessingInput = false;
+			this.lastInputTime = 0;
+			this.inputFrameCounter = 0;
+			this.frameOffset = 0;
+			this.rtt = 0;
+			this.lastMovePathSentAt = 0;
+			this.lastMovePathSentFrame = 0;
+			this.mapLoadCompleted$.next(false);
+			this.playerIdReceived$.next(false);
+			this.playersReceived$.next(false);
+			this.eventsReceived$.next(false);
+		} catch (error) {
+			console.warn("Error during client engine cleanup:", error);
+		}
+	}
+};
+//#endregion
+export { RpgClientEngine };
+
+//# sourceMappingURL=RpgClientEngine.js.map