WebSocket API 參考

協議概覽

屬性	值
WebSocket URL	ws://localhost:65530/ws
協議版本	RFC 6455
訊息格式	JSON
字元編碼	UTF-8
認證	無需認證

連接生命週期

1. 建立連接: 客戶端連接到 WebSocket 端點
2. 訊息交換: 雙向即時訊息傳輸
3. 錯誤處理: 自動重連機制
4. 連接關閉: 優雅關閉或異常斷線

基本訊息結構

所有 WebSocket 訊息都遵循統一格式：

interface Message<T> {
    type: string;    // 訊息類型識別符
    payload: T;      // 訊息內容，可為任意類型
}

資料模型

核心介面

Message<T>

基礎訊息包裝器

欄位	類型	必填	描述
type	string	✓	訊息類型識別符
payload	T		訊息內容，根據類型而定

Health

玩家健康狀態

欄位	類型	必填	描述
health	number	✓	血量 (0-20)
food	number	✓	飢餓值 (0-20)
saturation	number	✓	飽食度

Experience

經驗值資訊

欄位	類型	必填	描述
experience_bar	number	✓	經驗條進度 (0-1)
level	number	✓	等級
total_experience	number	✓	總經驗值

McfalloutInfo

伺服器特定資訊

欄位	類型	必填	描述
flight_seconds	number	✓	飛行秒數
total_flight_seconds	string	✓	總飛行時間 (字串格式)
emerald_balance	number	✓	綠寶石餘額
coin_balance	number	✓	金幣餘額
coin_price	number	✓	金幣價格
cur_server	number	✓	當前伺服器編號

PlayerPosition

玩家位置資訊

欄位	類型	必填	描述
x	number	✓	X 座標
y	number	✓	Y 座標
z	number	✓	Z 座標
yaw	number	✓	偏航角
pitch	number	✓	俯仰角

FooterData

頁尾狀態資料

欄位	類型	必填	描述
Status	string	✓	當前狀態
Pos	Position	✓	位置資訊
Server	number	✓	伺服器編號
Emerald	number	✓	綠寶石數量
Villager	number	✓	村民數量
TPS	number	✓	伺服器 TPS

Position

三維位置

欄位	類型	必填	描述
x	number	✓	X 座標
y	number	✓	Y 座標
z	number	✓	Z 座標

背包系統

Slot

背包槽位

欄位	類型	必填	描述
id	number	✓	物品 ID
count	number	✓	物品數量
NBT	SlotItem		NBT 資料

SlotItem

物品 NBT 資料

欄位	類型	必填	描述
display	Display		顯示資訊
SkullOwner	SkullOwner		頭顱擁有者
Enchantments	Enchantment[]		附魔列表
StoredEnchantments	Enchantment[]		儲存的附魔
Damage	number		耐久度損傷
RepairCost	number		修復成本
Unbreakable	boolean		是否無法破壞
HideFlags	number		隱藏標誌
PublicBukkitValues	PublicBukkitValues		Bukkit 自訂值
MapID	number		地圖 ID
MapColor	number		地圖顏色
Potion	string		藥水類型
CustomModelData	number		自訂模型資料
BlockEntityTag	BlockEntityTag		方塊實體標籤

Display

物品顯示資訊

欄位	類型	必填	描述
Name	string	✓	顯示名稱
Lore	string[]	✓	物品說明

SkullOwner

頭顱擁有者資訊

欄位	類型	必填	描述
Name	string	✓	玩家名稱
Id	number[]	✓	UUID 陣列
Properties	Textures	✓	貼圖屬性

Textures

貼圖資訊

欄位	類型	必填	描述
textures	TextureData[]	✓	貼圖資料陣列

TextureData

貼圖資料

欄位	類型	必填	描述
Value	string	✓	Base64 編碼的貼圖資料
Signature	string	✓	數位簽章

Enchantment

附魔資訊

欄位	類型	必填	描述
id	string	✓	附魔 ID
lvl	number	✓	附魔等級

PublicBukkitValues

Bukkit 自訂值

欄位	類型	必填	描述
[key: string]	string		鍵值對映

