Documentation

Class

RezPlot

RezPlot()

Constructor

# new RezPlot()

Tracks the progression of a storyline or quest through discrete stages.

A plot represents a linear sequence of stages that the player advances through. Each plot has a current stage and a total number of stages. When the current stage equals the total stages, the plot is considered complete.

Plots must be started before they can be advanced. Starting a plot makes it active but keeps it at stage 0. Advancing moves through stages 1 to N.

Plots fire events at key lifecycle points:

  • "start" when the plot is started (becomes active)
  • "advance" each time the stage increases (with {stage} param)
  • "complete" when the final stage is reached

Use plots for:

  • Main story progression
  • Side quests with multiple steps
  • Tutorial sequences
  • Achievement tracking

Define in Rez:


@plot main_quest {
  stages: 5
  on_did_start: (plot, evt) => {
    console.log("Quest begun!");
  }
  on_did_advance: (plot, evt) => {
    console.log(`Advanced to stage ${evt.stage}`);
  }
}
Mixes In:

View Source rez_plot.js, line 5

Example

Start the plot at runtime

const quest = $("main_quest");
// Activates the plot, fires on_start, sends on_plot_did_start to subscribers
quest.start();
// Moves to stage 1, fires on_advance, sends on_plot_did_advance to subscribers
quest.advance();
// Moves to stage 5, as with stage 1 but since the plot is now at stage 5 (complete)
// also fires on_complete, sends on_plot_did_complete to subscribers
quest.advance(4);

Extends

Members

boolean

# isComplete

Whether this plot has reached its final stage.

View Source rez_plot.js, line 70

Methods

# advance(n)

Advances the plot to the next stage.

Parameters:
Name Type Default Description
n number 1

number of stages to advance (default :1)

Increments the stage attribute and fires appropriate events:

  • "advance" with {stage} param on every advance
  • "complete" when reaching the final stage

Does nothing if the plot is not active or is already complete.

View Source rez_plot.js, line 119

  • advance - On every advance,event: with `{stage}` param
  • event:complete - When reaching the final stage

# notifySubscribers(event, paramsopt)

Fires the named event on every current subscriber, sorted by descending priority attribute (highest first, default 0).

Parameters:
Name Type Attributes Default Description
event string

The event name to fire on each subscriber
params Object <optional>
 {}

Additional parameters passed to the event handler. A source key is automatically added pointing to the notifying element.
Mixes In:

View Source rez_mixins.js, line 47

# revert(n)

Resets the plot clock to a previous stage.

Parameters:
Name Type Default Description
n number 0

stage to

Fires revert on itself and plot_did_revert to subscribers.

View Source rez_plot.js, line 99

# start()

Starts the plot, making it active.

Sets the active attribute to true and fires the "start" event. The plot remains at stage 0 until advance() is called.

Does nothing if the plot is already active.

View Source rez_plot.js, line 84

  • event:start - When the plot becomes active

# subscribe(refOrId)

Adds a game object as a subscriber. The object will receive event notifications when HasSubscribers#notifySubscribers is called. Throws if refOrId cannot be resolved to a known game object ID.

Parameters:
Name Type Description
refOrId string | Object

A game object reference or element ID to add as a subscriber
Mixes In:

View Source rez_mixins.js, line 27

# unsubscribe(refOrId)

Removes a previously added subscriber. Has no effect if the object is not currently subscribed. Throws if refOrId cannot be resolved to a known game object ID.

Parameters:
Name Type Description
refOrId string | Object

A game object reference or element ID to remove
Mixes In:

View Source rez_mixins.js, line 37

# static constructor(id, attributes)

Creates a new RezPlot.

Parameters:
Name Type Description
id string

Unique identifier for this plot
attributes Object

Initial attributes (should include stage and stages)

View Source rez_plot.js, line 54