> 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)下面将详细说明，所有组件的状态都使用协议缓冲区进行序列化。你可以点击每个标题中的链接查看完整定义。

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

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

***

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

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

该组件在场景生命周期中无疑是使用最频繁、更新最频繁的组件。因此， `变换` 不会使用协议缓冲区进行序列化，而是打包进自定义结构中。

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

```
.-----------------------.-------------------------------.-----------------------.-----------------.
|   x   |   y   |   z   |   x   |   y   |   z   |   w   |   x   |   y   |   z   | parent (uint32) |
'-----------------------'-------------------------------'-----------------------'-----------------'
╵  位置 (3x float)  ╵      旋转 (4x float)      ╵   缩放 (3x float)    ╵

```

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

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

该 `parent` 字段表示该实体应相对于另一个实体定位，后者由其 ID 标识。

由于 `parent` 的空值也是 [`根实体`](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)

根据其 `变换`.

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

***

**`可见性`** [**↗ 源码**](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)

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

它附加到 [`摄像机实体`](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)

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

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

***

**`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)

播放随场景打包的音频片段，给定 [其清单中的文件路径](https://github.com/decentraland/docs/tree/main/contributor/content/entities/README.md#files).

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

{% hint style="info" %}
为了为未来升级做准备， `AudioSource` 中的字段被称为 `audio_clip_url`，但在当前协议版本中它实际上是清单中定义的路径。
{% 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) 组件，并通过 `parent` 属性相互关联。

例如，一个浮动的选项窗口可以是一个带有 [`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 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/chang-jing-yun-xing-shi/basic-components.md?ask=<question>&goal=<endgoal>
```

`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.