Contributors
Scenes

Scenes

Scenes are the entities that produce behavior in different parts of Decentraland. They can span multiple land parcels, and players walking through them in a World Explorer will execute special code provided by the scene.

You can find a complete real-life example in this scene’s manifest on the Foundation’s content server.

Pointers #

Scenes have one or more associated pointers in the form of parcel coordinate strings, such as "0,0". Every parcel running the scene will be listed in the pointers array of the entity manifest, and all those pointers will be resolved by the content server to that scene.

In other words, you can choose the x/y coordinates of a parcel and locate the scene it’s running by querying the content server for the "<x>,<y>" pointer. This is the way World Explorers decide whether to enable a scene’s behavior as the player navigates the world.

A typical pointers array looks like this:

{
  "pointers": [
    "-113,-134",
    "-113,-133",
    "-113,-132",
  ],
  // ... other entity properties
}

This data is also available in the metadata.scene.parcels field detailed below, in case you want to save only the scene-specific object in the manifest.

Metadata Fields #

There are several special properties for entities of type scene located in the metadata top-level field.

Field Value
owner Information about the scene’s maintainer.
main The internal filename to this scene’s main JavaScript file.
tags An array of string labels descriptive of this scene.
display Information about the scene for Explorers to show players (see below).
scene The parcels this scene is active on, and its central location (see below).
contact Name and email address to reach the scene’s creators or maintainers (see below).
spawnPoints Locations and camera angles for players jumping into this scene (see below).
requiredPermissions Recommended permissions for Explorers to ask from players (see below).
featureToggles Settings for feature flags

Remember that entities and their metadata are allowed to have custom fields. You may find some properties out there that are not listed here.

Display #

In metadata.display, you’ll find properties that are useful to inform players about the scene before they enter it.

Field Value
title The display name of this scene.
description An extended description of this scene.
favicon Deprecated The internal filename to an icon, displayed when this scene is active.
navmapThumbnail The internal filename to this scene’s thumbnail for the world map.

An example:

{
  "title": "my_cool_scene",
  "favicon": "favicon.png",
  "navmapThumbnail": "thumbnail.png"
}

Scene #

The metadata.scene property is an object describing the position of this scene in the world map.

Field Value
parcels An array of parcel pointers that run this scene.
base The parcel pointer for the origin point of this scene.

In practice, it looks like this:

{
  "parcels": [
    "17,-112", 
    "17,-113"
  ],
  "base": "17,-112"
}

The base field is always included in the parcels array.

Contact #

The metadata.contact object contains the contact information of the scene’s owner or maintainer.

Field Value
name A name for this contact.
email (Optional) An email address to reach out to.

In JSON:

{
  "name": "cool_scene_maker",
  "email": "hello@decentraland.org"
}

While the name field is filled in every scene, you’ll find that in actual practice the email field is often an empty string. This is a privacy choice made the scene’s creator.

Spawn Points #

The metadata.spawnPoints field defines an array of points and camera directions determining where players entering the scene should appear, and where they should be initially looking. There must be at least one defined spawn point.

Each item in the array has a number of properties:

Field Value
name A label to identify this spawn point.
position The starting position in an { x, y, z } object with float coordinates.
cameraTarget The starting camera direction in an { x, y, z } object with float coordinates.
default Whether this spawn point is used unless otherwise specified.

For example:

[
  {
    "name": "spawn1",
    "position": { "x": 10.02, "y": 5.27, "z": 15.23  },
    "cameraTarget": { "x": 10.02, "y": 6.27, "z": 31.23 },
    "default": true
  }
]

Required Permissions #

In metadata.requiredPermissions you’ll find an array of well-known strings declaring which permissions should be asked from the player before the World Explorer allows certain actions. This is incumbent on the Explorer, on other clients built for different purposes may choose to ignore this.

This is the current set of supported permissions:

Permission Purpose
USE_FETCH Let the scene perform external HTTP requests.
USE_WEBSOCKET Let the scene use the Websocket API to establish external connections.
OPEN_EXTERNAL_LINK Let the scene open a URL (in a browser tab or web view).
USE_WEB3_API Let the scene communicate with a wallet.
ALLOW_TO_TRIGGER_AVATAR_EMOTE Let the scene to animate the player’s avatar with an emote.
ALLOW_TO_MOVE_PLAYER_INSIDE_SCENE Let the scene to change the player’s position.

Feature Toggles #

The metadata.featureToggles field lets a scene indicate whether certain features of the World Explorer should be enabled or disabled.

The field contains an object of the form { [featureName]: 'enabled' | 'disabled' }, like this one:

{
  "voiceChat": "enabled"
}

Currently, voiceChat is the only commonly supported feature flag.