BlockEntityTag

方塊實體標籤

欄位	類型	必填	描述
Items	SlotItem[]	✓	物品列表
id	string	✓	實體 ID

SlotWithIndex

帶索引的槽位

欄位	類型	必填	描述
index	number	✓	槽位索引
item	Slot	✓	槽位物品

任務系統

Task

建造任務 (詳細定義請參考 REST API 文檔)

ProcessUpdate

後處理進度更新

欄位	類型	必填	描述
current_map_uuid	string	✓	當前處理的地圖 UUID

日誌系統

ChatMessage

聊天訊息格式

欄位	類型	必填	描述
text	string	✓	訊息文字
bold	boolean		是否粗體
italic	boolean		是否斜體
underlined	boolean		是否底線
strikethrough	boolean		是否刪除線
obfuscated	boolean		是否混亂
font	string		字型
color	string		顏色
insertion	string		插入文字
clickEvent	ClickEvent		點擊事件
hoverEvent	HoverEvent		懸停事件
translate	string		翻譯鍵
with	ChatMessage[]		翻譯參數
extra	ChatMessage[]		額外內容

ClickEvent

點擊事件

欄位	類型	必填	描述
action	ClickAction | string	✓	動作類型
value	string	✓	動作值

HoverEvent

懸停事件

欄位	類型	必填	描述
action	string	✓	動作類型
contents	any	✓	內容
value	ChatMessage	✓	顯示值

ClickAction

點擊動作類型

值	描述
open_url	開啟網址
run_command	執行指令
suggest_command	建議指令

SpecificLog

特定標籤日誌

欄位	類型	必填	描述
Tag	string	✓	日誌標籤
Message	string	✓	日誌訊息

訊息目錄

伺服器 → 客戶端訊息

分類	訊息類型	載荷類型	描述
遊戲狀態	health	Health	玩家健康狀態
	experience	Experience	經驗值資訊
	mcfallout_info	McfalloutInfo	伺服器特定資訊
	tps	number	伺服器效能
	player_position	PlayerPosition	玩家位置
	auth	number	驗證剩餘時間
背包管理	inventory_content	Slot[]	背包內容
	inventory_update	SlotWithIndex	背包物品更新
	inventory_open	number	背包開啟
	player_carried_item	number	玩家手持物品
狀態資訊	footer	FooterData	頁尾狀態資料
	connection	boolean	連接狀態
任務管理	update_task	Task[]	任務列表更新
	update_history	Task[]	歷史任務更新
後處理	process_update	ProcessUpdate	處理進度更新
	process_success	string	處理成功
	state_update	string	狀態更新
	name_update	{}	名稱更新
日誌系統	log	ChatMessage	一般日誌
	debug	ChatMessage	除錯日誌
	specific_log	SpecificLog	特定標籤日誌
	error	string	錯誤訊息
	shared	any	共享資料
系統狀態	backend_version	string	後端版本
	debugMode	boolean	除錯模式
	exitConfirmMode	boolean	退出確認模式
	cpu_usage	string	CPU 使用率
	mem_usage	string	記憶體使用率
	profile_dialog	string	效能分析對話框

客戶端 → 伺服器訊息

分類	訊息類型	載荷類型	描述
遊戲互動	click_window	ClickWindow	點擊視窗
	scroll_inventory	1 | -1	滾動背包
	input	string	輸入指令
資料查詢	get_inventory_content	{}	取得背包內容
	get_player_carried_item	{}	取得手持物品
	get_player_info	{}	取得玩家資訊
	get_health	{}	取得健康狀態
	get_experience	{}	取得經驗值
	get_mcfallout_info	{}	取得伺服器資訊
	get_tps	{}	取得伺服器 TPS
	get_player_position	{}	取得玩家位置
	get_auth	{}	取得驗證資訊
	get_backend_version	{}	取得後端版本
	get_debug_mode	{}	取得除錯模式
	get_exist_confirm_mode	{}	取得退出確認模式
	get_connection	{}	取得連接狀態
設定變更	set_exist_confirm_mode	boolean	設定退出確認模式

