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

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/ItemManager.d.ts

@@ -1,4 +1,144 @@
 import { PlayerCtor } from '@rpgjs/common';
+import { RpgPlayer } from './Player';
+/**
+ * Interface defining the hooks that can be implemented on item classes or objects
+ *
+ * These hooks are called at specific moments during the item lifecycle:
+ * - `onAdd`: When the item is added to the player's inventory
+ * - `onUse`: When the item is successfully used
+ * - `onUseFailed`: When the item usage fails (e.g., chance roll failed)
+ * - `onRemove`: When the item is removed from the inventory
+ * - `onEquip`: When the item is equipped or unequipped
+ *
+ * @example
+ * ```ts
+ * const itemHooks: ItemHooks = {
+ *   onAdd(player) {
+ *     console.log('Item added to inventory');
+ *   },
+ *   onUse(player) {
+ *     player.hp += 100;
+ *   }
+ * };
+ * ```
+ */
+export interface ItemHooks {
+    /**
+     * Called when the item is added to the player's inventory
+     *
+     * @param player - The player receiving the item
+     */
+    onAdd?: (player: RpgPlayer) => void | Promise<void>;
+    /**
+     * Called when the item is successfully used
+     *
+     * @param player - The player using the item
+     */
+    onUse?: (player: RpgPlayer) => void | Promise<void>;
+    /**
+     * Called when the item usage fails (e.g., chance roll failed)
+     *
+     * @param player - The player attempting to use the item
+     */
+    onUseFailed?: (player: RpgPlayer) => void | Promise<void>;
+    /**
+     * Called when the item is removed from the inventory
+     *
+     * @param player - The player losing the item
+     */
+    onRemove?: (player: RpgPlayer) => void | Promise<void>;
+    /**
+     * Called when the item is equipped or unequipped
+     *
+     * @param player - The player equipping/unequipping the item
+     * @param equip - true if equipping, false if unequipping
+     */
+    onEquip?: (player: RpgPlayer, equip: boolean) => void | Promise<void>;
+}
+/**
+ * Base properties that can be included in an item object
+ *
+ * This interface defines the common properties that items can have.
+ * Use this as a base and extend it with specific item types.
+ *
+ * @template T - Additional properties specific to the item type
+ *
+ * @example
+ * ```ts
+ * interface PotionData extends ItemData {
+ *   hpValue: number;
+ *   mpValue: number;
+ * }
+ *
+ * const potion: ItemObject<PotionData> = {
+ *   name: 'Health Potion',
+ *   description: 'Restores 100 HP',
+ *   price: 200,
+ *   hpValue: 100,
+ *   mpValue: 0,
+ *   onUse(player) {
+ *     player.hp += this.hpValue;
+ *   }
+ * };
+ * ```
+ */
+export interface ItemData {
+    /** Item name */
+    name?: string;
+    /** Item description */
+    description?: string;
+    /** Item price */
+    price?: number;
+    /** HP value restored when used */
+    hpValue?: number;
+    /** MP/SP value restored when used */
+    mpValue?: number;
+    /** Chance to successfully use the item (0-1) */
+    hitRate?: number;
+    /** Whether the item is consumable */
+    consumable?: boolean;
+    /** States to add when used */
+    addStates?: any[];
+    /** States to remove when used */
+    removeStates?: any[];
+    /** Elemental properties */
+    elements?: any[];
+    /** Parameter modifiers */
+    paramsModifier?: Record<string, any>;
+    /** Item type (for equipment validation) */
+    _type?: 'item' | 'weapon' | 'armor';
+}
+/**
+ * Item object type that combines data properties with hooks
+ *
+ * This type allows you to create item objects directly without needing a class.
+ * The object can contain both item data properties and lifecycle hooks.
+ *
+ * @template T - Additional properties specific to the item type (extends ItemData)
+ *
+ * @example
+ * ```ts
+ * const potion: ItemObject = {
+ *   name: 'Health Potion',
+ *   description: 'Restores 100 HP',
+ *   price: 200,
+ *   hpValue: 100,
+ *   consumable: true,
+ *   onAdd(player) {
+ *     console.log('Potion added!');
+ *   },
+ *   onUse(player) {
+ *     player.hp += 100;
+ *   }
+ * };
+ *
+ * player.addItem(potion);
+ * ```
+ */
+export type ItemObject<T extends ItemData = ItemData> = T & ItemHooks & {
+    /** Item identifier (required if not using class or string) */
+    id?: string;
+};
 /**
  * Item Manager Mixin
  *