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

package/dist/RpgClient.d.ts

@@ -5,6 +5,23 @@ import { RpgClientObject } from './Game/Object';
 import { MapPhysicsEntityContext, MapPhysicsInitContext } from '@rpgjs/common';
 type RpgComponent = RpgClientObject;
 type SceneMap = Container;
+export type SpriteComponentConfig = ComponentFunction | {
+    component: ComponentFunction;
+    props?: Record<string, any> | ((object: RpgClientObject) => Record<string, any>);
+    data?: Record<string, any> | ((object: RpgClientObject) => Record<string, any>);
+    dependencies?: (object: RpgClientObject) => any[];
+};
+export interface RpgSpriteBeforeRemoveContext {
+    reason?: string;
+    data?: any;
+    transition?: {
+        animation?: string;
+        graphic?: string | string[];
+        duration?: number;
+        effect?: string;
+    };
+    timeoutMs?: number;
+}
 export interface RpgClientEngineHooks {
     /**
      * When the engine is started. If you send false, you prevent the client from connecting to the server
@@ -74,7 +91,7 @@ export interface RpgSpriteHooks {
      * }
      * ```
      */
-    componentsBehind?: ComponentFunction[];
+    componentsBehind?: SpriteComponentConfig[];
     /**
      * Array of components to render in front of the sprite
      * These components will be displayed with a higher z-index than the sprite itself
@@ -88,7 +105,27 @@ export interface RpgSpriteHooks {
      * }
      * ```
      */
-    componentsInFront?: ComponentFunction[];
+    componentsInFront?: SpriteComponentConfig[];
+    /**
+     * Reusable sprite components addressable by server-side component definitions.
+     *
+     * The server sends only the component id and serializable props. The client
+     * registry maps that id to the CanvasEngine component that renders it.
+     *
+     * @prop {Record<string, ComponentFunction>} [components]
+     * @memberof RpgSpriteHooks
+     * @example
+     * ```ts
+     * import GuildBadge from './components/guild-badge.ce'
+     *
+     * const sprite: RpgSpriteHooks = {
+     *   components: {
+     *     guildBadge: GuildBadge
+     *   }
+     * }
+     * ```
+     */
+    components?: Record<string, ComponentFunction>;
     /**
      * As soon as the sprite is initialized
      *
@@ -103,6 +140,17 @@ export interface RpgSpriteHooks {
      * @memberof RpgSpriteHooks
      */
     onDestroy?: (sprite: RpgComponent) => any;
+    /**
+     * Called when a sprite removal is requested, before it disappears from the scene.
+     *
+     * Return a promise to keep the sprite visible while an animation, effect, or
+     * sound transition is running. The server still owns gameplay removal and
+     * uses the timeout carried by the remove request as a safety limit.
+     *
+     * @prop { (sprite: RpgSprite, context: RpgSpriteBeforeRemoveContext) => any } [onBeforeRemove]
+     * @memberof RpgSpriteHooks
+     */
+    onBeforeRemove?: (sprite: RpgComponent, context: RpgSpriteBeforeRemoveContext) => any;
     /**
      * As soon as a data is changed on the server side (the name for example), you are able to know the new data but also the old data.
      *
@@ -457,6 +505,13 @@ export interface RpgClient {
          * ```
          */
         attachToSprite?: boolean;
+        /**
+         * Vue v4 compatibility alias for `attachToSprite`.
+         *
+         * Prefer `attachToSprite` in v5 projects. This is read by `@rpgjs/vue`
+         * for Vue GUI components migrated from the v4 GUI API.
+         */
+        rpgAttachToSprite?: boolean;
     } | any)[];
     /**
      * Array containing the list of sounds

package/dist/RpgClientEngine.d.ts

@@ -1,9 +1,19 @@
+import { Trigger } from 'canvasengine';
 import { AbstractWebsocket } from './services/AbstractSocket';
 import { Direction } from '@rpgjs/common';
 import { RpgClientMap } from './Game/Map';
 import { AnimationManager } from './Game/AnimationManager';
 import { Observable } from 'rxjs';
 import * as PIXI from "pixi.js";
+type ConfigurableTrigger<T> = Omit<Trigger<T>, "start"> & {
+    start(config?: T): Promise<void>;
+};
+type MapShakeOptions = {
+    intensity?: number;
+    duration?: number;
+    frequency?: number;
+    direction?: string;
+};
 export declare class RpgClientEngine<T = any> {
     context: any;
     private guiService;
@@ -17,7 +27,7 @@ export declare class RpgClientEngine<T = any> {
     stopProcessingInput: boolean;
     width: import('canvasengine').WritableSignal<string>;
     height: import('canvasengine').WritableSignal<string>;
-    spritesheets: Map<string, any>;
+    spritesheets: Map<string | number, any>;
     sounds: Map<string, any>;
     componentAnimations: any[];
     private spritesheetResolver?;
@@ -32,10 +42,11 @@ export declare class RpgClientEngine<T = any> {
     playerIdSignal: import('canvasengine').WritableSignal<string | null>;
     spriteComponentsBehind: import('canvasengine').WritableArraySignal<any[]>;
     spriteComponentsInFront: import('canvasengine').WritableArraySignal<any[]>;
+    spriteComponents: Map<string, any>;
     /** ID of the sprite that the camera should follow. null means follow the current player */
     cameraFollowTargetId: import('canvasengine').WritableSignal<string | null>;
     /** Trigger for map shake animation */
