Items API Reference

API reference for working with items and inventories in code.

Game Methods

createItem(template)

Create an item from a template object or registered template ID.

// From a registered template ID
const sword = game.createItem("iron_sword");
inventory.addItem(sword);

// From a custom template object
const customItem = game.createItem({
  id: "custom_sword",
  traits: { name: "Custom Sword", description: "My mighty custom sword." },
  slots: ["weapon_slot"],
  tags: ["weapon", "sword"]
});

createInventory(id, template?)

Create an inventory, optionally populated from a template.

// Create empty inventory
const chest = game.createInventory("treasure_chest_1");

// Create from template ID
const shop = game.createInventory("shop_1", "blacksmith_shop");

// Create from custom template object
const custom = game.createInventory("custom_inv", {
  items: [{ item_id: "gold", quantity: 100 }],
  max_size: 20,
  recipes: ["sword_recipe"]
});

addInventory(inventory)

Add an existing inventory instance to the game.

game.addInventory(inventory);

removeInventory(inventory)

Remove an inventory from the game. Accepts inventory instance or ID string.

game.removeInventory("temporary_chest");
game.removeInventory(chestInventory);

getInventory(id)

Get an inventory by ID.

const inventory = game.getInventory("party_inventory");
if (inventory) {
  console.log(`Inventory has ${inventory.items.length} items`);
}

openExchange(inventoryId, state)

Open an exchange UI (loot or trade) with an inventory.

game.openExchange("merchant_inventory", "trade");
game.openExchange("treasure_chest", "loot");

closeExchangeInventory(exchangeInventory)

Close the exchange UI and proceed to the next scene.

const merchant = game.getInventory("merchant_shop");
game.closeExchangeInventory(merchant);

canUseItems()

Check if item usage is currently allowed. Returns false when party inventory is blocked.

if (game.canUseItems()) {
  // Show use item button
}

addLearnedRecipe(recipeId)

Add a recipe to the player's learned recipes.

game.addLearnedRecipe("iron_sword_recipe");

getLearnedRecipes()

Get all learned recipe IDs.

const recipes = game.getLearnedRecipes();
if (recipes.has("iron_sword_recipe")) {
  console.log("Player can craft iron swords");
}

Item Properties

Item Methods

Trait Accessors

// Get trait value
const damage = item.getTrait("damage");

// Convenience accessors
const name = item.getName();
const image = item.getImage();
const description = item.getDescription();
const rarity = item.getRarity();
const type = item.getType();
const weight = item.getWeight(); // Multiplied by quantity

Tag Methods

// Get all tags
const tags = item.getTags();

// Check for tag
if (item.hasTag("consumable")) {
  // Show use button
}

Trading Methods

// Check if tradable
if (item.isTradable()) {
  // Get specific currency price
  const goldCost = item.getPrice("gold"); // 100

  // Get all prices
  const allPrices = item.getPrice(); // { gold: 100, gems: 5 }
}

Stacking

// Get max stack size (1 = non-stackable, -1 = unlimited)
if (item.maxStack() > 1) {
  console.log("This item is stackable");
}

CSS Classes

// Get attribute-based CSS classes
const classes = item.getAttributeClasses();
// ["rarity_legendary", "type_weapon"]

Inventory Properties

Inventory Methods

Item Management

// Add item (auto-stacks)
inventory.addItem(sword);
inventory.addItem(potion, 5);
inventory.addItem(goldCoin, 100, true); // Skip validation

// Clone item
const clone = inventory.cloneItem(item);

// Remove item
inventory.removeItem(item);

// Reduce quantity (removes item if it reaches 0)
inventory.reduceItemQuantity(item, 1);

// Remove all unequipped items
inventory.clear();

// Find items
const sword = inventory.getFirstItemById("iron_sword");
const potions = inventory.getItemsById("health_potion");
const item = inventory.getItemByUid("abc123");
const weapons = inventory.getItemsByTrait("damage");

Capacity

