@rpgjs/client 5.0.0-alpha.4 → 5.0.0-alpha.40

package/src/RpgClientEngine.ts

@@ -1,96 +1,596 @@
 import Canvas from "./components/scenes/canvas.ce";
-import { Context, inject } from "@signe/di";
-import { signal, bootstrapCanvas } from "canvasengine";
+import { inject } from './core/inject'
+import { signal, bootstrapCanvas, KeyboardControls, Howl, trigger } from "canvasengine";
 import { AbstractWebsocket, WebSocketToken } from "./services/AbstractSocket";
 import { LoadMapService, LoadMapToken } from "./services/loadMap";
-import { Hooks, ModulesToken } from "@rpgjs/common";
+import { RpgSound } from "./Sound";
+import { RpgResource } from "./Resource";
+import { Hooks, ModulesToken, Direction } from "@rpgjs/common";
+
+type DirectionValue = "up" | "down" | "left" | "right";
 import { load } from "@signe/sync";
 import { RpgClientMap } from "./Game/Map"
 import { RpgGui } from "./Gui/Gui";
-import { EffectManager } from "./Game/EffectManager";
-import { lastValueFrom } from "rxjs";
+import { AnimationManager } from "./Game/AnimationManager";
+import { lastValueFrom, Observable, combineLatest, BehaviorSubject, filter, switchMap, take } from "rxjs";
 import { GlobalConfigToken } from "./module";
