Documentation

Class

RezInventory

RezInventory()

Constructor

# new RezInventory()

Manages a collection of slots that can hold items.

An inventory is a container system that organizes items into typed slots. Each slot can accept items of a specific type and may have capacity limits. Inventories can be owned by actors, enabling equipment systems with effects.

Key features:

  • Typed Slots: Each slot accepts only items of a matching type
  • Capacity: Slots can have size limits based on item sizes
  • Effects: Items can apply effects to the inventory's owner when inserted
  • Events: Triggers events on insert/remove for items, slots, and inventory

Slots are defined as references to @slot elements. Each slot has an accessor attribute that determines the attribute name used to store its contents (e.g., a slot with accessor "weapon" stores items in weapon_contents).

Define in Rez:


@inventory player_inv {
  slots: [#slot_weapon, #slot_armor]
  initial_weapon: [#item_sword]
}

View Source rez_inventory.js, line 5

Example

Add an item at runtime

const inv = $("player_inv");
if (inv.canAddItemForSlot("slot_weapon", "item_axe").result) {
  inv.addItemToSlot("slot_weapon", "item_axe");
}

Extends

Methods

# addCopy(copyId)

create a copy of this object with the specified, rather than autogenerated, id

Parameters:
Name Type Description
copyId string

id to assign to the object copy
Inherited From:

View Source rez_0_basic_object.js, line 765

# addTag(tag)

Adds a tag to this object's tags attribute and updates the game's tag index so this object can be found via $game.getObjectsWithTag().

Parameters:
Name Type Description
tag string

the tag to add
Inherited From:

View Source rez_0_basic_object.js, line 967

# addToGame() → {RezBasicObject}

Registers this object with the game world by calling $game.addGameObject(). This makes the object accessible via the $() lookup function and indexes it by tags.

Inherited From:

View Source rez_0_basic_object.js, line 712

this object for method chaining

RezBasicObject

# applyEffect(effectId, slotId, itemId)

Hook method for applying an effect to this object. The base implementation only logs the request. Subclasses (particularly RezActor) should override this to actually apply the effect's modifications.

Parameters:
Name Type Description
effectId string

ID of the effect to apply
slotId string

ID of the inventory slot the item is in
itemId string

ID of the item providing the effect
Inherited From:

View Source rez_0_basic_object.js, line 1038

# archiveInto(archive)

Serializes this object's changed attributes into the archive object. Only attributes that have been modified (tracked in changedAttributes) are saved. Attributes listed in the $no_archive attribute are excluded. Functions are serialized with a special wrapper for later restoration.

Parameters:
Name Type Description
archive object

the archive object to write to
Inherited From:

View Source rez_0_basic_object.js, line 231

# attributes() → {object}

Returns the internal attributes object. Prefer using getAttribute(), setAttribute(), or property accessors rather than accessing this directly.

Inherited From:

View Source rez_0_basic_object.js, line 187

the raw attributes object

object

# changedAttributes() → {Set.<string>}

Returns the set of attribute names that have been changed since object creation. Used by the persistence system to determine what needs to be saved.

Inherited From:

View Source rez_0_basic_object.js, line 198

set of attribute names that have been modified

Set.<string>

# constructor(element, id, attributes)

Creates a new RezBasicObject. The attributes are normalized to collapse any {$ref: "id"} objects to plain ID strings. The object starts uninitialized; call init() to complete setup.

Parameters:
Name Type Description
element string

the Rez element type (e.g., "actor", "card", "scene")
id string

unique identifier for this object
attributes object

attribute key-value pairs from Rez compilation
Inherited From:

View Source rez_0_basic_object.js, line 103

# copyAssigningId(id) → {object}

creates a copy of this object. If this object has $template: true the copy will have $template: false. The copy will also be assigned a new attribute $original_id containing the id of this object.

Parameters:
Name Type Description
id string

the id to assign to the copy
Inherited From:

View Source rez_0_basic_object.js, line 724

copy of the current object

object

# copyWithAutoId()

creates a copy of this object that is assigned an ID automatically. In all other respects its behaviour is identical to copyAssigningId Copies an object with an auto-generated ID

Inherited From:

View Source rez_0_basic_object.js, line 755

# createAttributeByCopying(attrName, value)

Creates an attribute by copying a template object. Looks up the source element via the $copy reference, creates a copy of it using addCopy(), and stores the new copy's ID in this attribute.

Parameters:
Name Type Description
attrName string

name of the attribute to set
value object

object containing $copy field with source element reference
Inherited From:

View Source rez_0_basic_object.js, line 624

# createBehaviourTreeAttribute(attrName, value)

Creates a read-only property that returns an instantiated behaviour tree. The tree is created once during initialization and cached. Uses instantiateBehaviourTree to recursively build the tree structure.

Parameters:
Name Type Description
attrName string

name of the behaviour tree attribute
value object

attribute value containing the bht specification
Inherited From:

View Source rez_0_basic_object.js, line 666

# createCustomProperty(attrName, value)

Creates a computed property with a custom getter function. The property field contains JavaScript source code that becomes the getter body. The getter executes with this bound to the object.

Parameters:
Name Type Description
attrName string

name of the property to create
value object

attribute value containing the property getter source code
Inherited From:

View Source rez_0_basic_object.js, line 588

# createDelegateProperty(attrName, targetAttr)

Creates a read-only property that delegates to the corresponding property of the referenced element. For example, if targetAttr is "hull", this will look up this.hull (which is the dereferenced element from hull_id) and return its attrName property.

Parameters:
Name Type Description
attrName string

name of the attribute to create a delegate property for
targetAttr string

name of the attribute that holds a reference to the delegate target
Inherited From:

View Source rez_0_basic_object.js, line 639

# createDynamicProperties()

Creates synthetic properties for special attribute types that require custom behavior beyond simple getter/setter access. Handles:

  • ptable: - probability tables for weighted random selection
  • property: - computed properties with custom getter functions
  • bht: - behaviour tree instances
  • template: - template function properties

Skipped for template objects since they don't need runtime property initialization.

Inherited From:

View Source rez_0_basic_object.js, line 428

# createDynamicallyInitializedAttribute(attrName, value)

Initializes an attribute with a computed value at runtime. If the value is a RezDie, rolls it and stores the result. Otherwise, executes the initializer field as JavaScript code with this bound to the object, and stores the result. The attribute is set without notifying observers (third parameter is false).

Parameters:
Name Type Description
attrName string

name of the attribute to initialize
value object | RezDie

initializer specification or RezDie instance
Inherited From:

View Source rez_0_basic_object.js, line 604

# createProbabilityTable(attrName, value)

Creates a probability table property for weighted random selection. The ptable is an array of [value, cumulative_probability] pairs. Accessing the property returns a randomly selected value based on the weights.

Also creates a <attrName>_roll property that returns both the random probability and the selected value as {p: number, obj: any}.

Parameters:
Name Type Description
attrName string

name of the ptable attribute
value object

attribute value containing the ptable JSON
Inherited From:

View Source rez_0_basic_object.js, line 546

# createStaticProperties()

Iterates through all declared attributes and calls createStaticProperty for each one, creating JavaScript property accessors for the entire attribute set.

Inherited From:

View Source rez_0_basic_object.js, line 416

# createStaticProperty(attrName)

Creates a JavaScript property backed by a Rez attribute. The property provides getter/setter access to the underlying attribute value via getAttribute/setAttribute.

Additionally creates synthetic accessor properties for special attribute name patterns:

  • Attributes ending in _id get a dereferenced accessor (e.g., location_id creates a location property that returns the actual game object, not just the ID)
  • Attributes ending in _die get a roll accessor (e.g., damage_die creates a damage_roll property that returns the result of rolling the die)
Parameters:
Name Type Description
attrName string

name of the attribute to create a corresponding property for
Inherited From:

View Source rez_0_basic_object.js, line 366

# createTemplateProperty(attrName, value)

Creates a property for a template function attribute. The template function is assigned directly to the object. For system template attributes (those matching $*_template pattern), also creates a convenience accessor that evaluates the template with this bound to the object.

Parameters:
Name Type Description
attrName string

name of the template attribute
value object

attribute value containing the template function
Inherited From:

View Source rez_0_basic_object.js, line 461

# element() → {string}

Returns the element type string that identifies what kind of Rez element this object represents.

Inherited From:

View Source rez_0_basic_object.js, line 154

the Rez element type (e.g., "actor", "card", "scene")

string

# elementInitializer()

Hook method for subclass-specific initialization. Called during init_2 phase before the 'init' event fires. Subclasses (RezActor, RezScene, etc.) override this method to perform element-type-specific setup. The base implementation is empty.

Overrides:

View Source rez_0_basic_object.js, line 703

# eventHandler(event_name) → {function|undefined}

Returns the event handler function stored in attribute "on_<event_name>" or undefined if no handler is present

Parameters:
Name Type Description
event_name string

name of the event whose handler should be returned
Inherited From:

View Source rez_0_basic_object.js, line 824

event handle function or undefined

function | undefined

# game() → {RezGame}

Instance accessor for the game. Delegates to the static game property.

Inherited From:

View Source rez_0_basic_object.js, line 144

the singleton game instance

RezGame

# getAttribute(name) → {*}

returns the value of the attribute with the given name. If no such attribute is present returns undefined

Parameters:
Name Type Description
name string

name of the attribute
Inherited From:

View Source rez_0_basic_object.js, line 878

attribute value

*

# getAttributeValue(name, default_value) → {*}

returns the value of the attribute with the given name. If no such value is present it returns the default value. If no default value is given it throws an exception.

Parameters:
Name Type Description
name string

name of the attribute
default_value *

value to return if no such attribute is present
Inherited From:

View Source rez_0_basic_object.js, line 890

attribute value

*

# getNextAutoId()

returns the next auto id in the sequence

Inherited From:

View Source rez_0_basic_object.js, line 743

# getObjectViaAttribute(name, defaultValue) → {RezBasicObject}

Retrieves a game object by looking up its ID from an attribute value. Useful for following ID references to get the actual object.

Parameters:
Name Type Description
name string

attribute name containing an object ID
defaultValue *

default ID to use if attribute is not defined
Inherited From:

View Source rez_0_basic_object.js, line 915

the game object referenced by the attribute

RezBasicObject

# getRelationshipWith(targetId) → {RezRelationship|undefined}

Retrieves the relationship from this object to another object. Relationships are unidirectional - the relationship from A to B is distinct from the relationship from B to A. Use relationship.inverse to get the reverse direction.

Parameters:
Name Type Description
targetId string

ID of the target object
Inherited From:

View Source rez_0_basic_object.js, line 1024

the relationship object, or undefined if none exists

RezRelationship | undefined

# hasAttribute(name) → {boolean}

Parameters:
Name Type Description
name string

name of the attribute
Inherited From:

View Source rez_0_basic_object.js, line 868

true if the object defines the specified attribute

boolean

# hasTag(tag) → {boolean}

Checks whether this object has the specified tag in its tags attribute.

Parameters:
Name Type Description
tag string

the tag to check for
Inherited From:

View Source rez_0_basic_object.js, line 956

true if this object has the specified tag

boolean

# id() → {string}

Returns the unique ID assigned to this object. IDs are defined in Rez source files (e.g., @card my_card { ... } creates an object with id "my_card").

Inherited From:

View Source rez_0_basic_object.js, line 165

the unique identifier for this object

string

# init()

Runs the complete three-phase initialization lifecycle for this object. After init completes, isInitialized returns true. The phases are:

  • init_0: Property creation and dynamic attribute initialization
  • init_1: Mixin application
  • init_2: Element-specific initialization and 'init' event
Inherited From:

View Source rez_0_basic_object.js, line 294

# initDynamicAttributes()

Initializes dynamic attributes that require runtime computation. Processes three types of dynamic attributes in order:

  1. $copy attributes - creates copies of template objects
  2. $delegate attributes - creates delegate properties to other objects
  3. initializer attributes - runs initialization functions

Attributes are processed in priority order (1-10, as set by the compiler) to ensure dependencies are satisfied. Skipped for template objects.

Inherited From:

View Source rez_0_basic_object.js, line 496

# init_0()

Phase 0 of initialization: Creates all JavaScript properties from attributes. First creates static properties (simple getter/setters for each attribute), then creates dynamic properties for special attribute types (ptable, property, bht, template), and finally runs dynamic attribute initializers in priority order.

Inherited From:

View Source rez_0_basic_object.js, line 310

# init_1()

Phase 1 of initialization: Applies mixins. Iterates through the $mixins attribute (an array of mixin IDs) and applies each mixin's properties and methods to this object. Mixin properties use createCustomProperty, while mixin methods are bound directly to this object.

Inherited From:

View Source rez_0_basic_object.js, line 324

# init_2()

Phase 2 of initialization: Element-specific setup and 'init' event. Calls elementInitializer() for subclass-specific initialization, then fires the 'init' event. This phase is skipped for template objects (those with $template: true), since templates are not meant to be used directly.

Inherited From:

View Source rez_0_basic_object.js, line 350

# instantiateBehaviourTree(treeSpec) → {RezBehaviour}

Recursively instantiates a behaviour tree from a specification object. Each node references a behaviour template by ID, has options, and may have child nodes. Child specifications are recursively instantiated before the parent.

Parameters:
Name Type Description
treeSpec object

behaviour tree specification with behaviour, options, and children
Inherited From:

View Source rez_0_basic_object.js, line 686

instantiated behaviour tree node

RezBehaviour

# isInitialized() → {boolean}

Returns whether this object has completed its initialization lifecycle. Objects are not fully usable until initialization completes.

Inherited From:

View Source rez_0_basic_object.js, line 209

true if init() has completed

boolean

# isTemplateObject() → {boolean}

returns the value of the $template attribute

Inherited From:

View Source rez_0_basic_object.js, line 814

true if this object has a $template attribute with value true

boolean

# loadData(attrs)

Restores attributes from a saved archive. Handles special serialized types like functions (wrapped with json$safe markers). Each attribute is set using setAttribute, which triggers change tracking and observers.

Parameters:
Name Type Description
attrs object

attribute key-value pairs from a saved archive
Inherited From:

View Source rez_0_basic_object.js, line 261

if attrs is not an object

Error

# needsArchiving() → {boolean}

Returns whether this object has any modified attributes that need to be saved. Used by the persistence system to skip unchanged objects.

Inherited From:

View Source rez_0_basic_object.js, line 220

true if this object has changed attributes requiring save

boolean

# ref() → {Object}

Returns a reference object in the format {$ref: "id"}. This format is used by the Rez compiler for element references and can be used for serialization.

Inherited From:

View Source rez_0_basic_object.js, line 176

a reference object containing this object's ID

Object

# removeEffect(effectId, slotId, itemId)

Hook method for removing an effect from this object. The base implementation only logs the request. Subclasses (particularly RezActor) should override this to actually remove the effect's modifications.

Parameters:
Name Type Description
effectId string

ID of the effect to remove
slotId string

ID of the inventory slot the item was in
itemId string

ID of the item that provided the effect
Inherited From:

View Source rez_0_basic_object.js, line 1060

# removeTag(tag)

Removes a tag from this object's tags attribute and updates the game's tag index so this object is no longer found via $game.getObjectsWithTag().

Parameters:
Name Type Description
tag string

the tag to remove
Inherited From:

View Source rez_0_basic_object.js, line 986

# runEvent(event_name, params) → {*|boolean}

attempts to run the event handler function for the event name, passing the specified params to the handler

Parameters:
Name Type Description
event_name string

name of the event to run, e.g. "speak"
params object

object containing event params
Inherited From:

View Source rez_0_basic_object.js, line 848

returns a response object, or false if the event was not handled

* | boolean

# setAttribute(attr_name, new_value, notify_observers)

Parameters:
Name Type Description
attr_name string

name of attribute to set
new_value *

value for attribute
notify_observers boolean

whether observers should be notified that the value has changed
Inherited From:

View Source rez_0_basic_object.js, line 929

# setTags(newTags)

Replaces this object's tags with the specified set. Computes the difference between old and new tags, removing tags that are no longer present and adding new tags. Updates the game's tag index accordingly.

Parameters:
Name Type Description
newTags Set | Array

the complete set of tags this object should have
Inherited From:

View Source rez_0_basic_object.js, line 1005

# unmap() → {RezBasicObject}

Removes this object from the game world by calling $game.unmapObject(). After unmapping, the object is no longer accessible via the $() lookup function and is removed from tag indexes. Use this for cleanup when an object is no longer needed.

Inherited From:

View Source rez_0_basic_object.js, line 776

this object for method chaining

RezBasicObject

# unmap_attr(attr_name)

Unmaps a related object referenced by an _id attribute. First nulls the attribute on this object, then unmaps the referenced object from the game. Use this to clean up owned/related objects when they should be removed.

Parameters:
Name Type Description
attr_name string

name of an _id attribute referencing another object
Inherited From:

View Source rez_0_basic_object.js, line 789

if attr_name doesn't end with "_id"

Error

if the attribute is not defined on this object

Error

# willHandleEvent(event_name) → {boolean}

Returns true if this object defines an event handler function for the given event_name

Parameters:
Name Type Description
event_name string

name of the event to check for a handler, e.g. "speak"
Inherited From:

View Source rez_0_basic_object.js, line 835

true if this object handles the specified event

boolean

# static addItemHolderForSlot(slot_id)

add a new slot to the inventory

Parameters:
Name Type Description
slot_id string

View Source rez_inventory.js, line 66

# static addItemToSlot(slot_id, item_id)

adds the given item to the given slot, notifying inventory, slot & item and applying effects

Parameters:
Name Type Description
slot_id string
item_id string

View Source rez_inventory.js, line 323

# static appendItemToSlot(slot_id, item_id)

appends the given item to the given slot

Parameters:
Name Type Description
slot_id string
item_id string

View Source rez_inventory.js, line 139

# static appendItemsToSlot(item_or_items)

add either a single item_id or an array of item_ids to the slot

Parameters:
Name Type Description
item_or_items string | array

either an item_id or array of item_id's to append to the slot

View Source rez_inventory.js, line 150

# static applyEffects(slot_id, item_id) → {boolean}

Parameters:
Name Type Description
slot_id string
item_id string

View Source rez_inventory.js, line 373

whether the effect was applied

boolean

# static canAddItemForSlot(slot_id, item_id) → {boolean}

Parameters:
Name Type Description
slot_id string
item_id string

View Source rez_inventory.js, line 265

true if the slot accepts the item

boolean

# static canRemoveItemFromSlot(slot_id, item_id) → {object}

Parameters:
Name Type Description
slot_id string
item_id string

View Source rez_inventory.js, line 295

RezDecision containing the result whether the item can be removed from the slot

object

# static clearSlot(slot_id)

remove all items from give slot, removes any effects granted by those items

Parameters:
Name Type Description
slot_id string

View Source rez_inventory.js, line 457

# static containsItem(item_id) → {string|null}

Parameters:
Name Type Description
item_id string

View Source rez_inventory.js, line 205

slot_id of the slot containing the item, or null if no slot contains it

string | null

# static countItemsInSlot(slot_id) → {integer}

Parameters:
Name Type Description
slot_id string

View Source rez_inventory.js, line 184

number of items in the given slot

integer

# static elementInitializer()

called as part of the init process this creates the inital inventory slots

View Source rez_inventory.js, line 44

# static getFirstItemForSlot(slot_id) → {string}

Parameters:
Name Type Description
slot_id string

View Source rez_inventory.js, line 81

id of first item in the slot

string

# static getItemsForSlot(slot_id) → {array}

Parameters:
Name Type Description
slot_id string

View Source rez_inventory.js, line 91

contents of the specified slot

array

# static getSlot(slot_id) → {object}

Parameters:
Name Type Description
slot_id string

View Source rez_inventory.js, line 112

reference to the slot with the given id or throws an Error if the slot is either not defined, or not part of this inventory.

object

# static itemFitsInSlot(slot_id, item_id) → {boolean}

Parameters:
Name Type Description
slot_id string
item_id string

View Source rez_inventory.js, line 220

true if the item will fit with any other contents of the slot

boolean

# static removeEffects(slot_id, item_id)

Parameters:
Name Type Description
slot_id string
item_id string

View Source rez_inventory.js, line 435

# static removeItemForSlot(slot_id, item_id)

removes the specified item from the specified inventory slot

Parameters:
Name Type Description
slot_id string
item_id string

View Source rez_inventory.js, line 399

# static setItemForSlot(item_id)

replaces any existing item content for the slot with this item

Parameters:
Name Type Description
item_id string

View Source rez_inventory.js, line 164

# static setItemsForSlot(items)

replaces any existing item content for the slot with these items

Parameters:
Name Type Description
items array

array of item ids

View Source rez_inventory.js, line 174

# static setSlot(slot_id, items)

Parameters:
Name Type Description
slot_id string
items array

array of item id's

View Source rez_inventory.js, line 127

# static shouldApplyEffects(slot_id)

Determine whether effects should be applied to this inventory and the specified slot.

Parameters:
Name Type Description
slot_id string

View Source rez_inventory.js, line 351

# static slotAcceptsItem(slot_id, item_id) → {boolean}

Parameters:
Name Type Description
slot_id string
item_id string

View Source rez_inventory.js, line 249

true if the given item has a type that this slot accepts

boolean

# static slotContainsItem(slot_id, item_id) → {boolean}

Parameters:
Name Type Description
slot_id string
item_id string

View Source rez_inventory.js, line 194

true if the item_id is in the slot

boolean

# static slotIsOccupied(slot_id) → {boolean}

Parameters:
Name Type Description
slot_id string

View Source rez_inventory.js, line 102

true if there is at least one item in the slot

boolean