> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/contributor/contributor-zh/nei-rong/entities.md).
# 实体
世界中的每一份独立内容（例如场景或可穿戴物品）称为一个 *实体*.
实体是不可变的内容包 [文件](https://github.com/decentraland/docs/blob/main/contributor/filesystem.md) ，带有一个唯一的字符串标识符，该标识符由其所含数据确定性派生，可用于从内容服务器发现并下载相关文件。
实体的主文件是 *清单*，这是一个 JSON 文档，描述实体的通用属性，以及每个 [类型](#types)。实体的标识符实际上是该 [文件标识符](https://github.com/decentraland/docs/blob/main/contributor/filesystem.md#identifiers) 清单的。
由于实体不可变，因此不能以传统方式更新。相反，它们会被新的实体替换，而这些新实体可通过相同的稳定 [指针](https://github.com/decentraland/docs/blob/main/contributor/pointers.md)。实体的最新版本被称为 *处于活动状态*.
每个实体都由一个所有者签名（该所有者与一个 Ethereum 账户关联）。所有者之后可以使用相同的签名密钥上传实体的新版本，并表明它替换了旧版本。内容服务器在接受新实体之前会验证这些签名，无论这些实体是直接来自客户端，还是由另一台服务器转发而来。
你可以在以下位置查看实际部署的实体： [练习](https://github.com/decentraland/docs/blob/main/contributor/practice.md) 部分。
### 实体类型
实体共有七种类型：
* [**场景**](/contributor/contributor-zh/nei-rong/shi-ti-lei-xing/scenes.md)：世界中的虚拟空间，拥有自己的对象和行为。
* [**个人资料**](/contributor/contributor-zh/nei-rong/shi-ti-lei-xing/profiles.md)：关于某个特定玩家的信息，例如其姓名和头像。
* [**可穿戴物品**](/contributor/contributor-zh/nei-rong/shi-ti-lei-xing/wearables.md)：玩家可以添加到头像上的服装和物品。
* [**表情动作**](/contributor/contributor-zh/nei-rong/shi-ti-lei-xing/emotes.md)：玩家头像可以执行的动画。
* [**商店**](/contributor/contributor-zh/nei-rong/shi-ti-lei-xing/stores.md)：供玩家购买可穿戴物品和表情动作的市场站点。
* [**套装**](/contributor/contributor-zh/nei-rong/shi-ti-lei-xing/outfits.md)：某个特定玩家保存的套装。
所有类型在创建、标识、所有权和托管方面都遵循相同的流程。
### 通用属性
每个实体在其清单中都有一些通用属性，适用于所有类型。这些顶层字段始终会存在：
| 字段 | 值 |
| ---------- | -------------------------------------------------------------------------------------------------- |
| `类型` | 以下之一： `场景`, `个人资料`, `可穿戴物`, `表情动作`, `商店` 或 `套装`. |
| `指针` | 一个包含 [指针](https://github.com/decentraland/docs/blob/main/contributor/pointers.md) 与该实体关联。 |
| `时间戳` | 该实体上传时的 Unix UTC 时间戳。 |
| `内容` | 一个指向额外 [文件](https://github.com/decentraland/docs/blob/main/contributor/filesystem.md) 实体包中文件的引用数组。 |
| `metadata` | 一个包含此实体类型特定信息的对象。 |
该 `metadata` 字段在每种类型中的结构和值都在各自的页面中详细说明。 `指针` 数组的内容也会因类型而异。
{% hint style="info" %}
旧版实体清单可能包含 `版本` 字段，在以下版本中已弃用： [ADR-45](https://adr.decentraland.org/adr/ADR-45)。你可以放心忽略它，因为 `时间戳` 字段现在用于版本控制。
{% endhint %}
这是一个描述实体的典型 JSON 清单：
```json
{
"type": "wearable",
"pointers": ["urn:decentraland:matic:collections-v2:0xbdf21eaf54ebf4a6cadc2dcb371df7afce98bc1d:0"],
"timestamp": 1628181913506,
"content": [
// ……文件引用，见下文
],
"metadata": {
// ……此实体类型的特定字段，见相关页面
}
}
```
你可以在以下位置找到这些 JSON 结构以及 Decentraland 协议中其他对象的模式： [通用模式](https://github.com/decentraland/common-schemas) 仓库。
{% hint style="info" %}
在查看实体清单时，你可能会发现未文档化的字段。这是因为实体模式允许额外的自定义属性，可由所有者自由设置。
{% endhint %}
### 文件
如上所述，所有实体至少都有一个关联文件：描述实体本身的 JSON 清单。实体标识符实际上是该 [文件标识符](https://github.com/decentraland/docs/blob/main/contributor/filesystem.md#identifiers) 特殊文件的。
该 `内容` 每个清单中的字段是一个指向额外文件的引用数组。这些通常是资源，例如 3D 模型和动画，或场景脚本。
所有文件都存储在 Decentraland 的 [分布式文件系统](https://github.com/decentraland/docs/blob/main/contributor/filesystem.md)中，数组中的每一项都有两个属性：
| 字段 | 值 |
| ------ | ------------------------------------------------------------------------------------------------------------- |
| `文件` | 此实体中文件相互引用时使用的内部名称。 |
| `hash` | 该文件的全局 [标识符](https://github.com/decentraland/docs/blob/main/contributor/filesystem.md#identifiers)，在所有内容中都唯一。 |
它在 `内容` 字段中通常看起来是这样的：
```json
[
{
"file": "thumbnail.png",
"hash": "bafkreiglecvpnqibvf6pltcnid5nhbx3caj77lu4ia4xitpmp3lrcouuhm",
},
{
"file": "model.glb",
"hash": "bafkreic2i3awiu7srhatf3k47l3c5lmadisznjigppor2a35saosjfbo25",
},
// ……更多文件
]
```
{% hint style="info" %}
该 `文件` 字段值始终采用小写，以避免在不同操作系统中构建实体时出现问题，因为文件名大小写可能很重要。
{% endhint %}
文件的生命周期取决于包含它的实体。对于活动实体（即尚未被其所有者替换的实体），协议要求内容服务器保留所有关联文件。如果实体被删除，文件可以由服务器自行决定保留或丢弃。
### 所有权与认证
为了证明所有权并授权围绕实体的操作， [认证链](https://github.com/decentraland/docs/blob/main/auth/authchain.md) 会使用该机制。
该 [`decentraland-crypto`](https://github.com/decentraland/decentraland-crypto) 仓库包含所有加密流程的实现。
### 发现和下载实体
内容服务器可用于通过 [指针](https://github.com/decentraland/docs/blob/main/contributor/pointers.md)定位实体，并下载其清单及任何额外文件。
* 要将指针解析为实体 ID，可以使用 [`/entities/active`](https://decentraland.github.io/catalyst-api-specs/#tag/Content-Server/operation/getListOfEntities) 端点为你提供所有已知收藏集的列表。
* 使用实体 ID，你可以通过以下方式下载清单： [`/contents/`](https://decentraland.github.io/catalyst-api-specs/#tag/Content-Server/operation/getContentFile) 端点为你提供所有已知收藏集的列表。
* 要获取某一类型的所有活动实体，首先下载一个 [快照](https://github.com/decentraland/docs/blob/main/contributor/snapshots.md).
请查看 [练习](https://github.com/decentraland/docs/blob/main/contributor/practice.md) 部分以获取示例和指南。
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.decentraland.org/contributor/contributor-zh/nei-rong/entities.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.