Documentation

Class

RezGame

RezGame()

Constructor

# new RezGame()

The central singleton that manages the entire game runtime. RezGame is automatically instantiated with id "game" and is accessible globally via $game.

RezGame provides:

  • Object Registry: All game objects are registered here and accessible via $() or getGameObject(). Objects are indexed by tags and attributes for fast lookup.
  • Scene Management: Controls scene transitions (startSceneWithId), interludes (interludeSceneWithId), and resumption (resumePrevScene) with a scene stack.
  • View System: Manages the RezView that renders content to the DOM, including layout management and bound control updates.
  • Persistence: Save/load functionality via save() and load() methods that serialize/deserialize all changed game object attributes.
  • Undo System: Tracks attribute changes and object creation/deletion for undo support.
  • Flash Messages: Temporary messages displayed on the next render cycle.
  • Systems: Manages enabled RezSystem objects that hook into game events.

The game is started by calling start(containerId) which initializes all objects, builds the view, and starts the initial scene.

View Source rez_game.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 765

# addFlashMessage(message)

adds the given message to the flash to be displayed on the next render

Parameters:
Name Type Description
message string

View Source rez_game.js, line 713

# addGameObject(obj)

adds an object representing a game element to the game world and automatically tagging it by its attributes

Parameters:
Name Type Description
obj object

game-object

View Source rez_game.js, line 329

# addTag(tag)

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

Parameters:
Name Type Description
tag string

the tag to add
Inherited From:

View Source rez_0_basic_object.js, line 967

# addToAttrIndex(elem)

For each attribute defined on this game object, add it to the game-wide index for that attribute.

Parameters:
Name Type Description
elem basic_object

element whose attributes are to be indexed

View Source rez_game.js, line 219

# addToGame() → {RezBasicObject}

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

Inherited From:

View Source rez_0_basic_object.js, line 712

this object for method chaining

RezBasicObject

# addToTagIndex(obj)

indexes the specified game-object for all tags in it's tags attribute

Parameters:
Name Type Description
obj object

game-object

View Source rez_game.js, line 307

# applyEffect(effectId, slotId, itemId)

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

Parameters:
Name Type Description
effectId string

ID of the effect to apply
slotId string

ID of the inventory slot the item is in
itemId string

ID of the item providing the effect
Inherited From:

View Source rez_0_basic_object.js, line 1038

# archiveInto(archive)

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

Parameters:
Name Type Description
archive object

the archive object to write to
Inherited From:

View Source rez_0_basic_object.js, line 231

# attributes() → {object}

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

Inherited From:

View Source rez_0_basic_object.js, line 187

the raw attributes object

object

# buildView()

Assigns the #view private attribute with a RezView that is initialized with a single layout.

View Source rez_game.js, line 694

# canResume() → {boolean}

returns true if there is at least one scene in the scene stack

View Source rez_game.js, line 609

boolean

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

# clearFlashMessages()

empties the flash messages

View Source rez_game.js, line 723

# constructor(element, id, attributes)

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

Parameters:
Name Type Description
element string

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

unique identifier for this object
attributes object

attribute key-value pairs from Rez compilation
Inherited From:

View Source rez_0_basic_object.js, line 103

# copyAssigningId(id) → {object}

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

Parameters:
Name Type Description
id string

the id to assign to the copy
Inherited From:

View Source rez_0_basic_object.js, line 724

copy of the current object

object

# copyWithAutoId()

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

Inherited From:

View Source rez_0_basic_object.js, line 755

# createAttributeByCopying(attrName, value)

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

Parameters:
Name Type Description
attrName string

name of the attribute to set
value object

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

View Source rez_0_basic_object.js, line 624

# createBehaviourTreeAttribute(attrName, value)

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

Parameters:
Name Type Description
attrName string

name of the behaviour tree attribute
value object

attribute value containing the bht specification
Inherited From:

View Source rez_0_basic_object.js, line 666

# createCustomProperty(attrName, value)

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

Parameters:
Name Type Description
attrName string

name of the property to create
value object

attribute value containing the property getter source code
Inherited From:

View Source rez_0_basic_object.js, line 588

# createDelegateProperty(attrName, targetAttr)

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

Parameters:
Name Type Description
attrName string

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

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

View Source rez_0_basic_object.js, line 639

# createDynamicProperties()

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

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

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

Inherited From:

View Source rez_0_basic_object.js, line 428

# createDynamicallyInitializedAttribute(attrName, value)

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

Parameters:
Name Type Description
attrName string

name of the attribute to initialize
value object | RezDie

initializer specification or RezDie instance
Inherited From:

View Source rez_0_basic_object.js, line 604

# createProbabilityTable(attrName, value)

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

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

Parameters:
Name Type Description
attrName string

name of the ptable attribute
value object

attribute value containing the ptable JSON
Inherited From:

View Source rez_0_basic_object.js, line 546

# createStaticProperties()

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

Inherited From:

View Source rez_0_basic_object.js, line 416

# createStaticProperty(attrName)

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

Additionally creates synthetic accessor properties for special attribute name patterns:

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

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

View Source rez_0_basic_object.js, line 366

