# new RezScene()
Represents a scene in the Rez game engine. Scenes are containers that manage the flow of cards and content, handling transitions between different parts of the game narrative.
Scene Lifecycle
Scenes follow a defined lifecycle:
- start - Scene is initialized and begins playing its initial card
- ready - Scene is fully rendered and ready for player interaction
- interrupt - Scene is paused for an interlude (optional)
- resume - Scene continues after an interlude (optional)
- finish - Scene completes and is reset
Layout Modes
Scenes support two layout modes that control how cards are displayed:
- single - Each new card replaces the previous one (default)
- stack - Cards stack on top of each other; finished cards flip to show their back
Card Management
Scenes manage the current card and coordinate card transitions:
initial_card- The first card played when the scene startscurrent_card- The currently active cardlast_card_id- ID of the previously active card- Cards are wrapped in RezBlock instances and added to the scene's view layout
Interludes
Scenes can be interrupted for interludes - temporary scene switches that return to the original scene. The game maintains a scene stack for this purpose:
interrupt()- Called when an interlude beginsresume(params)- Called when returning from an interlude
Event Handlers
Scenes can define event handlers using the on_<event> attribute naming convention:
on_start- Called when the scene startson_ready- Called after the scene is renderedon_start_card- Called when a new card beginson_finish_card- Called when a card finisheson_interrupt- Called when an interlude beginson_resume- Called when returning from an interludeon_finish- Called when the scene ends
Extends
Methods
# addContentToViewLayout(params)
Creates a new content block for the current card and adds it to the scene's view layout
Parameters:
| Name | Type | Description |
|---|---|---|
params |
object
|
parameters to pass to the content block |
# 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:
# 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:
# 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:
this object for method chaining
# 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:
# 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:
# attributes() → {object}
Returns the internal attributes object. Prefer using getAttribute(),
setAttribute(), or property accessors rather than accessing this directly.
- Inherited From:
the raw attributes object
object
# changedAttributes() → {Set.<string>}
Returns the set of attribute names that have been changed since object creation. Used by the persistence system to determine what needs to be saved.
- Inherited From:
set of attribute names that have been modified
Set.<string>
# constructor(id, attributes)
Creates a new scene instance and initializes it to a reset state
Parameters:
| Name | Type | Description |
|---|---|---|
id |
string
|
unique identifier for this scene |
attributes |
object
|
scene attributes from Rez compilation |
- Overrides:
# 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:
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:
# 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 |
- Inherited From:
# 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 |
# 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:
# 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:
# createDynamicProperties()
Creates synthetic properties for special attribute types that require custom behavior beyond simple getter/setter access. Handles:
ptable:- probability tables for weighted random selectionproperty:- computed properties with custom getter functionsbht:- behaviour tree instancestemplate:- template function properties
Skipped for template objects since they don't need runtime property initialization.
- Inherited From:
# 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 |
# 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:
# createStaticProperties()
Iterates through all declared attributes and calls createStaticProperty
for each one, creating JavaScript property accessors for the entire attribute set.
- Inherited From:
# 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
_idget a dereferenced accessor (e.g.,location_idcreates alocationproperty that returns the actual game object, not just the ID) - Attributes ending in
_dieget a roll accessor (e.g.,damage_diecreates adamage_rollproperty 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:
# 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:
# createViewLayout() → {RezStackLayout|RezSingleLayout}
Creates a new view layout based on the scene's layout mode. Returns RezStackLayout for stack mode or RezSingleLayout for single mode.
the appropriate layout instance
# current_block() → {RezLayout}
Returns the view layout that manages how content is displayed in this scene
the current view layout for this scene
# element() → {string}
Returns the element type string that identifies what kind of Rez element this object represents.
- Inherited From:
the Rez element type (e.g., "actor", "card", "scene")
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.
- Inherited From:
# 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:
event handle function or undefined
function
|
undefined
# finish()
Finishes the scene by completing the current card, triggering the finish event, setting running state to false, and resetting the scene
# finishCurrentCard()
Finishes the currently active card by running its finish event, triggering the scene's finish_card event, and in stack layout mode, flipping the card.
# game() → {RezGame}
Instance accessor for the game. Delegates to the static game property.
- Inherited From:
the singleton game instance
# 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:
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:
attribute value
*
# 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:
the game object referenced by the attribute
# 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:
the relationship object, or undefined if none exists
RezRelationship
|
undefined
# getViewLayout() → {RezLayout}
Gets or creates the view layout for this scene. The layout is cached and reused.
the view layout instance for this scene
# getViewTemplate(flipped) → {*}
Returns the layout template for rendering this scene. The flipped parameter is ignored since scenes cannot be flipped.
Parameters:
| Name | Type | Description |
|---|---|---|
flipped |
boolean
|
ignored for scenes (only cards can be flipped) |
the template used to render this scene's layout
*
# hasAttribute(name) → {boolean}
Parameters:
| Name | Type | Description |
|---|---|---|
name |
string
|
name of the attribute |
- Inherited From:
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:
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:
the unique identifier for this object
string
# init()
Runs the complete three-phase initialization lifecycle for this object.
After init completes, isInitialized returns true. The phases are:
- init_0: Property creation and dynamic attribute initialization
- init_1: Mixin application
- init_2: Element-specific initialization and 'init' event
- Inherited From:
# initDynamicAttributes()
Initializes dynamic attributes that require runtime computation. Processes three types of dynamic attributes in order:
$copyattributes - creates copies of template objects$delegateattributes - creates delegate properties to other objectsinitializerattributes - 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:
# 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:
# 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:
# 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:
# 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:
instantiated behaviour tree node
# interrupt()
Interrupts the current scene execution, typically when switching to an interlude scene. Triggers the scene's interrupt event.
# isInitialized() → {boolean}
Returns whether this object has completed its initialization lifecycle. Objects are not fully usable until initialization completes.
- Inherited From:
true if init() has completed
boolean
# isStackLayout() → {boolean}
Determines if this scene stacks cards on top of each other (stack mode) or replaces the current card with each new one (single mode)
true if this scene uses stack layout mode
boolean
# isTemplateObject() → {boolean}
returns the value of the $template attribute
- Inherited From:
true if this object has a $template attribute with value true
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 |
- Inherited From:
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:
true if this object has changed attributes requiring save
boolean
# playCard(newCard, params)
Transitions to a new card, finishing the current card if any, starting the new one, updating the view, and triggering the card's ready event.
Parameters:
| Name | Type | Description |
|---|---|---|
newCard |
RezCard
|
the card instance to play |
params |
object
|
parameters to pass to the card |
# playCardWithId(cardId, params)
Plays a card by looking it up by ID and calling playCard with the card instance
Parameters:
| Name | Type | Description |
|---|---|---|
cardId |
string
|
ID of the card to play |
params |
object
|
parameters to pass to the card |
# ready()
Triggers the scene's ready event, indicating the scene is fully initialized and ready for interaction
# 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:
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:
# 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:
# reset()
Resets the scene to its initial state, clearing the current card, view layout, and running status
# resume(params)
Resumes the scene after an interlude, triggering the scene's resume event. Note: Card resume/ready events are fired by RezGame.resumePrevScene after the view is updated.
Parameters:
| Name | Type | Description |
|---|---|---|
params |
object
|
parameters passed from the interlude scene |
# resumeFromLoad()
Resumes the scene after loading from a saved game state. Ensures the current card is properly restored to the view layout.
if no current card is available to resume
Error
# 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:
returns a response object, or false if the event was not handled
*
|
boolean
# setAttribute(attr_name, new_value, notify_observers)
Parameters:
| Name | Type | Description |
|---|---|---|
attr_name |
string
|
name of attribute to set |
new_value |
*
|
value for attribute |
notify_observers |
boolean
|
whether observers should be notified that the value has changed |
- Inherited From:
# 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:
# start(params)
Starts the scene by initializing it, triggering the start event, setting the running state, and playing the initial card
Parameters:
| Name | Type | Description |
|---|---|---|
params |
object
|
parameters to pass to the scene and initial card |
# startNewCard(card, params)
Sets up a new card as the current card, adds it to the view layout, and triggers the appropriate start events.
Parameters:
| Name | Type | Description |
|---|---|---|
card |
RezCard
|
the card to start |
params |
object
|
parameters to pass to the card |
# 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:
this object for method chaining
# 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 |
- Inherited From:
if attr_name doesn't end with "_id"
Error
if the attribute is not defined on this object
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" |
- Inherited From:
true if this object handles the specified event
boolean