forio Toggle navigation

World API Adapter

A run is a collection of end user interactions with a project and its model -- including setting variables, making decisions, and calling operations. For building multiplayer simulations you typically want multiple end users to share the same set of interactions, and work within a common state. Epicenter allows you to create "worlds" to handle such cases. Only team projects can be multiplayer.

The World API Adapter allows you to create, access, and manipulate multiplayer worlds within your Epicenter project. You can use this to add and remove end users from the world, and to create, access, and remove their runs. Because of this, typically the World Adapter is used for facilitator pages in your project. (The related World Manager provides an easy way to access runs and worlds for particular end users, so is typically used in pages that end users will interact with.)

As with all the other API Adapters, all methods take in an "options" object as the last parameter. The options can be used to extend/override the World API Service defaults.

To use the World Adapter, instantiate it and then access the methods provided. Instantiating requires the account id (Team ID in the Epicenter user interface), project id (Project ID), and group (Group Name).

  var wa = new F.service.World({
     account: 'acme-simulations',
     project: 'supply-chain-game',
     group: 'team1' });
  wa.create()
     .then(function(world) {
         // call methods, e.g. wa.addUsers()
     });

Configuration Options

token

For projects that require authentication, pass in the user access token (defaults to empty string). 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).

project

  • String

The project id. If left undefined, taken from the URL.

account

  • String

The account id. In the Epicenter UI, this is the Team ID (for team projects). If left undefined, taken from the URL.

group

  • String

The group name. Defaults to undefined.

model

  • String

The model file to use to create runs in this world. Defaults to undefined.

filter

  • String

Criteria by which to filter world. Currently only supports world-ids as filters.

id

  • String

Convenience alias for filter

transport

  • Object

Options to pass on to the underlying transport layer. All jquery.ajax options at http://api.jquery.com/jQuery.ajax/ are available. Defaults to empty object.

success

  • function

Called when the call completes successfully. Defaults to $.noop.

error

  • function

Called when the call fails. Defaults to $.noop.

Methods

create

Creates a new World.

Using this method is rare. It is more common to create worlds automatically while you autoAssign() end users to worlds. (In this case, configuration data for the world, such as the roles, are read from the project-level world configuration information, for example by getProjectSettings().)

Example

 var wa = new F.service.World({
      account: 'acme-simulations',
      project: 'supply-chain-game',
      group: 'team1' });
 wa.create({
      roles: ['VP Marketing', 'VP Sales', 'VP Engineering']
  });

Parameters

  • params: object Parameters to create the world.

  • params.group: string (Optional) The Group Name to create this world under. Only end users in this group are eligible to join the world. Optional here; required when instantiating the service (new F.service.World()).

  • params.roles: object (Optional) The list of roles (strings) for this world. Some worlds have specific roles that must be filled by end users. Listing the roles allows you to autoassign users to worlds and ensure that all roles are filled in each world.

  • params.optionalRoles: object (Optional) The list of optional roles (strings) for this world. Some worlds have specific roles that may be filled by end users. Listing the optional roles as part of the world object allows you to autoassign users to worlds and ensure that all roles are filled in each world.

  • params.minUsers: integer (Optional) The minimum number of users for the world. Including this number allows you to autoassign end users to worlds and ensure that the correct number of users are in each world.

  • options: object (Optional) Options object to override global options.

update

Updates a World, for example to replace the roles in the world.

Typically, you complete world configuration at the project level, rather than at the world level. For example, each world in your project probably has the same roles for end users. And your project is probably either configured so that all end users share the same world (and run), or smaller sets of end users share worlds — but not both. However, this method is available if you need to update the configuration of a particular world.

Example

 var wa = new F.service.World({
      account: 'acme-simulations',
      project: 'supply-chain-game',
      group: 'team1' });
 wa.create()
      .then(function(world) {
          wa.update({ roles: ['VP Marketing', 'VP Sales', 'VP Engineering'] });
      });

