> 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/creator/content-creator-zh/chang-jing-sdk7/lian-wang/authoritative-servers.md).

# 多人服务器

使用无头多人服务器构建多人 Decentraland 场景。

**📔 注意**：多人游戏服务器（Multiplayer Server）以前称为 **权威服务器（Authoritative Server）**。名称虽然变了，但功能保持不变。要安装的 SDK 分支仍名为 `auth-server`，请参阅 [设置](#setup).

## 概览

Decentraland 会在玩家的设备上本地运行场景。默认情况下，玩家可以看到彼此并直接互动，但每位玩家都是独立地与环境互动。默认情况下，环境中的变化不会在玩家之间共享。

让所有玩家看到内容相同、状态一致的场景，对于玩家进行更有意义的互动至关重要。如果没有这一点，一位玩家打开门走进房子时，其他玩家看到的门仍然是关着的，而在他们看来，这位玩家就像直接穿过了关闭的门。

该 **多人服务器** 是一个无头服务器进程，用于运行场景代码、验证状态变更，并将结果广播给所有已连接的玩家。它采用权威服务器架构：服务器是唯一可信的数据来源，而不是依赖每个客户端上报自己的操作。这使其成为同步多人场景的推荐方案。

多人服务器非常适合重视游戏机制公平性的场景，因为你可以在服务器端实现复杂的反作弊验证。你也可以将私钥和其他敏感信息存储在服务器上，避免将其直接暴露给用户。

多人服务器还能解决一个实际问题：在点对点架构中，两名玩家同时控制某个对象（例如浮动平台）时，可能会产生相互冲突的结果。每个客户端都将平台设定为不同的高度，却没有任何一方有权决定哪个结果才正确。多人服务器会在同一处处理所有变更，让所有客户端最终保持相同的状态。

它还能为你提供一个位置，用来 **跨会话持久化数据**：排行榜、玩家进度、已解锁的成就，或环境变化（例如打开的门或放置的物品）。玩家再次回来时，世界会保留之前发生的一切。

Decentraland 会为你托管并部署服务器。通过常规流程发布场景时，服务器也会一并无缝发布，无需额外步骤，也无需支付托管费用。

## 设置

### 1. 安装 auth-server SDK 版本

原生多人游戏服务器 API（`isServer`, `registerMessages`, `Storage`, `EnvVar`等）可在单独的 SDK 分支中使用。

**在 Creator Hub 中**，打开场景设置并勾选 **启用多人游戏服务器** 中的 **高级** 部分 **设置** 选项卡。Creator Hub 会安装正确的 SDK，并为你配置 `scene.json` 。请参阅 [场景设置中的多人游戏服务器](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-bian-ji-qi/pei-zhi/scene-settings.md#multiplayer-server).

**在命令行中**，运行以下命令，以便在项目中安装此版本，而不是标准 SDK 分支：

```bash
npm install --save-exact @dcl/sdk@auth-server @dcl/js-runtime@auth-server
```

{% hint style="warning" %}
**📔 注意**：使用 `--save-exact`。否则，npm 会在 `^7.x.y-...` 中 `package.json`保存类似这样的版本范围，而后续常规 SDK 版本也会匹配该范围。之后执行 `npm install` 可能会将 auth-server 构建替换为常规构建，而常规构建不包含服务器 API，导致你的服务器代码无法构建。
{% endhint %}

### 2. 配置 scene.json

通过以下标志启用多人游戏服务器： `"authoritativeMultiplayer": true` 位于 `scene.json`的根级别。无需手动添加：使用 SDK 的 auth-server 分支时，首次构建或预览场景会自动添加该标志。请务必不要将其删除；没有此标志，服务器就不会运行，并且 `isServer()` 始终返回 *false*.

你也可以选择在 `scene.json` 的根级别添加以下内容：

```json
{
  "logsPermissions": ["0xYourWalletAddress"]
}
```

添加 `logsPermissions` ，以便这些钱包在部署后访问服务器日志和指标。在 Creator Hub 中，场景设置里的 **日志访问权限和存储** 列表可为你编辑此字段。世界所有者和符合条件的部署协作者也拥有访问权限，此外，Genesis City 所有者以及场景所在基础地块的 LAND 委托管理者也可访问。有关权限、登录和命令，请参阅 [场景洞察](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/tiao-shi/scene-insights.md) 。

### 3. 运行预览

使用标准预览命令即可，无需额外步骤。使用 SDK 的 auth-server 分支时，预览会自动在后台启动本地版本的多人游戏服务器。

服务器的本地会话与生产环境中的会话并不相连，因此你可以自由测试，不会影响已发布场景中的玩家。

## 服务器端 / 客户端分支控制

项目中 `src` 文件夹里的场景代码会同时在服务器端和客户端运行。使用 `isServer()` 函数来拆分执行路径：

```typescript
import { isServer } from "@dcl/sdk/network"
import { initServer } from "./server/server"
import { initClient } from "./client/setup"
import { setupUi } from "./client/ui"

function main() {
  if (isServer()) {
    // 仅服务器端：游戏逻辑、验证、状态管理
    initServer()
    return
  } else {
    // 仅客户端：UI、输入处理、消息发送
    initClient()
    setupUi()
  }
}
```

服务器以无头模式运行场景，不进行渲染。它可以通过 `PlayerIdentityData` 经验证地访问所有玩家的位置、可穿戴物品和其他数据，并且是游戏状态的唯一权威来源。

## 同步组件与验证

### 将实体同步到所有客户端

使用 `syncEntity` 广播该实体指定组件中的任何更改：

```typescript
import { isServer, syncEntity } from "@dcl/sdk/network"

if (isServer()) {
  syncEntity(
    entity,
    [Transform.componentId, GameState.componentId],
    /* enumId */ 1
  )
}
```

语法与以下内容中使用的语法相同： [无服务器多人游戏](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/lian-wang/serverless-multiplayer.md) 功能，因此将场景从这种架构升级为多人游戏服务器非常简单。使用多人游戏服务器时，状态更新不再在所有玩家之间直接传输，而是统一通过服务器路由和验证。

{% hint style="warning" %}
**📔 注意**：使用多人游戏服务器时，理想的模式是仅让服务器调用 `syncEntity`。这样就不必担心实体 ID 是否一致。实体由服务器实例化并共享，所有客户端都会同步该实例。务必使用 `isServer()`进行保护。这与 [无服务器多人游戏](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/lian-wang/serverless-multiplayer.md)不同，在后者中，每个客户端都会自行调用 `syncEntity` 。
{% endhint %}

### 验证更改

使用 `validateBeforeChange()` 来限制实体特定组件中的状态更新。你可以运行自定义验证函数；只有通过验证后，更改才会生效。

如果验证返回值 *true*，则接受更改并将其同步给所有玩家。如果验证返回值 *false*，则拒绝更改。被拒绝的更改不会传递给其他玩家，并且会在尝试进行更改的玩家一侧回滚。

#### 验证值

最简单的情况是验证要写入的新 *值* 是否在特定范围内。例如，只有当新的 Y 坐标大于 0 时，才接受对 `Transform` 的更改：

```typescript
import { engine, Transform } from "@dcl/sdk/ecs"
import { Vector3 } from "@dcl/sdk/math"
import { isServer } from "@dcl/sdk/network"

const entity = engine.addEntity()
Transform.create(entity, { position: Vector3.create(10, 2, 10) })

if (isServer()) {
  Transform.validateBeforeChange(entity, (value) => {
    // 拒绝所有会将实体放置在 Y = 0 或更低位置的更新
    return value.newValue.position.y > 0
  })
}
```

由于 `validateBeforeChange()` 仅在服务器上有意义，因此务必使用 `isServer()`进行保护。在客户端调用此函数不会产生实际作用。

你可以用它来阻止违反游戏逻辑的更改，例如作为反作弊机制。

#### 验证与玩家的距离

你可以将 `validateBeforeChange()` 与经过服务器验证的玩家位置结合使用，在允许玩家与物体交互前，检查玩家是否足够靠近该物体。例如，当玩家尝试通过更改物体的 `Transform`来拾取物体时，如果物体距离玩家超过 5 米，就可以拒绝此更改：

```typescript
import { engine, Transform, PlayerIdentityData } from "@dcl/sdk/ecs"
import { Vector3 } from "@dcl/sdk/math"
import { isServer } from "@dcl/sdk/network"

const pickableEntity = engine.addEntity()
Transform.create(pickableEntity, { position: Vector3.create(8, 1, 8) })

if (isServer()) {
  Transform.validateBeforeChange(pickableEntity, (value) => {
    // 查找发送此更改的玩家
    for (const [playerEntity, identity] of engine.getEntitiesWith(
      PlayerIdentityData
    )) {
      if (identity.address.toLowerCase() !== value.senderAddress.toLowerCase())
        continue

      const playerTransform = Transform.getOrNull(playerEntity)
      if (!playerTransform) return false

      // 获取更改前对象的当前位置
      const objectTransform = Transform.getOrNull(pickableEntity)
      if (!objectTransform) return false

      const distance = Vector3.distance(
        playerTransform.position,
        objectTransform.position
      )

      // 仅当玩家在 5 米范围内时才允许更改
      return distance <= 5
    }

    // 未在已连接的玩家中找到发送者 — 拒绝
    return false
  })
}
```

这种模式可用作反作弊机制：它可以防止玩家隔空抓取场景中不应与之交互的物体。

#### 仅允许管理员进行更改

你还可以根据 *谁* 发送更改来进行验证。每个传入的值都包含一个 `senderAddress` 字段，其中包含发送者的钱包地址。利用此字段，仅允许特定玩家进行更改。例如，若要仅允许场景管理员修改 `VideoPlayer` 组件：

```typescript
import { engine, VideoPlayer } from "@dcl/sdk/ecs"
import { isServer } from "@dcl/sdk/network"
import { isPreview } from "@dcl/asset-packs/dist/admin-toolkit-ui/fetch-utils"
import { getSceneAdmins } from "@dcl/asset-packs/dist/admin-toolkit-ui/ModerationControl/api"

// 管理员钱包地址缓存，根据场景管理员列表刷新
let adminAddresses = new Set<string>()

async function updateAdminAddresses() {
  if (isPreview()) return
  try {
    const [error, response] = await getSceneAdmins()
    if (error) {
      console.error("[SERVER] Error fetching admin list:", error)
      adminAddresses = new Set()
      return
    }
    adminAddresses = new Set(
      (response ?? []).map((admin) => admin.admin.toLowerCase())
    )
    console.log(
      "[SERVER] Updated admin addresses cache:",
      Array.from(adminAddresses)
    )
  } catch (error) {
    console.error("[SERVER] Error updating admin addresses:", error)
    adminAddresses = new Set()
  }
}

export async function main() {
  const videoEntity = engine.addEntity()
  VideoPlayer.create(videoEntity, { src: "videos/intro.mp4" })

  if (isServer()) {
    // 在设置验证逻辑之前填充缓存
    await updateAdminAddresses()

    VideoPlayer.validateBeforeChange(videoEntity, (value) => {
      // 在预览模式下始终允许更改，以便更轻松地进行本地测试
      if (isPreview()) return true

      const senderAddress = value.senderAddress.toLowerCase()
      if (!adminAddresses.has(senderAddress)) {
        console.log(
          "[SERVER] Unauthorized VideoPlayer change blocked from:",
          senderAddress
        )
        return false
      }
      return true
    })
  }
}
```

参见 [场景管理员](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-bian-ji-qi/shi-shi-yun-ying/scene-admin.md) ，了解玩家如何成为场景管理员。

#### 发送意图，而非结果

只要涉及分数、奖品或共享资源，就应围绕玩家 **想要做什么**来设计客户端消息，而不是围绕结果。客户端发送 `claimPoint` 或 `harvest`，绝不会发送“我的分数现在是 40”。

随后，服务器会检查消息：发送者是谁、游戏是否处于允许该操作的阶段、玩家是否足够接近，以及是否还有可领取的内容。只有通过这些检查后，服务器才会计算新值并写入。游戏状态只能由服务器写入。

如果客户端可以指定自己的分数，它就可以指定任何分数。

#### 只允许服务器进行更改

最严格的做法是只接受源自服务器本身的写入，拒绝客户端发起的任何更改。这是保护必须完全由服务器权威控制的状态的首选模式，例如分数、游戏阶段、生成的实体等。

每个传入值都包含一个 `senderAddress` 字段。发送者为服务器时，此字段与常量 `AUTH_SERVER_PEER_ID`相匹配。该常量由 `@dcl/sdk/network/message-bus-sync`.

导出。下面的示例定义了一个简单的 `protectServerEntity()` 辅助函数，可对指定实体上的一个或多个组件执行此检查。它可以方便地通过一次调用保护多个组件（例如 `Transform` 和 `GltfContainer`）：

```typescript
import { engine, Entity, Transform, GltfContainer } from "@dcl/sdk/ecs"
import { Vector3 } from "@dcl/sdk/math"
import { isServer } from "@dcl/sdk/network"
import { AUTH_SERVER_PEER_ID } from "@dcl/sdk/network/message-bus-sync"

type ComponentWithValidation = {
  validateBeforeChange: (
    entity: Entity,
    cb: (value: { senderAddress: string }) => boolean
  ) => void
}

function protectServerEntity(
  entity: Entity,
  components: ComponentWithValidation[]
) {
  for (const component of components) {
    component.validateBeforeChange(entity, (value) => {
      return value.senderAddress === AUTH_SERVER_PEER_ID
    })
  }
}

if (isServer()) {
  // 创建由服务器管理的实体后：
  const entity = engine.addEntity()
  Transform.create(entity, { position: Vector3.create(10, 5, 10) })
  GltfContainer.create(entity, { src: "assets/model.glb" })
  protectServerEntity(entity, [Transform, GltfContainer])
}
```

{% hint style="warning" %}
**📔 注意**：始终在 `protectServerEntity()` 中调用 `isServer()` 代码块。它会包装 `validateBeforeChange()`，此方法仅在服务器上有意义——在客户端调用会导致错误。
{% endhint %}

#### 自定义组件

你也可以在场景定义的自定义组件上使用 `validateBeforeChange()` 。

```typescript
import { engine, Schemas } from "@dcl/sdk/ecs"
import { isServer } from "@dcl/sdk/network"
import { AUTH_SERVER_PEER_ID } from "@dcl/sdk/network/message-bus-sync"

export const GameState = engine.defineComponent("game:State", {
  phase: Schemas.String,
  score: Schemas.Int,
  timeRemaining: Schemas.Int,
})

// 只有服务器可以修改此组件
if (isServer()) {
  GameState.validateBeforeChange((value) => {
    return value.senderAddress === AUTH_SERVER_PEER_ID
  })
}
```

## 消息

同步组件非常适合存储所有玩家都应持续看到的状态，例如位置、分数或游戏阶段。但并非所有内容都适合这种模式。有时，玩家只需要告诉服务器“我点击了这个按钮”或“我想加入游戏”，而服务器需要回复一次性响应，例如“回合开始了”或“这是你的统计数据”。这些是事件，而不是持续状态。

这正是消息的用途。使用 `registerMessages()` 在客户端与服务器之间进行带类型且经过架构验证的通信。消息采用发送即忘的方式：客户端向服务器发送一条消息，服务器处理后可以选择发送一条消息回来。消息本身不会直接创建任何持久状态。

### 定义消息

在一个由服务器和客户端共同导入的共享文件中定义所有消息。这样，双方就能始终对可用消息及其携带的数据达成一致。每条消息都是一个用于描述其负载的 `Schemas.Map` ：

```typescript
import { Schemas } from "@dcl/sdk/ecs"
import { registerMessages } from "@dcl/sdk/network"

export const Messages = {
  // 客户端 → 服务器
  playerReady: Schemas.Map({ displayName: Schemas.String }),
  playerAction: Schemas.Map({ action: Schemas.String, targetId: Schemas.Int }),
  giveCoins: Schemas.Map({ to: Schemas.String, amount: Schemas.Int }),

  // 服务器 → 客户端
  gameStarted: Schemas.Map({ roundNumber: Schemas.Int }),
  gameEnded: Schemas.Map({ winnerId: Schemas.String }),
}

export const room = registerMessages(Messages)
```

{% hint style="warning" %}
**📔 注意**：在共享模块的顶层调用一次 `registerMessages()` ，如上例所示。这样，模块首次加载时，它就会在服务器和客户端上运行。不要有条件地调用它，也不要在函数内部调用；双方必须始终注册相同的消息。
{% endhint %}

### 发送消息

客户端只能向服务器发送消息，不能直接在客户端之间发送消息。服务器可以向所有客户端广播，也可以按地址向特定玩家发送消息。

```typescript
import { room } from "./shared/messages"

// 客户端 → 服务器（广播，服务器接收）
room.send("playerReady", { displayName: "Alice" })

// 服务器 → 所有客户端
room.send("gameStarted", { roundNumber: 1 })

// 服务器 → 特定客户端（通过钱包地址）
room.send("gameEnded", { winnerId: "Alice" }, { to: [playerAddress] })
```

{% hint style="warning" %}
**📔 注意**：消息的最大大小约为 13 KB。更大的消息会被传输层静默丢弃，不会产生任何错误。请保持载荷较小；如果需要共享更大的数据，请将其拆分为多条消息，或使用同步组件。
{% endhint %}

### 接收消息

```typescript
import { room } from "./shared/messages"

// 客户端接收服务器消息
room.onMessage("gameStarted", (data) => {
  console.log(`Round ${data.roundNumber} started!`)
})

// 服务器接收客户端消息
room.onMessage("playerReady", (data, context) => {
  if (!context) return
  const senderAddress = context.from // 已验证的钱包地址
  console.log(`[Server] ${data.displayName} is ready (${senderAddress})`)
})
```

在服务器上，每条收到的消息都包含一个 `context` 对象，其中包含发送者经验证的钱包地址。请用它来确定是哪位玩家发送了消息（切勿依赖载荷中由发送者自行声明的身份）。

`context.from` 会按网络报告的原样传递，不会更改大小写。请将其转换为小写一次（`context.from.toLowerCase()`），并在所有 map、set 和 Storage 调用中使用该值，以免同一玩家的数据被拆分到两个键中。

### 发送前等待状态同步

客户端应等待场景状态同步完成后再发送第一条消息，以避免加入时发生竞态条件：

```typescript
import { engine } from "@dcl/sdk/ecs"
import { isStateSyncronized } from "@dcl/sdk/network"
import { room } from "./shared/messages"

engine.addSystem(() => {
  if (!isStateSyncronized()) return

  // 现在可以安全地发送消息
  room.send("playerReady", { displayName: "Alice" })
})
```

{% hint style="info" %}
**💡 提示**: `isStateSyncronized()` 只能告知客户端状态是否已同步，不能保证服务器已完成初始化。若要进行更可靠的就绪检查，可让服务器广播“ready”或心跳消息，并让客户端等待该消息后再发送游戏消息。
{% endhint %}

### 可用的 Schema 类型

所有消息载荷和自定义组件都使用 `Schemas` 进行二进制序列化。以下是可用类型的快速参考：

```typescript
import { Schemas } from "@dcl/sdk/ecs"

// 基本类型
Schemas.String // "hello"
Schemas.Int // 42
Schemas.Float // 3.14
Schemas.Boolean // true / false
Schemas.Int64 // Date.now()

// 向量类型
Schemas.Vector3 // { x: 1, y: 2, z: 3 }
Schemas.Quaternion // { x, y, z, w }

// 复杂类型
Schemas.Array(Schemas.String) // ["a", "b", "c"]
Schemas.Entity // 实体引用
Schemas.Optional(Schemas.String) // "hello" 或 undefined
Schemas.Optional(Schemas.Int) // 42 或 undefined

// 嵌套对象
Schemas.Map({
  name: Schemas.String,
  health: Schemas.Int,
  position: Schemas.Vector3,
  playerId: Schemas.Optional(Schemas.String),
})
```

{% hint style="warning" %}
**📔 注意**：Messages *必须* 使用 `Schemas.Map(...)`定义。不能发送普通 JavaScript 对象，否则二进制序列化会失败。
{% endhint %}

## 服务器读取玩家位置

服务器可以读取 **经过验证的** 玩家位置；客户端无法伪造这些位置。这是基于位置的反作弊机制的基础：

```typescript
import { engine, PlayerIdentityData, Transform } from "@dcl/sdk/ecs"

engine.addSystem(() => {
  for (const [entity, identity] of engine.getEntitiesWith(PlayerIdentityData)) {
    const transform = Transform.getOrNull(entity)
    if (!transform) continue

    const address = identity.address
    const position = transform.position
    // 此位置已经过服务器验证——绝不要信任客户端报告的位置
  }
})
```

{% hint style="warning" %}
**📔 注意**：始终使用 `PlayerIdentityData` + `Transform` 在服务器上获取玩家位置。绝不要信任客户端自行报告的值。
{% endhint %}

## 数据存储

在服务器重启后保留数据。存储功能 **仅限服务器使用**，调用时务必使用 `isServer()`进行保护。服务器既可以写入，也可以读取这些数据。

```typescript
import { Storage } from "@dcl/sdk/server"
```

数据可以存储在两个层级：

* **世界**：用于与所有玩家相关的数据，例如排行榜或持久化的环境更改。
* **玩家**：用于特定玩家的数据，例如保存该玩家的进度或偏好设置。

{% hint style="info" %}
**💡 提示**：存储值采用 JSON 格式。你可以直接存储数字、字符串、数组或普通对象，读取时会得到相同类型的值。无需使用 `JSON.stringify()` 或 `JSON.parse()`。有两个例外： `Date` 会以 ISO 文本形式存储（`"2026-10-27T13:05:12.000Z"`），而设为 `undefined` 的对象属性会被丢弃。之前用 `JSON.stringify()` 保存的值是字符串，因此读取时也会得到该字符串。

在本地开发期间，存储数据会写入 `node_modules/@dcl/sdk-commands/.runtime-data/server-storage.json`.
{% endhint %}

{% hint style="warning" %}
**📔 注意**：Storage 调用如何报告问题：

* `Storage.set()` 和 `Storage.player.set()` 会返回一个 **布尔值**. `false` 表示该值 **未能** 持久化，例如发生网络错误，或同时发出的请求过多时（见下文）。务必检查结果：被丢弃的 `false` 意味着保存会悄无声息地丢失。
* `set()` 会抛出 `TypeError` 错误，表示该值无法以原样存储为 JSON： `undefined`, `NaN` 或 `Infinity`、函数、 `Map` 或 `Set`等。若要移除键，请使用 `delete()`.
* `get()` 会返回存储的值；只有当键不存在时，才会返回 `null` 。读取失败时会抛出异常，因此不会把读取失败误认为键不存在。
* 各种 `delete()` 方法在请求失败时会抛出异常。只有当键原本不存在时，它们才会返回 `false` 。
  {% endhint %}

### 在检查点保存，而不是每次状态变化都保存

Storage 用于持久保存必须在服务器重启和重新部署后仍然保留的数据。它不是实时数据存储。请将游戏运行时状态保存在服务器内存中。这样速度更快，也更符合服务器端的正确做法。只有在确有需要时，才在有意义的检查点写入 Storage。

{% hint style="warning" %}
**⚠️ 警告**：服务器运行时最多允许同时进行 **40 个正在处理的主机调用** ，这些调用由 *所有* 场景请求运行时执行的操作共享：每个存储请求、 `signedFetch`以及其他运行时 API 调用都会占用同一限额。超出限额的调用 **不会排队**，而是立即因 `too many concurrent host calls` 错误而被拒绝。SDK 会捕获该拒绝，并将其解析为 `Storage.set` 承诺返回 `false` ，而不是抛出异常。如果代码丢弃了这个布尔值，保存失败就会悄无声息，导致持久化数据过时或丢失。请检查每次写入的结果（参见上面的注释）。
{% endhint %}

适合持久化的时机：

* 游戏结束或一轮结束时。
* 玩家离开时。
* 定期进行防抖保存（例如每 30 秒一次），而不是每帧保存。

只持久化必须在重启或重新部署后保留的数据。其他数据都可以存放在内存中。

下面的示例在内存中维护分数，只在检查点写入，而不是每得一分就写入：

```typescript
import { Storage } from "@dcl/sdk/server"

// 工作状态保存在内存中，每次事件发生时更新
const scores: Record<string, number> = {}

function onPointScored(address: string) {
  scores[address] = (scores[address] ?? 0) + 1
  // 此处不调用 Storage，只更新内存
}

// 仅在检查点持久化，例如玩家离开时
async function onPlayerLeave(address: string) {
  const saved = await Storage.player.set(address, "score", scores[address] ?? 0)
  if (!saved) {
    // 写入未能持久化——保留内存中的值，稍后重试
    console.error(`Failed to save score for ${address}`)
  }
}
```

对于有许多玩家同时在线的场景，更稳健的做法是跟踪哪些键存在尚未保存的更改（即“脏键集合”），并在下一次刷新时重试失败的写入：

```typescript
import { engine } from "@dcl/sdk/ecs"
import { Storage } from "@dcl/sdk/server"

// 工作状态保存在内存中，每次事件发生时更新
const scores: Record<string, number> = {}
const dirty = new Set<string>()

function onPointScored(address: string) {
  scores[address] = (scores[address] ?? 0) + 1
  dirty.add(address) // 标记以便稍后刷新，此处不调用 Storage
}

// 定期刷新脏键（例如每约 30 秒），并在检查点刷新
async function flush() {
  for (const address of dirty) {
    const ok = await Storage.player.set(address, "score", scores[address])
    if (ok) {
      dirty.delete(address) // 保存成功
    }
    // 如果 ok 为 false，该键会继续保持脏状态，并在下次刷新时重试
  }
}

// 使用 dt 累加器通过计时器运行刷新
let flushTimer = 0
engine.addSystem((dt) => {
  flushTimer += dt
  if (flushTimer > 30) {
    flushTimer = 0
    flush()
  }
})
```

### 世界存储——所有玩家共享

```typescript
import { Storage } from "@dcl/sdk/server"

type Entry = { name: string; score: number }

// 写入——如果值未能持久化，set() 会解析为 false
const ok = await Storage.set("leaderboard", [
  { name: "Alice", score: 100 },
  { name: "Bob", score: 85 },
])
if (!ok) {
  console.error("Failed to save leaderboard — retry later")
}

// 读取：键不存在时返回 null
const leaderboard = (await Storage.get<Entry[]>("leaderboard")) ?? []

// 删除
await Storage.delete("leaderboard")
```

你也可以通过命令行管理场景存储，使用 `npx sdk-commands storage scene`:

```bash
# 设置值
npx sdk-commands storage scene set high_score --value 100

# 获取值
npx sdk-commands storage scene get high_score

# 删除值
npx sdk-commands storage scene delete high_score

# 删除所有场景存储数据
npx sdk-commands storage scene clear --confirm
```

### 玩家存储 — 按钱包地址区分

```typescript
import { Storage } from "@dcl/sdk/server"

type Progress = { level: number; coins: number }

// 写入——如果值未能持久化，set() 会解析为 false
const ok = await Storage.player.set(playerAddress, "progress", {
  level: 5,
  coins: 250,
})
if (!ok) {
  console.error(`Failed to save progress for ${playerAddress} — retry later`)
}

// 读取：此玩家没有已保存的进度时为 null
const progress = (await Storage.player.get<Progress>(playerAddress, "progress")) ?? { level: 1, coins: 0 }

// 删除
await Storage.player.delete(playerAddress, "progress")
```

你也可以通过命令行管理玩家存储，使用 `npx sdk-commands storage player`:

```bash
# 为特定玩家设置值
npx sdk-commands storage player set level --value 10 --address 0x1234...

# 获取特定玩家的值
npx sdk-commands storage player get level --address 0x1234...

# 删除特定玩家的值
npx sdk-commands storage player delete level --address 0x1234...

# 删除特定玩家的所有数据
npx sdk-commands storage player clear --address 0x1234... --confirm

# 删除所有玩家的数据
npx sdk-commands storage player clear --confirm
```

每个场景值最大可为 512 KB，一个 World 的所有场景值共用 10 MB。每个玩家值最大可为 100 KB，每位玩家的总容量为 1 MB。

{% hint style="warning" %}
**📔 注意**：无法列出哪些玩家存储了数据。 `Storage.player.getValues(address, { prefix, offset })` 可以列出你已知的一位玩家的键，但 SDK、 `storage player` 命令以及 [存储界面](#access-stored-data) 都不会列出玩家地址。如果你将来可能需要遍历所有玩家，例如迁移他们的存档或据此构建排行榜，也请在场景键中维护自己的地址索引。
{% endhint %}

### 加载存档时不要覆盖它

玩家加入时，切勿先分配默认数据再保存：如果玩家已有已保存的数据但尚未加载，默认值就会覆盖这些数据。应先读取，只有当 `get()` 返回 `null`时才创建默认数据。如果读取操作抛出异常，请暂不加载该玩家，并稍后重试。

```typescript
import { Storage } from "@dcl/sdk/server"

type Save = { coins: number }
const saves: Record<string, Save> = {}

async function loadOrCreate(address: string): Promise<Save> {
  if (saves[address]) return saves[address] // 已加载
  // 读取失败时会抛出异常，因此失败绝不会变成新建存档
  const stored = await Storage.player.get<Save>(address, "save")
  saves[address] = stored ?? { coins: 0 } // 仅在存档不存在时使用默认值
  return saves[address]
}
```

在加入处理程序中 `try/catch` 内调用它。如果它抛出异常，就告知客户端以便重试；在该玩家的存档加载完成前，忽略其操作。

### 玩家不在场景中时的进度

不要为随时间增长的事物（例如作物、能量或商店补货）持续运行计时器。最后一名玩家离开后，多人游戏服务器会在几分钟后停止（参见 [等待服务器启动](#wait-for-the-server-to-start-up)），计时器也会随之停止。应改为存储上次更新进度的时间。玩家返回时，根据经过的时间计算进度，并将存储的时间更新到当前时间。

为此，请使用服务器上的 `Date.now()` ，切勿使用客户端发送的时间：玩家可以把时钟调快来跳过等待。

### 避免并发写入导致数据丢失

Storage 无法仅在读取后无人更改某个键的情况下更新该键（不支持“比较并交换”）。因此，如果你读取一个键、修改其值再写回，就可能丢失数据：

* 两个服务器实例可能同时写入。重新部署期间，场景的新旧版本重叠运行时就会发生这种情况。
* 读取可能返回比最近一次写入更旧的值。即使使用 `Storage.get(key, { fresh: true })`，跨服务器重启也是如此；Storage 曾返回过时长达一小时甚至更久的键值。 `fresh` 选项只会跳过 SDK 自身的缓存。
* 使用 `Storage.getValues()` 获取的列表也可能过时：它可能漏掉最近写入的键，或仍显示已删除的键。

对于只会增长的数据（例如结果日志或玩家反馈），请使用以下模式，而不是反复改写同一个键：

1. 将每个快照写入一个 **新键** ，该键按时间排序且不会冲突，例如 `results-1-20261027-130512-k3fz`：前缀、分段编号、UTC 时间以及几个随机字符。
2. 读取时，使用 `Storage.getValues({ prefix, offset })`按页列出该分段的所有键，直到获得 `pagination.total` 条记录，然后按行 ID 合并。
3. 将合并后的行写入一个新键。读回该键，只有在内容匹配时，才删除已合并的键。切勿删除其他写入者仍可能根据你自己的读取结果进行更改的键。

发生竞争时会留下一个额外的键，供下一次写入合并，而不是丢失一行数据。任何读取这些数据的人（包括从 [存储界面](#access-stored-data)下载数据时的你）都必须读取该分段的所有键，并去除重复 ID。

```typescript
import { Storage } from "@dcl/sdk/server"

type Row = { id: string; text: string }
const PREFIX = "results-1-"

// 所有以该前缀开头的键，按从旧到新的顺序排列
async function listAll(prefix: string) {
  const entries: { key: string; value: unknown }[] = []
  for (;;) {
    const page = await Storage.getValues({ prefix, offset: entries.length })
    entries.push(...page.data)
    if (page.data.length === 0 || entries.length >= page.pagination.total) break
  }
  return entries.sort((a, b) => (a.key < b.key ? -1 : 1))
}

async function appendRows(newRows: Row[]): Promise<boolean> {
  const versions = await listAll(PREFIX)
  // 按行 ID 合并，优先保留最先出现的项
  const rows = new Map<string, Row>()
  for (const { value } of versions) for (const row of value as Row[]) if (!rows.has(row.id)) rows.set(row.id, row)
  for (const row of newRows) if (!rows.has(row.id)) rows.set(row.id, row)
  const merged = [...rows.values()]

  // 每次都使用一个新键：UTC 时间加随机字符
  // "2026-10-27T13:05:12.123Z" becomes "20261027-130512"
  const stamp = new Date().toISOString().slice(0, 19).replace(/[-:]/g, "").replace("T", "-")
  const key = `${PREFIX}${stamp}-${Math.random().toString(36).slice(2, 6)}`
  if (!(await Storage.set(key, merged))) return false // 未保存，请稍后重试

  // 只有确认能读回新键后，才删除已合并的键
  const check = await Storage.get<Row[]>(key, { fresh: true })
  if (JSON.stringify(check) !== JSON.stringify(merged)) return true
  for (const version of versions) {
    try {
      await Storage.delete(version.key)
    } catch {
      // 保留这些数据：下次写入时会再次合并
    }
  }
  return true
}
```

单个值最多可存储 512 KB，因此应在某个分片接近上限之前开始新的分片（`results-2-`）。例如， [Scene Feedback 示例](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/0%2C-1-scene-feedback) 在其 CSV 文件中采用了这种模式，并在达到 400 KB 时切换到新分片。

### 访问存储数据

你可以通过存储界面查看和编辑服务器上实时存储的数据，只需访问以下链接：

[decentraland.org/storage](https://decentraland.org/storage)

对于 World，也可以通过 Creator Hub 访问此页面。打开 **管理** 页面，点击 World 卡片上的三点图标，然后选择 **查看存储**.

在这里，你可以看到所有可发布场景的 World 和土地列表。

打开你的场景，然后打开 **场景** 或 **玩家** 选项卡。

在 **场景** 选项卡中，你会看到所有已存储变量的列表。点击铅笔或垃圾桶图标，即可编辑或删除这些变量。

![Activate stream](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-bbb302fbdb29f57fdcff7bf62fc6608838a06d44%2Fscene-data.webp?alt=media)

在 **玩家** 选项卡中，你会看到所有在服务器上存有数据的玩家列表。你可以按地址或名称搜索，然后查看他们关联的所有数据。点击铅笔或垃圾桶图标，也可以编辑或删除这些数据。

### 更改数据结构

生产环境中存储的数据 **不会在发布场景新版本时清除**。这非常适用于排行榜、玩家进度，以及玩家期望在场景小幅更新后仍能保留的环境变更。

另一方面，存储中的数据可能是由旧版本的代码写入的。如果新代码预期的数据结构不同，解析或读取旧数据时就可能以不易察觉的方式失败。重命名的字段会缺失；原本是字符串、如今变成对象的字段，会在尝试访问其属性时引发错误。几个月未登录的玩家加载的数据，可能早于某种结构变更，而你的代码已不再知道如何处理这种结构。

{% hint style="warning" %}
**📔 注意**：架构变更的影响不只限于部署后的首次读取。存储的数据会一直保留，直到被覆盖或删除，因此旧格式的值随时可能出现，往往来自一个你早已忘记的回访玩家。
{% endhint %}

#### 最佳实践

* *始终以防御性方式读取*。将从存储中读取的任何内容都视为不可信输入，即使它是你写入的也是如此。传递给 `get<T>()` 的类型不会经过检查，因此在读取字段之前，请检查字段是否存在且类型正确，并在字段不符合要求时准备好合理的默认值：

  ```typescript
  import { Storage } from "@dcl/sdk/server"

  const saved = await Storage.player.get<any>(playerAddress, "progress")
  const progress = {
    level: typeof saved?.level === "number" ? saved.level : 1,
    coins: typeof saved?.coins === "number" ? saved.coins : 0,
  }
  ```
* *添加字段，不要重命名或删除字段*。最安全的架构变更是增量式的：引入带默认值的新字段，并保留现有字段不变。旧数据只会缺少新字段，而你的防御性解析已经能处理这种情况。重命名字段会导致所有旧记录都无法使用。
* *为存储的对象添加版本号*。从一开始就包含一个 `version` 字段。读取数据时，根据版本进行分支处理，并在使用旧数据之前将其迁移为当前格式。这样，代码的其余部分就始终可以使用统一的当前格式：

  ```typescript
  type ProgressV2 = { version: 2; level: number; coins: number; xp: number }

  function migrate(raw: any): ProgressV2 {
    const version = raw?.version ?? 1
    if (version === 1) {
      // v1 没有 xp 字段——为其设置默认值
      return {
        version: 2,
        level: raw.level ?? 1,
        coins: raw.coins ?? 0,
        xp: 0,
      }
    }
    return raw as ProgressV2
  }
  ```
* *将迁移后的值写回*。在内存中升级记录后，将其保存回去，这样下次读取时数据就已经是新格式。随着时间推移，旧格式记录会逐渐减少，无需编写一次性迁移脚本。
* *对于不兼容的变更，请使用新键*。如果新结构确实不兼容，而且不值得迁移，就写入新的存储键（例如 `progress_v2`），并忽略旧键。旧键会安然留在存储中，同时你也无需编写任何必须解析旧键的读取逻辑。之后可以通过 [存储界面](https://decentraland.org/storage) 或 `npx sdk-commands storage` 命令清理旧键。
* *使用真实生产数据进行测试*。部署结构变更之前，从存储界面获取几条真实记录，并用新的解析代码对其进行测试。导致问题的边缘情况通常来自你不知道其存在的记录。
* *留好补救途径*。请记住，你可以通过存储界面或使用 `npx sdk-commands storage`编辑或删除单条记录。如果架构变更后某个玩家的状态异常，你可以直接修复其记录，而无需重新部署。

## 环境变量

无需将值硬编码到代码中，即可配置场景。环境变量适用于敏感数据，也适用于功能开关或参数；这些内容无需重新发布场景即可轻松更改。

环境变量仅限 **服务器端**使用。请使用 `isServer()`进行保护。服务器可以读取环境变量，但不能更改其值。

`EnvVar.get()` 返回一个 `Promise<string>` 如果未设置该变量，则会解析为空字符串，因此始终要为缺失值提供备用值：

```typescript
import { EnvVar } from "@dcl/sdk/server"
import { isServer } from "@dcl/sdk/network"

export async function main() {
  if (!isServer()) return

  const maxPlayers = parseInt((await EnvVar.get("MAX_PLAYERS")) || "4")
  const gameDuration = parseInt((await EnvVar.get("GAME_DURATION")) || "300")
  const debugMode = ((await EnvVar.get("DEBUG")) || "false") === "true"
}
```

### 敏感数据

环境变量特别适合存储私钥、奖励领取码及其他敏感数据，因为将这些数据暴露在场景编译后的公开代码中会带来风险。

你可以将私钥存储在服务器的存储空间中，并让服务器独自读取这些数据，使用 `isServer()`。这样，敏感数据就不会经过玩家的设备。

### 本地开发

要在本地运行项目时使用环境变量，请在项目根目录中创建 `.env` 文件：

```
MAX_PLAYERS=8
GAME_DURATION=300
DEBUG=true
```

重要提示：将 `.env` 添加到 `.gitignore`中，避免这些可能包含敏感信息的值被上传到公开内容服务器。

### 更改环境变量

更改环境变量值最简单的方法是使用存储界面。

打开此链接即可访问场景存储的数据：

[decentraland.org/storage](https://decentraland.org/storage)

对于 World，也可以通过 Creator Hub 访问此页面。打开 **管理** 页面，点击 World 卡片上的三点图标，然后选择 **查看存储**.

在这里，你可以看到所有可发布场景的 World 和土地列表。

打开场景，然后切换到 **环境** 选项卡。你应该能看到项目中的所有环境变量。

![Activate stream](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-766c8433de10c67980a737242d867ad3c4fb5948%2Fenvironment-variables.webp?alt=media)

请注意，你无法读取这些环境变量的值（这是为了保护敏感数据），但可以删除或覆盖它们。只需点击铅笔或垃圾桶图标即可。

你也可以使用命令行管理环境变量，通过 `npx sdk-commands storage env`:

```bash
# 设置变量
npx sdk-commands storage env set MAX_PLAYERS --value 8

# 删除变量
npx sdk-commands storage env delete OLD_VAR

# 删除所有环境变量
npx sdk-commands storage env clear --confirm
```

你也可以使用 `--target` 标志指定目标环境：

```bash
# 部署到预发布环境
npx sdk-commands storage env set MY_KEY --value my_value --target https://storage.decentraland.zone

# 部署到本地开发服务器
npx sdk-commands storage env set MY_KEY --value my_value --target http://localhost:8000
```

已部署的环境变量优先于 `.env` 文件中的值。

## 推荐的项目结构

将服务器端、客户端和共享代码分开，能让代码库在增长时依然清晰易读：

```
src/
├── index.ts              # 入口点 — isServer() 分支
├── client/
│   ├── setup.ts          # 输入处理器、消息发送器
│   └── ui.tsx            # React ECS UI（读取同步后的状态）
├── server/
│   ├── server.ts         # 游戏循环、消息处理器、状态变更
│   └── gameState.ts      # 服务器状态辅助函数
└── shared/
    ├── schemas.ts        # 组件定义 + validateBeforeChange
    └── messages.ts       # registerMessages() — 两端均会导入
```

{% hint style="info" %}
**💡 提示**：将所有 `registerMessages()` 调用和自定义组件定义放在 `shared/`中。服务器端和客户端都从这里导入，确保双方的消息架构始终一致。
{% endhint %}

## 性能最佳实践

每次组件变更都会通过网络发送 *整个* 组件数据。这与 Colyseus 的做法不同，后者只发送差异数据。设计自定义组件时，请牢记这一点。最佳方案可能是根据数据的变更频率，将其存储在不同的组件中。

### ❌ 避免使用臃肿的组件

```typescript
import { engine, Schemas } from "@dcl/sdk/ecs"

// 不佳 — 修改分数时也会发送位置数组
const GameState = engine.defineComponent("GameState", {
  playerAScore: Schemas.Int,
  playerBScore: Schemas.Int,
  timer: Schemas.Int,
  playerPositions: Schemas.Array(Schemas.Vector3), // 负载较大
})
```

### ✅ 优先使用原子化组件

```typescript
import { engine, Schemas } from "@dcl/sdk/ecs"

// 推荐 — 每次更新都很小且互相独立
const PlayerScore = engine.defineComponent("PlayerScore", {
  playerA: Schemas.Int,
  playerB: Schemas.Int,
})

const GameTimer = engine.defineComponent("GameTimer", {
  secondsLeft: Schemas.Int,
})
```

*经验法则*：将同时变化且变化频率相近的字段分组。将快速变化的数据（计时器、位置）与缓慢变化的数据（分数、配置）分开。

### 限制高频消息的发送频率

避免每帧都发送消息。尽可能批量发送或限制发送频率：

```typescript
import { engine } from "@dcl/sdk/ecs"
import { room } from "./shared/messages"

let lastSend = 0
engine.addSystem((dt) => {
  lastSend += dt
  if (lastSend > 0.1) {
    // 每 100 毫秒
    room.send("position", transform.position)
    lastSend = 0
  }
})
```

例如，如果倒计时由服务器控制，就没必要每秒向所有玩家发送更新。最好由每个客户端自行计算经过的时间，再由服务器每隔约 30 秒广播一次当前状态，以确保一致性。

## 服务器资源限制

多人游戏服务器会在受沙箱保护的隔离环境中运行每个场景，并设有严格的资源上限。超出这些限制可能会导致数据被静默丢弃，或使场景中的所有用户都无法使用服务器，因此设计场景时应确保资源用量远低于上限。

### 内存

该隔离环境具有 **256 MB** 内存上限。超过此上限时，隔离环境会被销毁，服务器将对所有已连接的玩家关闭。保持工作状态精简，并在玩家离开时清理其数据。

### CPU

每个执行轮次都有一个墙钟时间预算：

* **同步执行**：每轮 10 秒。超过此时限的无界循环会导致隔离环境被终止。
* **异步轮次完成**：60 秒。如果 `Promise` 链或 `await` 耗时超过此限仍未完成，隔离环境将被终止。

使用 `dt` 累加器，在 `engine.addSystem()`中将繁重工作分摊到多个 tick。切勿在服务器上运行无界的同步循环。

### 入站消息速率

每个已连接的对等端每 **1,000 毫秒最多可发送约 300 条消息**。超出的数据帧会被丢弃（不会排队）。切勿让客户端每帧都发送消息。有关限流模式，请参阅 [性能最佳实践](#performance-best-practices) 。

### 消息大小

* 入站数据包上限为每个数据包 **128 KB** 。超大数据包会被整体丢弃。
* 场景到通信系统的消息上限约为 **30 KB**。在实际传输层中，同步消息应远小于 **13 KB** （请参阅 [消息](#messages) 部分）。

### 外部 fetch

并发 `signedFetch` 调用的上限为 **32** 个正在处理的请求。额外的 fetch 请求会排队，直到有空位。每次 fetch 尝试的超时时间为 **15 秒** 。fetch 响应上限为 **10 MB**。WebSocket 连接数限制为 **32** 个并发套接字，每条消息的最大大小为 **1 MB** 。

### 正在处理的主机调用

中所述的 40 次调用上限 [数据存储](#data-storage) 适用于整个隔离环境中的所有主机调用，包括 Storage， `signedFetch`以及其他运行时 API。超出调用次数限制的请求会立即被拒绝，不会排队。

## 常见陷阱

### 忘记验证仅限服务器端的状态

如果没有 `validateBeforeChange`，客户端就可以写入任何组件：

```typescript
import { engine, Schemas } from "@dcl/sdk/ecs"
import { isServer } from "@dcl/sdk/network"
import { AUTH_SERVER_PEER_ID } from "@dcl/sdk/network/message-bus-sync"

// ❌ 错误 — 客户端可以作弊
const Score = engine.defineComponent("Score", { value: Schemas.Int })

// ✅ 正确 — 仅限服务器端
if (isServer()) {
  Score.validateBeforeChange((v) => v.senderAddress === AUTH_SERVER_PEER_ID)
}
```

### 信任客户端提供的值

对于生命值、分数或位置等重要数据，绝不要让客户端自行指定数值：

```typescript
import { room } from "./shared/messages"

// ❌ 错误
room.onMessage("setHealth", (data) => {
  player.health = data.health // 数值由客户端控制！
})

// ✅ 正确 — 由服务器计算结果
room.onMessage("takeDamage", (data) => {
  const damage = calculateDamage(data.source)
  player.health = Math.max(0, player.health - damage)
})
```

### 信任消息中的金额和地址

来自客户端的消息是请求，而非事实。使用任何字段前都要逐一检查：

* **金额**: `Schemas.Int` 会将值解码为 32 位整数，但该值仍可能为零或负数。拒绝小于或等于零的金额，否则玩家可能会“发送” `-500` 金币，反而收到金币。还要检查发送方是否有足够的金币。
* **地址**：客户端发送的钱包地址必须是 `0x` 后跟 40 个十六进制字符。任何其他格式都应在进入映射或 Storage 前予以拒绝。

```typescript
import { room } from "./shared/messages"

const ADDRESS = /^0x[0-9a-f]{40}$/
const balances: Record<string, number> = {}

room.onMessage("giveCoins", (data, context) => {
  if (!context) return
  const from = context.from.toLowerCase()
  const to = String(data.to).toLowerCase()
  if (!ADDRESS.test(to) || to === from) return
  if (!Number.isInteger(data.amount) || data.amount <= 0) return // 拒绝负数和零
  if ((balances[from] ?? 0) < data.amount) return // 金币不足
  balances[from] -= data.amount
  balances[to] = (balances[to] ?? 0) + data.amount
})
```

### 在状态同步前发送消息

客户端必须等待状态同步完成后才能进行交互：

```typescript
import { engine } from "@dcl/sdk/ecs"
import { isStateSyncronized } from "@dcl/sdk/network"

engine.addSystem(() => {
  if (!isStateSyncronized()) return
  // 现在可以安全地发送消息
})
```

### 等待服务器启动

只有场景中至少有一名玩家时，服务器才会运行。最后一名玩家离开后，服务器会继续运行约两分钟，然后关闭。下次有人访问时，会冷启动一个新实例，大约需要 **在生产环境中需要 15 秒**。本地预览会立即启动服务器，因此冷启动问题几乎只会在发布后出现。

场景代码应做好等待服务器上线的准备。服务器完成启动前发送的消息会被静默丢弃。等待期间，向玩家显示“服务器正在唤醒”提示，并为初始服务器请求添加重试逻辑。

{% hint style="info" %}
**提示：** 检测服务器是否就绪的一种可靠方法是使用心跳：让服务器写入 `Date.now()` 每 2 秒更新一次同步组件字段，并让客户端跟踪上次检测到值变化的时间。如果 6 秒内没有收到变化，就将服务器视为离线。这比 `isStateSyncronized()`更可靠，因为它只能确认传输连接正常，并不能确认服务器正在运行。
{% endhint %}

## 完整示例

一个最简多人游戏计数器：点击按钮，服务器就会增加同步分数。服务器会将计数器持久化到 `Storage` 中，因此服务器重启后该值仍会保留。请记住，如果场景中没有玩家，服务器就会关闭；因此，如果不使用存储，每次场景中没有玩家时，计数都会重置为零。

```typescript
import { engine, Schemas } from "@dcl/sdk/ecs"
import { registerMessages, isServer, syncEntity } from "@dcl/sdk/network"
import { AUTH_SERVER_PEER_ID } from "@dcl/sdk/network/message-bus-sync"
import { pointerEventsSystem } from "@dcl/sdk/ecs"
import { Storage } from "@dcl/sdk/server"

// 1. 定义消息（共享）
const Messages = {
  increment: Schemas.Map({}),
  stateUpdate: Schemas.Map({
    count: Schemas.Int,
    lastPlayer: Schemas.String,
  }),
}

// 2. 定义仅服务器使用的组件（共享）
const Counter = engine.defineComponent("Counter", {
  value: Schemas.Int,
  lastPlayer: Schemas.String,
})

// 3. 创建房间
const room = registerMessages(Messages)

export async function main() {
  if (isServer()) {
    // === SERVER ===

    // 只有服务器可以修改此组件
    Counter.validateBeforeChange(
      (v) => v.senderAddress === AUTH_SERVER_PEER_ID
    )

    // 从存储中恢复计数器，以应对服务器重启
    let initialCount = 0
    let initialPlayer = "none"
    let loaded = false
    try {
      initialCount = (await Storage.get<number>("counter")) ?? 0
      initialPlayer = (await Storage.get<string>("lastPlayer")) ?? "none"
      loaded = true
    } catch (error) {
      console.log("[Server] Could not load the counter:", error)
    }

    const counterEntity = engine.addEntity()
    syncEntity(counterEntity, [Counter.componentId], 1)
    Counter.create(counterEntity, {
      value: initialCount,
      lastPlayer: initialPlayer,
    })

    room.onMessage("increment", async (_data, context) => {
      if (!context) return
      if (!loaded) return // Never save over a counter that didn't load
      const from = context.from.toLowerCase()
      const counter = Counter.getMutable(counterEntity)
      counter.value += 1
      counter.lastPlayer = from

      // 持久化到存储中，使该值在服务器重启后仍然保留
      const saved =
        (await Storage.set("counter", counter.value)) &&
        (await Storage.set("lastPlayer", from))
      if (!saved) console.log("[Server] Counter not saved, the next click saves it again")

      room.send("stateUpdate", {
        count: counter.value,
        lastPlayer: from,
      })
    })
  } else {
    // === 客户端 ===
    const button = engine.addEntity()
    // ... 添加 Transform、MeshRenderer 等组件。

    pointerEventsSystem.onPointerDown(button, () => {
      room.send("increment", {})
    })

    room.onMessage("stateUpdate", (data) => {
      console.log(`Count: ${data.count} (last click by ${data.lastPlayer})`)
    })
  }
}
```

## 本地测试

标准预览会处理所有事务。使用 SDK 的 auth-server 分支时，本地服务器会在后台与客户端预览一同自动启动。

要在本地测试多人交互，请在两个独立窗口中打开预览，每个窗口都会被视为一名独立玩家。使用不同地址连接每个窗口。两个客户端都会连接到同一个本地服务器实例。

使用 Creator Hub，在 **多实例预览** 的 **桌面客户端** 子菜单中打开该选项，然后点击 **播放选项**中的 **播放** 按钮，再打开一个 Decentraland 浏览器窗口。你必须使用不同的地址分别登录两个窗口。重新加载场景时，这些会话仍会保持打开状态。

或者，你也可以在浏览器地址栏中输入以下内容，打开第二个 Decentraland 浏览器窗口：

> `decentraland://realm=http://127.0.0.1:8000&local-scene=true&debug=true&multi-instance=true`

### 调试技巧

* *为日志添加前缀* ，例如 `[SERVER]` 或 `[CLIENT]` 这样你就能在终端中区分它们：

  ```typescript
  import { isServer } from "@dcl/sdk/network"

  if (isServer()) {
    console.log("[SERVER] Starting...")
  } else {
    console.log("[CLIENT] Starting...")
  }
  ```
* *验证组件同步* 在客户端通过记录实体数量来检查：

  ```typescript
  import { engine } from "@dcl/sdk/ecs"

  engine.addSystem(() => {
    const entities = Array.from(engine.getEntitiesWith(MyComponent))
    console.log("[CLIENT] Synced entities:", entities.length)
  })
  ```

## 在生产环境中调试

使用 [Scene Insights](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/tiao-shi/scene-insights.md) 搜索已发布的服务器日志、实时跟踪日志，并获取 CPU、内存和其他指标。日志和指标会保留 **7 天**，即使重启和重新部署也不会丢失。

更新到最新版本 `auth-server` SDK，然后在你的场景项目中运行以下命令：

```bash
npx sdk-commands scene-insights login
npx sdk-commands scene-insights tail
```

在浏览器中使用已授权的钱包登录。只读会话会在后续命令中重复使用，最长可达 12 小时。按下 **Ctrl+C** 以停止跟踪日志。

该 [Scene Insights 指南](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/tiao-shi/scene-insights.md) 介绍历史搜索、场景选择、访问权限、指标、AI 辅助调试以及集合限制。

### 查看存储数据

打开此链接即可访问场景存储的数据：

[decentraland.org/storage](https://decentraland.org/storage)

对于 World，也可以通过 Creator Hub 访问此页面。打开 **管理** 页面，点击 World 卡片上的三点图标，然后选择 **查看存储**.

在这里，你可以看到所有可发布场景的 World 和土地列表。

打开世界数据或玩家数据，查看其中存储的信息。

例如，如果某位玩家在游玩你的场景时遇到问题，你可以通过地址查找该玩家，并查看为其存储的数据，以了解他们的情况。他们可能遇到了某种边缘情况，导致数据相互矛盾。你甚至可以在此页面清除或编辑该玩家的数据，让其恢复到稳定状态。

## 版本控制

场景每个已发布版本都有一个唯一的哈希 ID，并且每个哈希都对应一个独立的服务器实例。这意味着客户端代码和服务器代码始终同步更新，不会出现运行旧逻辑的客户端与运行新逻辑的服务器通信（或反之）的情况。

发布更新时：

* *已在场景中的玩家* 会继续看到场景的旧版本，直到他们离开并重新进入。其客户端会继续连接到与旧哈希对应的服务器实例。
* *新加入的玩家* 会在更新后加载新版本的场景，并连接到新的服务器实例。

这可确保客户端和服务器状态不会因架构变更或组件重命名而失去同步。更新绝不会中断已在场景中的玩家的会话。

代价是，部署完成后的一小段时间内，玩家可能会分散在两个不同的服务器实例上。已经在场景中的玩家和刚加入的玩家可能看不到彼此，也无法通过场景进行交互，尽管他们身处同一场景；这种情况会持续到较早加入的玩家离开并重新加入为止。

{% hint style="info" %}
**💡 提示**：通过 [Storage](#data-storage) 服务存储的数据（例如排行榜、玩家进度或持久化的环境变更） *不会* 在不同版本之间被清除。Storage 会在位置级别持久化，并由指向同一场景的所有服务器实例共享，因此新版本会从上一版本停止的地方继续运行。
{% endhint %}

## 从 Colyseus 迁移

如果你已有基于 Colyseus 构建的场景，下表将常见的 Colyseus 模式对应到 SDK7 中的等效方案：

| Colyseus                   | SDK7 多人游戏服务器                        |
| -------------------------- | ----------------------------------- |
| `room.send(type, data)`    | `room.send(type, data)` — API 相同    |
| `room.onMessage(type, cb)` | `room.onMessage(type, cb)` — API 相同 |
| `room.state.players` （架构）  | `syncEntity` + 自定义组件                |
| JSON 序列化                   | 二进制序列化（通过 `Schemas`)                |
| 独立的服务器应用程序                 | 同一代码库 — `isServer()` 分支逻辑           |
| 自定义服务器托管                   | 内置：预览时会自动运行服务器                      |

需要牢记的主要区别：

* *序列化*：Colyseus 发送 JSON 差异；SDK 会在每次变更时发送完整组件。请保持组件精简（参见 [性能最佳实践](#performance-best-practices)).
* *状态模型*：Colyseus 使用可变状态树并自动计算差异。SDK 使用通过 `syncEntity` 同步并通过 `validateBeforeChange`.
* *托管*：无需单独部署服务器。多人游戏服务器会与场景一同自动部署。


---

# 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/creator/content-creator-zh/chang-jing-sdk7/lian-wang/authoritative-servers.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.
