@rpgjs/server 5.0.0-alpha.21 → 5.0.0-alpha.22

package/dist/Player/BattleManager.d.ts

@@ -1,32 +1,44 @@
 import { PlayerCtor } from '@rpgjs/common';
-/**
- * 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 declare function WithBattleManager<TBase extends PlayerCtor>(Base: TBase): 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>>;
+import { RpgPlayer } from './Player';
+export interface IBattleManager {
+    /**
+      * 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.
+      * 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
+      * // 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!');
+      * }
+      * ```
+      */
+    applyDamage(attackerPlayer: RpgPlayer, skill?: any): {
+        damage: number;
+        critical: boolean;
+        elementVulnerable: boolean;
+        guard: boolean;
+        superGuard: boolean;
+    };
+}
+export declare function WithBattleManager<TBase extends PlayerCtor>(Base: TBase): new (...args: ConstructorParameters<TBase>) => InstanceType<TBase> & IBattleManager;

package/dist/Player/ClassManager.d.ts

@@ -1,4 +1,6 @@
 import { PlayerCtor } from '@rpgjs/common';
+type ClassClass = any;
+type ActorClass = any;
 /**
  * Class Manager Mixin
  *
@@ -25,7 +27,25 @@ import { PlayerCtor } from '@rpgjs/common';
  */
 export declare function WithClassManager<TBase extends PlayerCtor>(Base: TBase): TBase;
 /**
- * Type helper to extract the interface from the WithClassManager mixin
- * This provides the type without duplicating method signatures
+ * Interface for Class Manager functionality
+ *
+ * Provides class and actor management capabilities including character class assignment
+ * and actor setup. This interface defines the public API of the ClassManager mixin.
  */
-export type IClassManager = InstanceType<ReturnType<typeof WithClassManager>>;
+export interface IClassManager {
+    /**
+     * Assign a class to the player
+     *
+     * @param _class - The class constructor or class ID to assign to the player
+     * @returns The instantiated class object
+     */
+    setClass(_class: ClassClass | string): any;
+    /**
+     * Set up the player as a specific actor archetype
+     *
+     * @param actorClass - The actor constructor or actor ID to assign to the player
+     * @returns The instantiated actor object
+     */
+    setActor(actorClass: ActorClass | string): any;
+}
+export {};

package/dist/Player/EffectManager.d.ts