Parameters

  • params: object Parameters to update the world.

  • params.name: string A string identifier for the linked end users, for example, "name": "Our Team".

  • params.roles: object (Optional) The list of roles (strings) for this world. Some worlds have specific roles that must be filled by end users. Listing the roles allows you to autoassign users to worlds and ensure that all roles are filled in each world.

  • params.optionalRoles: object (Optional) The list of optional roles (strings) for this world. Some worlds have specific roles that may be filled by end users. Listing the optional roles as part of the world object allows you to autoassign users to worlds and ensure that all roles are filled in each world.

  • params.minUsers: integer (Optional) The minimum number of users for the world. Including this number allows you to autoassign end users to worlds and ensure that the correct number of users are in each world.

  • options: object (Optional) Options object to override global options.

delete

Deletes an existing world.

This function optionally takes one argument. If the argument is a string, it is the id of the world to delete. If the argument is an object, it is the override for global options.

Example

 var wa = new F.service.World({
      account: 'acme-simulations',
      project: 'supply-chain-game',
      group: 'team1' });
 wa.create()
      .then(function(world) {
          wa.delete();
      });

Parameters

  • options: String|Object (Optional) The id of the world to delete, or options object to override global options.

updateConfig

Updates the configuration for the current instance of the World API Adapter (including all subsequent function calls, until the configuration is updated again).

Example

 var wa = new F.service.World({...}).updateConfig({ filter: '123' }).addUser({ userId: '123' });

Parameters

  • config: object The configuration object to use in updating existing configuration.

list

Lists all worlds for a given account, project, and group. All three are required, and if not specified as parameters, are read from the service.

Example

 var wa = new F.service.World({
      account: 'acme-simulations',
      project: 'supply-chain-game',
      group: 'team1' });
 wa.create()
      .then(function(world) {
          // lists all worlds in group "team1"
          wa.list();

          // lists all worlds in group "other-group-name"
          wa.list({ group: 'other-group-name' });
      });

Parameters

  • options: object (Optional) Options object to override global options.

getWorldsForUser

Gets all worlds that an end user belongs to for a given account (team), project, and group.

Example

 var wa = new F.service.World({
      account: 'acme-simulations',
      project: 'supply-chain-game',
      group: 'team1' });
 wa.create()
      .then(function(world) {
          wa.getWorldsForUser('b1c19dda-2d2e-4777-ad5d-3929f17e86d3')
      });

Parameters

  • userId: string The userId of the user whose worlds are being retrieved.

  • options: object (Optional) Options object to override global options.

load

Load information for a specific world. All further calls to the world service will use the id provided.

Parameters

  • worldId: String The id of the world to load.

  • options: Object (Optional) Options object to override global options.

addUsers

Adds an end user or list of end users to a given world. The end user must be a member of the group that is associated with this world.

Example

 var wa = new F.service.World({
      account: 'acme-simulations',
      project: 'supply-chain-game',
      group: 'team1' });
 wa.create()
      .then(function(world) {
          // add one user
          wa.addUsers('b1c19dda-2d2e-4777-ad5d-3929f17e86d3');
          wa.addUsers(['b1c19dda-2d2e-4777-ad5d-3929f17e86d3']);
          wa.addUsers({ userId: 'b1c19dda-2d2e-4777-ad5d-3929f17e86d3', role: 'VP Sales' });

          // add several users
          wa.addUsers([
              { userId: 'a6fe0c1e-f4b8-4f01-9f5f-01ccf4c2ed44',
                role: 'VP Marketing' },
              { userId: '8f2604cf-96cd-449f-82fa-e331530734ee',
                role: 'VP Engineering' }
          ]);

          // add one user to a specific world
          wa.addUsers('b1c19dda-2d2e-4777-ad5d-3929f17e86d3', world.id);
          wa.addUsers('b1c19dda-2d2e-4777-ad5d-3929f17e86d3', { filter: world.id });
      });

Parameters

  • users: string|object|array User id, array of user ids, object, or array of objects of the users to add to this world.

  • users.role: string The role the user should have in the world. It is up to the caller to ensure, if needed, that the role passed in is one of the roles or optionalRoles of this world.

  • worldId: string The world to which the users should be added. If not specified, the filter parameter of the options object is used.

  • options: object (Optional) Options object to override global options.

updateUser

Updates the role of an end user in a given world. (You can only update one end user at a time.)

Example

 var wa = new F.service.World({
      account: 'acme-simulations',
      project: 'supply-chain-game',
      group: 'team1' });

 wa.create().then(function(world) {
      wa.addUsers('b1c19dda-2d2e-4777-ad5d-3929f17e86d3');
      wa.updateUser({ userId: 'b1c19dda-2d2e-4777-ad5d-3929f17e86d3', role: 'leader' });
 });