-import { ClientIo } from "@signe/room";
+import * as PIXI from "pixi.js";
+import { PrebuiltComponentAnimations } from "./components/animations";
+import {
+  PredictionController,
+  type PredictionHistoryEntry,
+  type PredictionState,
+} from "@rpgjs/common";
+import { NotificationManager } from "./Gui/NotificationManager";
+import { SaveClientService } from "./services/save";
+
+interface MovementTrajectoryPoint {
+  frame: number;
+  tick: number;
+  timestamp: number;
+  input: Direction;
+  x: number;
+  y: number;
+  direction?: Direction;
+}
 
 export class RpgClientEngine<T = any> {
   private guiService: RpgGui;
   private webSocket: AbstractWebsocket;
   private loadMapService: LoadMapService;
   private hooks: Hooks;
-  private sceneMap: RpgClientMap = new RpgClientMap();
+  private sceneMap: RpgClientMap
   private selector: HTMLElement;
   public globalConfig: T;
   public sceneComponent: any;
   stopProcessingInput = false;
-
   width = signal("100%");
   height = signal("100%");
   spritesheets: Map<string, any> = new Map();
   sounds: Map<string, any> = new Map();
-  effects: any[] = [];
+  componentAnimations: any[] = [];
+  private spritesheetResolver?: (id: string) => any | Promise<any>;
+  private soundResolver?: (id: string) => any | Promise<any>;
   particleSettings: {
     emitters: any[]
   } = {
-    emitters: []
+      emitters: []
+    }
+  renderer: PIXI.Renderer;
+  tick: Observable<number>;
+  private canvasApp?: any;
+  private canvasElement?: any;
+  playerIdSignal = signal<string | null>(null);
+  spriteComponentsBehind = signal<any[]>([]);
+  spriteComponentsInFront = signal<any[]>([]);
+  /** ID of the sprite that the camera should follow. null means follow the current player */
+  cameraFollowTargetId = signal<string | null>(null);
+  /** Trigger for map shake animation */
+  mapShakeTrigger = trigger();
+
+  controlsReady = signal(undefined); 
+  gamePause = signal(false);
+
+  private predictionEnabled = false;
+  private prediction?: PredictionController<Direction>;
+  private readonly SERVER_CORRECTION_THRESHOLD = 30;
+  private inputFrameCounter = 0;
+  private pendingPredictionFrames: number[] = [];
+  private lastClientPhysicsStepAt = 0;
+  private frameOffset = 0;
+  // Ping/Pong for RTT measurement
+  private rtt: number = 0; // Round-trip time in ms
+  private pingInterval: any = null;
+  private readonly PING_INTERVAL_MS = 5000; // Send ping every 5 seconds
+  private lastInputTime = 0;
+  private readonly MOVE_PATH_RESEND_INTERVAL_MS = 120;
+  private readonly MAX_MOVE_TRAJECTORY_POINTS = 240;
+  private lastMovePathSentAt = 0;
+  private lastMovePathSentFrame = 0;
+  // Track map loading state for onAfterLoading hook using RxJS
+  private mapLoadCompleted$ = new BehaviorSubject<boolean>(false);
+  private playerIdReceived$ = new BehaviorSubject<boolean>(false);
+  private playersReceived$ = new BehaviorSubject<boolean>(false);
+  private eventsReceived$ = new BehaviorSubject<boolean>(false);
+  private onAfterLoadingSubscription?: any;
+  private sceneResetQueued = false;
+  
+  // Store subscriptions and event listeners for cleanup
+  private tickSubscriptions: any[] = [];
+  private resizeHandler?: () => void;
+  private notificationManager: NotificationManager = new NotificationManager();
+
+  constructor(public context) {
+    this.webSocket = inject(WebSocketToken);
+    this.guiService = inject(RpgGui);
+    this.loadMapService = inject(LoadMapToken);
+    this.hooks = inject<Hooks>(ModulesToken);
+    this.globalConfig = inject(GlobalConfigToken)
+
+    if (!this.globalConfig) {
+      this.globalConfig = {} as T
+    }
+    if (!(this.globalConfig as any).box) {
+      (this.globalConfig as any).box = {
+        styles: {
+          backgroundColor: "#1a1a2e",
+          backgroundOpacity: 0.9
+        },
+        sounds: {}
+      }
+    }
+
+    this.addComponentAnimation({
+      id: "animation",
+      component: PrebuiltComponentAnimations.Animation
+    })
+
+    this.predictionEnabled = (this.globalConfig as any)?.prediction?.enabled !== false;
+    this.initializePredictionController();
   }
 
-  constructor(public context: Context) {
-    this.webSocket = inject(context, WebSocketToken);
-    this.guiService = inject(context, RpgGui);
-    this.loadMapService = inject(context, LoadMapToken);
-    this.hooks = inject<Hooks>(context, ModulesToken);
-    this.globalConfig = inject(context, GlobalConfigToken)
+  /**
+   * 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: any) {
+    const currentValues = this.context.values['inject:' + 'KeyboardControls']
+    this.context.values['inject:' + 'KeyboardControls'] = {
+      ...currentValues,
+      values: new Map([['__default__', controlInstance]])
+    }
+    this.controlsReady.set(undefined);
   }
 
   async start() {
+    this.sceneMap = new RpgClientMap()
+    this.sceneMap.configureClientPrediction(this.predictionEnabled);
+    this.sceneMap.loadPhysic();
     this.selector = document.body.querySelector("#rpg") as HTMLElement;
 
-    await bootstrapCanvas(this.selector, Canvas);
+    const bootstrapOptions = (this.globalConfig as any)?.bootstrapCanvasOptions;
+    const { app, canvasElement } = await bootstrapCanvas(
+      this.selector,
+      Canvas,
+      bootstrapOptions
+    );
+    this.canvasApp = app;
+    this.canvasElement = canvasElement;
+    this.renderer = app.renderer as PIXI.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 as any).stopMovement(player);
+      }
+    });
+    this.tickSubscriptions.push(inputCheckSubscription);
 
-    await lastValueFrom(this.hooks.callHooks("client-engine-onStart", this));
 
     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-effects-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));
+
+    // wondow is resize
+    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();
+
+      // Clean up old prediction states and input history every 60 ticks (approximately every second at 60fps)
+      if (tick % 60 === 0) {
+        const now = Date.now();
+        this.prediction?.cleanup(now);
+        this.prediction?.tryApplyPendingSnapshot();
+      }
+    });
+    this.tickSubscriptions.push(tickSubscription);
 
-  
     await this.webSocket.connection(() => {
+      const saveClient = inject(SaveClientService);
+      saveClient.initialize(this.webSocket);
       this.initListeners()
       this.guiService._initialize()
+      this.startPingPong();
     });
   }
 
+  private prepareSyncPayload(data: any): any {
+    const payload = { ...(data ?? {}) };
+    delete payload.ack;
+    delete payload.timestamp;
+
+    const myId = this.playerIdSignal();
+    const players = payload.players;
+    const shouldMaskLocalPosition =
+      this.predictionEnabled && !!this.prediction?.hasPendingInputs();
+    if (shouldMaskLocalPosition && 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;
+  }
+
+  private normalizeAckWithSyncState(
+    ack: { frame: number; serverTick?: number; x?: number; y?: number; direction?: Direction },
+    syncData: any,
+  ): { frame: number; serverTick?: number; x?: number; y?: number; direction?: Direction } {
+    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,
+    };
+  }
+
   private initListeners() {
     this.webSocket.on("sync", (data) => {
-      load(this.sceneMap, data, true);
+      if (data.pId) {
+        this.playerIdSignal.set(data.pId);
+        // Signal that player ID was received
+        this.playerIdReceived$.next(true);
+      }
+
+      if (this.sceneResetQueued) {
+        this.sceneMap.reset();
+        this.sceneMap.loadPhysic();
+        this.sceneResetQueued = false;
+      }
+
+      // Apply client-side prediction filtering and server reconciliation
+      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)
+          : undefined;
+      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]
+        }
+      }
+      
+      // Check if players and events are present in sync data
+      const players = payload.players || this.sceneMap.players();
+      if (players && Object.keys(players).length > 0) {
+        this.playersReceived$.next(true);
+      }
+      
+      const events = payload.events || this.sceneMap.events();
+      if (events !== undefined) {
+        this.eventsReceived$.next(true);
+      }
+    });
+
+    // Handle pong responses for RTT measurement
+    this.webSocket.on("pong", (data: { serverTick: number; clientFrame: number; clientTime: number }) => {
+      const now = Date.now();
+      this.rtt = now - data.clientTime;
+
+      // Calculate frame offset: how many ticks ahead the server is compared to our frame counter
+      // This helps us estimate which server tick corresponds to each client input frame
+      const estimatedTicksInFlight = Math.floor(this.rtt / 2 / (1000 / 60)); // Estimate ticks during half RTT
+      const estimatedServerTickNow = data.serverTick + estimatedTicksInFlight;
+
+      // Update frame offset (only if we have inputs to calibrate with)
+      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.loadScene(data.mapId);
+      this.sceneResetQueued = true;
+      // Reset camera follow to default (follow current player) when changing maps
+      this.cameraFollowTargetId.set(null);
+      const transferToken = typeof data?.transferToken === "string" ? data.transferToken : undefined;
+      this.loadScene(data.mapId, transferToken);
     });
 
-    this.webSocket.on("showEffect", (data) => {
-      const { params, object, id } = data;
-      if (!object) {
-        throw new Error("Object not found");
+    this.webSocket.on("showComponentAnimation", (data) => {
+      const { params, object, position, id } = data;
+      if (!object && position === undefined) {
+        throw new Error("Please provide an object or x and y coordinates");
       }
-      const player = this.sceneMap.getObjectById(object);
-      this.getEffect(id).displayEffect(params, player)
+      const player = object ? this.sceneMap.getObjectById(object) : undefined;
+      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 } = data;
+       const player = this.sceneMap.getObjectById(object);
+       if (graphic !== undefined) {
+         player.setAnimation(animationName, graphic, nbTimes);
+       } else {
+         player.setAnimation(animationName, nbTimes);
+       }
+     })
+
+    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) : undefined;
+      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 as any).start({
+        intensity,
+        duration,
+        frequency,
+        direction
+      });
+    });
+
+    this.webSocket.on("weatherState", (data) => {
+      const raw = (data && typeof data === "object" && "value" in data)
+        ? (data as any).value
+        : data;
+
+      if (raw === null) {
+        this.sceneMap.weatherState.set(null);
+        return;
+      }
+
+      const validEffects = ["rain", "snow", "fog", "cloud"];
+      if (!raw || !validEffects.includes((raw as any).effect)) {
+        return;
+      }
+
+      this.sceneMap.weatherState.set({
+        effect: (raw as any).effect,
+        preset: (raw as any).preset,
+        params: (raw as any).params,
+        transitionMs: (raw as any).transitionMs,
+        durationMs: (raw as any).durationMs,
+        startedAt: (raw as any).startedAt,
+        seed: (raw as any).seed,
+      });
+    });
+
+    this.webSocket.on('open', () => {
+      this.hooks.callHooks("client-engine-onConnected", this, this.socket).subscribe();
+      // Start ping/pong for synchronization
+      this.startPingPong();
+    })
+
+    this.webSocket.on('close', () => {
+      this.hooks.callHooks("client-engine-onDisconnected", this, this.socket).subscribe();
+      // Stop ping/pong when disconnected
+      this.stopPingPong();
+    })
+
+    this.webSocket.on('error', (error) => {
+      this.hooks.callHooks("client-engine-onConnectError", this, error, this.socket).subscribe();
+    })
   }
-  
-  private async loadScene(mapId: string) {
-    this.webSocket.updateProperties({ room: mapId })
+
+  /**
+   * 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();
+   * ```
+   */
+  private startPingPong(): void {
+    // Stop existing interval if any
+    this.stopPingPong();
+
+    // Send initial ping immediately
+    this.sendPing();
+
+    // Set up periodic pings
+    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();
+   * ```
+   */
+  private stopPingPong(): void {
+    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();
+   * ```
+   */
+  private sendPing(): void {
+    const clientTime = Date.now();
+    const clientFrame = this.getPhysicsTick();
+
+    this.webSocket.emit('ping', {
+      clientTime,
+      clientFrame
+    });
+  }
+
+  private async loadScene(mapId: string, transferToken?: string) {
+    await lastValueFrom(this.hooks.callHooks("client-sceneMap-onBeforeLoading", this.sceneMap));
+
+    // Clear client prediction states when changing maps
+    this.clearClientPredictionStates();
+
+    // Reset all conditions for new map loading
+    this.mapLoadCompleted$.next(false);
+    this.playerIdReceived$.next(false);
+    this.playersReceived$.next(false);
+    this.eventsReceived$.next(false);
+
+    // Unsubscribe previous subscription if exists
+    if (this.onAfterLoadingSubscription) {
+      this.onAfterLoadingSubscription.unsubscribe();
+    }
+
+    // Setup RxJS observable to wait for all conditions
+    this.setupOnAfterLoadingObserver();
+
+    this.webSocket.updateProperties({
+      room: mapId,
+      query: transferToken ? { transferToken } : undefined,
+    })
     await this.webSocket.reconnect(() => {
+      const saveClient = inject(SaveClientService);
+      saveClient.initialize(this.webSocket);
       this.initListeners()
       this.guiService._initialize()
     })
     const res = await this.loadMapService.load(mapId)
     this.sceneMap.data.set(res)
-    this.hooks.callHooks("client-sceneMap-onAfterLoading", this.sceneMap).subscribe();
-    //this.sceneMap.loadPhysic()
+    
+    // Check if playerId is already present
+    if (this.playerIdSignal()) {
+      this.playerIdReceived$.next(true);
+    }
+    
+    // Check if players and events are already present in sceneMap
+    const players = this.sceneMap.players();
+    if (players && Object.keys(players).length > 0) {
+      this.playersReceived$.next(true);
+    }
+    
+    const events = this.sceneMap.events();
+    if (events !== undefined) {
+      this.eventsReceived$.next(true);
+    }
+    
+    // Signal that map loading is completed (this should be last to ensure other checks are done)
+    this.mapLoadCompleted$.next(true);
+    this.sceneMap.configureClientPrediction(this.predictionEnabled);
+    this.sceneMap.loadPhysic()
   }
 
   addSpriteSheet<T = any>(spritesheetClass: any, id?: string): any {
@@ -98,44 +598,1201 @@ export class RpgClientEngine<T = any> {
     return spritesheetClass as any;
   }
 
-  addSound(sound: any, id?: string) {
-    this.sounds.set(id || sound.id, sound);
+  /**
+   * 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: (id: string) => any | Promise<any>): void {
+    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 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: string): any | Promise<any> {
+    // Check cache first
+    if (this.spritesheets.has(id)) {
+      return this.spritesheets.get(id);
+    }
+
+    // If not in cache and resolver exists, use it
+    if (this.spritesheetResolver) {
+      const result = this.spritesheetResolver(id);
+
+      // Check if result is a Promise
+      if (result instanceof Promise) {
+        return result.then((spritesheet) => {
+          if (spritesheet) {
+            // Cache the resolved spritesheet
+            this.spritesheets.set(id, spritesheet);
+          }
+          return spritesheet;
+        });
+      } else {
+        // Synchronous result
+        if (result) {
+          // Cache the resolved spritesheet
+          this.spritesheets.set(id, result);
+        }
+        return result;
+      }
+    }
+
+    // No resolver and not in cache
+    return undefined;
+  }
+
+  /**
+   * 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: any, id?: string): any {
+    const soundId = id || sound.id;
+    
+    if (!soundId) {
+      console.warn('Sound added without an ID. It will not be retrievable.');
+      return sound;
+    }
+
+    // If sound has a src property, create a Howler instance
+    if (sound.src && typeof sound.src === 'string') {
+      const howlOptions: any = {
+        src: [sound.src],
+        loop: sound.loop || false,
+        volume: sound.volume !== undefined ? sound.volume : 1.0,
+      };
+
+      const howl = new (Howl as any).Howl(howlOptions);
+      this.sounds.set(soundId, howl);
+      return howl;
+    }
+
+    // If sound already has a play method (Howler instance or custom), use it directly
+    if (sound && typeof sound.play === 'function') {
+      this.sounds.set(soundId, sound);
+      return sound;
+    }
+
+    // Otherwise, store as-is
+    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: (id: string) => any | Promise<any>): void {
+    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: string): any | Promise<any> {
+    // Check cache first
+    if (this.sounds.has(id)) {
+      return this.sounds.get(id);
+    }
+
+    // If not in cache and resolver exists, use it
+    if (this.soundResolver) {
+      const result = this.soundResolver(id);
+
+      // Check if result is a Promise
+      if (result instanceof Promise) {
+        return result.then((sound) => {
+          if (sound) {
+            // Cache the resolved sound
+            this.sounds.set(id, sound);
+          }
+          return sound;
+        });
+      } else {
+        // Synchronous result
+        if (result) {
+          // Cache the resolved sound
+          this.sounds.set(id, result);
+        }
+        return result;
+      }
+    }
+
+    // No resolver and not in cache
+    return undefined;
+  }
+
+  /**
+   * 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: string, options?: { volume?: number; loop?: boolean }): Promise<void> {
+    const sound = await this.getSound(soundId);
+    if (sound && sound.play) {
+      // Sound is already a Howler instance or has a play method
+      const howlSoundId = sound._sounds?.[0]?._id;
+      
+      // Apply volume if provided
+      if (options?.volume !== undefined) {
+        if (howlSoundId !== undefined) {
+          sound.volume(Math.max(0, Math.min(1, options.volume)), howlSoundId);
+        } else {
+          sound.volume(Math.max(0, Math.min(1, options.volume)));
+        }
+      }
+      
+      // Apply loop if provided
+      if (options?.loop !== undefined) {
+        if (howlSoundId !== undefined) {
+          sound.loop(options.loop, howlSoundId);
+        } else {
+          sound.loop(options.loop);
+        }
+      }
+      
+      if (howlSoundId !== undefined) {
+        sound.play(howlSoundId);
+      } else {
+        sound.play();
+      }
+    } else if (sound && sound.src) {
+      // If sound is just a source URL, create a Howler instance and cache it
+      const howlOptions: any = {
+        src: [sound.src],
+        loop: options?.loop !== undefined ? options.loop : (sound.loop || false),
+        volume: options?.volume !== undefined ? Math.max(0, Math.min(1, options.volume)) : (sound.volume !== undefined ? sound.volume : 1.0),
+      };
+
+      const howl = new (Howl as any).Howl(howlOptions);
+      
+      // Cache the Howler instance for future use
+      this.sounds.set(soundId, howl);
+      
+      // Play the sound
+      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: string): void {
+    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(): void {
+    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: string | null,
+    smoothMove?: boolean | { time?: number; ease?: string }
+  ): void {
+    // Store smoothMove options for potential future use with viewport animation
+    // For now, we just set the target ID and let CanvasEngine handle the viewport follow
+    // The smoothMove options could be used to configure viewport animation if CanvasEngine supports it
+    this.cameraFollowTargetId.set(targetId);
+    
+    // If smoothMove is an object, we could store it for viewport configuration
+    // This would require integration with CanvasEngine's viewport animation system
+    if (typeof smoothMove === "object" && smoothMove !== null) {
+      // Future: Apply smoothMove.time and smoothMove.ease to viewport animation
+      // For now, CanvasEngine handles viewport following automatically
+    }
+  }
+
   addParticle(particle: any) {
     this.particleSettings.emitters.push(particle)
     return particle;
   }
 
-  addEffect(effect: {
+  /**
+   * 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: any) {
+    this.spriteComponentsBehind.update((components: any[]) => [...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: any | { component: any, props: (object: any) => any, dependencies?: (object: any) => any[] }) {
+    this.spriteComponentsInFront.update((components: any[]) => [...components, component])
+    return component
+  }
+
+  /**
+   * 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: {
     component: any,
     id: string
   }) {
-    const instance = new EffectManager()
-    this.effects.push({
-      id: effect.id,
-      component: effect.component,
+    const instance = new AnimationManager()
+    this.componentAnimations.push({
+      id: componentAnimation.id,
+      component: componentAnimation.component,
       instance: instance,
       current: instance.current
     })
-    return effect;
+    return componentAnimation;
   }
 
-  getEffect(id: string): EffectManager {
-    const effect = this.effects.find((effect) => effect.id === id)
-    if (!effect) {
-      throw new Error(`Effect with id ${id} not found`)
+  /**
+   * 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: string): AnimationManager {
+    const componentAnimation = this.componentAnimations.find((componentAnimation) => componentAnimation.id === id)
+    if (!componentAnimation) {
+      throw new Error(`Component animation with id ${id} not found`)
     }
-    return effect.instance
+    return componentAnimation.instance
   }
 
-  processInput({ input }: { input: number }) {
-    this.webSocket.emit('move', { input })
+  /**
+   * 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')
+   * });
+   * ```
+   */
+  startTransition(id: string, props: any = {}) {
+    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.`);
+    }
+    this.guiService.display(id, props);
+  }
+
+  async processInput({ input }: { input: Direction }) {
+    const timestamp = Date.now();
+    let frame: number;
+    let tick: number;
+    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 currentPlayer = this.sceneMap.getCurrentPlayer();
+    const bodyReady = this.ensureCurrentPlayerBody();
+    if (currentPlayer && bodyReady) {
+      currentPlayer.changeDirection(input);
+      (this.sceneMap as any).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 }: { action: number }) {
     if (this.stopProcessingInput) 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
+  }
+
+  private getPhysicsTick(): number {
+    return this.sceneMap?.getTick?.() ?? 0;
+  }
+
+  private ensureCurrentPlayerBody(): boolean {
+    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);
+  }
+
+  private stepClientPhysicsTick(): void {
+    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);
+  }
+
+  private flushPendingPredictedStates(): void {
+    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);
+      }
+    }
+  }
+
+  private buildPendingMoveTrajectory(): MovementTrajectoryPoint[] {
+    if (!this.predictionEnabled || !this.prediction) {
+      return [];
+    }
+    const pendingInputs = this.prediction.getPendingInputs();
+    const trajectory: MovementTrajectoryPoint[] = [];
+    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;
+  }
+
+  private emitMovePacket(
+    input: Direction,
+    frame: number,
+    tick: number,
+    timestamp: number,
+    force = false,
+  ): void {
+    const trajectory = this.buildPendingMoveTrajectory();
+    const latestTrajectoryFrame =
+      trajectory.length > 0 ? trajectory[trajectory.length - 1].frame : frame;
+    const shouldThrottle =
+      !force &&
+      latestTrajectoryFrame <= this.lastMovePathSentFrame &&
+      timestamp - this.lastMovePathSentAt < this.MOVE_PATH_RESEND_INTERVAL_MS;
+    if (shouldThrottle) {
+      return;
+    }
+
+    this.webSocket.emit("move", {
+      input,
+      timestamp,
+      frame,
+      tick,
+      trajectory,
+    });
+    this.lastMovePathSentAt = timestamp;
+    this.lastMovePathSentFrame = Math.max(this.lastMovePathSentFrame, latestTrajectoryFrame, frame);
+  }
+
+  private flushPendingMovePath(): void {
+    if (!this.predictionEnabled || !this.prediction) {
+      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);
+  }
+
+  private getLocalPlayerState(): PredictionState<Direction> {
+    const currentPlayer = this.sceneMap?.getCurrentPlayer();
+    if (!currentPlayer) {
+      return { x: 0, y: 0, direction: Direction.Down };
+    }
+    const topLeft = this.sceneMap.getBodyPosition(currentPlayer.id, "top-left");
+    const x = topLeft?.x ?? currentPlayer.x();
+    const y = topLeft?.y ?? currentPlayer.y();
+    const direction = currentPlayer.direction();
+    return { x, y, direction };
+  }
+
+  private applyAuthoritativeState(state: PredictionState<Direction>): void {
+    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;
+    const updated = this.sceneMap.updateHitbox(player.id, state.x, state.y, width, height);
+    if (!updated) {
+      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);
+    }
+  }
+
+  private initializePredictionController(): void {
+    if (!this.predictionEnabled) {
+      this.prediction = undefined;
+      this.sceneMap?.configureClientPrediction?.(false);
+      return;
+    }
+    const configuredTtl = (this.globalConfig as any)?.prediction?.historyTtlMs;
+    const historyTtlMs = typeof configuredTtl === "number" ? configuredTtl : 10000;
+    const configuredMaxEntries = (this.globalConfig as any)?.prediction?.maxHistoryEntries;
+    const maxHistoryEntries =
+      typeof configuredMaxEntries === "number"
+        ? configuredMaxEntries
+        : Math.max(600, Math.ceil(historyTtlMs / 16) + 120);
+    this.sceneMap?.configureClientPrediction?.(true);
+    this.prediction = new PredictionController<Direction>({
+      correctionThreshold: (this.globalConfig as any)?.prediction?.correctionThreshold ?? this.SERVER_CORRECTION_THRESHOLD,
+      historyTtlMs,
+      maxHistoryEntries,
+      getPhysicsTick: () => this.getPhysicsTick(),
+      getCurrentState: () => this.getLocalPlayerState(),
+      setAuthoritativeState: (state) => this.applyAuthoritativeState(state),
+    });
+  }
+
+  getCurrentPlayer() {
+    return this.sceneMap.getCurrentPlayer()
+  }
+
+  /**
+   * 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();
+   * ```
+   */
+  private setupOnAfterLoadingObserver(): void {
+    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), // Only execute once when all conditions are met
+      switchMap(() => {
+        // Call the hook and return the observable
+        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;
+  }
+
+  /**
+   * 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?: string,
+    options?: {
+      type?: 'alpha' | 'tint' | 'both';
+      duration?: number;
+      cycles?: number;
+      alpha?: number;
+      tint?: number | string;
+    }
+  ): void {
+    const targetId = spriteId || this.playerId;
+    if (!targetId) return;
+
+    const sprite = this.sceneMap.getObjectById(targetId);
+    if (sprite && typeof sprite.flash === 'function') {
+      sprite.flash(options);
+    }
+  }
+
+  private applyServerAck(ack: { frame: number; serverTick?: number; x?: number; y?: number; direction?: Direction }) {
+    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 }
+            : undefined,
+      });
+      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;
+    const updated = this.sceneMap.updateHitbox(myId, ack.x, ack.y, width, height);
+    if (!updated) {
+      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);
+    }
+  }
+
+  private reconcilePrediction(
+    authoritativeState: PredictionState<Direction>,
+    pendingInputs: PredictionHistoryEntry<Direction>[],
+  ): void {
+    const player = this.getCurrentPlayer();
+    if (!player) {
+      return;
+    }
+
+    (this.sceneMap as any).stopMovement(player);
+    this.applyAuthoritativeState(authoritativeState);
+
+    if (!pendingInputs.length) {
+      return;
+    }
+
+    // Keep replay bounded while still tolerating high-latency links.
+    const replayInputs = pendingInputs.slice(-600);
+    for (const entry of replayInputs) {
+      if (!entry?.direction) continue;
+      (this.sceneMap as any).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);
+   * ```
+   */
+  private async replayUnackedInputsFromFrame(_startFrame: number): Promise<void> {
+    // Prediction controller handles replay internally. Kept for backwards compatibility.
+  }
+
+  /**
+   * 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(): void {
+    try {
+      // First, unsubscribe from all tick subscriptions to stop rendering attempts
+      for (const subscription of this.tickSubscriptions) {
+        if (subscription && typeof subscription.unsubscribe === 'function') {
+          subscription.unsubscribe();
+        }
+      }
+      this.tickSubscriptions = [];
+
+      // Stop ping/pong interval
+      if (this.pingInterval) {
+        clearInterval(this.pingInterval);
+        this.pingInterval = null;
+      }
+
+      // Clean up onAfterLoading subscription
+      if (this.onAfterLoadingSubscription && typeof this.onAfterLoadingSubscription.unsubscribe === 'function') {
+        this.onAfterLoadingSubscription.unsubscribe();
+        this.onAfterLoadingSubscription = undefined;
+      }
+
+      // Clean up canvasElement (CanvasEngine) BEFORE destroying PIXI app
+      // This prevents CanvasEngine from trying to render after PIXI is destroyed
+      // CanvasEngine manages its own render loop which could try to access PIXI after destruction
+      if (this.canvasElement) {
+        try {
+          // Try to stop or cleanup canvasElement if it has cleanup methods
+          if (typeof (this.canvasElement as any).destroy === 'function') {
+            (this.canvasElement as any).destroy();
+          }
+          // Clear the reference
+          this.canvasElement = undefined;
+        } catch (error) {
+          // Ignore errors during canvasElement cleanup
+        }
+      }
+
+      // Reset scene map if it exists (this should stop any ongoing animations/renders)
+      if (this.sceneMap && typeof (this.sceneMap as any).reset === 'function') {
+        (this.sceneMap as any).reset(true);
+      }
+
+      // Stop all sounds
+      this.stopAllSounds();
+
+      // Remove resize event listener
+      if (this.resizeHandler && typeof window !== 'undefined') {
+        window.removeEventListener('resize', this.resizeHandler);
+        this.resizeHandler = undefined;
+      }
+
+      // Destroy PIXI app and renderer if they exist
+      // Destroy the app first, which will destroy the renderer
+      // Store renderer reference before destroying app (since app.destroy() will destroy the renderer)
+      const rendererStillExists = this.renderer && typeof this.renderer.destroy === 'function';
+      
+      if (this.canvasApp && typeof this.canvasApp.destroy === 'function') {
+        try {
+          // Stop the ticker first to prevent any render calls during destruction
+          if (this.canvasApp.ticker) {
+            if (typeof this.canvasApp.ticker.stop === 'function') {
+              this.canvasApp.ticker.stop();
+            }
+            // Also remove all listeners from ticker to prevent callbacks
+            if (typeof this.canvasApp.ticker.removeAll === 'function') {
+              this.canvasApp.ticker.removeAll();
+            }
+          }
+          
+          // Stop the renderer's ticker if it exists separately
+          if (this.renderer && (this.renderer as any).ticker) {
+            if (typeof (this.renderer as any).ticker.stop === 'function') {
+              (this.renderer as any).ticker.stop();
+            }
+            if (typeof (this.renderer as any).ticker.removeAll === 'function') {
+              (this.renderer as any).ticker.removeAll();
+            }
+          }
+          
+          // Remove the canvas from DOM before destroying to prevent render attempts
+          if (this.canvasApp.canvas && this.canvasApp.canvas.parentNode) {
+            this.canvasApp.canvas.parentNode.removeChild(this.canvasApp.canvas);
+          }
+          
+          // Destroy with minimal options to avoid issues
+          // Don't pass options that might trigger additional cleanup that could fail
+          this.canvasApp.destroy(true);
+        } catch (error) {
+          // Ignore errors during destruction
+        }
+        this.canvasApp = undefined;
+        // canvasApp.destroy() already destroyed the renderer, so just null it
+        this.renderer = null as any;
+      } else if (rendererStillExists) {
+        // Fallback: destroy renderer directly only if app doesn't exist or wasn't destroyed
+        try {
+          // Stop the renderer's ticker if it has one
+          if ((this.renderer as any).ticker) {
+            if (typeof (this.renderer as any).ticker.stop === 'function') {
+              (this.renderer as any).ticker.stop();
+            }
+            if (typeof (this.renderer as any).ticker.removeAll === 'function') {
+              (this.renderer as any).ticker.removeAll();
+            }
+          }
+          
+          this.renderer.destroy(true);
+        } catch (error) {
+          // Ignore errors during destruction
+        }
+        this.renderer = null as any;
+      }
+
+      // Clean up prediction controller
+      if (this.prediction) {
+        // Prediction controller cleanup is handled internally when destroyed
+        this.prediction = undefined;
+      }
+
+      // Reset signals
+      this.playerIdSignal.set(null);
+      this.cameraFollowTargetId.set(null);
+      this.spriteComponentsBehind.set([]);
+      this.spriteComponentsInFront.set([]);
+      
+      // Clear maps and arrays
+      this.spritesheets.clear();
+      this.sounds.clear();
+      this.componentAnimations = [];
+      this.particleSettings.emitters = [];
+
+      // Reset state
+      this.stopProcessingInput = false;
+      this.lastInputTime = 0;
+      this.inputFrameCounter = 0;
+      this.frameOffset = 0;
+      this.rtt = 0;
+      this.lastMovePathSentAt = 0;
+      this.lastMovePathSentFrame = 0;
+
+      // Reset behavior subjects
+      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);
+    }
+  }
 }