@rpgjs/server 5.0.0-alpha.2 → 5.0.0-alpha.20

package/dist/Gui/DialogGui.d.ts

@@ -17,6 +17,10 @@ export interface DialogOptions {
     tranparent?: boolean;
     typewriterEffect?: boolean;
     talkWith?: RpgPlayer;
+    face?: {
+        id: string;
+        expression: string;
+    };
 }
 export declare class DialogGui extends Gui {
     constructor(player: RpgPlayer);

package/dist/Gui/index.d.ts

@@ -4,3 +4,4 @@ import { MenuGui } from './MenuGui';
 import { ShopGui } from './ShopGui';
 import { NotificationGui } from './NotificationGui';
 export { Gui, DialogGui, MenuGui, ShopGui, NotificationGui };
+export { DialogPosition } from './DialogGui';

package/dist/Player/BattleManager.d.ts

@@ -1,22 +1,32 @@
-import { Constructor, RpgCommonPlayer } from '@rpgjs/common';
-import { RpgPlayer } from './Player';
-interface PlayerWithMixins extends RpgCommonPlayer {
-    parameters: any[];
-    getFormulas(name: string): any;
-    hasEffect(effect: string): boolean;
-    coefficientElements(attackerPlayer: RpgPlayer): number;
-    hp: number;
-    getFormulas(name: string): any;
-    hasEffect(effect: string): boolean;
-}
-export interface IBattleManager {
-    applyDamage(attackerPlayer: RpgPlayer, skill?: any): {
-        damage: number;
-        critical: boolean;
-        elementVulnerable: boolean;
-        guard: boolean;
-        superGuard: boolean;
-    };
-}
-export declare function WithBattleManager<TBase extends Constructor<PlayerWithMixins>>(Base: TBase): Constructor<IBattleManager> & TBase;
-export {};
+import { PlayerCtor } from '@rpgjs/common';
+/**
+ * Battle Manager Mixin
+ *
+ * Provides battle management capabilities to any class. This mixin handles
+ * damage calculation, critical hits, elemental vulnerabilities, and guard effects.
+ * It implements a comprehensive battle system with customizable formulas and effects.
+ *
+ * @param Base - The base class to extend with battle management
+ * @returns Extended class with battle management methods
+ *
+ * @example
+ * ```ts
+ * class MyPlayer extends WithBattleManager(BasePlayer) {
+ *   constructor() {
+ *     super();
+ *     // Battle system is automatically initialized
+ *   }
+ * }
+ *
+ * const player = new MyPlayer();
+ * const attacker = new MyPlayer();
+ * const result = player.applyDamage(attacker);
+ * console.log(`Damage dealt: ${result.damage}`);
+ * ```
+ */
+export declare function WithBattleManager<TBase extends PlayerCtor>(Base: TBase): TBase;
+/**
+ * Type helper to extract the interface from the WithBattleManager mixin
+ * This provides the type without duplicating method signatures
+ */
+export type IBattleManager = InstanceType<ReturnType<typeof WithBattleManager>>;

package/dist/Player/ClassManager.d.ts

@@ -1,18 +1,31 @@
-import { Constructor, RpgCommonPlayer } from '@rpgjs/common';
-type ClassClass = any;
-type ActorClass = any;
-interface PlayerWithMixins extends RpgCommonPlayer {
-    databaseById(id: string): any;
-    addParameter(name: string, { start, end }: {
-        start: number;
-        end: number;
-    }): void;
-    addItem(item: any): void;
-    equip(item: any, equip: boolean): void;
-}
-export interface IClassManager {
-    setClass(_class: ClassClass | string): ClassClass;
-    setActor(actorClass: ActorClass | string): ActorClass;
-}
-export declare function WithClassManager<TBase extends Constructor<PlayerWithMixins>>(Base: TBase): Constructor<IClassManager> & TBase;
-export {};
+import { PlayerCtor } from '@rpgjs/common';
+/**
+ * Class Manager Mixin
+ *
+ * Provides class and actor management capabilities to any class. This mixin handles
+ * character class assignment and actor setup, including automatic parameter configuration,
+ * starting equipment, and skill progression based on class definitions.
+ *
+ * @param Base - The base class to extend with class management
+ * @returns Extended class with class management methods
+ *
+ * @example
+ * ```ts
+ * class MyPlayer extends WithClassManager(BasePlayer) {
+ *   constructor() {
+ *     super();
+ *     // Class system is automatically initialized
+ *   }
+ * }
+ *
+ * const player = new MyPlayer();
+ * player.setClass(Fighter);
+ * player.setActor(Hero);
+ * ```
+ */
+export declare function WithClassManager<TBase extends PlayerCtor>(Base: TBase): TBase;
+/**
+ * Type helper to extract the interface from the WithClassManager mixin
+ * This provides the type without duplicating method signatures
+ */
+export type IClassManager = InstanceType<ReturnType<typeof WithClassManager>>;

package/dist/Player/ComponentManager.d.ts

@@ -0,0 +1,123 @@
+import { Constructor, RpgCommonPlayer } from '@rpgjs/common';
+import { ComponentInput, ComponentLayout } from './Components';
+type ComponentPosition = 'top' | 'center' | 'bottom' | 'left' | 'right';
+/**
+ * Component Manager Mixin
+ *
+ * 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. 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
+ *
+ * @example
+ * ```ts
+ * class MyPlayer extends WithComponentManager(BasePlayer) {
+ *   constructor() {
+ *     super();
+ *     this.setGraphic("hero");
+ *   }
+ * }
+ *
+ * const player = new MyPlayer();
+ * player.setGraphic(["hero_idle", "hero_walk"]);
+ * player.setComponentsTop(Components.text('{name}'));
+ * ```
+ */
+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 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"]);
+     * ```
+     */
+    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/EffectManager.d.ts

@@ -0,0 +1,40 @@
+import { PlayerCtor } from '@rpgjs/common';
+export declare enum Effect {
+    CAN_NOT_SKILL = "CAN_NOT_SKILL",
+    CAN_NOT_ITEM = "CAN_NOT_ITEM",
+    CAN_NOT_STATE = "CAN_NOT_STATE",
+    CAN_NOT_EQUIPMENT = "CAN_NOT_EQUIPMENT",
+    HALF_SP_COST = "HALF_SP_COST",
+    GUARD = "GUARD",
+    SUPER_GUARD = "SUPER_GUARD"
+}
+/**
+ * Effect Manager Mixin
+ *
+ * Provides effect management capabilities to any class. This mixin handles
+ * player effects including restrictions, buffs, and debuffs. Effects can come
+ * from various sources like states, equipment, and temporary conditions.
+ *
+ * @param Base - The base class to extend with effect management
+ * @returns Extended class with effect management methods
+ *
+ * @example
+ * ```ts
+ * class MyPlayer extends WithEffectManager(BasePlayer) {
+ *   constructor() {
+ *     super();
+ *     // Effect system is automatically initialized
+ *   }
+ * }
+ *
+ * const player = new MyPlayer();
+ * player.effects = [Effect.GUARD];
+ * console.log(player.hasEffect(Effect.GUARD)); // true
+ * ```
+ */
+export declare function WithEffectManager<TBase extends PlayerCtor>(Base: TBase): TBase;
+/**
+ * Type helper to extract the interface from the WithEffectManager mixin
+ * This provides the type without duplicating method signatures
+ */
+export type IEffectManager = InstanceType<ReturnType<typeof WithEffectManager>>;

package/dist/Player/ElementManager.d.ts

@@ -0,0 +1,31 @@
+import { PlayerCtor } from '@rpgjs/common';
+/**
+ * Element Manager Mixin
+ *
+ * Provides elemental management capabilities to any class. This mixin handles
+ * elemental resistances, vulnerabilities, and attack elements. It manages both
+ * defensive capabilities (elementsDefense) and offensive elements from equipment,
+ * as well as player-specific elemental efficiency modifiers.
+ *
+ * @param Base - The base class to extend with element management
+ * @returns Extended class with element management methods
+ *
+ * @example
+ * ```ts
+ * class MyPlayer extends WithElementManager(BasePlayer) {
+ *   constructor() {
+ *     super();
+ *     this.elementsEfficiency = [{ rate: 0.5, element: 'fire' }];
+ *   }
+ * }
+ *
+ * const player = new MyPlayer();
+ * const fireResistance = player.elementsDefense.find(e => e.element === 'fire');
+ * ```
+ */
+export declare function WithElementManager<TBase extends PlayerCtor>(Base: TBase): TBase;
+/**
+ * Type helper to extract the interface from the WithElementManager mixin
+ * This provides the type without duplicating method signatures
+ */
+export type IElementManager = InstanceType<ReturnType<typeof WithElementManager>>;

package/dist/Player/GoldManager.d.ts

@@ -0,0 +1,22 @@
+import { PlayerCtor } from '@rpgjs/common';
+export interface GoldManager {
+    /**
+     * You can change the game money
+     *
+     * ```ts
+     * player.gold += 100
+     * ```
+     *
+     * @title Change Gold
+     * @prop {number} player.gold
+     * @default 0
+     * @memberof GoldManager
+     * */
+    gold: number;
+}
+export declare function WithGoldManager<TBase extends PlayerCtor>(Base: TBase): new (...args: ConstructorParameters<TBase>) => InstanceType<TBase> & GoldManager;
+/**
+ * Type helper to extract the interface from the WithGoldManager mixin
+ * This provides the type without duplicating method signatures
+ */
+export type IGoldManager = InstanceType<ReturnType<typeof WithGoldManager>>;