-    mapShakeTrigger: import('canvasengine').Trigger<any>;
+    mapShakeTrigger: ConfigurableTrigger<MapShakeOptions>;
     controlsReady: import('canvasengine').WritableSignal<undefined>;
     gamePause: import('canvasengine').WritableSignal<boolean>;
     private predictionEnabled;
@@ -175,7 +186,7 @@ export declare class RpgClientEngine<T = any> {
      * });
      * ```
      */
-    setSpritesheetResolver(resolver: (id: string) => any | Promise<any>): void;
+    setSpritesheetResolver(resolver: (id: string | number) => any | Promise<any>): void;
     /**
      * Get a spritesheet by ID, using resolver if not found in cache
      *
@@ -183,7 +194,7 @@ export declare 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
      *
@@ -196,7 +207,7 @@ export declare class RpgClientEngine<T = any> {
      * const spritesheet = await engine.getSpriteSheet('dynamic-sprite');
      * ```
      */
-    getSpriteSheet(id: string): any | Promise<any>;
+    getSpriteSheet(id: string | number): any | Promise<any>;
     /**
      * Add a sound to the engine
      *
@@ -451,6 +462,30 @@ export declare class RpgClientEngine<T = any> {
         props: (object: any) => any;
         dependencies?: (object: any) => any[];
     }): any;
+    /**
+     * 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): any;
+    /**
+     * 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): any;
     /**
      * Add a component animation to the engine
      *
@@ -520,9 +555,12 @@ export declare 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): void;
+    startTransition(id: string, props?: any): Promise<void>;
     processInput({ input }: {
         input: Direction;
     }): Promise<void>;
@@ -584,6 +622,22 @@ export declare class RpgClientEngine<T = any> {
      * ```
      */
     clearClientPredictionStates(): void;
+    /**
+     * 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): boolean;
     /**
      * Trigger a flash animation on a sprite
      *
@@ -681,3 +735,4 @@ export declare class RpgClientEngine<T = any> {
      */
     clear(): void;
 }
+export {};

package/dist/RpgClientEngine.js

@@ -1,19 +1,24 @@
 import { inject } from "./core/inject.js";
 import { WebSocketToken } from "./services/AbstractSocket.js";
+import { getCanMoveValue } from "./utils/readPropValue.js";
 import { SaveClientService } from "./services/save.js";
 import { RpgGui } from "./Gui/Gui.js";
