The variables plugin aims to provide a simple API for defining and updating variables.
It uses a node-centric approach, where metadata in Nodes will cause variables to be updated/set.
Variables values can then be used to make decisions during playback (e.g. go to win node if score is above 200, or lose node otherwise).
Example
// Initialize a score numeric variable
player.variables.register({
name: 'score',
action: 'sum',
initialValue: 0,
updateOn: 'playlistpush',
resetOn: 'playlistreset',
dataSet: {
node_a: 5,
node_b: 20,
node_c: -10
}
});
// Choose ending according to accumulated score
player.variables.connect({
from: 'node_game_end',
to: function(variables) {
// If score is greater than 200 at the time we've reached the last node of gameplay ('node_game_end'),
// Let's go to 'node_win' next
if (variables.score >= 200) {
return 'node_win';
}
// Otherwise, go to 'node_lose'
return 'node_lose';
},
evaluateOn: 'playlistpush'
});
- Table of Contents
- Properties
- version pro
- Methods
- Events
- Properties
Properties
player.variables.version : string
The variables plugin’s version string.
Example
console.log('The variables plugin version is', player.variables.version);
Methods
player.variables.register(name, [options])
Registers a new variable with the variables plugin.
This variable will be automatically updated throughout playback via metadata set on the nodes.
There are 2 ways to invoke this function:
1. With a single options
object that must include a name
param: player.variables.register({name: 'myVar', ...})
2. With the following signature: player.variables.register(name, [options])
See: variables.update, variables.reset
Param | Type | Description |
---|---|---|
name | string |
The variable’s name. |
[options] | object |
An optional options object (if this is the only argument, must include name param). |
[options.name] | string |
The variable’s name. If invoked with options object as the only argument, this is required. |
[options.action] | string |
Optional. The action that will be used when updating variable’s value. Values set and sum are supported out of the box. You can register custom actions via the registerAction method. Default: 'set' . |
[options.initialValue] | * |
Optional. The initial value of the variable. When the variable is reset, it’ll be returned to this value. Default: '' for set / custom actions, and 0 for sum action. |
[options.dataSet] | object |
Optional. An object that maps node ids to values. These values will be set on the node object under node.data.variables[variableName] . Each node that has a property with this variable name will cause the value to be updated. Default: null . |
[options.updateOn] | string |
Optional. When should the variable be updated? This can be any event that’s triggered on the player, as long as the first argument of this event is a node object. For instance, you can set this to 'nodestart' or 'playlistpush' . Default: 'playlistpush' . |
[options.resetOn] | string |
Optional. When should the variable be reset to its initialValue? This can be any event that’s triggered on the player. Default: 'playlistreset' . |
[options.verbose] | boolean |
Optional. If true, will log variable updates/resets to console. Default: false . |
[options.trackingEnabled] | boolean |
Optional. If true, will automatically track variable registration and updates using the tracker plugin. Default: false . |
Example
// Register a score numeric variable
player.variables.register({
name: 'score',
action: 'sum',
initialValue: 0,
updateOn: 'playlistpush',
resetOn: 'playlistreset',
dataSet: {
node_a: 5,
node_b: 20,
node_c: -10
}
});
// Register a pastry variable
player.variables.register('pastry', {
action: 'set',
updateOn: 'nodestart',
dataSet: {
node_donut: 'donut',
node_cupcake: 'cupcake',
node_muffin: 'muffin',
node_beignet: 'beignet'
}
});
// Register a bar variable
player.variables.register('bar');
player.variables.has(name) ⇒ boolean
Checks whether a variable with given name has been registered.
Returns: boolean
- True if the variable has been registered, false otherwise.
Param | Type | Description |
---|---|---|
name | string |
The variable’s name. |
Example
player.variables.register('fruit');
player.variables.has('fruit'); // true
player.variables.has('vegetable'); // false
player.variables.getValue(name) ⇒ *
Get the current value of a registered variable.
Returns: *
- The variable’s current value.
Param | Type | Description |
---|---|---|
name | string |
The variable’s name. |
Example
player.variables.register('fruit', {initialValue: 'apple'});
player.variables.getValue('fruit'); // 'apple'
player.variables.setValue(name, newValue)
Set/assign a new value to a registered variable.
See: variables.update
Param | Type | Description |
---|---|---|
name | string |
The variable’s name. |
newValue | * |
A new value to be assigned to the variable. |
Example
player.variables.register('fruit', {initialValue: 'apple'});
player.variables.getValue('fruit'); // 'apple'
player.variables.setValue('fruit', 'watermelon');
player.variables.getValue('fruit'); // 'watermelon'
player.variables.registerAction(name, fn)
Register a custom action function that will be invoked when updating registered variables that use this action.
NOTE: Functions cannot be saved/restored via checkpoints. For more info, refer to checkpoints.
Param | Type | Description |
---|---|---|
name | string |
A unique action name. |
fn | actionFn |
An action function. |
Example
// Register a custom multiply action
player.variables.registerAction('multiply', function(oldValue, newValue) {
return oldValue * newValue;
});
// Use this custom action when registering a variable
player.variables.register({
name: 'myVariable',
action: 'multiply',
initialValue: 1,
dataSet: {...}
});
player.variables.connect(from, to, [options])
Add connection logic.
When the next node following from
needs to be decided, the to
function will be called and its return value will be pushed to the playlist.
There are 2 ways to invoke this function:
1. With a single options
object that must include from
and to
params:player.variables.connect({ from: 'node_a', to: function() { ... } })
2. With the following signature: player.variables(from, to, [options])
NOTE: Functions cannot be saved/restored via checkpoints. For more info, refer to checkpoints.
See: variables.connect
Param | Type | Description |
---|---|---|
from | string | Node | RegExp | function | Array.<*> |
The node (or nodes) from which to connect to (aka the decision‘s parent). This value can either be a string (node id), a node object, a RegExp that will match one or more node ids, a function that receives a node object and returns true if it matches, or an array of any of these. |
to | connectToFn |
A callback function that will be invoked when it’s time to make a decision. |
[options] | object |
An optional options object. |
[options.evaluateOn] | string |
Default "" (empty string). The evaluateOn option governs when the to function will be invoked and the next node will be pushed to the playlist. The given string value will be used to listen to that event on the from node. To append the next node at the earliest possible moment, use the value "playlishpush" (will evaluate the to function and push the next node as soon as the from node has been pushed). The default value "" (empty string) will fallback to using the decision plugin to set up a decider function (which is called right before the from node ends, at the decision’s end). |
Example
// Choose ending according to accumulated score
player.variables.connect({
from: 'node_game_end',
to: function(variables) {
// If score is greater than 200 at the time we've reached the last node of gameplay ('node_game_end'),
// Let's go to 'node_win' next
if (variables.score >= 200) {
return 'node_win';
}
// Otherwise, go to 'node_lose'
return 'node_lose';
},
evaluateOn: 'playlistpush'
});
// Choose a drink to go along with a pastry
player.variables.connect(
[/^node_pre_drink/, 'node_other_pre_drink'],
function(variables) {
if (variables.pastry === 'donut') {
return 'node_vanilla_shake';
}
if (variables.pastry === 'cupcake') {
return 'node_beer';
}
if (variables.pastry === 'muffin') {
return 'node_hot_chocolate';
}
if (variables.pastry === 'beignet') {
return 'node_coffee';
}
},
{
evaluateOn: 'playlistpush'
}
);
Events
“variables.register”
Triggered when a variable has been successfully registered.
See: register
Param | Type | Description |
---|---|---|
name | string |
The variable’s name. |
value | * |
The current (initial) value of the variable. |
Example
player.on('variables.register', function(name, value) {
console.log('The ' + name + ' variable has been registered with value: ' + value);
});
“variables.update”
Triggered when a variable’s value has been updated/changed.
Param | Type | Description |
---|---|---|
name | string |
The variable’s name. |
oldValue | * |
The old value of the variable. |
newValue | * |
The new value of the variable. |
Example
player.on('variables.update', function(name, oldValue, newValue) {
console.log('The ' + name + ' variable has been updated: ' + oldValue + ' => ' + newValue);
});
“variables.reset”
Triggered when a variable’s value has been reset.
See: register
Param | Type | Description |
---|---|---|
name | string |
The variable’s name. |
oldValue | * |
The old value of the variable. |
newValue | * |
The new value of the variable. |
Example
player.on('variables.reset', function(name, oldValue, newValue) {
console.log('The ' + name + ' variable has been reset: ' + oldValue + ' => ' + newValue);
});
“variables.connect”
Triggered when a connection decision has been made.
See: connect
Param | Type | Description |
---|---|---|
parent | Node |
Parent node (aka from node). |
chosenChild | * |
This is the value returned from the connectToFn function. |
Example
player.on('variables.connect', function(parent, chosenChild) {
console.log('A decision has been made. ' + chosenChild + ' will follow ' + parent.id);
});
Objects
reduxState : object
Variables plugin’s redux state sub-object (i.e. player.reduxStore.getState().variables).
See: reduxStore
Example
// player.reduxStore.getState().variables
{
// For each registered variable, the key is the variable's name,
// and the value is its current value
myVarName: 'myVarValue'
}
Callbacks
connectToFn ⇒ string
| Node
| boolean
| undefined
A callback function that will be invoked when a decision has to be made.
This is the 2nd argument of the connect method.
Returns: string
| Node
| boolean
| undefined
- Same as the return value for decider.
Param | Type | Description |
---|---|---|
variables | object |
An object containing all variables registered. |
parent | Node |
The parent node (aka from node - same node that this decision is attached to). |
children | Array.<Node> |
An array of children. |
options | object |
The options object associated with this decision. |
Example
function to(variables, parent, children, options) {
// If score is greater than 200 at the time we've reached the last node of gameplay ('node_game_end'),
// Let's go to 'node_win' next
if (variables.score >= 200) {
return 'node_win';
}
// Otherwise, go to 'node_lose'
return 'node_lose';
}
actionFn ⇒ *
An action function that updates a variable’s value.
This is the 2nd argument of the registerAction method.
Returns: *
- The calculated value that the variable will be set to.
Param | Type | Description |
---|---|---|
oldValue | * |
The old value of the variable. |
newValue | * |
The new value of the variable. |
Example
function myCustomAction(oldValue, newValue) {
return newValue * 2;
}