Overview

The _Inventory class is a base class that represents an item container. It should be derived from when implementing specific inventories (e.g. player inventory, chest, shop inventory). It provides built-in logic for item management through transactions (adding, removing, splitting, joining, swapping, etc.).

The system enforces size, weight, and stacking constraints unless these are disabled by setting them to -1 (unlimited).

Properties

• name (string): Identifier of the inventory. Defaults to "unnamed".
• owner (any): Reference to the entity that owns this inventory (e.g., a player object).
• inventory_size (int): Maximum number of items. -1 means infinite.
• inventory_weight (int): Maximum total weight allowed. -1 means infinite.
• stack_size (int): Maximum items per stack. -1 means infinite.

Core Functions

Item Access

• get_item(index) → InventoryItem | undefined Retrieves the item at a specific index.

• items_length() → int Returns the total number of item stacks in the inventory.

Counting and Measuring

• count_items(name = "*") → int
  Counts total items, optionally filtered by name (supports * wildcard).

• weight_items(name = "*") → float
  Calculates the total weight, optionally filtered by name (supports *).

• fill_factor() → float (0–1)
  Returns the fill ratio compared to inventory_size.

• weight_factor() → float (0–1)
  Returns the ratio of current weight to inventory_weight.

Transactions

Transactions encapsulate operations on the inventory. Each transaction validates constraints before executing.

Adding & Removing

• add_item(item, stack_size = stack_size)
  Adds an item while respecting stack limits.

• remove_item(item, is_removing_all = false) → int
  Removes an item. Returns the number of items not removed.

Moving & Buying

• move_item(item, inventory, is_moving_all = false) → int
  Moves items between inventories.

• buy_item(item, inventory, available_money)
  Handles purchasing logic (returns change).

Splitting & Joining

• split_item(item, stack_size)
  Splits an item into multiple stacks.

• join_items(item1, item2, stack_size = stack_size)
  Combines items into stacks (splits if necessary).

• join_or_swap_items(item1, item2, stack_size = stack_size)
  Joins if names match, otherwise swaps.

Swapping & Cleanup

• swap_items(item1, item2)
  Exchanges positions of two items.

• clean_up()
  Automatically consolidates stacks and reorganizes.

Specialized Inventory Types

List Inventory

The ListInventory is the simplest form of inventory, directly extending _Inventory. It behaves like a plain list where items are appended in sequence.

Constructor

ListInventory(_inventory_size = -1, _inventory_weight = -1, _stack_size = -1)

• inventory_size: Maximum number of items (-1 = unlimited).
• inventory_weight: Maximum total weight (-1 = unlimited).
• stack_size: Maximum items per stack (-1 = unlimited).

This type is suitable for lightweight inventories (e.g., loot tables or temporary storage).

Grid Inventory

The GridInventory is a specialized subclass of _Inventory that represents items in a grid layout (X × Y), commonly used in RPGs or survival games. Empty slots are explicitly represented as undefined.

Constructor

GridInventory(_x = 12, _y = 8, _inventory_weight = -1, _stack_size = -1)

Features

• Grid-based indexing (get_item(x, y)).
• Inserts into the first empty slot.
• Maintains grid structure when items are added or removed.

Slot Inventory

The SlotInventory associates items with specific slots, commonly used for equipment systems (helmet, chestplate, weapon, etc.).

Constructor

SlotInventory(_inventory_size = 1, _inventory_weight = -1, _slots = [new InventorySlot()])

• inventory_size: Number of slots available.
• inventory_weight: Maximum total weight (-1 = unlimited).
• slots: An array of InventorySlot objects that define slot constraints.

Features

• add_or_swap_item_to_slot(item, slot_name)
  Adds an item to a slot. If the slot is occupied, the existing item is swapped.

• find_slot_by_name(slot_name) → InventorySlot | undefined
  Retrieves a slot by its name.

This inventory type is perfect for character equipment, enforcing that only valid items go into specific slots.

Usage Example (List Inventory)

// Create a new player inventory with 20 slots, unlimited weight, and stacks of up to 10.
var player_inv = new ListInventory(20, -1, 10);
player_inv.name = "Player Inventory";

// Add an item
var sword = new InventoryItem("Sword", 1, 5); // name, count, weight
player_inv.add_item(sword);

// Count swords
var sword_count = player_inv.count_items("Sword");

// Check fill percentage
var fill = player_inv.fill_factor();

Usage Example (Grid Inventory)

// Create a 5x5 grid inventory
var chest_inv = new GridInventory(5, 5);
chest_inv.name = "Treasure Chest";

// Add a potion (goes into first available slot)
var potion = new InventoryItem("Potion", 1, 0.5);
chest_inv.add_item(potion);

// Add a sword
var sword = new InventoryItem("Iron Sword", 1, 5);
chest_inv.add_item(sword);

// Retrieve the item at position (0, 0)
var first_slot_item = chest_inv.get_item(0, 0);

// Retrieve an item at grid position (2, 3)
var grid_item = chest_inv.get_item(2, 3);

// Check how full the chest is
var fill = chest_inv.fill_factor();

// Count potions
var potion_count = chest_inv.count_items("Potion");

Usage Example (Slot Inventory)

// Create a slot-based inventory with helmet and weapon slots
var slots = [new InventorySlot("Helmet"), new InventorySlot("Weapon")];
var equip_inv = new SlotInventory(2, -1, slots);

// Add a helmet item
var helmet = new InventoryItem("Iron Helmet", 1, 3);
equip_inv.add_or_swap_item_to_slot(helmet, "Helmet");

// Swap an equipped weapon
var sword = new InventoryItem("Iron Sword", 1, 5);
equip_inv.add_or_swap_item_to_slot(sword, "Weapon");

Best Practices

• Always check fill_factor and weight_factor before adding new items to prevent failures.
• Use transactions (add_item, remove_item, etc.) instead of manually modifying arrays.
• Choose the right inventory type for the gameplay feature:
  • ListInventory for simple sequential storage.
  • GridInventory for grid-based item management.
  • SlotInventory for equipment systems.