@rpgjs/server 5.0.0-alpha.17 → 5.0.0-alpha.18

package/dist/Player/ComponentManager.d.ts

@@ -1,10 +1,15 @@
-import { PlayerCtor } from '@rpgjs/common';
+import { Constructor, RpgCommonPlayer } from '@rpgjs/common';
+import { ComponentInput, ComponentLayout } from './Components';
+type ComponentPosition = 'top' | 'center' | 'bottom' | 'left' | 'right';
 /**
  * Component Manager Mixin
  *
- * Provides graphic management capabilities to any class. This mixin allows
+ * Provides graphic and component management capabilities to any class. This mixin allows
  * setting single or multiple graphics for player representation, enabling
- * dynamic visual changes and animation sequences.
+ * dynamic visual changes and animation sequences. It also provides methods to
+ * display UI components around the player graphic (top, bottom, center, left, right).
+ *
+ * Components are stored as JSON strings for efficient synchronization.
  *
  * @param Base - The base class to extend with component management
  * @returns Extended class with component management methods
@@ -20,41 +25,99 @@ import { PlayerCtor } from '@rpgjs/common';
  *
  * const player = new MyPlayer();
  * player.setGraphic(["hero_idle", "hero_walk"]);
+ * player.setComponentsTop(Components.text('{name}'));
  * ```
  */
-export declare function WithComponentManager<TBase extends PlayerCtor>(Base: TBase): new (...args: ConstructorParameters<TBase>) => InstanceType<TBase> & IComponentManager;
+export declare function WithComponentManager<TBase extends Constructor<RpgCommonPlayer>>(Base: TBase): new (...args: ConstructorParameters<TBase>) => InstanceType<TBase> & IComponentManager;
 /**
  * Interface for component management capabilities
- * Defines the method signature that will be available on the player
+ * Defines the method signatures that will be available on the player
  */
 export interface IComponentManager {
     /**
-       * Set the graphic(s) for this player
-       *
-       * Allows setting either a single graphic or multiple graphics for the player.
-       * When multiple graphics are provided, they are used for animation sequences.
-       * The graphics system provides flexible visual representation that can be
-       * dynamically changed during gameplay for different states, equipment, or animations.
-       *
-       * @param graphic - Single graphic name or array of graphic names for animation sequences
-       * @returns void
-       *
-       * @example
-       * ```ts
-       * // Set a single graphic for static representation
-       * player.setGraphic("hero");
-       *
-       * // Set multiple graphics for animation sequences
-       * player.setGraphic(["hero_idle", "hero_walk", "hero_run"]);
-       *
-       * // Dynamic graphic changes based on equipment
-       * if (player.hasArmor('platemail')) {
-       *   player.setGraphic("hero_armored");
-       * }
-       *
-       * // Animation sequences for different actions
-       * player.setGraphic(["mage_cast_1", "mage_cast_2", "mage_cast_3"]);
-       * ```
-       */
+     * Set the graphic(s) for this player
+     *
+     * Allows setting either a single graphic or multiple graphics for the player.
+     * When multiple graphics are provided, they are used for animation sequences.
+     * The graphics system provides flexible visual representation that can be
+     * dynamically changed during gameplay for different states, equipment, or animations.
+     *
+     * @param graphic - Single graphic name or array of graphic names for animation sequences
+     * @returns void
+     *
+     * @example
+     * ```ts
+     * // Set a single graphic for static representation
+     * player.setGraphic("hero");
+     *
+     * // Set multiple graphics for animation sequences
+     * player.setGraphic(["hero_idle", "hero_walk", "hero_run"]);
+     *
+     * // Dynamic graphic changes based on equipment
+     * if (player.hasArmor('platemail')) {
+     *   player.setGraphic("hero_armored");
+     * }
+     *
+     * // Animation sequences for different actions
+     * player.setGraphic(["mage_cast_1", "mage_cast_2", "mage_cast_3"]);
+     * ```
+     */
     setGraphic(graphic: string | string[]): void;
+    /**
+     * Set components to display above the player graphic
+     *
+     * @param layout - Component(s) to display, can be single, array, or 2D array
+     * @param options - Optional layout options for positioning and sizing
+     * @returns void
+     */
+    setComponentsTop(layout: ComponentInput, options?: ComponentLayout): void;
+    /**
+     * Set components to display below the player graphic
+     *
+     * @param layout - Component(s) to display, can be single, array, or 2D array
+     * @param options - Optional layout options for positioning and sizing
+     * @returns void
+     */
+    setComponentsBottom(layout: ComponentInput, options?: ComponentLayout): void;
+    /**
+     * Set components to display at the center of the player graphic
+     *
+     * @param layout - Component(s) to display, can be single, array, or 2D array
+     * @param options - Optional layout options for positioning and sizing
+     * @returns void
+     */
+    setComponentsCenter(layout: ComponentInput, options?: ComponentLayout): void;
+    /**
+     * Set components to display to the left of the player graphic
+     *
+     * @param layout - Component(s) to display, can be single, array, or 2D array
+     * @param options - Optional layout options for positioning and sizing
+     * @returns void
+     */
+    setComponentsLeft(layout: ComponentInput, options?: ComponentLayout): void;
+    /**
+     * Set components to display to the right of the player graphic
+     *
+     * @param layout - Component(s) to display, can be single, array, or 2D array
+     * @param options - Optional layout options for positioning and sizing
+     * @returns void
+     */
+    setComponentsRight(layout: ComponentInput, options?: ComponentLayout): void;
+    /**
+     * Remove components from a specific position
+     *
+     * @param position - Position of the components: 'top', 'center', 'bottom', 'left', or 'right'
+     * @returns void
+     */
+    removeComponents(position: ComponentPosition): void;
+    /**
+     * Merge components with existing components at a specific position
+     *
+     * @param position - Position of the components: 'top', 'center', 'bottom', 'left', or 'right'
+     * @param layout - Component(s) to merge, can be single, array, or 2D array
+     * @param options - Optional layout options for positioning and sizing
+     * @returns void
+     */
+    mergeComponents(position: ComponentPosition, layout: ComponentInput, options?: ComponentLayout): void;
 }
