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,);
});
- Table of Contents
- Properties
- parentpro
- childrenp
- defaultsp
- selectedpro
- deciderp
- checkpointsp
- autoPushSingleChildp
- durationpro
- remainingTimepro
- progresspro
- statepro
- Methods
- Events
- starte
- ende
- madee
- timeupdatee
- Properties
Properties
decision.parent : Node
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>
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>
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
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
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
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
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
The decision’s total duration, in seconds.
Example
console.log('This decision will last for a total of', decision.duration, 'seconds.');
decision.remainingTime : number
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
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
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)
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.
| 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)
Adds a listener function to the event on the decision, this listener will automatically be removed after first execution.
| 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)
Removes a listener function from the event on the decision.
| 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)
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.
| 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])
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, this call will be ignored with a warning.
If the decision’s state is made, this call will be ignored with a warning unless it was called with options.seek true. In that case the decision will be made again.
| 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”
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”
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”
Triggered when the decision is made, either by code calling make or when automatically called at end of a decision or on nodecritical 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”
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
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 :
object- .node :
Node - .autoDecided :
boolean - .seek :
boolean - .data :
object
- .node :
selectedObject.node : Node
The node that was chosen as a result of this decision.
selectedObject.autoDecided : boolean
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
true if make was called with options.seek set to true, otherwise false.
selectedObject.data : object
Any custom data attached to the make invocation that triggered this event to fire.