> 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/tong-xin/messages.md).

# 消息

通信中的消息是二进制数据 *数据包*，使用以下方式序列化 [协议缓冲区](https://github.com/protocolbuffers/protobuf)。它们承载文本和语音聊天、位置更新、个人资料变更以及其他实时交互。

{% hint style="info" %}
你可以看到 comms 协议的实际运行，并使用开源的 [Comms Station](https://decentraland.github.io/comms-station/).
{% endhint %}

所有消息定义都可在 [协议仓库](https://github.com/decentraland/protocol)中找到，并且下面的每种消息类型都有其声明链接。

**`数据包`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/c48ea0aa00d8173084571552463a6a05a7f49636/proto/decentraland/kernel/comms/rfc4/comms.proto#L8)

该 `数据包` 结构是所有消息的容器。

| 字段        | 类型   | 值                                                                                                                                                     |
| --------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `message` | `枚举` | <p>以下之一： <code>聊天</code>, <code>语音</code>, <code>位置</code>, <code>公告个人资料版本</code>,<br><code>个人资料请求</code>, <code>个人资料响应</code>，或 <code>场景</code>.</p> |

### 文本和语音聊天

客户端通过向所有已连接的同伴（通常是同一岛屿中的玩家）广播文本消息和音频片段来聊天。

只涉及两种 `数据包` 类型：每种用例各一种。在典型情况下，客户端会将这些消息广播给其岛屿中的其他所有客户端，也就是它们可以交互的附近玩家群组。

***

**`聊天`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/c48ea0aa00d8173084571552463a6a05a7f49636/proto/decentraland/kernel/comms/rfc4/comms.proto#L56)

向其他客户端发送文本聊天消息。

| 字段        | 类型       | 值            |
| --------- | -------- | ------------ |
| `message` | `字符串`    | 消息文本         |
| `时间戳`     | `双精度浮点数` | 发送者的 UTC 时间戳 |

***

**`语音`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/c48ea0aa00d8173084571552463a6a05a7f49636/proto/decentraland/kernel/comms/rfc4/comms.proto#L66)

向其他客户端发送已编码的语音样本。

| 字段                | 类型         | 值                         |
| ----------------- | ---------- | ------------------------- |
| `encoded_samples` | `字节`       | 已编码音频数据                   |
| `codec`           | `枚举`       | 仅 `VC_OPUS` （目前不支持其他编解码器） |
| `index`           | `无符号32位整数` | 由发送者设置的递增计数器              |

该 `codec` 字段是一个 `枚举` 值。不支持自定义编解码器。

### 移动

控制头像的客户端会在其岛屿内发送和接收位置更新，以同步玩家之间的移动和姿态。

***

**`位置`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/c48ea0aa00d8173084571552463a6a05a7f49636/proto/decentraland/kernel/comms/rfc4/comms.proto#L20)

向其他客户端更新头像的位置和朝向。

| 字段                                                                                                                  | 类型         | 值            |
| ------------------------------------------------------------------------------------------------------------------- | ---------- | ------------ |
| <p><code>position\_x</code><br><code>position\_y</code><br><code>position\_z</code></p>                             | `浮点数`      | 世界地图中的头像位置   |
| <p><code>rotation\_x</code><br><code>rotation\_y</code><br><code>rotation\_z</code><br><code>rotation\_w</code></p> | `浮点数`      | 头像旋转四元数      |
| `index`                                                                                                             | `无符号32位整数` | 由发送者设置的递增计数器 |

客户端通常会发送 `位置` 低频率更新（例如每 1 或 2 秒一次），并在移动或交互时切换到高频率（每秒数次）。

{% hint style="info" %}
发送位置更新时，速度通常比可靠性更重要。只要传递更快，感知性能就会更好，即使 `位置` 消息偶尔被丢弃或乱序。某些传输方式（例如 [LiveKit](https://github.com/decentraland/docs/blob/main/contributor/communications/transport-types/livekit/README.md)）可以按每条消息在快速模式和可靠模式之间切换。
{% endhint %}

建议使用低频广播作为一种简单方案，把更新传递给那些暂时失去连接，或在加入岛屿时未能接收到消息的客户端。

该 `index` 字段是一个递增计数器，由发送者设置，以便接收者对乱序到达的更新进行排序。

### 资料共享

岛屿内的客户端可以请求其他玩家的头像信息，以便渲染他们的头像、显示他们的名字和图片等。

由于资料变更很少见（例如与位置更新相比），因此该系统旨在简化本地资料缓存的维护任务，并且只在需要时获取资料。

有 3 [`数据包`](#Packet) 种相关类型：一个 [`个人资料请求`](#ProfileRequest)/[`个人资料响应`](#ProfileResponse) 由客户端按需共享资料的一对，以及 [`公告个人资料版本`](#AnnounceProfileVersion) 用于告诉同伴最新版本是什么的消息，这样他们就可以决定是否请求它。

客户端通常会定期广播 `公告个人资料版本` 消息，并在资料变更时立即广播。

{% @mermaid/diagram content="sequenceDiagram
participant Client1 as Client 1
participant Client2 as Client 2
participant Client3 as Client 3

```
Note over Client1: Broadcast profile version
Client1->>Client1: AnnounceProfileVersion(v1)
Client1->>Client1: AnnounceProfileVersion(v1)

Note over Client3: Request profile
Client3->>Client1: ProfileRequest(@client 1)
Client1->>Client3: ProfileResponse(v1)

Client1->>Client1: AnnounceProfileVersion(v1)

Note over Client1: Profile updated
Client1->>Client1: AnnounceProfileVersion(v2)

Note over Client2,Client3: Multiple clients request
Client2->>Client1: ProfileRequest(@client 1)
Client3->>Client1: ProfileRequest(@client 1)
Client1->>Client2: ProfileResponse(v2)
Client1->>Client3: ProfileResponse(v2)" %}
```

***

**`公告个人资料版本`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/c48ea0aa00d8173084571552463a6a05a7f49636/proto/decentraland/kernel/comms/rfc4/comms.proto#L34)

向其他客户端发出信号，表明有一个 [资料实体](https://github.com/decentraland/docs/blob/main/contributor/content/entity-types/profiles/README.md) 可供请求。

| 字段                | 类型         | 值             |
| ----------------- | ---------- | ------------- |
| `profile_version` | `无符号32位整数` | 每次修改都会递增的版本号。 |

缓存资料的接收者可以使用该 `profile_version` 编号来判断其本地副本是否是最新的，或者是否需要发送一个 [`个人资料请求`](#ProfileRequest).

***

**`个人资料请求`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/c48ea0aa00d8173084571552463a6a05a7f49636/proto/decentraland/kernel/comms/rfc4/comms.proto#L41)

从指定的对等方请求特定版本的资料。

| 字段                | 类型         | 值        |
| ----------------- | ---------- | -------- |
| `address`         | 字符串        | 资料的标识地址。 |
| `profile_version` | `无符号32位整数` | 所需的资料版本。 |

接收者可以回复 [`个人资料响应`](#ProfileResponse) 消息来提供所请求的资料。

***

**`个人资料响应`** [**↗ 源码**](https://github.com/decentraland/protocol/blob/c48ea0aa00d8173084571552463a6a05a7f49636/proto/decentraland/kernel/comms/rfc4/comms.proto#L46)

作为对以下内容的响应发送资料： [`个人资料请求`](#ProfileRequest).

| 字段                   | 类型         | 值                     |
| -------------------- | ---------- | --------------------- |
| `serialized_profile` | 字符串        | 以 JSON 序列化的资料实体。      |
| `base_url`           | `无符号32位整数` | 文件系统端点的基础 URL，由发送者建议。 |

该 `serialized_profile` 字段包含一个 [资料实体](https://github.com/decentraland/docs/blob/main/contributor/content/entity-types/profiles/README.md).

如果发送者希望推荐一个内容服务器，用于下载其资料中引用的实体（例如可穿戴物品），则可以将 `base_url` 字段设为提示。客户端可以自由使用或忽略此 URL。


---

# 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/tong-xin/messages.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.