-import component from "./components/scenes/canvas.ce.js";
+import __ce_component from "./components/scenes/canvas.ce.js";
 import { LoadMapToken } from "./services/loadMap.js";
 import { RpgSound } from "./Sound.js";
 import { RpgResource } from "./Resource.js";
-import { load } from "./node_modules/.pnpm/@signe_sync@2.9.0/node_modules/@signe/sync/dist/index.js";
+import { load } from "./node_modules/.pnpm/@signe_sync@3.0.1/node_modules/@signe/sync/dist/index.js";
 import { RpgClientMap } from "./Game/Map.js";
 import { AnimationManager } from "./Game/AnimationManager.js";
 import { GlobalConfigToken } from "./module.js";
 import { PrebuiltComponentAnimations } from "./components/animations/index.js";
+import __ce_component$1 from "./components/dynamics/text.ce.js";
+import __ce_component$2 from "./components/dynamics/bar.ce.js";
+import __ce_component$3 from "./components/dynamics/shape.ce.js";
+import __ce_component$4 from "./components/dynamics/image.ce.js";
 import { NotificationManager } from "./Gui/NotificationManager.js";
 import { Howl, bootstrapCanvas, signal, trigger } from "canvasengine";
-import { Direction, ModulesToken, PredictionController } from "@rpgjs/common";
+import { Direction, ModulesToken, PredictionController, normalizeLightingState } from "@rpgjs/common";
 import { BehaviorSubject, combineLatest, filter, lastValueFrom, switchMap, take } from "rxjs";
 import * as PIXI from "pixi.js";
 //#region src/RpgClientEngine.ts
@@ -30,6 +35,7 @@ var RpgClientEngine = class {
 		this.playerIdSignal = signal(null);
 		this.spriteComponentsBehind = signal([]);
 		this.spriteComponentsInFront = signal([]);
+		this.spriteComponents = /* @__PURE__ */ new Map();
 		this.cameraFollowTargetId = signal(null);
 		this.mapShakeTrigger = trigger();
 		this.controlsReady = signal(void 0);
@@ -72,6 +78,12 @@ var RpgClientEngine = class {
 			id: "animation",
 			component: PrebuiltComponentAnimations.Animation
 		});
+		this.registerSpriteComponent("rpg:text", __ce_component$1);
+		this.registerSpriteComponent("rpg:hpBar", __ce_component$2);
+		this.registerSpriteComponent("rpg:spBar", __ce_component$2);
+		this.registerSpriteComponent("rpg:bar", __ce_component$2);
+		this.registerSpriteComponent("rpg:shape", __ce_component$3);
+		this.registerSpriteComponent("rpg:image", __ce_component$4);
 		this.predictionEnabled = this.globalConfig?.prediction?.enabled !== false;
 		this.initializePredictionController();
 	}
