让 Godot 游戏多人联机,不用自己搭游戏服务器
· Hibira
我们为 Godot 4 做了一个纯 GDScript 的 Hibira 插件:房间、聊天、玩家位置同步,网页导出也能用。我们为什么做它、它怎么工作,以及五分钟跑起来的演示。

有一天团队里有人问了一句:“Godot 支持 Pusher 协议吗?”
答案是不支持。Godot 4 内置了 WebSocket,也有一整套高层多人联机 API,但它们都假设你自己有一台游戏服务器,或者让其中一位玩家当主机。对很多小团队来说,这正是做多人游戏最卡的地方:游戏本身做好了,却还得学怎么搭服务器、怎么开端口、怎么处理 NAT,最后还要每个月为一台不知道会有多少人用的主机付钱。
我们想要另一种做法:游戏里只放一个客户端,连到托管的实时服务,房间、在线名单和玩家之间的消息都交给它转发。于是我们做了 Hibira 的 Godot 插件。它是纯 GDScript,不需要原生扩展,Godot 能导出的平台它都能跑,网页也包括在内。

小型多人游戏真正需要什么
不是每款多人游戏都是射击游戏。我们看了看身边的独立游戏和 Game Jam 作品,多人功能大多是这几种:
- 大厅和房间:建一个房间、拿到一组代码、分享给朋友、等大家点“准备”。
- 谁在线:房间里有谁、谁刚加入、谁离开了、谁是房主。
- 聊天:包括“对方正在输入…”。
- 轻量同步:合作游戏里大家的位置、派对游戏里谁先按下按钮、回合制游戏的下一步。
这些需求有个共同点:消息都很小,延迟要求是“人能感觉到的快”,而不是射击游戏那种每一毫秒都要算的快。它们很适合用一条 WebSocket 加上“频道”的模型来处理,这正是 Pusher 协议擅长的。
为什么选 Pusher 协议
Pusher 协议已经存在十多年,模型很简单:客户端订阅频道,服务器或其他客户端往频道发事件。对游戏来说,最有用的是 presence 频道:
- 订阅时由你的后端签名,所以由你决定谁能进哪个房间。
- 频道会告诉每个人当前的成员名单,以及谁加入、谁离开。
- 玩家之间可以直接发 client 事件,而且服务器会在每一条事件上盖上发送者的
user_id。
最后一点很关键。因为 user_id 是服务器盖的,不是客户端自己填的,所以收到“玩家 A 移动到这里”时,你可以确定这条消息真的来自玩家 A。后面的位置同步就建立在这个保证上。
另一个好处是:协议相同,网页和游戏就能互通。我们的网页大厅 SDK @hibira-io/lobby 用的是同一组事件,所以 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,然后这样生成每位玩家:
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 次的更新如果直接套用,画面会一格一格地跳。所以收到的值会被当作目标,角色每一帧往目标靠近一点,旋转角度和四元数也有对应的插值。
需要说清楚的是,HibiraSync 适合派对游戏、合作游戏、桌游这类“大家都是朋友”的游戏。每位玩家对自己的角色有完全的控制权,它不是服务器权威的网络同步,竞技游戏要防作弊的话,仍然需要由服务器做判定。
五分钟上手
- 从 GitHub 下载
addons/hibira,放进项目的addons/文件夹,然后在 项目 → 项目设置 → 插件 里启用 Hibira Realtime。 - 打开
addons/hibira/demo/playground.tscn,按 F6。无需任何设置,它会连到我们的公开演示 app,创建一个四个字母的房间代码。 - 在 调试 → 自定义运行实例 里把实例数改成 2 再运行一次,就能看到两个点在同一个房间里互相移动。
想直接在浏览器里试,可以打开在线 playground,它就是同一个场景导出成网页版的结果。把链接连同房间代码发给朋友,对方打开就会进到同一个房间。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,游戏启动时自动连接,任何脚本都可以直接用:
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! 就按”。


它和我们的网页版大厅示例使用同一组事件,所以 Godot 玩家和浏览器玩家可以一起玩。完整源码在 examples/godot-lobby。
费用与限制
- 每条 client 事件算一条消息,不管有多少人收到。四个人玩五回合,大约几十条消息。免费方案每天有 20 万条,做原型和小规模测试绰绰有余。
- HibiraSync 默认每秒最多 8 条(可以在项目设置里调整,上限 10),而且只在有变化时才发。四个人一直在移动的话,一小时最多约 11 万条;站着不动时不计。
- 免费方案每条事件的数据上限是 4 KB(付费方案更大)。HibiraSync 会把批次切在这个大小以下;单个值(例如很长的字符串)请保持精简。
- presence 频道最多 100 位成员,对房间来说足够了;更大的场景(例如上千人的大厅)适合改用普通频道配合服务器端广播。
接下来
插件已经可以在 GitHub 下载,也已经提交到 Godot Asset Library 上架。接下来我们想加上端到端加密频道和用户登录(pusher:signin)。
如果你正在用 Godot 做多人游戏,欢迎试试看,也很想听听你的游戏需要什么。