1739 字
9 分钟
失落的龙约私服联机教程(下):Luxon 联机插件的完整移植与部署

前言#

上篇用两条路线解决了联机服务器的「有无」问题,其中 LuxonServer 路线当时只覆盖了建房和进房:房主点了「开始任务」,客户端会永远停在等待界面——因为战斗开局、结算上报、房间复用这些业务逻辑全在插件里,而上篇只移植了进门那一半。

本文把另一半补完。插件源码已整理开源:luxon-gluon-plugin,本文是其部署手册,也是移植过程里踩坑记录的沉淀。上篇的 Photon v4 路线不受影响。

插件的协议职责#

把 C# 参考实现(Dawnshard 的 GameLogicPlugin / StateManagerPlugin)逐回调对照后,一个「能打完一局」的联机插件至少要做四件事:

阶段触发插件动作
开局握手房主点开始,客户端逐级上报 GoToIngameState 1→4计算全员最小值:min=1 下发房间属性 GoToIngameInfo;min=2 插件向游戏 API 拉 heroparam/batch;min=3 广播 Party(0x3e);min=4 广播 CharacterData(0x14)
就绪聚合各端载入完成上报 Ready(0x03)全员就绪后广播 StartQuest(0x15),正式进图
对局生命周期战斗内事件死亡(0x48)记账;通关 ClearQuestRequest(0x3f) 解包后转发游戏 API record_multi,响应以 ClearQuestResponse(0x40) 单播回传;失败(0x43→0x44)、全灭、房主 GameSucceed(0x18) 重置房间复用
房间列表建房/进房/退房/关房/属性变更推送 GameCreate / GameJoin / GameLeave / GameClose / RoomId / Visible / MatchingType / EntryConditions 给 PhotonStateManager——公开列表和按 ID 搜房的数据源

另有三个细节容易漏:进房拒绝规则(满员 ≥4、对局进行中、无房主)、房主退出广播 RoomBroken(0x17) 且余员全就绪时补发 StartQuest、随机匹配房 30 秒自动开局定时器。

仓库结构#

luxon-gluon-plugin/
├── CMakeLists.txt # 经 luxon_register_plugin() 接入 Luxon 构建体系
├── gluon.cpp # 插件全部实现
├── quest_tables.h # raid/ranked/random matching 任务表(脚本生成)
└── patches/
└── handler_gameserver.cpp # Luxon 服务端 handler 的修改版

patches/ 里的文件不是插件的一部分,而是 Luxon 源码树 src/handler_gameserver.cpp 的修改版——v4 客户端兼容补丁都打在这里:GS InitResponse 必须携带 ResponseObject 字段、Join 响应必须携带 PluginName/PluginVersion、ViewerId 注入必须在请求属性落库之后执行(否则被整表覆盖)。缺任何一处,客户端在房间阶段就静默卡死 30 秒。

构建#

Luxon 走 vcpkg manifest 模式(依赖 mbedtls 等),首次配置会自己拉依赖:

Terminal window
# 源码树与插件目录
git clone https://github.com/niansa/LuxonServer /opt/luxon-src
# 服务端补丁
cp patches/handler_gameserver.cpp /opt/luxon-src/src/
# 插件目录放到任意位置
git clone https://github.com/Anyuluo996/luxon-gluon-plugin /opt/gluon-plugin
cmake -S /opt/luxon-src -B /opt/luxon-build \
-DCMAKE_BUILD_TYPE=Release \
-DLUXON_SERVER_ENABLE_PLUGINS=ON \
-DLUXON_PLUGINS=/opt/gluon-plugin
cmake --build /opt/luxon-build -j

产物是单文件 /opt/luxon-build/luxon_server,插件以静态库整档链接进二进制,没有运行时加载这回事——改插件必须整体重编。

部署#

systemd 单位示例:

[Unit]
Description=Luxon Server
After=network.target
[Service]
Type=simple
WorkingDirectory=/opt/luxon-test
EnvironmentFile=/etc/luxon-gluon.env
ExecStart=/opt/luxon-test/luxon_server
Restart=on-failure
RestartSec=2
[Install]
WantedBy=multi-user.target

替换二进制的固定流程,三步都不能省:

Terminal window
systemctl stop luxon-server # 不停服 cp 会撞 ETXTBSY(文件被运行中进程占用)
cp /opt/luxon-build/luxon_server /opt/luxon-test/luxon_server
md5sum /opt/luxon-build/luxon_server /opt/luxon-test/luxon_server # 必须核对一致
systemctl start luxon-server

md5 核对不是强迫症: cp 和 systemd start 之间任何脚本短路都会造成「看起来部署了、跑的还是旧版」,排查时会把人引向完全错误的方向。

