Class World

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

Example

const world = await new World(topia, "exampleWorld", {
  attributes: { name: "Example World" },
  credentials: { interactiveNonce: "exampleNonce", assetId: "droppedAssetId", visitorId: 1, urlSlug: "exampleWorld" }
});

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>
Example
```
const analytics = await world.fetchWorldAnalytics({
  periodType: "week",
  dateValue: 40,
  year: 2023,
});
```
- Defined in controllers/World.ts:845

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>
Example
```
await world.fetchDataObject();
const { dataObject } = world;
```
Implementation of WorldInterface.fetchDataObject
- Defined in controllers/World.ts:661

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
Example
```
await world.incrementDataObjectValue([`keyAssets.${keyAssetId}.totalItemsCollected.count`], 1);
```
Implementation of WorldInterface.incrementDataObjectValue
- Defined in controllers/World.ts:779

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
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:703

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
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:743

Dropped Assets

fetchDroppedAssets

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

Returns Promise<void | ResponseType>
Example
```
await world.fetchDroppedAssets();
const assets = world.droppedAssets;
```
Implementation of WorldInterface.fetchDroppedAssets
- Defined in controllers/World.ts:184

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.
Example
```
const droppedAssets = await world.fetchDroppedAssetsBySceneDropId({
  sceneDropId: "sceneDropIdExample",
  uniqueName: "optionalUniqueNameExample",
});
```
Implementation of WorldInterface.fetchDroppedAssetsBySceneDropId
- Defined in controllers/World.ts:266

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.
Example
```
const droppedAssets = await world.fetchDroppedAssetsWithUniqueName({ uniqueName: "exampleUniqueName", isPartial: true });
```
Implementation of WorldInterface.fetchDroppedAssetsWithUniqueName
- Defined in controllers/World.ts:216

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.
Example
```
const zones = await world.fetchLandmarkZones("optionalLandmarkZoneName", "optionalSceneDropIdExample");
```
- Defined in controllers/World.ts:343

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.
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:322

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:43

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:50

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;
}
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;
}
Inherited from SDKController.errorHandler
- Defined in controllers/SDKController.ts:97

fetchDetails

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

Returns Promise<void | ResponseType>
Example
```
await world.fetchDetails();
const { name } = world;
```
Implementation of WorldInterface.fetchDetails
- Defined in controllers/World.ts:64

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();
```
- Defined in controllers/World.ts:391

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.
Example
```
await world.fireToast({
  groupId: "custom-message",
  title: "Hello World",
  text: "Thank you for participating!",
});
```
Implementation of WorldInterface.fireToast
- Defined in controllers/World.ts:631

topiaPublicApi

topiaPublicApi(): AxiosInstance
Returns AxiosInstance
Inherited from SDKController.topiaPublicApi
- Defined in controllers/SDKController.ts:93

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.
Example
```
await world.triggerActivity({ type: "GAME_ON", assetId: "abc123" });
```
- Defined in controllers/World.ts:595

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.

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

updateDetails

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

Update details of a world.

Parameters

__namedParameters: WorldDetailsInterface

Returns Promise<void | ResponseType>

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>
Example
```
await world.getAllParticles();

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

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.
Example
```
const droppedAsset = await DroppedAsset.get(assetId, urlSlug, { credentials });

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

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 }
```
Example
```
await world.dropScene({
  "sceneId": "string",
  "position": {
    "x": 0,
    "y": 0
  },
  "assetSuffix": "string"
});
```
Implementation of WorldInterface.dropScene
- Defined in controllers/World.ts:468

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"
            }
        }
    },
  }
}

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.

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

Webhooks

fetchWebhooks

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

Returns Promise<void | ResponseType>
Example
```
await world.fetchWebhooks();
const webhooks = world.webhooks;
```
- Defined in controllers/World.ts:818

Class World

Example

Hierarchy (View Summary)

Implements

Index

Analytics

Data Objects

Dropped Assets

Other

Particles

Scenes

Webhooks

Analytics

fetchWorldAnalytics

Parameters

Returns Promise<void | ResponseType>

Example

Data Objects

fetchDataObject

Parameters

Returns Promise<void | ResponseType>

Example

incrementDataObjectValue

Parameters

Returns Promise<void | ResponseType>

Remarks

Example

setDataObject

Parameters

Returns Promise<void | ResponseType>

Remarks

Example

updateDataObject

Parameters

Returns Promise<void | ResponseType>

Remarks

Example

Dropped Assets

fetchDroppedAssets

Returns Promise<void | ResponseType>

Example

fetchDroppedAssetsBySceneDropId

Parameters

Returns Promise<DroppedAsset[]>

Example

fetchDroppedAssetsWithUniqueName

Parameters

Returns Promise<DroppedAsset[]>

Example

fetchLandmarkZones

Parameters

Returns Promise<DroppedAsset[]>

Example

updateCustomTextDroppedAssets

Parameters

Returns Promise<object>

Example

Other

constructor

Parameters

Returns World

credentials

OptionaldataObject

Optionaljwt

requestOptions

OptionalsceneDropIds

Optionalscenes

topia

urlSlug

Optionalwebhooks

droppedAssets

Returns { [key: string]: DroppedAsset }

errorHandler

Parameters

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

fetchDetails

Returns Promise<void | ResponseType>

Example

fetchSceneDropIds

Returns Promise<object | ResponseType>

`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;
}