Skip to main content
Creates a new inventory in both database and memory (depending on options). If an inventory with the same ID already exists, returns the existing one without modifying it.

Parameters

Return value

Notes

options fields:
  • maxWeight (number, optional): Maximum weight capacity
  • maxSlots (number, optional): Maximum number of slots
  • columns (number, optional): Number of columns for grid display in the UI (e.g. 10 total slots but 2 columns → 2x5 grid)
  • temporary (boolean, optional): If true, the inventory is not saved to the database and will be lost on script restart
  • prefillItems (table, optional): Random loot configuration. Items are picked via weighted selection without replacement:
    • minTypes (number, optional): Minimum number of different item types to add. Default: 1
    • maxTypes (number, optional): Maximum number of different item types to add. Default: pool size
    • items (table, required): Array of possible items, each entry: {name = string, chance = number, min = number, max = number, metadata = table?}
  • revealItems (table, optional): Progressive item reveal animation when the inventory is opened:
    • delayPerItem (number, optional): Milliseconds between each item reveal. Default: 1000
    • randomOrder (boolean, optional): If true, items are revealed in random order instead of slot order. Default: false
  • slots (table, optional): Per-slot configuration. Key is the slot number, value is a SlotConfig table: label, image, opacity, whitelist, blacklist
  • whitelist / blacklist (table, optional): Inventory-level item filters. Format: {itemName = true, ...}
  • allowedJobs (table, optional): Jobs allowed to access this inventory
  • allowedIdentifiers (table, optional): Character identifiers allowed to access this inventory
  • disableIncoming / disableOutgoing (boolean, optional): Block transfers in or out by the player
  • dropDisabled (boolean, optional): If true, items cannot be dropped from this inventory
  • noLimitDrag (boolean, optional): If true, dragging ignores the amount selection dialog and moves the full stack. Used internally for shops
Also:
  • If id already exists, the existing inventory is returned as is, static items and prefillItems are NOT re-applied
  • prefillItems uses weighted random selection without replacement (each item type can only be picked once)
  • prefillItems is processed via options, while static items is a separate parameter, they serve different purposes
  • Use temporary = true for ephemeral inventories (lootboxes, event rewards) to avoid database bloat