Consensus Service

The Consensus Service allows you to build common features in multiplayer games like:

- Delaying execution of an operation until all users within a world have 'submitted'
- Enforcing timed 'rounds' within the game
- Providing the model with default values for users who haven't submitted

The consensus endpoint is scoped by world, and acts upon the current run in the world. 

    var wm = new F.manager.WorldManager({ model: 'mymodel.vmf' });
    wm.getCurrentWorld().then(function (world) {
        var cs = new F.service.Consensus({ 
            name: 'round-1',
            worldId: world.id
        });
        return cs;
    });

You can optionally provide a `consensusGroup` parameter to group related consensus steps. For example:

    new F.service.Consensus({ 
        consensusGroup: 'round'
        name: '1',
        worldId: world.id
    });

This allows you to use `F.service.ConsensusGroup` to list out/ delete all consensus points within that group for reporting.

Constructor options

Required?	Name	Type	Description
Yes	worldId	string	Id of world this consensus service is a part of
Yes	name	string	Name Unique identifier for this consensus point (e.g. step-1, step-2 etc.)
	consensusGroup	string	This allows you to use F.service.ConsensusGroup to list out/ delete all consensus points within the given 'consensusGroup' for reporting.; if not passed in, a group name of 'default' is assumed.
	token	string	For projects that require authentication, pass in the user access token (defaults to undefined). If the user is already logged in to Epicenter, the user access token is already set in a cookie and automatically loaded from there. (See more background on access tokens). @see Authentication API Service for getting tokens.
	transport	JQueryAjaxOptions	Options to pass on to the underlying transport layer. All jquery.ajax options are supported.
	server	object
	server.host	string	The value of host is usually the string api.forio.com, the URI of the Forio API server. This is automatically set, but you can pass it explicitly if desired. It is most commonly used for clarity when you are hosting an Epicenter project on your own server
	server.protocol	https / http	Defaults to https

Methods

create(params[, options])

Creates a new consensus point

Parameters

Required?	Name	Type	Description
Yes	params	object	creation options
Yes	params.roles	Array.<string> / {"string":["number"]}
	params.defaultActions	{"string":["Array.<object>"]}	Actions to take if the role specified in the key does not submit
	params.ttlSeconds	number	How long the consensus point lasts for - note you'll still have to explicitly call forceClose yourself after timer runs out
	params.executeActionsImmediately	boolean	Determines if actions are immediately sent to the server. If set to false, only the last action which completes the consensus will be passed on
	options	object	Overrides for service options

Example

cs.create({
                roles: ['P1', 'P2'],
                defaultActions: {
                    P1: [{ name: 'submitPlayer1', arguments: [1] }],
                    P2: [{ name: 'submitPlayer2', arguments: [2] }],
                },
                ttlSeconds: 10
            }

updateDefaults(params[, options])

Update defaults set during create. Currently only updating defaultActions is supported.

Parameters

Required?	Name	Type	Description
Yes	params	{"defaultActions":["Array.<actions>"]}	Consensus defaults to override
	options	object	Overrides for service options

load([options])

Returns current consensus point

Parameters

Required?	Name	Type	Description
	options	object	Overrides for service options

delete([options])

Deletes current consensus point

Parameters

Required?	Name	Type	Description
	options	object	Overrides for service options

forceClose([options])

Marks current consensus point as complete. Default actions, if specified, will be sent for defaulting roles.

Parameters

Required?	Name	Type	Description
	options	object	Overrides for service options

Example

cs.forceClose();

submitActions(actions[, options])

Submits actions for your turn and marks you as having submitted. If executeActionsImmediately was set to true while creating the consensus point, the actions will be immediately sent to the model. Note that you can still call operations from the RunService directly, but will bypass the consensus requirements.

Parameters

Required?	Name	Type	Description
Yes	actions	Array.<object> / {"name":["string"],"arguments":["Array.<any>"]}	Actions to send
	options	object	Overrides for service options

Example

cs.submitActions([{ name: 'step', arguments: [] }]);

undoSubmit([options])

Reverts submission. Note if executeActionsImmediately was set to true while creating the consensus point the action will have already been passed on to the model.

Parameters

Required?	Name	Type	Description
	options	object	Overrides for service options

getCurrentConfig()

Returns current configuration

Parameters

None