# Entities

Cada pieza individual de contenido en el world (como una scene o un wearable item) se llama un *entity*.

Entities son paquetes inmutables de [archivos](https://github.com/decentraland/docs/blob/main/contributor/filesystem.md) con un identificador de cadena único, derivado determinísticamente de los datos contenidos, que puede usarse para descubrir y descargar los archivos relacionados desde el content server.

El archivo principal de una entidad es el *manifest*, un documento JSON que describe las propiedades generales de la entidad, así como atributos especiales para cada [type](#types). El identificador de una entidad es en realidad el [file identifier](https://github.com/decentraland/docs/blob/main/contributor/filesystem.md#identifiers) de este manifest.

Como son inmutables, las entidades no pueden actualizarse en el sentido tradicional. En su lugar, son reemplazadas por nuevas entidades descubribles usando el mismo [pointer](https://github.com/decentraland/docs/blob/main/contributor/pointers.md). La versión más reciente de una entidad se dice que está *active*.

Toda entidad está firmada por un owner (que está asociado a una cuenta de Ethereum). El owner puede más tarde usar las mismas claves de firma para subir una nueva versión de la entidad e indicar que reemplaza a la anterior. Los content servers validan estas firmas antes de aceptar nuevas entidades, ya sea que vengan directamente de un client o hayan sido retransmitidas por otro server.

Puedes ver entidades realmente desplegadas en el [práctica](https://github.com/decentraland/docs/blob/main/contributor/practice.md) sección.

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

Existen siete tipos de entidades:

* [**Scenes**](https://docs.decentraland.org/contributor/contributor-es/contenido/tipos-de-entity/scenes): espacios virtuales en el world con sus propios objetos y comportamiento.
* [**Profiles**](https://docs.decentraland.org/contributor/contributor-es/contenido/tipos-de-entity/profiles): información sobre un jugador específico, como su nombre y avatar.
* [**Wearables**](https://docs.decentraland.org/contributor/contributor-es/contenido/tipos-de-entity/wearables): ropa y objetos que los jugadores pueden añadir a sus avatars.
* [**Emotes**](https://docs.decentraland.org/contributor/contributor-es/contenido/tipos-de-entity/emotes): animaciones que el avatar de un jugador puede ejecutar.
* [**Stores**](https://docs.decentraland.org/contributor/contributor-es/contenido/tipos-de-entity/stores): sitios de marketplace para wearables y emotes que los jugadores pueden comprar.
* [**Outfits**](https://docs.decentraland.org/contributor/contributor-es/contenido/tipos-de-entity/outfits): outfits guardados para un jugador específico.

Todos los tipos siguen los mismos procedimientos para creación, identificación, ownership y hosting.

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

Cada entidad tiene ciertas propiedades comunes en su manifest, aplicables a todos los tipos. Estos campos de primer nivel siempre estarán presentes:

| Campo       | Valor                                                                                                                                                              |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type`      | Uno de `escena`, `perfil`, `wearable`, `emote`, `store` o `outfits`.                                                                                               |
| `pointers`  | Un arreglo de [pointers](https://github.com/decentraland/docs/blob/main/contributor/pointers.md) associated to this entity.                                        |
| `timestamp` | La marca de tiempo Unix UTC cuando esta entidad fue subida.                                                                                                        |
| `content`   | Un arreglo de referencias a archivos adicionales [archivos](https://github.com/decentraland/docs/blob/main/contributor/filesystem.md) en el paquete de la entidad. |
| `metadata`  | Un objeto con información específica para este tipo de entidad.                                                                                                    |

La estructura y los valores del `metadata` campo para cada tipo se detallan en sus páginas específicas. El `pointers` array también tiene contenidos diferentes dependiendo del tipo.

{% hint style="info" %}
Los manifiestos de entidades antiguos pueden contener el `version` campo, desaprobado en [ADR-45](https://adr.decentraland.org/adr/ADR-45). Puedes ignorarlo con seguridad, ya que el `timestamp` campo ahora se usa para versionado.
{% endhint %}

Este es un manifest JSON típico que describe una entidad:

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

Puedes encontrar los esquemas para estas estructuras JSON, junto con otros objetos en el protocolo de Decentraland, en el [Common Schemas](https://github.com/decentraland/common-schemas) repository.

{% hint style="info" %}
Al mirar los manifiestos de entidades, puedes encontrar campos no documentados. Esto se debe a que el esquema de entidad permite propiedades personalizadas adicionales, establecidas libremente por el owner.
{% endhint %}

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

Como se mencionó arriba, todas las entidades tienen al menos un archivo asociado: el manifest JSON que describe la propia entidad. El identificador de la entidad es en realidad el [file identifier](https://github.com/decentraland/docs/blob/main/contributor/filesystem.md#identifiers) de este archivo especial.

El `content` el campo dentro de cada manifest es un arreglo de referencias a archivos adicionales. Estos suelen ser assets, como modelos 3D y animations, o scripts para scenes.

Todos los archivos se almacenan en el [distributed file system](https://github.com/decentraland/docs/blob/main/contributor/filesystem.md)de Decentraland, y cada elemento en el arreglo tiene dos propiedades:

| Campo  | Valor                                                                                                                                                 |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `file` | El nombre interno usado por los archivos en esta entidad para referenciarse entre sí.                                                                 |
| `hash` | El global [identifier for this file](https://github.com/decentraland/docs/blob/main/contributor/filesystem.md#identifiers), único en todo el content. |

Así es como normalmente se ve dentro del `content` campo:

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

{% hint style="info" %}
El `file` El valor del campo siempre está en minúsculas, para evitar problemas al construir entidades en diferentes sistemas operativos, donde la distinción entre mayúsculas y minúsculas en los nombres de archivo puede ser importante.
{% endhint %}

La vida útil de un archivo está ligada a la entidad que lo contiene. Para entidades active (es decir, que aún no han sido reemplazadas por su owner), los content servers están obligados por el protocolo a preservar todos los archivos asociados. Si la entidad es eliminada, los archivos pueden conservarse o descartarse a discreción del server.

### Ownership and Authentication <a href="#ownership" id="ownership"></a>

Para demostrar ownership y autorizar acciones alrededor de entidades, se utiliza el [auth chain](https://github.com/decentraland/docs/blob/main/auth/authchain.md) mechanism is used.

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

### Discovering and Downloading Entities

Los content servers pueden usarse para ubicar entidades usando [pointers](https://github.com/decentraland/docs/blob/main/contributor/pointers.md), y para descargar sus manifests y cualquier archivo adicional.

* Para resolver un pointer en un entity ID, puedes usar el [`/entities/active`](https://decentraland.github.io/catalyst-api-specs/#tag/Content-Server/operation/getListOfEntities) endpoint.
* Usando el entity ID, puedes descargar el manifest con el [`/contents/<id>`](https://decentraland.github.io/catalyst-api-specs/#tag/Content-Server/operation/getContentFile) endpoint.
* Para obtener todas las entidades active de cierto tipo, comienza descargando un [snapshot](https://github.com/decentraland/docs/blob/main/contributor/snapshots.md).

Consulta la sección [práctica](https://github.com/decentraland/docs/blob/main/contributor/practice.md) para ejemplos y guías.