@rpgjs/server 5.0.0-alpha.4 → 5.0.0-alpha.41

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,86 @@
+import { PlayerCtor } from '../../../common/src';
+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;
+/**
+ * Interface for Effect Manager functionality
+ *
+ * Provides effect management capabilities including restrictions, buffs, and debuffs.
+ * This interface defines the public API of the EffectManager mixin.
+ */
+export interface IEffectManager {
+    /**
+     * Gets all currently active effects on the player from multiple sources:
+     * - Direct effects assigned to the player
+     * - Effects from active states (buffs/debuffs)
+     * - Effects from equipped weapons and armor
+     * The returned array contains unique effects without duplicates.
+     *
+     * @returns Array of all active effects on the player
+     */
+    effects: any[];
+    /**
+     * Check if the player has a specific effect
+     *
+     * Determines whether the player currently has the specified effect active.
+     * This includes effects from states, equipment, and temporary conditions.
+     * The effect system provides a flexible way to apply various gameplay
+     * restrictions and enhancements to the player.
+     *
+     * @param effect - The effect identifier to check for
+     * @returns true if the player has the effect, false otherwise
+     *
+     * @example
+     * ```ts
+     * import { Effect } from '@rpgjs/database'
+     *
+     * // Check for skill restriction
+     * const cannotUseSkills = player.hasEffect(Effect.CAN_NOT_SKILL);
+     * if (cannotUseSkills) {
+     *   console.log('Player cannot use skills right now');
+     * }
+     *
+     * // Check for guard effect
+     * const isGuarding = player.hasEffect(Effect.GUARD);
+     * if (isGuarding) {
+     *   console.log('Player is in guard stance');
+     * }
+     *
+     * // Check for cost reduction
+     * const halfCost = player.hasEffect(Effect.HALF_SP_COST);
+     * const actualCost = skillCost / (halfCost ? 2 : 1);
+     * ```
+     */
+    hasEffect(effect: string): boolean;
+}

package/dist/Player/ElementManager.d.ts

@@ -0,0 +1,104 @@
+import { PlayerCtor } from '../../../common/src';
+import { RpgPlayer } from './Player';
+/**
+ * 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;
+/**
+ * Interface for Element Manager functionality
+ *
+ * Provides elemental management capabilities including resistances, vulnerabilities,
+ * and attack elements. This interface defines the public API of the ElementManager mixin.
+ */
+export interface IElementManager {
+    /**
+     * Gets the defensive capabilities against various elements from equipped items.
+     * The system automatically consolidates multiple defensive items, keeping only
+     * the highest protection rate for each element type.
+     *
+     * @returns Array of element defense objects with rate and element properties
+     */
+    elementsDefense: {
+        rate: number;
+        element: any;
+    }[];
+    /**
+     * Manages the player's elemental efficiency modifiers, which determine how
+     * effective different elements are against this player. Values greater than 1
+     * indicate vulnerability, while values less than 1 indicate resistance.
+     * This combines both class-based efficiency and player-specific modifiers.
+     *
+     * @returns Array of element efficiency objects with rate and element properties
+     */
+    elementsEfficiency: {
+        rate: number;
+        element: any;
+    }[];
+    /**
+     * Gets all offensive elements available to the player from equipped weapons and armor.
+     * This determines what elemental damage types the player can deal in combat.
+     * The system automatically combines elements from all equipped items and removes duplicates.
+     *
+     * @returns Array of element objects with rate and element properties for offensive capabilities
+     */
+    elements: {
+        rate: number;
+        element: string;
+    }[];
+    /**
+     * Calculate elemental damage coefficient against another player
+     *
+     * Determines the damage multiplier when this player attacks another player,
+     * taking into account the attacker's offensive elements, the defender's
+     * elemental efficiency, and elemental defense from equipment. This is used
+     * in the battle system to calculate elemental damage modifiers.
+     *
+     * @param otherPlayer - The target player to calculate coefficient against
+     * @returns Numerical coefficient to multiply base damage by
+     *
+     * @example
+     * ```ts
+     * // Calculate elemental damage coefficient
+     * const firePlayer = new MyPlayer();
+     * const icePlayer = new MyPlayer();
+     *
+     * // Fire player attacks ice player (assuming ice is weak to fire)
+     * const coefficient = icePlayer.coefficientElements(firePlayer);
+     * console.log(`Damage multiplier: ${coefficient}`); // e.g., 2.0 for double damage
+     *
+     * // Use in damage calculation
+     * const baseDamage = 100;
+     * const finalDamage = baseDamage * coefficient;
+     * console.log(`Final damage: ${finalDamage}`);
+     *
+     * // Check for elemental advantage
+     * if (coefficient > 1) {
+     *   console.log('Attacker has elemental advantage!');
+     * } else if (coefficient < 1) {
+     *   console.log('Defender resists this element');
+     * }
+     * ```
+     */
+    coefficientElements(otherPlayer: RpgPlayer): number;
+}

package/dist/Player/GoldManager.d.ts

@@ -0,0 +1,22 @@
+import { PlayerCtor } from '../../../common/src';
+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>>;