---
title: ZEPETO.Multiplay
slug: world-sdk-guide-ch/zepetomultiplay
docTags: 
createdAt: 2026-09-04T05:22:03.801Z
---

| 类型                                        | 说明                             |
| ----------------------------------------- | ------------------------------ |
| [SandboxPlayer](./#sandboxplayer)         | 表示已连接到 Multiplay Room 的玩家客户端。  |
| [IBroadcastOptions](./#ibroadcastoptions) | 从 Multiplay Room 向客户端广播消息时的选项。 |
| [SandboxOptions](./#sandboxoptions)       | 创建 Multiplay Room 时的选项。        |
| [Sandbox](./#sandbox)                     | 表示 Multiplay Room。             |

## SandboxPlayer

`interface`

表示已连接到 Multiplay Room 的玩家客户端。

### 属性

| 名称        | 类型       | 说明        |
| --------- | -------- | --------- |
| sessionId | `string` | 客户端的会话 ID |
| userId    | `string` | 玩家的用户 ID  |

### 方法

### send

`send(type: string | number, message?: T) → void`

通过指定的频道向客户端发送消息。

| 参数           | 类型                 | 说明                    |
| ------------ | ------------------ | --------------------- |
| type         | `string \| number` | 用于发送消息的频道标识符。         |
| message （可选） | `T`                | message 要发送的消息内容（可选）。 |

## IBroadcastOptions

`interface`

从 Multiplay Room 向客户端广播消息时的选项。

### 属性

| 名称     | 类型                                | 说明             |
| ------ | --------------------------------- | -------------- |
| except | [SandboxPlayer](./#sandboxplayer) | 指定要从广播中排除的客户端。 |

## SandboxOptions

`interface`

创建 Multiplay Room 时的选项。

### 属性

| 名称        | 类型        | 说明                                            |
| --------- | --------- | --------------------------------------------- |
| isSandbox | `boolean` | 指定 Room 是否在本地托管，例如在 Unity 编辑器中进行 QR 移动端测试的情况。 |

## Sandbox

`class`

表示 Multiplay Room。

### 属性

| 名称                    | 类型                                | 说明                                               |
| --------------------- | --------------------------------- | ------------------------------------------------ |
| locked                | `boolean`                         | 指定 Multiplay Room 是否已锁定。                         |
| roomId                | `string`                          | Multiplay Room 的 ID，在创建时随机分配以避免重复。               |
| uniqueId              | `string`                          | Multiplay Room 的 ID，在创建时显式指定。                    |
| maxClients            | `number`                          | 可连接到 Multiplay Room 的最大客户端数量。                    |
| state                 | `State`                           | Multiplay Room 的状态。状态数据的架构由 Multiplay Schema 定义。 |
| clients               | `IterableIterator<SandboxPlayer>` | 已连接到 Multiplay Room 的客户端的可迭代表示。                  |
| allowReconnectionTime | `number`                          | 允许连接不稳定的客户端重新连接的时限（秒）。                           |
| private               | `boolean`                         | 指定 Multiplay Room 是否为私密房间。                       |

### 方法

### onCreate

`onCreate(options: SandboxOptions) → void | Promise<void>`

该抽象方法的实现会在 Multiplay Room 创建时执行一次。
该实现可以选择性地声明为 `async`。

| 参数      | 类型                                  | 说明                       |
| ------- | ----------------------------------- | ------------------------ |
| options | [SandboxOptions](./#sandboxoptions) | 创建该 Multiplay Room 时的选项。 |

**返回值：** `void | Promise<void>` — 若为异步，则返回 `Promise<void>`；否则返回 `void`。

### onJoin

`onJoin(client: SandboxPlayer) → void | Promise<void>`

该抽象方法的实现会在客户端加入 Multiplay Room 时执行。
该实现可以选择性地声明为 `async`。

| 参数     | 类型                                | 说明        |
| ------ | --------------------------------- | --------- |
| client | [SandboxPlayer](./#sandboxplayer) | 玩家的客户端对象。 |

**返回值：** `void | Promise<void>` — 若为异步，则返回 `Promise<void>`；否则返回 `void`。

### onLeave

`onLeave(client: SandboxPlayer, consented?: boolean) → void | Promise<void>`

该抽象方法的实现会在客户端离开 Multiplay Room 时执行。
该实现可以选择性地声明为 `async`。

| 参数             | 类型                                | 说明              |
| -------------- | --------------------------------- | --------------- |
| client         | [SandboxPlayer](./#sandboxplayer) | 玩家的客户端对象。       |
| consented （可选） | `boolean`                         | 指定该玩家是否已同意重新连接。 |

**返回值：** `void | Promise<void>` — 若为异步，则返回 `Promise<void>`；否则返回 `void`。

### lock

`lock() → Promise<void>`

锁定 Multiplay Room。

**返回值：** `Promise<void>` — 锁定处理完成时兑现的 `Promise`。

### unlock

`unlock() → Promise<void>`

解锁 Multiplay Room。

**返回值：** `Promise<void>` — 解锁处理完成时兑现的 `Promise`。

### onTick

`onTick(deltaTime: number) → void`

该方法的实现约每 100 毫秒执行一次。

| 参数        | 类型       | 说明                  |
| --------- | -------- | ------------------- |
| deltaTime | `number` | 表示与上一次调用之间的时间差（毫秒）。 |

### onMessage

`onMessage(messageType: '*' | string | number, callback: (client: SandboxPlayer, message: T) => void) → void`

注册用于处理来自客户端消息的回调。

| 参数          | 类型                                            | 说明              |
| ----------- | --------------------------------------------- | --------------- |
| messageType | `'*' \| string \| number`                     | 消息发送所经频道的标识符。   |
| callback    | `(client: SandboxPlayer, message: T) => void` | 用于处理所接收消息的回调方法。 |

### broadcast

`broadcast(type: string | number, message?: any, options?: IBroadcastOptions) → void`

通过指定的频道向已连接到 Multiplay Room 的所有客户端发送消息。

| 参数           | 类型                                        | 说明            |
| ------------ | ----------------------------------------- | ------------- |
| type         | `string \| number`                        | 用于发送消息的频道标识符。 |
| message （可选） | `any`                                     | 消息内容（可选）。     |
| options （可选） | [IBroadcastOptions](./#ibroadcastoptions) | 广播选项。         |

### loadPlayer

`loadPlayer(sessionId: string) → SandboxPlayer | undefined`

获取与会话 ID 关联的客户端对象。

| 参数        | 类型       | 说明         |
| --------- | -------- | ---------- |
| sessionId | `string` | 客户端的会话 ID。 |

**返回值：** `SandboxPlayer | undefined` — 客户端对象。

### setPrivate

`setPrivate(isPrivate: boolean) → Promise<void>`

设置 Multiplay Room 的私密状态。

| 参数        | 类型        | 说明                       |
| --------- | --------- | ------------------------ |
| isPrivate | `boolean` | 指定 Multiplay Room 的私密状态。 |

**返回值：** `Promise<void>` — 处理完成时兑现的 `Promise`。

### kick

`kick(client: SandboxPlayer, reason?: string) → Promise<void>`

将客户端踢出 Multiplay Room。

| 参数          | 类型                                | 说明            |
| ----------- | --------------------------------- | ------------- |
| client      | [SandboxPlayer](./#sandboxplayer) | 要踢出的客户端对象。    |
| reason （可选） | `string`                          | 可选择性地说明踢出的原因。 |

**返回值：** `Promise<void>` — 处理完成时兑现的 `Promise`。