Files
Oshima-Game/docs/Godot联机接入与UI草案.md
2026-09-19 17:24:02 +08:00

331 lines
17 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 人物、每名玩家控制单角色还是小队、是否需要战争迷雾、回合决策是否有倒计时,以及首发平台是否包含移动端。