@rpgjs/server 5.0.0-alpha.8 → 5.0.0-beta.1

package/dist/Player/SkillManager.d.ts

@@ -1,4 +1,124 @@
-import { PlayerCtor } from '@rpgjs/common';
+import { PlayerCtor } from '../../../common/src';
+import { RpgPlayer } from './Player';
+/**
+ * Type for skill class constructor
+ */
+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 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
  *
@@ -6,26 +126,80 @@ import { PlayerCtor } from '@rpgjs/common';
  * 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
- * class MyPlayer extends WithSkillManager(BasePlayer) {
- *   constructor() {
- *     super();
- *     // Skill system is automatically initialized
- *   }
- * }
+ * // Using string ID (from database)
+ * player.learnSkill('fire');
  *
- * const player = new MyPlayer();
- * player.learnSkill(Fire);
- * player.useSkill(Fire, targetPlayer);
+ * // 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;
 /**
- * Type helper to extract the interface from the WithSkillManager mixin
- * This provides the type without duplicating method signatures
+ * 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 type ISkillManager = InstanceType<ReturnType<typeof WithSkillManager>>;
+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 {};

package/dist/Player/StateManager.d.ts

@@ -1,4 +1,8 @@
-import { PlayerCtor } from '@rpgjs/common';
+import { PlayerCtor } from '../../../common/src';
+import { RpgPlayer } from './Player';
+type StateClass = {
+    new (...args: any[]): any;
+};
 /**
  * State Manager Mixin
  *
@@ -26,7 +30,74 @@ import { PlayerCtor } from '@rpgjs/common';
  */
 export declare function WithStateManager<TBase extends PlayerCtor>(Base: TBase): TBase;
 /**
- * Type helper to extract the interface from the WithStateManager mixin
- * This provides the type without duplicating method signatures
+ * 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 type IStateManager = InstanceType<ReturnType<typeof WithStateManager>>;
+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;
+    }[];
+    /**
+     * 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?: Array<{
+            state: any;
+            rate: number;
+        }>;
+        removeStates?: Array<{
+            state: any;
+            rate: number;
+        }>;
+    }): void;
+    /**
+     * 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;
+}
+export {};

package/dist/Player/VariableManager.d.ts

@@ -1,4 +1,4 @@
-import { PlayerCtor } from '@rpgjs/common';
+import { PlayerCtor } from '../../../common/src';
 /**
  * Variable Manager Mixin
  *
@@ -6,6 +6,11 @@ import { PlayerCtor } from '@rpgjs/common';
  * pairs that can store any type of data associated with the player, such as
  * quest progress, game flags, inventory state, and custom game data.
  *
+ * Player variables have two main roles:
+ *
+ * 1. Persist player-specific state so it can be restored from saves.
+ * 2. Carry that state across maps and map servers through the player snapshot.
+ *
  * @param Base - The base class to extend with variable management
  * @returns Extended class with variable management methods
  *
@@ -24,7 +29,60 @@ import { PlayerCtor } from '@rpgjs/common';
  */
 export declare function WithVariableManager<TBase extends PlayerCtor>(Base: TBase): TBase;
 /**
- * Type helper to extract the interface from the WithVariableManager mixin
- * This provides the type without duplicating method signatures
+ * 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 type IVariableManager = InstanceType<ReturnType<typeof WithVariableManager>>;
+export interface IVariableManager {
+    /**
+     * Map storing all player variables.
+     *
+     * These values belong to the player, are persisted, and travel with the
+     * player snapshot when switching maps or servers.
+     */
+    variables: Map<string, any>;
+    /**
+     * Assign a variable to the player.
+     *
+     * Use player variables for quest flags, per-player event state, and any value
+     * that must survive saves and map transitions.
+     *
+     * @param key - The variable identifier
+     * @param val - The value to store
+     * @memberof VariableManager
+     */
+    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;
+}