Documentation

Class

RezList

RezList()

Constructor

# new RezList()

Represents a list of values with multiple selection strategies. Lists provide various ways to retrieve values - from simple indexed access to sophisticated random selection algorithms that prevent repetition or starvation.

Basic Access

  • values - The underlying array of values
  • length - Number of values in the list
  • at(idx) - Get value at index (supports negative indices)
  • lookup(value) - Find index of a value

Selection Strategies

RezList provides multiple strategies for selecting values:

Random with Replacement

  • randomElement() - Simple random selection, same value can appear consecutively

Random without Starvation

  • randomWithoutStarvation(poolId) - Ensures all values appear with roughly equal frequency
  • warmStarvationPool(poolId) - Pre-populates the pool to avoid initial bias

Cycle

  • nextForCycle(cycleId) - Returns values in sequence, wrapping at the end

Bag (Random without Replacement)

  • randomFromBag(bagId) - Removes and returns a random value; bag empties over time
  • Useful when you want each value exactly once before any repeats

Walk (Random without Replacement, Auto-Reset)

  • randomWalk(walkId) - Like bag, but automatically refills when empty
  • Guarantees all values appear once before any can repeat

Multiple Named Instances

Cycle, bag, walk, and starvation pool methods accept an optional ID parameter, allowing multiple independent instances of the same strategy on one list.

List Includes

Lists can include values from other lists via the includes attribute. Included values are prepended to the list's own values during initialization.

View Source rez_list.js, line 5

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 766

# 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 968

# 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 713

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 1043

# 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

# at(idx) → {*}

Gets the value at the specified index. Supports negative indices where -1 is the last element, -2 is second-to-last, etc.

Parameters:
Name Type Description
idx number

the index to retrieve (supports negative indices)

View Source rez_list.js, line 99

the value at the specified index

*

# 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(id, attributes)

Creates a new list instance

Parameters:
Name Type Description
id string

unique identifier for this list
attributes object

list attributes from Rez compilation
Overrides:

View Source rez_list.js, line 49

# 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 725

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 756

# 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 627

# createBag(bagId) → {Array}

Creates a new bag as a copy of the list's values.

Parameters:
Name Type Description
bagId string

identifier for the bag

View Source rez_list.js, line 289

the newly created bag

Array

# 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 669

# 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 594

# 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 642

# 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 608

# 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 552

# 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()

Called during initialization to merge values from included lists. If the list has an includes attribute, collects values from all referenced lists and prepends them to this list's own values.

Overrides:

View Source rez_list.js, line 60

if an included list does not exist

Error

# 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 825

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 879

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 891

attribute value

*

# getBag(bagId) → {Array}

Gets the bag's current contents, creating it if it doesn't exist.

Parameters:
Name Type Description
bagId string

identifier for the bag

View Source rez_list.js, line 262

the current contents of the bag

Array

# getNextAutoId()

returns the next auto id in the sequence

Inherited From:

View Source rez_0_basic_object.js, line 744

# 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 916

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 1029

the relationship object, or undefined if none exists

RezRelationship | undefined

# getWalk(walkId) → {Array}

Gets the current walk state, creating it if it doesn't exist.

Parameters:
Name Type Description
walkId string

identifier for the walk

View Source rez_list.js, line 328

array of remaining indices to visit

Array

# hasAttribute(name) → {boolean}

Parameters:
Name Type Description
name string

name of the attribute
Inherited From:

View Source rez_0_basic_object.js, line 869

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 957

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 687

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 815

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

boolean

# length() → {number}

Returns the count of values in this list

View Source rez_list.js, line 89

the number of values in the list

number

# 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

# lookup(value) → {number}

Finds the index of the specified value in the list

Parameters:
Name Type Description
value *

the value to find

View Source rez_list.js, line 111

the index of the value, or -1 if not found

number

# 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

# nextForCycle(cycleIdopt) → {*}

Treats the list as a repeating cycle, returning values in order and wrapping back to the start after reaching the end. Each named cycle maintains its own position, allowing multiple independent cycles on the same list.

Parameters:
Name Type Attributes Default Description
cycleId string <optional>
 "$default"

identifier for this cycle

View Source rez_list.js, line 193

the next value in the cycle

*

# randomElement() → {*}

Returns a random element of the list with replacement. The same value can be returned on consecutive calls.

View Source rez_list.js, line 122

a randomly selected value from the list

*

# randomFromBag(bagIdopt) → {*}

Removes and returns a random value from the bag. The bag starts as a copy of the list's values and empties over time. Returns undefined when the bag is empty. Use this when you want each value exactly once.

Parameters:
Name Type Attributes Default Description
bagId string <optional>
 "$default"

identifier for this bag

View Source rez_list.js, line 216

a randomly selected value, removed from the bag

*

# randomRemaining(bagId) → {*}

Low-level method that returns a random element from the bag without removing it. Prefer using randomFromBag() for typical use cases.

Parameters:
Name Type Description
bagId string

identifier for the bag

View Source rez_list.js, line 231

a random value from the bag without removing it, or undefined if empty

*

# randomWalk(walkId) → {*}

Returns a random element without replacement. No item will be returned twice in any given walk. When all items have been returned, a new walk automatically begins with a fresh shuffle. Unlike bag, walk never returns undefined - it automatically resets when exhausted.

Parameters:
Name Type Description
walkId string

identifier for this walk

View Source rez_list.js, line 307

the next random value in the walk

*

# randomWithoutStarvation(poolIdopt) → {*}

Returns a random element while ensuring no element goes too long without being selected. Each element tracks how many selections have passed since it was last chosen. When an element exceeds the starvation threshold (approximately length + length/3), it becomes a priority candidate. Algorithm credit: jkj yuio from intfiction.org

Parameters:
Name Type Attributes Default Description
poolId string <optional>
 "$default"

identifier for the starvation pool

View Source rez_list.js, line 153

a randomly selected value that hasn't been "starving"

*

# 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 1057

# 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 987

# resetWalk(walkId) → {Array}

Resets the walk to a fresh shuffled order of all indices. Uses Fisher-Yates shuffle for unbiased randomization.

Parameters:
Name Type Description
walkId string

identifier for the walk

View Source rez_list.js, line 344

the newly shuffled array of indices

Array

# 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 849

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 930

# setBag(bagId, bag)

Sets the bag's contents directly.

Parameters:
Name Type Description
bagId string

identifier for the bag
bag Array

the new bag contents

View Source rez_list.js, line 277

# 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 1006

# takeFrom(bagId, value)

Low-level method that removes the specified value from the bag. Prefer using randomFromBag() for typical use cases.

Parameters:
Name Type Description
bagId string

identifier for the bag
value *

the value to remove from the bag

View Source rez_list.js, line 248

# 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 777

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 790

if attr_name doesn't end with "_id"

Error

if the attribute is not defined on this object

Error

# warmStarvationPool(poolIdopt)

Pre-populates the starvation pool by running 2*length iterations. This avoids initial bias where early selections might favor certain indices. Call this once before using randomWithoutStarvation if you want more uniform distribution from the start.

Parameters:
Name Type Attributes Default Description
poolId string <optional>
 "$default"

identifier for the starvation pool

View Source rez_list.js, line 137

# 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 836

true if this object handles the specified event

boolean