Class World

Create an instance of World class with a given url slug and optional attributes and session credentials.

Example

import { World } from "utils/topiaInit.ts";

const world = await World.create(exampleUrlSlug, {
  attributes: { name: "Example World" },
  credentials: { interactivePublicKey: "examplePublicKey", interactiveNonce: "exampleNonce", assetId: "exampleDroppedAssetId", visitorId: 1, urlSlug: "exampleUrlSlug" }
});

Hierarchy (View Summary)

SDKController
- World

Implements

WorldInterface

Analytics

fetchWorldAnalytics

fetchWorldAnalytics(
    __namedParameters: {
        dateValue: number;
        periodType: "week" | "month" | "quarter" | "year";
        year: number;
    },
): Promise<void | ResponseType>
Retrieve world analytics by day, week, month, quarter, or year
Parameters
- __namedParameters: {
      dateValue: number;
      periodType: "week" | "month" | "quarter" | "year";
      year: number;
  }
Returns Promise<void | ResponseType>
Keywords
get, fetch, retrieve, analytics, stats, statistics, data, metrics
Example
```
const analytics = await world.fetchWorldAnalytics({
  periodType: "week",
  dateValue: 40,
  year: 2023,
});
```
Implementation of WorldInterface.fetchWorldAnalytics
- Defined in controllers/World.ts:955

Data Objects

fetchDataObject

fetchDataObject(
    appPublicKey?: string,
    appJWT?: string,
    sharedAppPublicKey?: string,
    sharedAppJWT?: string,
): Promise<void | ResponseType>
Retrieves the data object for a world. Must have valid interactive credentials from a visitor in the world.
Parameters
- OptionalappPublicKey: string
- OptionalappJWT: string
- OptionalsharedAppPublicKey: string
- OptionalsharedAppJWT: string
Returns Promise<void | ResponseType>
Keywords
get, fetch, retrieve, load, data, object, state
Example
```
await world.fetchDataObject();
const { dataObject } = world;
```
Implementation of WorldInterface.fetchDataObject
- Defined in controllers/World.ts:761

incrementDataObjectValue

incrementDataObjectValue(
    path: string,
    amount: number,
    options?: {
        analytics?: AnalyticType[];
        appJWT?: string;
        appPublicKey?: string;
        lock?: { lockId: string; releaseLock?: boolean };
        sharedAppJWT?: string;
        sharedAppPublicKey?: string;
    },
): Promise<void | ResponseType>
Increments a specific value in the data object for a world by the amount specified. Must have valid interactive credentials from a visitor in the world.
Parameters
- path: string
- amount: number
- options: {
      analytics?: AnalyticType[];
      appJWT?: string;
      appPublicKey?: string;
      lock?: { lockId: string; releaseLock?: boolean };
      sharedAppJWT?: string;
      sharedAppPublicKey?: string;
  } = {}
Returns Promise<void | ResponseType>
Remarks
Optionally, a lock can be provided with this request to ensure only one update happens at a time between all updates that share the same lock id

Keywords
increment, increase, add, count, data, object, state
Example
```
await world.incrementDataObjectValue([`keyAssets.${keyAssetId}.totalItemsCollected.count`], 1);
```
Implementation of WorldInterface.incrementDataObjectValue
- Defined in controllers/World.ts:885

setDataObject

setDataObject(
    dataObject: undefined | null | object,
    options?: {
        analytics?: AnalyticType[];
        appJWT?: string;
        appPublicKey?: string;
        lock?: { lockId: string; releaseLock?: boolean };
        sharedAppJWT?: string;
        sharedAppPublicKey?: string;
    },
): Promise<void | ResponseType>
Sets the data object for a user. Must have valid interactive credentials from a visitor in the world.
Parameters
- dataObject: undefined | null | object
- options: {
      analytics?: AnalyticType[];
      appJWT?: string;
      appPublicKey?: string;
      lock?: { lockId: string; releaseLock?: boolean };
      sharedAppJWT?: string;
      sharedAppPublicKey?: string;
  } = {}
Returns Promise<void | ResponseType>
Remarks
Optionally, a lock can be provided with this request to ensure only one update happens at a time between all updates that share the same lock id

