@rpgjs/server 5.0.0-alpha.26 → 5.0.0-alpha.28

package/dist/Player/MoveManager.d.ts

@@ -1,8 +1,54 @@
-import { PlayerCtor, ProjectileType, RpgCommonPlayer, Direction, MovementStrategy } from '../../../common/src';
+import { PlayerCtor, ProjectileType, RpgCommonPlayer, Direction, MovementStrategy, MovementOptions } from '../../../common/src';
 import { RpgPlayer } from './Player';
 type CallbackTileMove = (player: RpgPlayer, map: any) => Direction[];
 type CallbackTurnMove = (player: RpgPlayer, map: any) => string;
 type Routes = (string | Promise<any> | Direction | Direction[] | Function)[];
+export type { MovementOptions };
+/**
+ * Options for moveRoutes method
+ */
+export interface MoveRoutesOptions {
+    /**
+     * Callback function called when the player gets stuck (cannot move towards target)
+     *
+     * This callback is triggered when the player is trying to move but cannot make progress
+     * towards the target position, typically due to obstacles or collisions.
+     *
+     * @param player - The player instance that is stuck
+     * @param target - The target position the player was trying to reach
+     * @param currentPosition - The current position of the player
+     * @returns If true, the route will continue; if false, the route will be cancelled
+     *
+     * @example
+     * ```ts
+     * await player.moveRoutes([Move.right()], {
+     *   onStuck: (player, target, currentPos) => {
+     *     console.log('Player is stuck!');
+     *     return false; // Cancel the route
+     *   }
+     * });
+     * ```
+     */
+    onStuck?: (player: RpgPlayer, target: {
+        x: number;
+        y: number;
+    }, currentPosition: {
+        x: number;
+        y: number;
+    }) => boolean | void;
+    /**
+     * Time in milliseconds to wait before considering the player stuck (default: 500ms)
+     *
+     * The player must be unable to make progress for this duration before onStuck is called.
+     */
+    stuckTimeout?: number;
+    /**
+     * Minimum distance change in pixels to consider movement progress (default: 1 pixel)
+     *
+     * If the player moves less than this distance over the stuckTimeout period, they are considered stuck.
+     */
+    stuckThreshold?: number;
+}
 export declare enum Frequency {
     Lowest = 600,
     Lower = 400,
@@ -21,34 +67,39 @@ export declare enum Speed {
     Faster = 7,
     Fastest = 10
 }
-/**
-* @title Move
-* @enum {Object}
-*
-* Move.right(repeat=1) | Movement of a number of pixels on the right
-* Move.left(repeat=1) | Movement of a number of pixels on the left
-* Move.up(repeat=1) | Movement of a number of pixels on the up
-* Move.down(repeat=1) | Movement of a number of pixels on the down
-* Move.random(repeat=1) | Movement of a number of pixels in a random direction
-* Move.towardPlayer(player, repeat=1) | Moves a number of pixels in the direction of the designated player
-* Move.awayFromPlayer(player, repeat=1) | Moves a number of pixels in the opposite direction of the designated player
-* Move.tileRight(repeat=1) | Movement of a number of tiles on the right
-* Move.tileLeft(repeat=1) | Movement of a number of tiles on the left
-* Move.tileUp(repeat=1) | Movement of a number of tiles on the up
-* Move.tileDown(repeat=1) | Movement of a number of tiles on the down
-* Move.tileRandom(repeat=1) | Movement of a number of tiles in a random direction
-* Move.tileTowardPlayer(player, repeat=1) | Moves a number of tiles in the direction of the designated player
-* Move.tileAwayFromPlayer(player, repeat=1) | Moves a number of tiles in the opposite direction of the designated player
-* Move.turnRight() | Turn to the right
-* Move.turnLeft() | Turn to the left
-* Move.turnUp() | Turn to the up
-* Move.turnDown() | Turn to the down
-* Move.turnRandom() | Turn to random direction
-* Move.turnAwayFromPlayer(player) | Turns in the opposite direction of the designated player
-* Move.turnTowardPlayer(player) | Turns in the direction of the designated player
-* @memberof Move
-* */
 declare class MoveList {
+    private static perlinNoise;
+    private static randomCounter;
+    private static callCounter;
+    private static playerMoveStates;
+    private static readonly STUCK_THRESHOLD;
+    /**
+     * Clears the movement state for a specific player
+     *
+     * Should be called when a player changes map or is destroyed to prevent
+     * memory leaks and stale stuck detection data.
+     *
+     * @param playerId - The ID of the player to clear state for
+     *
+     * @example
+     * ```ts
+     * // Clear state when player leaves map
+     * Move.clearPlayerState(player.id);
+     * ```
+     */
+    static clearPlayerState(playerId: string): void;
+    /**
+     * Clears all player movement states
+     *
+     * Useful for cleanup during server shutdown or when resetting game state.
+     *
+     * @example
+     * ```ts
+     * // Clear all states on server shutdown
+     * Move.clearAllPlayerStates();
+     * ```
+     */
+    static clearAllPlayerStates(): void;
     repeatMove(direction: Direction, repeat: number): Direction[];
     private repeatTileMove;
     right(repeat?: number): Direction[];
@@ -166,18 +217,77 @@ export declare function WithMoveManager<TBase extends PlayerCtor>(Base: TBase):
  * This interface defines the public API of the MoveManager mixin.
  */
 export interface IMoveManager {
-    /** Whether the player passes through other players */
+    /**
+     * Whether the player passes through other players
+     *
+     * When `true`, the player can walk through other player entities without collision.
+     * This is useful for busy areas where players shouldn't block each other.
+     *
+     * @default true
+     *
+     * @example
+     * ```ts
+     * // Disable player-to-player collision
+     * player.throughOtherPlayer = true;
+     *
+     * // Enable player-to-player collision
+     * player.throughOtherPlayer = false;
+     * ```
+     */
     throughOtherPlayer: boolean;
-    /** Whether the player goes through events or other players */
+    /**
+     * Whether the player goes through all characters (players and events)
+     *
+     * When `true`, the player can walk through all character entities (both players and events)
+     * without collision. Walls and obstacles still block movement.
+     * This takes precedence over `throughOtherPlayer` and `throughEvent`.
+     *
+     * @default false
+     *
+     * @example
+     * ```ts
+     * // Enable ghost mode - pass through all characters
+     * player.through = true;
+     *
+     * // Disable ghost mode
+     * player.through = false;
+     * ```
+     */
     through: boolean;
+    /**
+     * Whether the player passes through events (NPCs, objects)
+     *
+     * When `true`, the player can walk through event entities without collision.
+     * This is useful for NPCs that shouldn't block player movement.
+     *
+     * @default false
+     *
+     * @example
+     * ```ts
+     * // Allow passing through events
+     * player.throughEvent = true;
+     *
+     * // Block passage through events
+     * player.throughEvent = false;
+     * ```
+     */
+    throughEvent: boolean;
     /** Frequency for movement timing (milliseconds between movements) */
     frequency: number;
+    /** Whether direction changes are locked (prevents automatic direction changes) */
+    directionFixed: boolean;
+    /** Whether animation changes are locked (prevents automatic animation changes) */
+    animationFixed: boolean;
     /**
      * Add a custom movement strategy to this entity
      *
+     * Returns a Promise that resolves when the movement completes.
+     *
      * @param strategy - The movement strategy to add
+     * @param options - Optional callbacks for movement lifecycle events
+     * @returns Promise that resolves when the movement completes
      */
-    addMovement(strategy: MovementStrategy): void;
+    addMovement(strategy: MovementStrategy, options?: MovementOptions): Promise<void>;
     /**
      * Remove a specific movement strategy from this entity
      *
@@ -217,36 +327,48 @@ export interface IMoveManager {
     /**
      * Perform a dash movement in the specified direction
      *
+     * The total speed is calculated by adding the player's base speed to the additional speed.
+     * Returns a Promise that resolves when the dash completes.
+     *
      * @param direction - Normalized direction vector
-     * @param speed - Movement speed (default: 8)
+     * @param additionalSpeed - Extra speed added on top of base speed (default: 4)
      * @param duration - Duration in milliseconds (default: 200)
+     * @param options - Optional callbacks for movement lifecycle events
+     * @returns Promise that resolves when the dash completes
      */
     dash(direction: {
         x: number;
         y: number;
-    }, speed?: number, duration?: number): void;
+    }, additionalSpeed?: number, duration?: number, options?: MovementOptions): Promise<void>;
     /**
      * Apply knockback effect in the specified direction
      *
+     * The force is scaled by the player's base speed for consistent behavior.
+     * Returns a Promise that resolves when the knockback completes.
+     *
      * @param direction - Normalized direction vector
-     * @param force - Initial knockback force (default: 5)
+     * @param force - Force multiplier applied to base speed (default: 5)
      * @param duration - Duration in milliseconds (default: 300)
+     * @param options - Optional callbacks for movement lifecycle events
+     * @returns Promise that resolves when the knockback completes
      */
     knockback(direction: {
         x: number;
         y: number;
-    }, force?: number, duration?: number): void;
+    }, force?: number, duration?: number, options?: MovementOptions): Promise<void>;
     /**
      * Follow a sequence of waypoints
      *
+     * Speed is calculated from the player's base speed multiplied by the speedMultiplier.
+     *
      * @param waypoints - Array of x,y positions to follow
-     * @param speed - Movement speed (default: 2)
+     * @param speedMultiplier - Multiplier applied to base speed (default: 0.5)
      * @param loop - Whether to loop back to start (default: false)
      */
     followPath(waypoints: Array<{
         x: number;
         y: number;
-    }>, speed?: number, loop?: boolean): void;
+    }>, speedMultiplier?: number, loop?: boolean): void;
     /**
      * Apply oscillating movement pattern
      *
@@ -261,31 +383,36 @@ export interface IMoveManager {
     /**
      * Apply ice movement physics
      *
+     * Max speed is calculated from the player's base speed multiplied by the speedFactor.
+     *
      * @param direction - Target movement direction
-     * @param maxSpeed - Maximum speed when fully accelerated (default: 4)
+     * @param speedFactor - Factor multiplied with base speed for max speed (default: 1.0)
      */
     applyIceMovement(direction: {
         x: number;
         y: number;
-    }, maxSpeed?: number): void;
+    }, speedFactor?: number): void;
     /**
      * Shoot a projectile in the specified direction
      *
+     * Speed is calculated from the player's base speed multiplied by the speedFactor.
+     *
      * @param type - Type of projectile trajectory
      * @param direction - Normalized direction vector
-     * @param speed - Projectile speed (default: 200)
+     * @param speedFactor - Factor multiplied with base speed (default: 50)
      */
     shootProjectile(type: ProjectileType, direction: {
         x: number;
         y: number;
-    }, speed?: number): void;
+    }, speedFactor?: number): void;
     /**
      * Give an itinerary to follow using movement strategies
      *
      * @param routes - Array of movement instructions to execute
+     * @param options - Optional configuration including onStuck callback
      * @returns Promise that resolves when all routes are completed
      */
