@rpgjs/client 5.0.0-alpha.9 → 5.0.0-beta.10

package/dist/Resource.d.ts

@@ -0,0 +1,97 @@
+import { RpgClientEngine } from './RpgClientEngine';
+/**
+ * RpgResource class
+ *
+ * Provides a unified API to access resource file links (images and sounds) in the game.
+ * Resources are stored as Maps of resource IDs to file paths/URLs.
+ *
+ * ## Design
+ *
+ * RpgResource acts as a facade over the engine's resource storage, providing
+ * easy access to resource file links. It maintains Maps that are synchronized
+ * with the engine's internal storage, but only stores the file paths/URLs,
+ * not the full resource objects.
+ *
+ * @example
+ * ```ts
+ * import { RpgResource } from '@rpgjs/client'
+ *
+ * // Get spritesheet image link
+ * const imageLink = RpgResource.spritesheets.get('hero')
+ *
+ * // Get sound file link
+ * const soundLink = RpgResource.sounds.get('town-music')
+ *
+ * // Set a new resource link
+ * RpgResource.spritesheets.set('new-sprite', './assets/new-sprite.png')
+ * ```
+ */
+export declare class RpgResource {
+    private static engine;
+    private static _spritesheets;
+    private static _sounds;
+    /**
+     * Initialize RpgResource with the engine instance
+     *
+     * This is called automatically by the engine during initialization.
+     * It synchronizes the resource Maps with the engine's internal storage.
+     *
+     * @param engine - The RpgClientEngine instance
+     */
+    static init(engine: RpgClientEngine): void;
+    /**
+     * Synchronize resource Maps with the engine's internal storage
+     *
+     * Extracts file links from spritesheets and sounds stored in the engine
+     * and updates the Maps accordingly.
+     *
+     * @private
+     */
+    private static syncResources;
+    /**
+     * Get/Set image links for spritesheets
+     *
+     * Map of spritesheet IDs to their image file paths/URLs.
+     * This Map is synchronized with the engine's spritesheet storage.
+     *
+     * @type {Map<string, string>}
+     *
+     * @example
+     * ```ts
+     * // Get an image link
+     * const imageLink = RpgResource.spritesheets.get('hero')
+     *
+     * // Set a new image link
+     * RpgResource.spritesheets.set('new-sprite', './assets/new-sprite.png')
+     *
+     * // Check if a spritesheet exists
+     * if (RpgResource.spritesheets.has('monster')) {
+     *   const link = RpgResource.spritesheets.get('monster')
+     * }
+     * ```
+     */
+    static get spritesheets(): Map<string, string>;
+    /**
+     * Get/Set sound file links
+     *
+     * Map of sound IDs to their audio file paths/URLs.
+     * This Map is synchronized with the engine's sound storage.
+     *
+     * @type {Map<string, string>}
+     *
+     * @example
+     * ```ts
+     * // Get a sound link
+     * const soundLink = RpgResource.sounds.get('town-music')
+     *
+     * // Set a new sound link
+     * RpgResource.sounds.set('new-sound', './assets/new-sound.ogg')
+     *
+     * // Iterate over all sounds
+     * RpgResource.sounds.forEach((link, id) => {
+     *   console.log(`Sound ${id}: ${link}`)
+     * })
+     * ```
+     */
+    static get sounds(): Map<string, string>;
+}

package/dist/Resource.js

