forio Toggle navigation

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> / [object Object]
  params.defaultActions [object 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 [object Object] 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> / [object Object] 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