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 via the init() method, which runs these steps in order:

Creates static properties (from declared attributes) and dynamic properties (ptable, property, bht, template types), then runs dynamic attribute initializers
Applies mixins defined in the $mixins attribute
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 element-specific 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 53

Methods

# addCopy(paramsopt)

create a copy of this object and add it to the game. Pass {id: "..."} to assign a specific id, otherwise one is auto-generated.

Parameters:

Name	Type	Attributes	Description
`params`	`object`	<optional>	options for the copy
`id`	`string`	<optional>	id to assign to the object copy; auto-generated if omitted
`post_init_fn`	`function`	<optional>	called with the new copy after `init()` has run (so `on_init` has fired and all attribute accessor properties exist — plain `copy.attrName = value` assignment is safe here) but before the `copy` event fires. Use this to set instance-specific values, e.g. a procedurally-chosen `level`, that an `on_copy` handler then reads to finish setting up the object.

View Source rez_0_basic_object.js, line 855

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

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

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 1155

# applyMixins()

Applies the mixins declared in the $mixins attribute, attaching each mixin's custom properties and methods to this object. Shared by init() and reInit().

View Source rez_0_basic_object.js, line 370

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

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

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 216

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 108

# copyAssigningId(id, paramsopt) → {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	Attributes	Description
`id`	`string`		the id to assign to the copy
`params`	`object`	<optional>	options for the copy
`post_init_fn`	`function`	<optional>	called with the new copy after `init()` has run (so `on_init` has fired and all attribute accessor properties exist — plain `copy.attrName = value` assignment is safe here) but before the `copy` event fires. Use this to set instance-specific values, e.g. a procedurally-chosen `level`, that an `on_copy` handler then reads to finish setting up the object.

View Source rez_0_basic_object.js, line 809

Returns:

copy of the current object

Type: object

# copyForLoad(id) → {object}

Rebuilds a procedurally-created copy while loading a save. Parallels copyAssigningId but runs reInit() (structural-only) instead of init(), so no generative initializers, elementInitializer(), init event, or copy event fire. The $auto_id_idx/$template/$original_id metadata set here is overwritten by the archived values when the loader subsequently calls loadData() on the copy.

Parameters:

Name	Type	Description
`id`	`string`	the id to assign to the reconstructed copy

View Source rez_0_basic_object.js, line 836

Returns:

a structurally-initialized copy of this object

Type: object

# copyWithAutoId(paramsopt)

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

Parameters:

Name	Type	Attributes	Description
`params`	`object`	<optional>	forwarded to `copyAssigningId`; see its `post_init_fn` param

View Source rez_0_basic_object.js, line 798

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

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

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

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

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

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

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

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

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

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

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

Returns:

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

Type: string

# elementInitializer()

Hook method for subclass-specific initialization. Called during init() 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 753

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

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 149

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 985

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. Note that for certain value types (function, dice roll) you obtain the result (value) not the attribute value. For these cases use getAttribute() instead.

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 996

Returns:

attribute value

Type: *

# getNextAutoId()

returns the next auto id in the sequence

View Source rez_0_basic_object.js, line 774

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

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 1141

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 964

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 1068

Returns:

true if this object has the specified tag

Type: boolean

# hasValue(attrName) → {boolean}

Parameters:

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

View Source rez_0_basic_object.js, line 974

Returns:

true if the attribute exists and has been assigned a non-placeholder value

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 183

Returns:

the unique identifier for this object

Type: string

# init()

Runs the complete initialization lifecycle for this object. After init completes, isInitialized returns true. The steps run in order because each depends on the previous:

Create properties: static properties (getter/setters for each attribute) and dynamic properties (ptable, property, bht, template types), then run dynamic attribute initializers in priority order.
Apply mixins declared in the $mixins attribute — these attach to the properties created in step 1.
Element-specific setup: call elementInitializer() for subclass-specific initialization, then fire the 'init' event. Skipped for template objects (those with $template: true), since templates are not used directly.

View Source rez_0_basic_object.js, line 312

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

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

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 227

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 911

Returns:

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

Type: boolean

# kindOf(name) → {boolean}

Checks whether this object's type hierarchy includes the given name. For example, given @elem foo = object and @elem bar = foo, an instance of @bar returns true for kindOf("bar"), kindOf("foo"), and kindOf("object").

Parameters:

Name	Type	Description
`name`	`string`	element type or alias name to test

View Source rez_0_basic_object.js, line 170

Returns:

true if this object is of the given kind anywhere in its alias chain

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 279

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 238

Returns:

true if this object has changed attributes requiring save

Type: boolean

# reInit()

Structural-only initialization for objects reconstructed from a save archive (see RezGame#load). Builds the JavaScript property machinery — static getter/setters, dynamic-property accessors (ptable/property/bht/template), $delegate getters — and applies $mixins. None of these mutate game state; they reproduce identically on every run.

It deliberately omits everything generative: the $copy/initializer/dieroll attribute initializers, elementInitializer() (which establishes initial state such as an actor's moveTo or an inventory's initial contents), and the init event. The results of those steps were captured in the archive during play and are restored by loadData(); re-running them would reset or duplicate state. The loader fires the did_load event afterwards.

View Source rez_0_basic_object.js, line 346

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

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 1169

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

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

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 1037

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

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

Returns:

this object for method chaining

Type: RezBasicObject

# unmapAttr(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 886

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 932

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 138

Returns:

the singleton game instance

Type: RezGame