Files
FunGameServer-Test/docs/02-v3-Core-变更分析.md
2026-08-28 19:44:46 +08:00

15 KiB
Raw Permalink Blame History

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)

关键模式:

  1. 进程内直接引用模组代码(characterModule.Load() 等),不再有 DLL 插件/模组加载器
  2. GamingQueue 跑完一局 → RoundRecord 列表 → 压缩归档 rounds_archive.zip
  3. WebAPI 提供回放端点:/api/meta、/api/rounds/summary、/api/rounds/{n}、/api/statistics、/api/reload、/api/simulate/team
  4. 无数据库、无账号、无网络协议——纯战斗模拟与回放
  5. 发布 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 开发的关键影响(决策输入)

  1. Core v3 不再是"开箱即用的服务器":v3 Server 需要自己补齐网络、数据库、认证、配置、日志五大基础设施。
  2. 战斗与回放是 v3 的拳头能力:GamingQueue + RoundRecord + IRoundRecordSink(即时 POST 外发)+ BattleStatePredictor + RoundRecordRenderer 构成完整的"对局产生 → 记录 → 外发 → 回放"链路,这是 v3 Server 应当优先围绕设计的核心。
  3. 默认外发通道是 HTTP POST(DefaultRoundRecordSink):说明 v3 的设计意图之一是"战斗服务器算、外部服务收"——Server-v3 天然适合做成 WebAPI 形态,自己既是战斗宿主又是记录接收方(或转发到数据服务)。
  4. 模组体系变化:从"DLL 热插拔"变为"代码引用 + 配置数据"。Server-v3 要么跟随(进程内引用模组)、要么自行实现 DLL 隔离加载(回到 v2 思路,Core 不再帮忙)。
  5. v2 Server 的业务代码(房间/匹配/账号/经济/控制台)仍然有效,可以整体迁移,但要换掉所有 Milimoe.FunGame.Core.* 命名空间引用,并重写底层依赖(SQLHelper→自选数据层、DataRequest 传输→自定协议)。
  6. Testing-v3 不是"服务器":它是无账号无网络的对战模拟/回放台。Server-v3 可以在它之上叠加网络/账号/房间层,或者完全另起架构。