# 让 Godot 游戏多人联机，不用自己搭游戏服务器

> 我们为 Godot 4 做了一个纯 GDScript 的 Hibira 插件：房间、聊天、玩家位置同步，网页导出也能用。我们为什么做它、它怎么工作，以及五分钟跑起来的演示。

Source: https://hibira.io/zh-cn/blog/godot-multiplayer-without-a-server
Updated: 2026-11-17

有一天团队里有人问了一句：“Godot 支持 Pusher 协议吗？”

答案是不支持。Godot 4 内置了 WebSocket，也有一整套高层多人联机 API，但它们都假设你自己有一台游戏服务器，或者让其中一位玩家当主机。对很多小团队来说，这正是做多人游戏最卡的地方：游戏本身做好了，却还得学怎么搭服务器、怎么开端口、怎么处理 NAT，最后还要每个月为一台不知道会有多少人用的主机付钱。

我们想要另一种做法：游戏里只放一个客户端，连到托管的实时服务，房间、在线名单和玩家之间的消息都交给它转发。于是我们做了 Hibira 的 Godot 插件。它是纯 GDScript，不需要原生扩展，Godot 能导出的平台它都能跑，网页也包括在内。

![同一个房间里，左边是 Godot 玩家，右边是浏览器玩家。](https://hibira.io/portal/articles/godot-lobby-crossplay-zh-CN.webp)

## 小型多人游戏真正需要什么

不是每款多人游戏都是射击游戏。我们看了看身边的独立游戏和 Game Jam 作品，多人功能大多是这几种：

- **大厅和房间**：建一个房间、拿到一组代码、分享给朋友、等大家点“准备”。
- **谁在线**：房间里有谁、谁刚加入、谁离开了、谁是房主。
- **聊天**：包括“对方正在输入…”。
- **轻量同步**：合作游戏里大家的位置、派对游戏里谁先按下按钮、回合制游戏的下一步。

这些需求有个共同点：消息都很小，延迟要求是“人能感觉到的快”，而不是射击游戏那种每一毫秒都要算的快。它们很适合用一条 WebSocket 加上“频道”的模型来处理，这正是 Pusher 协议擅长的。

## 为什么选 Pusher 协议

Pusher 协议已经存在十多年，模型很简单：客户端订阅频道，服务器或其他客户端往频道发事件。对游戏来说，最有用的是 presence 频道：

- 订阅时由你的后端签名，所以由你决定谁能进哪个房间。
- 频道会告诉每个人当前的成员名单，以及谁加入、谁离开。
- 玩家之间可以直接发 client 事件，而且服务器会在每一条事件上盖上发送者的 `user_id`。

最后一点很关键。因为 `user_id` 是服务器盖的，不是客户端自己填的，所以收到“玩家 A 移动到这里”时，你可以确定这条消息真的来自玩家 A。后面的位置同步就建立在这个保证上。

另一个好处是：协议相同，网页和游戏就能互通。我们的网页大厅 SDK @hibira-io/lobby 用的是同一组事件，所以 Godot 玩家和浏览器玩家可以坐进同一个房间，就像上面那张截图。

## 它是怎么工作的

```text
flow: 游戏只连 Hibira；你的后端只负责签名
Godot 游戏|HibiraClient --签名请求--> 你的后端|用 app secret 签 presence 频道
Godot 游戏|HibiraClient --WebSocket--> *Hibira|房间、成员名单、转发事件 --WebSocket--> 其他玩家|Godot 或浏览器
```

插件里有四个主要部分：

- **`HibiraClient`**：Pusher 协议 v7 的客户端，建立在 Godot 内置的 `WebSocketPeer` 上。负责连接、订阅、ping/pong，断线后自动重连并重新订阅。
- **`HibiraChannel`**：一个频道，用 `bind()` 绑定事件、用 `trigger()` 发 client 事件，presence 频道还有成员名单和加入／离开的 signal。
- **`HibiraRoom`**：把 presence 频道变成游戏房间，提供座位、房主、准备状态、房间设置、踢人、开始游戏，以及聊天和输入中提示。
- **`HibiraSync`**：0.2.0 新增的节点，挂在角色下面，它的位置就会出现在其他玩家的画面上。

App secret 自始至终不会出现在游戏里。游戏导出后任何人都能把文件拆开，所以签名一定要交给你的后端，这和 pusher-js 或 Laravel Echo 的做法完全一样。已经有网页版的话，现成的鉴权接口可以直接用。

## HibiraSync：挂上就同步

做合作游戏时，最常见的需求就是“让别人看到我在哪里”。我们希望这件事简单到只需挂一个节点：在 `player.tscn` 的 CharacterBody2D 下面挂一个 HibiraSync，频道设为 `presence-match-1`，要同步的属性设为 `position` 和 `rotation`，然后这样生成每位玩家：

```gdscript
func spawn(user_id: String) -> void:
	var p := PLAYER.instantiate()
	p.name = user_id
	p.get_node("HibiraSync").owner_id = user_id # 谁在操控它
	add_child(p)
```

背后做了几件事：

- **只有拥有者能动它。** 每个节点有一个 `owner_id`。收到的值如果不是拥有者发的，就直接丢掉；靠的正是服务器盖上的 `user_id`。
- **整个场景合成一条消息。** 同一个频道上所有要同步的节点，每个 tick 合并成一条 client 事件发出，默认每秒 8 次。Hibira 对 client 事件的限制是每条连接每秒 10 条，所以不管场景里有多少节点要同步，都不会超限。
- **只发有变化的值。** 角色站着不动，就什么都不发；有人新加入房间，再把全部的值发一次给他。
- **收到后平滑移动。** 每秒 8 次的更新如果直接套用，画面会一格一格地跳。所以收到的值会被当作目标，角色每一帧往目标靠近一点，旋转角度和四元数也有对应的插值。

```text
sequence: 一个 tick 里发生的事
玩家 A 的游戏 | *Hibira | 玩家 B 的游戏
1 > 2: client-hibira-sync | {"s": {"A/Player": {"position": [...]}}}
2 > 3: 同一条事件 | 加上 user_id: "A"
note: 玩家 B 确认 user_id 是这个节点的拥有者，才让角色平滑移到新位置
```

![Playground：两个浏览器窗口在同一个房间，各自控制一个点，另一边的点会平滑地跟上。](https://hibira.io/portal/articles/godot-playground-zh-CN.mp4)

需要说清楚的是，HibiraSync 适合派对游戏、合作游戏、桌游这类“大家都是朋友”的游戏。每位玩家对自己的角色有完全的控制权，它不是服务器权威的网络同步，竞技游戏要防作弊的话，仍然需要由服务器做判定。

## 五分钟上手

1. 从 [GitHub](https://github.com/hibira-io/godot) 下载 `addons/hibira`，放进项目的 `addons/` 文件夹，然后在 **项目 → 项目设置 → 插件** 里启用 Hibira Realtime。
2. 打开 `addons/hibira/demo/playground.tscn`，按 F6。无需任何设置，它会连到我们的公开演示 app，创建一个四个字母的房间代码。
3. 在 **调试 → 自定义运行实例** 里把实例数改成 2 再运行一次，就能看到两个点在同一个房间里互相移动。

想直接在浏览器里试，可以打开[在线 playground](https://demos.hibira.io/godot/)，它就是同一个场景导出成网页版的结果。把链接连同房间代码发给朋友，对方打开就会进到同一个房间。Playground 的每个窗口都是一位新玩家。换成你自己的游戏时，用同一个账号登录的两个窗口在房间里只算一位成员，所以测试时要用两个账号，例如另开一个浏览器或无痕窗口。

换成你自己的 app 时，先在 Hibira 后台设置好：从 app 的 **Overview → Credentials** 复制 **key**（secret 只在创建 app 时显示一次，而且只放在你的后端）；打开 **Settings → Allow client events**；导出网页版的话，把网页的来源（例如 `https://yourname.itch.io`）加进 **Settings → Allowed origins**。免费方案不接受 `*`，没有加入来源的话，浏览器会连不上。你的鉴权接口用任何兼容 Pusher 的后端都能签 `presence-` 频道；Node 可以直接用 @hibira-io/lobby 的 `authorizeRoom()`。

接着在项目设置的 **Hibira** 区块填上 app key 和鉴权接口即可。插件会加入一个叫 `Hibira` 的 autoload，游戏启动时自动连接，任何脚本都可以直接用：

```gdscript
func _ready() -> void:
	var lobby := HibiraRoom.join(Hibira, "presence-room-ABCD", {"capacity": 4})
	lobby.message_received.connect(func(m): print(m.info.name, ": ", m.text))
	lobby.started.connect(func(data, _by): start_game(data))
```

## 完整的例子：反应速度游戏

为了确认这些零件拼在一起真的能做出一款游戏，我们用它做了一个四人反应速度小游戏：房间列表、四个座位、房主、准备、踢人、房间聊天，以及五回合“看到 GO! 就按”。

![房间列表：创建房间，或用代码加入朋友的房间。](https://hibira.io/portal/articles/godot-lobby-rooms-zh-CN.webp)

![游戏画面：房主开始后，每一次点击都是房间频道上的一条 client 事件。](https://hibira.io/portal/articles/godot-lobby-game-zh-CN.webp)

它和我们的网页版大厅示例使用同一组事件，所以 Godot 玩家和浏览器玩家可以一起玩。完整源码在 [examples/godot-lobby](https://github.com/hibira-io/examples/tree/main/godot-lobby)。

## 费用与限制

- 每条 client 事件算一条消息，不管有多少人收到。四个人玩五回合，大约几十条消息。免费方案每天有 20 万条，做原型和小规模测试绰绰有余。
- HibiraSync 默认每秒最多 8 条（可以在项目设置里调整，上限 10），而且只在有变化时才发。四个人一直在移动的话，一小时最多约 11 万条；站着不动时不计。
- 免费方案每条事件的数据上限是 4 KB（付费方案更大）。HibiraSync 会把批次切在这个大小以下；单个值（例如很长的字符串）请保持精简。
- presence 频道最多 100 位成员，对房间来说足够了；更大的场景（例如上千人的大厅）适合改用普通频道配合服务器端广播。

## 接下来

插件已经可以在 [GitHub](https://github.com/hibira-io/godot/releases) 下载，也已经提交到 Godot Asset Library 上架。接下来我们想加上端到端加密频道和用户登录（`pusher:signin`）。

如果你正在用 Godot 做多人游戏，欢迎试试看，也很想听听你的游戏需要什么。
