# 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、协议对象和状态更新流程。