DecisionInstance

The DecisionInstance is an object representing a Decision, an opportunity to choose the next node that will be pushed to the playlist and played.
A decision is generally made by a user via GUI, programmatically by calling the .make() method, or automatically by the decider specified when the decision was added (or the default decider).
Most commonly, a DecisionInstance instance will be used to display an overlay to the user showing the options (children) and prompting them to make a choice before the time elapses and push the chosen node to the playlist.
If the time runs out, a choice will be made for the user by the decider, which should be reflected in the GUI.

Example

var decision = player.decision.get('someNodeName');
decision.on('start', function(decision) {
    console.log('DecisionInstance started for node:', decision.parent.id);
});
decision.on('made', function(decision) {
    console.log('Decision has been made for node:', decision.parent.id);
    console.log('Selected node:', decision.selected.node.id,);
});

Properties

decision.parent : Node
propertyreadonly

The parent node (the node that this decision is attached to).

Example

console.log('This represents the decision of node', decision.parent.id);

decision.children : Array.<Node>
property

An array of the decision’s children, specified when the decision was added via add.
Typically, one of these child nodes will be pushed to the playlist as a result of the decision.

Example

console.log(
    'The names of the children nodes to choose from are',
    decision.children.map(node => node.id)
);

decision.defaults : Array.<Node>
property

An array of the decision’s defaults, specified when the decision was added via add.
If no custom decider is specified, and the decision ends before a decision has been made, the default decider will randomly choose from one of these defaults.

Example

console.log(
    'The names of the default nodes to choose from are',
    decision.defaults.map(node => node.id)
);

decision.selected : selectedObject
propertyreadonly

A selectedObject that describes the node selected by the instance.

Example

if (decision.selected.node && decision.selected.node.id === 'myNodeId') {
    console.log('myNodeId was selected');
}

decision.decider : decider
property

This DecisionInstance’s custom value for the decider property.
If a decider is specified for this specific decision, it will be run when make() is called with no arguments, or end is reached and no decision has been made.
If no decider has been specified for this specific decision, this property’s value will be undefined; decisions will default to the global decider.

Default: undefined
See: decider
Example

function selectFirstChild(parent, children) {
    console.log('Selecting first child!');
    return children[0];
}
decision.decider = selectFirstChild;

