World Functions

To manage worlds, use the functions exported by the World adapter.

Importing the adapter

To use the functions of the World adapter, import it as shown:
import { worldAdapter } from 'epicenter-libs';

The worldAdapter namespace exports functions that make calls to the World API.

learn more

For descriptions of the objects used by the World adapter functions, read World Entities.

Worlds

Create a world

To create a world , use the create() function. You have the options of specifying a group and/or an episode.

The name of the new world must be unique within the world's scope. You don't have to provide a name. If the name is omitted, Epicenter generates one using a world name generator. There are two types of world name generators:

Sequential (default): Generates names of format "World###", where ### is a numeral starting with 001.
Color + animal: Randomly combines a color and an animal.

You can specify the type of world name generator you want to use in the worldNameGenerator parameter.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

The create() function:

Constructs a POST request to the endpoint /world/{GROUP_NAME} or /world/{GROUP_NAME}/{EPISODE_NAME} if an episode name is provided.
Sends optional parameters as the request body to configure the world.
Returns a WorldReadOutView object object.

Function signature
export async function create<R extends WorldRole = WorldRole>(
    optionals: {
        name?: string;
        displayName?: string;
        groupName?: string;
        episodeName?: string;
        worldNameGenerator?: WorldNameGenerator;
        allowChannel?: boolean;
    } & RoutingOptions = {},
): Promise<WorldReadOutView<R>>

Parameters

warning

A world's name and displayName cannot be an empty string and cannot contain any of these characters:

`$%^*={}[]|;\"<>?\r\n

optionals: Optional parameters and a RoutingOptions object.
- name (string): (Optional) A name for the world. Must be unique within the world's scope.
- displayName (string): (Optional) An informative display name for the world. Doe not need to be unique.
- groupName (string): (Optional) The name of the group where the world is created. If not provided, defaults to the groupName stored in the session.
- episodeName (string): (Optional) The name of the episode in which the world is created.
- worldNameGenerator (WorldNameGenerator object): (Optional) Specifies the method for generating the world name.
- allowChannel (boolean): (Optional) If true, send out push notifications for this world. Applicable to projects with phylogeny >= SILENT.

Return value

A promise that resolves to a WorldReadOutView object object.

import { worldAdapter } from 'epicenter-libs';  

await worldAdapter.create({ name: 'Whole New World' });

List worlds for group or episode

To retrieve worlds associated with a group or episode, use the get() function.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

The get() function:

Constructs a GET request to /world/{GROUP_NAME} or /world/{GROUP_NAME}/{EPISODE_NAME} if an episode name is provided.
If mine is set to true, only worlds owned by the current user are returned.
Defaults to the user's session group if groupName is not provided.
Returns an array of WorldReadOutView objects.

Function signature
export async function get<R extends WorldRole = WorldRole>(
    optionals: {
        groupName?: string;
        episodeName?: string;
        mine?: boolean;
    } & RoutingOptions = {},
): Promise<WorldReadOutView<R>[]>

Parameters

optionals: Optional parameters and a RoutingOptions object.
- groupName (string): The name of the group. If not provided, defaults to the groupName stored in the session.
- episodeName (string): The episode name for worlds scoped to an episode.
- mine (boolean): If true, get only the worlds the requesting user is in (based on session token). Default is false.

Return value

A promise that resolves to an array of WorldReadOutView objects.

Usage example

import { worldAdapter } from 'epicenter-libs';

// Retrieve the world for the groupName stored in the session
worldAdapter.get();

// Retrieve the world for a specific group and episode
worldAdapter.get({ groupName: 'group_1', episodeName: 'episode_1' });

// Retrieve only worlds the current user is in
worldAdapter.get({ mine: true });

List worlds for the current user

Permissions

Requires a role of PARTICIPANT or higher.

Function description

The getSessionWorlds() function:

Constructs a GET request to the endpoint /world/assignment.
Retrieves the worlds associated with the current session.
Returns a list of WorldReadOutView objects assigned to the current user.

Function signature
export async function getSessionWorlds<R extends WorldRole = WorldRole>(
    optionals: RoutingOptions = {},
): Promise<WorldReadOutView<R>[]>

Parameters

optionals (Type: RoutingOptions = {}): Additional routing options.

Return value

A promise that resolves to an array of WorldReadOutView objects.

Usage example

import { worldAdapter } from 'epicenter-libs';  

const worlds = await worldAdapter.getSessionWorlds();

Update a world

To update an existing world, use the update() function.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

The update() function:

Constructs a PATCH request to /world/{WORLD_KEY}.
Sends updated world attributes in the request body.
Returns a WorldReadOutView object with the updated fields.

Function signature
export async function update<R extends WorldRole = WorldRole>(
    worldKey: string,
    update: {
        displayName?: string;
        runKey?: string;
        allowChannel?: boolean;
    },
    optionals: RoutingOptions = {},
): Promise<WorldReadOutView<R>>

Parameters

warning

A world's displayName cannot contain any of these characters:

`$%^*={}[]|;\"<>?\r\n

