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 attribute that has been assigned. On save, archiveInto() serializes only those attributes (excluding those listed in $no_archive). The loadData() method restores attributes from a saved archive.

Tracking happens in setAttribute(), which property assignment calls. Rez cannot see inside an attribute's value, so changing a list, set or record in place (push, splice, list[0] = x, record.key = x) does NOT flag the attribute. An attribute that is only ever changed in place, and never assigned, is missing from the save file. Change a collection in place with modifyAttribute(attrName, fn), or call markChanged(attrName) afterwards, or assign the attribute a new value.

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 86

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 910

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

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

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 1267

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

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

The current value of each changed attribute is saved, so in-place changes to a collection are saved provided the attribute was assigned or flagged with modifyAttribute() or markChanged() at some point. An attribute that has only ever been changed in place is not saved.

Parameters:

Name	Type	Description
`archive`	`object`	the archive object to write to

View Source rez_0_basic_object.js, line 294

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

Returns:

the raw attributes object

Type: object

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

Returns the set of attribute names that have been assigned (via setAttribute() or property assignment) or flagged with markChanged() or modifyAttribute() since object creation. Used by the persistence system to determine what needs to be saved.

Changes made inside a list, set or record without assigning the attribute are not tracked, see modifyAttribute().

View Source rez_0_basic_object.js, line 256

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 148

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

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 891

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 853

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

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

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

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

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

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

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

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

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

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

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

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 808

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

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 189

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 1040

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 1051

Returns:

attribute value

Type: *

# getNextAutoId()

returns the next auto id in the sequence

View Source rez_0_basic_object.js, line 829

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

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 1253

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 1019

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 1180

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 1029

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 223

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 366

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

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

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 272

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 966

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 210

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 329

Throws:

if attrs is not an object

Type: Error

# markChanged(attrName)

Flags an attribute as changed so that it is included in the save file, without assigning it a new value. Rez can only detect that an attribute has changed when it is assigned, so use this after changing a list, set or record in place. Where the change is made at the call site prefer modifyAttribute(), which does this for you. This is for when the change is made elsewhere, for example by a helper function that is handed the list.

This only affects saving. Unlike setAttribute() it does not run <attr>_changed or attr_change handlers, notify observers, update bound controls or record the change for undo. If you need those, assign a new value instead, for example actor.inventory = [...actor.inventory, item].

Parameters:

Name	Type	Description
`attrName`	`string`	name of the attribute to flag for saving

View Source rez_0_basic_object.js, line 1129

Throws:

if the object has no attribute with this name

Type: Error

Example

actor.inventory.push(item);
actor.markChanged("inventory");

# modifyAttribute(attrName, modifyFn) → {*}

Changes a list, set or record attribute in place and makes sure the change is saved. The attribute is flagged with markChanged() and then modifyFn is called with the live value, so the change and the flag can't get separated. The attribute is flagged before modifyFn runs, so it is also saved if modifyFn throws part way through.

This only affects saving, see markChanged() for what it does not do.

Parameters:

Name	Type	Description
`attrName`	`string`	name of the attribute whose value is going to be modified
`modifyFn`	`function`	called with the current value of the attribute, which it may change in place

View Source rez_0_basic_object.js, line 1156

Throws:

if the object has no attribute with this name

Type: Error

Returns:

whatever modifyFn returns

Type: *

Example

actor.modifyAttribute("inventory", (inventory) => inventory.push(item));
const [removed] = actor.modifyAttribute("inventory", (inventory) => inventory.splice(index, 1));
actor.modifyAttribute("flags", (flags) => { flags.door_open = true; });

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

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 400

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

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 1281

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

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

Returns:

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

Type: * | boolean

# setAttribute(attr_name, new_value, notify_observers)

Sets the attribute, runs the <attr>_changed event, flags the attribute to be included in the save file and (unless notify_observers is false) notifies observers, bound controls and the undo manager.

This is the only thing that flags an attribute for saving. Changing a list, set or record in place does not go through here, use modifyAttribute() for that.

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 1092

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

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

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 941

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 987

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 178

Returns:

the singleton game instance

Type: RezGame