first commit

This commit is contained in:
2026-09-19 17:24:02 +08:00
commit afb343aa49
109 changed files with 13011 additions and 0 deletions
+330
View File
@@ -0,0 +1,330 @@
# 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 人物、每名玩家控制单角色还是小队、是否需要战争迷雾、回合决策是否有倒计时,以及首发平台是否包含移动端。