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

package/src/Player/ItemManager.ts

@@ -1,8 +1,8 @@
-import { isInstanceOf, isString, Item, PlayerCtor, type Constructor } from "@rpgjs/common";
-import { RpgCommonPlayer, Matter } from "@rpgjs/common";
-import { ATK, PDEF, SDEF } from "../presets";
+import { isInstanceOf, isString, Item, type PlayerCtor} from "@rpgjs/common";
+import { ATK, PDEF, SDEF } from "@rpgjs/common";
 import { ItemLog } from "../logs";
-import { ArmorInstance, ItemClass, ItemInstance, WeaponInstance } from "@rpgjs/database";
+import type { ItemClass, ItemInstance } from "@rpgjs/database";
+import { RpgPlayer } from "./Player";
 
 // Ajout des enums manquants
 enum Effect {
@@ -15,6 +15,152 @@ enum ClassHooks {
 
 type Inventory = { nb: number; item: ItemInstance };
 
+/**
+ * Interface defining the hooks that can be implemented on item classes or objects
+ * 
+ * These hooks are called at specific moments during the item lifecycle:
+ * - `onAdd`: When the item is added to the player's inventory
+ * - `onUse`: When the item is successfully used
+ * - `onUseFailed`: When the item usage fails (e.g., chance roll failed)
+ * - `onRemove`: When the item is removed from the inventory
+ * - `onEquip`: When the item is equipped or unequipped
+ * 
+ * @example
+ * ```ts
+ * const itemHooks: ItemHooks = {
+ *   onAdd(player) {
+ *     console.log('Item added to inventory');
+ *   },
+ *   onUse(player) {
+ *     player.hp += 100;
+ *   }
+ * };
+ * ```
+ */
+export interface ItemHooks {
+  /**
+   * Called when the item is added to the player's inventory
+   * 
+   * @param player - The player receiving the item
+   */
+  onAdd?: (player: RpgPlayer) => void | Promise<void>;
+
+  /**
+   * Called when the item is successfully used
+   * 
+   * @param player - The player using the item
+   */
+  onUse?: (player: RpgPlayer) => void | Promise<void>;
+
+  /**
+   * Called when the item usage fails (e.g., chance roll failed)
+   * 
+   * @param player - The player attempting to use the item
+   */
+  onUseFailed?: (player: RpgPlayer) => void | Promise<void>;
+
+  /**
+   * Called when the item is removed from the inventory
+   * 
+   * @param player - The player losing the item
+   */
+  onRemove?: (player: RpgPlayer) => void | Promise<void>;
+
+  /**
+   * Called when the item is equipped or unequipped
+   * 
+   * @param player - The player equipping/unequipping the item
+   * @param equip - true if equipping, false if unequipping
+   */
+  onEquip?: (player: RpgPlayer, equip: boolean) => void | Promise<void>;
+}
+
+/**
+ * Base properties that can be included in an item object
+ * 
+ * This interface defines the common properties that items can have.
+ * Use this as a base and extend it with specific item types.
+ * 
+ * @template T - Additional properties specific to the item type
+ * 
+ * @example
+ * ```ts
+ * interface PotionData extends ItemData {
+ *   hpValue: number;
+ *   mpValue: number;
+ * }
+ * 
+ * const potion: ItemObject<PotionData> = {
+ *   name: 'Health Potion',
+ *   description: 'Restores 100 HP',
+ *   price: 200,
+ *   hpValue: 100,
+ *   mpValue: 0,
+ *   onUse(player) {
+ *     player.hp += this.hpValue;
+ *   }
+ * };
+ * ```
+ */
+export interface ItemData {
+  /** Item name */
+  name?: string;
+  /** Item description */
+  description?: string;
+  /** Item price */
+  price?: number;
+  /** HP value restored when used */
+  hpValue?: number;
+  /** MP/SP value restored when used */
+  mpValue?: number;
+  /** Chance to successfully use the item (0-1) */
+  hitRate?: number;
+  /** Whether the item is consumable */
+  consumable?: boolean;
+  /** States to add when used */
+  addStates?: any[];
+  /** States to remove when used */
+  removeStates?: any[];
+  /** Elemental properties */
+  elements?: any[];
+  /** Parameter modifiers */
+  paramsModifier?: Record<string, any>;
+  /** Item type (for equipment validation) */
+  _type?: 'item' | 'weapon' | 'armor';
+}
+
+/**
+ * Item object type that combines data properties with hooks
+ * 
+ * This type allows you to create item objects directly without needing a class.
+ * The object can contain both item data properties and lifecycle hooks.
+ * 
+ * @template T - Additional properties specific to the item type (extends ItemData)
+ * 
+ * @example
+ * ```ts
+ * const potion: ItemObject = {
+ *   name: 'Health Potion',
+ *   description: 'Restores 100 HP',
+ *   price: 200,
+ *   hpValue: 100,
+ *   consumable: true,
+ *   onAdd(player) {
+ *     console.log('Potion added!');
+ *   },
+ *   onUse(player) {
+ *     player.hp += 100;
+ *   }
+ * };
+ * 
+ * player.addItem(potion);
+ * ```
+ */
+export type ItemObject<T extends ItemData = ItemData> = T & ItemHooks & {
+  /** Item identifier (required if not using class or string) */
+  id?: string;
+};
+
 /**
  * Item Manager Mixin
  *
@@ -42,43 +188,11 @@ type Inventory = { nb: number; item: ItemInstance };
 export function WithItemManager<TBase extends PlayerCtor>(Base: TBase) {
   return class extends Base {
 
-    /**
-     * Retrieves the information of an object: the number and the instance
-     * @title Get Item
-     * @method player.getItem(itemClass)
-     * @param {ItemClass | string} itemClass Identifier of the object if the parameter is a string
-     * @returns {{ nb: number, item: instance of ItemClass }}
-     * @memberof ItemManager
-     * @example
-     *
-     * ```ts
-     * import Potion from 'your-database/potion'
-     *
-     * player.addItem(Potion, 5)
-     * const inventory = player.getItem(Potion)
-     * console.log(inventory) // { nb: 5, item: <instance of Potion> }
-     *  ```
-     */
     getItem(itemClass: ItemClass | string): Item {
       const index: number = this._getItemIndex(itemClass);
       return (this as any).items()[index];
     }
 
-    /**
-     * Check if the player has the item in his inventory.
-     * @title Has Item
-     * @method player.hasItem(itemClass)
-     * @param {ItemClass | string} itemClass Identifier of the object if the parameter is a string
-     * @returns {boolean}
-     * @memberof ItemManager
-     * @example
-     *
-     * ```ts
-     * import Potion from 'your-database/potion'
-     *
-     * player.hasItem(Potion) // false
-     *  ```
-     */
     hasItem(itemClass: ItemClass | string): boolean {
       return !!this.getItem(itemClass);
     }
@@ -91,72 +205,237 @@ export function WithItemManager<TBase extends PlayerCtor>(Base: TBase) {
         return isInstanceOf(it, itemClass);
       });
     }