worldKey (string): The key identifying the world.
update (Type: { displayName?: string, runKey?: string, allowChannel?: boolean }): The world's attributes you are updating.
- displayName (string): The new display name for the world. Does not need to be unique.
- runKey (string): The new model run key to associate the world with.
- allowChannel (boolean): If true, send out push notifications for this world. Applicable to projects with phylogeny >= SILENT.
optionals (Type: RoutingOptions = {}): Additional routing options.

Return value

A promise that resolves to an updated WorldReadOutView object.

Usage example

import { worldAdapter } from 'epicenter-libs';  

worldAdapter.update('0000017a445032dc38cb2cecd5fc56706934',
                    { runKey: '0000018d61f1217b22ce0ae605ff00649d6i', displayName: 'World A1' });  

Assign a run to a world

To assign an existing run to a world, call the assignRun() function.

tip

Use this function when you need to assign the world to a different run.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

The assignRun() function:

Constructs a PATCH request to /world/run/{WORLD_KEY}.
Sends the runKey in the request body to associate the run with the world.
Returns a WorldReadOutView object representing the updated world.

Function signature
export async function assignRun<R extends WorldRole = WorldRole>(
    worldKey: string,
    runKey: string,
    optionals: RoutingOptions = {},
): Promise<WorldReadOutView<R>>

Parameters

worldKey (string): The unique key identifying the world.
runKey (string): The key of the run to be assigned to the world.
optionals (Type: RoutingOptions = {}): Additional routing options. Pass network call options overrides here.

Return value

A promise that resolves to an updated WorldReadOutView object.

Usage example

import { worldAdapter } from 'epicenter-libs';  

await worldAdapter.assignRun('0000017a445032dc38cb2cecd5fc56679324',
                        '0000018d61f1217b22ce0ae605ff00669d8o');

Delete a world

To delete a world, use the destroy() function.

Permissions

Requires a role of FACILITATOR or higher.

Function description

The destroy() function:

Constructs a DELETE request to the endpoint /world/{WORLD_KEY}.
Executes the request and returns a void promise upon success.

Function signature
export async function destroy(
    worldKey: string,
    optionals: RoutingOptions = {}
): Promise<void>

Parameters

worldKey (string): The unique key identifying the world to be deleted.
optionals (Type: RoutingOptions = {}): Additional routing options.

Return value

A promise that resolves to void when the world is successfully deleted.

Usage example

import { worldAdapter } from 'epicenter-libs';  

worldAdapter.destroy('0000017a445032dc38cb2cecd5fc13563218');  

User assignments

List assignments

Retrieves a list of user assignments with some information on the world included for a group or episode (if specified).

Permissions

Requires a role of PARTICIPANT or higher.

Function description

The getAssignments() function:

Constructs a GET request to /world/assignment/for/{GROUP_NAME} or /world/assignment/for/{GROUP_NAME}/{EPISODE_NAME} if an episode name is provided.
Optionally filters results to only the worlds the requesting user is assigned to.
Returns a list of WorldReadOutView objects representing the assignments.

Function signature
export async function getAssignments<R extends WorldRole = WorldRole>(
    optionals: {
        groupName?: string;
        episodeName?: string;
        mine?: boolean;
    } & RoutingOptions = {},
): Promise<WorldReadOutView<R>[]>

Parameters

optionals: Filters and a RoutingOptions object.
- groupName (string): The name of the group for which assignments should be retrieved. Defaults to the session's group name.
- episodeName (string): The episode name for worlds scoped to an episode.
- mine (boolean): If true, retrieves only the worlds the current user is assigned to.

Return value

A promise that resolves to an array of WorldReadOutView objects.

Usage example

import { worldAdapter } from 'epicenter-libs';  

worldAdapter.getAssignments({ mine: true }); // Get only the worlds the current user is assigned to.

Assign the current user

Automatically assigns the current session's user to a world.

Permissions

Requires a role of FACILITATOR or higher.

Function description

The selfAssign() function:

Constructs a POST request to /world/selfassign/{GROUP_NAME} or /world/selfassign/{GROUP_NAME}/{EPISODE_NAME} if an episode name is provided.
Sends optional parameters — such as role, objective, populace, and world‑name generation strategy—in the request body.
Returns a WorldReadOutView object representing the world the user was assigned to.

