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

11 KiB
Raw Blame History

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 只负责显示状态和提交玩家意图,战斗结果统一由权威主机计算。

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# 基础文档。

桌面端优先可以规避 Web 导出限制;若以后要做浏览器版,应将其视为单独技术路线,而不是默认继承桌面 C# 客户端。

7. 推荐的近期工作边界

第一阶段只做一条端到端竖切链路:

  1. Godot 连接现有 /ws/solo。
  2. 完成角色选择并显示首个权威快照。
  3. 实现行动、技能、目标/格子和询问这几类决策。
  4. 显示回合队列、角色状态、决策点和结果。
  5. 验证断线重连、AI 接管和恢复。

竖切通过后,再把单人会话抽象到房主模式和 Server-v3。这样可以让三种部署方式复用同一套 Godot UI、协议对象和状态更新流程。