Keywords
set, assign, store, save, data, object, state
Example
```
 await world.setDataObject(
   {
     ...defaultGameData,
     keyAssetId: droppedAsset.id,
   },
   { lock: { lock: { lockId: `${keyAssetId}-${new Date(Math.round(new Date().getTime() / 10000) * 10000)}` }, releaseLock: true } },
 );
const { profileMapper } = world.dataObject;
```
Implementation of WorldInterface.setDataObject
- Defined in controllers/World.ts:805

updateDataObject

updateDataObject(
    dataObject: object,
    options?: {
        analytics?: AnalyticType[];
        appJWT?: string;
        appPublicKey?: string;
        lock?: { lockId: string; releaseLock?: boolean };
        sharedAppJWT?: string;
        sharedAppPublicKey?: string;
    },
): Promise<void | ResponseType>
Updates the data object for a world. Must have valid interactive credentials from a visitor in the world.
Parameters
- dataObject: object
- options: {
      analytics?: AnalyticType[];
      appJWT?: string;
      appPublicKey?: string;
      lock?: { lockId: string; releaseLock?: boolean };
      sharedAppJWT?: string;
      sharedAppPublicKey?: string;
  } = {}
Returns Promise<void | ResponseType>
Remarks
Optionally, a lock can be provided with this request to ensure only one update happens at a time between all updates that share the same lock id

Keywords
update, modify, change, edit, alter, data, object, state
Example
```
await world.updateDataObject({
  [`keyAssets.${keyAssetId}.itemsCollectedByUser.${profileId}`]: { [dateKey]: { count: 1 }, total: 1 },
  [`profileMapper.${profileId}`]: username,
});
const { profileMapper } = world.dataObject;
```
Implementation of WorldInterface.updateDataObject
- Defined in controllers/World.ts:847

Dropped Assets

fetchDroppedAssets

fetchDroppedAssets(): Promise<void | ResponseType>
Retrieve all assets dropped in a world.

Returns Promise<void | ResponseType>
Keywords
get, fetch, retrieve, list, current, dropped assets
Example
```
await world.fetchDroppedAssets();
const assets = world.droppedAssets;
```
Implementation of WorldInterface.fetchDroppedAssets
- Defined in controllers/World.ts:248

fetchDroppedAssetsBySceneDropId

fetchDroppedAssetsBySceneDropId(
__namedParameters: { sceneDropId: string; uniqueName?: string },
): Promise<DroppedAsset[]>
Retrieve all assets dropped in a world matching sceneDropId.
Parameters
- __namedParameters: { sceneDropId: string; uniqueName?: string }
Returns Promise<DroppedAsset[]>
Returns an array of DroppedAsset instances.
Keywords
get, fetch, retrieve, list, current, dropped assets, sceneDropId
Example
```
const droppedAssets = await world.fetchDroppedAssetsBySceneDropId({
  sceneDropId: "sceneDropIdExample",
  uniqueName: "optionalUniqueNameExample",
});
```
Implementation of WorldInterface.fetchDroppedAssetsBySceneDropId
- Defined in controllers/World.ts:334

fetchDroppedAssetsWithUniqueName

fetchDroppedAssetsWithUniqueName(
    __namedParameters: {
        isPartial?: boolean;
        isReversed?: boolean;
        uniqueName: string;
    },
): Promise<DroppedAsset[]>
Retrieve all assets dropped in a world matching uniqueName.
Parameters
- __namedParameters: { isPartial?: boolean; isReversed?: boolean; uniqueName: string }
Returns Promise<DroppedAsset[]>
Returns an array of DroppedAsset instances.
Keywords
get, fetch, retrieve, list, current, dropped assets, uniqueName
Example
```
const droppedAssets = await world.fetchDroppedAssetsWithUniqueName({ uniqueName: "exampleUniqueName", isPartial: true });
```
Implementation of WorldInterface.fetchDroppedAssetsWithUniqueName
- Defined in controllers/World.ts:282

fetchLandmarkZones

fetchLandmarkZones(
landmarkZoneName?: string,
sceneDropId?: string,
): Promise<DroppedAsset[]>
Retrieve all landmark zone assets dropped in a world.
Parameters
- OptionallandmarkZoneName: string
- OptionalsceneDropId: string
Returns Promise<DroppedAsset[]>
Returns an array of DroppedAsset instances.
Keywords
get, fetch, retrieve, list, landmark, zones, dropped assets
Example
```
const zones = await world.fetchLandmarkZones("optionalLandmarkZoneName", "optionalSceneDropIdExample");
```
Implementation of WorldInterface.fetchLandmarkZones
- Defined in controllers/World.ts:427