// Weight
const totalWeight = inventory.getTotalWeight();
const availableWeight = inventory.getAvailableWeight(); // null if unlimited

// Slots
const availableSlots = inventory.getAvailableSlots(); // null if unlimited

// Status checks
if (inventory.isOverflowing()) { /* more items than maxSize */ }
if (inventory.isOverweight()) { /* weight exceeds maxWeight */ }

Equipment

// Get equipped/unequipped items
const equipped = inventory.getEquippedItems();
const unequipped = inventory.getUnequippedItems();

// Equip/unequip via character (recommended)
character.equipItem(sword);                  // Auto-find slot
character.equipItem("item_uid_123", "weapon"); // Specific slot type
character.equipItem("item_uid_123", "ring", 1); // Specific slot index
character.unequipItem(sword);

// Items not in inventory are added automatically
const newSword = game.createItem("iron_sword");
character.equipItem(newSword); // Added to inventory and equipped

// Already-equipped items are skipped (logs error)

// Low-level inventory methods
inventory.equipSlot(slot, item, character);
inventory.unequipSlot(slot, character);

Transfer

// Transfer between inventories
const success = playerInventory.transferTo(chestInventory, sword, 1);

Currency

// Get item quantity (works for any item, including currencies)
const gold = inventory.getItemQuantity("gold");

// Get all currencies
const currencies = inventory.getCurrencies(); // { gold: 150, gems: 20 }

// Check affordability
if (inventory.canAfford(shopItem)) { /* can buy */ }
if (inventory.canAffordPrice({ gold: 100, gems: 5 })) { /* has enough */ }

// Deduct currency
const paid = inventory.deductCurrency({ gold: 100 });

Recipes & Crafting

// Add recipe
inventory.addRecipe("iron_sword_recipe");

// Get recipes
const recipes = inventory.getRecipes();

// Craft
inventory.selectedRecipeId = "iron_sword_recipe";
inventory.craft();

// Or craft specific recipe
inventory.craft("iron_sword_recipe");

// Apply interactive action or craft
inventory.apply();

Events

Item Events

// Item created
game.on("item_create", (item) => {
  console.log("Created:", item.getName());
});

// Before equip (return false to cancel)
game.on("item_equip_before", (item, character) => {
  if (character.getStat("strength") < 10) {
    return false; // Too weak to equip
  }
});

// After equip
game.on("item_equip_after", (item, character) => {
  console.log(character.getName(), "equipped", item.getName());
});

// Before unequip (return false to cancel)
game.on("item_unequip_before", (item, character) => {
  if (item.hasTag("cursed")) {
    return false; // Can't remove cursed items
  }
});

// After unequip
game.on("item_unequip_after", (item, character) => {
  console.log("Unequipped:", item.getName());
});

// Before consume (return false to cancel)
game.on("item_consume_before", (item, character) => {
  if (character.getResource("health") > character.getStat("health") * 0.9) {
    return false; // Don't waste potion when nearly full
  }
});

// After consume
game.on("item_consume_after", (item, character) => {
  console.log(character.getName(), "consumed", item.getName());
});

Inventory Events

// Inventory opened
game.on("inventory_open", (inventory) => {
  console.log("Opened:", inventory.name);
});

// Inventory closed
game.on("inventory_close", (inventory) => {
  console.log("Closed:", inventory.name);
});

// Changes applied (craft button, etc.)
game.on("inventory_apply", (inventory) => {
  console.log("Applied:", inventory.id);
});

// Items transferred
game.on("inventory_transfer", (source, target, item, quantity, isTrade) => {
  console.log(`Transferred ${quantity}x ${item.getName()}`);
});

Trade Events

// Trade initiated (modify prices here)
game.on("trade_init", (traderInventory, item) => {
  // Apply discount
  item.tradePrice.trader.gold *= 0.9;
});

// Recipe learned
game.on("recipe_learned", (recipeId) => {
  console.log("Learned recipe:", recipeId);
});