decision.on('start', function() {
    // As soon as the decision starts, we call `make()` with no arguments
    // which will call `selectFirstChild`, logging "Selecting first child!" and selecting the first child in the `children` array
    decision.make();
}

decision.checkpoints : object
property

This DecisionInstance’s object describing its auto-registering-checkpoints settings.
Described at length at the add method.
This getter / setter can be used to override checkpoints settings for a specific DecisionInstance.
This is the recommended way to disable or change the times of automatically-registered checkpoints for one or many nodes.

See: add
Example

// Unregister the checkpoint that was automatically registered for one decision
var decisionRemoveCheckpoint = player.decision.get('some_node_that_shouldnt_have_a_checkpoint');
decisionRemoveCheckpoint.checkpoints.enabled = false;

// Change the timing (relative to startTime) of the checkpoint automatically registered for a decision
var decisionMoveCheckpoint = player.decision.get('some_node_whose_checkpoint_time_is_wrong');
decisionMoveCheckpoint.checkpoints.time = -1;

decision.autoPushSingleChild : Boolean
property

An instance-specific setting of whether, if this decision has a single child, that child should be pushed as quickly as possible.
true (default) means we fall back to the global plugin autoPushSingleChild setting (also true by default)
false means that this node should wait until the end of the decision, when a decider would normally be run, to push the single child

See: autoPushSingleChild

decision.duration : number
propertyreadonly

The decision’s total duration, in seconds.

Example

console.log('This decision will last for a total of', decision.duration, 'seconds.');

decision.remainingTime : number
propertyreadonly

The decision’s remaining time, in seconds.
While a decision is inactive, this will be equal to the decision’s total duration.

Example

decision.on('timeupdate', () => {
    console.log('Decision remaining time:', decision.remainingTime);
});

decision.progress : number
propertyreadonly

The decision’s progress, as a percentage from 0 to 1, where 0 is the start of the decision and 1 is the end of the decision.
While a decision is inactive, this will be 0.

Example

decision.on('timeupdate', () => {
    console.log('Decision progress:', decision.progress);
});

decision.state : string
propertyreadonly

One of three possible states a decision can be in:
"inactive" - playback has not reached the start of the decision yet, or the decision has run its course and playback has already passed the end of the decision.
"active" - playback reached the start of the decision, and no decision has been made yet.
"made" - an outcome has been selected, and playback has not reached the end of the decision yet.
This can be especially useful to refer to when creating callbacks or GUI that don’t follow the exact lifecycle of a decision.

Example

// I want to play an audio telling the user to hurry up if they haven't decided by 12 seconds into a node
var decision = player.decision.get('myNodeId');
decision.parent.on('timeupdate:12', function() {
    if (decision.state === 'active') {
        player.audio.play('hurryup');
    }
});

Methods

decision.on(evt, listener)
method

Adds a listener function to the specified event on the decision.
If the listener function returns true then it will be removed after it is called.

See: once, off, trigger

Param Type Description
evt string | RegExp Name of the event to attach the listener to.
listener function Method to be called when the event is triggered. If the function returns true, then it will be removed after calling.

decision.once(evt, listener)
method

Adds a listener function to the event on the decision, this listener will automatically be removed after first execution.

See: on, off, trigger

Param Type Description
evt string | RegExp Name of the event to attach the listener to.
listener function Method to be called when the event is triggered.

decision.off(evt, listener)
method

Removes a listener function from the event on the decision.

See: on, once, trigger

Param Type Description
evt string | RegExp Name of the event to remove the listener from.
listener function Method to remove from the event.

decision.trigger(evt)
method

Triggers an event of your choice.
When triggered, every listener attached to that event will be executed.
If you pass the optional arguments then those arguments will be passed to every listener upon execution.

See: on, once, off

Param Type Description
evt string | RegExp Name of the event to emit and execute listeners for.
[…args] * Optional arguments to be passed to each listener.

decision.make([child], [options])
method

Makes an active decision.
If a child node is provided as an argument, that node will become the outcome of the decsion, and will be pushed to the playlist.
If no arguments are provided, this forces the decision’s decider to automatically select a child node.
For instance, if a custom decider was specified, and you know that the decider relies on a variable that has already been set, you should call make() with no arguments to invoke that decider.

If the decision’s state is inactive, or already made, this call will be ignored with a warning.

Param Type Description
[child] string | Node Optional. If specified, this is the node or id of the child node that will be played after the parent.
[options] object An options object.
[options.seek] boolean Optional. If true, the player will immediately seek to the node that is pushed.
[options.data] object Optional. Default {}. Any custom data to attach to this make() invocation which will be accessible in the corresponding made event and in the decision reduxState. This is usually useful for linking made events with data from the originating call of the make() method.

Events

“start”
event

Triggered when playback reaches a decision start time, making the decision’s state “active”.

Param Type Description
decision DecisionInstance the decision that has just started.

Example

decision.on('start', function(decision) {
    console.log('Decision started');
});

“end”
event

Triggered when playback reaches a decision end time, making the decision’s state “inactive”.
Usually, after a decision ends, the decision GUI will fade out for a set amount of time.
This is also triggered when the player seeks away from a decision.

Param Type Description
decision DecisionInstance the decision that just ended.

Example

decision.on('end', function(decision) {
    console.log('Decision ended');
});

“made”
event

Triggered when the decision is made, either by code calling make or immediately before the end of a decision when a decider is invoked.
Note: To support legacy projects that might call playlist.push() directly, if a decision is active, but a node has been pushed from elsewhere, the decision will consider itself made and fire this event. Nodes that are pushed with a data: { decisionIgnore: true } property will be ignored, and the decision will continue to be active

Param Type Description
decision DecisionInstance the decision that was just made.

Example

decision.on('made', function(decision) {
    console.log('Decision made! Selected node:', decision.selected.node.id);
});

“timeupdate”
event

Triggered every 250ms while the decision is active, the timeupdate event allows you to animate elements as long as the decision is playing.
This allows a GUI listener to only worry about listening to a single event rather than handling interruptions in playback (play, pause, waiting, etc.)

Param Type Description
decision DecisionInstance the active decision whose time is updating

Example

decision.on('timeupdate', function(decision) {
    console.log('Decision progress:', decision.progress);
});

Callbacks

selectedObject : object
readonly

An object describing the outcome of the decision that was made while the decision is in made state.
An empty object while a decision is still in active or inactive states.

selectedObject.node : Node
property

The node that was chosen as a result of this decision.

selectedObject.autoDecided : boolean
property

false if the node was chosen explicitly via a call to .make() (or was pushed from code elsewhere not controlled by the DecisionInstance);
true if the decision reached its end and a decider function was automatically called

selectedObject.seek : boolean
property

true if make was called with options.seek set to true, otherwise false.

selectedObject.data : object
property

Any custom data attached to the make invocation that triggered this event to fire.

Rate this page: X
Tell us more!