Function signature
export async function selfAssign<R extends WorldRole = WorldRole>(
    optionals: {
        role?: R;
        groupName?: string;
        episodeName?: string;
        objective?: keyof typeof OBJECTIVE;
        worldNameGenerator?: WorldNameGenerator;
        populace?: PersonaCreateInView<R>[];
        allowChannel?: boolean;
    } & RoutingOptions = {},
): Promise<WorldReadOutView<R>>

Parameters

optionals: Optional parameters and a RoutingOptions object.
- role (R): The world role to be assigned to the user.
- groupName (string): The name of the group. Defaults to the session's group name.
- episodeName (string): The episode name for worlds scoped to an episode.
- objective (keyof typeof OBJECTIVE): The assignment objective type. Defaults to OBJECTIVE.MINIMUM.
- worldNameGenerator (WorldNameGenerator object): Defines the naming convention for the world.
- populace (PersonaCreateInView<R>[]): List of personas to dictate the self assignment.
- allowChannel (boolean): If true, enables push notifications for the world. Applicable to projects with phylogeny >= SILENT.

Return value

A promise that resolves to an assigned WorldReadOutView object.

Usage example

import { worldAdapter } from 'epicenter-libs';
// Assigns user to a group-scoped world
epicenter.worldAdapter.selfAssign();
// Assigns user to a group-scoped world with role "cartographer"
epicenter.worldAdapter.selfAssign({ role: 'cartographer' });
// Assigns user to an episode-scoped world with role "cartographer"
epicenter.worldAdapter.selfAssign({ role: 'cartographer', episodeName: 'my-episode-name' });

Auto-assign users to worlds

To assign a list of users to world personas, call the autoAssignUsers() function.

This function completes the persona assignments for all existing worlds and creates new worlds for remaining unassigned users. The assignment is done according to the specified assignment objective.

tip

You can make this an all-or-nothing operation by setting the requireAllAssignments to true. In this case all the users in the list must be assigned or none.

Permissions

Requires a role of FACILITATOR or higher.

Function description

The autoAssignUsers() function:

Constructs a POST request to /world/assignment/{GROUP_NAME} or /world/assignment/{GROUP_NAME}/{EPISODE_NAME} if an episode name is provided.
Sends assignment data—including user assignments, objectives, populace constraints, and world‑name generation strategy—in the request body.
Returns a list of WorldReadOutView objects representing the worlds created or updated by the assignment.

Function signature
export async function autoAssignUsers<R extends WorldRole = WorldRole>(
    assignments: AssignmentCreateInView<R>[],
    optionals: {
        groupName?: string;
        episodeName?: string;
        objective?: keyof typeof OBJECTIVE;
        worldNameGenerator?: WorldNameGenerator;
        requireAllAssignments?: boolean;
        keepEmptyWorlds?: boolean;
        populace?: PersonaCreateInView<R>[];
        allowChannel?: boolean;
    } & RoutingOptions = {},
): Promise<WorldReadOutView<R>[]>

Parameters

assignments (Type: AssignmentCreateInView<R>[]): An array of user assignment objects.
optionals: Optional parameters and a RoutingOptions object.
- groupName (string): The name of the group. Defaults to the session's group name.
- episodeName (string): The episode name for episode scoped worlds.
- objective (keyof typeof OBJECTIVE): Defaults to OBJECTIVE.MINIMUM.
- worldNameGenerator (WorldNameGenerator object): Defines the naming convention for the world.
- requireAllAssignments (boolean): If true, return an error when an assignment was not made (instead of silently leaving the user as unassigned).
- keepEmptyWorlds (boolean): If false, worlds that are now empty should be deleted.
- populace (PersonaCreateInView<R>[]): Array of persona objects to assign to worlds.
- allowChannel (boolean): If true, enables push notifications for the world. Applicable to projects with phylogeny >= SILENT.

Return value

A promise that resolves to an array of WorldReadOutView objects.

Usage example

import { worldAdapter } from 'epicenter-libs';
    const worlds = await worldAdapter.assignUsers([
                        { userKey: '000001796733eef0842f4d6d960997035d69', role: 'locksmith' },
                        { userKey: '000001796733eef0842f4d6d960997069s5w' },
    ]);

Edit assignments

Manually assign users to a world. You have the option of specifying a persona for each user.

tip

You can make this an all-or-nothing operation by setting the requireAllAssignments to true. In this case all the users in the list must be assigned or none.

Permissions

Requires a role of FACILITATOR or higher.

Function description

The editAssignments() function:

