sitemap.xml llms.txt
Skip to main content

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​

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​

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​

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);