updateCustomTextDroppedAssets

updateCustomTextDroppedAssets(
droppedAssetsToUpdate: DroppedAsset[],
style: object,
): Promise<object>
Update multiple custom text dropped assets with a single style while preserving text for specified dropped assets only.
Parameters
- droppedAssetsToUpdate: DroppedAsset[]
- style: object
Returns Promise<object>
Updates each DroppedAsset instance and world.droppedAssets map.
Keywords
update, modify, change, edit, dropped assets, custom text, style, text
Example
```
const droppedAssetsToUpdate = [world.droppedAssets["6"], world.droppedAssets["12"]];
const style = {
  "textColor": "#abc123",
  "textFontFamily": "Arial",
  "textSize": 40,
  "textWeight": "normal",
  "textWidth": 200
};
await world.updateCustomText(droppedAssetsToUpdate, style);
```
Implementation of WorldInterface.updateCustomTextDroppedAssets
- Defined in controllers/World.ts:404

Other

constructor

new World(
    topia: Topia,
    urlSlug: string,
    options?: WorldOptionalInterface,
): World
Parameters
- topia: Topia
- urlSlug: string
- options: WorldOptionalInterface = ...
Returns World
Overrides SDKController.constructor
- Defined in controllers/World.ts:99

credentials

credentials: undefined | InteractiveCredentials

`Optional`dataObject

dataObject?: null | object

`Optional`jwt

jwt?: string

requestOptions

requestOptions: object

`Optional`sceneDropIds

sceneDropIds?: null | [string]

`Optional`scenes

scenes?: null | [string]

topia

topia: Topia

urlSlug

urlSlug: string

`Optional`webhooks

webhooks?: null | WorldWebhooksInterface

droppedAssets

get droppedAssets(): { [key: string]: DroppedAsset }
Returns { [key: string]: DroppedAsset }
- Defined in controllers/World.ts:106

errorHandler

errorHandler(
    __namedParameters: {
        error?: unknown;
        message?: string;
        params?: object;
        sdkMethod?: string;
    },
): {
    data: {};
    message: string;
    method: string;
    params: object;
    sdkMethod: undefined
    | string;
    stack: string;
    stackTrace: Error;
    status: number;
    success: boolean;
    url: string;
}
Standardized error handler for all SDK operations.
Parameters
- __namedParameters: { error?: unknown; message?: string; params?: object; sdkMethod?: string }
Returns {
    data: {};
    message: string;
    method: string;
    params: object;
    sdkMethod: undefined | string;
    stack: string;
    stackTrace: Error;
    status: number;
    success: boolean;
    url: string;
}
Standardized error object with properties: data, message, method, params, sdkMethod, stack, status, success, url
Remarks
This method processes errors from API calls and formats them consistently across the SDK. It extracts relevant error information including:
- HTTP status codes and response data
- Error messages from API responses
- Stack traces for debugging
- Request details (URL, method, parameters)
All errors thrown by SDK methods flow through this handler to ensure consistent error format.
Keywords
error, exception, handler, debugging, api error, http error
Inherited from SDKController.errorHandler
- Defined in controllers/SDKController.ts:159

fetchDetails

fetchDetails(): Promise<void | ResponseType>
Retrieves details of a world.

Returns Promise<void | ResponseType>
Keywords
get, fetch, retrieve, details, info, information, world
Example
```
await world.fetchDetails();
const { name } = world;
```
Implementation of WorldInterface.fetchDetails
- Defined in controllers/World.ts:122

fetchSceneDropIds

fetchSceneDropIds(): Promise<object | ResponseType>
Returns Promise<object | ResponseType>
```
{ sceneDropIds: [] }
```
Deprecated
Use fetchScenes instead.

Fetch a list of all scene drop ids in a world that include at least one asset with an interactivePublicKey
Example
```
await world.fetchSceneDropIds();
```
Implementation of WorldInterface.fetchSceneDropIds
- Defined in controllers/World.ts:475

fireToast

