@rpgjs/client 5.0.0-alpha.2 → 5.0.0-alpha.20

package/dist/index2.js

@@ -1,44 +1,103 @@
-import component from './index14.js';
-import { inject } from './index15.js';
-import { signal, bootstrapCanvas } from 'canvasengine';
-import { WebSocketToken } from './index16.js';
+import component from './index19.js';
+import { inject } from './index18.js';
+import { signal, bootstrapCanvas, Howl } from 'canvasengine';
+import { WebSocketToken } from './index20.js';
 import { LoadMapToken } from './index7.js';
-import { ModulesToken } from '@rpgjs/common';
-import { load } from './index17.js';
-import { RpgClientMap } from './index18.js';
+import { RpgSound } from './index17.js';
+import { Direction, PredictionController, ModulesToken } from '@rpgjs/common';
+import { load } from './index21.js';
+import { RpgClientMap } from './index22.js';
 import { RpgGui } from './index9.js';
-import { EffectManager } from './index19.js';
+import { AnimationManager } from './index23.js';
 import { lastValueFrom } from 'rxjs';
 import { GlobalConfigToken } from './index8.js';
+import * as PIXI from 'pixi.js';
+import { PrebuiltComponentAnimations } from './index12.js';
 
 class RpgClientEngine {
   constructor(context) {
     this.context = context;
-    this.sceneMap = new RpgClientMap();
     this.stopProcessingInput = false;
     this.width = signal("100%");
     this.height = signal("100%");
     this.spritesheets = /* @__PURE__ */ new Map();
     this.sounds = /* @__PURE__ */ new Map();
-    this.effects = [];
+    this.componentAnimations = [];
     this.particleSettings = {
       emitters: []
     };
+    this.playerIdSignal = signal(null);
+    this.spriteComponentsBehind = signal([]);
+    this.spriteComponentsInFront = signal([]);
+    this.predictionEnabled = false;
+    this.SERVER_CORRECTION_THRESHOLD = 30;
+    this.inputFrameCounter = 0;
+    this.frameOffset = 0;
+    // Ping/Pong for RTT measurement
+    this.rtt = 0;
+    // Round-trip time in ms
+    this.pingInterval = null;
+    this.PING_INTERVAL_MS = 5e3;
+    // Send ping every 5 seconds
+    this.lastInputTime = 0;
     this.webSocket = inject(context, WebSocketToken);
     this.guiService = inject(context, RpgGui);
     this.loadMapService = inject(context, LoadMapToken);
     this.hooks = inject(context, ModulesToken);
     this.globalConfig = inject(context, GlobalConfigToken);
+    if (!this.globalConfig) {
+      this.globalConfig = {};
+    }
+    if (!this.globalConfig.box) {
+      this.globalConfig.box = {
+        styles: {
+          backgroundColor: "#1a1a2e",
+          backgroundOpacity: 0.9
+        },
+        sounds: {}
+      };
+    }
+    this.addComponentAnimation({
+      id: "animation",
+      component: PrebuiltComponentAnimations.Animation
+    });
+    this.predictionEnabled = this.globalConfig?.prediction?.enabled !== false;
+    this.initializePredictionController();
   }
   async start() {
+    this.sceneMap = new RpgClientMap();
     this.selector = document.body.querySelector("#rpg");
-    await bootstrapCanvas(this.selector, component);
-    await lastValueFrom(this.hooks.callHooks("client-engine-onStart", this));
+    const { app, canvasElement } = await bootstrapCanvas(this.selector, component);
+    this.renderer = app.renderer;
+    this.tick = canvasElement?.propObservables?.context["tick"].observable;
+    this.tick.subscribe(() => {
+      if (Date.now() - this.lastInputTime > 100) {
+        const player = this.getCurrentPlayer();
+        if (!player) return;
+        this.sceneMap.stopMovement(player);
+      }
+    });
     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);
     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));