Constructs a PUT request to /world/assignment/{GROUP_NAME} or /world/assignment/{GROUP_NAME}/{EPISODE_NAME} if an episode name is provided.
Sends a map of world keys to updated assignment lists in the request body.
Returns a list of WorldReadOutView objects representing the updated worlds.

Function signature
export async function editAssignments<R extends WorldRole = WorldRole>(
    assignments: AssignmentMap<R>,
    optionals: {
        groupName?: string;
        episodeName?: string;
        objective?: keyof typeof OBJECTIVE;
        keepEmptyWorlds?: boolean;
        requireAllAssignments?: boolean;
    } & RoutingOptions = {},
): Promise<WorldReadOutView<R>[]>

Parameters

assignments (Type: AssignmentMap<R>): A mapping of world keys to user assignments.
optionals: Optional parameters and a RoutingOptions object.
- groupName (string): The name of the group for which assignments are updated. Defaults to the session's group name.
- episodeName (string): The episode name for worlds scoped to an episode.
- objective (keyof typeof OBJECTIVE): Defaults to OBJECTIVE.MINIMUM.
- keepEmptyWorlds (boolean): If true, worlds with no assigned users are still maintained.
- requireAllAssignments (boolean): If true, return an error when an assignment was not made (instead of silently leaving the user as unassigned).

Return value

A promise that resolves to an array of WorldReadOutView objects.

Usage example

import { worldAdapter } from 'epicenter-libs';  

const updatedWorlds = await worldAdapter.editAssignments({
    '0000017a445032dc38cb2cecd5fc13708314': [
        { userKey: '000001796733eef0842f4d6d960997018a43', role: 'locksmith' },
        { userKey: '000001796733eef0842f4d6d960997018d9h' },
    ],
    '0000017a445032dc38cb2cecd5fc13708315': [
        { userKey: '000001796733eef0842f4d6d960997018a4c', role: 'navigator' },
    ],
});

Get assignments for a world

To retrieve the current assignments for a world, call the getAssignmentsByKey() function.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

The getAssignmentsByKey() function:

Constructs a GET request to /world/assignment/{WORLD_KEY}.
Retrieves the assignment information associated with the specified world.
Returns a WorldReadOutView object containing the assignment data.

Function signature
export async function getAssignmentsByKey<R extends WorldRole = WorldRole>(
    worldKey: string,
    optionals: RoutingOptions = {},
): Promise<WorldReadOutView<R>>

Parameters

worldKey (string): The unique key identifying the world.
optionals (Type: RoutingOptions = {}): Additional routing options. Pass network call options overrides here.

Return value

A promise that resolves to a WorldReadOutView object.

Usage example

import { worldAdapter } from 'epicenter-libs';  
const assignments = await worldAdapter.getAssignmentsByKey(world.worldKey);

Remove users

To remove a user of a set of users from assignments, call removeUsers() function.

warning

Any worlds that do not contain users within them will be automatically deleted in the process unless you unless you set the keepEmptyWorlds parameter to true.

Permissions

Requires a role of FACILITATOR or higher.

Function description

The removeUsers() function:

Constructs a DELETE request to /world/assignment/{GROUP_NAME} or /world/assignment/{GROUP_NAME}/{EPISODE_NAME} if an episode name is provided.
Removes users from world assignments based on specified parameters.
Deletes any worlds that become empty unless keepEmptyWorlds is set to true.
Returns a void promise upon success.

Function signature
export async function removeUsers(
    userKeys: string[],
    optionals: {
        groupName?: string,
        episodeName?: string,
        keepEmptyWorlds?: boolean,
    } & RoutingOptions = {}
): Promise<void>

Parameters

userKeys (Type: string[]): An array of user keys to be removed from their world persona assignments.
optionals: Optional parameters and a RoutingOptions object.
- groupName (string): The name of the group. Defaults to the session's group name.
- episodeName (string): The episode name for worlds scoped to an episode.
- keepEmptyWorlds (boolean): If false, worlds that have no assigned users as a result of the function call are deleted.

Return value

A promise that resolves to void when the users are successfully removed.

Usage example

import { worldAdapter } from 'epicenter-libs';
const usersToRemove = ['000001796733eef0842f4d6d960997639ww5r'];
await worldAdapter.removeUsers(usersToRemove);

Personas

List personas

To get a list of the personas for a given scope (project, group, episode, or world), call the getPersonas() function.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

The getPersonas() function:

Constructs a GET request to /world/persona/{SCOPE_BOUNDARY}/{SCOPE_KEY}.
Determines the correct URI components based on the provided scope boundary and scope key.
Returns an array of PersonaReadOutView objects for the specified scope.