@@ -34,7 +34,53 @@ export declare enum Effect {
  */
 export declare function WithEffectManager<TBase extends PlayerCtor>(Base: TBase): TBase;
 /**
- * Type helper to extract the interface from the WithEffectManager mixin
- * This provides the type without duplicating method signatures
+ * Interface for Effect Manager functionality
+ *
+ * Provides effect management capabilities including restrictions, buffs, and debuffs.
+ * This interface defines the public API of the EffectManager mixin.
  */
-export type IEffectManager = InstanceType<ReturnType<typeof WithEffectManager>>;
+export interface IEffectManager {
+    /**
+     * 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
+     */
+    effects: any[];
+    /**
+     * 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'
+     *
+     * // 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);
+     * ```
+     */
+    hasEffect(effect: string): boolean;
+}

package/dist/Player/ElementManager.d.ts

@@ -1,4 +1,5 @@
 import { PlayerCtor } from '@rpgjs/common';
+import { RpgPlayer } from './Player';
 /**
  * Element Manager Mixin
  *
@@ -25,7 +26,79 @@ import { PlayerCtor } from '@rpgjs/common';
  */
 export declare function WithElementManager<TBase extends PlayerCtor>(Base: TBase): TBase;
 /**
- * Type helper to extract the interface from the WithElementManager mixin
- * This provides the type without duplicating method signatures
+ * Interface for Element Manager functionality
+ *
+ * Provides elemental management capabilities including resistances, vulnerabilities,
+ * and attack elements. This interface defines the public API of the ElementManager mixin.
  */
-export type IElementManager = InstanceType<ReturnType<typeof WithElementManager>>;
+export interface IElementManager {
+    /**
+     * Gets the defensive capabilities against various elements from equipped items.
+     * The system automatically consolidates multiple defensive items, keeping only
+     * the highest protection rate for each element type.
+     *
+     * @returns Array of element defense objects with rate and element properties
+     */
+    elementsDefense: {
+        rate: number;
+        element: any;
+    }[];
+    /**
+     * Manages the player's elemental efficiency modifiers, which determine how
+     * effective different elements are against this player. Values greater than 1
+     * indicate vulnerability, while values less than 1 indicate resistance.
+     * This combines both class-based efficiency and player-specific modifiers.
+     *
+     * @returns Array of element efficiency objects with rate and element properties
+     */
+    elementsEfficiency: {
+        rate: number;
+        element: any;
+    }[];
+    /**
+     * Gets all offensive elements available to the player from equipped weapons and armor.
+     * This determines what elemental damage types the player can deal in combat.
+     * The system automatically combines elements from all equipped items and removes duplicates.
+     *
+     * @returns Array of element objects with rate and element properties for offensive capabilities
+     */
+    elements: {
+        rate: number;
+        element: string;
+    }[];
+    /**
+     * Calculate elemental damage coefficient against another player
+     *
+     * Determines the damage multiplier when this player attacks another player,
+     * taking into account the attacker's offensive elements, the defender's
+     * elemental efficiency, and elemental defense from equipment. This is used
+     * in the battle system to calculate elemental damage modifiers.
+     *
+     * @param otherPlayer - The target player to calculate coefficient against
+     * @returns Numerical coefficient to multiply base damage by
+     *
+     * @example
+     * ```ts
+     * // Calculate elemental damage coefficient
+     * const firePlayer = new MyPlayer();
+     * const icePlayer = new MyPlayer();
+     *
+     * // Fire player attacks ice player (assuming ice is weak to fire)
+     * const coefficient = icePlayer.coefficientElements(firePlayer);
+     * console.log(`Damage multiplier: ${coefficient}`); // e.g., 2.0 for double damage
+     *
+     * // Use in damage calculation
+     * const baseDamage = 100;
+     * const finalDamage = baseDamage * coefficient;
+     * console.log(`Final damage: ${finalDamage}`);
+     *
+     * // Check for elemental advantage
+     * if (coefficient > 1) {
+     *   console.log('Attacker has elemental advantage!');
+     * } else if (coefficient < 1) {
+     *   console.log('Defender resists this element');
+     * }
+     * ```
+     */
+    coefficientElements(otherPlayer: RpgPlayer): number;
+}

package/dist/Player/ItemManager.d.ts

@@ -1,4 +1,5 @@
-import { PlayerCtor } from '@rpgjs/common';
+import { Item, PlayerCtor } from '@rpgjs/common';
+import { ItemClass } from '@rpgjs/database';
 import { RpgPlayer } from './Player';
 /**
  * Interface defining the hooks that can be implemented on item classes or objects
@@ -165,7 +166,294 @@ export type ItemObject<T extends ItemData = ItemData> = T & ItemHooks & {
  */
 export declare function WithItemManager<TBase extends PlayerCtor>(Base: TBase): TBase;
 /**
- * Type helper to extract the interface from the WithItemManager mixin
- * This provides the type without duplicating method signatures
+ * Interface for Item Manager functionality
+ *
+ * Provides comprehensive item management capabilities including inventory management,
+ * item usage, equipment, buying/selling, and item effects. This interface defines
+ * the public API of the ItemManager mixin.
  */
-export type IItemManager = InstanceType<ReturnType<typeof WithItemManager>>;
+export interface IItemManager {
+    /**
+     * Retrieves the information of an object: the number and the instance
+     *
+     * The returned Item instance contains the quantity information accessible via `quantity()` method.
+     *
+     * @param itemClass - Item class or string identifier. If string, it's the item ID
+     * @returns Item instance containing quantity and item data
+     *
+     * @example
+     * ```ts
+     * import Potion from 'your-database/potion'
+     *
+     * player.addItem(Potion, 5)
+     * const inventory = player.getItem(Potion)
+     * console.log(inventory.quantity()) // 5
+     * console.log(inventory) // <instance of Item>
+     * ```
+     */
+    getItem(itemClass: ItemClass | string): Item;
+    /**
+     * Check if the player has the item in his inventory
+     *
+     * @param itemClass - Item class or string identifier. If string, it's the item ID
+     * @returns `true` if player has the item, `false` otherwise
+     *
+     * @example
+     * ```ts
+     * import Potion from 'your-database/potion'
+     *
+     * player.hasItem(Potion) // false
+     * player.addItem(Potion, 1)
+     * player.hasItem(Potion) // true
+     * ```
+     */
+    hasItem(itemClass: ItemClass | string): boolean;
+    /**
+     * Add an item in the player's inventory
+     *
+     * You can add items using:
+     * - Item class (automatically registered in database if needed)
+     * - Item object (automatically registered in database if needed)
+     * - String ID (must be pre-registered in database)
+     *
+     * The `onAdd()` method is called on the ItemClass or ItemObject when the item is added.
+     *
+     * @param item - Item class, object, or string identifier
+     * @param nb - Number of items to add (default: 1)
+     * @returns The item instance added to inventory
+     *
+     * @example
+     * ```ts
+     * import Potion from 'your-database/potion'
+     *
+     * // Add using class
+     * player.addItem(Potion, 5)
+     *
+     * // Add using string ID (must be registered in database)
+     * player.addItem('Potion', 3)
+     *
+     * // Add using object
+     * player.addItem({
+     *   id: 'custom-potion',
+     *   name: 'Custom Potion',
+     *   price: 200,
+     *   onAdd(player) {
+     *     console.log('Custom potion added!')
+     *   }
+     * }, 2)
+     * ```
+     */
+    addItem(item: ItemClass | ItemObject | string, nb?: number): Item;
+    /**
+     * Deletes an item from inventory
+     *
+     * Decreases the quantity by `nb`. If the quantity falls to 0 or below, the item is removed from the inventory.
+     * The method returns `undefined` if the item is completely removed.
+     *
+     * The `onRemove()` method is called on the ItemClass when the item is removed.
+     *
+     * @param itemClass - Item class or string identifier. If string, it's the item ID
+     * @param nb - Number of items to remove (default: 1)
+     * @returns Item instance or `undefined` if the item was completely removed
+     * @throws {Object} ItemLog.notInInventory - If the item is not in the inventory
+     *   - `id`: `ITEM_NOT_INVENTORY`
+     *   - `msg`: Error message
+     *
+     * @example
+     * ```ts
+     * import Potion from 'your-database/potion'
+     *
+     * try {
+     *   player.removeItem(Potion, 5)
+     * } catch (err) {
+     *   console.log(err) // { id: 'ITEM_NOT_INVENTORY', msg: '...' }
+     * }
+     * ```
+     */
+    removeItem(itemClass: ItemClass | string, nb?: number): Item | undefined;
+    /**
+     * Purchases an item and reduces the amount of gold
+     *
+     * The player's gold is reduced by `nb * item.price`. The item is then added to the inventory.
+     * The `onAdd()` method is called on the ItemClass when the item is added.
+     *
+     * @param item - Item class, object, or string identifier
+     * @param nb - Number of items to buy (default: 1)
+     * @returns Item instance added to inventory
+     * @throws {Object} ItemLog.haveNotPrice - If the item has no price set
+     *   - `id`: `NOT_PRICE`
+     *   - `msg`: Error message
+     * @throws {Object} ItemLog.notEnoughGold - If the player doesn't have enough gold
+     *   - `id`: `NOT_ENOUGH_GOLD`
+     *   - `msg`: Error message
+     *
+     * @example
+     * ```ts
+     * import Potion from 'your-database/potion'
+     *
+     * try {
+     *   player.buyItem(Potion)
+     * } catch (err) {
+     *   if (err.id === 'NOT_ENOUGH_GOLD') {
+     *     console.log('Not enough gold!')
+     *   } else if (err.id === 'NOT_PRICE') {
+     *     console.log('Item has no price!')
+     *   }
+     * }
+     * ```
+     */
+    buyItem(item: ItemClass | ItemObject | string, nb?: number): Item;
+    /**
+     * Sell an item and the player wins the amount of the item divided by 2
+     *
+     * The player receives `(item.price / 2) * nbToSell` gold. The item is removed from the inventory.
+     * The `onRemove()` method is called on the ItemClass when the item is removed.
+     *
+     * @param itemClass - Item class or string identifier. If string, it's the item ID
+     * @param nbToSell - Number of items to sell (default: 1)
+     * @returns Item instance that was sold
+     * @throws {Object} ItemLog.haveNotPrice - If the item has no price set
+     *   - `id`: `NOT_PRICE`
+     *   - `msg`: Error message
+     * @throws {Object} ItemLog.notInInventory - If the item is not in the inventory
+     *   - `id`: `ITEM_NOT_INVENTORY`
+     *   - `msg`: Error message
+     * @throws {Object} ItemLog.tooManyToSell - If trying to sell more items than available
+     *   - `id`: `TOO_MANY_ITEM_TO_SELL`
+     *   - `msg`: Error message
+     *
+     * @example
+     * ```ts
+     * import Potion from 'your-database/potion'
+     *
+     * try {
+     *   player.addItem(Potion)
+     *   player.sellItem(Potion)
+     * } catch (err) {
+     *   console.log(err)
+     * }
+     * ```
+     */
+    sellItem(itemClass: ItemClass | string, nbToSell?: number): Item;
+    /**
+     * Use an object. Applies effects and states. Removes the object from the inventory
+     *
+     * When an item is used:
+     * - Effects are applied to the player (HP/MP restoration, etc.)
+     * - States are applied/removed as defined in the item
+     * - The item is removed from inventory (consumed)
+     *
+     * If the item has a `hitRate` property (0-1), there's a chance the usage might fail.
+     * If usage fails, the item is still removed and `onUseFailed()` is called instead of `onUse()`.
+     *
+     * The `onUse()` method is called on the ItemClass if the use was successful.
+     * The `onUseFailed()` method is called on the ItemClass if the chance roll failed.
+     * The `onRemove()` method is called on the ItemClass when the item is removed.
+     *
+     * @param itemClass - Item class or string identifier. If string, it's the item ID
+     * @returns Item instance that was used
+     * @throws {Object} ItemLog.restriction - If the player has the `Effect.CAN_NOT_ITEM` effect
+     *   - `id`: `RESTRICTION_ITEM`
+     *   - `msg`: Error message
+     * @throws {Object} ItemLog.notInInventory - If the item is not in the inventory
+     *   - `id`: `ITEM_NOT_INVENTORY`
+     *   - `msg`: Error message
+     * @throws {Object} ItemLog.notUseItem - If the item's `consumable` property is `false`
+     *   - `id`: `NOT_USE_ITEM`
+     *   - `msg`: Error message
+     * @throws {Object} ItemLog.chanceToUseFailed - If the chance to use the item failed (hitRate roll failed)
+     *   - `id`: `USE_CHANCE_ITEM_FAILED`
+     *   - `msg`: Error message
+     *   - Note: The item is still deleted from the inventory even if usage failed
+     *
+     * @example
+     * ```ts
+     * import Potion from 'your-database/potion'
+     *
+     * try {
+     *   player.addItem(Potion)
+     *   player.useItem(Potion)
+     * } catch (err) {
+     *   if (err.id === 'USE_CHANCE_ITEM_FAILED') {
+     *     console.log('Item usage failed due to chance roll')
+     *   } else {
+     *     console.log(err)
+     *   }
+     * }
+     * ```
+     */
+    useItem(itemClass: ItemClass | string): Item;
+    /**
+     * Equips a weapon or armor on a player
+     *
+     * Think first to add the item in the inventory with the `addItem()` method before equipping the item.
+     *
+     * The `onEquip()` method is called on the ItemClass when the item is equipped or unequipped.
+     *
+     * @param itemClass - Item class or string identifier. If string, it's the item ID
+     * @param equip - Equip the item if `true`, unequip if `false` (default: `true`)
+     * @throws {Object} ItemLog.notInInventory - If the item is not in the inventory
+     *   - `id`: `ITEM_NOT_INVENTORY`
+     *   - `msg`: Error message
+     * @throws {Object} ItemLog.invalidToEquiped - If the item is not a weapon or armor (item._type is "item")
+     *   - `id`: `INVALID_ITEM_TO_EQUIP`
+     *   - `msg`: Error message
+     * @throws {Object} ItemLog.isAlreadyEquiped - If the item is already equipped
+     *   - `id`: `ITEM_ALREADY_EQUIPED`
+     *   - `msg`: Error message
+     *
+     * @example
+     * ```ts
+     * import Sword from 'your-database/sword'
+     *
+     * try {
+     *   player.addItem(Sword)
+     *   player.equip(Sword)
+     *   // Later, unequip it
+     *   player.equip(Sword, false)
+     * } catch (err) {
+     *   console.log(err)
+     * }
+     * ```
+     */
+    equip(itemClass: ItemClass | string, equip?: boolean): void;
+    /**
+     * Get the player's attack (sum of items equipped)
+     *
+     * Returns the total attack value from all equipped items on the player.
+     *
+     * @returns Total attack value from equipped items
+     *
+     * @example
+     * ```ts
+     * console.log(player.atk) // 150 (sum of all equipped weapons/armors attack)
+     * ```
+     */
+    readonly atk: number;
+    /**
+     * Get the player's physical defense (sum of items equipped)
+     *
+     * Returns the total physical defense value from all equipped items on the player.
+     *
+     * @returns Total physical defense value from equipped items
+     *
+     * @example
+     * ```ts
+     * console.log(player.pdef) // 80 (sum of all equipped armors physical defense)
+     * ```
+     */
+    readonly pdef: number;
+    /**
+     * Get the player's skill defense (sum of items equipped)
+     *
+     * Returns the total skill defense value from all equipped items on the player.
+     *
+     * @returns Total skill defense value from equipped items
+     *
+     * @example
+     * ```ts
+     * console.log(player.sdef) // 60 (sum of all equipped armors skill defense)
+     * ```
+     */
+    readonly sdef: number;
+}