fireToast(__namedParameters: FireToastInterface): Promise<void | ResponseType>
Display a message via a toast to all visitors currently in a world.
Parameters
- __namedParameters: FireToastInterface
Returns Promise<void | ResponseType>
Returns { success: true } or an error.
Keywords
send, display, show, toast, message, notification
Example
```
await world.fireToast({
  groupId: "custom-message",
  title: "Hello World",
  text: "Thank you for participating!",
});
```
Implementation of WorldInterface.fireToast
- Defined in controllers/World.ts:729

topiaPublicApi

topiaPublicApi(): AxiosInstance
Returns the configured Axios instance for making API calls to Topia's Public API.

Returns AxiosInstance
The configured Axios client instance with authentication headers.

Remarks
All HTTP requests to the Topia API should use this method to ensure proper authentication headers and base URL configuration are applied.

Keywords
api, axios, http, request, client, public api
Inherited from SDKController.topiaPublicApi
- Defined in controllers/SDKController.ts:133

triggerActivity

triggerActivity(
    __namedParameters: {
        assetId: string;
        excludeFromNotification?: (string | number)[];
        type: WorldActivityType;
    },
): Promise<string | ResponseType>
Add an activity to a world excludeFromNotification is an array of visitorIds to exclude from the notification
Parameters
- __namedParameters: {
      assetId: string;
      excludeFromNotification?: (string | number)[];
      type: WorldActivityType;
  }
Returns Promise<string | ResponseType>
Returns the activityId or an error response.
Keywords
start, trigger, activity
Example
```
await world.triggerActivity({ type: "GAME_ON", assetId: "abc123" });
```
Implementation of WorldInterface.triggerActivity
- Defined in controllers/World.ts:691

updateCloseWorldSettings

updateCloseWorldSettings(
    __namedParameters: {
        closeWorldDescription: string;
        isWorldClosed: boolean;
    },
): Promise<void | ResponseType>
Set close world settings
Parameters
- __namedParameters: { closeWorldDescription: string; isWorldClosed: boolean }
Returns Promise<void | ResponseType>
Returns { success: true } or an error.
Keywords
update, modify, change, edit, world, settings, details, close, closed
Example
```
await world.updateCloseWorldSettings({
  controls: {
    allowMuteAll: true,
    disableHideVideo: true,
    isMobileDisabled: false,
    isShowingCurrentGuests: false,
  },
  description: 'Welcome to my world.',
  forceAuthOnLogin: false,
  height: 2000,
  name: 'Example',
  spawnPosition: { x: 100, y: 100 },
  width: 2000
});
```
Implementation of WorldInterface.updateCloseWorldSettings
- Defined in controllers/World.ts:211

updateDetails

updateDetails(
__namedParameters: WorldDetailsInterface,
): Promise<void | ResponseType>

Update details of a world.

Parameters

__namedParameters: WorldDetailsInterface

Returns Promise<void | ResponseType>

Keywords

update, modify, change, edit, world, settings, details

Example

await world.updateDetails({
  controls: {
    allowMuteAll: true,
    disableHideVideo: true,
    isMobileDisabled: false,
    isShowingCurrentGuests: false,
  },
  description: 'Welcome to my world.',
  forceAuthOnLogin: false,
  height: 2000,
  name: 'Example',
  spawnPosition: { x: 100, y: 100 },
  width: 2000
});

const { name, description } = world;

Particles

getAllParticles

getAllParticles(): Promise<object | ResponseType>
Get all particles available

Returns Promise<object | ResponseType>
Keywords
get, fetch, retrieve, list, particles
Example
```
await world.getAllParticles();

@returns {Promise<ResponseType>} Returns an array of particles or an error response.
```
Implementation of WorldInterface.getAllParticles
- Defined in controllers/World.ts:622

triggerParticle

triggerParticle(
    __namedParameters: {
        duration?: number;
        id?: string;
        name?: string;
        position?: object;
    },
): Promise<string | ResponseType>
Trigger a particle effect at a position in the world
Parameters
- __namedParameters: { duration?: number; id?: string; name?: string; position?: object }
Returns Promise<string | ResponseType>
Returns { success: true } or a message if no particleId is found.
Keywords
trigger, start, play, particle, effect
Example
```
const droppedAsset = await DroppedAsset.get(assetId, urlSlug, { credentials });

await world.triggerParticle({ name: "Flame", duration: 5, position: droppedAsset.position });
```
Implementation of WorldInterface.triggerParticle
- Defined in controllers/World.ts:647

Scenes