-    moveRoutes(routes: Routes): Promise<boolean>;
+    moveRoutes(routes: Routes, options?: MoveRoutesOptions): Promise<boolean>;
     /**
      * Give a path that repeats itself in a loop to a character
      *
@@ -303,4 +430,3 @@ export interface IMoveManager {
      */
     replayRoutes(): void;
 }
-export {};

package/dist/Player/Player.d.ts

@@ -136,6 +136,8 @@ export declare class RpgPlayer extends RpgPlayer_base {
      * When `nbTimes` is set to a finite number, the animation will play that many times
      * before returning to the previous animation state.
      *
+     * If `animationFixed` is true, this method will not change the animation.
+     *
      * @param animationName - The name of the animation to play (e.g., 'attack', 'skill', 'walk')
      * @param nbTimes - Number of times to repeat the animation (default: Infinity for continuous)
      *
@@ -147,8 +149,9 @@ export declare class RpgPlayer extends RpgPlayer_base {
      * // Play attack animation 3 times then return to previous state
      * player.setAnimation('attack', 3);
      *
-     * // Play skill animation once
-     * player.setAnimation('skill', 1);
+     * // Lock animation to prevent automatic changes
+     * player.animationFixed = true;
+     * player.setAnimation('skill'); // This will be ignored
      *
      * // Set idle/stand animation
      * player.setAnimation('stand');
@@ -459,10 +462,18 @@ export declare class RpgPlayer extends RpgPlayer_base {
      * @param schema - The schema to set
      */
     setSync(schema: any): void;
+    isEvent(): boolean;
 }
 export declare class RpgEvent extends RpgPlayer {
     execMethod(methodName: string, methodData?: any[], instance?: this): Promise<any>;
+    /**
+     * Remove this event from the map
+     *
+     * Stops all movements before removing to prevent "unable to resolve entity" errors
+     * from the MovementManager when the entity is destroyed while moving.
+     */
     remove(): void;
+    isEvent(): boolean;
 }
 /**
  * Interface extension for RpgPlayer

package/dist/Player/SkillManager.d.ts

@@ -1,5 +1,124 @@
 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
  *
@@ -7,21 +126,31 @@ import { RpgPlayer } from './Player';
  * 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;
@@ -35,36 +164,42 @@ export interface ISkillManager {
     /**
      * Retrieves a learned skill. Returns null if not found
      *
-     * @param skillClass - Skill class or data id
-     * @returns Instance of SkillClass or null
+     * @param skillInput - Skill class, object, or data id
+     * @returns The skill data or null
      */
-    getSkill(skillClass: any | string): any | null;
+    getSkill(skillInput: SkillClass | SkillObject | string): any | null;
     /**
      * Learn a skill
      *
-     * @param skillId - Skill class or data id
-     * @returns Instance of SkillClass
+     * 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(skillId: any | string): any;
+    learnSkill(skillInput: SkillClass | SkillObject | string): any;
     /**
      * Forget a skill
      *
-     * @param skillId - Skill class or data id
-     * @returns Instance of SkillClass
+     * @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(skillId: any | string): any;
+    forgetSkill(skillInput: SkillClass | SkillObject | string): any;
     /**
-     * Using a skill
+     * Use a skill
      *
-     * @param skillId - Skill class or data id
+     * @param skillInput - Skill class, object, or data id
      * @param otherPlayer - Optional target player(s) to apply skill to
-     * @returns Instance of SkillClass
+     * @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(skillId: any | string, otherPlayer?: RpgPlayer | RpgPlayer[]): any;
+    useSkill(skillInput: SkillClass | SkillObject | string, otherPlayer?: RpgPlayer | RpgPlayer[]): any;
 }
+export {};

package/dist/index.d.ts

@@ -13,3 +13,4 @@ export * from './Gui';
 export { RpgShape, RpgModule } from '../../common/src';
 export * from './decorators/event';
 export * from './decorators/map';
+export * from './Player/MoveManager';