配置#

全部走环境变量,无配置文件:

变量默认值说明
GLUON_API_HOST127.0.0.1游戏 API 地址
GLUON_API_PORT18080游戏 API 端口
GLUON_API_TOKEN无与游戏 API PhotonOptions__Token 一致,必填
GLUON_SM_HOST同 API_HOSTPhotonStateManager 地址
GLUON_SM_PORT8081PhotonStateManager 端口

Token 属于敏感信息,用 EnvironmentFile 注入并把文件权限收到 600,不要写进 unit 文本或任何进仓库的地方:

Terminal window
printf 'GLUON_API_TOKEN=<与游戏API一致的Token>\n' > /etc/luxon-gluon.env
chmod 600 /etc/luxon-gluon.env

游戏 API 侧记得 PhotonOptions__Token 配同一个值——结算上报的 record_multi 请求同时要求这个 Bearer 头和 Auth-ViewerId 头,两侧不一致的表象是「战斗能打、通关卡死」。

验证清单#

部署完按顺序过一遍,每步都有明确的日志锚点(journalctl -u luxon-server 里 [Gluon] 前缀):

步骤操作日志锚点
建房房主建房OnCreateGame: injected RoomId=;statemanager 收到 GameCreate
进房客人按 ID 加入OnJoinGame: injected ViewerId;GameJoin 已推送
ID 搜房第三方界面按房号搜/matching/get_room_name 能返回房间
准备+开始全员准备,房主开始OnSetGoToIngameState: computed min 逐级上涨到 4,中途出现 RequestHeroParam: fetched N actor entries
进图加载完成Raised Party event → Raised CharacterData events → Raising event 0x15
结算打完通关ClearQuestResponse sent to actor N;API 侧 record_multi 200
续战/退房结果页确认双方 GoToIngameState=0 回房;退房时 RoomBroken 广播

游戏 API 侧同步确认:/heroparam/batch 与 /dungeon_record/record_multi 都是 200。

踩坑实录#

移植过程中有三个坑值得单独记录,都属于「抓包/单测定案后五分钟修完、不定案三天出不来」的类型。

其一:客户端的 LZ4 是 v1 格式。 通关事件(0x3f)的载荷带 MessagePack 压缩包装。按 MessagePack-C# v2 文档实现 Lz4Block(ext type −103,多块结构)后线上解析依然失败,加诊断打出原始字节:c9 00 00 02 75 63 d2 …——ext type 是 0x63(+99),body 是 [int32 总长][单个裸 LZ4 块]。Dragalia 客户端是 2018 年的代码,用的是 v1 时代 LZ4MessagePackSerializer 的老格式。现在 unwrap_lz4block 两种 type 都收。教训:跨版本协议实现,第一个怀疑对象就是文档没写的旧格式。

其二:HTTP 响应头的末行陷阱。 自写的 HTTP 客户端逐行解析响应头,find("\r\n") 找不到换行就 break——但头缓冲区本身不含结尾 CRLF,于是最后一个头永远没被解析。Kestrel 恰好把 Transfer-Encoding: chunked 放在最后,导致 chunk 分帧原样进了 JSON 解析器,表象是「API 返回 200 但内容是乱码」。修法是给头缓冲区补一个终止符再逐行扫。教训:手写解析器要专门测「字段恰好处于末尾」的用例。

其三:msgpack 数组格式的稀疏 Key。 HeroParam 的 Key 从 0 一路跳到 160,序列化时数组长度是 maxKey+1,空缺下标必须写 nil;另外空 Dictionary 和空匿名对象都编码为 0x80(空 map)而不是空数组。这些没法从文档推断,直接用 .NET 写十行程序调 MessagePack-C# 打印字节最快。

还有一条方法论:给插件的每条协议链路预埋 [Gluon] 日志锚点,等价于在暗巷里装路灯。上述三个坑平均定位时间不超过一轮真机测试,全靠日志里那行十六进制。

已知边界#

  • 随机匹配房的 30 秒自动开局已实现(主循环定时器),但仅经代码路径验证,未在真机用随机匹配任务完整走一遍;
  • EntryConditions 解析覆盖数组格式(官方序列化格式),map 格式为容错分支;
  • 房间状态不持久化,联机服务器重启即丢房间。

参考#

失落的龙约私服联机教程(下):Luxon 联机插件的完整移植与部署
https://blog.anyul.cn/posts/dragalia-luxon-plugin-deploy/
作者
安雨落
发布于
2026-09-10
许可协议
CC BY-NC-SA 4.0

分享文章

生成精美分享图或复制链接,与更多人分享本文。

继续阅读

沿着主题读

基于共同的标签与分类