Entidades

Cada peça individual de conteúdo no mundo (como uma scene ou um wearable item) é chamada de entity.

Entities são pacotes imutáveis de files com um identificador de string único, derivado deterministically dos dados contidos, que pode ser usado para descobrir e baixar os arquivos relacionados do content server.

O arquivo principal de uma entity é o manifest, um documento JSON descrevendo as propriedades gerais da entity, bem como atributos especiais para cada type. O identificador para uma entity é na verdade o file identifier deste manifest.

Como são imutáveis, entities não podem ser atualizadas no sentido tradicional. Em vez disso, elas são substituídas por novas entities descobríveis usando o mesmo pointer. A versão mais recente de uma entity é dita estar active.

Cada entity é assinada por um owner (que está associado a uma conta Ethereum). O owner pode posteriormente usar as mesmas chaves de assinatura para fazer upload de uma nova versão da entity e indicar que ela substitui a anterior. Content servers validam essas assinaturas antes de aceitar novas entities, quer elas venham diretamente de um client ou tenham sido retransmitidas por outro server.

Você pode observar entities realmente implantadas no prática seção.

Entity Types

Existem sete tipos de entities:

• Scenes: espaços virtuais no mundo com seus próprios objetos e comportamento.

• Profiles: informações sobre um jogador específico, como seu nome e avatar.

• Wearables: roupas e itens que os players podem adicionar aos seus avatars.

• Emotes: animações que o avatar de um player pode executar.

• Stores: sites de marketplace para wearables e emotes que os players podem comprar.

• Outfits: outfits salvos para um player específico.

Todos os tipos seguem os mesmos procedimentos para criação, identificação, propriedade e hospedagem.

Common Properties

Cada entity tem certas propriedades comuns em seu manifest, aplicáveis a todos os tipos. Esses campos de nível superior estarão sempre presentes:

Campo	Valor
type	Um de cena, perfil, wearable, emote, store ou outfits.
pointers	Um array de pointers associado a esta entity.
timestamp	O timestamp Unix UTC quando esta entity foi enviada.
content	Uma matriz de referências para arquivos adicionais files no pacote da entity.
metadata	Um objeto com informações específicas para este tipo de entity.

A estrutura e os valores do campo metadata para cada tipo são detalhados em suas páginas específicas. O array pointers também tem conteúdos diferentes dependendo do tipo.

Manifests antigos de entity podem conter o campo version , obsoleto em ADR-45. Você pode ignorá-lo com segurança, já que o campo timestamp agora é usado para versionamento.

Este é um manifest JSON típico descrevendo uma entity:

{
  "type": "wearable",
  "pointers": ["urn:decentraland:matic:collections-v2:0xbdf21eaf54ebf4a6cadc2dcb371df7afce98bc1d:0"],
  "timestamp": 1628181913506,
  "content": [
    // ...referências de arquivos, veja abaixo
  ],
  "metadata": {
    // ...campos específicos para este tipo de entity, veja a página relevante
  }
}

Você pode encontrar os schemas para essas estruturas JSON, junto com outros objetos no protocolo Decentraland, no Common Schemas repositório.

Ao olhar os manifests de entity, você pode encontrar campos não documentados. Isso ocorre porque o schema da entity permite propriedades personalizadas adicionais, definidas livremente pelo owner.

Arquivos

Como mencionado acima, todas as entities têm pelo menos um arquivo associado: o manifest JSON descrevendo a própria entity. O identificador da entity é na verdade o file identifier deste arquivo especial.

O content O campo dentro de cada manifest é um array de referências para arquivos adicionais. Estes são tipicamente assets, como modelos 3D e animações, ou scripts para scenes.

Todos os arquivos são armazenados no distributed file systemdo Decentraland, e cada item no array tem duas propriedades:

Campo	Valor
file	O nome interno usado pelos arquivos nesta entity para se referirem uns aos outros.
hash	O global identifier for this file, único através de todo o conteúdo.

É assim que normalmente aparece dentro do campo content :

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

O file O valor do campo é sempre em letras minúsculas, para evitar problemas ao construir entities em diferentes sistemas operacionais, onde a diferenciação de maiúsculas/minúsculas em nomes de arquivo pode ser importante.

A vida útil de um arquivo está vinculada à entity que o contém. Para entities ativas (ou seja, ainda não substituídas pelo seu owner), os content servers são obrigados pelo protocolo a preservar todos os arquivos associados. Se a entity for deletada, os arquivos podem ser mantidos ou descartados a critério do server.

Ownership and Authentication

Para provar propriedade e autorizar ações envolvendo entities, o mecanismo auth_chain é usado.

O decentraland-crypto repositório contém a implementação de todos os procedimentos criptográficos.

Discovering and Downloading Entities

Content servers podem ser usados para localizar entities usando pointers, e para baixar seus manifests e quaisquer arquivos adicionais.

• Para resolver um pointer em um entity ID, você pode usar o /entities/active endpoint.

• Usando o entity ID, você pode baixar o manifest com o /contents/<id> endpoint.

• Para obter todas as entities ativas de um certo tipo, comece baixando um snapshot.

Confira a seção prática para exemplos e guias.