Contributors
Entities

Entities

Each individual piece of content in the world (such as a scene or a wearable item) is called an entity.

Entities are immutable packages of files with a unique string identifier, deterministically derived from the contained data, which can be used to discover and download the related files from the content server.

The main file of an entity is the manifest, a JSON document describing the entity’s general properties, as well as special attributes for each type. The identifier for an entity is actually the file identifier of this manifest.

Since they are immutable, entities can’t be updated in the traditional sense. Instead, they are replaced by new entities discoverable using the same stable pointer. The newest version of an entity is said to be active.

Every entitiy is signed by an owner (who is associated to an Ethereum account). The owner can later use the same signing keys to upload a new version of the entity and indicate that it replaces the old one. Content servers validate these signatures before accepting new entities, whether they come straight from a client or were relayed by another server.

You can look at actually deployed entities in the practice section.

Entity Types #

There are five types of entities:

  • Scenes: virtual spaces in the world with their own objects and behavior.
  • Profiles: information about a specific player, such as their name and avatar.
  • Wearables: clothing and items that players can add to their avatars.
  • Emotes: animations that a player’s avatar can perform.
  • Stores: marketplace sites for wearables and emotes that players can purchase.

All types follow the same procedures for creation, identification, ownership and hosting.

Common Properties #

Every entity has certain common properties in its manifest, applicable to all types. These top-level fields will always be present:

Field Value
type One of scene, profile, wearable, emote or store.
pointers An array of pointers associated to this entity.
timestamp The Unix UTC timestamp when this entity was uploaded.
content An array of references to additional files in the entity’s package.
metadata An object with information specific to this entity type.

The structure and values of the metadata field for each type are detailed in their specific pages. The pointers array also has different contents dependent on the type.

Old entity manifests may contain the version field, deprecated in ADR-45. You may safely ignore it, since the timestamp field is now used for versioning.

This is a typical JSON manifest describing an entity:

{
  "type": "wearable",
  "pointers": ["urn:decentraland:matic:collections-v2:0xbdf21eaf54ebf4a6cadc2dcb371df7afce98bc1d:0"],
  "timestamp": 1628181913506,
  "content": [
    // ...file references, see below
  ],
  "metadata": {
    // ...specific fields for this entity type, see the relevant page
  }
}

You can find the schemas for these JSON structures, along with other objects in Decentraland protocol, in the Common Schemas repository.

When looking at entity manifests, you may find undocumented fields. This is because the entity schema allows for additional custom properties, freely set by the owner.

Files #

As mentioned above, all entities have at least one associated file: the JSON manifest describing the entity itself. The entity identifier is actually the file identifier of this special file.

The content field inside each manifest is an array of references to additional files. These are typically assets, such as 3D models and animations, or scripts for scenes.

All files are stored in Decentraland’s distributed file system, and each item in the array has two properties:

Field Value
file The internal name used by files in this entity to reference each other.
hash The global identifier for this file, unique across all content.

This is how it typically looks inside the content field:

[
  {
    "file": "thumbnail.png",
    "hash": "bafkreiglecvpnqibvf6pltcnid5nhbx3caj77lu4ia4xitpmp3lrcouuhm",
  },
  {
    "file": "model.glb",
    "hash": "bafkreic2i3awiu7srhatf3k47l3c5lmadisznjigppor2a35saosjfbo25",
  },
  // ...more files
]

The file field value is always in lower-case, to prevent issues when building entities in different operating systems, where filename casing may be important.

The lifespan of a file is tied to the entity that contains it. For active entities (i.e. not yet replaced by their owner), content servers are required by protocol to preserve all associated files. If the entity is deleted, the files can be kept or discarded at the server’s discretion.

Ownership and Authentication #

Work in Progress

This section is incomplete. Sorry! Give us some time to continue expanding the documentation, and we'll have great content for you here.

The decentraland-crypto repository contains the functionality for authenticating entities.

Discovering and Downloading Entities #

Content servers can be used to locate entities using pointers, and to download their manifests and any additional files.

  • To resolve a pointer into an entity ID, you can use the /entities/active endpoint.

  • Using the entity ID, you can download the manifest with the /contents/<id> endpoint.

  • To get all active entities of a certain type, start by downloading a snapshot.

Check out the practice section for examples and guides.