+    window.addEventListener("resize", () => {
+      this.hooks.callHooks("client-engine-onWindowResize", this).subscribe();
+    });
+    this.tick.subscribe((tick) => {
+      this.hooks.callHooks("client-engine-onStep", this, tick).subscribe();
+      if (tick % 60 === 0) {
+        const now = Date.now();
+        this.prediction?.cleanup(now);
+        this.prediction?.tryApplyPendingSnapshot();
+      }
+    });
     await this.webSocket.connection(() => {
       this.initListeners();
       this.guiService._initialize();
@@ -46,21 +105,122 @@ class RpgClientEngine {
   }
   initListeners() {
     this.webSocket.on("sync", (data) => {
+      if (data.pId) this.playerIdSignal.set(data.pId);
+      this.hooks.callHooks("client-sceneMap-onChanges", this.sceneMap, { partial: data }).subscribe();
       load(this.sceneMap, data, 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.sceneMap.reset();
       this.loadScene(data.mapId);
     });
-    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 === 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("setAnimation", (data) => {
+      const { animationName, nbTimes, object } = data;
       const player = this.sceneMap.getObjectById(object);
-      this.getEffect(id).displayEffect(params, player);
+      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("open", () => {
+      this.hooks.callHooks("client-engine-onConnected", this, this.socket).subscribe();
+    });
+    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) {
+    this.hooks.callHooks("client-sceneMap-onBeforeLoading", this.sceneMap).subscribe();
+    this.clearClientPredictionStates();
     this.webSocket.updateProperties({ room: mapId });
     await this.webSocket.reconnect(() => {
       this.initListeners();
@@ -69,43 +229,534 @@ class RpgClientEngine {
     const res = await this.loadMapService.load(mapId);
     this.sceneMap.data.set(res);
     this.hooks.callHooks("client-sceneMap-onAfterLoading", this.sceneMap).subscribe();
+    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 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;
+      }
+    }
+    return void 0;
+  }
+  /**
+   * 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) {
-    this.sounds.set(id || sound.id, sound);
+    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;
+      }
+    }
+    return void 0;
+  }
+  /**
+   * 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`);
+    }
+  }
   addParticle(particle) {
     this.particleSettings.emitters.push(particle);
     return particle;
   }
-  addEffect(effect) {
-    const instance = new EffectManager();
-    this.effects.push({
-      id: effect.id,
-      component: effect.component,
+  /**
+   * Add a component to render behind sprites
+   * Components added with this method will be displayed with a lower z-index than the sprite
+   * 
+   * @param component - The component to add behind sprites
+   * @returns The added component
+   * 
+   * @example
+   * ```ts
+   * // Add a shadow component behind all sprites
+   * engine.addSpriteComponentBehind(ShadowComponent);
+   * ```
+   */
+  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
+   * 
+   * @param component - The component to add in front of sprites
+   * @returns The added component
+   * 
+   * @example
+   * ```ts
+   * // Add a health bar component in front of all sprites
+   * engine.addSpriteComponentInFront(HealthBarComponent);
+   * ```
+   */
+  addSpriteComponentInFront(component) {
+    this.spriteComponentsInFront.update((components) => [...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) {
+    const instance = new AnimationManager();
+    this.componentAnimations.push({
+      id: componentAnimation.id,
+      component: componentAnimation.component,
       instance,
       current: instance.current
     });
-    return effect;
+    return componentAnimation;
   }
-  getEffect(id) {
-    const effect = this.effects.find((effect2) => effect2.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) {
+    const componentAnimation = this.componentAnimations.find((componentAnimation2) => componentAnimation2.id === id);
+    if (!componentAnimation) {
+      throw new Error(`Component animation with id ${id} not found`);
     }
-    return effect.instance;
+    return componentAnimation.instance;
   }
-  processInput({ input }) {
-    this.webSocket.emit("move", { input });
+  async processInput({ input }) {
+    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.hooks.callHooks("client-engine-onInput", this, { input, playerId: this.playerId }).subscribe();
+    this.webSocket.emit("move", {
+      input,
+      timestamp,
+      frame,
+      tick
+    });
+    const currentPlayer = this.sceneMap.getCurrentPlayer();
+    if (currentPlayer) {
+      this.sceneMap.moveBody(currentPlayer, input);
+    }
+    this.lastInputTime = Date.now();
+    this.playerIdSignal();
   }
   processAction({ action }) {
     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;
+  }
+  getPhysicsTick() {
+    return this.sceneMap?.getTick?.() ?? 0;
+  }
+  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");
+    const x = topLeft?.x ?? currentPlayer.x();
+    const y = topLeft?.y ?? currentPlayer.y();
+    const direction = currentPlayer.direction();
+    return { x, y, 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;
+    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);
+    }
+  }
+  initializePredictionController() {
+    if (!this.predictionEnabled) {
+      this.prediction = void 0;
+      return;
+    }
+    this.prediction = new PredictionController({
+      correctionThreshold: this.globalConfig?.prediction?.correctionThreshold ?? this.SERVER_CORRECTION_THRESHOLD,
+      historyTtlMs: this.globalConfig?.prediction?.historyTtlMs ?? 2e3,
+      getPhysicsTick: () => this.getPhysicsTick(),
+      getCurrentState: () => this.getLocalPlayerState(),
+      setAuthoritativeState: (state) => this.applyAuthoritativeState(state)
+    });
+  }
+  getCurrentPlayer() {
+    return this.sceneMap.getCurrentPlayer();
+  }
+  /**
+   * 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;
+  }
+  applyServerAck(ack) {
+    if (this.predictionEnabled && this.prediction) {
+      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
+      });
+      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);
+    }
+  }
+  /**
+   * 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) {
+  }
 }
 
 export { RpgClientEngine };