first commit
This commit is contained in:
@@ -0,0 +1,219 @@
|
||||
# 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、协议对象和状态更新流程。
|
||||
Reference in New Issue
Block a user