dropScene

dropScene(
    __namedParameters: {
        allowNonAdmins?: boolean;
        assetSuffix?: string;
        position: object;
        sceneDropId?: string;
        sceneId: string;
    },
): Promise<ResponseType>
Drops a scene in a world and returns sceneDropId.
Parameters
- __namedParameters: {
      allowNonAdmins?: boolean;
      assetSuffix?: string;
      position: object;
      sceneDropId?: string;
      sceneId: string;
  }
Returns Promise<ResponseType>
```
{ sceneDropId: sceneId-timestamp, success: true }
```
Keywords
drop, add, place, scene
Example
```
await world.dropScene({
  "sceneId": "string",
  "position": {
    "x": 0,
    "y": 0
  },
  "assetSuffix": "string"
});
```
Implementation of WorldInterface.dropScene
- Defined in controllers/World.ts:556

fetchScenes

fetchScenes(): Promise<object | ResponseType>

Fetch a list of all scene drop ids and dropped assets in a world

Returns Promise<object | ResponseType>

{ "scenes": {
    "sceneDropId_1": {
        "droppedAssets": {
            "droppedAssetId_1": {
                "metaName": "hello"
                "metaNameReversed": "olleh"
            },
            "droppedAssetId_2": {
                "metaName": "world"
                "metaNameReversed": "dlorw"
            }
        }
    },
  }
}

Keywords

get, fetch, retrieve, list, scenes

Example

await world.fetchScenes();

replaceScene

replaceScene(sceneId: string): Promise<void | ResponseType>
Replace the current scene of a world.
Parameters
- sceneId: string
Returns Promise<void | ResponseType>
Returns { success: true } or an error.
Keywords
replace, change, scene
Example
```
const droppedAssetsToUpdate = [world.droppedAssets["6"], world.droppedAssets["12"]]
const style = {
  "textColor": "#abc123",
  "textFontFamily": "Arial",
  "textSize": 40,
  "textWeight": "normal",
  "textWidth": 200
}
await world.replaceScene(SCENE_ID);
```
Implementation of WorldInterface.replaceScene
- Defined in controllers/World.ts:600

Webhooks

fetchWebhooks

fetchWebhooks(): Promise<void | ResponseType>
Retrieve all webhooks in a world.

Returns Promise<void | ResponseType>
Keywords
get, fetch, retrieve, list, current, webhooks
Example
```
await world.fetchWebhooks();
const webhooks = world.webhooks;
```
Implementation of WorldInterface.fetchWebhooks
- Defined in controllers/World.ts:926

Class World

Example

Hierarchy (View Summary)

Implements

Index

Analytics

Data Objects

Dropped Assets

Other

Particles

Scenes

Webhooks

Analytics

fetchWorldAnalytics

Parameters

Returns Promise<void | ResponseType>

Keywords

Example

Data Objects

fetchDataObject

Parameters

Returns Promise<void | ResponseType>

Keywords

Example

incrementDataObjectValue

Parameters

Returns Promise<void | ResponseType>

Remarks

Keywords

Example

setDataObject

Parameters

Returns Promise<void | ResponseType>

Remarks

Keywords

Example

updateDataObject

Parameters

Returns Promise<void | ResponseType>

Remarks

Keywords

Example

Dropped Assets

fetchDroppedAssets

Returns Promise<void | ResponseType>

Keywords

Example

fetchDroppedAssetsBySceneDropId

Parameters

Returns Promise<DroppedAsset[]>

Keywords

Example

fetchDroppedAssetsWithUniqueName

Parameters

Returns Promise<DroppedAsset[]>

Keywords

Example

fetchLandmarkZones

Parameters

Returns Promise<DroppedAsset[]>

Keywords

Example

updateCustomTextDroppedAssets

Parameters

Returns Promise<object>

Keywords

Example

Other

constructor

Parameters

Returns World

credentials

OptionaldataObject

Optionaljwt

requestOptions

OptionalsceneDropIds

Optionalscenes

topia

urlSlug

Optionalwebhooks

`Optional`dataObject

`Optional`jwt

`Optional`sceneDropIds

`Optional`scenes

`Optional`webhooks

Returns {
data: {};
message: string;
method: string;
params: object;
sdkMethod: undefined | string;
stack: string;
stackTrace: Error;
status: number;
success: boolean;
url: string;
}