+
+    private _getItemMap(required: boolean = true) {
+      // Use this.map directly to support both RpgMap and LobbyRoom
+      const map = (this as any).getCurrentMap?.() || (this as any).map;
+      if (required && (!map || !map.database)) {
+        throw new Error('Player must be on a map to add items');
+      }
+      return map;
+    }
+
+    private _resolveItemInput(
+      item: ItemClass | ItemObject | string,
+      map: any,
+      databaseByIdOverride?: (id: string) => any
+    ) {
+      let itemId: string;
+      let data: any;
+      let itemInstance: any = null;
+
+      if (isString(item)) {
+        itemId = item as string;
+        data = databaseByIdOverride
+          ? databaseByIdOverride(itemId)
+          : (this as any).databaseById(itemId);
+      } else if (typeof item === 'function' || (item as any).prototype) {
+        itemId = (item as any).name;
+
+        const existingData = map.database()[itemId];
+        if (existingData) {
+          data = existingData;
+        } else {
+          map.addInDatabase(itemId, item as ItemClass);
+          data = item as ItemClass;
+        }
+
+        itemInstance = new (item as ItemClass)();
+      } else {
+        const itemObj = item as ItemObject;
+        itemId = itemObj.id || `item-${Date.now()}`;
+
+        const existingData = map.database()[itemId];
+        if (existingData) {
+          data = { ...existingData, ...itemObj };
+          map.addInDatabase(itemId, data, { force: true });
+        } else {
+          map.addInDatabase(itemId, itemObj);
+          data = itemObj;
+        }
+
+        itemInstance = itemObj;
+      }
+
+      return { itemId, data, itemInstance };
+    }
+
+    private _createItemInstance(
+      itemId: string,
+      data: any,
+      nb: number,
+      itemInstance: any
+    ): Item {
+      const instance = new Item(data);
+      instance.id.set(itemId);
+      instance.quantity.set(nb);
+
+      if (itemInstance) {
+        (instance as any)._itemInstance = itemInstance;
+        if (itemInstance.onAdd) {
+          instance.onAdd = itemInstance.onAdd.bind(itemInstance);
+        }
+      }
+
+      return instance;
+    }
+
     /**
-     * Add an item in the player's inventory. You can give more than one by specifying `nb`
-     *
-     * `onAdd()` method is called on the ItemClass
-     *
-     * @title Add Item
-     * @method player.addItem(item,nb=1)
-     * @param {ItemClass} itemClass
-     * @param {number} [nb] Default 1
-     * @returns {{ nb: number, item: instance of ItemClass }}
-     * @memberof ItemManager
-     * @example
-     *
-     * ```ts
-     * import Potion from 'your-database/potion'
-     * player.addItem(Potion, 5)
-     *  ```
+     * Create an item instance without inventory changes or hook execution.
      */
