# new RezCard()
Represents a card in the Rez game engine. Cards are the primary content containers that display narrative text, choices, and interactive elements to the player.
Cards exist within scenes and follow a defined lifecycle:
- start - Card is initialized and becomes the current card
- ready - Card is rendered and ready for player interaction
- finish - Card is being replaced or scene is ending
Template System
Cards use templates to render their content:
$content_template- The main content template (required)$flipped_template- Optional back-side template for use in stack layouts$flipped- Boolean indicating whether to show the flipped template
Scene Relationship
Cards have a transient reference to their containing scene, set when the scene
calls playCard(). In single layout mode, this reference becomes stale when
the card is replaced. In stack layout mode, the reference persists while the
scene is running.
Block System
Each card is wrapped in a RezBlock for rendering. The block manages the card's position in the layout and handles flip state transitions.
Event Handlers
Cards can define event handlers using the on_<event> attribute naming convention:
on_start- Called when the card becomes the current cardon_ready- Called after the card is renderedon_finish- Called when the card is being replacedon_<custom>- Custom events triggered by game logic
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:
# 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
# bindAs() → {string}
Returns the binding identifier used in template rendering. When a card is rendered, its properties are bound to the template context under this name.
"card"
string
# 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 card instance with null scene and block references
Parameters:
| Name | Type | Description |
|---|---|---|
id |
string
|
unique identifier for this card |
attributes |
object
|
card 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:
# current_block(block)
Sets the RezBlock instance for this card. Called by the scene when adding the card to the view layout.
Parameters:
| Name | Type | Description |
|---|---|---|
block |
RezBlock
|
the block to set |
# 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
# 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
# getViewTemplate(flippedopt) → {function}
Returns the appropriate template for rendering this card based on flip state. If flipped is true, returns the $flipped_template (falling back to $content_template if no flipped template exists). Otherwise returns the $content_template.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
flipped |
boolean
|
<optional> |
whether to get the flipped template. Defaults to the card's $flipped attribute. |
if the card has no content template defined
Error
the template function for rendering this card
function
# handleCustomEvent(event_name, evt) → {object}
Handles custom events by looking up and invoking the appropriate event handler.
Event handlers are defined using the on_<event_name> attribute naming convention.
Returns an error object with a descriptive message if no handler is found.
Parameters:
| Name | Type | Description |
|---|---|---|
event_name |
string
|
the name of the custom event to handle |
evt |
RezEvent
|
the event object containing event data |
the result from the event handler, or an error object if no handler exists
object
# 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
# 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
# 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
# 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:
# 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
# scene(scene)
Sets the scene reference for this card. Called by the scene when starting a new card.
Parameters:
| Name | Type | Description |
|---|---|---|
scene |
RezScene
|
the scene to set |
# 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:
# 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