15 KiB
15 KiB
FunGame.Core v3 变更分析(v2 → v3)
分析对象:
C:\milimoe\FunGame.Core(master 分支,3.0.0-dev,net10.0) 对比基准:v2 分支(2.1.0 Release) 配套参考:C:\milimoe\FunGame.Testing-v3(v3 的测试项目,WebAPI + React 回放台)
1. 总体结论(先看这里)
v3 把 Core 从"游戏服务器运行时框架"重构为"纯回合制战斗引擎库"。
- v2:Core = 网络 + 数据库 + 插件 + 模组加载 + 邮件 + 任务调度 + 战斗引擎(一整包服务器运行时)
- v3:Core = 实体模型 + 战斗引擎(GamingQueue)+ 回合记录/回放基础设施 + 模块(数据驱动)机制。网络、SQL、SMTP、插件加载器等全部从 Core 中移除,由使用方(Server / WebAPI 等)自行实现。
v2→v3 共 10 个提交、280 个文件变更,+4816 / -18642 行——删除远多于新增,删除的正是"服务器运行时"那一层。
2. 版本与命名空间
| 项 | v2 | v3 |
|---|---|---|
| 版本 | 2.1.0 | 3.0.0-dev(每日版本后缀) |
| 目标框架 | net10.0(v2 分支后期已升级) | net10.0 |
| 根命名空间 | Milimoe.FunGame.Core |
FunGame.Core |
| 打包 | NuGet FunGame.Core |
继续 NuGet 发布(新增自动发布工作流)+ slnx |
| 文档 | README.md | README.md + README_EN.md |
⚠️ 命名空间整体变更:所有 v2 代码中的
using Milimoe.FunGame.Core.*在 v3 都要改为using FunGame.Core.*。这是迁移时最机械但覆盖面最广的改动。
3. 从 Core 中移除的内容(v3 不再提供)
这些能力在 v3 Server 项目中必须自行实现(或放弃)。
3.1 网络与协议层(全部移除)
| 移除项(v2 位置) | 功能 |
|---|---|
Service/SocketManager.cs |
Socket 服务管理 |
Library/Common/Network/Socket.cs、SocketObject.cs |
Socket 对象与消息协议(SocketMessageType 等) |
Library/Common/Network/ServerSocket.cs、ServerWebSocket.cs |
服务端 Socket/WebSocket 实现 |
Library/Common/Network/SocketListener.cs、HTTPListener.cs |
监听器(TCP / HTTP 前缀) |
Library/Common/Network/HTTPClient.cs |
HTTP 客户端封装 |
Interface/Base/ISocketListener、ISocketMessageProcessor、IBaseSocket、ISocketHeartBeat、ISocketHandler、Sockets/* |
网络接口 |
Controller/SocketHandlerController.cs、Service/HTTPManager.cs |
消息处理与 HTTP 管理 |
Library/Common/Architecture/HeartBeat.cs、AsyncAwaiter.cs、TaskAwaiter.cs、SyncAwaiter.cs(部分) |
心跳与异步等待基建 |
3.2 数据访问层(移除)
| 移除项 | 功能 |
|---|---|
Api/Transmittal/SQLHelper.cs、Interface/Base/ISQLHelper.cs、Model/SQLServerInfo.cs |
SQLHelper 抽象 |
Library/SQLScript/**(全部) |
全部 SQL 语句类(UserQuery、RoomQuery、OffersQuery……)与建库脚本 fungame.sql / fungame_sqlite.sql、补丁脚本 |
Library/Common/JsonConverter/DataSetConverter.cs、DataTableConverter.cs |
DataSet/DataTable 序列化(SQL 时代的遗留) |
3.3 通信协议与事务(移除)
| 移除项 | 功能 |
|---|---|
Api/Transmittal/DataRequest.cs |
DataRequestType 数据请求传输模型 |
Api/Transmittal/MailSender.cs、IMailSender、Model/SmtpClientInfo.cs、Library/Common/Network/MailObject.cs |
SMTP 邮件 |
Library/Common/Addon/AddonDataRequestEventArgs.cs |
插件数据请求事件 |
3.4 插件 / 模组 / 加载器(移除或重构)
| 移除项 | 功能 |
|---|---|
Service/AddonManager.cs、HotLoadAddonManager.cs |
插件管理、热加载上下文管理 |
Api/Utility/PluginLoader.cs、ServerPluginLoader.cs、WebAPIPluginLoader.cs、PluginConfig.cs |
插件加载器与配置存储 |
Library/Common/Addon/Plugin.cs、ServerPlugin.cs、WebAPIPlugin.cs、GameModule.cs、GameModuleDepend.cs、GameModuleServer.cs、GamingObject.cs |
插件/模组基类(全部删除) |
Api/Utility/GameModuleLoader.cs |
模组 DLL 加载器 |
Controller/AddonController.cs、BaseAddonController.cs、ServerAddonController.cs、RunTimeController.cs |
加载项控制器(事件分发中枢) |
Interface/Base/Addons/*、Interface/Base/HTTP/*、Interface/Base/IAddon.cs→IModule.cs |
加载项接口(重构为模块接口) |
Api/Utility/TextReader.cs(txt 资源读取)、TwoFactorAuthenticator.cs、Singleton.cs、TaskScheduler.cs、ConcurrentFIFOQueue.cs、ConcurrentModelList.cs |
工具类 |
3.5 服务器模型(移除)
| 移除项 | 功能 |
|---|---|
Interface/Base/IServerModel.cs |
服务器客户端模型接口(v2 Server 的 ServerModel 实现它) |
Model/Gaming.cs、Model/RoomList.cs、Model/ActionQueue.cs、Model/RecurringTask.cs、Model/ScheduledTask.cs、Model/Session.cs、Model/FunGameConfig.cs |
服务器状态模型 |
4. v3 新增 / 重构的内容
4.1 回合记录框架(Framework 模型,v3 核心新特性)
Model/Framework/ 下新增,围绕"可回放的对局记录"设计:
| 类型 | 说明 |
|---|---|
RoundRecord |
单回合完整记录:行动流(Actions)、操作类型与目标、技能/物品及消耗、伤害/暴击/闪避/免疫/治疗字典、特效触发(Effects)与施加特效(ApplyEffects)、击杀/助攻、连杀、吟唱/硬直、复活、回合奖励、杂项消息、全角色清单、队伍归属映射、检查点快照、最终统计、游戏结果排名(GameResult)等;提供 Snapshot() 结构快照 |
ActionRecord |
单次操作记录(决策点系统允许一回合多次操作,ActionIndex 从 1 开始),含伤害记录、特效记录、状态变更等 |
CharacterStateSnapshot |
角色状态快照(HP/MP/EP、装备明细、物品、技能、状态栏特效) |
EquipmentStateSnapshot |
装备状态快照 |
DamageRecord / DeathRelation |
伤害记录 / 死亡关系 |
RankingEntry |
游戏结束排名条目(角色或团队、胜者标记、KDA、得分、赚钱) |
RoundRecordPayload |
外发数据包线协议:紧凑字段 g(队列 Guid)/t(时间戳)/e(事件 id)/d(数据)/s(签名) |
GameMap、Grid |
地图与格子(原 Addon 中移入 Framework 并重构) |
4.2 回合记录外发通道(v3 最重要新增特性)
Interface/Base/IRoundRecordSink:回合记录外发接口,8+1 个事件:SendAction("0",每次角色操作后即时)、SendRound("1",每操作后当前回合全量)、SendCheckpointRound("2",检查点回合,带全角色状态快照)、SendCharacterStatistics("3")、SendCharacters("4")、SendTeams("5")、SendQueueData("6",行动顺序表)、SendEliminatedCharacters("7")、SendEliminatedTeams("8")- 另有
Attach(queueId)、End()生命周期方法
Api/DefaultRoundRecordSink:默认实现——即时主动 POST 外发:把数据包 POST 到外部专用服务器(Bearer AccessToken 可选),支持Secret签名握手(事件 "13" 验证签名,失败每 60s 重试,成功前不外发其他事件),HttpClient 5 秒超时防挂起Api/BattleStatePredictor:状态推算器——从回合记录序列推算任意回合的全角色状态(基于检查点 + 行动记录),回放端无需完整状态即可展示Api/RoundRecordRenderer:回合记录文本渲染(RenderRound/RenderAll/RenderCharacterActions)
4.3 战斗引擎重构(GamingQueue)
Model/ActionQueue.cs→Model/Queue/GamingQueue.cs(+615 行重写)MixGamingQueue(混战队列)、TeamGamingQueue(团队队列)重构- 新增属性:
RoundRecordSink(绑定外发通道)、CheckpointInterval(检查点间隔,默认 50 回合)、Rounds(全量回合记录)、LastRound、GameOver、CustomData、EarnedMoney、CharacterDecisionPoints、MaxScoreToWin、MaxRespawnTimes等 - 战斗能力保留并强化:伤害计算(物理/魔法)、暴击/闪避/免疫、特效钩子(
EffectHookCache)、决策点系统(DecisionPoints)、复活、回合奖励、商店(AddStoreItems/BuyItems)、物品使用、地图寻路与目标选择、AI 决策 Api/EffectHookCache.cs:特效钩子缓存(配合Model/Framework/ActionRecord的"特效记录"重写,提交 #167"依靠检查方法重写以记录触发的特效")
4.4 实体工厂与模块配置(数据驱动)
Api/Factory.cs:新实体工厂——Factory.OpenFactory.RegisterFactory<T>/GetInstance<T>(id, name, args)(按 id/name 动态实例化 Character/Skill/Effect/Item/Inventory/Room/User),GetGameModuleInstances<T>(module_name, file_name)从模块配置文件批量实例化,CreateGameModuleEntityConfig<T>生成模块实体配置Api/EntityModuleConfig.cs:实体模块配置文件(modules/目录、可配置目录)Library/Module/:IModule+CharacterModule/SkillModule/ItemModule(Load()/UnLoad()),替代 v2 的Library/Common/Addon/GameModule体系;Example/示例模块- 意义:模组内容 = 代码类 + 配置文件,运行期按配置实例化,替代 v2 的"DLL 扫描加载"模式
4.5 JSON 序列化体系重构
Service/JsonManager.cs→Api/JsonService.cs(全局JsonSerializerOptions、GeneralOptions)Library/Common/JsonConverter/大幅更新:新增ActionRecordConverter、CharacterStateSnapshotConverter、RankingEntryConverter、RoundRecordConverter(重写)、EntityRefHelper(实体引用表,解决循环引用/共享引用)- 移除 DataSet/DataTable 转换器(SQL 时代产物)
4.6 工具类整合
Api/General.cs:合并NetworkUtility(partial + RegexGenerator)、Encryption(HMAC/SHA/RSA/MD5/随机串)、Verification(验证码)、日期时间工具、数值工具(Round/PercentageCheck 等)、JSON 快捷方法Api/Attribute.cs、LINQExtension.cs、SkillExtension.cs、OpenItemAdapter/OpenSkillAdapter(开放实体适配)、NovelConfig.cs(剧情配置)
4.7 保留的内容(基本未动)
Entity/**:Character / Skill / Effect / Item / Inventory / User / Room / Team / Store / Market / Offer / Goods / Club / Season / Explore(Region/Quest/Activity) / Statistics 等全部实体(局部字段调整:Item 构造公开、Skill 关联 Item、Equal 应用 Guid)Library/Constant/:TypeEnum(含战斗相关枚举)、StateEnum、ResultEnum、ConstantSet、FunGameInfo、General(经济平衡常量)Library/Common/Event/:事件参数(Connect/Login/Register/Room/SendTalk/General/Gaming/UserActivity 等,命名空间调整)Interface/Event/:事件处理器接口(IGamingConnectEventHandler、IGamingRoundEventHandler 等局内事件 + EventCenter 活动/商店中心)Model/PrefabricatedEntity/:预制技能/特效(灵魂绑定、魔法卡包等)Library/Architecture/BaseEntityConverter.cs:实体转换基类Library/Exception/:异常体系
5. FunGame.Testing-v3 参考(v3 的"服务器"长什么样)
Testing-v3 是 v3 Core 目前唯一的宿主参考实现,展示了 v3 时代的运行形态:
FunGame.Testing-v3/
├── WebAPI/ # ASP.NET Core Web API(net10.0,唯一项目)
│ ├── Program.cs # 入口:模块初始化 + 6 个 REST 端点 + 托管前端
│ ├── Services/ArchiveStore.cs # 读取 rounds_archive.zip(回合存档)
│ ├── Tests/FunGameService.cs # 角色/技能/物品注册表 + Rating 计算
│ ├── Tests/FunGameSimulation.cs # 进程内跑一局 AI 对战(GamingQueue)
│ ├── Tests/EffectAutoRecordTest.cs # 特效自动记录测试
│ ├── Tests/RoundRecordSinkTest.cs # RoundRecordSink 测试
│ └── OshimaGameModules/ # 模组代码(角色/技能/特效/物品,全部编译期引用)
├── webui/ # React + Vite + Tailwind 回放台(统计/回放/快照三面板)
└── rounds_archive.zip # 回合记录归档(rounds_data.json)
关键模式:
- 进程内直接引用模组代码(
characterModule.Load()等),不再有 DLL 插件/模组加载器 GamingQueue跑完一局 →RoundRecord列表 → 压缩归档rounds_archive.zip- WebAPI 提供回放端点:
/api/meta、/api/rounds/summary、/api/rounds/{n}、/api/statistics、/api/reload、/api/simulate/team - 无数据库、无账号、无网络协议——纯战斗模拟与回放
- 发布 Linux 自包含(publish-linux.sh)
6. v2 → v3 变化对照总表
| 能力 | v2(Core 提供) | v3(Core 提供) | Server-v3 需要 |
|---|---|---|---|
| 回合制战斗引擎 | ✅ GamingQueue | ✅ 重构强化 + 回合记录 | 直接用 |
| 回合记录/回放 | ❌ | ✅ RoundRecord/ActionRecord/快照/渲染 | 直接用 |
| 记录外发(POST) | ❌ | ✅ IRoundRecordSink / DefaultRoundRecordSink | 配置 URL 或自定义实现 |
| 实体/模块 | Addon DLL 体系 | IModule + 实体配置 + Factory | 采用新模块方式 |
| 网络(Socket/WS) | ✅ | ❌ | 自研或引入第三方 |
| 消息协议(SocketObject/DataRequest) | ✅ | ❌ | 自研 |
| 数据库(SQLHelper + SQL 脚本) | ✅ | ❌ | 自研(EF/ADO/Dapper…) |
| 邮件 SMTP | ✅ | ❌ | 自研或引入库 |
| 插件系统 + 热加载 | ✅ | ❌ | 自研(或改为服务内模块) |
| 账号/注册/登录/2FA | 部分(Authenticator 骨架) | ❌ | 自研 |
| 房间/匹配/Elo | ❌(Server 层实现) | ❌ | 迁移 v2 Server 代码 |
| 商店/市场/报价经济 | ❌(Server 层实现) | ❌ | 迁移 v2 Server 代码 |
| 控制台管理 | 部分(Core 提供订单定义) | ❌ | 自研 |
| INI 配置 | ✅ | ❌ | 自研或引入库 |
| 日志 | ✅ TXTHelper/ServerHelper | ❌ | 自研或引入库(ILogger 等) |
| 事件体系 | 插件事件链 | 局内事件 + EventCenter | 自研服务事件 |
| 任务调度 | ✅ TaskScheduler | ❌ | 自研 |
7. 对 Server-v3 开发的关键影响(决策输入)
- Core v3 不再是"开箱即用的服务器":v3 Server 需要自己补齐网络、数据库、认证、配置、日志五大基础设施。
- 战斗与回放是 v3 的拳头能力:
GamingQueue+RoundRecord+IRoundRecordSink(即时 POST 外发)+BattleStatePredictor+RoundRecordRenderer构成完整的"对局产生 → 记录 → 外发 → 回放"链路,这是 v3 Server 应当优先围绕设计的核心。 - 默认外发通道是 HTTP POST(
DefaultRoundRecordSink):说明 v3 的设计意图之一是"战斗服务器算、外部服务收"——Server-v3 天然适合做成 WebAPI 形态,自己既是战斗宿主又是记录接收方(或转发到数据服务)。 - 模组体系变化:从"DLL 热插拔"变为"代码引用 + 配置数据"。Server-v3 要么跟随(进程内引用模组)、要么自行实现 DLL 隔离加载(回到 v2 思路,Core 不再帮忙)。
- v2 Server 的业务代码(房间/匹配/账号/经济/控制台)仍然有效,可以整体迁移,但要换掉所有
Milimoe.FunGame.Core.*命名空间引用,并重写底层依赖(SQLHelper→自选数据层、DataRequest 传输→自定协议)。 - Testing-v3 不是"服务器":它是无账号无网络的对战模拟/回放台。Server-v3 可以在它之上叠加网络/账号/房间层,或者完全另起架构。