> 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/shi-ti-lei-xing/scenes.md).

# 场景

场景是 [实体](https://github.com/decentraland/docs/tree/main/contributor/entities/README.md) 这些实体会在 Decentraland 的不同部分产生行为。它们可以跨越多个土地地块，而穿过它们的玩家在 World Explorer 中会执行场景提供的特殊代码。

你可以在以下位置找到一个完整的真实示例： [此场景的清单](https://peer.decentraland.org/content/contents/bafkreidihplrc5cxarjkji2enmzhicpjoa2vrlqyyffnholmxb3o2xft3u) 在 Foundation 的内容服务器上。

### 指针 <a href="#pointers" id="pointers"></a>

场景有一个或多个关联的 [指针](https://github.com/decentraland/docs/tree/main/contributor/pointers/README.md) ，其形式为地块坐标字符串，例如 `"0,0"`。运行该场景的每个地块都会列在 [`指针` 数组](https://github.com/decentraland/docs/tree/main/contributor/entities/README.md#properties) 中，并且内容服务器会将所有这些指针解析到该场景。

换句话说，你可以选择某个地块的 x/y 坐标，并通过向内容服务器查询 `"<x>,<y>"` 指针来定位正在运行的场景。这是 World Explorer 在玩家浏览世界时决定是否启用场景行为的方式。

一个典型的 `指针` 数组如下：

```json
{
  "pointers": [
    "-113,-134",
    "-113,-133",
    "-113,-132",
  ],
  // ... 其他实体属性
}
```

这些数据也可在 `metadata.scene.parcels` 字段中找到，下面会详细说明，以防你只想在 manifest 中保存该场景专属对象。

### 元数据字段

有几个特殊属性适用于 [实体](https://github.com/decentraland/docs/tree/main/contributor/entities/README.md) 类型为 `场景` 位于 `metadata` 顶层字段中。

| 字段                    | 值                                                                                                                      |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `owner`               | 有关场景维护者的信息。                                                                                                            |
| `main`                | 该 [内部文件名](https://github.com/decentraland/docs/tree/main/contributor/entities/README.md#files) ，指向该场景的主 JavaScript 文件。 |
| `tags`                | 一个描述该场景的字符串标签数组。                                                                                                       |
| `display`             | 有关该场景的信息，供 Explorer 向玩家展示（见下文）。                                                                                        |
| `场景`                  | 该场景处于激活状态的地块及其中心位置（见下文）。                                                                                               |
| `contact`             | 用于联系场景创建者或维护者的姓名和电子邮件地址（见下文）。                                                                                          |
| `spawnPoints`         | 玩家进入该场景时的位置和摄像机角度（见下文）。                                                                                                |
| `requiredPermissions` | 建议 Explorer 向玩家请求的权限（见下文）。                                                                                             |
| `featureToggles`      | 功能开关设置                                                                                                                 |

{% hint style="info" %}
请记住，实体及其元数据可以包含自定义字段。你可能会在其他地方发现一些此处未列出的属性。
{% endhint %}

#### 显示

在 `metadata.display`，你会找到一些在玩家进入场景前向他们介绍场景时很有用的属性。

| 字段                | 值                                                                                                                              |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `title`           | 该场景的显示名称。                                                                                                                      |
| `description`     | 该场景的详细描述。                                                                                                                      |
| `favicon`         | *已弃用* 该 [内部文件名](https://github.com/decentraland/docs/tree/main/contributor/entities/README.md#files) 指向一个图标，该图标会在此场景处于激活状态时显示。 |
| `navmapThumbnail` | 该 [内部文件名](https://github.com/decentraland/docs/tree/main/contributor/entities/README.md#files) 指向该场景用于世界地图的缩略图。                |

示例：

```json
{
  "title": "my_cool_scene",
  "favicon": "favicon.png",
  "navmapThumbnail": "thumbnail.png"
}
```

#### 场景

该 `metadata.scene` 属性是一个对象，用于描述该场景在世界地图中的位置。

| 字段        | 值             |
| --------- | ------------- |
| `parcels` | 运行此场景的地块指针数组。 |
| `base`    | 该场景原点的地块指针。   |

实际中看起来像这样：

```json
{
  "parcels": [
    "17,-112", 
    "17,-113"
  ],
  "base": "17,-112"
}
```

该 `base` 字段始终包含在 `parcels` 数组中。

#### 联系

该 `metadata.contact` 对象包含场景所有者或维护者的联系信息。

| 字段      | 值                |
| ------- | ---------------- |
| `name`  | 此联系人的姓名。         |
| `email` | （可选）用于联系的电子邮件地址。 |

在 JSON 中：

```json
{
  "name": "cool_scene_maker",
  "email": "hello@decentraland.org"
}
```

虽然 `name` 字段在每个场景中都会填入，但你会发现实际中 `email` 字段往往是空字符串。这是场景创建者出于隐私做出的选择。

#### 出生点

该 `metadata.spawnPoints` 字段定义了一个点和摄像机方向数组，用于决定进入场景的玩家应出现在哪里，以及最初应朝向哪里。必须至少定义一个出生点。

数组中的每一项都有若干属性：

| 字段             | 值                                 |
| -------------- | --------------------------------- |
| `name`         | 用于标识此出生点的标签。                      |
| `位置`           | 在一个 `{ x, y, z }` 带浮点坐标的对象中的起始位置。 |
| `cameraTarget` | 在一个 `{ x, y, z }` 带浮点坐标的对象中的起始位置。 |
| `default`      | 除非另有指定，否则是否使用此出生点。                |

例如：

```json
[
  {
    "name": "spawn1",
    "position": { "x": 10.02, "y": 5.27, "z": 15.23  },
    "cameraTarget": { "x": 10.02, "y": 6.27, "z": 31.23 },
    "default": true
  }
]
```

{% hint style="info" %}
**📔 注意**：可以使用 Creator Hub 设置出生区域和摄像机目标。更多信息请访问 [Spawn Area](https://github.com/decentraland/docs/tree/main/creator/scene-editor/build/spawn-areas.md) 文档。
{% endhint %}

#### 所需权限 <a href="#permissions" id="permissions"></a>

在 `metadata.requiredPermissions` 你会找到一个由众所周知的字符串组成的数组，用于声明在 World Explorer 允许某些操作之前应向玩家请求哪些权限。这取决于 Explorer；其他为不同目的构建的客户端可以选择忽略它。

以下是当前支持的权限集：

| 权限                                  | 目的                           |
| ----------------------------------- | ---------------------------- |
| `USE_FETCH`                         | 允许场景发起外部 HTTP 请求。            |
| `USE_WEBSOCKET`                     | 允许场景使用 WebSocket API 建立外部连接。 |
| `OPEN_EXTERNAL_LINK`                | 允许场景打开一个 URL（在浏览器标签页或网页视图中）。 |
| `USE_WEB3_API`                      | 允许场景与钱包通信。                   |
| `ALLOW_TO_TRIGGER_AVATAR_EMOTE`     | 允许场景用表情动作让玩家的头像动起来。          |
| `ALLOW_TO_MOVE_PLAYER_INSIDE_SCENE` | 允许场景改变玩家的位置。                 |

#### 功能开关

该 `metadata.featureToggles` 字段允许场景指示 World Explorer 的某些功能应启用还是禁用。

该字段包含一个如下形式的对象 `{ [featureName]: 'enabled' | 'disabled' }`，例如：

```json
{
  "voiceChat": "enabled"
}
```

目前， `voiceChat` 是唯一常见支持的功能标志。


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/contributor/contributor-zh/nei-rong/shi-ti-lei-xing/scenes.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.