# 讓 Godot 遊戲多人連線，不用自己架遊戲伺服器

> 我們為 Godot 4 做了一個純 GDScript 的 Hibira 插件：房間、聊天、玩家位置同步，網頁匯出也能用。我們為什麼做它、它怎麼運作，以及五分鐘跑起來的示範。

Source: https://hibira.io/zh-tw/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-TW.webp)

## 小型多人遊戲真正需要的是什麼

不是每款多人遊戲都是射擊遊戲。我們看了一下身邊的獨立遊戲和遊戲活動，多人功能大多是這幾種：

- **大廳和房間**：建一個房間、拿到一組代碼、分享給朋友、等大家按「準備」。
- **誰在線上**：房間裡有誰、誰剛加入、誰離開了、誰是房主。
- **聊天**：包括「對方正在輸入…」。
- **輕量的同步**：合作遊戲裡大家的位置、派對遊戲裡誰先按下按鈕、回合制遊戲的下一步。

這些需求有個共同點：訊息都很小，延遲要求是「人感覺得到的快」，而不是射擊遊戲那種每一毫秒都要算進去的快。它們很適合用一條 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-TW.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-TW.webp)

![遊戲畫面：房主開始之後，每一次點擊都是房間頻道上的一則 client 事件。](https://hibira.io/portal/articles/godot-lobby-game-zh-TW.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 做多人遊戲，歡迎試試看，也很想聽聽你的遊戲需要什麼。
