Constructor

# new RezBasicObject()

The foundational base class for all Rez game objects. Bridges Rez language elements (defined in .rez source files) to living JavaScript objects at runtime.

Every Rez element (@actor, @card, @scene, @item, etc.) extends this class. It provides:

Identity: Unique IDs and element type tracking
Attributes: Key-value store bridging Rez declarations to JS properties
Property Generation: Automatic JS property creation from attributes
Initialization Lifecycle: Three-phase object setup
Event System: Handler dispatch for game logic
Persistence: Save/load via change tracking
Template/Copying: Runtime object instantiation from templates

Initialization Lifecycle

Objects initialize in three phases via the init() method:

init_0: Creates static properties (from declared attributes) and dynamic properties (ptable, property, bht, template types), then runs dynamic attribute initializers
init_1: Applies mixins defined in the $mixins attribute
init_2: Calls elementInitializer() for subclass-specific setup, then fires the 'init' event (skipped for template objects)

Property Generation

Attributes become JS properties automatically:

foo → obj.foo (getter/setter backed by attribute)
bar_id → obj.bar (dereferences ID to actual game object)
damage_die → obj.damage_roll (rolls the RezDie and returns result)
ptable: → weighted random selection property
property: → computed property with custom getter
bht: → behaviour tree instance
template: → template function property

Template Objects

Objects with $template: true are templates meant to be copied via addCopy() or copyWithAutoId(), not used directly. Templates skip init_2 phase initialization.

Persistence

The changedAttributes Set tracks every modified attribute. On save, archiveInto() serializes only changed attributes (excluding those listed in $no_archive). The loadData() method restores attributes from a saved archive.

Static Game Reference

The static game property provides access to the singleton RezGame instance from any game object via this.game.

View Source rez_0_basic_object.js, line 48

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

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

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.

View Source rez_0_basic_object.js, line 713

Returns:

this object for method chaining

Type: 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

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

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.

View Source rez_0_basic_object.js, line 187

Returns:

the raw attributes object

Type: 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.

View Source rez_0_basic_object.js, line 198

Returns:

set of attribute names that have been modified

Type: 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

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

View Source rez_0_basic_object.js, line 725

Returns:

copy of the current object

Type: 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

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

View Source rez_0_basic_object.js, line 627

# 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

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

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

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.

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

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

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.

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

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

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.

View Source rez_0_basic_object.js, line 154

Returns:

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

Type: 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.

View Source rez_0_basic_object.js, line 704

# 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

View Source rez_0_basic_object.js, line 825

Returns:

event handle function or undefined

Type: function | undefined

# game() → {RezGame}

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

View Source rez_0_basic_object.js, line 144

Returns:

the singleton game instance

Type: 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

View Source rez_0_basic_object.js, line 879

Returns:

attribute value

Type: *

# 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

View Source rez_0_basic_object.js, line 891

Returns:

attribute value

Type: *

# getNextAutoId()

returns the next auto id in the sequence

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

View Source rez_0_basic_object.js, line 916

Returns:

the game object referenced by the attribute

Type: 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

View Source rez_0_basic_object.js, line 1029

Returns:

the relationship object, or undefined if none exists

Type: RezRelationship | undefined

# hasAttribute(name) → {boolean}

Parameters:

Name	Type	Description
`name`	`string`	name of the attribute

View Source rez_0_basic_object.js, line 869

Returns:

true if the object defines the specified attribute

Type: 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

View Source rez_0_basic_object.js, line 957

Returns:

true if this object has the specified tag

Type: 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").

View Source rez_0_basic_object.js, line 165

Returns:

the unique identifier for this object

Type: 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

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:

$copy attributes - creates copies of template objects
$delegate attributes - creates delegate properties to other objects
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.

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.

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.

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.

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

View Source rez_0_basic_object.js, line 687

Returns:

instantiated behaviour tree node

Type: RezBehaviour

# isInitialized() → {boolean}

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

View Source rez_0_basic_object.js, line 209

Returns:

true if init() has completed

Type: boolean

# isTemplateObject() → {boolean}

returns the value of the $template attribute

View Source rez_0_basic_object.js, line 815

Returns:

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

Type: 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

View Source rez_0_basic_object.js, line 261

Throws:

if attrs is not an object

Type: 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.

View Source rez_0_basic_object.js, line 220

Returns:

true if this object has changed attributes requiring save

Type: 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.

View Source rez_0_basic_object.js, line 176

Returns:

a reference object containing this object's ID

Type: 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

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

View Source rez_0_basic_object.js, line 987

# 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

View Source rez_0_basic_object.js, line 849

Returns:

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

Type: * | 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

View Source rez_0_basic_object.js, line 930

# 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

View Source rez_0_basic_object.js, line 1006

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

View Source rez_0_basic_object.js, line 777

Returns:

this object for method chaining

Type: 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

View Source rez_0_basic_object.js, line 790

Throws:

if attr_name doesn't end with "_id"

Type: Error

if the attribute is not defined on this object

Type: 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"

View Source rez_0_basic_object.js, line 836

Returns:

true if this object handles the specified event

Type: boolean

# static game() → {RezGame}

Gets the static game reference shared by all RezBasicObject instances.

View Source rez_0_basic_object.js, line 133

Returns:

the singleton game instance

Type: RezGame