forio Toggle navigation

Multiplayer Project API

A world is a set of end users and their shared runs.

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 API allows you to specify, at a project level, how multiplayer worlds for each project are configured.

Because multiplayer worlds links end users, the Multiplayer Project API is only used with Authenticated projects, that is, projects with end users and groups.

The Multiplayer Project API supports the following methods:

Setting a Project-Level World Configuration

Method: PUT

URI: /v2/multiplayer/project/{account id}/{project id}

Headers: Content-Type: application/json, Authorization: Bearer{project access token}

Body: JSON object containing the worlds, roles, and optionalRoles

Return Status:

  • 201: Successful creation of world configuration

Return Body: The world configuration (JSON object) for this project

Example:

curl -X PUT \
    'https://api.forio.com/v2/multiplayer/project/acme-simulations/supply-chain-game' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
    --data '{"worlds": "single", "roles": ["VP Marketing", "VP Sales", "VP Engineering"], "optionalRoles": ["VP HR"]}'

Example Response:

{
    "created": "2015-04-06T17:15:46.000Z",
    "lastModified": "2015-04-06T17:15:46.000Z",
    "worlds": "single",
    "roles": [
        "VP Marketing",
        "VP Sales",
        "VP Engineering"
    ],
    "optionalRoles": [
        "VP HR"
    ]
}

Notes:

  • In the URI, the account field is the Team ID.
  • In the header, the access token should be the project access token for the project.
  • In the body, the worlds field can have one of two values:
    • single: All end users of the project share one world (and one run).
    • dynamic: There are multiple worlds, each shared by a few users.
  • In the body, the roles field is an array of strings. Some worlds have specific roles that must be filled by end users. Listing the roles as part of the world object allows you to autoassign users to worlds and ensure that all roles are filled in each world. (This is true for all roles listed in the roles array, regardless of whether the particular role is also listed in the optionalRoles array.)
  • In the body, the optionalRoles field is an optional array of strings. 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.
  • This project-level configuration is the default for all worlds created in this project. However, each world can override these values; see the Multiplayer World API.

Updating a Project-Level World Configuration

Method: PATCH

URI: /v2/multiplayer/project/{account id}/{project id}

Headers: Content-Type: application/json, Authorization: Bearer{project access token}

Body: JSON object containing the fields to update: one or more of worlds, roles, and optionalRoles

Return Status:

  • 200: Successful creation of world configuration

Return Body: The world configuration (JSON object) for this project

Example:

curl -X PATCH \
    'https://api.forio.com/v2/multiplayer/project/acme-simulations/supply-chain-game' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
    --data '{"worlds": "dynamic"}'

Example Response:

{
    "created": "2015-04-06T17:15:46.000Z",
    "lastModified": "2015-04-06T17:15:46.000Z",
    "worlds": "dynamic",
    "roles": [
        "VP Marketing",
        "VP Sales",
        "VP Engineering"
    ],
    "optionalRoles": [
        "VP HR"
    ]
}

Notes:

  • In the URI, the account field is the Team ID.
  • In the header, the access token should be the project access token for the project.
  • In the body, the worlds field can have one of two values:
    • single: All end users of the project share one world (and one run).
    • dynamic: There are multiple worlds, each shared by a few users.
  • In the body, the roles field is an array of strings. Some worlds have specific roles that must be filled by end users. Listing the roles as part of the world object allows you to autoassign users to worlds and ensure that all roles are filled in each world.
  • In the body, the optionalRoles field is an optional array of strings. 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.
  • This project-level configuration is the default for all worlds created in this project. However, each world can override these values; see the Multiplayer World API.

Reading a Project-level World Configuration

Method: GET

URI: /v2/multiplayer/project/{account id}/{project id}

Headers: Authorization: Bearer{access token}

Return Status:

  • 200: Successfully retrieved world configuration
  • 404: No world configuration found for this project

Return Body: The world configuration (JSON object) for this project

Example:

curl -G \
    'https://api.forio.com/v2/multiplayer/project/acme-simulations/supply-chain-game' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \

Example Response:

{
    "created": "2015-04-06T17:15:46.000Z",
    "lastModified": "2015-04-06T17:15:46.000Z",
    "worlds": "dynamic",
    "roles": [
        "VP Marketing",
        "VP Sales",
        "VP Engineering"
    ],
    "optionalRoles": [
        "VP HR"
    ]
}

Notes:

  • In the URI, the account field is the Team ID.
  • In the header, the access token can be the user access token of a team member developing this project, or the project access token for the project.
  • This project-level configuration is the default for all worlds created in this project. However, each world can override these values; see the Multiplayer World API.

Removing a Project-Level World Configuration

Method: DELETE

URI: /v2/multiplayer/project/{account id}/{project id}

Headers: Authorization: Bearer{project access token}

Return Status:

  • 204 Successful deletion of world configuration from project

Example:

curl -X DELETE \
    'https://api.forio.com/v2/multiplayer/project/acme-simulations/supply-chain-game' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \

Example Response:

There is no response body for a DELETE request.

Notes:

  • In the URI, the account field is the Team ID.
  • In the header, the access token should be the project access token for the project.
  • This project-level configuration is the default for all worlds created in this project. Removing it means that values are taken from the individual world records; see the Multiplayer World API.
  • Deleting the world configuration sets the Project Settings to have multiplayer disabled.