inventory-system

Inventory System

When to Use

Use this skill when:

• Managing player inventory
• Implementing item collection
• Creating equipment systems
• Building crafting systems
• Managing item stacking
• Implementing item drops

Core Principles

1. Slot-Based: Fixed or dynamic inventory slots
2. Stackable: Items can stack with limits
3. Data-Driven: Item definitions in data
4. Type-Safe: Strong typing for items
5. Event-Driven: Item pickup/use events
6. Serializable: Save/load inventory

Inventory System Implementation

1. Item Definitions

// items/ItemDefinition.ts
export enum ItemType {
  Consumable = 'consumable',
  Equipment = 'equipment',
  Material = 'material',
  Quest = 'quest',
}

export enum EquipmentSlot {
  Head = 'head',
  Chest = 'chest',
  Legs = 'legs',
  Weapon = 'weapon',
  Shield = 'shield',
}

export interface ItemDefinition {
  id: string;
  name: string;
  description: string;
  type: ItemType;
  maxStack: number;
  icon?: string;
  value?: number; // Sell price
  weight?: number;

  // Equipment
  equipmentSlot?: EquipmentSlot;
  armor?: number;
  damage?: number;

  // Consumable
  healAmount?: number;
  effectDuration?: number;
}

export class ItemDatabase {
  private items = new Map<string, ItemDefinition>();

  register(item: ItemDefinition): void {
    this.items.set(item.id, item);
  }

  get(id: string): ItemDefinition | undefined {
    return this.items.get(id);
  }

  getAll(): ItemDefinition[] {
    return Array.from(this.items.values());
  }
}

2. Inventory Components

// components/Inventory.ts
export interface InventorySlot {
  itemId: string | null;
  quantity: number;
}

export class Inventory {
  slots: InventorySlot[];
  maxSlots: number;

  constructor(maxSlots: number = 20) {
    this.maxSlots = maxSlots;
    this.slots = Array.from({ length: maxSlots }, () => ({
      itemId: null,
      quantity: 0,
    }));
  }

  addItem(itemId: string, quantity: number = 1, itemDb: ItemDatabase): boolean {
    const itemDef = itemDb.get(itemId);
    if (!itemDef) return false;

    let remaining = quantity;

    // Try to stack with existing items
    if (itemDef.maxStack > 1) {
      for (const slot of this.slots) {
        if (slot.itemId === itemId && slot.quantity < itemDef.maxStack) {
          const canAdd = Math.min(remaining, itemDef.maxStack - slot.quantity);
          slot.quantity += canAdd;
          remaining -= canAdd;

          if (remaining === 0) return true;
        }
      }
    }

    // Add to empty slots
    while (remaining > 0) {
      const emptySlot = this.slots.find((s) => s.itemId === null);
      if (!emptySlot) return false; // Inventory full

      const addAmount = Math.min(remaining, itemDef.maxStack);
      emptySlot.itemId = itemId;
      emptySlot.quantity = addAmount;
      remaining -= addAmount;
    }

    return true;
  }

  removeItem(itemId: string, quantity: number = 1): boolean {
    let remaining = quantity;

    for (const slot of this.slots) {
      if (slot.itemId === itemId) {
        const removeAmount = Math.min(remaining, slot.quantity);
        slot.quantity -= removeAmount;
        remaining -= removeAmount;

        if (slot.quantity === 0) {
          slot.itemId = null;
        }

        if (remaining === 0) return true;
      }
    }

    return remaining === 0;
  }

  hasItem(itemId: string, quantity: number = 1): boolean {
    let count = 0;

    for (const slot of this.slots) {
      if (slot.itemId === itemId) {
        count += slot.quantity;
      }
    }

    return count >= quantity;
  }

  getItemCount(itemId: string): number {
    let count = 0;

    for (const slot of this.slots) {
      if (slot.itemId === itemId) {
        count += slot.quantity;
      }
    }

    return count;
  }

  isFull(): boolean {
    return this.slots.every((slot) => slot.itemId !== null);
  }

  isEmpty(): boolean {
    return this.slots.every((slot) => slot.itemId === null);
  }

  clear(): void {
    for (const slot of this.slots) {
      slot.itemId = null;
      slot.quantity = 0;
    }
  }

  getFilledSlots(): InventorySlot[] {
    return this.slots.filter((slot) => slot.itemId !== null);
  }
}

// components/Equipment.ts
export class Equipment {
  slots = new Map<EquipmentSlot, string | null>();

  constructor() {
    // Initialize all equipment slots
    for (const slot of Object.values(EquipmentSlot)) {
      this.slots.set(slot, null);
    }
  }

  equip(slot: EquipmentSlot, itemId: string): string | null {
    const previous = this.slots.get(slot) ?? null;
    this.slots.set(slot, itemId);
    return previous; // Return unequipped item
  }

  unequip(slot: EquipmentSlot): string | null {
    const itemId = this.slots.get(slot) ?? null;
    this.slots.set(slot, null);
    return itemId;
  }

  getEquipped(slot: EquipmentSlot): string | null {
    return this.slots.get(slot) ?? null;
  }

  isEquipped(itemId: string): boolean {
    return Array.from(this.slots.values()).includes(itemId);
  }

  getTotalArmor(itemDb: ItemDatabase): number {
    let total = 0;

    for (const itemId of this.slots.values()) {
      if (itemId) {
        const item = itemDb.get(itemId);
        if (item?.armor) {
          total += item.armor;
        }
      }
    }

    return total;
  }

  getTotalDamage(itemDb: ItemDatabase): number {
    let total = 0;

    for (const itemId of this.slots.values()) {
      if (itemId) {
        const item = itemDb.get(itemId);
        if (item?.damage) {
          total += item.damage;
        }
      }
    }

    return total;
  }
}