212 lines
15 KiB
Markdown
212 lines
15 KiB
Markdown
# 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 可以在它之上叠加网络/账号/房间层,或者完全另起架构。
|