Function signature
export async function getPersonas<R extends WorldRole = WorldRole>(
    scope: GenericScope,
    optionals: RoutingOptions = {},
): Promise<PersonaReadOutView<R>[]>

Parameters

scope (Type: GenericScope): The scope defining the level at which personas are retrieved.
- scopeBoundary (string): The boundary level for the scope. Defaults to PROJECT.
- scopeKey (string): The specific key within the scope.
optionals (Type: RoutingOptions = {}): Additional routing options.

Return value

A promise that resolves to an array of PersonaReadOutView objects when the personas are successfully retrieved.

Usage example

import { worldAdapter } from 'epicenter-libs';  
await worldAdapter.getPersonas({ scopeBoundary: SCOPE_BOUNDARY.GROUP, scopeKey: GROUP_KEY });

Set personas

To set the personas of a given entity (project, group, episode, or world), call the setPersonas() function.

Note

The setPersonas() function performs an overwrite of the set of personas for an entity. You must always pass the entire array.

Permissions

Requires a role of FACILITATOR or higher.

Function description

The setPersonas() function:

Constructs a PUT request to /world/persona/{SCOPE_BOUNDARY}/{SCOPE_KEY}.
Returns undefined when the personas are successfully updated.

Function signature
export async function setPersonas<R extends WorldRole = WorldRole>(
    personas: PersonaCreateInView<R>[],
    scope?: GenericScope,
    optionals: RoutingOptions = {},
): Promise<void>

Parameters

personas (Type: PersonaCreateInView<R>[]): A list of persona objects:
- role (string): See description of the PersonaCreateInView interface.
- minimum (number, optional): See description of the PersonaCreateInView interface.
- maximum (number, optional): See description of the PersonaCreateInView interface.
- marginal (number, optional): See description of the PersonaCreateInView interface.
scope? (Type: GenericScope, optional): The scope object defining the level at which personas are set. Defaults to the current project's scope if omitted.
optionals (Type: RoutingOptions = {}): Additional routing options.

Return value

A promise that resolves to void when the personas are successfully set.

Usage example

import { worldAdapter } from 'epicenter-libs';  

const personas = [{ role: 'leader', minimum: 1 },];

const scope = { scopeBoundary: SCOPE_BOUNDARY.GROUP, scopeKey: GROUP_KEY };

await worldAdapter.setPersonas(personas, scope);

Importing the adapter​

Worlds​

Create a world​

Permissions​

Function description​

Parameters​

Return value​

List worlds for group or episode​

Permissions​

Function description​

Parameters​

Return value​

Usage example​

List worlds for the current user​

Permissions​

Function description​

Parameters​

Return value​

Usage example​

Update a world​

Permissions​

Function description​

Parameters​

Return value​

Usage example​

Assign a run to a world​

Permissions​

Function description​

Parameters​

Return value​

Usage example​

Delete a world​

Permissions​

Function description​

Parameters​

Return value​

Usage example​

User assignments​

List assignments​

Permissions​

Function description​

Parameters​

Return value​

Usage example​

Assign the current user​

Permissions​

Function description​

Parameters​

Return value​

Usage example​

Auto-assign users to worlds​

Permissions​

Function description​

Parameters​

Return value​

Usage example​

Edit assignments​

Permissions​

Function description​

Parameters​

Return value​

Usage example​

Get assignments for a world​

Permissions​

Function description​

Parameters​

Return value​

Usage example​

Remove users​

Permissions​

Function description​

Parameters​

Return value​

Usage example​

Personas​

List personas​

Permissions​

Function description​

Parameters​

Return value​

Importing the adapter

Worlds

Create a world

Permissions

Function description

Parameters

Return value

List worlds for group or episode

Permissions

Function description

Parameters

Return value

Usage example

List worlds for the current user

Permissions

Function description

Parameters

Return value

Usage example

Update a world

Permissions

Function description

Parameters

Return value

Usage example

Assign a run to a world

Permissions

Function description

Parameters

Return value

Usage example

Delete a world

Permissions

Function description

Parameters

Return value

Usage example

User assignments

List assignments

Permissions

Function description

Parameters

Return value

Usage example

Assign the current user

Permissions

Function description

Parameters

Return value

Usage example

Auto-assign users to worlds

Permissions

Function description

Parameters

Return value

Usage example

Edit assignments

Permissions

Function description

Parameters

Return value

Usage example

Get assignments for a world

Permissions

Function description

Parameters

Return value

Usage example

Remove users

Permissions

Function description

Parameters

Return value

Usage example

Personas

List personas

Permissions

Function description

Parameters

Return value