Class

RezInventory

RezInventory()

Constructor

# new RezInventory()

Holds items in named positions.

An inventory is made up of positions, each declared by a nested @contains block. The block's id is the position's name and its slot_id names the @slot that decides what the position accepts. Several positions, in the same inventory or in different ones, can use the same @slot.

Key features:

  • Typed positions: a position only accepts items whose type is (or derives from) what its slot accepts
  • Capacity: a slot with has_capacity: true limits the total size of the items in each position that uses it
  • Weight: an inventory can have a max_weight, checked against the total weight of everything it holds
  • Exclusion: a slot can exclude other slots, so filling one position blocks another
  • Enabled state: positions can be disabled (locked) and enabled at runtime
  • Single location: an item is in at most one position at a time. The item records where it is in its inventory_id and position attributes. Use move() to move an item from wherever it is.
  • Effects: items can apply effects to the inventory's owner while they are in it
  • Events: adding and removing items runs insert and remove events on the inventory, the slot, and the item

All position state lives in the positions attribute, compiled from the @contains blocks:


positions: {
  left_ring: {slot_id: "ring_slot", enabled: true, contents: ["silver_ring"]}
}

Don't change positions directly; use the methods of this class. They replace the whole record on every change, so the change is saved and observers (such as views) are told about it, and on_positions_changed runs.

Define in Rez:


