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

package/dist/RpgClient.d.ts

@@ -1,7 +1,9 @@
-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 interface RpgClientEngineHooks {
     /**
@@ -179,6 +181,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 +316,200 @@ 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;
+    } | 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 +556,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;
     }[];