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

# 消息

comms 中的消息是二进制数据 *数据包*，使用 [Protocol Buffers](https://github.com/protocolbuffers/protobuf)。它们承载文本和语音聊天、位置更新、资料变更以及其他实时交互。

{% hint style="info" %}
你可以通过开源的 [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)

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

| 字段   | 类型   | 值                                                                                                                                                                                   |
| ---- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `消息` | `枚举` | <p>以下之一 <code>聊天</code>, <code>语音</code>, <code>位置</code>, <code>AnnounceProfileVersion</code>,<br><code>ProfileRequest</code>, <code>ProfileResponse</code>，或 <code>场景</code>.</p> |

### 文本和语音聊天

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

仅有两种 `数据包` 类型参与，每个用例对应一种。在典型情况下，客户端会将这些消息广播给岛内的所有其他客户端，也就是他们可以交互的附近玩家组。

***

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

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

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

***

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

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

| 字段                | 类型       | 值                         |
| ----------------- | -------- | ------------------------- |
| `encoded_samples` | `字节`     | 编码后的音频数据                  |
| `编解码器`            | `枚举`     | 仅 `VC_OPUS` （目前不支持其他编解码器） |
| `索引`              | `uint32` | 由发送者设置的递增计数器              |

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

### 移动

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

***

**`位置`** [**↗ 源码**](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> | `浮点数`    | 头像旋转四元数      |
| `索引`                                                                                                                | `uint32` | 由发送者设置的递增计数器 |

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

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

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

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

### 资料共享

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

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

有 3 个 [`数据包`](#Packet) 涉及的类型：一个 [`ProfileRequest`](#ProfileRequest)/[`ProfileResponse`](#ProfileResponse) 客户端用于按需共享资料的一对，以及 [`AnnounceProfileVersion`](#AnnounceProfileVersion) 用于告知对等方最新版本的消息，以便它们决定是否请求。

客户端通常广播 `AnnounceProfileVersion` 消息，并在资料变更时立即广播。

```mermaid
序列图
    participant Client1 as 客户端1
    participant Client2 as 客户端2
    participant Client3 as 客户端3
    
    Note over Client1: 广播资料版本
    Client1->>Client1: AnnounceProfileVersion(v1)
    Client1->>Client1: AnnounceProfileVersion(v1)
    
    Note over Client3: 请求资料
    Client3->>Client1: ProfileRequest(@client 1)
    Client1->>Client3: ProfileResponse(v1)
    
    Client1->>Client1: AnnounceProfileVersion(v1)
    
    Note over Client1: 资料已更新
    Client1->>Client1: AnnounceProfileVersion(v2)
    
    Note over Client2,Client3: 多个客户端请求
    Client2->>Client1: ProfileRequest(@client 1)
    Client3->>Client1: ProfileRequest(@client 1)
    Client1->>Client2: ProfileResponse(v2)
    Client1->>Client3: ProfileResponse(v2)
```

***

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

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

| 字段                | 类型       | 值             |
| ----------------- | -------- | ------------- |
| `profile_version` | `uint32` | 每次修改都会递增的版本号。 |

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

***

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

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

| 字段                | 类型       | 值        |
| ----------------- | -------- | -------- |
| `地址`              | 字符串      | 资料的标识地址。 |
| `profile_version` | `uint32` | 所需的资料版本。 |

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

***

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

作为对一条 [`ProfileRequest`](#ProfileRequest).

| 字段                   | 类型       | 值                   |
| -------------------- | -------- | ------------------- |
| `serialized_profile` | 字符串      | 以 JSON 序列化的资料实体。    |
| `base_url`           | `uint32` | 发送者推荐的文件系统端点基础 URL。 |

该 `serialized_profile` 字段包含一个……的 JSON 序列化 [资料实体](https://github.com/decentraland/docs/tree/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 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/tong-xin/messages.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.