@@ -122,7 +134,7 @@ var RpgClientEngine = class {
 		this.sceneMap.loadPhysic();
 		this.selector = document.body.querySelector("#rpg");
 		const bootstrapOptions = this.globalConfig?.bootstrapCanvasOptions;
-		const { app, canvasElement } = await bootstrapCanvas(this.selector, component, bootstrapOptions);
+		const { app, canvasElement } = await bootstrapCanvas(this.selector, __ce_component, bootstrapOptions);
 		this.canvasApp = app;
 		this.canvasElement = canvasElement;
 		this.renderer = app.renderer;
@@ -163,7 +175,7 @@ var RpgClientEngine = class {
 		});
 		this.tickSubscriptions.push(tickSubscription);
 		await this.webSocket.connection(() => {
-			inject(SaveClientService).initialize(this.webSocket);
+			inject(SaveClientService).initialize();
 			this.initListeners();
 			this.guiService._initialize();
 			this.startPingPong();
@@ -227,7 +239,8 @@ var RpgClientEngine = class {
 			if ((payload.events || this.sceneMap.events()) !== void 0) this.eventsReceived$.next(true);
 		});
 		this.webSocket.on("pong", (data) => {
-			this.rtt = Date.now() - data.clientTime;
+			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;
@@ -235,6 +248,7 @@ var RpgClientEngine = class {
 		});
 		this.webSocket.on("changeMap", (data) => {
 			this.sceneResetQueued = true;
+			this.sceneMap.clearLightSpots();
 			this.cameraFollowTargetId.set(null);
 			const transferToken = typeof data?.transferToken === "string" ? data.transferToken : void 0;
 			this.loadScene(data.mapId, transferToken);
@@ -249,10 +263,15 @@ var RpgClientEngine = class {
 			this.notificationManager.add(data);
 		});
 		this.webSocket.on("setAnimation", (data) => {
-			const { animationName, nbTimes, object, graphic } = data;
-			const player = this.sceneMap.getObjectById(object);
-			if (graphic !== void 0) player.setAnimation(animationName, graphic, nbTimes);
-			else player.setAnimation(animationName, nbTimes);
+			const { animationName, nbTimes, object, graphic, restoreAnimationName, restoreGraphics } = data;
+			const player = object ? this.sceneMap.getObjectById(object) : void 0;
+			if (!player) return;
+			const restoreOptions = {
+				restoreAnimationName,
+				restoreGraphics
+			};
+			if (graphic !== void 0) player.setAnimation(animationName, graphic, nbTimes, restoreOptions);
+			else player.setAnimation(animationName, nbTimes, restoreOptions);
 		});
 		this.webSocket.on("playSound", (data) => {
 			const { soundId, volume, loop } = data;
@@ -314,6 +333,10 @@ var RpgClientEngine = class {
 				seed: raw.seed
 			});
 		});
+		this.webSocket.on("lightingState", (data) => {
+			const raw = data && typeof data === "object" && "value" in data ? data.value : data;
+			this.sceneMap.lightingState.set(normalizeLightingState(raw));
+		});
 		this.webSocket.on("open", () => {
 			this.hooks.callHooks("client-engine-onConnected", this, this.socket).subscribe();
 			this.startPingPong();
@@ -403,7 +426,7 @@ var RpgClientEngine = class {
 			query: transferToken ? { transferToken } : void 0
 		});
 		await this.webSocket.reconnect(() => {
-			inject(SaveClientService).initialize(this.webSocket);
+			inject(SaveClientService).initialize();
 			this.initListeners();
 			this.guiService._initialize();
 		});
@@ -458,7 +481,7 @@ var RpgClientEngine = class {
 	* 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
 	* 
@@ -807,6 +830,35 @@ var RpgClientEngine = class {
 		return component;
 	}
 	/**
+	* Register a reusable sprite component that can be addressed by the server.
+	*
+	* Server-side component definitions only carry the component id and
+	* serializable props. The client registry maps that id to the CanvasEngine
+	* component that performs the actual rendering.
+	*
+	* @param id - Stable component id used by server component definitions
+	* @param component - CanvasEngine component to render for this id
+	* @returns The registered component
+	*
+	* @example
+	* ```ts
+	* engine.registerSpriteComponent('guildBadge', GuildBadgeComponent);
+	* ```
+	*/
+	registerSpriteComponent(id, component) {
+		this.spriteComponents.set(id, component);
+		return component;
+	}
+	/**
+	* Get a reusable sprite component by id.
+	*
+	* @param id - Component id registered on the client
+	* @returns The CanvasEngine component, or undefined when missing
+	*/
+	getSpriteComponent(id) {
+		return this.spriteComponents.get(id);
+	}
+	/**
 	* Add a component animation to the engine
 	* 
 	* Component animations are temporary visual effects that can be displayed
@@ -882,13 +934,34 @@ var RpgClientEngine = class {
 	*   duration: 1000,
 	*   onFinish: () => console.log('Fade complete')
 	* });
+	*
+	* // Wait until the transition component calls onFinish
+	* await engine.startTransition('fade', { duration: 1000 });
 	* ```
 	*/
 	startTransition(id, props = {}) {
 		if (!this.guiService.exists(id)) throw new Error(`Transition with id ${id} not found. Make sure to add it using engine.addTransition() or in your module's transitions property.`);
-		this.guiService.display(id, props);
+		return new Promise((resolve) => {
+			let finished = false;
+			const finish = (data) => {
+				if (finished) return;
+				finished = true;
+				props?.onFinish?.(data);
+				resolve();
+			};
+			this.guiService.display(id, {
+				...props,
+				onFinish: finish
+			});
+		});
 	}
 	async processInput({ input }) {
+		if (this.stopProcessingInput) return;
+		const currentPlayer = this.sceneMap.getCurrentPlayer();
+		if (!(!currentPlayer || getCanMoveValue(currentPlayer))) {
+			this.interruptCurrentPlayerMovement(currentPlayer);
+			return;
+		}
 		const timestamp = Date.now();
 		let frame;
 		let tick;
@@ -905,7 +978,6 @@ var RpgClientEngine = class {
 			input,
 			playerId: this.playerId
 		}).subscribe();
-		const currentPlayer = this.sceneMap.getCurrentPlayer();
 		const bodyReady = this.ensureCurrentPlayerBody();
 		if (currentPlayer && bodyReady) {
 			currentPlayer.changeDirection(input);
@@ -920,6 +992,8 @@ var RpgClientEngine = class {
 	}
 	processAction({ action }) {
 		if (this.stopProcessingInput) return;
+		const currentPlayer = this.sceneMap.getCurrentPlayer();
+		if (!(!currentPlayer || getCanMoveValue(currentPlayer))) return;
 		this.hooks.callHooks("client-engine-onInput", this, {
 			input: "action",
 			playerId: this.playerId
@@ -1008,6 +1082,11 @@ var RpgClientEngine = class {
 	}
 	flushPendingMovePath() {
 		if (!this.predictionEnabled || !this.prediction) return;
+		const player = this.sceneMap?.getCurrentPlayer?.();
+		if (player && !getCanMoveValue(player)) {
+			this.interruptCurrentPlayerMovement(player);
+			return;
+		}
 		const pendingInputs = this.prediction.getPendingInputs();
 		if (pendingInputs.length === 0) return;
 		const latest = pendingInputs[pendingInputs.length - 1];
@@ -1124,6 +1203,31 @@ var RpgClientEngine = class {
 		this.lastMovePathSentFrame = 0;
 	}
 	/**
+	* Stop local movement immediately and discard pending predicted movement.
+	*
+	* Use this before a blocking action such as an A-RPG attack, dialog, dash
+	* startup, or any client-side state where already buffered movement inputs
+	* must not be replayed after server reconciliation.
+	*
+	* @param player - Player object to stop. Defaults to the current player.
+	* @returns `true` when a player was found and interrupted.
+	*
+	* @example
+	* ```ts
+	* engine.interruptCurrentPlayerMovement();
+	* ```
+	*/
+	interruptCurrentPlayerMovement(player = this.sceneMap?.getCurrentPlayer?.()) {
+		if (!player) return false;
+		this.sceneMap?.stopMovement?.(player);
+		this.prediction?.clearPendingInputs();
+		this.pendingPredictionFrames = [];
+		this.lastInputTime = 0;
+		this.lastMovePathSentAt = Date.now();
+		this.lastMovePathSentFrame = this.inputFrameCounter;
+		return true;
+	}
+	/**
 	* Trigger a flash animation on a sprite
 	* 
 	* This method allows you to trigger a flash effect on any sprite from client-side code.
@@ -1205,6 +1309,10 @@ var RpgClientEngine = class {
 	reconcilePrediction(authoritativeState, pendingInputs) {
 		const player = this.getCurrentPlayer();
 		if (!player) return;
+		if (!getCanMoveValue(player)) {
+			this.interruptCurrentPlayerMovement(player);
+			return;
+		}
 		this.sceneMap.stopMovement(player);
 		this.applyAuthoritativeState(authoritativeState);
 		if (!pendingInputs.length) return;