@rpgjs/client 5.0.0-alpha.14 → 5.0.0-alpha.16

package/src/RpgClientEngine.ts

@@ -3,7 +3,9 @@ import { Context, inject } from "@signe/di";
 import { signal, bootstrapCanvas } from "canvasengine";
 import { AbstractWebsocket, WebSocketToken } from "./services/AbstractSocket";
 import { LoadMapService, LoadMapToken } from "./services/loadMap";
-import { Hooks, ModulesToken } from "@rpgjs/common";
+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";
@@ -12,6 +14,10 @@ import { lastValueFrom, Observable } from "rxjs";
 import { GlobalConfigToken } from "./module";
 import * as PIXI from "pixi.js";
 import { PrebuiltComponentAnimations } from "./components/animations";
+import {
+  PredictionController,
+  type PredictionState,
+} from "@rpgjs/common";
 
 export class RpgClientEngine<T = any> {
   private guiService: RpgGui;
@@ -28,17 +34,29 @@ export class RpgClientEngine<T = any> {
   spritesheets: Map<string, any> = new Map();
   sounds: Map<string, any> = new Map();
   componentAnimations: any[] = [];
+  private spritesheetResolver?: (id: string) => any | Promise<any>;
   particleSettings: {
     emitters: any[]
   } = {
-    emitters: []
-  }
+      emitters: []
+    }
   renderer: PIXI.Renderer;
   tick: Observable<number>;
   playerIdSignal = signal<string | null>(null);
   spriteComponentsBehind = signal<any[]>([]);
   spriteComponentsInFront = signal<any[]>([]);
 
+  private predictionEnabled = false;
+  private prediction?: PredictionController<Direction>;
+  private readonly SERVER_CORRECTION_THRESHOLD = 30;
+  private inputFrameCounter = 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;
+
   constructor(public context: Context) {
     this.webSocket = inject(context, WebSocketToken);
     this.guiService = inject(context, RpgGui);
@@ -47,10 +65,10 @@ export class RpgClientEngine<T = any> {
     this.globalConfig = inject(context, GlobalConfigToken)
 
     if (!this.globalConfig) {
-      this.globalConfig = {}
+      this.globalConfig = {} as T
     }
-    if (!this.globalConfig.box) {
-      this.globalConfig.box = {
+    if (!(this.globalConfig as any).box) {
+      (this.globalConfig as any).box = {
         styles: {
           backgroundColor: "#1a1a2e",
           backgroundOpacity: 0.9
@@ -63,6 +81,9 @@ export class RpgClientEngine<T = any> {
       id: "animation",
       component: PrebuiltComponentAnimations.Animation
     })
+
+    this.predictionEnabled = (this.globalConfig as any)?.prediction?.enabled !== false;
+    this.initializePredictionController();
   }
 
   async start() {
@@ -73,8 +94,17 @@ export class RpgClientEngine<T = any> {
     this.renderer = app.renderer as PIXI.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 as any).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-gui-load", this).subscribe();
     this.hooks.callHooks("client-particles-load", this).subscribe();
@@ -90,6 +120,13 @@ export class RpgClientEngine<T = any> {
 
     this.tick.subscribe((tick) => {
       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();
+      }
     })
 
     await this.webSocket.connection(() => {
@@ -100,11 +137,33 @@ export class RpgClientEngine<T = any> {
 
   private initListeners() {
     this.webSocket.on("sync", (data) => {
+
       if (data.pId) this.playerIdSignal.set(data.pId)
+      // Apply client-side prediction filtering and server reconciliation
+
       this.hooks.callHooks("client-sceneMap-onChanges", this.sceneMap, { partial: data }).subscribe();
+
       load(this.sceneMap, data, 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.sceneMap.reset()
       this.loadScene(data.mapId);
@@ -127,19 +186,98 @@ export class RpgClientEngine<T = any> {
 
     this.webSocket.on('open', () => {
       this.hooks.callHooks("client-engine-onConnected", this, this.socket).subscribe();
+      // Start ping/pong for synchronization
     })
 
     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();
     })
   }
-  
+
+  /**
+   * 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) {
     this.hooks.callHooks("client-sceneMap-onBeforeLoading", this.sceneMap).subscribe();
+
+    // Clear client prediction states when changing maps
+    this.clearClientPredictionStates();
+
     this.webSocket.updateProperties({ room: mapId })
     await this.webSocket.reconnect(() => {
       this.initListeners()
@@ -148,7 +286,7 @@ export class RpgClientEngine<T = any> {
     const res = await this.loadMapService.load(mapId)
     this.sceneMap.data.set(res)
     this.hooks.callHooks("client-sceneMap-onAfterLoading", this.sceneMap).subscribe();
-    //this.sceneMap.loadPhysic()
+    this.sceneMap.loadPhysic()
   }
 
   addSpriteSheet<T = any>(spritesheetClass: any, id?: string): any {
@@ -156,6 +294,90 @@ export class RpgClientEngine<T = any> {
     return spritesheetClass as any;
   }
 
+  /**
+   * 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;
+  }
+
   addSound(sound: any, id?: string) {
     this.sounds.set(id || sound.id, sound);
     return sound;
@@ -267,9 +489,34 @@ export class RpgClientEngine<T = any> {
     return componentAnimation.instance
   }
 
-  processInput({ input }: { input: number }) {
+  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.hooks.callHooks("client-engine-onInput", this, { input, playerId: this.playerId }).subscribe();
-    this.webSocket.emit('move', { input })
+
+    this.webSocket.emit('move', {
+      input,
+      timestamp,
+      frame,
+      tick,
+    });
+
+    const currentPlayer = this.sceneMap.getCurrentPlayer();
+    if (currentPlayer) {
+      (this.sceneMap as any).moveBody(currentPlayer, input);
+    }
+    this.lastInputTime = Date.now();
+    const myId = this.playerIdSignal();
+
   }
 
   processAction({ action }: { action: number }) {
@@ -285,7 +532,7 @@ export class RpgClientEngine<T = any> {
   get socket() {
     return this.webSocket
   }
-  
+
   get playerId() {
     return this.playerIdSignal()
   }
@@ -294,7 +541,123 @@ export class RpgClientEngine<T = any> {
     return this.sceneMap
   }
 
+  private getPhysicsTick(): number {
+    return this.sceneMap?.getTick?.() ?? 0;
+  }
+
+  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;
+      return;
+    }
+    this.prediction = new PredictionController<Direction>({
+      correctionThreshold: (this.globalConfig as any)?.prediction?.correctionThreshold ?? this.SERVER_CORRECTION_THRESHOLD,
+      historyTtlMs: (this.globalConfig as any)?.prediction?.historyTtlMs ?? 2000,
+      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;
+  }
+
+  private applyServerAck(ack: { frame: number; serverTick?: number; x?: number; y?: number; direction?: Direction }) {
+    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 }
+            : undefined,
+      });
+      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);
+   * ```
+   */
+  private async replayUnackedInputsFromFrame(_startFrame: number): Promise<void> {
+    // Prediction controller handles replay internally. Kept for backwards compatibility.
+  }
 }

package/src/components/animations/animation.ce

@@ -7,10 +7,9 @@
   const { x, y, animationName, graphic, onFinish } = defineProps();
 
   const client = inject(RpgClientEngine);
-  const spritesheets = client.spritesheets;
 
   const sheet = {
-    definition: spritesheets.get(graphic()),
+    definition: client.getSpriteSheet(graphic()),
     playing: animationName() ?? 'default',
     onFinish
   };

package/src/components/character.ce

@@ -1,4 +1,4 @@
-<Container x y zIndex={y} viewportFollow={isMe} controls onBeforeDestroy visible={isConnected}>
+<Container x={smoothX} y={smoothY} zIndex={y} viewportFollow={isMe} controls onBeforeDestroy visible>
   @for (component of componentsBehind) {
     <Container>
       <component object />
@@ -18,8 +18,8 @@
 </Container>
 
 <script>
-  import { signal, effect, mount, computed, tick } from "canvasengine";
-  import { lastValueFrom } from "rxjs";
+  import { signal, effect, mount, computed, tick, animatedSignal } from "canvasengine";
+  import { lastValueFrom, combineLatest, pairwise, filter, map, startWith } from "rxjs";
   import { Particle } from "@canvasengine/presets";
   import { GameEngineToken, ModulesToken } from "@rpgjs/common";
   import { RpgClientEngine } from "../RpgClientEngine";
@@ -28,7 +28,7 @@
   import Hit from "./effects/hit.ce";
 
   const { object, id } = defineProps();
-  
+
   const client = inject(RpgClientEngine);
   const hooks = inject(ModulesToken);
 
@@ -49,7 +49,7 @@
     particleName, 
     graphics, 
     hitbox,
-    isConnected
+    isConnected,
   } = object;
 
   const particleSettings = client.particleSettings;
@@ -57,6 +57,13 @@
   const canControls = () => isMe() && object.canMove()
   const keyboardControls = client.globalConfig.keyboardControls;
 
+  const visible = computed(() => {
+    if (object.type === 'event') {
+      return true
+    }
+    return isConnected()
+  });
+
   const controls = signal({
     down: {
       repeat: true,
@@ -99,10 +106,28 @@
     },
   });
 
+  const smoothX = animatedSignal(x(), {
+    duration: isMe() ? 0 : 0
+  });
+
+  const smoothY = animatedSignal(y(), {
+    duration: isMe() ? 0 : 0,
+  });
+
+  const realAnimationName = signal(animationName());
+
+  const xSubscription = x.observable.subscribe((value) => {
+    smoothX.set(value);
+  });
+
+  const ySubscription = y.observable.subscribe((value) => {
+    smoothY.set(value);
+  });
+  
   const sheet = (graphicId) => {
     return {
-      definition: spritesheets.get(graphicId),
-      playing: animationName,
+      definition: client.getSpriteSheet(graphicId),
+      playing: realAnimationName,
       params: {
         direction
       },
@@ -112,27 +137,62 @@
     };
   }
 
-  // Track animation changes to reset animation state when needed
-  let previousAnimationName = animationName();
-  effect(() => {
-    const currentAnimationName = animationName();
-    
-    // If animation changed externally (not through setAnimation), reset the state
-    if (currentAnimationName !== previousAnimationName && object.animationIsPlaying && object.animationIsPlaying()) {
-      // Check if this is a movement animation (walk, stand) that should interrupt custom animations
-      const movementAnimations = ['walk', 'stand'];
-      if (movementAnimations.includes(currentAnimationName)) {
+  // Combine animation change detection with movement state from smoothX/smoothY
+  const movementAnimations = ['walk', 'stand'];
+  const epsilon = 0; // movement threshold to consider the easing still running
+
+  const stateX$ = smoothX.animatedState.observable;
+  const stateY$ = smoothY.animatedState.observable;
+  const animationName$ = animationName.observable;
+
+  const moving$ = combineLatest([stateX$, stateY$]).pipe(
+    map(([sx, sy]) => {
+      const xFinished = Math.abs(sx.value.current - sx.value.end) <= epsilon;
+      const yFinished = Math.abs(sy.value.current - sy.value.end) <= epsilon;
+      return !xFinished || !yFinished; // moving if X or Y is not finished
+    }),
+    startWith(false)
+  );
+
+  const animationChange$ = animationName$.pipe(
+    startWith(animationName()),
+    pairwise(),
+    filter(([prev, curr]) => prev !== curr)
+  );
+
+  const animationMovementSubscription = combineLatest([animationChange$, moving$]).subscribe(([[prev, curr], isMoving]) => {
+    if (curr == 'stand' && !isMoving) {
+      realAnimationName.set(curr);
+    }
+    else if (curr == 'walk' && isMoving) {
+      realAnimationName.set(curr);
+    }
+    else if (!movementAnimations.includes(curr)) {
+      realAnimationName.set(curr);
+    }
+    if (!isMoving && object.animationIsPlaying && object.animationIsPlaying()) {
+      if (movementAnimations.includes(curr)) {
         if (typeof object.resetAnimationState === 'function') {
           object.resetAnimationState();
         }
       }
     }
-    
-    previousAnimationName = currentAnimationName;
-    
   });
 
+  /**
+   * Cleanup subscriptions and call hooks before sprite destruction.
+   *
+   * # Design
+   * - Prevent memory leaks by unsubscribing from all local subscriptions created in this component.
+   * - Execute destruction hooks to notify modules and scene map of sprite removal.
+   *
+   * @example
+   * await onBeforeDestroy();
+   */
   const onBeforeDestroy = async () => {
+    animationMovementSubscription.unsubscribe();
+    xSubscription.unsubscribe();
+    ySubscription.unsubscribe();
     await lastValueFrom(hooks.callHooks("client-sprite-onDestroy", object)) 
     await lastValueFrom(hooks.callHooks("client-sceneMap-onRemoveSprite", client.sceneMap, object))
   }

package/src/components/gui/dialogbox/index.ce

@@ -78,7 +78,6 @@
   }
   const dialogBoxTypewriterSound = client.globalConfig?.box?.sounds?.typewriter
 
-  const spritesheets = client.spritesheets;
   const sounds = client.sounds;
 
   client.stopProcessingInput = true;
@@ -140,7 +139,7 @@
 
   const faceSheet = (graphicId, animationName) => {
     return {
-      definition: spritesheets.get(graphicId),
+      definition: client.getSpriteSheet(graphicId),
       playing: animationName,
     };
   }