@rpgjs/server 5.0.0-alpha.1 → 5.0.0-alpha.10

package/dist/rooms/map.d.ts

@@ -102,7 +102,76 @@ export declare class RpgMap extends RpgCommonMap<RpgPlayer> implements RoomOnJoi
     getPlayer(playerId: string): RpgPlayer | undefined;
     getEvents(): RpgEvent[];
     removeEvent(eventId: string): void;
-    showAnimation(animationName: string, object: RpgPlayer): void;
+    /**
+     * Display a component animation at a specific position on the map
+     *
+     * This method broadcasts a component animation to all clients connected to the map,
+     * allowing temporary visual effects to be displayed at any location on the map.
+     * Component animations are custom Canvas Engine components that can display
+     * complex effects with custom logic and parameters.
+     *
+     * @param id - The ID of the component animation to display
+     * @param position - The x, y coordinates where to display the animation
+     * @param params - Parameters to pass to the component animation
+     *
+     * @example
+     * ```ts
+     * // Show explosion at specific coordinates
+     * map.showComponentAnimation("explosion", { x: 300, y: 400 }, {
+     *   intensity: 2.5,
+     *   duration: 1500
+     * });
+     *
+     * // Show area damage effect
+     * map.showComponentAnimation("area-damage", { x: player.x, y: player.y }, {
+     *   radius: 100,
+     *   color: "red",
+     *   damage: 50
+     * });
+     *
+     * // Show treasure spawn effect
+     * map.showComponentAnimation("treasure-spawn", { x: 150, y: 200 }, {
+     *   sparkle: true,
+     *   sound: "treasure-appear"
+     * });
+     * ```
+     */
+    showComponentAnimation(id: string, position: {
+        x: number;
+        y: number;
+    }, params: any): void;
+    /**
+     * Display a spritesheet animation at a specific position on the map
+     *
+     * This method displays a temporary visual animation using a spritesheet at any
+     * location on the map. It's a convenience method that internally uses showComponentAnimation
+     * with the built-in 'animation' component. This is useful for spell effects, environmental
+     * animations, or any visual feedback that uses predefined spritesheets.
+     *
+     * @param position - The x, y coordinates where to display the animation
+     * @param graphic - The ID of the spritesheet to use for the animation
+     * @param animationName - The name of the animation within the spritesheet (default: 'default')
+     *
+     * @example
+     * ```ts
+     * // Show explosion at specific coordinates
+     * map.showAnimation({ x: 100, y: 200 }, "explosion");
+     *
+     * // Show spell effect at player position
+     * const playerPos = { x: player.x, y: player.y };
+     * map.showAnimation(playerPos, "spell-effects", "lightning");
+     *
+     * // Show environmental effect
+     * map.showAnimation({ x: 300, y: 150 }, "nature-effects", "wind-gust");
+     *
+     * // Show portal opening animation
+     * map.showAnimation({ x: 500, y: 400 }, "portals", "opening");
+     * ```
+     */
+    showAnimation(position: {
+        x: number;
+        y: number;
+    }, graphic: string, animationName?: string): void;
 }
 export interface RpgMap {
     $send: (conn: MockConnection, data: any) => void;

package/package.json

@@ -1,21 +1,17 @@
 {
   "name": "@rpgjs/server",
-  "version": "5.0.0-alpha.1",
+  "version": "5.0.0-alpha.10",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "dev": "vite build --watch",
-    "build": "vite build"
-  },
   "keywords": [],
   "author": "",
   "license": "MIT",
   "description": "",
   "dependencies": {
-    "@rpgjs/common": "workspace:*",
+    "@rpgjs/common": "5.0.0-alpha.10",
     "@rpgjs/database": "^4.3.0",
     "@signe/di": "^2.3.2",
     "@signe/reactive": "^2.3.2",
@@ -27,5 +23,9 @@
     "vite": "^6.2.5",
     "vite-plugin-dts": "^4.5.3"
   },
-  "type": "module"
-}
+  "type": "module",
+  "scripts": {
+    "dev": "vite build --watch",
+    "build": "vite build"
+  }
+}

package/src/Player/BattleManager.ts