@inventory player_inv {
  @contains weapon {
    slot_id: #s_weapon
    contents: [#item_sword]
  }
  @contains left_ring {
    slot_id: #s_ring
  }
  @contains right_ring {
    slot_id: #s_ring
    enabled: false
  }
}

View Source rez_inventory.js, line 5

Examples

Add an item at runtime

const inv = $("player_inv");
const decision = inv.add("left_ring", "item_gold_ring");
if(decision.wasNo) {
  console.log(decision.reason);
}

Move an item from wherever it is

$("player_inv").move("weapon", "item_axe");

Extends

Methods

# static add(name, itemId) → {RezDecision}

Adds an item, that isn't already somewhere, to the position. Runs insert events on the inventory, the slot, and the item (in that order), and applies the item's effects to the owner.

Parameters:
Name Type Description
name string

name of a position

itemId string

View Source rez_inventory.js, line 557

the decision from canAdd. When it is yes the item has been added; otherwise nothing has changed and the decision says why.

RezDecision
Example
const d = inv.add("weapon", "item_axe");
if(d.wasNo) showMessage(d.reason);

# static addPosition(name, slotId, enabledopt)

Adds a new, empty position to the inventory at runtime.

Parameters:
Name Type Attributes Default Description
name string

name of the new position

slotId string

id of the @slot the position uses

enabled boolean <optional>
true

whether the position starts enabled

View Source rez_inventory.js, line 234

if the position already exists

Error

# static allItems() → {Array.<string>}

View Source rez_inventory.js, line 295

ids of every item in every position

Array.<string>

# static applyEffects(name, itemId) → {boolean}

Parameters:
Name Type Description
name string

name of a position

itemId string

View Source rez_inventory.js, line 755

whether any effects were applied

boolean

# static canAdd(name, itemId) → {RezDecision}

Checks, in order: the position is enabled; the item isn't already somewhere (failed_on: "located", use move() instead); the slot accepts the item's type; the position isn't blocked by an exclusion; the item fits the slot's capacity; the item fits the inventory's max_weight; and finally the owner's on_accept_item handler. When the decision is no, its failed_on data says which check failed.

Parameters:
Name Type Description
name string

name of a position

itemId string

View Source rez_inventory.js, line 503

whether the item can be added to the position

RezDecision

# static canMove(name, itemId) → {RezDecision}

Parameters:
Name Type Description
name string

name of a position in this inventory

itemId string

View Source rez_inventory.js, line 648

whether the item can be moved from wherever it is now into the position. Combines canRemove at its current position (if it has one) with the checks of canAdd.

RezDecision

# static canRemove(name, itemId) → {RezDecision}

Parameters:
Name Type Description
name string

name of a position

itemId string

View Source rez_inventory.js, line 579

whether the item can be removed from the position. The decision is no (failed_on: "missing") if the item isn't in it.

RezDecision

# static clear(name)

Removes every item from the position.

Parameters:
Name Type Description
name string

name of a position

View Source rez_inventory.js, line 622

# static countItemsIn(name) → {number}

Parameters:
Name Type Description
name string

name of a position

View Source rez_inventory.js, line 275

number of items in the position

number

# static disable(name)

Disables the position so no further items can be added to it. Items already in it stay there.

Parameters:
Name Type Description
name string

name of a position

View Source rez_inventory.js, line 360

# static elementInitializer()

Called during the init process. Resolves the owner, then empties each position and adds its starting contents back through the add path, so that starting items fire insert events and apply effects like any other. Starting items are placed even in positions that begin disabled.

View Source rez_inventory.js, line 78

if a starting item can't be placed

Error

# static enable(name)

Enables the position so items can be added to it.

Parameters:
Name Type Description
name string

name of a position

View Source rez_inventory.js, line 350

# static firstItemIn(name) → {string|undefined}

Parameters:
Name Type Description
name string

name of a position

View Source rez_inventory.js, line 265

id of the first item in the position

string | undefined

# static getPositionNames() → {Array.<string>}

View Source rez_inventory.js, line 194

the names of this inventory's positions

Array.<string>

# static getPositions() → {Array.<object>}

View Source rez_inventory.js, line 203

a {name, slot, enabled, contents} description of each position, where slot is the RezSlot and contents is an array of item ids

Array.<object>
Example
for(const {name, slot, enabled, contents} of inv.getPositions()) {
  const available = inv.isAvailable(name);
  // enabled=false → locked; available=false → excluded by another position
}

# static getSlot(name) → {RezSlot}

Parameters:
Name Type Description
name string

name of a position

View Source rez_inventory.js, line 223

if there is no such position

Error

the slot that the position uses

RezSlot

# static hasItem(itemId) → {boolean}

Parameters:
Name Type Description
itemId string

View Source rez_inventory.js, line 315

true if the item is in any position of this inventory

boolean

# static hasPosition(name) → {boolean}

Parameters:
Name Type Description
name string

name of a position

View Source rez_inventory.js, line 184

true if this inventory has a position with the given name

boolean

# static isAvailable(name) → {boolean}

Useful for greying out positions in an inventory UI.

Parameters:
Name Type Description
name string

name of a position

View Source rez_inventory.js, line 371

true if the position is not blocked by an exclusion

boolean

# static isBlockedByExclusion(name) → {boolean}

Parameters:
Name Type Description
name string

name of a position

View Source rez_inventory.js, line 382

true if another occupied position's slot excludes this position's slot, or this position's slot excludes the slot of another occupied position

boolean

# static isEnabled(name) → {boolean}

Positions start enabled unless their @contains block says enabled: false. Use enable() at runtime when the player unlocks one.

Parameters:
Name Type Description
name string

name of a position

View Source rez_inventory.js, line 329

true if the position is enabled

boolean
Examples

Define a locked position in Rez

// @inventory player_equip {
//   @contains ring1 {slot_id: #s_ring}
//   @contains ring2 {slot_id: #s_ring enabled: false}
// }

Unlock it at runtime

if(player.level >= 5) {
  $("player_equip").enable("ring2");
}

# static isOccupied(name) → {boolean}

Parameters:
Name Type Description
name string

name of a position

View Source rez_inventory.js, line 285

true if there is at least one item in the position

boolean

# static isOverweight() → {boolean}

View Source rez_inventory.js, line 478

true if the inventory's total weight exceeds max_weight

boolean

# static itemFits(name, itemId) → {boolean}

If the position's slot has has_capacity: true, items count towards slot.capacity using their size attribute, defaulting to 1 if unset. This means capacity: 1 naturally limits a position to a single item unless an item explicitly opts out with size: 0 or takes up more room with size: 2+. Slots without has_capacity: true accept any number of items.

Parameters:
Name Type Description
name string

name of a position

itemId string

View Source rez_inventory.js, line 426

true if the item fits alongside the position's other contents

boolean

# static itemFitsWeight(itemId) → {boolean}

Parameters:
Name Type Description
itemId string

View Source rez_inventory.js, line 487

true if this inventory can hold the item without exceeding max_weight. An item already in this inventory is only counted once.

boolean

# static itemsIn(name) → {Array.<string>}

Parameters:
Name Type Description
name string

name of a position

View Source rez_inventory.js, line 255

a copy of the ids of the items in the position

Array.<string>

# static locationOf(itemId) → {object|null}

Parameters:
Name Type Description
itemId string

View Source rez_inventory.js, line 159

{inventory, position} for the inventory and position the item is in, or null if it isn't in any inventory

object | null
Example
const where = RezInventory.locationOf("item_gold_ring");
if(where) console.log(`In ${where.inventory.id}/${where.position}`);

# static maxWeight() → {number}

View Source rez_inventory.js, line 460

the max_weight attribute, or Infinity if not set

number

# static move(name, itemId) → {RezDecision}

Moves an item into the position from wherever it is, which may be another position of this inventory, another inventory, or nowhere.

Parameters:
Name Type Description
name string

name of a position in this inventory

itemId string

View Source rez_inventory.js, line 673

the decision from canMove. When it is yes the item has been removed from where it was (if anywhere) and added to the position.

RezDecision
Example
$("chest").move("contents", "item_gold_ring");

# static positionAccepts(name, itemId) → {boolean}

Parameters:
Name Type Description
name string

name of a position

itemId string

View Source rez_inventory.js, line 414

true if the item's type is one that the position's slot accepts

boolean

# static positionOf(itemId) → {string|undefined}

Parameters:
Name Type Description
itemId string

View Source rez_inventory.js, line 304

name of the position holding the item, or undefined if it isn't in this inventory

string | undefined

# static remainingWeight() → {number}

View Source rez_inventory.js, line 469

how much more weight this inventory can carry before reaching max_weight

number

# static remove(name, itemId) → {RezDecision}

Removes the item from the position. Runs remove events on the slot, the item, and the inventory (in that order), and removes the item's effects from the owner.

Parameters:
Name Type Description
name string

name of a position

itemId string

View Source rez_inventory.js, line 603

the decision from canRemove. When it is yes the item has been removed; otherwise nothing has changed and the decision says why.

RezDecision

# static removeEffects(name, itemId) → {boolean}

Parameters:
Name Type Description
name string

name of a position

itemId string

View Source rez_inventory.js, line 776

whether any effects were removed

boolean

# static resolveOwner()

If owner_id was not authored directly, find the actor that declares this inventory as its container_id and record it as owner_id, so that inventory.owner is reliably available (for the actor veto, effect application, and insert/remove event handlers). Author ownership in a single place (actor.container_id); an explicitly authored owner_id still wins. Safe at init time because all game objects are registered before any object is initialised.

View Source rez_inventory.js, line 108

# static setContents(name, itemIds) → {Array.<RezDecision>}

Empties the position, then adds each item. An item that can't be added is left where it was and its decision says why.

Parameters:
Name Type Description
name string

name of a position

itemIds string | Array.<string>

the item or items the position should hold

View Source rez_inventory.js, line 634

a decision for each item added, in order

Array.<RezDecision>

# static shouldApplyEffects(name) → {boolean}

Parameters:
Name Type Description
name string

name of a position

View Source rez_inventory.js, line 743

true if items in the position apply their effects: the inventory has an owner and both the inventory and the position's slot have apply_effects: true

boolean

# static totalWeight() → {number}

View Source rez_inventory.js, line 449

sum of the weight attribute of every item in every position

number