-    addItem(itemId: string, nb: number = 1): Item {
-      const data = (this as any).databaseById(itemId);
-      const item = (this as any).items().find((it) => it.id() == itemId);
+    createItemInstance(item: ItemClass | ItemObject | string, nb: number = 1) {
+      const map = this._getItemMap();
+      const { itemId, data, itemInstance } = this._resolveItemInput(item, map);
+      const instance = this._createItemInstance(itemId, data, nb, itemInstance);
+      return { itemId, data, itemInstance, instance };
+    }
+
+    /**
+     * Resolve item snapshot entries into Item instances without side effects.
+     */
+    resolveItemsSnapshot(snapshot: { items?: any[] }, mapOverride?: any) {
+      if (!snapshot || !Array.isArray(snapshot.items)) {
+        return snapshot;
+      }
+
+      const map = mapOverride ?? this._getItemMap(false);
+      if (!map || !map.database) {
+        return snapshot;
+      }
+
+      const databaseByIdOverride = (id: string) => {
+        const data = map.database()[id];
+        if (!data) {
+          throw new Error(
+            `The ID=${id} data is not found in the database. Add the data in the property "database"`
+          );
+        }
+        return data;
+      };
+
+      const items = snapshot.items.map((entry: any) => {
+        const itemId = isString(entry) ? entry : entry?.id;
+        if (!itemId) {
+          return entry;
+        }
+
+        const nb =
+          !isString(entry) && typeof entry?.nb === 'number'
+            ? entry.nb
+            : !isString(entry) && typeof entry?.quantity === 'number'
+              ? entry.quantity
+              : 1;
+
+        const { data, itemInstance } = this._resolveItemInput(
+          itemId,
+          map,
+          databaseByIdOverride
+        );
+        return this._createItemInstance(itemId, data, nb, itemInstance);
+      });
+
+      return { ...snapshot, items };
+    }
+
+    /**
+     * Resolve equipment snapshot entries into Item instances without side effects.
+     */
+    resolveEquipmentsSnapshot(snapshot: { equipments?: any[]; items?: any[] }, mapOverride?: any) {
+      if (!snapshot || !Array.isArray(snapshot.equipments)) {
+        return snapshot;
+      }
+
+      const map = mapOverride ?? this._getItemMap(false);
+      if (!map || !map.database) {
+        return snapshot;
+      }
+
+      const databaseByIdOverride = (id: string) => {
+        const data = map.database()[id];
+        if (!data) {
+          throw new Error(
+            `The ID=${id} data is not found in the database. Add the data in the property "database"`
+          );
+        }
+        return data;
+      };
+
+      const resolvedItems = Array.isArray(snapshot.items) ? snapshot.items : [];
+      const getItemId = (entry: any) => {
+        if (isString(entry)) return entry;
+        if (typeof entry?.id === 'function') return entry.id();
+        return entry?.id;
+      };
+
+      const equipments = snapshot.equipments.map((entry: any) => {
+        const itemId = getItemId(entry);
+        if (!itemId) {
+          return entry;
+        }
+
+        const existing = resolvedItems.find((item: any) => {
+          const existingId = getItemId(item);
+          return existingId === itemId;
+        });
+        if (existing) {
+          return existing;
+        }
+
+        const { data, itemInstance } = this._resolveItemInput(
+          itemId,
+          map,
+          databaseByIdOverride
+        );
+        return this._createItemInstance(itemId, data, 1, itemInstance);
+      });
+
+      return { ...snapshot, equipments };
+    }
+    addItem(item: ItemClass | ItemObject | string, nb: number = 1): Item {
+      const map = this._getItemMap();
+      const { itemId, data, itemInstance } = this._resolveItemInput(item, map);
+
+      // Find existing item in inventory
+      const existingItem = (this as any).items().find((it: Item) => it.id() == itemId);
       let instance: Item;
-      if (item) {
-        instance = item;
+
+      if (existingItem) {
+        // Item already exists, update quantity and merge properties
+        instance = existingItem;
         instance.quantity.update((it) => it + nb);
+        
+        // Update item properties from merged data (e.g., name, description, price)
+        if (data.name !== undefined) {
+          instance.name.set(data.name);
+        }
+        if (data.description !== undefined) {
+          instance.description.set(data.description);
+        }
+        if (data.price !== undefined) {
+          instance.price.set(data.price);
+        }
+        
+        // Update stored instance if it's an object with hooks
+        if (itemInstance && typeof itemInstance === 'object' && !(itemInstance instanceof Function)) {
+          (instance as any)._itemInstance = itemInstance;
+          // Update hooks if they exist
+          if (itemInstance.onAdd) {
+            instance.onAdd = itemInstance.onAdd.bind(itemInstance);
+          }
+        }
       } else {
-        instance = new Item(data);
-        instance.id.set(itemId);
+        // Create new item instance
+        instance = this._createItemInstance(itemId, data, nb, itemInstance);
         (this as any).items().push(instance);
       }
-      (this as any)["execMethod"]("onAdd", [this], instance);
+
+      // Call onAdd hook - use stored instance if available
+      const hookTarget = (instance as any)._itemInstance || instance;
+      // Only call onAdd if it exists and is a function
+      (this as any)["execMethod"]("onAdd", [this], hookTarget);
       return instance;
     }
 
-    /**
-     * Deletes an item. Decreases the value `nb`. If the number falls to 0, then the item is removed from the inventory. The method then returns `undefined`
-     *
-     * `onRemove()` method is called on the ItemClass
-     *
-     * @title Remove Item
-     * @method player.removeItem(item,nb=1)
-     * @param {ItemClass | string} itemClass string is item id
-     * @param {number} [nb] Default 1
-     * @returns {{ nb: number, item: instance of ItemClass } | undefined}
-     * @throws {ItemLog} notInInventory
-     * If the object is not in the inventory, an exception is raised
-     *  ```
-     * {
-     *      id: ITEM_NOT_INVENTORY,
-     *      msg: '...'
-     * }
-     * ```
-     * @memberof ItemManager
-     * @example
-     *
-     * ```ts
-     * import Potion from 'your-database/potion'
-     *
-     * try {
-     *    player.removeItem(Potion, 5)
-     * }
-     * catch (err) {
-     *    console.log(err)
-     * }
-     * ```
-     */
     removeItem(
       itemClass: ItemClass | string,
       nb: number = 1
@@ -172,52 +451,35 @@ export function WithItemManager<TBase extends PlayerCtor>(Base: TBase) {
       } else {
         this.items()[itemIndex].quantity.update((it) => it - nb);
       }
-      this["execMethod"]("onRemove", [this], item);
+      // Call onRemove hook - use stored instance if available
+      const hookTarget = (item as any)._itemInstance || item;
+      if (hookTarget && typeof hookTarget.onRemove === 'function') {
+        this["execMethod"]("onRemove", [this], hookTarget);
+      }
       return this.items()[itemIndex];
     }
 
-    /**
-     * Purchases an item and reduces the amount of gold
-     *
-     * `onAdd()` method is called on the ItemClass
-     *
-     * @title Buy Item
-     * @method player.buyItem(item,nb=1)
-     * @param {ItemClass | string} itemClass string is item id
-     * @param {number} [nb] Default 1
-     * @returns {{ nb: number, item: instance of ItemClass }}
-     * @throws {ItemLog} haveNotPrice
-     * If you have not set a price on the item
-     *  ```
-     * {
-     *      id: NOT_PRICE,
-     *      msg: '...'
-     * }
-     * ```
-     * @throws {ItemLog} notEnoughGold
-     * If the player does not have enough money
-     *  ```
-     * {
-     *      id: NOT_ENOUGH_GOLD,
-     *      msg: '...'
-     * }
-     * ```
-     * @memberof ItemManager
-     * @example
-     *
-     * ```ts
-     * import Potion from 'your-database/potion'
-     *
-     * try {
-     *    player.buyItem(Potion)
-     * }
-     * catch (err) {
-     *    console.log(err)
-     * }
-     * ```
-     */
-    buyItem(itemId: string, nb = 1): Item {
-      const data = (this as any).databaseById(itemId);
+    buyItem(item: ItemClass | ItemObject | string, nb = 1): Item {
+      let itemId: string;
+      let data: any;
+      
+      if (isString(item)) {
+        itemId = item as string;
+        data = (this as any).databaseById(itemId);
+      } else if (typeof item === 'function' || (item as any).prototype) {
+        itemId = (item as any).name;
+        data = (this as any).databaseById(itemId);
+      } else {
+        const itemObj = item as ItemObject;
+        itemId = itemObj.id || `item-${Date.now()}`;
+        try {
+          const dbData = (this as any).databaseById(itemId);
+          data = { ...dbData, ...itemObj };
+        } catch {
+          data = itemObj;
+        }
+      }
+      
       if (!data.price) {
         throw ItemLog.haveNotPrice(itemId);
       }
@@ -226,61 +488,13 @@ export function WithItemManager<TBase extends PlayerCtor>(Base: TBase) {
         throw ItemLog.notEnoughGold(itemId, nb);
       }
       this._gold.update((gold) => gold - totalPrice);
-      return this.addItem(itemId, nb);
+      return this.addItem(item, nb);
     }
 
-    /**
-     * Sell an item and the player wins the amount of the item divided by 2
-     *
-     * `onRemove()` method is called on the ItemClass
-     *
-     * @title Sell Item
-     * @method player.sellItem(item,nb=1)
-     * @param {ItemClass | string} itemClass string is item id
-     * @param {number} [nbToSell] Default 1
-     * @returns {{ nb: number, item: instance of ItemClass }}
-     * @throws {ItemLog} haveNotPrice
-     * If you have not set a price on the item
-     *   ```
-     * {
-     *      id: NOT_PRICE,
-     *      msg: '...'
-     * }
-     * ```
-     * @throws {ItemLog} notInInventory
-     * If the object is not in the inventory, an exception is raised
-     *  ```
-     * {
-     *      id: ITEM_NOT_INVENTORY,
-     *      msg: '...'
-     * }
-     * ```
-     * @throws {ItemLog} tooManyToSell
-     * If the number of items for sale exceeds the number of actual items in the inventory
-     *  ```
-     * {
-     *      id: TOO_MANY_ITEM_TO_SELL,
-     *      msg: '...'
-     * }
-     * ```
-     * @memberof ItemManager
-     * @example
-     *
-     * ```ts
-     * import Potion from 'your-database/potion'
-     *
-     * try {
-     *     player.addItem(Potion)
-     *     player.sellItem(Potion)
-     * }
-     * catch (err) {
-     *    console.log(err)
-     * }
-     * ```
-     */
-    sellItem(itemId: string, nbToSell = 1): Item {
+    sellItem(itemClass: ItemClass | string, nbToSell = 1): Item {
+      const itemId = isString(itemClass) ? itemClass : (itemClass as any).name;
       const data = (this as any).databaseById(itemId);
-      const inventory = this.getItem(itemId);
+      const inventory = this.getItem(itemClass);
       if (!inventory) {
         throw ItemLog.notInInventory(itemId);
       }
@@ -292,14 +506,20 @@ export function WithItemManager<TBase extends PlayerCtor>(Base: TBase) {
         throw ItemLog.haveNotPrice(itemId);
       }
       this._gold.update((gold) => gold + (data.price / 2) * nbToSell);
-      this.removeItem(itemId, nbToSell);
+      this.removeItem(itemClass, nbToSell);
       return inventory;
     }
 
     getParamItem(name: string): number {
       let nb = 0;
       for (let item of this.equipments()) {
-        nb += item[name] || 0;
+        // Retrieve item data from database to get properties like atk, pdef, sdef
+        try {
+          const itemData = (this as any).databaseById(item.id());
+          nb += itemData[name] || 0;
+        } catch {
+          // If item not in database, skip it
+        }
       }
       const modifier = (this as any).paramsModifier?.[name];
       if (modifier) {
@@ -309,183 +529,71 @@ export function WithItemManager<TBase extends PlayerCtor>(Base: TBase) {
       return nb;
     }
 
-    /**
-     * recover the attack sum of items equipped on the player.
-     *
-     * @title Get the player's attack
-     * @prop {number} player.atk
-     * @memberof ItemManager
-     */
     get atk(): number {
       return this.getParamItem(ATK);
     }
 
-    /**
-     * recover the physic defense sum of items equipped on the player.
-     *
-     * @title Get the player's pdef
-     * @prop {number} player.pdef
-     * @memberof ItemManager
-     */
     get pdef(): number {
       return this.getParamItem(PDEF);
     }
 
-    /**
-     * recover the skill defense sum of items equipped on the player.
-     *
-     * @title Get the player's sdef
-     * @prop {number} player.sdef
-     * @memberof ItemManager
-     */
     get sdef(): number {
       return this.getParamItem(SDEF);
     }
 
-    /**
-     *  Use an object. Applies effects and states. Removes the object from the inventory then
-     *
-     * `onUse()` method is called on the ItemClass (If the use has worked)
-     * `onRemove()` method is called on the ItemClass
-     *
-     * @title Use an Item
-     * @method player.useItem(item,nb=1)
-     * @param {ItemClass | string} itemClass string is item id
-     * @returns {{ nb: number, item: instance of ItemClass }}
-     * @throws {ItemLog} restriction
-     * If the player has the `Effect.CAN_NOT_ITEM` effect
-     *   ```
-     * {
-     *      id: RESTRICTION_ITEM,
-     *      msg: '...'
-     * }
-     * ```
-     * @throws {ItemLog} notInInventory
-     * If the object is not in the inventory, an exception is raised
-     *  ```
-     * {
-     *      id: ITEM_NOT_INVENTORY,
-     *      msg: '...'
-     * }
-     * ```
-     * @throws {ItemLog} notUseItem
-     * If the `consumable` property is on false
-     *  ```
-     * {
-     *      id: NOT_USE_ITEM,
-     *      msg: '...'
-     * }
-     * ```
-     * @throws {ItemLog} chanceToUseFailed
-     * Chance to use the item has failed. Chances of use is defined with `ItemClass.hitRate`
-     *  ```
-     * {
-     *      id: USE_CHANCE_ITEM_FAILED,
-     *      msg: '...'
-     * }
-     * ```
-     * > the item is still deleted from the inventory
-     *
-     * `onUseFailed()` method is called on the ItemClass
-     *
-     * @memberof ItemManager
-     * @example
-     *
-     * ```ts
-     * import Potion from 'your-database/potion'
-     *
-     * try {
-     *     player.addItem(Potion)
-     *     player.useItem(Potion)
-     * }
-     * catch (err) {
-     *    console.log(err)
-     * }
-     * ```
-     */
-    useItem(itemId: string): Item {
-      const inventory = this.getItem(itemId);
+    useItem(itemClass: ItemClass | string): Item {
+      const itemId = isString(itemClass) ? itemClass : (itemClass as any).name;
+      const inventory = this.getItem(itemClass);
       if ((this as any).hasEffect?.(Effect.CAN_NOT_ITEM)) {
         throw ItemLog.restriction(itemId);
       }
       if (!inventory) {
         throw ItemLog.notInInventory(itemId);
       }
-      const item = inventory;
-      if ((item as any).consumable === false) {
+      
+      // Retrieve item data from database to check consumable and hitRate
+      const itemData = (this as any).databaseById(itemId);
+      const consumable = itemData?.consumable;
+      
+      // If consumable is explicitly false, throw error
+      if (consumable === false) {
+        throw ItemLog.notUseItem(itemId);
+      }
+      
+      // If consumable is undefined and item is not of type 'item', it's not consumable
+      if (consumable === undefined && itemData?._type && itemData._type !== 'item') {
         throw ItemLog.notUseItem(itemId);
       }
-      const hitRate = (item as any).hitRate ?? 1;
+      
+      const hitRate = itemData?.hitRate ?? 1;
+      const hookTarget = (inventory as any)._itemInstance || inventory;
+      
       if (Math.random() > hitRate) {
-        this.removeItem(itemId);
-        this["execMethod"]("onUseFailed", [this], item);
+        this.removeItem(itemClass);
+        this["execMethod"]("onUseFailed", [this], hookTarget);
         throw ItemLog.chanceToUseFailed(itemId);
       }
-      (this as any).applyEffect?.(item);
-      (this as any).applyStates?.(this, item);
-      this["execMethod"]("onUse", [this], item);
-      this.removeItem(itemId);
+      (this as any).applyEffect?.(itemData);
+      (this as any).applyStates?.(this, itemData);
+      this["execMethod"]("onUse", [this], hookTarget);
+      this.removeItem(itemClass);
       return inventory;
     }
 
-    /**
-     * 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.
-     * 
-     * `onEquip()` method is called on the ItemClass
-     * 
-     * @title Equip Weapon or Armor
-     * @method player.equip(itemClass,equip=true)
-     * @param {ItemClass | string} itemClass string is item id
-     * @param {number} [equip] Equip the object if true or un-equipped if false
-     * @returns {void}
-     * @throws {ItemLog} notInInventory 
-     * If the item is not in the inventory
-     *  ```
-        {
-            id: ITEM_NOT_INVENTORY,
-            msg: '...'
-        }
-        ```
-     * @throws {ItemLog} invalidToEquiped 
-        If the item is not by a weapon or armor
-        ```
-        {
-            id: INVALID_ITEM_TO_EQUIP,
-            msg: '...'
-        }
-        ```
-    * @throws {ItemLog} isAlreadyEquiped 
-        If the item Is already equipped
-        ```
-        {
-            id: ITEM_ALREADY_EQUIPED,
-            msg: '...'
-        }
-        ```
-     * @memberof ItemManager
-     * @example
-     * 
-     * ```ts
-     * import Sword from 'your-database/sword'
-     * 
-     * try {
-     *      player.addItem(Sword)
-     *      player.equip(Sword)
-     * }
-     * catch (err) {
-     *    console.log(err)
-     * }
-     * ```
-     */
     equip(
       itemId: string,
-      equip: boolean = true
+      equip: boolean | 'auto' = true
     ): void {
-      const inventory: Item = this.getItem(itemId);
+      const autoAdd = equip === 'auto';
+      const equipState = equip === 'auto' ? true : equip;
+      const data = (this as any).databaseById(itemId);
+      let inventory: Item = this.getItem(itemId);
+      if (!inventory && autoAdd) {
+        inventory = this.addItem(itemId, 1);
+      }
       if (!inventory) {
         throw ItemLog.notInInventory(itemId);
       }
-      const data = (this as any).databaseById(itemId);
       if (data._type == "item") {
         throw ItemLog.invalidToEquiped(itemId);
       }
@@ -503,23 +611,321 @@ export function WithItemManager<TBase extends PlayerCtor>(Base: TBase) {
 
       const item = inventory;
 
-      if ((item as any).equipped && equip) {
+      if ((item as any).equipped && equipState) {
         throw ItemLog.isAlreadyEquiped(itemId);
       }
-      (item as any).equipped = equip;
-      if (!equip) {
+      (item as any).equipped = equipState;
+      if (!equipState) {
         const index = this.equipments().findIndex((it) => it.id() == item.id());
         this.equipments().splice(index, 1);
       } else {
         this.equipments().push(item);
       }
-      this["execMethod"]("onEquip", [this, equip], item);
+      // Call onEquip hook - use stored instance if available
+      const hookTarget = (item as any)._itemInstance || item;
+      this["execMethod"]("onEquip", [this, equipState], hookTarget);
     }
   } as unknown as 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,
+   * or pass `"auto"` to add the item if it is missing and equip it.
+   * 
+   * The `onEquip()` method is called on the ItemClass when the item is equipped or unequipped.
+   * 
+   * @param itemId - Item identifier to resolve from the database
+   * @param equip - Equip the item if `true`, unequip if `false`, or `"auto"` to add then equip (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
+   * try {
+   *   player.addItem('sword')
+   *   player.equip('sword')
+   *   // Later, unequip it
+   *   player.equip('sword', false)
+   * } catch (err) {
+   *   console.log(err)
+   * }
+   * ```
+   */
+  equip(itemId: string, equip?: boolean | 'auto'): 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;
+}