+export {};

package/dist/Player/Components.d.ts

@@ -0,0 +1,345 @@
+/**
+ * Component definitions for player UI elements
+ *
+ * This module provides factory functions to create component definitions
+ * that can be displayed above or below player graphics. Components are
+ * synchronized from server to client and rendered using CanvasEngine.
+ *
+ * ## Design
+ *
+ * Components are defined as data structures that describe UI elements
+ * (text, bars, shapes) with their properties and layout options. The
+ * server creates these definitions and they are automatically synchronized
+ * to all clients on the map.
+ *
+ * @example
+ * ```ts
+ * import { Components } from '@rpgjs/server';
+ *
+ * // Create a text component
+ * const nameComponent = Components.text('{name}');
+ *
+ * // Create an HP bar
+ * const hpBar = Components.hpBar();
+ *
+ * // Set components on player
+ * player.setComponentsTop([nameComponent, hpBar]);
+ * ```
+ */
+export interface ComponentLayout {
+    /** Width of the component block in pixels */
+    width?: number;
+    /** Height of the component block in pixels */
+    height?: number;
+    /** Margin from the top of the player in pixels */
+    marginTop?: number;
+    /** Margin from the bottom of the player in pixels */
+    marginBottom?: number;
+    /** Margin from the left of the player in pixels */
+    marginLeft?: number;
+    /** Margin from the right of the player in pixels */
+    marginRight?: number;
+}
+export interface TextComponentOptions {
+    /** Text color in hexadecimal format (e.g., '#000000') */
+    fill?: string;
+    /** Font size in pixels */
+    fontSize?: number;
+    /** Font family */
+    fontFamily?: string;
+    /** Font style: 'normal', 'italic', 'oblique' */
+    fontStyle?: 'normal' | 'italic' | 'oblique';
+    /** Font weight: 'normal', 'bold', 'bolder', 'lighter', or numeric values */
+    fontWeight?: 'normal' | 'bold' | 'bolder' | 'lighter' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900' | number;
+    /** Stroke color in hexadecimal format */
+    stroke?: string;
+    /** Opacity between 0 and 1 */
+    opacity?: number;
+    /** Word wrap */
+    wordWrap?: boolean;
+    /** Text alignment */
+    align?: 'left' | 'center' | 'right' | 'justify';
+}
+export interface BarComponentOptions {
+    /** Background color in hexadecimal format */
+    bgColor?: string;
+    /** Fill color in hexadecimal format */
+    fillColor?: string;
+    /** Border color in hexadecimal format */
+    borderColor?: string;
+    /** Border width */
+    borderWidth?: number;
+    /** Height of the bar in pixels */
+    height?: number;
+    /** Width of the bar in pixels */
+    width?: number;
+    /** Border radius */
+    borderRadius?: number;
+    /** Opacity between 0 and 1 */
+    opacity?: number;
+}
+export interface ShapeComponentOptions {
+    /** Fill color in hexadecimal format */
+    fill: string;
+    /** Type of shape */
+    type: 'circle' | 'rectangle' | 'ellipse' | 'polygon' | 'line' | 'rounded-rectangle';
+    /** Radius (for circle) */
+    radius?: number | string;
+    /** Width (for rectangle, ellipse) */
+    width?: number | string;
+    /** Height (for rectangle, ellipse) */
+    height?: number | string;
+    /** X1 position (for line) */
+    x1?: number | string;
+    /** Y1 position (for line) */
+    y1?: number | string;
+    /** X2 position (for line) */
+    x2?: number | string;
+    /** Y2 position (for line) */
+    y2?: number | string;
+    /** Points array (for polygon) */
+    points?: number[];
+    /** Opacity between 0 and 1 */
+    opacity?: number | string;
+    /** Line/border style */
+    line?: {
+        color?: string;
+        width?: number;
+        alpha?: number;
+    };
+}
+export type ComponentDefinition = {
+    type: 'text';
+    value: string;
+    style?: TextComponentOptions;
+} | {
+    type: 'hpBar';
+    style?: BarComponentOptions;
+    text?: string | null;
+} | {
+    type: 'spBar';
+    style?: BarComponentOptions;
+    text?: string | null;
+} | {
+    type: 'bar';
+    current: string;
+    max: string;
+    style?: BarComponentOptions;
+    text?: string | null;
+} | {
+    type: 'shape';
+    value: ShapeComponentOptions;
+} | {
+    type: 'image';
+    value: string;
+} | {
+    type: 'tile';
+    value: number | string;
+};
+export type ComponentInput = ComponentDefinition | ComponentDefinition[] | ComponentDefinition[][];
+/**
+ * Components factory for creating component definitions
+ *
+ * Provides factory methods to create various UI components that can be
+ * displayed above or below player graphics. Components support template
+ * strings with placeholders like {name}, {hp}, etc. that are replaced
+ * with actual player property values on the client.
+ *
+ * @example
+ * ```ts
+ * // Create a text component
+ * Components.text('Player: {name}');
+ *
+ * // Create an HP bar with custom text
+ * Components.hpBar({}, '{$percent}%');
+ *
+ * // Create a custom bar
+ * Components.bar('wood', 'param.maxWood');
+ * ```
+ */
+export declare const Components: {
+    /**
+     * Create a text component
+     *
+     * Creates a text component that displays text with optional styling.
+     * Supports template strings with placeholders like {name}, {hp}, etc.
+     * that are replaced with actual player property values.
+     *
+     * ## Design
+     *
+     * Text components use template strings to allow dynamic content without
+     * resending the entire component structure when values change. Only the
+     * property values are synchronized, reducing bandwidth usage.
+     *
+     * @param text - Text to display, can include placeholders like {name}, {hp}
+     * @param options - Text styling options
+     * @returns Component definition for text
+     *
+     * @example
+     * ```ts
+     * // Simple text
+     * Components.text('Player Name');
+     *
+     * // Text with placeholder
+     * Components.text('{name}');
+     *
+     * // Text with styling
+     * Components.text('{name}', {
+     *   fill: '#000000',
+     *   fontSize: 20
+     * });
+     * ```
+     */
+    text(value: string, style?: TextComponentOptions): ComponentDefinition;
+    /**
+     * Create an HP bar component
+     *
+     * Creates a health point bar that automatically displays the player's
+     * current HP relative to their maximum HP. The bar updates automatically
+     * as HP changes.
+     *
+     * ## Design
+     *
+     * HP bars read from the player's hp and param.maxHp properties. The
+     * bar can optionally display text above it showing current, max, or
+     * percentage values.
+     *
+     * @param options - Bar styling options
+     * @param text - Optional text to display above the bar. Can use placeholders:
+     *   - {$current} - Current HP value
+     *   - {$max} - Maximum HP value
+     *   - {$percent} - Percentage value
+     *   Set to null to hide text
+     * @returns Component definition for HP bar
+     *
+     * @example
+     * ```ts
+     * // Simple HP bar
+     * Components.hpBar();
+     *
+     * // HP bar with percentage text
+     * Components.hpBar({}, '{$percent}%');
+     *
+     * // HP bar with custom styling
+     * Components.hpBar({
+     *   fillColor: '#ff0000',
+     *   height: 8
+     * });
+     * ```
+     */
+    hpBar(style?: BarComponentOptions, text?: string | null): ComponentDefinition;
+    /**
+     * Create an SP bar component
+     *
+     * Creates a skill point bar that automatically displays the player's
+     * current SP relative to their maximum SP. The bar updates automatically
+     * as SP changes.
+     *
+     * @param style - Bar styling options
+     * @param text - Optional text to display above the bar. Can use placeholders:
+     *   - {$current} - Current SP value
+     *   - {$max} - Maximum SP value
+     *   - {$percent} - Percentage value
+     *   Set to null to hide text
+     * @returns Component definition for SP bar
+     *
+     * @example
+     * ```ts
+     * // Simple SP bar
+     * Components.spBar();
+     *
+     * // SP bar with text
+     * Components.spBar({}, 'SP: {$current}/{$max}');
+     * ```
+     */
+    spBar(style?: BarComponentOptions, text?: string | null): ComponentDefinition;
+    /**
+     * Create a custom bar component
+     *
+     * Creates a bar that displays a custom property value relative to a maximum.
+     * Useful for displaying custom resources like wood, mana, energy, etc.
+     *
+     * @param current - Property path for current value (e.g., 'wood', 'mana')
+     * @param max - Property path for maximum value (e.g., 'param.maxWood', 'param.maxMana')
+     * @param style - Bar styling options
+     * @param text - Optional text to display above the bar. Can use placeholders:
+     *   - {$current} - Current value
+     *   - {$max} - Maximum value
+     *   - {$percent} - Percentage value
+     *   Set to null to hide text
+     * @returns Component definition for custom bar
+     *
+     * @example
+     * ```ts
+     * // Bar for custom property
+     * Components.bar('wood', 'param.maxWood');
+     *
+     * // Bar with text
+     * Components.bar('mana', 'param.maxMana', {}, 'Mana: {$current}/{$max}');
+     * ```
+     */
+    bar(current: string, max: string, style?: BarComponentOptions, text?: string | null): ComponentDefinition;
+    /**
+     * Create a shape component
+     *
+     * Creates a geometric shape that can be displayed above or below the player.
+     * Useful for visual indicators, backgrounds, or decorative elements.
+     *
+     * @param value - Shape configuration options
+     * @returns Component definition for shape
+     *
+     * @example
+     * ```ts
+     * // Circle shape
+     * Components.shape({
+     *   fill: '#ffffff',
+     *   type: 'circle',
+     *   radius: 10
+     * });
+     *
+     * // Rectangle shape
+     * Components.shape({
+     *   fill: '#ff0000',
+     *   type: 'rectangle',
+     *   width: 32,
+     *   height: 32
+     * });
+     *
+     * // Using parameters
+     * Components.shape({
+     *   fill: '#ffffff',
+     *   type: 'circle',
+     *   radius: 'hp' // radius will be the same as hp value
+     * });
+     * ```
+     */
+    shape(value: ShapeComponentOptions): ComponentDefinition;
+    /**
+     * Create an image component
+     *
+     * Displays an image from a URL or spritesheet identifier.
+     *
+     * @param value - Image source URL or spritesheet identifier
+     * @returns Component definition for image
+     *
+     * @example
+     * ```ts
+     * Components.image('mygraphic.png');
+     * ```
+     */
+    image(value: string): ComponentDefinition;
+    /**
+     * Create a tile component
+     *
+     * Displays a tile from a tileset by ID.
+     *
+     * @param value - Tile ID in the tileset
+     * @returns Component definition for tile
+     *
+     * @example
+     * ```ts
+     * Components.tile(3); // Use tile #3
+     * ```
+     */
+    tile(value: number | string): ComponentDefinition;
+};

