@rpgjs/client 5.0.0-beta.1 → 5.0.0-beta.10

package/src/RpgClientEngine.ts

@@ -1,11 +1,11 @@
 import Canvas from "./components/scenes/canvas.ce";
 import { inject } from './core/inject'
-import { signal, bootstrapCanvas, Howl, trigger } from "canvasengine";
+import { signal, bootstrapCanvas, Howl, trigger, type Trigger } from "canvasengine";
 import { AbstractWebsocket, WebSocketToken } from "./services/AbstractSocket";
 import { LoadMapService, LoadMapToken } from "./services/loadMap";
 import { RpgSound } from "./Sound";
 import { RpgResource } from "./Resource";
-import { Hooks, ModulesToken, Direction } from "@rpgjs/common";
+import { Hooks, ModulesToken, Direction, normalizeLightingState } from "@rpgjs/common";
 import { load } from "@signe/sync";
 import { RpgClientMap } from "./Game/Map"
 import { RpgGui } from "./Gui/Gui";
@@ -14,6 +14,10 @@ import { lastValueFrom, Observable, combineLatest, BehaviorSubject, filter, swit
 import { GlobalConfigToken } from "./module";
 import * as PIXI from "pixi.js";
 import { PrebuiltComponentAnimations } from "./components/animations";
+import TextComponent from "./components/dynamics/text.ce";
+import BarComponent from "./components/dynamics/bar.ce";
+import ShapeComponent from "./components/dynamics/shape.ce";
+import ImageComponent from "./components/dynamics/image.ce";
 import {
   PredictionController,
   type PredictionHistoryEntry,
@@ -21,6 +25,7 @@ import {
 } from "@rpgjs/common";
 import { NotificationManager } from "./Gui/NotificationManager";
 import { SaveClientService } from "./services/save";
+import { getCanMoveValue } from "./utils/readPropValue";
 
 interface MovementTrajectoryPoint {
   frame: number;
@@ -32,6 +37,17 @@ interface MovementTrajectoryPoint {
   direction?: Direction;
 }
 
+type ConfigurableTrigger<T> = Omit<Trigger<T>, "start"> & {
+  start(config?: T): Promise<void>;
+};
+
+type MapShakeOptions = {
+  intensity?: number;
+  duration?: number;
+  frequency?: number;
+  direction?: string;
+};
+
 export class RpgClientEngine<T = any> {
   private guiService: RpgGui;
   private webSocket: AbstractWebsocket;
@@ -44,10 +60,10 @@ export class RpgClientEngine<T = any> {
   stopProcessingInput = false;
   width = signal("100%");
   height = signal("100%");
-  spritesheets: Map<string, any> = new Map();
+  spritesheets: Map<string | number, any> = new Map();
   sounds: Map<string, any> = new Map();
   componentAnimations: any[] = [];
-  private spritesheetResolver?: (id: string) => any | Promise<any>;
+  private spritesheetResolver?: (id: string | number) => any | Promise<any>;
   private soundResolver?: (id: string) => any | Promise<any>;
   particleSettings: {
     emitters: any[]
@@ -61,10 +77,11 @@ export class RpgClientEngine<T = any> {
   playerIdSignal = signal<string | null>(null);
   spriteComponentsBehind = signal<any[]>([]);
   spriteComponentsInFront = signal<any[]>([]);
+  spriteComponents: Map<string, any> = new Map();
   /** 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();
+  mapShakeTrigger: ConfigurableTrigger<MapShakeOptions> = trigger<MapShakeOptions>();
 
   controlsReady = signal(undefined); 
   gamePause = signal(false);
@@ -123,6 +140,13 @@ export class RpgClientEngine<T = any> {
       component: PrebuiltComponentAnimations.Animation
     })
 
+    this.registerSpriteComponent("rpg:text", TextComponent);
+    this.registerSpriteComponent("rpg:hpBar", BarComponent);
+    this.registerSpriteComponent("rpg:spBar", BarComponent);
+    this.registerSpriteComponent("rpg:bar", BarComponent);
+    this.registerSpriteComponent("rpg:shape", ShapeComponent);
+    this.registerSpriteComponent("rpg:image", ImageComponent);
+
     this.predictionEnabled = (this.globalConfig as any)?.prediction?.enabled !== false;
     this.initializePredictionController();
   }
@@ -233,7 +257,7 @@ export class RpgClientEngine<T = any> {
 
     await this.webSocket.connection(() => {
       const saveClient = inject(SaveClientService);
-      saveClient.initialize(this.webSocket);
+      saveClient.initialize();
       this.initListeners()
       this.guiService._initialize()
       this.startPingPong();
@@ -355,6 +379,7 @@ export class RpgClientEngine<T = any> {
 
     this.webSocket.on("changeMap", (data) => {
       this.sceneResetQueued = true;
+      this.sceneMap.clearLightSpots();
       // Reset camera follow to default (follow current player) when changing maps
       this.cameraFollowTargetId.set(null);
       const transferToken = typeof data?.transferToken === "string" ? data.transferToken : undefined;
@@ -374,15 +399,27 @@ export class RpgClientEngine<T = any> {
       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("setAnimation", (data) => {
+      const {
+        animationName,
+        nbTimes,
+        object,
+        graphic,
+        restoreAnimationName,
+        restoreGraphics,
+      } = data;
+      const player = object ? this.sceneMap.getObjectById(object) : undefined;
+      if (!player) return;
+      const restoreOptions = {
+        restoreAnimationName,
+        restoreGraphics,
+      };
+      if (graphic !== undefined) {
+        player.setAnimation(animationName, graphic, nbTimes, restoreOptions);
+      } else {
+        player.setAnimation(animationName, nbTimes, restoreOptions);
+      }
+    })
 
     this.webSocket.on("playSound", (data) => {
       const { soundId, volume, loop } = data;
@@ -413,7 +450,7 @@ export class RpgClientEngine<T = any> {
 
     this.webSocket.on("shakeMap", (data) => {
       const { intensity, duration, frequency, direction } = data || {};
-      (this.mapShakeTrigger as any).start({
+      this.mapShakeTrigger.start({
         intensity,
         duration,
         frequency,
@@ -447,6 +484,14 @@ export class RpgClientEngine<T = any> {
       });
     });
 
+    this.webSocket.on("lightingState", (data) => {
+      const raw = (data && typeof data === "object" && "value" in data)
+        ? (data as any).value
+        : data;
+
+      this.sceneMap.lightingState.set(normalizeLightingState(raw));
+    });
+
     this.webSocket.on('open', () => {
       this.hooks.callHooks("client-engine-onConnected", this, this.socket).subscribe();
       // Start ping/pong for synchronization
@@ -562,7 +607,7 @@ export class RpgClientEngine<T = any> {
     })
     await this.webSocket.reconnect(() => {
       const saveClient = inject(SaveClientService);
-      saveClient.initialize(this.webSocket);
+      saveClient.initialize();
       this.initListeners()
       this.guiService._initialize()
     })
@@ -623,7 +668,7 @@ export class RpgClientEngine<T = any> {
    * });
    * ```
    */
-  setSpritesheetResolver(resolver: (id: string) => any | Promise<any>): void {
+  setSpritesheetResolver(resolver: (id: string | number) => any | Promise<any>): void {
     this.spritesheetResolver = resolver;
   }
 
@@ -634,7 +679,7 @@ export class RpgClientEngine<T = any> {
    * 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
+   * @param id - The spritesheet ID or legacy tile ID to retrieve
    * @returns The spritesheet if found or created, or undefined if not found and no resolver
    * @returns Promise<any> if the resolver is asynchronous
    * 
@@ -647,7 +692,7 @@ export class RpgClientEngine<T = any> {
    * const spritesheet = await engine.getSpriteSheet('dynamic-sprite');
    * ```
    */
-  getSpriteSheet(id: string): any | Promise<any> {
+  getSpriteSheet(id: string | number): any | Promise<any> {
     // Check cache first
     if (this.spritesheets.has(id)) {
       return this.spritesheets.get(id);
@@ -1081,6 +1126,37 @@ export class RpgClientEngine<T = any> {
     return component
   }
 
+  /**
+   * Register a reusable sprite component that can be addressed by the server.
+   *
+   * Server-side component definitions only carry the component id and
+   * serializable props. The client registry maps that id to the CanvasEngine
+   * component that performs the actual rendering.
+   *
+   * @param id - Stable component id used by server component definitions
+   * @param component - CanvasEngine component to render for this id
+   * @returns The registered component
+   *
+   * @example
+   * ```ts
+   * engine.registerSpriteComponent('guildBadge', GuildBadgeComponent);
+   * ```
+   */
+  registerSpriteComponent(id: string, component: any) {
+    this.spriteComponents.set(id, component);
+    return component;
+  }
+
+  /**
+   * Get a reusable sprite component by id.
+   *
+   * @param id - Component id registered on the client
+   * @returns The CanvasEngine component, or undefined when missing
+   */
+  getSpriteComponent(id: string) {
+    return this.spriteComponents.get(id);
+  }
+
   /**
    * Add a component animation to the engine
    * 
@@ -1164,16 +1240,43 @@ export class RpgClientEngine<T = any> {
    *   duration: 1000,
    *   onFinish: () => console.log('Fade complete')
    * });
+   *
+   * // Wait until the transition component calls onFinish
+   * await engine.startTransition('fade', { duration: 1000 });
    * ```
    */
-  startTransition(id: string, props: any = {}) {
+  startTransition(id: string, props: any = {}): Promise<void> {
     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);
+    return new Promise<void>((resolve) => {
+      let finished = false;
+      const finish = (data?: any) => {
+        if (finished) return;
+        finished = true;
+        props?.onFinish?.(data);
+        resolve();
+      };
+
+      this.guiService.display(id, {
+        ...props,
+        onFinish: finish,
+      });
+    });
   }
 
   async processInput({ input }: { input: Direction }) {
+    if (this.stopProcessingInput) return;
+
+    const currentPlayer = this.sceneMap.getCurrentPlayer() as any;
+    const canMove =
+      !currentPlayer ||
+      getCanMoveValue(currentPlayer);
+    if (!canMove) {
+      this.interruptCurrentPlayerMovement(currentPlayer);
+      return;
+    }
+
     const timestamp = Date.now();
     let frame: number;
     let tick: number;
@@ -1188,7 +1291,6 @@ export class RpgClientEngine<T = any> {
     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);
@@ -1207,6 +1309,12 @@ export class RpgClientEngine<T = any> {
 
   processAction({ action }: { action: number }) {
     if (this.stopProcessingInput) return;
+    const currentPlayer = this.sceneMap.getCurrentPlayer() as any;
+    const canMove =
+      !currentPlayer ||
+      getCanMoveValue(currentPlayer);
+    if (!canMove) return;
+
     this.hooks.callHooks("client-engine-onInput", this, { input: 'action', playerId: this.playerId }).subscribe();
     this.webSocket.emit('action', { action })
   }
@@ -1337,6 +1445,14 @@ export class RpgClientEngine<T = any> {
     if (!this.predictionEnabled || !this.prediction) {
       return;
     }
+    const player = this.sceneMap?.getCurrentPlayer?.() as any;
+    if (
+      player &&
+      !getCanMoveValue(player)
+    ) {
+      this.interruptCurrentPlayerMovement(player);
+      return;
+    }
     const pendingInputs = this.prediction.getPendingInputs();
     if (pendingInputs.length === 0) {
       return;
@@ -1475,6 +1591,34 @@ export class RpgClientEngine<T = any> {
     this.lastMovePathSentFrame = 0;
   }
 
+  /**
+   * Stop local movement immediately and discard pending predicted movement.
+   *
+   * Use this before a blocking action such as an A-RPG attack, dialog, dash
+   * startup, or any client-side state where already buffered movement inputs
+   * must not be replayed after server reconciliation.
+   *
+   * @param player - Player object to stop. Defaults to the current player.
+   * @returns `true` when a player was found and interrupted.
+   *
+   * @example
+   * ```ts
+   * engine.interruptCurrentPlayerMovement();
+   * ```
+   */
+  interruptCurrentPlayerMovement(player: any = this.sceneMap?.getCurrentPlayer?.()): boolean {
+    if (!player) {
+      return false;
+    }
+    (this.sceneMap as any)?.stopMovement?.(player);
+    this.prediction?.clearPendingInputs();
+    this.pendingPredictionFrames = [];
+    this.lastInputTime = 0;
+    this.lastMovePathSentAt = Date.now();
+    this.lastMovePathSentFrame = this.inputFrameCounter;
+    return true;
+  }
+
   /**
    * Trigger a flash animation on a sprite
    * 
@@ -1560,7 +1704,7 @@ export class RpgClientEngine<T = any> {
     if (typeof ack.x !== "number" || typeof ack.y !== "number") {
       return;
     }
-    const player = this.getCurrentPlayer();
+    const player = this.getCurrentPlayer() as any;
     const myId = this.playerIdSignal();
     if (!player || !myId) {
       return;
@@ -1583,10 +1727,14 @@ export class RpgClientEngine<T = any> {
     authoritativeState: PredictionState<Direction>,
     pendingInputs: PredictionHistoryEntry<Direction>[],
   ): void {
-    const player = this.getCurrentPlayer();
+    const player = this.getCurrentPlayer() as any;
     if (!player) {
       return;
     }
+    if (!getCanMoveValue(player)) {
+      this.interruptCurrentPlayerMovement(player);
+      return;
+    }
 
     (this.sceneMap as any).stopMovement(player);
     this.applyAuthoritativeState(authoritativeState);