@@ -0,0 +1,133 @@
+//#region src/Resource.ts
+/**
+* RpgResource class
+* 
+* Provides a unified API to access resource file links (images and sounds) in the game.
+* Resources are stored as Maps of resource IDs to file paths/URLs.
+* 
+* ## Design
+* 
+* RpgResource acts as a facade over the engine's resource storage, providing
+* easy access to resource file links. It maintains Maps that are synchronized
+* with the engine's internal storage, but only stores the file paths/URLs,
+* not the full resource objects.
+* 
+* @example
+* ```ts
+* import { RpgResource } from '@rpgjs/client'
+* 
+* // Get spritesheet image link
+* const imageLink = RpgResource.spritesheets.get('hero')
+* 
+* // Get sound file link
+* const soundLink = RpgResource.sounds.get('town-music')
+* 
+* // Set a new resource link
+* RpgResource.spritesheets.set('new-sprite', './assets/new-sprite.png')
+* ```
+*/
+var RpgResource = class RpgResource {
+	static {
+		this.engine = null;
+	}
+	static {
+		this._spritesheets = /* @__PURE__ */ new Map();
+	}
+	static {
+		this._sounds = /* @__PURE__ */ new Map();
+	}
+	/**
+	* Initialize RpgResource with the engine instance
+	* 
+	* This is called automatically by the engine during initialization.
+	* It synchronizes the resource Maps with the engine's internal storage.
+	* 
+	* @param engine - The RpgClientEngine instance
+	*/
+	static init(engine) {
+		RpgResource.engine = engine;
+		RpgResource.syncResources();
+	}
+	/**
+	* Synchronize resource Maps with the engine's internal storage
+	* 
+	* Extracts file links from spritesheets and sounds stored in the engine
+	* and updates the Maps accordingly.
+	* 
+	* @private
+	*/
+	static syncResources() {
+		if (!RpgResource.engine) return;
+		RpgResource._spritesheets.clear();
+		RpgResource.engine.spritesheets.forEach((spritesheet, id) => {
+			const imageLink = spritesheet?.image || spritesheet?.imageSource || void 0;
+			if (imageLink) RpgResource._spritesheets.set(String(id), imageLink);
+		});
+		RpgResource._sounds.clear();
+		RpgResource.engine.sounds.forEach((sound, id) => {
+			let soundLink;
+			if (sound && typeof sound === "object") {
+				if (sound._src && Array.isArray(sound._src) && sound._src.length > 0) soundLink = sound._src[0];
+				else if (sound.src && typeof sound.src === "string") soundLink = sound.src;
+				else if (sound.src && Array.isArray(sound.src) && sound.src.length > 0) soundLink = sound.src[0];
+			}
+			if (soundLink) RpgResource._sounds.set(id, soundLink);
+		});
+	}
+	/**
+	* Get/Set image links for spritesheets
+	* 
+	* Map of spritesheet IDs to their image file paths/URLs.
+	* This Map is synchronized with the engine's spritesheet storage.
+	* 
+	* @type {Map<string, string>}
+	* 
+	* @example
+	* ```ts
+	* // Get an image link
+	* const imageLink = RpgResource.spritesheets.get('hero')
+	* 
+	* // Set a new image link
+	* RpgResource.spritesheets.set('new-sprite', './assets/new-sprite.png')
+	* 
+	* // Check if a spritesheet exists
+	* if (RpgResource.spritesheets.has('monster')) {
+	*   const link = RpgResource.spritesheets.get('monster')
+	* }
+	* ```
+	*/
+	static get spritesheets() {
+		RpgResource.syncResources();
+		return RpgResource._spritesheets;
+	}
+	/**
+	* Get/Set sound file links
+	* 
+	* Map of sound IDs to their audio file paths/URLs.
+	* This Map is synchronized with the engine's sound storage.
+	* 
+	* @type {Map<string, string>}
+	* 
+	* @example
+	* ```ts
+	* // Get a sound link
+	* const soundLink = RpgResource.sounds.get('town-music')
+	* 
+	* // Set a new sound link
+	* RpgResource.sounds.set('new-sound', './assets/new-sound.ogg')
+	* 
+	* // Iterate over all sounds
+	* RpgResource.sounds.forEach((link, id) => {
+	*   console.log(`Sound ${id}: ${link}`)
+	* })
+	* ```
+	*/
+	static get sounds() {
+		RpgResource.syncResources();
+		return RpgResource._sounds;
+	}
+};
+//#endregion
+export { RpgResource };
+
+//# sourceMappingURL=Resource.js.map

