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

212 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 可以在它之上叠加网络/账号/房间层,或者完全另起架构。