Parameters

  • user: object User object with userId and the new role.

  • options: object (Optional) Options object to override global options.

removeUser

Removes an end user from a given world.

Example

 var wa = new F.service.World({
      account: 'acme-simulations',
      project: 'supply-chain-game',
      group: 'team1' });
 wa.create()
      .then(function(world) {
          wa.addUsers(['a6fe0c1e-f4b8-4f01-9f5f-01ccf4c2ed44', '8f2604cf-96cd-449f-82fa-e331530734ee']);
          wa.removeUser('a6fe0c1e-f4b8-4f01-9f5f-01ccf4c2ed44');
          wa.removeUser({ userId: '8f2604cf-96cd-449f-82fa-e331530734ee' });
      });

Parameters

  • user: object|string The userId of the user to remove from the world, or an object containing the userId field.

  • options: object (Optional) Options object to override global options.

getCurrentRunId

Gets the run id of current run for the given world. If the world does not have a run, creates a new one and returns the run id.

Remember that a run is a collection of interactions with a project and its model. In the case of multiplayer projects, the run is shared by all end users in the world.

Example

 var wa = new F.service.World({
      account: 'acme-simulations',
      project: 'supply-chain-game',
      group: 'team1' });
 wa.create()
      .then(function(world) {
          wa.getCurrentRunId({ model: 'model.py' });
      });

Parameters

  • options: object (Optional) Options object to override global options.

  • options.model: object The model file to use to create a run if needed.

getCurrentWorldForUser

Gets the current (most recent) world for the given end user in the given group. Brings this most recent world into memory if needed.

Example

 var wa = new F.service.World({
      account: 'acme-simulations',
      project: 'supply-chain-game',
      group: 'team1' });
 wa.getCurrentWorldForUser('8f2604cf-96cd-449f-82fa-e331530734ee')
      .then(function(world) {
          // use data from world
      });

Parameters

  • userId: string The userId of the user whose current (most recent) world is being retrieved.

  • groupName: string (Optional) The name of the group. If not provided, defaults to the group used to create the service.

deleteRun

Deletes the current run from the world.

(Note that the world id remains part of the run record, indicating that the run was formerly an active run for the world.)

Example

 var wa = new F.service.World({
      account: 'acme-simulations',
      project: 'supply-chain-game',
      group: 'team1' });

 wa.deleteRun('sample-world-id');

Parameters

  • worldId: string The worldId of the world from which the current run is being deleted.

  • options: object (Optional) Options object to override global options.

newRunForWorld

Creates a new run for the world.

Example

 var wa = new F.service.World({
      account: 'acme-simulations',
      project: 'supply-chain-game',
      group: 'team1' });

 wa.getCurrentWorldForUser('8f2604cf-96cd-449f-82fa-e331530734ee')
      .then(function (world) {
              wa.newRunForWorld(world.id);
      });

Parameters

  • worldId: string worldId in which we create the new run.

  • options: object (Optional) Options object to override global options.

  • options.model: object The model file to use to create a run if needed.

autoAssign

Assigns end users to worlds, creating new worlds as appropriate, automatically. Assigns all end users in the group, and creates new worlds as needed based on the project-level world configuration (roles, optional roles, and minimum end users per world).

Example

 var wa = new F.service.World({
      account: 'acme-simulations',
      project: 'supply-chain-game',
      group: 'team1' });

 wa.autoAssign();

Parameters

  • options: object (Optional) Options object to override global options.

getProjectSettings

Gets the project's world configuration.

Typically, every interaction with your project uses the same configuration of each world. For example, each world in your project probably has the same roles for end users. And your project is probably either configured so that all end users share the same world (and run), or smaller sets of end users share worlds — but not both.

(The Multiplayer Project REST API allows you to set these project-level world configurations. The World Adapter simply retrieves them, for example so they can be used in auto-assignment of end users to worlds.)

Example

 var wa = new F.service.World({
      account: 'acme-simulations',
      project: 'supply-chain-game',
      group: 'team1' });

 wa.getProjectSettings()
      .then(function(settings) {
          console.log(settings.roles);
          console.log(settings.optionalRoles);
      });

Parameters

  • options: object (Optional) Options object to override global options.