# createTemplateProperty(attrName, value)

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

Parameters:
Name Type Description
attrName string

name of the template attribute
value object

attribute value containing the template function
Inherited From:

View Source rez_0_basic_object.js, line 461

# element() → {string}

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

Inherited From:

View Source rez_0_basic_object.js, line 154

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

string

# elementAttributeHasChanged(elem, attr_name, old_value, new_value)

should be called whenever an attribute value is changed

Currently this function notifies the undo manager and the view

Parameters:
Name Type Description
elem object

reference to game-object
attr_name string

name of the attribute whose value has changed
old_value *

value of the attribute before the change
new_value *

value of the attribute after the change

View Source rez_game.js, line 409

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

Inherited From:

View Source rez_0_basic_object.js, line 703

# eventHandler(event_name) → {function|undefined}

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

Parameters:
Name Type Description
event_name string

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

View Source rez_0_basic_object.js, line 824

event handle function or undefined

function | undefined

# filterObjects(pred) → {array}

filters all game-objects returning those for which the pred filter returns true

Parameters:
Name Type Description
pred function

predicate to filter with

View Source rez_game.js, line 457

game-objects passing the filter

array

# 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

# getAll(target_type) → {array}

filters all game-objects returning those with the specified type

Parameters:
Name Type Description
target_type string

(optional) a specific game object type (e.g. 'actor', 'item')

View Source rez_game.js, line 468

game-objects with the specified type

array

# getAttribute(name) → {*}

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

Parameters:
Name Type Description
name string

name of the attribute
Inherited From:

View Source rez_0_basic_object.js, line 878

attribute value

*

# getAttributeValue(name, default_value) → {*}

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

Parameters:
Name Type Description
name string

name of the attribute
default_value *

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

View Source rez_0_basic_object.js, line 890

attribute value

*

# getEnabledSystems() → {array}

View Source rez_game.js, line 702

all 'system' game-objects with attribute enabled=true

array

# getGameObject(idOrRef, should_throw) → {basic_object|undefined}

given an element id returns the appropriate game-object reference

Accepts both plain string IDs and {$ref: "id"} objects for backward compatibility. If should_throw is true an exception will be thrown if the element id is not valid. Otherwise null is returned.

Parameters:
Name Type Description
idOrRef string | object

either a string ID or a {$ref: "id"} object
should_throw boolean

(default: true)

View Source rez_game.js, line 364

game-object or undefined

basic_object | undefined

# getNextAutoId()

returns the next auto id in the sequence

Inherited From:

View Source rez_0_basic_object.js, line 743

# getObjectViaAttribute(name, defaultValue) → {RezBasicObject}

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

Parameters:
Name Type Description
name string

attribute name containing an object ID
defaultValue *

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

View Source rez_0_basic_object.js, line 915

the game object referenced by the attribute

RezBasicObject

# getObjectsWithTag(tag) → {array}

returns all game-objects tagged with the specified tag

Parameters:
Name Type Description
tag string

View Source rez_game.js, line 195

array of indexed game-objects that have the specified tag

array

# getRelationship(source_id, target_id) → {RezRelationship|null}

we can cheat looking up a relationship because we know how their IDs are constructed.

Note that in Rez relationships are unidirectional so that getRelationship("a", "b") and getRelationship("b", "a") are different RezRelationship objects.

Parameters:
Name Type Description
source_id string

id of game-object that holds the relationship
target_id string

id of game-object to which the relationship refers

View Source rez_game.js, line 428

the relationship object for this relationship

RezRelationship | null

# getRelationshipWith(targetId) → {RezRelationship|undefined}

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

Parameters:
Name Type Description
targetId string

ID of the target object
Inherited From:

View Source rez_0_basic_object.js, line 1024

the relationship object, or undefined if none exists

RezRelationship | undefined

# getTypedGameObject(id, type, should_throw) → {basic_object|null}

Parameters:
Name Type Description
id string

id of game-object
type string

game object type (e.g. 'actor' or 'item')
should_throw boolean

(default: true)

View Source rez_game.js, line 389

game-object or null

basic_object | null

# hasAttribute(name) → {boolean}

Parameters:
Name Type Description
name string

name of the attribute
Inherited From:

View Source rez_0_basic_object.js, line 868

true if the object defines the specified attribute

boolean

# hasTag(tag) → {boolean}

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

Parameters:
Name Type Description
tag string

the tag to check for
Inherited From:

View Source rez_0_basic_object.js, line 956

true if this object has the specified tag

boolean

# id() → {string}

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

Inherited From:

View Source rez_0_basic_object.js, line 165

the unique identifier for this object

string

# indexAttribute(elem_id, attr_name)

Adds the element to the per-attribute index.

Parameters:
Name Type Description
elem_id string

id of element to add to the per-attr index
attr_name string

View Source rez_game.js, line 241

# indexObjectForTag(obj, tag)

applies the specified tag to the spectified game-object

Parameters:
Name Type Description
obj object

reference to a game-object
tag string

View Source rez_game.js, line 272

# init()

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

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

View Source rez_0_basic_object.js, line 294

