> 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/chang-jing-yun-xing-shi/basic-components.md).

# 基础组件

World Explorer 支持一组基础组件，这些组件与场景共享定义，并内置支持定位、动画、媒体、世界状态查询

共有五种组件：

1. [对象组件](#object) 为实体添加视觉和物理属性。
2. [游戏组件](#game) 可以向游戏引擎请求动作并接收信息。
3. [媒体组件](#media) 可以显示图像并播放声音。
4. [区域组件](#area) 更改特定区域内实体的行为。
5. [UI 组件](#ui) 允许场景渲染浮动界面。

除 [`变换`](#Transform)，如下文详细说明，所有组件的状态都使用 protocol buffers 进行序列化。你可以点击每个标题中的链接查看完整定义。

### 对象组件 <a href="#object" id="object"></a>

最常见的组件是那些为实体附加视觉和物理属性的组件。它们可用于对游戏中的对象进行定位、调整大小、上色，并添加碰撞。

***

**`变换`** [**↗ 规范**](https://adr.decentraland.org/adr/ADR-153)

为实体添加位置、旋转和缩放。

在场景生命周期中，这个组件远远是最常用且更新最频繁的。因此， `变换` 不使用 protocol buffers 进行序列化，而是打包到自定义结构中。

`变换` 大小为 `44` 字节，布局如下：

```
.-----------------------.-------------------------------.-----------------------.-----------------.
|   x   |   y   |   z   |   x   |   y   |   z   |   w   |   x   |   y   |   z   | 父级 (uint32) |
'-----------------------'-------------------------------'-----------------------'-----------------'
╵  位置（3 个 float）  ╵      旋转（4 个 float）      ╵   缩放（3 个 float）    ╵

```

这种方法使运行时（尤其在底层代码环境中）能够避免中间的序列化和反序列化步骤。某个对象所在的内存 `变换` 可以被复制、共享并直接指向。

坐标可以是小数，因此使用 4 字节浮点数。

该 `父级` 字段表示该实体应相对于另一个通过其 ID 标识的实体定位。

由于 `父级` 的空值也是 [`RootEntity`](https://github.com/decentraland/docs/tree/main/contributor/runtime/entities/README.md#RootEntity) ID（`0`），任何 `变换` 默认都相对于它。

按照协议， `变换` 必须以大端字节序序列化。

***

**`MeshRenderer`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/mesh_renderer.proto#L7)

为实体提供基本渲染行为。

它可以设置为渲染平面、球体、立方体或圆柱体。要渲染任意 3D 形状，请使用 [`GltfContainer`](#GltfContainer).

***

**`MeshCollider`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/mesh_collider.proto#L15)

为实体提供基本碰撞行为和鼠标指针检测。

它可以设置为表现得像平面、球体、立方体或圆柱体。若要使用自定义碰撞网格，请使用 [`GltfContainer`](#GltfContainer).

***

**`Material`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/material.proto#L19)

设置同时具有以下组件的实体的纹理、光照、颜色和透明度属性： [`MeshRenderer`](#MeshRenderer) 组件。

它是一个用于涵盖所有常见情况的复杂结构，但每个字段都有合理的默认值，并且可以留空。

若要完全自定义实体的视觉属性，请使用 [`GltfContainer`](#GltfContainer).

***

**`GltfContainer`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/gltf_container.proto#L7)

根据以下内容将 3D 模型附加到此实体： [文件路径](https://github.com/decentraland/docs/tree/main/contributor/content/entities/README.md#files) 的 `.gltf` 场景清单中的资源。

由于模型有自己的网格和材质，此组件会覆盖来自以下组件的任何行为： [`MeshRenderer`](#MeshRenderer), [`MeshCollider`](#MeshCollider) 和 [`Material`](#Material).

***

**`Billboard`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/billboard.proto#L17)

使实体自动重新调整其 `变换` 朝向摄像机，或者可选地朝向通过以下方式引用的另一个实体： `target_entity`。顾名思义，它用于显示游戏内广告牌，并且经常与以下组件组合使用： [`TextShape`](#TextShape).

默认情况下它会影响所有方向，但可以设置为仅绕一个轴旋转。如果引用的目标实体不存在，则会暂停重新朝向，直到它出现。

***

**`Animator`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/animator.proto#L7)

定义一个或多个可同时应用于实体的动画。

场景可以设置组件状态来自定义、播放和切换动画，也可以读取它以检查哪些动画可用或当前正在播放。

***

**`AvatarAttach`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/avatar_attach.proto#L16)

表示实体的位置必须跟随虚拟形象身体中的特定锚点。

通过设置用户 ID，它可以影响任何虚拟形象，而不仅仅是玩家的虚拟形象。

***

**`TextShape`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/text_shape.proto#L11)

根据其以下内容，在实体位置上渲染文本： `变换`.

它具有高度可配置性，支持大小、边距、内边距、颜色、阴影等参数。

***

**`Visibility`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/visibility_component.proto#L7)

设置实体是可见（默认）还是不可见。

不可见对象仍然存在，并会表现出任何其他已附加组件的行为。

***

**`AvatarShape`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/avatar_shape.proto#L8)

包含有关玩家虚拟形象的信息，包括其身体形状、颜色、穿戴物和过渡状态。

此组件附加到以下内容中的实体： [虚拟形象场景](https://github.com/decentraland/docs/tree/main/contributor/runtime/execution/README.md#avatarScene).

### 游戏组件 <a href="#game" id="game"></a>

场景和运行时可以使用一些基础组件来交换信息。它们利用 [ECS 同步机制](https://github.com/decentraland/docs/tree/main/contributor/runtime/modules/engine_api/README.md#synchronization) 来保证任何状态更改或事件的一致性和顺序。

***

**`CameraMode`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/camera_mode.proto#L8)

可用于确定玩家是第一人称还是第三人称视角。

***

**`PointerLock`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/pointer_lock.proto#L7)

可用于确定鼠标指针是否自动跟随摄像机的焦点（锁定），或可以在屏幕上自由移动（解锁）。

它附加到 [`CameraEntity`](https://github.com/decentraland/docs/tree/main/contributor/runtime/entities/README.md#CameraEntity)，其状态可以从场景中读取（但不能写入）。

***

**`PointerEvents`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/pointer_events.proto#L17)

当指针点击或悬停在实体上时显示视觉反馈。

***

**`PointerEventsResult`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/pointer_events_result.proto#L13)

包含玩家最近输入的信息，包括按键和指针操作。

它附加到 `RootEntity`，并由运行时在每一帧使用任何新事件更新。

***

**`Raycast`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/raycast.proto#L15)

可附加到实体上，以向游戏引擎请求一次射线投射。 `RaycastResult` 组件稍后将附加到同一实体。

可以配置射线的起点、方向和最大长度。

***

**`RaycastResult`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/raycast_result.proto#L9)

由运行时附加到具有 [`Raycast`](#Raycast) 组件且结果待返回的实体。

它包含原始射线的信息，并标识任何被击中的实体。

### 媒体组件 <a href="#media" id="media"></a>

场景可以附加特殊组件来显示图像、展示视频或播放声音。

***

**`AudioSource`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/audio_source.proto#L7)

根据以下内容播放随场景捆绑的音频片段： [其 manifest 中的文件路径](https://github.com/decentraland/docs/tree/main/contributor/content/entities/README.md#files).

声音源自关联实体的位置。可以设置其音高、音量和循环行为，并且可以读取音频播放器的状态。

{% hint style="info" %}
为未来升级做准备， `AudioSource` 称为 `audio_clip_url`，但在当前协议版本中，它实际上是 manifest 中定义的路径。
{% endhint %}

***

**`AudioStream`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/audio_stream.proto#L7)

类似于 [AudioSource](#AudioSource)，但音频会从外部 URL 实时流式传输。

尽管附加到特定实体上，声音不会受到其位置的影响。可以设置音量，并读取音频播放器的状态。

***

**`NftShape`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/nft_shape.proto#L36)

显示与图像或视频资源关联的 NFT。

它渲染一个带可配置装饰边框的 2D 画布。

### 区域组件

这些组件允许场景修改指定范围内实体的默认行为。

***

**`AvatarModifierArea`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/avatar_modifier_area.proto#L15)

更改以实体为中心的空间内虚拟形象的行为。

它使用 3D 尺寸向量定义，可以影响虚拟形象是否可见或可点击。可以根据用户 ID 将特定虚拟形象排除在此效果之外。

***

**`CameraModeArea`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/camera_mode_area.proto#L11)

更改以实体为中心的空间内的摄像机模式（第一人称或第三人称）。

它使用 3D 尺寸向量和所需的摄像机模式定义。

### UI 组件 <a href="#ui" id="ui"></a>

以下组件用于创建悬浮在游戏世界之上的图形界面。

它们通常附加到具有层级 [`UiTransform`](#UiTransform) 组件的实体集合上，这些实体通过 `父级` 属性。

例如，一个浮动选项窗口可以是一个具有 [`UiTransform`](#UiTransform) 和一个 [`UiBackground`](#UiBackground) 组件的实体，再加上一个带有子级 [`UiTransform`](#UiTransform) 和一个 [`UiDropdown`](#UiDropdown).

***

**`UiTransform`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/ui_transform.proto#L77)

描述 UI 组件的大小、定位、外边距和内边距。

它基于 flexbox 模型，并且高度可定制。

***

**`UiBackground`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/ui_background.proto#L11)

描述用于 UI 实体背景的颜色或纹理。

***

**`UiDropdown`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/ui_dropdown.proto#L11)

定义一组互斥选项列表，用于在下拉控件中显示。

***

**`UiDropdownResult`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/ui_dropdown_result.proto#L9)

包含来自以下组件的所选值： [`UiDropdown`](#UiDropdown)，由运行时设置并由场景读取。

***

**`UiInput`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/ui_input.proto#L11)

定义一个文本输入控件，并留有一定的自定义余地。

***

**`UiInputResult`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/ui_input_result.proto#L9)

包含以下组件的文本值： [`UiInput`](#UiInput)，由运行时设置并由场景读取。

***

**`UiText`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/ui_text.proto#L11)

定义一个简单的文本视图，并留有一定的自定义余地。

***


---

# 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/chang-jing-yun-xing-shi/basic-components.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.