实体

世界中的每一份独立内容（例如场景或可穿戴物品）称为一个 实体.

实体是不可变的内容包 文件 ，带有一个唯一的字符串标识符，该标识符由其所含数据确定性派生，可用于从内容服务器发现并下载相关文件。

实体的主文件是 清单，这是一个 JSON 文档，描述实体的通用属性，以及每个 类型。实体的标识符实际上是该 文件标识符 清单的。

由于实体不可变，因此不能以传统方式更新。相反，它们会被新的实体替换，而这些新实体可通过相同的稳定 指针。实体的最新版本被称为 处于活动状态.

每个实体都由一个所有者签名（该所有者与一个 Ethereum 账户关联）。所有者之后可以使用相同的签名密钥上传实体的新版本，并表明它替换了旧版本。内容服务器在接受新实体之前会验证这些签名，无论这些实体是直接来自客户端，还是由另一台服务器转发而来。

你可以在以下位置查看实际部署的实体： 练习 部分。

实体类型

实体共有七种类型：

• 场景：世界中的虚拟空间，拥有自己的对象和行为。

• 个人资料：关于某个特定玩家的信息，例如其姓名和头像。

• 可穿戴物品：玩家可以添加到头像上的服装和物品。

• 表情动作：玩家头像可以执行的动画。

• 商店：供玩家购买可穿戴物品和表情动作的市场站点。

• 套装：某个特定玩家保存的套装。

所有类型在创建、标识、所有权和托管方面都遵循相同的流程。

通用属性

每个实体在其清单中都有一些通用属性，适用于所有类型。这些顶层字段始终会存在：

字段	值
类型	以下之一： 场景, 个人资料, 可穿戴物, 表情动作, 商店 或 套装.
指针	一个包含 指针 与该实体关联。
时间戳	该实体上传时的 Unix UTC 时间戳。
内容	一个指向额外 文件 实体包中文件的引用数组。
metadata	一个包含此实体类型特定信息的对象。

该 metadata 字段在每种类型中的结构和值都在各自的页面中详细说明。 指针 数组的内容也会因类型而异。

旧版实体清单可能包含 版本 字段，在以下版本中已弃用： ADR-45。你可以放心忽略它，因为 时间戳 字段现在用于版本控制。

这是一个描述实体的典型 JSON 清单：

{
  "type": "wearable",
  "pointers": ["urn:decentraland:matic:collections-v2:0xbdf21eaf54ebf4a6cadc2dcb371df7afce98bc1d:0"],
  "timestamp": 1628181913506,
  "content": [
    // ……文件引用，见下文
  ],
  "metadata": {
    // ……此实体类型的特定字段，见相关页面
  }
}

你可以在以下位置找到这些 JSON 结构以及 Decentraland 协议中其他对象的模式： 通用模式 仓库。

在查看实体清单时，你可能会发现未文档化的字段。这是因为实体模式允许额外的自定义属性，可由所有者自由设置。

文件

如上所述，所有实体至少都有一个关联文件：描述实体本身的 JSON 清单。实体标识符实际上是该 文件标识符 特殊文件的。

该 内容 每个清单中的字段是一个指向额外文件的引用数组。这些通常是资源，例如 3D 模型和动画，或场景脚本。

所有文件都存储在 Decentraland 的 分布式文件系统中，数组中的每一项都有两个属性：

字段	值
文件	此实体中文件相互引用时使用的内部名称。
hash	该文件的全局 标识符，在所有内容中都唯一。

它在 内容 字段中通常看起来是这样的：

[
  {
    "file": "thumbnail.png",
    "hash": "bafkreiglecvpnqibvf6pltcnid5nhbx3caj77lu4ia4xitpmp3lrcouuhm",
  },
  {
    "file": "model.glb",
    "hash": "bafkreic2i3awiu7srhatf3k47l3c5lmadisznjigppor2a35saosjfbo25",
  },
  // ……更多文件
]

该 文件 字段值始终采用小写，以避免在不同操作系统中构建实体时出现问题，因为文件名大小写可能很重要。

文件的生命周期取决于包含它的实体。对于活动实体（即尚未被其所有者替换的实体），协议要求内容服务器保留所有关联文件。如果实体被删除，文件可以由服务器自行决定保留或丢弃。

所有权与认证

为了证明所有权并授权围绕实体的操作， 认证链 会使用该机制。

该 decentraland-crypto 仓库包含所有加密流程的实现。

发现和下载实体

内容服务器可用于通过 指针定位实体，并下载其清单及任何额外文件。

• 要将指针解析为实体 ID，可以使用 /entities/active 端点为你提供所有已知收藏集的列表。

• 使用实体 ID，你可以通过以下方式下载清单： /contents/<id> 端点为你提供所有已知收藏集的列表。

• 要获取某一类型的所有活动实体，首先下载一个 快照.

请查看 练习 部分以获取示例和指南。