package/dist/Resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Resource.js","names":[],"sources":["../src/Resource.ts"],"sourcesContent":["import { RpgClientEngine } from './RpgClientEngine';\n\n/**\n * RpgResource class\n * \n * Provides a unified API to access resource file links (images and sounds) in the game.\n * Resources are stored as Maps of resource IDs to file paths/URLs.\n * \n * ## Design\n * \n * RpgResource acts as a facade over the engine's resource storage, providing\n * easy access to resource file links. It maintains Maps that are synchronized\n * with the engine's internal storage, but only stores the file paths/URLs,\n * not the full resource objects.\n * \n * @example\n * ```ts\n * import { RpgResource } from '@rpgjs/client'\n * \n * // Get spritesheet image link\n * const imageLink = RpgResource.spritesheets.get('hero')\n * \n * // Get sound file link\n * const soundLink = RpgResource.sounds.get('town-music')\n * \n * // Set a new resource link\n * RpgResource.spritesheets.set('new-sprite', './assets/new-sprite.png')\n * ```\n */\nexport class RpgResource {\n  private static engine: RpgClientEngine | null = null;\n  private static _spritesheets: Map<string, string> = new Map();\n  private static _sounds: Map<string, string> = new Map();\n\n  /**\n   * Initialize RpgResource with the engine instance\n   * \n   * This is called automatically by the engine during initialization.\n   * It synchronizes the resource Maps with the engine's internal storage.\n   * \n   * @param engine - The RpgClientEngine instance\n   */\n  static init(engine: RpgClientEngine): void {\n    RpgResource.engine = engine;\n    RpgResource.syncResources();\n  }\n\n  /**\n   * Synchronize resource Maps with the engine's internal storage\n   * \n   * Extracts file links from spritesheets and sounds stored in the engine\n   * and updates the Maps accordingly.\n   * \n   * @private\n   */\n  private static syncResources(): void {\n    if (!RpgResource.engine) {\n      return;\n    }\n\n    // Sync spritesheets\n    RpgResource._spritesheets.clear();\n    RpgResource.engine.spritesheets.forEach((spritesheet, id) => {\n      // Extract image path from spritesheet\n      const imageLink = spritesheet?.image || spritesheet?.imageSource || undefined;\n      if (imageLink) {\n        RpgResource._spritesheets.set(String(id), imageLink);\n      }\n    });\n\n    // Sync sounds\n    RpgResource._sounds.clear();\n    RpgResource.engine.sounds.forEach((sound, id) => {\n      // Extract src path from sound\n      let soundLink: string | undefined;\n      \n      // If it's a Howler instance, try to get src from _src or src property\n      if (sound && typeof sound === 'object') {\n        if (sound._src && Array.isArray(sound._src) && sound._src.length > 0) {\n          soundLink = sound._src[0];\n        } else if (sound.src && typeof sound.src === 'string') {\n          soundLink = sound.src;\n        } else if (sound.src && Array.isArray(sound.src) && sound.src.length > 0) {\n          soundLink = sound.src[0];\n        }\n      }\n      \n      if (soundLink) {\n        RpgResource._sounds.set(id, soundLink);\n      }\n    });\n  }\n\n  /**\n   * Get/Set image links for spritesheets\n   * \n   * Map of spritesheet IDs to their image file paths/URLs.\n   * This Map is synchronized with the engine's spritesheet storage.\n   * \n   * @type {Map<string, string>}\n   * \n   * @example\n   * ```ts\n   * // Get an image link\n   * const imageLink = RpgResource.spritesheets.get('hero')\n   * \n   * // Set a new image link\n   * RpgResource.spritesheets.set('new-sprite', './assets/new-sprite.png')\n   * \n   * // Check if a spritesheet exists\n   * if (RpgResource.spritesheets.has('monster')) {\n   *   const link = RpgResource.spritesheets.get('monster')\n   * }\n   * ```\n   */\n  static get spritesheets(): Map<string, string> {\n    // Sync before returning to ensure we have the latest data\n    RpgResource.syncResources();\n    return RpgResource._spritesheets;\n  }\n\n  /**\n   * Get/Set sound file links\n   * \n   * Map of sound IDs to their audio file paths/URLs.\n   * This Map is synchronized with the engine's sound storage.\n   * \n   * @type {Map<string, string>}\n   * \n   * @example\n   * ```ts\n   * // Get a sound link\n   * const soundLink = RpgResource.sounds.get('town-music')\n   * \n   * // Set a new sound link\n   * RpgResource.sounds.set('new-sound', './assets/new-sound.ogg')\n   * \n   * // Iterate over all sounds\n   * RpgResource.sounds.forEach((link, id) => {\n   *   console.log(`Sound ${id}: ${link}`)\n   * })\n   * ```\n   */\n  static get sounds(): Map<string, string> {\n    // Sync before returning to ensure we have the latest data\n    RpgResource.syncResources();\n    return RpgResource._sounds;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,IAAa,cAAb,MAAa,YAAY;;gBACyB;;;uCACI,IAAI,IAAI;;;iCACd,IAAI,IAAI;;;;;;;;;;CAUtD,OAAO,KAAK,QAA+B;EACzC,YAAY,SAAS;EACrB,YAAY,cAAc;CAC5B;;;;;;;;;CAUA,OAAe,gBAAsB;EACnC,IAAI,CAAC,YAAY,QACf;EAIF,YAAY,cAAc,MAAM;EAChC,YAAY,OAAO,aAAa,SAAS,aAAa,OAAO;GAE3D,MAAM,YAAY,aAAa,SAAS,aAAa,eAAe,KAAA;GACpE,IAAI,WACF,YAAY,cAAc,IAAI,OAAO,EAAE,GAAG,SAAS;EAEvD,CAAC;EAGD,YAAY,QAAQ,MAAM;EAC1B,YAAY,OAAO,OAAO,SAAS,OAAO,OAAO;GAE/C,IAAI;GAGJ,IAAI,SAAS,OAAO,UAAU;QACxB,MAAM,QAAQ,MAAM,QAAQ,MAAM,IAAI,KAAK,MAAM,KAAK,SAAS,GACjE,YAAY,MAAM,KAAK;SAClB,IAAI,MAAM,OAAO,OAAO,MAAM,QAAQ,UAC3C,YAAY,MAAM;SACb,IAAI,MAAM,OAAO,MAAM,QAAQ,MAAM,GAAG,KAAK,MAAM,IAAI,SAAS,GACrE,YAAY,MAAM,IAAI;GAAA;GAI1B,IAAI,WACF,YAAY,QAAQ,IAAI,IAAI,SAAS;EAEzC,CAAC;CACH;;;;;;;;;;;;;;;;;;;;;;;CAwBA,WAAW,eAAoC;EAE7C,YAAY,cAAc;EAC1B,OAAO,YAAY;CACrB;;;;;;;;;;;;;;;;;;;;;;;CAwBA,WAAW,SAA8B;EAEvC,YAAY,cAAc;EAC1B,OAAO,YAAY;CACrB;AACF"}

package/dist/RpgClient.d.ts

@@ -1,8 +1,27 @@
-import { ComponentFunction } from 'canvasengine';
+import { ComponentFunction, Signal } from 'canvasengine';
 import { RpgClientEngine } from './RpgClientEngine';
 import { Loader, Container } from 'pixi.js';
-type RpgComponent = Container;
+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
@@ -72,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
@@ -86,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
      *
@@ -101,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.
      *
@@ -179,6 +229,37 @@ export interface RpgSceneMapHooks extends RpgSceneHooks<SceneMap> {
      * @memberof RpgSceneHooks
      */
     onMapLoading?: (scene: SceneMap, loader: Loader) => any;
+    /**
+     * Called when client physics has been initialized for the current map.
+     *
+     * Use this hook to initialize shared physics extensions based on map data
+     * (for example, tile-based collision rules used by client prediction).
+     *
+     * @prop { (scene: SceneMap, context: MapPhysicsInitContext) => any } [onPhysicsInit]
+     * @memberof RpgSceneMapHooks
+     */
+    onPhysicsInit?: (scene: SceneMap, context: MapPhysicsInitContext) => any;
+    /**
+     * Called when a character physics body is added to the map.
+     *
+     * @prop { (scene: SceneMap, context: MapPhysicsEntityContext) => any } [onPhysicsEntityAdd]
+     * @memberof RpgSceneMapHooks
+     */
+    onPhysicsEntityAdd?: (scene: SceneMap, context: MapPhysicsEntityContext) => any;
+    /**
+     * Called when a character physics body is removed from the map.
+     *
+     * @prop { (scene: SceneMap, context: MapPhysicsEntityContext) => any } [onPhysicsEntityRemove]
+     * @memberof RpgSceneMapHooks
+     */
+    onPhysicsEntityRemove?: (scene: SceneMap, context: MapPhysicsEntityContext) => any;
+    /**
+     * Called when the physics world is reset (e.g. before a map physics reload).
+     *
+     * @prop { (scene: SceneMap) => any } [onPhysicsReset]
+     * @memberof RpgSceneMapHooks
+     */
+    onPhysicsReset?: (scene: SceneMap) => any;
 }
 export interface RpgClient {
     /**
@@ -283,33 +364,207 @@ export interface RpgClient {
      * */
     spritesheets?: any[];
     /**
-     * Array containing the list of VueJS components
+     * Resolver function for dynamically creating spritesheets
+     *
+     * This function 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.
+     *
+     * ```ts
+     * import { defineModule, RpgClient } from '@rpgjs/client'
+     *
+     * defineModule<RpgClient>({
+     *      spritesheetResolver: (id: string) => {
+     *          // Synchronous resolver
+     *          if (id === 'dynamic-sprite') {
+     *              return {
+     *                  id: 'dynamic-sprite',
+     *                  image: 'path/to/image.png',
+     *                  framesWidth: 32,
+     *                  framesHeight: 32
+     *              };
+     *          }
+     *          return undefined;
+     *      }
+     * })
+     *
+     * // Or asynchronous resolver
+     * defineModule<RpgClient>({
+     *      spritesheetResolver: async (id: string) => {
+     *          const response = await fetch(`/api/spritesheets/${id}`);
+     *          const data = await response.json();
+     *          return data;
+     *      }
+     * })
+     * ```
+     *
+     * @prop {(id: string) => any | Promise<any>} [spritesheetResolver]
+     * @memberof RpgClient
+     * */
+    spritesheetResolver?: (id: string) => any | Promise<any>;
+    /**
+     * Resolver function for dynamically loading 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.
+     *
+     * ```ts
+     * import { defineModule, RpgClient } from '@rpgjs/client'
+     *
+     * defineModule<RpgClient>({
+     *     soundResolver: (id: string) => {
+     *         if (id === 'dynamic-sound') {
+     *             return { id: 'dynamic-sound', src: 'path/to/sound.mp3' };
+     *         }
+     *         return undefined;
+     *     }
+     * })
+     * ```
+     *
+     * @prop {(id: string) => any | Promise<any>} [soundResolver]
+     * @memberof RpgClient
+     * */
+    soundResolver?: (id: string) => any | Promise<any>;
+    /**
+     * Array containing the list of GUI components
+     *
+     * ```ts
+     * import { defineModule, RpgClient } from '@rpgjs/client'
+     * import InventoryComponent from './inventory.ce'
+     *
+     * defineModule<RpgClient>({
+     *      gui: [
+     *          {
+     *              id: 'inventory',
+     *              component: InventoryComponent,
+     *              autoDisplay: true,
+     *              dependencies: () => [playerSignal, inventorySignal]
+     *          }
+     *      ]
+     * })
+     * ```
      *
      * [Guide: Create GUI](/guide/create-gui.html)
      *
-     * @prop {Array<Component of CanvasEngine>} [gui]
+     * @prop {Array<GuiOptions>} [gui]
      * @memberof RpgClient
      * */
-    gui?: ComponentFunction[];
+    gui?: ({
+        id: string;
+        component: ComponentFunction;
+        /**
+         * Auto display the GUI when added to the system
+         * @default false
+         */
+        autoDisplay?: boolean;
+        /**
+         * Function that returns an array of Signal dependencies
+         * The GUI will only display when all dependencies are resolved (!= undefined)
+         */
+        dependencies?: () => Signal[];
+        /**
+         * Attach the GUI to sprites instead of displaying globally
+         *
+         * When set to `true`, the GUI component will be rendered directly on each sprite
+         * in the game world, rather than being displayed as a fixed overlay on the screen.
+         * This is useful for tooltips, health bars, name tags, or any UI element that
+         * should follow a specific sprite.
+         *
+         * The GUI will be rendered in the `character.ce` component for each sprite.
+         * You can control the display state of attached GUIs from the server side using
+         * `player.showAttachedGui()` and `player.hideAttachedGui()` methods.
+         *
+         * @default false
+         * @example
+         * ```ts
+         * import { defineModule, RpgClient } from '@rpgjs/client'
+         * import TooltipComponent from './tooltip.ce'
+         *
+         * defineModule<RpgClient>({
+         *     gui: [
+         *         {
+         *             id: "my-tooltip",
+         *             component: TooltipComponent,
+         *             attachToSprite: true
+         *         }
+         *     ]
+         * })
+         * ```
+         *
+         * On the server side, control the display:
+         * ```ts
+         * // Show the tooltip for this player
+         * player.showAttachedGui()
+         *
+         * // Hide the tooltip for this player
+         * player.hideAttachedGui()
+         *
+         * // Show tooltip for other players
+         * player.showAttachedGui([otherPlayer1, otherPlayer2])
+         * ```
+         */
+        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
-     * Each element is a simple object containing sound definitions
+     * Each element can be:
+     * - A simple object containing sound definitions
+     * - A class decorated with @Sound
      *
      * ```ts
-     * import { defineModule, RpgClient } from '@rpgjs/client'
+     * import { defineModule, RpgClient, Sound } from '@rpgjs/client'
      *
+     * // Using simple objects
      * defineModule<RpgClient>({
      *      sounds: [
      *          {
-     *              town: require('./assets/Town_Theme.ogg'),
-     *              battle: require('./assets/Battle_Theme.ogg')
+     *              id: 'typewriter',
+     *              src: 'typewriter.wav'
+     *          },
+     *          {
+     *              id: 'cursor',
+     *              src: 'cursor.wav'
      *          }
      *      ]
      * })
+     *
+     * // Using @Sound decorator
+     * @Sound({
+     *     id: 'town-music',
+     *     sound: require('./sound/town.ogg'),
+     *     loop: true,
+     *     volume: 0.5
+     * })
+     * export class TownMusic {}
+     *
+     * defineModule<RpgClient>({
+     *      sounds: [TownMusic]
+     * })
+     *
+     * // Multiple sounds in one class
+     * @Sound({
+     *     sounds: {
+     *         hero: require('./assets/hero.ogg'),
+     *         monster: require('./assets/monster.ogg')
+     *     },
+     *     loop: true
+     * })
+     * export class CharacterSounds {}
+     *
+     * defineModule<RpgClient>({
+     *      sounds: [CharacterSounds]
+     * })
      * ```
      *
-     * @prop {Array<Object>} [sounds]
+     * @prop {Array<Object | Class>} [sounds]
      * @memberof RpgClient
      * */
     sounds?: any[];
@@ -356,7 +611,34 @@ export interface RpgClient {
     scenes?: {
         map: RpgSceneMapHooks;
     };
-    effects?: {
+    sceneMap?: RpgSceneMapHooks;
+    /**
+     * Array containing the list of component animations
+     * Each element defines a temporary component to display for animations like hits, effects, etc.
+     *
+     * ```ts
+     * import { defineModule, RpgClient } from '@rpgjs/client'
+     * import HitComponent from './hit.ce'
+     * import ExplosionComponent from './explosion.ce'
+     *
+     * defineModule<RpgClient>({
+     *      componentAnimations: [
+     *          {
+     *              id: 'hit',
+     *              component: HitComponent
+     *          },
+     *          {
+     *              id: 'explosion',
+     *              component: ExplosionComponent
+     *          }
+     *      ]
+     * })
+     * ```
+     *
+     * @prop {Array<{id: string, component: ComponentFunction}>} [componentAnimations]
+     * @memberof RpgClient
+     * */
+    componentAnimations?: {
         id: string;
         component: ComponentFunction;
     }[];