@rpgjs/client 5.0.0-beta.7 → 5.0.0-beta.8

package/dist/RpgClient.d.ts

@@ -5,6 +5,12 @@ 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;
@@ -85,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
@@ -99,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
      *
@@ -479,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: any;
     height: any;
-    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: any;
     spriteComponentsBehind: any;
     spriteComponentsInFront: any;
+    spriteComponents: Map<string, any>;
     /** ID of the sprite that the camera should follow. null means follow the current player */
     cameraFollowTargetId: any;
     /** Trigger for map shake animation */
-    mapShakeTrigger: any;
+    mapShakeTrigger: ConfigurableTrigger<MapShakeOptions>;
     controlsReady: any;
     gamePause: any;
     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
      *
@@ -700,3 +735,4 @@ export declare class RpgClientEngine<T = any> {
      */
     clear(): void;
 }
+export {};

package/dist/RpgClientEngine.js

@@ -11,6 +11,10 @@ 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";
@@ -30,6 +34,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 +77,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();
 	}
@@ -163,7 +174,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();
@@ -409,7 +420,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();
 		});
@@ -464,7 +475,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
 	* 
@@ -813,6 +824,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