# initDynamicAttributes()

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

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

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

Inherited From:

View Source rez_0_basic_object.js, line 496

# init_0()

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

Inherited From:

View Source rez_0_basic_object.js, line 310

# init_1()

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

Inherited From:

View Source rez_0_basic_object.js, line 324

# init_2()

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

Inherited From:

View Source rez_0_basic_object.js, line 350

# instantiateBehaviourTree(treeSpec) → {RezBehaviour}

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

Parameters:
Name Type Description
treeSpec object

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

View Source rez_0_basic_object.js, line 686

instantiated behaviour tree node

RezBehaviour

# interludeSceneWithId(scene_id, params)

interrupts the current scene, pushing it to the scene stack, and then starts the new scene with the given id

Parameters:
Name Type Description
scene_id string
params object

data to pass to the new scene

View Source rez_game.js, line 510

# isInitialized() → {boolean}

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

Inherited From:

View Source rez_0_basic_object.js, line 209

true if init() has completed

boolean

# isTemplateObject() → {boolean}

returns the value of the $template attribute

Inherited From:

View Source rez_0_basic_object.js, line 814

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

boolean

# load(source)

given a JSON source archive restore the game state to what was archived.

Parameters:
Name Type Description
source string

JSON format source archive

View Source rez_game.js, line 152

# loadData(attrs)

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

Parameters:
Name Type Description
attrs object

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

View Source rez_0_basic_object.js, line 261

if attrs is not an object

Error

# needsArchiving() → {boolean}

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

Inherited From:

View Source rez_0_basic_object.js, line 220

true if this object has changed attributes requiring save

boolean

# popScene(params)

removes the top object of the scene stack and makes it the current scene

Parameters:
Name Type Description
params object

data to be passed to the scene being resumed

View Source rez_game.js, line 631

# pushScene()

interrupts the current scene and puts it on the scene stack

View Source rez_game.js, line 619

# ref() → {Object}

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

Inherited From:

View Source rez_0_basic_object.js, line 176

a reference object containing this object's ID

Object

# removeEffect(effectId, slotId, itemId)

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

Parameters:
Name Type Description
effectId string

ID of the effect to remove
slotId string

ID of the inventory slot the item was in
itemId string

ID of the item that provided the effect
Inherited From:

View Source rez_0_basic_object.js, line 1060

# removeFromTagIndex(obj)

unindexes the specified object from all tags in its tags attribute

Parameters:
Name Type Description
obj object

game-object

View Source rez_game.js, line 318

# removeTag(tag)

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

Parameters:
Name Type Description
tag string

the tag to remove
Inherited From:

View Source rez_0_basic_object.js, line 986

# resumePrevScene(params)

finishes the current scene, then pops the previous scene from the scene stack and resumes it

Parameters:
Name Type Description
params object

data to pass back to the previous scene

View Source rez_game.js, line 535

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

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

Parameters:
Name Type Description
event_name string

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

object containing event params
Inherited From:

View Source rez_0_basic_object.js, line 848

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

* | boolean

# save()

triggers a download of the game archive

This uses a hidden link with a 'download' attribute. The link is "clicked" triggering the download of the JSON file. A timeout is used to remove the link.

View Source rez_game.js, line 119

# setAttribute(attr_name, new_value, notify_observers)

Parameters:
Name Type Description
attr_name string

name of attribute to set
new_value *

value for attribute
notify_observers boolean

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

View Source rez_0_basic_object.js, line 929

# setTags(newTags)

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

Parameters:
Name Type Description
newTags Set | Array

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

View Source rez_0_basic_object.js, line 1005

# setViewLayout(layout)

???

Parameters:
Name Type Description
layout *

???

View Source rez_game.js, line 643

# start(container_id)

called automatically from the index.html this runs init on the registered game objects then starts the view and starts the initial scene

Parameters:
Name Type Description
container_id string

id of the HTML element into which game content is rendered

View Source rez_game.js, line 653

# startSceneWithId(scene_id, params)

finish the current scene and start the new scene with the given id

Parameters:
Name Type Description
scene_id string

id of scene game-object
params object

data to pass to the new scene

View Source rez_game.js, line 483

# unindexObjectForTag(obj, tag)

removes the specified tag from the specified game-object

Parameters:
Name Type Description
obj object

reference to a game-object
tag string

a tag to remove

View Source rez_game.js, line 289

# unmap() → {RezBasicObject}

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

Inherited From:

View Source rez_0_basic_object.js, line 776

this object for method chaining

RezBasicObject

# unmap_attr(attr_name)

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

Parameters:
Name Type Description
attr_name string

name of an _id attribute referencing another object
Inherited From:

View Source rez_0_basic_object.js, line 789

if attr_name doesn't end with "_id"

Error

if the attribute is not defined on this object

Error

# updateView()

re-renders the view calling 'will_render' and 'did_render' event handlers on both game and current scene

View Source rez_game.js, line 585

# willHandleEvent(event_name) → {boolean}

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

Parameters:
Name Type Description
event_name string

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

View Source rez_0_basic_object.js, line 835

true if this object handles the specified event

boolean