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

package/src/Gui/NotificationManager.ts

@@ -0,0 +1,69 @@
+import { signal, animatedSignal } from "canvasengine";
+
+export type NotificationType = "info" | "warn" | "error";
+
+export interface NotificationPayload {
+  message: string;
+  type?: NotificationType;
+  icon?: string;
+  time?: number;
+  sound?: string;
+}
+
+export interface NotificationItem extends NotificationPayload {
+  id: number;
+  opacity: any;
+  offset: any;
+  layoutY: any;
+  removing: boolean;
+}
+
+const DEFAULT_DURATION = 220;
+
+export class NotificationManager {
+  stack = signal<NotificationItem[]>([]);
+  private _counter = 0;
+
+  add(payload: NotificationPayload, engine?: { playSound?: (id: string) => void }) {
+    const id = ++this._counter;
+    const opacity = animatedSignal(0, { duration: DEFAULT_DURATION });
+    const offset = animatedSignal(12, { duration: DEFAULT_DURATION });
+    const layoutY = animatedSignal(0, { duration: DEFAULT_DURATION });
+    const item: NotificationItem = {
+      id,
+      message: payload.message,
+      type: payload.type || "info",
+      icon: payload.icon,
+      time: payload.time,
+      sound: payload.sound,
+      opacity,
+      offset,
+      layoutY,
+      removing: false,
+    };
+    this.stack.update((list) => [...list, item]);
+    opacity.set(1);
+    offset.set(0);
+
+    if (payload.sound && engine?.playSound) {
+      engine.playSound(payload.sound);
+    }
+
+    const delay = typeof payload.time === "number" ? payload.time : 2000;
+    setTimeout(() => {
+      this.remove(id);
+    }, delay);
+  }
+
+  remove(id: number) {
+    const list = this.stack();
+    const item = list.find((it) => it.id === id);
+    if (!item || item.removing) return;
+    item.removing = true;
+    item.opacity.set(0);
+    item.offset.set(-8);
+    setTimeout(() => {
+      this.stack.update((items) => items.filter((it) => it.id !== id));
+    }, DEFAULT_DURATION);
+  }
+}

package/src/Resource.ts

@@ -0,0 +1,149 @@
+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 class RpgResource {
+  private static engine: RpgClientEngine | null = null;
+  private static _spritesheets: Map<string, string> = new Map();
+  private static _sounds: Map<string, string> = 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: RpgClientEngine): void {
+    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
+   */
+  private static syncResources(): void {
+    if (!RpgResource.engine) {
+      return;
+    }
+
+    // Sync spritesheets
+    RpgResource._spritesheets.clear();
+    RpgResource.engine.spritesheets.forEach((spritesheet, id) => {
+      // Extract image path from spritesheet
+      const imageLink = spritesheet?.image || spritesheet?.imageSource || undefined;
+      if (imageLink) {
+        RpgResource._spritesheets.set(String(id), imageLink);
+      }
+    });
+
+    // Sync sounds
+    RpgResource._sounds.clear();
+    RpgResource.engine.sounds.forEach((sound, id) => {
+      // Extract src path from sound
+      let soundLink: string | undefined;
+      
+      // If it's a Howler instance, try to get src from _src or src property
+      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(): Map<string, string> {
+    // Sync before returning to ensure we have the latest data
+    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(): Map<string, string> {
+    // Sync before returning to ensure we have the latest data
+    RpgResource.syncResources();
+    return RpgResource._sounds;
+  }
+}

package/src/RpgClient.ts

@@ -1,10 +1,30 @@
-import { ComponentFunction } from 'canvasengine'
+import { ComponentFunction, Signal } from 'canvasengine'
 import { RpgClientEngine } from './RpgClientEngine'
 import { Loader, Container } from 'pixi.js'
+import { RpgClientObject } from './Game/Object'
+import { type MapPhysicsEntityContext, type MapPhysicsInitContext } from '@rpgjs/common'
 
 type RpgClass<T = any> = new (...args: any[]) => T
-type RpgComponent = Container
+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 {
     /**
@@ -79,7 +99,7 @@ export interface RpgSpriteHooks {
      * }
      * ```
      */
-    componentsBehind?: ComponentFunction[]
+    componentsBehind?: SpriteComponentConfig[]
     
     /**
      * Array of components to render in front of the sprite
@@ -94,7 +114,28 @@ 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
@@ -112,6 +153,21 @@ export interface 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.
      * 
@@ -196,6 +252,41 @@ 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 {
@@ -305,34 +396,210 @@ 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[],
@@ -382,8 +649,36 @@ export interface RpgClient {
         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
     }[]
-}
+}