variables

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'
});

Properties

player.variables.version : string
propertyreadonly

The variables plugin’s version string.

Example 

console.log('The variables plugin version is', player.variables.version);

Methods

player.variables.register(name, [options])
method

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
method

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) ⇒ *
method

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)
method

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)
method

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])
method

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”
event

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”
event

Triggered when a variable’s value has been updated/changed.

See: register, setValue

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”
event

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”
event

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
property

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
callback

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 ⇒ *
callback

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;
}
Rate this page:
☆ ☆ ☆ ☆ ☆
X
Tell us more!