package/dist/Player/Player.d.ts

@@ -1,4 +1,4 @@
-import { Hooks, RpgCommonPlayer, Direction } from '@rpgjs/common';
+import { Hooks, RpgCommonPlayer, Constructor, Direction, AttachShapeOptions, RpgShape } from '@rpgjs/common';
 import { IComponentManager } from './ComponentManager';
 import { RpgMap } from '../rooms/map';
 import { Context } from '@signe/di';
@@ -15,16 +15,7 @@ import { ISkillManager } from './SkillManager';
 import { IBattleManager } from './BattleManager';
 import { IClassManager } from './ClassManager';
 import { IStateManager } from './StateManager';
-interface ZoneOptions {
-    x?: number;
-    y?: number;
-    radius: number;
-    angle?: number;
-    direction?: any;
-    linkedTo?: string;
-    limitedByWalls?: boolean;
-}
-declare const RpgPlayer_base: typeof RpgCommonPlayer;
+declare const RpgPlayer_base: Constructor<RpgCommonPlayer>;
 /**
  * RPG Player class with component management capabilities
  *
@@ -49,6 +40,10 @@ export declare class RpgPlayer extends RpgPlayer_base {
     context?: Context;
     conn: MockConnection | null;
     touchSide: boolean;
+    /** Internal: Shapes attached to this player */
+    private _attachedShapes;
+    /** Internal: Shapes where this player is currently located */
+    private _inShapes;
     /** Last processed client input timestamp for reconciliation */
     lastProcessedInputTs: number;
     /** Last processed client input frame for reconciliation with server tick */
