Files
Oshima-Game/docs/FunGame代码调研.md
T
2026-09-19 17:24:02 +08:00

220 lines
11 KiB
Markdown
Raw 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.
# FunGame 代码调研
> 调研日期:2026-09-18
> 范围:`FunGame.Core`、`FunGame.Testing-v3/OshimaGameModules`、`FunGame.Testing-v3/WebAPI`,并参考 `FunGame.Server-v3`、`FunGame.Godot` 与 `webui-solo`。
> 本文记录当前代码事实与接入判断,不把尚未实现的联机能力描述为已完成。
## 1. 结论摘要
现有代码已经具备制作 Godot 竖切版本所需的三个主要部分:
1. **规则层**:`FunGame.Core` 提供完整的回合、行动队列、决策点、技能、效果、伤害、地图和回合记录能力。
2. **内容层**:`OshimaGameModules` 已把《筽祀牻》的 18 名角色、专属技能、通用技能、效果、物品和职业体系实现为可执行 C# 模块。
3. **服务器原型层**:`WebAPI` 的 `/ws/solo` 已把同步的回合制核心包装成服务器权威会话,支持状态快照、客户端决策、暂停、断线重连和 AI 接管。
因此,Godot 第一阶段不需要重写战斗规则。较稳妥的方案是:**Godot 只负责显示状态和提交玩家意图,战斗结果统一由权威主机计算**。
```text
OshimaGameModules(角色、技能、物品)
↓
FunGame.Core(回合规则与状态)
↓
WebAPI / 未来的 Server-v3(权威会话与协议)
↓
Godot C#(画面、输入、动画、声音)
```
## 2. FunGame.Core
路径:`C:\milimoe\FunGame.Core`
### 2.1 工程与职责
- 当前工程目标框架为 `net10.0`,包版本为 `3.0.0-dev`。
- 核心库本身不依赖第三方 NuGet 包。
- 许可证为 LGPL-3.0-or-later;发行游戏时需要保留许可证与署名,并单独评估修改核心库和静态/动态分发的合规方式。
- 核心入口是 `IGamingQueue` / `GamingQueue`,其职责不只是“队列”,还包括回合推进、行动解析、伤害与治疗、死亡、移动、目标选择、AI 控制和效果派发。
### 2.2 已有能力
- 行动顺序、硬直时间与时间流逝。
- 决策点(DP)、行动次数和行动类型配额。
- 普通攻击、技能、物品、移动、放弃行动与继续行动。
- 伤害、治疗、暴击、闪避、免疫、效果附加与驱散。
- 单位死亡、打断、召唤/衍生单位和淘汰队列。
- 混战队列 `MixGamingQueue` 与团队队列 `TeamGamingQueue`。
- `ActionRecord`、`RoundRecord`、统计数据和角色状态检查点。
- `IRoundRecordSink` 可将行动、回合、统计、角色、队伍和队列数据输出到外部存储或远程服务。
- `JsonService` 已包含角色、技能、效果、物品、行动记录、回合记录和快照等转换器。
### 2.3 对客户端最重要的事件
`GamingQueue` 暴露了约 29 类战斗事件,覆盖:
- 回合开始/结束、队列更新、行动完成、决策完成;
- 选择行动、技能、物品、目标、格子和询问选项;
- 攻击、施法、使用物品、移动、伤害、治疗、免疫、死亡和游戏结束。
这些事件适合由“会话适配层”转换成网络消息,不应让 Godot UI 直接订阅核心对象。
### 2.4 线程与调用约束
核心事件及其询问流程是同步的。服务器需要在游戏线程里等待玩家决策,而 Godot 的节点和界面只能在主线程安全更新。因此:
- 核心回合循环不能在 Godot 主线程运行;
- 网络消息先进入客户端状态仓库,再由 Godot 主线程更新节点;
- 即使将来提供离线内嵌模式,也要保留游戏线程与显示线程之间的消息边界。
## 3. OshimaGameModules
路径:`C:\milimoe\FunGame.Testing-v3\OshimaGameModules`
### 3.1 内容规模
- 18 名可玩角色,稳定 ID 为 1–18。
- 每名角色有 1 个专属被动和 1 个专属爆发技,共 36 个专属技能文件。
- 通用内容目前包含约 53 个魔法、59 个战技、30 个通用被动和 16 个通用爆发技。
- 效果模块包含开放效果、被动效果和技能效果;另有物品、单位与 JSON 配置。
- 世界职业体系已有 3 个基础职业、每个职业 2 个进阶分支,共 6 个成长方向。
### 3.2 角色 ID 对照
| ID | 角色类 |
|---:|---|
| 1 | OshimaShiya |
| 2 | XinYin |
| 3 | Yang |
| 4 | NanGanYu |
| 5 | NiuNan |
| 6 | DokyoMayor |
| 7 | MagicalGirl |
| 8 | QingXiang |
| 9 | QWQAQW |
| 10 | ColdBlue |
| 11 | Dddovo |
| 12 | Quduoduo |
| 13 | ShiYu |
| 14 | XReouni |
| 15 | Neptune |
| 16 | CHAOS |
| 17 | Ryuko |
| 18 | TheGodK |
角色并非只有静态数值。专属被动通过效果钩子响应回合开始、获得效果、受伤等事件,主动技能也会执行持续时间、属性变化、自伤、额外攻击等逻辑。这意味着内容层已经可以直接作为服务器规则模块使用。
### 3.3 素材映射建议
Godot 不应以中文名或类名模糊查找素材,应使用稳定数值 ID 建立清单:
- 角色头像:角色 ID `1..18` → `assets/images/2d-game-icons/characters`。
- 技能图标:技能数值 ID → 有边框版或 `skills/borderless` 无边框版。
- “不可主动使用”建议由 UI 灰度、遮罩和状态标识表达;无边框图可作为该视觉状态的底图,但不要把规则状态编码进文件名判断。
后续宜新增单一的图标清单文件,由程序和美术共同维护,避免重命名素材后代码失效。
## 4. WebAPI 单人战斗原型
路径:`C:\milimoe\FunGame.Testing-v3\WebAPI`
### 4.1 已实现接口
- WebSocket:`/ws/solo`
- REST:`/api/solo/state`、`/api/solo/stop`、`/api/solo/pause`、`/api/solo/ranking`
- 回放/归档:游戏数据、元数据、回合摘要、指定回合、统计、模拟和重载等接口。
- 职业方案:定义、选择、升级、学习、分配、应用和保存等接口。
### 4.2 消息信封
协议使用统一信封:
| 字段 | 含义 |
|---|---|
| `t` | 消息类型 |
| `i` | 请求/消息 ID |
| `ok` | 是否成功 |
| `d` | 业务数据 |
| `ts` | 时间戳 |
| `error` | 错误信息 |
主要消息包含 `gaming.start`、`gaming.action`、`gaming.state`、`gaming.request`、`gaming.resolved`、`gaming.pause`、`gaming.resume`、`gaming.round`、`gaming.queue` 和 `gaming.over`。
玩家决策类型覆盖:选择角色、行动类型、技能、物品、目标、单个格子、多个格子、询问与继续。
### 4.3 会话运行方式
`SoloGameSession` 采用服务器权威模式:
1. 服务器创建角色、队伍、地图、物品与行动队列。
2. 回合核心在后台线程运行。
3. 需要玩家输入时发送 `gaming.request`,游戏线程等待客户端的 `gaming.action`。
4. 服务器校验选择,解析行动后推送新的权威状态。
5. 客户端断线时可以重连并收到完整快照和仍待处理的决策。
6. 决策超时或异常重复时,服务器把玩家暂时交给 AI,避免整局永久阻塞。
当前快照已经包含地图、格子、全部角色、队列、玩家决策点、当前行动者、队伍、奖励、暂停和 AI 接管状态。角色 DTO 还包含 HP/MP/EP、移动力、属性、状态、格子、技能、物品、效果和装备等 UI 所需信息。
### 4.4 当前限制
- `SoloGameHost` 目前按单个单人会话设计,不是多人房间管理器。
- 服务器目前以完整快照为主,联机规模扩大后宜加入状态版本号、增量更新和带宽观测。
- WebSocket 接收处当前使用单次固定缓冲读取;正式版需要正确拼接分片消息,并为大快照设置尺寸上限、压缩或拆包策略。
- 决策请求需要进一步加入明确的截止时间、状态版本、幂等处理和拒绝原因,才能可靠应对高延迟和重复包。
- REST 快照与游戏线程并发读取已有防护思路,但正式多人版仍应统一状态复制策略。
## 5. 可参考的现有项目
### 5.1 webui-solo
路径:`C:\milimoe\FunGame.Testing-v3\webui-solo`
这是目前最接近“已验证交互原型”的客户端。它已经实现:
- 顶部回合/时间/比分与暂停区;
- 左侧行动队列和决策点;
- 中央地图、范围高亮与目标确认;
- 右侧操作、日志和队伍面板;
- 角色详情、不可用技能原因和决策确认;
- WebSocket 心跳与协议类型定义。
其 `soloClient` 已体现“传输层可替换”的思路。Godot 版可以继承其信息架构,但应重新制作适合桌面、手柄和安全区的 Godot UI。
### 5.2 FunGame.Godot
路径:`C:\milimoe\FunGame.Godot`
旧原型包含行动栏、行动面板、状态、Buff、回合队列和目标选择等场景,也有两个值得复用的思想:
- 用 `TaskCompletionSource` 把 UI 选择转换成异步请求结果;
- 用主线程调度器把后台逻辑更新安全地切回 Godot 主线程。
但该项目直接把 `Character`、`Skill`、`Item` 等核心对象绑定到 UI,引用的是 FunGame.Core 2.0.0,并大量使用固定像素位置。新的可联机客户端不应沿用这种强耦合方式。
### 5.3 FunGame.Server-v3
路径:`C:\milimoe\FunGame.Server-v3`
Server-v3 已具备 JWT、房间、匹配、WebSocket、插件、回合记录和 OSM 模块加载等专用服务器基础设施,也沿用了相同的消息信封。
不过,当前通用托管游戏仍主要让角色由 AI 执行;多名真人玩家与核心同步决策的完整桥接尚未完成。因此它适合作为专用服务器目标架构,不能直接视为“多人战斗已经完成”。下一步应把 `SoloGameSession` 已验证的决策桥接抽象成可绑定多个用户、角色和连接的通用会话组件。
## 6. 版本与工具链
- 三个主调研工程均以 `net10.0` 为当前代码基线。
- 本机已安装 .NET 7、8、10 SDK,但命令行暂未发现 Godot 可执行文件。
- 现有 `FunGame.Godot` 工程声明 `Godot.NET.Sdk/4.7.0` 与 `net10.0`,说明项目正在尝试较新的 Godot/.NET 组合。
- Godot 官方稳定文档当前仍以 .NET 8 为 C# 基线,并说明 C# 项目不能导出到 Web。正式创建工程前,应以实际安装的 Godot 编辑器、对应 .NET SDK 和目标平台导出模板做一次最小构建验证:[Godot C# 基础文档](https://docs.godotengine.org/en/stable/tutorials/scripting/c_sharp/c_sharp_basics.html)。
桌面端优先可以规避 Web 导出限制;若以后要做浏览器版,应将其视为单独技术路线,而不是默认继承桌面 C# 客户端。
## 7. 推荐的近期工作边界
第一阶段只做一条端到端竖切链路:
1. Godot 连接现有 `/ws/solo`。
2. 完成角色选择并显示首个权威快照。
3. 实现行动、技能、目标/格子和询问这几类决策。
4. 显示回合队列、角色状态、决策点和结果。
5. 验证断线重连、AI 接管和恢复。
竖切通过后,再把单人会话抽象到房主模式和 Server-v3。这样可以让三种部署方式复用同一套 Godot UI、协议对象和状态更新流程。