詳細規格

遊戲狀態訊息

health

玩家健康狀態更新

觸發條件: 玩家血量、飢餓值或飽食度變化 更新頻率: 實時

experience

經驗值資訊更新

觸發條件: 玩家獲得或失去經驗值 更新頻率: 實時

mcfallout_info

McFallout 伺服器特定資訊

觸發條件: 伺服器資料更新 更新頻率: 定期

tps

伺服器效能指標

觸發條件: TPS 計算完成 更新頻率: 定期 (通常每秒)

player_position

玩家位置資訊

觸發條件: 玩家移動 更新頻率: 高頻率

auth

驗證剩餘時間

觸發條件: 驗證狀態檢查 更新頻率: 定期

背包管理訊息

inventory_content

完整背包內容

觸發條件: 背包內容重大變化或主動查詢 資料格式: 陣列，null 表示空槽位

inventory_update

單一槽位更新

觸發條件: 特定槽位物品變化 用途: 增量更新，避免全量傳輸

inventory_open

背包開啟事件

載荷: 容器 ID 或 0 表示玩家背包

player_carried_item

手持物品變化

載荷: 選中的快捷欄槽位 (0-8)

狀態資訊訊息

footer

頁尾狀態資料

觸發條件: 狀態資料更新 用途: UI 頁尾顯示

connection

連接狀態變化

載荷: true=已連接, false=已斷開 用途: 連接狀態指示器

任務管理訊息

update_task

任務列表更新

觸發條件: 任務新增、修改或狀態變化 載荷: 完整任務陣列

update_history

歷史任務更新

觸發條件: 任務完成或歷史記錄變化 載荷: 歷史任務陣列

後處理訊息

process_update

後處理進度更新

觸發條件: 地圖處理進度變化 用途: 進度追蹤

process_success

處理完成通知

觸發條件: 後處理任務成功完成 載荷: 成功訊息文字

state_update

狀態更新通知

觸發條件: 處理狀態變化 載荷: 狀態描述文字

name_update

名稱更新通知

觸發條件: 地圖名稱更新完成 載荷: 空物件 用途: 通知客戶端重新獲取地圖列表

日誌系統訊息

log

一般系統日誌

載荷: ChatMessage 格式 用途: 系統運行日誌

debug

除錯日誌

載荷: ChatMessage 格式 用途: 開發除錯資訊

specific_log

特定標籤日誌

用途: 分類日誌記錄 標籤範例: "building", "scanning", "copying"

error

錯誤訊息

載荷: 錯誤描述字串 用途: 錯誤通知

shared

共享資料

載荷: 任意格式資料 用途: 跨組件資料共享

系統狀態訊息

backend_version

後端版本資訊

載荷: 版本字串 (如 "v1.0.0")

debugMode

除錯模式狀態

載荷: boolean 值

exitConfirmMode

退出確認模式狀態

載荷: boolean 值

cpu_usage

CPU 使用率

載荷: 百分比字串 (如 "15.5%")

mem_usage

記憶體使用率

載荷: 使用量字串 (如 "512MB/2GB")

profile_dialog

效能分析對話框

載荷: 分析結果或狀態訊息

客戶端請求訊息

ClickWindow

視窗點擊請求

欄位	類型	必填	描述
index	number	✓	槽位索引
button	number	✓	按鈕類型 (0=左鍵, 1=右鍵)
mode	number	✓	點擊模式 (0=正常, 1=Shift, 4=丟棄)

click_window

點擊視窗操作

用途: 模擬玩家點擊背包槽位 載荷: ClickWindow 物件

scroll_inventory

滾動背包

載荷: 1 (向上) 或 -1 (向下) 用途: 切換快捷欄選中項

input

輸入指令

載荷: 指令字串 用途: 發送聊天訊息或指令

資料查詢請求

所有 get_* 類型的請求都使用空物件 {} 作為載荷，用於主動查詢對應的狀態資訊。

set_exist_confirm_mode

設定退出確認模式

載荷: boolean 值 用途: 開啟或關閉退出確認對話框