@@ -162,7 +157,79 @@ export declare class RpgPlayer extends RpgPlayer_base {
     syncChanges(): void;
     databaseById(id: string): any;
     private _eventChanges;
-    attachShape(id: string, options: ZoneOptions): void;
+    /**
+     * Attach a zone shape to this player using the physic zone system
+     *
+     * This method creates a zone attached to the player's entity in the physics engine.
+     * The zone can be circular or cone-shaped and will detect other entities (players/events)
+     * entering or exiting the zone.
+     *
+     * @param id - Optional zone identifier. If not provided, a unique ID will be generated
+     * @param options - Zone configuration options
+     *
+     * @example
+     * ```ts
+     * // Create a circular detection zone
+     * player.attachShape("vision", {
+     *   radius: 150,
+     *   angle: 360,
+     * });
+     *
+     * // Create a cone-shaped vision zone
+     * player.attachShape("vision", {
+     *   radius: 200,
+     *   angle: 120,
+     *   direction: Direction.Right,
+     *   limitedByWalls: true,
+     * });
+     *
+     * // Create a zone with width/height (radius calculated automatically)
+     * player.attachShape({
+     *   width: 100,
+     *   height: 100,
+     *   positioning: "center",
+     * });
+     * ```
+     */
+    attachShape(idOrOptions: string | AttachShapeOptions, options?: AttachShapeOptions): RpgShape | undefined;
+    /**
+     * Get all shapes attached to this player
+     *
+     * Returns all shapes that were created using `attachShape()` on this player.
+     *
+     * @returns Array of RpgShape instances attached to this player
+     *
+     * @example
+     * ```ts
+     * player.attachShape("vision", { radius: 150 });
+     * player.attachShape("detection", { radius: 100 });
+     *
+     * const shapes = player.getShapes();
+     * console.log(shapes.length); // 2
+     * ```
+     */
+    getShapes(): RpgShape[];
+    /**
+     * Get all shapes where this player is currently located
+     *
+     * Returns all shapes (from any player/event) where this player is currently inside.
+     * This is updated automatically when the player enters or exits shapes.
+     *
+     * @returns Array of RpgShape instances where this player is located
+     *
+     * @example
+     * ```ts
+     * // Another player has a detection zone
+     * otherPlayer.attachShape("detection", { radius: 200 });
+     *
+     * // Check if this player is in any shape
+     * const inShapes = player.getInShapes();
+     * if (inShapes.length > 0) {
+     *   console.log("Player is being detected!");
+     * }
+     * ```
+     */
+    getInShapes(): RpgShape[];
     /**
      * Show a temporary component animation on this player
      *
@@ -189,6 +256,60 @@ export declare class RpgPlayer extends RpgPlayer_base {
      */
     showComponentAnimation(id: string, params?: any): void;
     showHit(text: string): void;
+    /**
+     * Play a sound on the client side for this player only
+     *
+     * This method emits an event to play a sound only for this specific player.
+     * The sound must be defined on the client side (in the client module configuration).
+     *
+     * ## Design
+     *
+     * The sound is sent only to this player's client connection, making it ideal
+     * for personal feedback sounds like UI interactions, notifications, or personal
+     * achievements. For map-wide sounds that all players should hear, use `map.playSound()` instead.
+     *
+     * @param soundId - Sound identifier, defined on the client side
+     * @param options - Optional sound configuration
+     * @param options.volume - Volume level (0.0 to 1.0, default: 1.0)
+     * @param options.loop - Whether the sound should loop (default: false)
+     *
+     * @example
+     * ```ts
+     * // Play a sound for this player only (default behavior)
+     * player.playSound("item-pickup");
+     *
+     * // Play a sound with volume and loop
+     * player.playSound("background-music", {
+     *   volume: 0.5,
+     *   loop: true
+     * });
+     *
+     * // Play a notification sound at low volume
+     * player.playSound("notification", { volume: 0.3 });
+     * ```
+     */
+    playSound(soundId: string, options?: {
+        volume?: number;
+        loop?: boolean;
+    }): void;
+    /**
+     * Stop a sound that is currently playing for this player
+     *
+     * This method stops a sound that was previously started with `playSound()`.
+     * The sound must be defined on the client side.
+     *
+     * @param soundId - Sound identifier to stop
+     *
+     * @example
+     * ```ts
+     * // Start a looping background music
+     * player.playSound("background-music", { loop: true });
+     *
+     * // Later, stop it
+     * player.stopSound("background-music");
+     * ```
+     */
+    stopSound(soundId: string): void;
     /**
      * Set the sync schema for the map
      * @param schema - The schema to set

package/dist/index.d.ts

@@ -4,8 +4,10 @@ export * from './RpgServer';
 export * from './core/setup';
 export * from './core/inject';
 export * from './Player/Player';
+export * from './Player/Components';
 export * from './module';
 export * from './rooms/map';
 export * from './presets';
 export * from '@signe/reactive';
 export * from './Gui';
+export { RpgShape } from '@rpgjs/common';