# Godot 联机接入与 UI 草案 > 状态:讨论稿 > 日期:2026-09-18 > 前提:Godot C# 客户端、FunGame.Core 规则、OSM 内容模块、服务器权威计算。 ## 1. 设计目标 Godot 客户端从第一版起就按“可联机”设计,即使最初只连接本机 WebAPI,也不允许战斗 UI 直接修改规则对象。 核心原则: 1. **一个客户端,三种部署方式**:本机单人、房主权威 P2P、专用服务器共享同一套协议和界面。 2. **权威端计算**:客户端只发送意图,不能自行决定伤害、命中、效果或行动是否合法。 3. **显示与规则解耦**:Godot 只消费 DTO/视图模型,不引用服务器内部的 `Character`、`Skill` 和 `GamingQueue` 对象。 4. **状态可恢复**:任意时刻收到完整快照,客户端都能重建战场;动画不是权威状态。 5. **输入方式无关**:鼠标、触屏和手柄最终都产生相同的决策命令。 ## 2. 三种部署方式 | 模式 | 权威计算位置 | 适用场景 | 主要代价 | |---|---|---|---| | 本机单人 | 本机 WebAPI/游戏服务 | 开发、离线、单人剧情 | 打包和进程管理 | | 房主模式 | 房主设备的监听服务器 | 好友房、局域网、低成本联机 | 房主可作弊;房主退出会终止对局 | | 专用服务器 | Server-v3 或其后续服务 | 排位、公开房、长期运营 | 部署、账号、监控和带宽成本 | ### 2.1 本机单人 Godot 启动或连接本机服务,仍通过与联机相同的消息协议进行游戏。这样单机版不会形成第二套战斗逻辑。 开发期可以手动启动 WebAPI;发行期再决定使用子进程、内嵌宿主或随游戏启动的本机服务。进程生命周期、端口冲突和崩溃恢复需要单独设计。 ### 2.2 P2P:建议采用房主权威 这里的 P2P 建议定义为 **listen server(房主既是玩家也是服务器)**,而不是所有客户端各自运行规则后做确定性锁步。 原因:FunGame.Core 有丰富的可变效果、同步询问和随机过程,现阶段强行做确定性锁步会显著增加状态一致性和调试成本。房主权威可以直接复用 WebAPI 的会话思路。 - 局域网/直连:房主开放 WebSocket 服务,其他玩家通过地址加入。 - 互联网直连:还需要大厅/信令、端口映射、STUN/TURN 或中继服务;单有 P2P 按钮并不能解决 NAT 穿透。 - 公平性:房主能够修改进程和结果,因此该模式适合好友娱乐,不适合有强公平要求的排位。 - 第一版不建议做房主迁移;房主离开即保存记录并结束对局,复杂度更可控。 ### 2.3 专用服务器 Godot 连接 Server-v3,由服务端完成登录、房间、准备、匹配、战斗、重连和记录。现有 Server-v3 已有外围框架,但仍需把 Solo 会话的真人决策桥接扩展到多连接、多玩家和多角色控制。 ## 3. 统一客户端分层 ```text Godot 场景与控件 ↓ 读取 ViewModel / 提交 Intent BattleStore(当前权威快照 + 本地选中态) ↓ GameSession(请求关联、状态机、重连、心跳) ↓ IGameTransport ├─ WebSocketTransport:本机、房主、专服 └─ MockTransport:UI 演示和自动测试 ``` 建议的 Godot Autoload: - `GameSession`:连接状态、消息分派、请求 ID、心跳、重连和退出。 - `BattleStore`:保存最后一个权威快照和短暂的本地 UI 状态,发出细粒度更新信号。 - `AssetCatalog`:角色/技能/状态 ID 到纹理、名称和占位图的映射。 - `UiRouter`:大厅、选人、战斗、结算和错误页之间切换。 - `GameSettings`:音量、语言、画面、输入和无障碍设置。 服务器项目和 OSM 内容模块不应成为 Godot UI 程序集的直接依赖。可以建立一个轻量的“协议契约”C# 项目,仅存放信封、DTO、枚举和序列化设置,由 WebAPI、Server-v3 和 Godot 共同引用。 ## 4. 协议演进建议 现有 `t/i/ok/d/ts/error` 信封可以保留。正式联机版建议逐步增加: - `protocolVersion`:客户端与服务器协议版本。 - `gameId` / `sessionId`:避免重连或多局消息串线。 - `stateRevision`:每次权威状态变化递增,用于丢包、乱序和去重判断。 - `requestId` 与 `deadline`:决策属于哪个请求、服务端何时超时。 - `clientActionId`:客户端重试时保持幂等。 - `actorUserId` / 控制关系:服务器明确哪个连接可控制哪些角色。 - `capabilities`:协商压缩、增量状态、观战和回放等能力。 - 结构化拒绝原因:状态过期、目标非法、资源不足、非当前玩家等。 - 重连令牌:短期恢复连接,不把登录凭据直接当对局凭据使用。 客户端只能提交类似下面的意图: ```text 选择行动类型 → 选择 skillId/itemId → 选择 targetCharacterIds/gridIds → 确认 ``` 客户端不能提交“造成 120 点伤害”或“给目标添加效果”之类的结果。 ## 5. 战斗视觉与界面布局 视觉方向已确定为:**类似《少女前线 2:追放》的斜俯视战场、半隐藏战棋格、全屏地图与贴边悬浮 HUD,人物明确使用纯 2D 素材。**参考对象只用于镜头、信息层级和交互节奏,不复刻其美术、图标或具体版式。 结合本项目以 2D 素材为目标,本文先按“2D 场景 + 2D 人物”的斜投影方案设计;若后续确定采用“3D 场景 + 2D 人物”,网络协议、逻辑格和 HUD 均可保留,只替换战场渲染与遮挡实现。 地图分层、图块尺寸、规则数据和美术拆分详见[《Godot 地图与素材制作建议》](./Godot地图与素材制作建议.md)。 第一版以 **16:9 横屏桌面** 为基准。地图始终铺满整个视口,HUD 不再把画面硬切成左、中、右三栏: ```text ┌─菜单 / 回合 / 任务──────────────精简行动队列────────网络 / 暂停─┐ │ │ │ 全屏斜俯视 2D 战场 │ │ 平时隐藏格子;移动、攻击、目标选择时局部显现 │ │ 单位头顶只保留 HP、效果和掩体等必要信息 │ │ │ │ 当前角色头像与资源 技能 / 物品 / 等待 / 结束行动 │ └──────────────────上下文提示 / 取消 / 确认────────────────────────┘ ``` - 左上:菜单、回合、胜利条件和任务进度。 - 上方中部:精简行动顺序;完整队列通过展开面板查看。 - 左下:当前角色头像、HP/MP/EP、决策点和关键状态。 - 右下:圆形或方形行动图标、技能/物品入口及结束行动。 - 底部中间:仅在目标选择期间出现“取消/确认”和选择计数。 - 角色详情、队伍、战斗日志从屏幕边缘抽屉式展开,不长期遮挡地图。 ### 5.1 纯 2D 斜俯视投影 当前推荐的全 2D 战场使用 `Node2D + Camera2D`。逻辑仍是二维整数格,显示层通过独立的 `GridProjector` 将服务器格子坐标投影到斜俯视画面: ```text screenX = (gridX - gridY) × cellWidth / 2 screenY = (gridX + gridY) × cellHeight / 2 - heightLevel × heightStep ``` 推荐先使用接近 2:1 的菱形/二等角投影,再根据人物比例调整 `cellWidth : cellHeight`。服务器只关心格子 ID、坐标、高度、通行和掩体规则,不依赖实际像素位置。 纯 2D 人物建议采用: - `AnimatedSprite2D`,脚底中心作为原点,至少准备四方向,正式品质以八方向更自然; - 独立的脚底阴影、选中环、受击闪烁和状态特效层; - `idle / move / attack / skill / hit / defeat` 为第一批必需动画; - 将来如需要更细腻的待机和换装,可在不改变网络协议的情况下换成 `Skeleton2D` 切片动画。 ### 5.2 Godot 场景分层 ```text BattleScreen (Node) ├─ BattleWorld (Node2D, y_sort_enabled) │ ├─ GroundLayer (TileMapLayer / 大图切片) │ ├─ GroundDecalLayer │ ├─ GridOverlay2D │ ├─ LowCoverLayer │ ├─ UnitsLayer (Node2D, y_sort_enabled) │ ├─ EffectsLayer │ ├─ TallPropsLayer │ └─ ForegroundOccluders ├─ BattleCamera (Camera2D) ├─ WorldInfoLayer (CanvasLayer) │ ├─ UnitBars │ ├─ CoverHints │ └─ TargetHints ├─ HudLayer (CanvasLayer) │ └─ SafeArea (MarginContainer, Full Rect) │ ├─ TopLeftMissionPanel │ ├─ TopTurnQueue │ ├─ BottomLeftCharacterPanel │ ├─ BottomRightActionDock │ └─ BottomContextBar └─ OverlayLayer (CanvasLayer) ├─ CharacterDetailDrawer ├─ TeamRosterDrawer ├─ BattleLogDrawer ├─ InquiryDialog ├─ PauseDialog ├─ ReconnectOverlay └─ ResultScreen ``` 地面可由 `TileMapLayer` 组合,也可以使用预绘的大型 2D 场景切片;两者都必须通过格子元数据与规则坐标对齐。HUD 使用 `Control`、容器和主题资源,不以固定像素定位。所有主要按钮设置鼠标、键盘和手柄焦点路径。 ### 5.3 半隐藏战棋格 网格不是场景贴图的一部分,而是单独的 `GridOverlay2D`。建议用一次性绘制或复用的多边形批次显示,不为每个格子常驻一个复杂控件。 网格状态: | 状态 | 表现 | |---|---| | 平时观察 | 全部隐藏;只保留必要的掩体标识和悬停轮廓 | | 选择移动 | 淡蓝显示可达格;不可达格不显示或低亮度显示 | | 路径预览 | 连接起点到目标格,显示消耗与终点轮廓 | | 选择攻击 | 有效目标淡红/橙,技能范围使用第二层半透明色 | | 范围技能 | 选中格高亮,受影响格以脉冲或描边预览 | | 等待服务器 | 保留已提交目标的细描边,禁止继续点击 | 透明度应允许玩家看清地面与掩体。颜色不能作为唯一信息,格子还需通过图案、边线或图标区分移动、攻击和危险范围。 鼠标拾取应由 `GridProjector` 将屏幕坐标反算为候选格,再用菱形边界确认;不依赖大量 `Area2D`。触屏和手柄则通过当前格坐标移动游标。 ### 5.4 遮挡、层级与掩体 纯 2D 斜俯视的关键风险是单位被墙体或前景遮住。处理规则如下: - 单位和低矮物件按脚底 `screenY` 排序;Godot 使用 `y_sort_enabled`,必要时给跨多格物件设置人工排序锚点。 - 高墙、屋顶、树冠和前景物拆成独立遮挡层,不能与地面烘焙成一张不可分离图片。 - 遮挡当前角色、鼠标格或目标时,以 Tween/Shader 将相关前景淡化到约 25%–45%,移开后恢复。 - 掩体规则来自服务器格子边缘数据,画面中的箱子和墙只是其视觉表现;不能通过贴图颜色推断是否有掩体。 - 建议地图数据预留 `walkable`、`heightLevel`、`terrainCost`、`blocksSight` 与四边掩体信息;最终字段名以 FunGame 地图模型的扩展方式为准。 镜头支持拖拽、边缘移动、滚轮缩放、聚焦当前行动者和查看目标。自动镜头只能平滑引导,玩家手动操作后应立即让出控制。 ### 5.5 决策与面板映射 | 服务器决策 | Godot 表现 | |---|---| | `SelectCharacter` | 选人页;卡片、详情、确认 | | `ActionType` | 右下行动坞;移动、攻击、技能、物品、等待 | | `Skill` | 右下技能图标展开;长按/悬停显示消耗、冷却和原因 | | `Item` | 右侧物品抽屉,不关闭战场视野 | | `Targets` | 单位与脚下格共同高亮;底部上下文栏确认 | | `TargetGrid` | 可选格子高亮;单选确认 | | `TargetGrids` | 多选计数、撤销与确认 | | `Inquiry` | 模态选项框,保留超时提示 | | `Continue` | 明确的继续/结束行动按钮 | 推荐交互顺序是“选中 → 预览 → 确认”,而不是点到单位立即提交。这样能兼容触屏误触和高延迟网络,也与现有 webui-solo 的验证方向一致。 ### 5.6 UI 状态机 ```text Disconnected → Connecting → Lobby/CharacterSelect → LoadingBattle ↘ Reconnecting ↗ ↓ Watching → ChooseAction → ChooseSkill/Item → ChooseTarget/Grid → WaitingServer ↑ ↓ └────────────────────── Applied / Rejected ──────────────────────┘ ↓ Paused / Finished ``` `WaitingServer` 期间可以显示已提交选择,但不得预演权威伤害结果。若服务器拒绝操作,恢复到服务器指定的决策状态并显示可理解的原因。 ## 6. 动画与状态同步 完整快照用于恢复,事件/差异用于表现: 1. `BattleStore` 保存旧快照和新快照。 2. 比较位置、HP、效果、队列和行动者变化。 3. 生成只影响表现的动画任务,例如移动、受击、数字飘字和效果图标。 4. 动画积压过多或重连时,允许快进并直接对齐最新快照。 不要让动画完成回调决定角色是否死亡,也不要为了动画暂停服务器状态更新。表现层可以落后,但最终必须追上最新的 `stateRevision`。 ## 7. 素材接入 当前项目已经有角色头像与技能图标,建议由 `AssetCatalog` 统一加载: - `assets/images/2d-game-icons/characters` - `assets/images/2d-game-icons/skills` - `assets/images/2d-game-icons/skills/borderless` 建议每个图标槽包含四层:底图、品质/阵营装饰、冷却/禁用遮罩、状态角标。角色头像素材本身保持无阵营和无边框,边框由主题控件统一渲染;这样换阵营、选中、受伤和死亡状态不需要生成多套位图。 战场人物需要另行建立完整的 2D 单位素材规范。角色头像不能直接充当棋盘单位;两者使用同一个角色 ID 关联,但分别服务于 HUD 和战场。建议先用方向明确的临时剪影验证投影、格子占位和遮挡,再批量制作正式角色动画,避免美术比例在地图定型后返工。 ## 8. 联机安全与公平性 - 随机种子和随机结果由权威端掌握并写入回合记录。 - 服务端校验行动者、资源、冷却、目标、距离、格子和请求时效。 - 客户端只接收自己有权看到的信息;未来若有战争迷雾,不能把隐藏单位发给客户端后仅靠 UI 隐藏。 - 所有重要选择带请求 ID,重复发送不会重复执行。 - 专用服务器保留行动记录、结果摘要和必要审计信息。 - 房主模式明确标记为非强公平模式,因为房主天然拥有服务器控制权。 ## 9. 分阶段实施 ### 阶段 0:契约与最小工程 - 固化消息信封、DTO、枚举和 JSON 设置。 - 建立 Godot C# 最小工程并验证目标 Godot/.NET 组合可构建、可导出。 - 建立 ID 到素材路径的清单和占位图策略。 ### 阶段 1:连接现有 Solo WebAPI - WebSocket 连接、心跳、错误和重连。 - 角色选择、全量快照、行动/技能/目标/格子/询问。 - 先用简单控件完成全流程,不追求最终美术。 ### 阶段 2:完成战斗 UI 竖切 - 按 webui-solo 的信息结构重建 Godot UI。 - 加入队列、状态、DP、技能原因、日志、结果和基本动画。 - 补齐键鼠、手柄、缩放和安全区适配。 ### 阶段 3:本机发行形态 - 服务启动/停止、端口选择、日志收集和异常恢复。 - 断线、暂停、存档/回放和版本不兼容提示。 ### 阶段 4:房主模式 - 一名房主、多名连接、玩家到角色的控制映射。 - 房间准备、超时、掉线 AI 接管和重新加入。 - 先支持局域网/直连,再评估信令与中继。 ### 阶段 5:专用服务器 - 接入 Server-v3 的 JWT、房间和匹配。 - 把已验证的真人决策桥接移入通用多人会话。 - 加入观战、运营监控、服务器回放和反作弊审计。 ## 10. 验收清单 - 网络延迟或重复点击不会执行两次行动。 - 断线后能够恢复地图、队列、当前决策和倒计时。 - 玩家只能控制服务器分配给自己的角色。 - 窗口缩放后地图、队列和操作区仍可用,不重叠。 - 所有操作可用鼠标完成,核心流程也可用手柄完成。 - 不可用技能仍可查看说明,并明确显示不可用原因。 - 大量状态效果、召唤单位和长队列不会撑破布局。 - 动画被跳过后画面能立即对齐权威快照。 - 同一 Godot 构建可以切换本机、房主和专服地址。 ## 11. 当前推荐决策 建议先定下以下默认值,再用竖切结果复盘: - Windows 桌面端、16:9 横屏优先。 - 服务器权威;单人也走 WebSocket 协议。 - 全屏纯 2D 斜俯视地图;逻辑格平时隐藏,仅在移动、攻击和目标选择时局部显现。 - HUD 采用贴边悬浮布局:左上任务、上方精简队列、左下角色状态、右下行动坞、底部确认区。 - P2P 第一版为房主权威且不做房主迁移。 - 第一目标是接通 `/ws/solo`,不是立刻重构 Server-v3。 仍需产品层共同决定的内容包括:场景也采用纯 2D 斜投影还是使用 3D 地形搭配 2D 人物、每名玩家控制单角色还是小队、是否需要战争迷雾、回合决策是否有倒计时,以及首发平台是否包含移动端。