@@ -1,4 +1,4 @@
-import { Constructor, RpgCommonPlayer } from "@rpgjs/common";
+import { Constructor, PlayerCtor, RpgCommonPlayer } from "@rpgjs/common";
 import { RpgPlayer } from "./Player";
 import { ATK, PDEF, SDEF } from "../presets";
 import { Effect } from "./EffectManager";
@@ -9,41 +9,68 @@ interface PlayerWithMixins extends RpgCommonPlayer {
   hasEffect(effect: string): boolean;
   coefficientElements(attackerPlayer: RpgPlayer): number;
   hp: number;
-  getFormulas(name: string): any;
-  hasEffect(effect: string): boolean; 
-}
-
-export interface IBattleManager {
-  applyDamage(attackerPlayer: RpgPlayer, skill?: any): {
-    damage: number;
-    critical: boolean;
-    elementVulnerable: boolean;
-    guard: boolean;
-    superGuard: boolean;
-  };
+  getCurrentMap(): any;
 }
 
-export function WithBattleManager<TBase extends Constructor<PlayerWithMixins>>(
-  Base: TBase
-): Constructor<IBattleManager> & TBase {
-  return class extends Base implements IBattleManager {
+/**
+ * Battle Manager Mixin
+ * 
+ * Provides battle management capabilities to any class. This mixin handles
+ * damage calculation, critical hits, elemental vulnerabilities, and guard effects.
+ * It implements a comprehensive battle system with customizable formulas and effects.
+ * 
+ * @param Base - The base class to extend with battle management
+ * @returns Extended class with battle management methods
+ * 
+ * @example
+ * ```ts
+ * class MyPlayer extends WithBattleManager(BasePlayer) {
+ *   constructor() {
+ *     super();
+ *     // Battle system is automatically initialized
+ *   }
+ * }
+ * 
+ * const player = new MyPlayer();
+ * const attacker = new MyPlayer();
+ * const result = player.applyDamage(attacker);
+ * console.log(`Damage dealt: ${result.damage}`);
+ * ```
+ */
+export function WithBattleManager<TBase extends PlayerCtor>(Base: TBase) {
+  return class extends Base {
     /**
      * Apply damage. Player will lose HP. the `attackerPlayer` parameter is the other player, the one who attacks.
      *
      * If you don't set the skill parameter, it will be a physical attack.
-     * The attack formula is already defined but you can customize it in the server options
+     * The attack formula is already defined but you can customize it in the server options.
+     * This method handles all aspects of damage calculation including critical hits,
+     * elemental vulnerabilities, guard effects, and applies the final damage to HP.
      *
+     * @param attackerPlayer - The attacking player who deals the damage
+     * @param skill - Optional skill object for magical attacks, if not provided uses physical attack
+     * @returns Object containing damage details and special effects that occurred
+     * 
+     * @example
      * ```ts
-     * player.applyDamage(attackerPlayer) // returns { damage: number }
+     * // Physical attack
+     * const result = player.applyDamage(attackerPlayer);
+     * console.log(`Physical damage: ${result.damage}, Critical: ${result.critical}`);
+     * 
+     * // Magical attack with skill
+     * const fireSkill = { id: 'fire', power: 50, element: 'fire' };
+     * const magicResult = player.applyDamage(attackerPlayer, fireSkill);
+     * console.log(`Magic damage: ${magicResult.damage}, Vulnerable: ${magicResult.elementVulnerable}`);
+     * 
+     * // Check for guard effects
+     * if (result.guard) {
+     *   console.log('Attack was partially blocked!');
+     * }
+     * if (result.superGuard) {
+     *   console.log('Attack was heavily reduced by super guard!');
+     * }
      * ```
-     *
-     * @title Apply Damage
-     * @method player.applyDamage(attackerPlayer,skill)
-     * @param {RpgPlayer} attackerPlayer The attacking player
-     * @param {any} [skill]
-     * @returns {object}
-     * @memberof BattleManager
-     * */
+     */
     applyDamage(
       attackerPlayer: RpgPlayer,
       skill?: any
@@ -56,13 +83,13 @@ export function WithBattleManager<TBase extends Constructor<PlayerWithMixins>>(
     } {
       const getParam = (player: RpgPlayer) => {
         const params = {};
-        this.parameters.forEach((val, key) => {
-          params[key] = player.param[key];
+        (this as any).parameters.forEach((val, key) => {
+          params[key] = (player as any).param[key];
         });
         return {
-          [ATK]: player.atk,
-          [PDEF]: player.pdef,
-          [SDEF]: player.sdef,
+          [ATK]: (player as any).atk,
+          [PDEF]: (player as any).pdef,
+          [SDEF]: (player as any).sdef,
           ...params,
         };
       };
@@ -87,7 +114,7 @@ export function WithBattleManager<TBase extends Constructor<PlayerWithMixins>>(
           throw new Error("Physic Formulas not exists");
         }
         damage = fn(paramA, paramB);
-        const coef = this.coefficientElements(attackerPlayer);
+        const coef = (this as any).coefficientElements(attackerPlayer);
         if (coef >= 2) {
           elementVulnerable = true;
         }
@@ -101,7 +128,7 @@ export function WithBattleManager<TBase extends Constructor<PlayerWithMixins>>(
           damage = newDamage;
         }
       }
-      if (this.hasEffect(Effect.GUARD)) {
+      if ((this as any).hasEffect(Effect.GUARD)) {
         fn = this.getFormulas("damageGuard");
         if (fn) {
           let newDamage = fn(damage, paramA, paramB);
@@ -111,11 +138,11 @@ export function WithBattleManager<TBase extends Constructor<PlayerWithMixins>>(
           damage = newDamage;
         }
       }
-      if (this.hasEffect(Effect.SUPER_GUARD)) {
+      if ((this as any).hasEffect(Effect.SUPER_GUARD)) {
         damage /= 4;
         superGuard = true;
       }
-      this.hp -= damage;
+      (this as any).hp -= damage;
       return {
         damage,
         critical,
@@ -125,9 +152,41 @@ export function WithBattleManager<TBase extends Constructor<PlayerWithMixins>>(
       };
     }
 
+    /**
+     * Get damage formulas from the current map
+     * 
+     * Retrieves the damage calculation formulas defined in the current map's configuration.
+     * These formulas are used to calculate different types of damage including physical,
+     * magical, critical hits, and guard effects. The formulas provide flexibility in
+     * customizing the battle system's damage calculations.
+     * 
+     * @param name - The name of the formula to retrieve (e.g., 'damagePhysic', 'damageSkill')
+     * @returns The formula function or undefined if not found
+     * 
+     * @example
+     * ```ts
+     * // Get physical damage formula
+     * const physicFormula = player.getFormulas('damagePhysic');
+     * if (physicFormula) {
+     *   const damage = physicFormula(attackerParams, defenderParams);
+     * }
+     * 
+     * // Get critical damage formula
+     * const criticalFormula = player.getFormulas('damageCritical');
+     * if (criticalFormula) {
+     *   const criticalDamage = criticalFormula(baseDamage, attackerParams, defenderParams);
+     * }
+     * ```
+     */
     getFormulas(name: string) {
-      const map = this.getCurrentMap(); 
+      const map = (this as any).getCurrentMap(); 
       return map.damageFormulas[name];
     }
-  };
+  } as unknown as TBase
 }
+
+/**
+ * Type helper to extract the interface from the WithBattleManager mixin
+ * This provides the type without duplicating method signatures
+ */
+export type IBattleManager = InstanceType<ReturnType<typeof WithBattleManager>>;

package/src/Player/ClassManager.ts

@@ -1,4 +1,4 @@
-import { Constructor, isString, RpgCommonPlayer } from "@rpgjs/common";
+import { Constructor, isString, PlayerCtor, RpgCommonPlayer } from "@rpgjs/common";
 
 type ClassClass = any;
 type ActorClass = any;
@@ -10,69 +10,129 @@ interface PlayerWithMixins extends RpgCommonPlayer {
   equip(item: any, equip: boolean): void;
 }
 
-export interface IClassManager {
-  setClass(_class: ClassClass | string): ClassClass;
-  setActor(actorClass: ActorClass | string): ActorClass;
-}
-
-export function WithClassManager<TBase extends Constructor<PlayerWithMixins>>(
-  Base: TBase
-): Constructor<IClassManager> & TBase {
-  return class extends Base implements IClassManager {
+/**
+ * Class Manager Mixin
+ * 
+ * Provides class and actor management capabilities to any class. This mixin handles
+ * character class assignment and actor setup, including automatic parameter configuration,
+ * starting equipment, and skill progression based on class definitions.
+ * 
+ * @param Base - The base class to extend with class management
+ * @returns Extended class with class management methods
+ * 
+ * @example
+ * ```ts
+ * class MyPlayer extends WithClassManager(BasePlayer) {
+ *   constructor() {
+ *     super();
+ *     // Class system is automatically initialized
+ *   }
+ * }
+ * 
+ * const player = new MyPlayer();
+ * player.setClass(Fighter);
+ * player.setActor(Hero);
+ * ```
+ */
+export function WithClassManager<TBase extends PlayerCtor>(Base: TBase) {
+  return class extends Base {
 
     /**
      * Assign a class to the player
      *
+     * Sets the player's class, which defines their combat abilities, stat growth,
+     * and available skills. The class system provides the foundation for character
+     * progression and specialization. When a class is set, it automatically triggers
+     * the class's onSet method for any additional initialization.
+     * 
+     * @param _class - The class constructor or class ID to assign to the player
+     * @returns The instantiated class object
+     * 
+     * @example
      * ```ts
      * import { Fighter } from 'my-database/classes/fighter'
      *
-     * player.setClass(Fighter)
+     * // Set class using constructor
+     * const fighterClass = player.setClass(Fighter);
+     * console.log('Class set:', fighterClass.name);
+     * 
+     * // Set class using string ID
+     * player.setClass('fighter');
+     * 
+     * // Class affects available skills and stats
+     * console.log('Available skills:', player.skills);
+     * console.log('Class bonuses applied to stats');
+     * 
+     * // Class determines level progression
+     * player.level = 5;
+     * // Skills may be automatically learned based on class definition
      * ```
-     *
-     * @title Set Class
-     * @method player.setClass(ClassClass)
-     * @param {ClassClass | string} class class or id
-     * @returns {instance of ClassClass}
-     * @memberof ClassManager
-     * */
+     */
     setClass(_class: ClassClass | string) {
-      if (isString(_class)) _class = this.databaseById(_class);
+      if (isString(_class)) _class = (this as any).databaseById(_class);
       const classInstance = new (_class as ClassClass)();
-      this["execMethod"]("onSet", [this], classInstance);
+      (this as any)["execMethod"]("onSet", [this], classInstance);
       return classInstance;
     }
 
     /**
      * Allows to give a set of already defined properties to the player (default equipment, or a list of skills to learn according to the level)
      *
+     * Sets up the player as a specific actor archetype, which includes predefined
+     * characteristics like starting equipment, parameters, level ranges, and associated class.
+     * This is typically used for creating pre-configured character templates or NPCs
+     * with specific roles and equipment loadouts.
+     * 
+     * @param actorClass - The actor constructor or actor ID to assign to the player
+     * @returns The instantiated actor object
+     * 
+     * @example
      * ```ts
      * import { Hero } from 'my-database/classes/hero'
      *
-     * player.setActor(Hero)
+     * // Set up player as Hero actor
+     * const heroActor = player.setActor(Hero);
+     * console.log('Actor configured:', heroActor.name);
+     * 
+     * // Actor automatically sets up:
+     * // - Starting equipment (sword, armor, etc.)
+     * console.log('Starting equipment:', player.equipments());
+     * 
+     * // - Parameter ranges and growth
+     * console.log('Level range:', player.initialLevel, '-', player.finalLevel);
+     * 
+     * // - Associated class
+     * console.log('Assigned class:', player.class);
+     * 
+     * // - Experience curve
+     * console.log('EXP curve:', player.expCurve);
+     * 
+     * // Actor setup is comprehensive
+     * player.setActor('hero'); // Can also use string ID
      * ```
-     *
-     * @title Set Actor
-     * @method player.setActor(ActorClass)
-     * @param {ActorClass | string} actorClass actor class or id
-     * @returns {instance of ActorClass}
-     * @memberof ClassManager
-     * */
+     */
     setActor(actorClass: ActorClass | string) {
-      if (isString(actorClass)) actorClass = this.databaseById(actorClass);
+      if (isString(actorClass)) actorClass = (this as any).databaseById(actorClass);
       const actor = new (actorClass as ActorClass)();
       ["name", "initialLevel", "finalLevel", "expCurve"].forEach((key) => {
-        if (actor[key]) this[key] = actor[key];
+        if (actor[key]) (this as any)[key] = actor[key];
       });
       for (let param in actor.parameters) {
-        this.addParameter(param, actor.parameters[param]);
+        (this as any).addParameter(param, actor.parameters[param]);
       }
       for (let item of actor.startingEquipment) {
-        this.addItem(item);
-        this.equip(item, true);
+        (this as any).addItem(item);
+        (this as any).equip(item, true);
       }
       if (actor.class) this.setClass(actor.class);
-      this["execMethod"]("onSet", [this], actor);
+      (this as any)["execMethod"]("onSet", [this], actor);
       return actor;
     }
-  };
+  } as unknown as TBase;
 }
+
+/**
+ * Type helper to extract the interface from the WithClassManager mixin
+ * This provides the type without duplicating method signatures
+ */
+export type IClassManager = InstanceType<ReturnType<typeof WithClassManager>>;

package/src/Player/ComponentManager.ts

@@ -1,29 +1,73 @@
-import { type Constructor } from "@rpgjs/common";
+import { Constructor, PlayerCtor } from "@rpgjs/common";
 import { RpgCommonPlayer } from "@rpgjs/common";
 
 /**
- * Interface defining what ComponentManager adds to a class
+ * Component Manager Mixin
+ * 
+ * Provides graphic management capabilities to any class. This mixin allows
+ * setting single or multiple graphics for player representation, enabling
+ * dynamic visual changes and animation sequences.
+ * 
+ * @param Base - The base class to extend with component management
+ * @returns Extended class with component management methods
+ * 
+ * @example
+ * ```ts
+ * class MyPlayer extends WithComponentManager(BasePlayer) {
+ *   constructor() {
+ *     super();
+ *     this.setGraphic("hero");
+ *   }
+ * }
+ * 
+ * const player = new MyPlayer();
+ * player.setGraphic(["hero_idle", "hero_walk"]);
+ * ```
  */
-export interface IComponentManager {
-  setGraphic(graphic: string | string[]): void;
+export function WithComponentManager<TBase extends PlayerCtor>(Base: TBase): new (...args: ConstructorParameters<TBase>) => InstanceType<TBase> & IComponentManager {
+  return class extends Base {
+    setGraphic(graphic: string | string[]): void {
+       if (Array.isArray(graphic)) {
+         this.graphics.set(graphic);
+       } else {
+         this.graphics.set([graphic]);
+       }
+     }
+  } as unknown as any;
 }
 
 /**
- * Component Manager mixin
- * 
- * Adds methods to manage player graphics
- * 
- * @param Base - The base class to extend
- * @returns A new class with component management capabilities
+ * Interface for component management capabilities
+ * Defines the method signature that will be available on the player
  */
-export function WithComponentManager<TBase extends Constructor<RpgCommonPlayer>>(Base: TBase) {
-  return class extends Base implements IComponentManager {
-    setGraphic(graphic: string | string[]) {
-      if (Array.isArray(graphic)) {
-        this.graphics.set(graphic);
-      } else {
-        this.graphics.set([graphic]);
-      }
-    }
-  };
+export interface IComponentManager {
+  /**
+     * Set the graphic(s) for this player
+     *
+     * Allows setting either a single graphic or multiple graphics for the player.
+     * When multiple graphics are provided, they are used for animation sequences.
+     * The graphics system provides flexible visual representation that can be
+     * dynamically changed during gameplay for different states, equipment, or animations.
+     *
+     * @param graphic - Single graphic name or array of graphic names for animation sequences
+     * @returns void
+     *
+     * @example
+     * ```ts
+     * // Set a single graphic for static representation
+     * player.setGraphic("hero");
+     *
+     * // Set multiple graphics for animation sequences
+     * player.setGraphic(["hero_idle", "hero_walk", "hero_run"]);
+     * 
+     * // Dynamic graphic changes based on equipment
+     * if (player.hasArmor('platemail')) {
+     *   player.setGraphic("hero_armored");
+     * }
+     * 
+     * // Animation sequences for different actions
+     * player.setGraphic(["mage_cast_1", "mage_cast_2", "mage_cast_3"]);
+     * ```
+     */
+  setGraphic(graphic: string | string[]): void;
 }