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

package/dist/Player/SkillManager.d.ts

@@ -1,23 +1,205 @@
-import { Constructor, RpgCommonPlayer } from '@rpgjs/common';
+import { PlayerCtor } from '../../../common/src';
 import { RpgPlayer } from './Player';
 /**
- * Interface defining dependencies from other mixins that SkillManager needs
+ * Type for skill class constructor
  */
-interface SkillManagerDependencies {
-    sp: number;
-    skills(): any[];
-    hasEffect(effect: string): boolean;
-    databaseById(id: string): any;
-    applyStates(player: RpgPlayer, skill: any): void;
+type SkillClass = {
+    new (...args: any[]): any;
+};
+/**
+ * Interface defining the hooks that can be implemented on skill classes or objects
+ *
+ * These hooks are called at specific moments during the skill lifecycle:
+ * - `onLearn`: When the skill is learned by the player
+ * - `onUse`: When the skill is successfully used
+ * - `onUseFailed`: When the skill usage fails (e.g., chance roll failed)
+ * - `onForget`: When the skill is forgotten
+ *
+ * @example
+ * ```ts
+ * const skillHooks: SkillHooks = {
+ *   onLearn(player) {
+ *     console.log('Skill learned!');
+ *   },
+ *   onUse(player, target) {
+ *     console.log('Skill used on target');
+ *   }
+ * };
+ * ```
+ */
+export interface SkillHooks {
+    /**
+     * Called when the skill is learned by the player
+     *
+     * @param player - The player learning the skill
+     */
+    onLearn?: (player: RpgPlayer) => void | Promise<void>;
+    /**
+     * Called when the skill is successfully used
+     *
+     * @param player - The player using the skill
+     * @param target - The target player(s) if any
+     */
+    onUse?: (player: RpgPlayer, target?: RpgPlayer | RpgPlayer[]) => void | Promise<void>;
+    /**
+     * Called when the skill usage fails (e.g., chance roll failed)
+     *
+     * @param player - The player attempting to use the skill
+     * @param target - The intended target player(s) if any
+     */
+    onUseFailed?: (player: RpgPlayer, target?: RpgPlayer | RpgPlayer[]) => void | Promise<void>;
+    /**
+     * Called when the skill is forgotten
+     *
+     * @param player - The player forgetting the skill
+     */
+    onForget?: (player: RpgPlayer) => void | Promise<void>;
 }
 /**
- * Interface defining what SkillManager adds to a class
+ * Interface for skill object definition
+ *
+ * Defines the properties that a skill can have when defined as an object.
+ * Skills can be defined as objects, classes, or string IDs referencing the database.
+ *
+ * @example
+ * ```ts
+ * const fireSkill: SkillObject = {
+ *   id: 'fire',
+ *   name: 'Fire',
+ *   description: 'A basic fire spell',
+ *   spCost: 10,
+ *   hitRate: 0.9,
+ *   power: 50,
+ *   onUse(player) {
+ *     console.log('Fire spell cast!');
+ *   }
+ * };
+ *
+ * player.learnSkill(fireSkill);
+ * ```
+ */
+export interface SkillObject extends SkillHooks {
+    /**
+     * Unique identifier for the skill
+     * If not provided, one will be auto-generated
+     */
+    id?: string;
+    /**
+     * Display name of the skill
+     */
+    name?: string;
+    /**
+     * Description of the skill
+     */
+    description?: string;
+    /**
+     * SP (Skill Points) cost to use the skill
+     * @default 0
+     */
+    spCost?: number;
+    /**
+     * Hit rate (0-1) - probability of successful skill usage
+     * @default 1
+     */
+    hitRate?: number;
+    /**
+     * Base power of the skill for damage calculation
+     */
+    power?: number;
+    /**
+     * Coefficient multipliers for damage calculation
+     */
+    coefficient?: Record<string, number>;
+    /**
+     * Type marker for database
+     */
+    _type?: 'skill';
+    /**
+     * Allow additional properties
+     */
+    [key: string]: any;
+}
+/**
+ * Skill Manager Mixin
+ *
+ * Provides skill management capabilities to any class. This mixin handles
+ * learning, forgetting, and using skills, including SP cost management,
+ * hit rate calculations, and skill effects application.
+ *
+ * Supports three input formats for skills:
+ * - **String ID**: References a skill in the database
+ * - **Class**: A skill class that will be instantiated
+ * - **Object**: A skill object with properties and hooks
+ *
+ * @param Base - The base class to extend with skill management
+ * @returns Extended class with skill management methods
+ *
+ * @example
+ * ```ts
+ * // Using string ID (from database)
+ * player.learnSkill('fire');
+ *
+ * // Using skill class
+ * player.learnSkill(FireSkill);
+ *
+ * // Using skill object
+ * player.learnSkill({
+ *   id: 'ice',
+ *   name: 'Ice',
+ *   spCost: 15,
+ *   onUse(player) {
+ *     console.log('Ice spell cast!');
+ *   }
+ * });
+ * ```
+ */
+export declare function WithSkillManager<TBase extends PlayerCtor>(Base: TBase): TBase;
+/**
+ * Interface for Skill Manager functionality
+ *
+ * Provides skill management capabilities including learning, forgetting, and using skills.
+ * This interface defines the public API of the SkillManager mixin.
  */
-export interface IWithSkillManager {
-    getSkill(skillClass: any | string): any;
-    learnSkill(skillId: any | string): any;
-    forgetSkill(skillId: any | string): any;
-    useSkill(skillId: any | string, otherPlayer?: RpgPlayer | RpgPlayer[]): any;
+export interface ISkillManager {
+    /**
+     * Retrieves a learned skill. Returns null if not found
+     *
+     * @param skillInput - Skill class, object, or data id
+     * @returns The skill data or null
+     */
+    getSkill(skillInput: SkillClass | SkillObject | string): any | null;
+    /**
+     * Learn a skill
+     *
+     * Supports three input formats:
+     * - String ID: Retrieves from database
+     * - Class: Creates instance and adds to database
+     * - Object: Uses directly and adds to database
+     *
+     * @param skillInput - Skill class, object, or data id
+     * @returns The learned skill data
+     * @throws SkillLog.alreadyLearned if the player already knows the skill
+     */
+    learnSkill(skillInput: SkillClass | SkillObject | string): any;
+    /**
+     * Forget a skill
+     *
+     * @param skillInput - Skill class, object, or data id
+     * @returns The forgotten skill data
+     * @throws SkillLog.notLearned if trying to forget a skill not learned
+     */
+    forgetSkill(skillInput: SkillClass | SkillObject | string): any;
+    /**
+     * Use a skill
+     *
+     * @param skillInput - Skill class, object, or data id
+     * @param otherPlayer - Optional target player(s) to apply skill to
+     * @returns The used skill data
+     * @throws SkillLog.restriction if player has Effect.CAN_NOT_SKILL
+     * @throws SkillLog.notLearned if player tries to use an unlearned skill
+     * @throws SkillLog.notEnoughSp if player does not have enough SP
+     * @throws SkillLog.chanceToUseFailed if the chance to use the skill has failed
+     */
+    useSkill(skillInput: SkillClass | SkillObject | string, otherPlayer?: RpgPlayer | RpgPlayer[]): any;
 }
-export declare function WithSkillManager<TBase extends Constructor<RpgCommonPlayer & SkillManagerDependencies>>(Base: TBase): Constructor<IWithSkillManager> & TBase;
 export {};

package/dist/Player/StateManager.d.ts

@@ -1,39 +1,103 @@
-import { Constructor, RpgCommonPlayer } from '@rpgjs/common';
-import { WritableArraySignal } from '@signe/reactive';
+import { PlayerCtor } from '../../../common/src';
 import { RpgPlayer } from './Player';
-interface StateManagerDependencies {
-    equipments(): any[];
-    databaseById(id: string | StateClass): any;
-    addState(stateClass: StateClass | string, chance?: number): object | null;
-    removeState(stateClass: StateClass | string, chance?: number): void;
-}
+type StateClass = {
+    new (...args: any[]): any;
+};
+/**
+ * State Manager Mixin
+ *
+ * Provides state management capabilities to any class. This mixin handles
+ * player states (buffs/debuffs), state defense from equipment, and state
+ * efficiency modifiers. It manages the complete state system including
+ * application, removal, and resistance mechanics.
+ *
+ * @param Base - The base class to extend with state management
+ * @returns Extended class with state management methods
+ *
+ * @example
+ * ```ts
+ * class MyPlayer extends WithStateManager(BasePlayer) {
+ *   constructor() {
+ *     super();
+ *     // State system is automatically initialized
+ *   }
+ * }
+ *
+ * const player = new MyPlayer();
+ * player.addState(Paralyze);
+ * console.log(player.getState(Paralyze));
+ * ```
+ */
+export declare function WithStateManager<TBase extends PlayerCtor>(Base: TBase): TBase;
 /**
- * Interface defining what MoveManager adds to a class
+ * Interface for State Manager functionality
+ *
+ * Provides state management capabilities including state defense, efficiency modifiers,
+ * and state application/removal. This interface defines the public API of the StateManager mixin.
  */
 export interface IStateManager {
+    /**
+     * Gets the defensive capabilities against various states from equipped items
+     *
+     * @returns Array of state defense objects with rate and state properties
+     */
     statesDefense: {
         rate: number;
         state: any;
     }[];
-    statesEfficiency: WritableArraySignal<any[]>;
+    /**
+     * Manages the player's state efficiency modifiers
+     *
+     * @returns Signal containing array of state efficiency objects
+     */
+    statesEfficiency: any;
+    /**
+     * Apply states to a player from skill or item effects
+     *
+     * @param player - The target player to apply states to
+     * @param states - Object containing arrays of states to add or remove
+     */
     applyStates(player: RpgPlayer, states: {
-        addStates?: any[];
-        removeStates?: any[];
+        addStates?: Array<{
+            state: any;
+            rate: number;
+        }>;
+        removeStates?: Array<{
+            state: any;
+            rate: number;
+        }>;
     }): void;
-    getState(stateClass: StateClass | string): any;
+    /**
+     * Get a state to the player. Returns null if the state is not present
+     *
+     * @param stateClass - The state class constructor or state ID to search for
+     * @returns The state instance if found, null otherwise
+     */
+    getState(stateClass: StateClass | string): any | null;
+    /**
+     * Adds a state to the player
+     *
+     * @param stateClass - The state class constructor or state ID to apply
+     * @param chance - Probability of successful application (0-1, default 1)
+     * @returns The state instance if successfully applied, null if already present
+     * @throws StateLog.addFailed if the chance roll fails
+     */
     addState(stateClass: StateClass | string, chance?: number): object | null;
+    /**
+     * Remove a state to the player
+     *
+     * @param stateClass - The state class constructor or state ID to remove
+     * @param chance - Probability of successful removal (0-1, default 1)
+     * @throws StateLog.removeFailed if the chance roll fails
+     * @throws StateLog.notApplied if the state is not currently active
+     */
     removeState(stateClass: StateClass | string, chance?: number): void;
+    /**
+     * Find state efficiency modifier for a specific state class
+     *
+     * @param stateClass - The state class to find efficiency for
+     * @returns The efficiency object if found, undefined otherwise
+     */
+    findStateEfficiency(stateClass: any): any | undefined;
 }
-type StateClass = {
-    new (...args: any[]): any;
-};
-/**
- * Move Manager mixin
- *
- * Adds methods to manage player movement
- *
- * @param Base - The base class to extend
- * @returns A new class with move management capabilities
- */
-export declare function WithStateManager<TBase extends Constructor<RpgCommonPlayer & StateManagerDependencies>>(Base: TBase): Constructor<IStateManager> & TBase;
 export {};

package/dist/Player/VariableManager.d.ts

@@ -0,0 +1,74 @@
+import { PlayerCtor } from '../../../common/src';
+/**
+ * Variable Manager Mixin
+ *
+ * Provides variable management capabilities to any class. Variables are key-value
+ * pairs that can store any type of data associated with the player, such as
+ * quest progress, game flags, inventory state, and custom game data.
+ *
+ * @param Base - The base class to extend with variable management
+ * @returns Extended class with variable management methods
+ *
+ * @example
+ * ```ts
+ * class MyPlayer extends WithVariableManager(BasePlayer) {
+ *   constructor() {
+ *     super();
+ *     // Variables are automatically initialized
+ *   }
+ * }
+ *
+ * const player = new MyPlayer();
+ * player.setVariable('questCompleted', true);
+ * ```
+ */
+export declare function WithVariableManager<TBase extends PlayerCtor>(Base: TBase): TBase;
+/**
+ * Interface for Variable Manager functionality
+ *
+ * Provides variable management capabilities including storing, retrieving, and managing
+ * key-value pairs for player-specific data. This interface defines the public API
+ * of the VariableManager mixin.
+ */
+export interface IVariableManager {
+    /** Map storing all player variables */
+    variables: Map<string, any>;
+    /**
+     * Assign a variable to the player
+     *
+     * @param key - The variable identifier
+     * @param val - The value to store
+     */
+    setVariable(key: string, val: any): void;
+    /**
+     * Get a variable value
+     *
+     * @param key - The variable identifier to retrieve
+     * @returns The stored value or undefined if not found
+     */
+    getVariable<U = any>(key: string): U | undefined;
+    /**
+     * Remove a variable
+     *
+     * @param key - The variable identifier to remove
+     * @returns true if a variable existed and has been removed, false otherwise
+     */
+    removeVariable(key: string): boolean;
+    /**
+     * Check if a variable exists
+     *
+     * @param key - The variable identifier to check
+     * @returns true if the variable exists, false otherwise
+     */
+    hasVariable(key: string): boolean;
+    /**
+     * Get all variable keys
+     *
+     * @returns Array of all variable keys
+     */
+    getVariableKeys(): string[];
+    /**
+     * Clear all variables
+     */
+    clearVariables(): void;
+}