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

package/src/Player/Components.ts

@@ -0,0 +1,380 @@
+/**
+ * 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 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 {
+    return {
+      type: 'text',
+      value,
+      style
+    };
+  },
+
+  /**
+   * 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 {
+    return {
+      type: 'hpBar',
+      style,
+      text: text ?? undefined
+    };
+  },
+
+  /**
+   * 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 {
+    return {
+      type: 'spBar',
+      style,
+      text: text ?? undefined
+    };
+  },
+
+  /**
+   * 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 {
+    return {
+      type: 'bar',
+      current,
+      max,
+      style,
+      text: text ?? undefined
+    };
+  },
+
+  /**
+   * 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 {
+    return {
+      type: 'shape',
+      value
+    };
+  },
+
+  /**
+   * 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 {
+    return {
+      type: 'image',
+      value
+    };
+  },
+
+  /**
+   * 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 {
+    return {
+      type: 'tile',
+      value
+    };
+  }
+}; 
+

package/src/Player/EffectManager.ts

@@ -2,13 +2,10 @@ import {
   arrayFlat,
   arrayUniq,
   Constructor,
+  PlayerCtor,
   RpgCommonPlayer,
 } from "@rpgjs/common";
 
-export interface IWithEffectManager {
-  effects: any[];
-}
-
 export enum Effect {
   CAN_NOT_SKILL = 'CAN_NOT_SKILL',
   CAN_NOT_ITEM = 'CAN_NOT_ITEM',
@@ -19,23 +16,64 @@ export enum Effect {
   SUPER_GUARD = 'SUPER_GUARD'
 }
 
-export function WithEffectManager<TBase extends Constructor<RpgCommonPlayer>>(
-  Base: TBase
-) {
-  return class extends Base implements IWithEffectManager {
+/**
+ * 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 function WithEffectManager<TBase extends PlayerCtor>(Base: TBase) {
+  return class extends Base {
     /**
+     * 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'
      *
-     * const bool = player.hasEffect(Effect.CAN_NOT_SKILL)
+     * // 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);
      * ```
-     *
-     * @title Has Effect
-     * @method player.hasEffect(effect)
-     * @param {string} effect
-     * @returns {boolean}
-     * @memberof EffectManager
-     * */
+     */
     hasEffect(effect: string): boolean {
       return this.effects.includes(effect);
     }
@@ -43,13 +81,31 @@ export function WithEffectManager<TBase extends Constructor<RpgCommonPlayer>>(
     /**
      * Retrieves a array of effects assigned to the player, state effects and effects of weapons and armors equipped with the player's own weapons.
      *
+     * 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
+     * 
+     * @example
      * ```ts
-     * console.log(player.effects)
+     * // Get all active effects
+     * console.log(player.effects); // ['GUARD', 'HALF_SP_COST', ...]
+     * 
+     * // Check multiple effects
+     * const effects = player.effects;
+     * const hasRestrictions = effects.some(effect => 
+     *   effect.startsWith('CAN_NOT_')
+     * );
+     * 
+     * // Count beneficial effects
+     * const beneficialEffects = effects.filter(effect => 
+     *   ['GUARD', 'SUPER_GUARD', 'HALF_SP_COST'].includes(effect)
+     * );
      * ```
-     * @title Get Effects
-     * @prop {Array<Effect>} player.effects
-     * @memberof EffectManager
-     * */
+     */
     get effects(): any[] {
       const getEffects = (prop) => {
         return arrayFlat(this[prop]().map((el) => el.effects || []));
@@ -64,17 +120,44 @@ export function WithEffectManager<TBase extends Constructor<RpgCommonPlayer>>(
     /**
      * Assigns effects to the player. If you give a array, it does not change the effects of the player's states and armor/weapons equipped.
      *
+     * Sets the direct effects on the player. This only affects the player's own effects
+     * and does not modify effects from states or equipment. The total effects will be
+     * the combination of these direct effects plus any effects from states and equipment.
+     * 
+     * @param val - Array of effect identifiers to assign to the player
+     * 
+     * @example
      * ```ts
      * import { Effect } from '@rpgjs/database'
      *
-     * player.effects = [Effect.CAN_NOT_SKILL]
+     * // Set direct player effects
+     * player.effects = [Effect.CAN_NOT_SKILL];
+     * 
+     * // Add multiple effects
+     * player.effects = [
+     *   Effect.GUARD,
+     *   Effect.HALF_SP_COST,
+     *   Effect.CAN_NOT_ITEM
+     * ];
+     * 
+     * // Clear direct effects (equipment/state effects remain)
+     * player.effects = [];
+     * 
+     * // Temporary effect application
+     * const originalEffects = player.effects;
+     * player.effects = [...originalEffects, Effect.SUPER_GUARD];
+     * // Later restore
+     * player.effects = originalEffects;
      * ```
-     * @title Set Effects
-     * @prop {Array<Effect>} player.effects
-     * @memberof EffectManager
-     * */
+     */
     set effects(val) {
       this._effects.set(val);
     }
-  };
+  } as unknown as 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>>;