# 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](https://github.com/decentraland/docs/blob/main/contributor/filesystem.md) 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](#types). The identifier for an entity is actually the [file identifier](https://github.com/decentraland/docs/blob/main/contributor/filesystem.md#identifiers) 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](https://github.com/decentraland/docs/blob/main/contributor/pointers.md). The newest version of an entity is said to be *active*.

Every entity 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](https://github.com/decentraland/docs/blob/main/contributor/practice.md) section.

### Entity Types <a href="#types" id="types"></a>

There are seven types of entities:

* [**Scenes**](https://docs.decentraland.org/contributor/content/entity-types/scenes): virtual spaces in the world with their own objects and behavior.
* [**Profiles**](https://docs.decentraland.org/contributor/content/entity-types/profiles): information about a specific player, such as their name and avatar.
* [**Wearables**](https://docs.decentraland.org/contributor/content/entity-types/wearables): clothing and items that players can add to their avatars.
* [**Emotes**](https://docs.decentraland.org/contributor/content/entity-types/emotes): animations that a player's avatar can perform.
* [**Stores**](https://docs.decentraland.org/contributor/content/entity-types/stores): marketplace sites for wearables and emotes that players can purchase.
* [**Outfits**](https://docs.decentraland.org/contributor/content/entity-types/outfits): saved outfits for a specific player.

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

### Common Properties <a href="#properties" id="properties"></a>

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`, `store` or `outfits`.                                                                           |
| `pointers`  | An array of [pointers](https://github.com/decentraland/docs/blob/main/contributor/pointers.md) associated to this entity.                       |
| `timestamp` | The Unix UTC timestamp when this entity was uploaded.                                                                                           |
| `content`   | An array of references to additional [files](https://github.com/decentraland/docs/blob/main/contributor/filesystem.md) 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.

{% hint style="info" %}
Old entity manifests may contain the `version` field, deprecated in [ADR-45](https://adr.decentraland.org/adr/ADR-45). You may safely ignore it, since the `timestamp` field is now used for versioning.
{% endhint %}

This is a typical JSON manifest describing an entity:

```json
{
  "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](https://github.com/decentraland/common-schemas) repository.

{% hint style="info" %}
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.
{% endhint %}

### Files <a href="#files" id="files"></a>

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](https://github.com/decentraland/docs/blob/main/contributor/filesystem.md#identifiers) 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](https://github.com/decentraland/docs/blob/main/contributor/filesystem.md), 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](https://github.com/decentraland/docs/blob/main/contributor/filesystem.md#identifiers), unique across all content. |

This is how it typically looks inside the `content` field:

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

{% hint style="info" %}
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.
{% endhint %}

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 <a href="#ownership" id="ownership"></a>

To prove ownership and authorize actions around entities, the [authentication chain](https://github.com/decentraland/docs/blob/main/auth/authchain.md) mechanism is used.

The [`decentraland-crypto`](https://github.com/decentraland/decentraland-crypto) repository contains the implementation of all cryptographic procedures.

### Discovering and Downloading Entities

Content servers can be used to locate entities using [pointers](https://github.com/decentraland/docs/blob/main/contributor/pointers.md), and to download their manifests and any additional files.

* To resolve a pointer into an entity ID, you can use the [`/entities/active`](https://decentraland.github.io/catalyst-api-specs/#tag/Content-Server/operation/getListOfEntities) endpoint.
* Using the entity ID, you can download the manifest with the [`/contents/<id>`](https://decentraland.github.io/catalyst-api-specs/#tag/Content-Server/operation/getContentFile) endpoint.
* To get all active entities of a certain type, start by downloading a [snapshot](https://github.com/decentraland/docs/blob/main/contributor/snapshots.md).

Check out the [practice](https://github.com/decentraland/docs/blob/main/contributor/practice.md) section for examples and guides.