From 007c33f7723a94c7790ad4944493b9022cf61db6 Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Thu, 23 Apr 2026 07:30:03 +0800 Subject: [PATCH] =?UTF-8?q?docs(game):=20=E5=88=B7=E6=96=B0=20Game=20?= =?UTF-8?q?=E6=A8=A1=E5=9D=97=E6=96=87=E6=A1=A3=E5=9F=BA=E7=BA=BF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新 Game family README、landing 与 abstractions 页面，补齐声明级 XML inventory 入口 - 修复 Game.Abstractions 页面与当前源码不一致的旧接口摘录，改写为真实契约边界与最小接入路径 - 补充 ai-plan 跟踪与 trace，推进恢复点到 RP-005 并记录验证结果 --- GFramework.Game.Abstractions/README.md | 14 ++ GFramework.Game.SourceGenerators/README.md | 9 + GFramework.Game/README.md | 13 ++ ...ation-full-coverage-governance-tracking.md | 34 ++- ...entation-full-coverage-governance-trace.md | 37 +++ docs/zh-CN/abstractions/game-abstractions.md | 210 ++++++++++-------- docs/zh-CN/game/index.md | 15 ++ 7 files changed, 232 insertions(+), 100 deletions(-) diff --git a/GFramework.Game.Abstractions/README.md b/GFramework.Game.Abstractions/README.md index 91fa5f32..d69c7c10 100644 --- a/GFramework.Game.Abstractions/README.md +++ b/GFramework.Game.Abstractions/README.md @@ -131,6 +131,20 @@ Scene 与 UI 路由共享这套基础约定。 - `Enums/` - UI/Scene 转场、UI 层级、输入动作、存储类型等公共枚举 +## XML 覆盖基线 + +下面这份 inventory 记录的是 `2026-04-23` 对 `GFramework.Game.Abstractions` 做的一轮轻量 XML 盘点结果：只统计公开 / +内部类型声明是否带 XML 注释，用来建立契约层阅读入口；成员级参数、返回值、异常和生命周期说明仍需要在后续 API 波次继续细化。 + +| 契约族 | 基线状态 | 代表类型 | 阅读重点 | +| --- | --- | --- | --- | +| `Config/` | `7/7` 个类型声明已带 XML 注释 | `IConfigLoader`、`IConfigRegistry`、`IConfigTable`、`ConfigLoadException` | 看配置表注册、读取约定和失败诊断模型 | +| `Data/` | `14/14` 个类型声明已带 XML 注释 | `IDataRepository`、`ISettingsDataRepository`、`ISaveRepository`、`DataRepositoryOptions` | 看业务数据、设置持久化、槽位存档和版本迁移契约 | +| `Setting/` | `12/12` 个类型声明已带 XML 注释 | `ISettingsData`、`ISettingsModel`、`ISettingsSystem`、`LocalizationSettings` | 看设置数据、应用语义、迁移接口和内置设置对象 | +| `Scene/` | `14/14` 个类型声明已带 XML 注释 | `IScene`、`ISceneRouter`、`ISceneFactory`、`SceneTransitionEvent` | 看场景行为、路由、工厂 / root 边界与转场事件模型 | +| `UI/` | `19/19` 个类型声明已带 XML 注释 | `IUiPage`、`IUiRouter`、`IUiFactory`、`UiInteractionProfile`、`UiTransitionHandlerOptions` | 看页面栈、层级 UI、输入动作与 UI 转场契约 | +| `Routing/` `Storage/` `Asset/` `Enums/` | `13/13` 个类型声明已带 XML 注释 | `IRoute`、`IRouteContext`、`IFileStorage`、`IAssetRegistry`、`UiLayer`、`SceneTransitionType` | 看公共路由上下文、存储角色、资源注册表与跨层共享枚举 | + ## 最小接入路径 ### 1. 只想在公共业务层声明游戏对象 diff --git a/GFramework.Game.SourceGenerators/README.md b/GFramework.Game.SourceGenerators/README.md index 050c4d16..c12a3607 100644 --- a/GFramework.Game.SourceGenerators/README.md +++ b/GFramework.Game.SourceGenerators/README.md @@ -44,6 +44,15 @@ GameProject/ 默认情况下，打包产物会通过 `targets` 把 `schemas/**/*.schema.json` 纳入 `AdditionalFiles`。 +## XML 覆盖基线 + +下面这份 inventory 记录的是 `2026-04-23` 对 `GFramework.Game.SourceGenerators` 做的一轮轻量 XML 盘点结果：只统计公开类型声明是否带 XML 注释，用来建立生成器入口；具体诊断消息、生成输出和兼容性语义仍需要回到源码与测试继续核对。 + +| 类型族 | 基线状态 | 代表类型 | 阅读重点 | +| --- | --- | --- | --- | +| `Config/` | `1/1` 个类型声明已带 XML 注释 | `SchemaConfigGenerator` | 看 schema 到配置类型 / 表包装 / 注册辅助代码的生成入口 | +| `Diagnostics/` | `1/1` 个类型声明已带 XML 注释 | `ConfigSchemaDiagnostics` | 看生成器会抛出的诊断类别与失败边界 | + ## 最小接入路径 ```xml diff --git a/GFramework.Game/README.md b/GFramework.Game/README.md index 60336e82..b4e8b8c2 100644 --- a/GFramework.Game/README.md +++ b/GFramework.Game/README.md @@ -169,6 +169,19 @@ 这两部分一般被上层子系统消费，不是多数项目的第一接入点。 +## XML 覆盖基线 + +下面这份 inventory 记录的是 `2026-04-23` 对 `GFramework.Game` 做的一轮轻量 XML 盘点结果：只统计公开 / +内部类型声明是否带 XML 注释，用来建立运行时阅读入口；成员级参数、返回值、异常和生命周期说明仍需要在后续 API 波次继续细化。 + +| 子系统 | 基线状态 | 代表类型 | 阅读重点 | +| --- | --- | --- | --- | +| `Config/` | `26/26` 个类型声明已带 XML 注释 | `YamlConfigLoader`、`ConfigRegistry`、`GameConfigBootstrap`、`YamlConfigSchemaValidator` | 看 YAML 加载、schema 校验、模块接入与热重载边界 | +| `Data/` `Storage/` `Serializer/` | `8/8` 个类型声明已带 XML 注释 | `DataRepository`、`SaveRepository`、`UnifiedSettingsDataRepository`、`FileStorage`、`JsonSerializer` | 看持久化布局、槽位存档、统一设置文件和底层序列化 / 存储实现 | +| `Setting/` | `9/9` 个类型声明已带 XML 注释 | `SettingsModel`、`SettingsSystem`、`SettingsAppliedEvent` | 看初始化、应用、保存、重置等设置生命周期编排 | +| `Scene/` `UI/` `Routing/` | `10/10` 个类型声明已带 XML 注释 | `SceneRouterBase`、`UiRouterBase`、`SceneTransitionPipeline`、`UiTransitionPipeline`、`RouterBase` | 看路由基类、转换处理器和项目层需要自己提供的 factory / root 边界 | +| `Extensions/` `Internal/` `State/` | `3/3` 个类型声明已带 XML 注释 | `DataLocationExtensions`、`VersionedMigrationRunner`、`GameStateMachineSystem` | 看辅助扩展、内部迁移执行逻辑和游戏态状态机封装 | + ## 最小接入路径 下面按最常见的四种接入目标给出最短路径。 diff --git a/ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md b/ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md index 350e49a0..941b7f00 100644 --- a/ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md +++ b/ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md @@ -12,12 +12,12 @@ ## 当前恢复点 -- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-004` -- 当前阶段：`Phase 3 - Cqrs Docs Refresh` +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-005` +- 当前阶段：`Phase 4 - Game Docs Refresh` - 当前焦点： - - 收口 `Cqrs` / `Cqrs.Abstractions` / `Cqrs.SourceGenerators` 的 landing / generator topic / API 入口 + - 收口 `Game` / `Game.Abstractions` / `Game.SourceGenerators` 的 README / landing / abstractions / XML inventory - 延续 `README / landing / API reference / XML inventory` 的同一治理模板 - - 为下一波 `Game` family 审计保留统一的恢复模板与验证口径 + - 把 `Game.Abstractions` 从失真的接口摘录页收敛为真实契约边界页面，并为下一轮巡检保留统一口径 ## 当前状态摘要 @@ -47,6 +47,10 @@ - 新建 `docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`，为 `Cqrs.SourceGenerators` 补齐站内专题入口 - 更新 `docs/zh-CN/source-generators/index.md`、`docs/zh-CN/api-reference/index.md` 与 VitePress sidebar，使 `Cqrs` family 的 generator 入口可导航 - 为 `GFramework.Cqrs/Internal/CqrsHandlerRegistrar.cs` 与 `GFramework.Cqrs.SourceGenerators/Cqrs/CqrsHandlerRegistryGenerator.cs` 中缺失的内部类型补齐 XML 注释，使本轮轻量 inventory 达到声明级闭环 + - 为 `GFramework.Game/README.md`、`GFramework.Game.Abstractions/README.md`、`GFramework.Game.SourceGenerators/README.md` 补齐 `Game` family 的类型族级 XML inventory + - 为 `docs/zh-CN/game/index.md` 补齐 frontmatter，并增加 `Game` / `Game.Abstractions` / `Game.SourceGenerators` 的 XML 覆盖基线入口 + - 将 `docs/zh-CN/abstractions/game-abstractions.md` 从失真的旧接口摘录页重写为契约边界 / 包关系 / 最小接入路径页面 + - 基于顶层目录轻量盘点确认：`GFramework.Game` 为 `56/56`、`GFramework.Game.Abstractions` 为 `80/80`、`GFramework.Game.SourceGenerators` 为 `2/2`，当前公开 / 内部类型声明都已带 XML 注释 ## Inventory（第一版） @@ -54,7 +58,7 @@ | --- | --- | --- | --- | | `Core` / `Core.Abstractions` | `README / landing / 类型族级 XML inventory 已收口，成员级审计待补齐` | 根 README、模块 README、`docs/zh-CN/core/**`、`docs/zh-CN/abstractions/core-abstractions.md` 已对齐当前目录与类型族基线 | 进入巡检；如有新 API 变更，再追加成员级 XML 审计 | | `Cqrs` / `Cqrs.Abstractions` / `Cqrs.SourceGenerators` | `README / landing / generator topic / 类型族级 XML inventory 已收口，成员级审计待补齐` | `GFramework.Cqrs/README.md`、`GFramework.Cqrs.Abstractions/README.md`、`GFramework.Cqrs.SourceGenerators/README.md`、`docs/zh-CN/core/cqrs.md`、`docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`、`docs/zh-CN/api-reference/index.md` 已对齐当前源码与测试 | 转入巡检；下一波切到 `Game` family 的 XML / 教程链路审计 | -| `Game` / `Game.Abstractions` / `Game.SourceGenerators` | `已验证` | 根 README、模块 README、`docs/zh-CN/game/**` 和 abstractions 页已存在 | 后续波次补 XML / 教程链路审计 | +| `Game` / `Game.Abstractions` / `Game.SourceGenerators` | `README / landing / abstractions / 类型族级 XML inventory 已收口，成员级审计待补齐` | `GFramework.Game/README.md`、`GFramework.Game.Abstractions/README.md`、`GFramework.Game.SourceGenerators/README.md`、`docs/zh-CN/game/index.md`、`docs/zh-CN/abstractions/game-abstractions.md` 已对齐当前源码与目录基线 | 转入巡检；优先抽查 `config-system`、`scene`、`ui` 与 `source-generators` 交叉链路是否回漂 | | `Godot` / `Godot.SourceGenerators` | `已验证` | 上一轮归档 topic 已完成核心 landing / topic / tutorial 校验 | 进入巡检周期，重点看回漂 | | `Ecs.Arch` / `Ecs.Arch.Abstractions` | `README / landing / abstractions / 类型族级 XML inventory 已收口，成员级审计待补齐` | `GFramework.Ecs.Arch/README.md`、`GFramework.Ecs.Arch.Abstractions/README.md`、`docs/zh-CN/ecs/**`、`docs/zh-CN/abstractions/ecs-arch-abstractions.md` 已对齐当前源码与测试 | 转入巡检；后续仅在运行时公共 API 变动时补成员级 XML 细审 | | `SourceGenerators.Common` 与 `*.SourceGenerators.Abstractions` | `已判定为内部支撑` | `*.csproj` 明确 `IsPackable=false` | 由所属模块 README 与生成器栏目说明 owner，不建独立采用页 | @@ -76,8 +80,8 @@ - 当前 `Core` / `Core.Abstractions` 只完成了类型族级 XML 基线，不等于成员级契约全审计 - 缓解措施：后续只在共享抽象或高风险生命周期接口发生改动时补成员级细审，不在本轮扩张范围 -- 其他模块族尚未全部建立同粒度的 XML inventory - - 缓解措施：按 `Ecs`、`Cqrs`、`Game` 的波次顺序继续推广同一模板 +- `Godot` family 的治理结论主要留在已归档 topic 中，active topic 当前只保留摘要 + - 缓解措施：后续巡检优先抽查 `Godot` 入口页是否仍与归档结论一致，必要时把关键 XML inventory 摘要迁回 active topic - 新功能分支若修改 README / docs / 公共 API 却不挂文档 topic，仍可能回漂 - 缓解措施：将本 topic 作为长期 active topic 保留，并在后续巡检中记录回漂来源 - VitePress 页面不能直接链接到 `docs/` 目录之外的模块 `README.md` @@ -138,9 +142,21 @@ - `cd docs && bun run build` - 结果：通过 - 备注：`2026-04-22` 在 `Cqrs` 波次文档刷新后重新构建通过；仅保留 VitePress 大 chunk warning，无构建失败 +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions/game-abstractions.md` +- 结果：通过 +- 备注：`2026-04-23` 在重写 `Game.Abstractions` 页面后验证通过 +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/index.md` +- 结果：通过 +- 备注：`2026-04-23` 在补充 frontmatter 与 XML inventory 后重新验证 +- `python3` 轻量 XML inventory 扫描 +- 结果：通过 +- 备注：`2026-04-23` 确认 `GFramework.Game` 为 `56/56`、`GFramework.Game.Abstractions` 为 `80/80`、`GFramework.Game.SourceGenerators` 为 `2/2` +- `cd docs && bun run build` +- 结果：通过 +- 备注：`2026-04-23` 在 `Game` 波次文档刷新后重新构建通过；仅保留 VitePress 大 chunk warning，无构建失败 ## 下一步 -1. 切换到 `Game` / `Game.Abstractions` / `Game.SourceGenerators` 波次，按 `Cqrs` 模板核对 README / landing / tutorials / API reference / XML 链路 -2. 评估 `Game` family 当前是否已经具备类型族级 XML inventory，还是仍停留在“README / 页面存在但不可审计” +1. 进入巡检周期，优先抽查 `docs/zh-CN/game/config-system.md`、`scene.md`、`ui.md` 与 `docs/zh-CN/source-generators/index.md` 的交叉引用是否仍与当前 `Game` family README 对齐 +2. 评估是否需要把 `Godot` family 的关键 XML inventory 摘要迁回 active topic，避免长期治理只依赖 archive 恢复 3. 在后续环境治理任务中单独处理 `GFramework.Cqrs` 本地 build 的 fallback package folder 阻塞，避免影响后续代码类验证 diff --git a/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md b/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md index 7b541418..4c938d80 100644 --- a/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md +++ b/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md @@ -141,3 +141,40 @@ 1. 切换到 `Game` family 波次，按 `Core` / `Ecs` / `Cqrs` 已验证模板继续补 XML inventory 与教程链路 2. 把 `GFramework.Cqrs` 的本地构建阻塞留给后续环境治理或构建脚本清理，不在本 topic 内扩张为环境修复任务 + +### 当前恢复点：RP-005 + +- 完成 `Game` 波次的模块族入口刷新： + - 更新 `GFramework.Game/README.md` + - 更新 `GFramework.Game.Abstractions/README.md` + - 更新 `GFramework.Game.SourceGenerators/README.md` + - 更新 `docs/zh-CN/game/index.md` + - 重写 `docs/zh-CN/abstractions/game-abstractions.md` +- 将 `Game` family 从“README / 页面存在但缺少可审计 XML 入口，且 abstractions 页失真”推进到“runtime / abstractions / source generator 都有声明级 XML inventory 与真实采用边界” +- 基于轻量扫描确认： + - `GFramework.Game` 当前类型声明级 XML 覆盖为 `56/56` + - `GFramework.Game.Abstractions` 当前类型声明级 XML 覆盖为 `80/80` + - `GFramework.Game.SourceGenerators` 当前类型声明级 XML 覆盖为 `2/2` + +### 当前决策（RP-005） + +- `docs/zh-CN/abstractions/game-abstractions.md` 不再维护虚构接口摘录，而是与源码中的 `Config` / `Data` / `Setting` / `Scene` / `UI` / `Routing` 契约分组保持一致 +- `Game.SourceGenerators` 继续以 `README + docs/zh-CN/game/config-system.md + docs/zh-CN/source-generators/index.md` 组成入口，不额外新增只为凑数量的专题页 +- `docs/zh-CN/game/index.md` 补 frontmatter，并承担 `Game` family 的 XML 基线入口；更细的类型族说明继续留在模块 README 与 abstractions 页 + +### 当前验证（RP-005） + +- 文档校验： + - `validate-all.sh docs/zh-CN/abstractions/game-abstractions.md`：通过 + - `validate-all.sh docs/zh-CN/game/index.md`：通过 +- 轻量 XML inventory： + - `GFramework.Game`：`56/56` + - `GFramework.Game.Abstractions`：`80/80` + - `GFramework.Game.SourceGenerators`：`2/2` +- 构建校验： + - `cd docs && bun run build`：通过；仅保留 VitePress 大 chunk warning，无构建失败 + +### 下一步 + +1. 进入 `Game` family 巡检，优先检查 `config-system.md`、`scene.md`、`ui.md` 与 `source-generators/index.md` 的交叉引用是否回漂 +2. 评估是否需要把 `Godot` family 的关键 XML inventory 摘要迁回 active topic，减少对 archive 的依赖 diff --git a/docs/zh-CN/abstractions/game-abstractions.md b/docs/zh-CN/abstractions/game-abstractions.md index bb854ca2..196557e0 100644 --- a/docs/zh-CN/abstractions/game-abstractions.md +++ b/docs/zh-CN/abstractions/game-abstractions.md @@ -1,94 +1,122 @@ -# Game Abstractions - -> GFramework.Game.Abstractions 游戏模块抽象接口定义 - -## 概述 - -GFramework.Game.Abstractions 包含了游戏特定功能的抽象接口，这些接口定义了游戏开发中的通用契约。 - -## 存档接口 - -### ISaveSystem - -存档系统接口： - -```csharp -public interface ISaveSystem -{ - void Save(string slotId, SaveData data); - SaveData Load(string slotId); - bool HasSave(string slotId); - void Delete(string slotId); - List GetAllSaveSlots(); -} -``` - -### ISaveData - -存档数据接口： - -```csharp -public interface ISaveData -{ - int Version { get; } - DateTime Timestamp { get; } - void Validate(); -} -``` - -## 设置接口 - -### IGameSettings - -游戏设置接口： - -```csharp -public interface IGameSettings -{ - AudioSettings Audio { get; } - GraphicsSettings Graphics { get; } - InputSettings Input { get; } - - void Save(); - void Load(); - void ResetToDefaults(); -} -``` - -## 场景管理接口 - -### ISceneManager - -场景管理器接口： - -```csharp -public interface ISceneManager -{ - void SwitchScene() where TScene : IScene; - Task SwitchSceneAsync() where TScene : IScene; - - void PushScene() where TScene : IScene; - void PopScene(); - - IScene CurrentScene { get; } -} -``` - -### IScene - -场景接口： - -```csharp -public interface IScene -{ - void OnEnter(); - void OnExit(); - void OnUpdate(float delta); -} -``` +--- +title: Game Abstractions +description: GFramework.Game.Abstractions 的契约边界、包关系与 XML 阅读重点。 --- -**相关文档**： +# Game Abstractions -- [Game 概述](../game/index.md) -- [核心抽象](./core-abstractions.md) +`GFramework.Game.Abstractions` 是 `Game` 运行时的契约包。 + +它建立在 `GFramework.Core.Abstractions` 之上，负责定义配置、数据、设置、场景、UI、路由、存储和资源注册表相关的接口、 +枚举与事件契约；默认实现、路由基类、YAML 加载器、文件存储和设置 / 存档仓库则在 `GFramework.Game` 中。 + +如果你要开箱即用地接入游戏运行时能力，应依赖 `GFramework.Game`；如果你在做共享业务层、feature 包、测试替身或引擎适配层， +才单独消费本包。 + +## 什么时候单独依赖它 + +- 你希望公共业务层只依赖 `ISceneRouter`、`IUiRouter`、`ISettingsSystem`、`ISaveRepository` 这类契约 +- 你要让多个程序集共享 `ISettingsData`、`IData`、`ISceneEnterParam`、`IUiPageEnterParam` 等数据和路由上下文 +- 你需要自己实现 factory、root、存储或配置加载器，但不想把默认运行时一起带进来 + +## 包关系 + +- 契约层：`GFramework.Game.Abstractions` +- 运行时实现：`GFramework.Game` +- 底层基础契约：`GFramework.Core.Abstractions` + +## 契约地图 + +| 契约族 | 作用 | +| --- | --- | +| `Config/` | `IConfigLoader`、`IConfigRegistry`、`IConfigTable` 和配置失败诊断模型 | +| `Data/` | `IData`、`IVersionedData`、`IDataRepository`、`ISettingsDataRepository`、`ISaveRepository` 及数据事件 | +| `Setting/` | `ISettingsData`、`ISettingsModel`、`ISettingsSystem`、设置迁移契约与内置设置数据类型 | +| `Scene/` | `IScene`、`ISceneRouter`、`ISceneFactory`、`ISceneRoot`、转场处理器与事件 | +| `UI/` | `IUiPage`、`IUiRouter`、`IUiFactory`、`IUiRoot`、交互配置与 UI 转场选项 | +| `Routing/` | `IRoute`、`IRouteContext`、`IRouteGuard`，作为 Scene / UI 共享的路由基础约定 | +| `Storage/` `Asset/` `Enums/` | 文件存储角色、资源注册表，以及转场 / UI 层级 / 输入动作等跨层枚举 | + +## XML 覆盖基线 + +下面这份 inventory 记录的是 `2026-04-23` 对 `GFramework.Game.Abstractions` 做的一轮轻量 XML 盘点结果：只统计公开 / +内部类型声明是否带 XML 注释，用来建立契约层阅读入口；成员级参数、返回值、异常和生命周期说明仍需要后续 API 波次继续细化。 + +| 契约族 | 基线状态 | 代表类型 | 阅读重点 | +| --- | --- | --- | --- | +| `Config/` | `7/7` 个类型声明已带 XML 注释 | `IConfigLoader`、`IConfigRegistry`、`IConfigTable`、`ConfigLoadException` | 看配置表注册、只读访问和失败诊断边界 | +| `Data/` | `14/14` 个类型声明已带 XML 注释 | `IDataRepository`、`ISettingsDataRepository`、`ISaveRepository`、`DataRepositoryOptions` | 看业务数据、统一设置文件、槽位存档与迁移契约 | +| `Setting/` | `12/12` 个类型声明已带 XML 注释 | `ISettingsData`、`ISettingsModel`、`ISettingsSystem`、`LocalizationSettings` | 看设置生命周期、应用语义、迁移接口和内置设置对象 | +| `Scene/` | `14/14` 个类型声明已带 XML 注释 | `IScene`、`ISceneRouter`、`ISceneFactory`、`SceneTransitionEvent` | 看场景行为、工厂 / root 边界和转场模型 | +| `UI/` | `19/19` 个类型声明已带 XML 注释 | `IUiPage`、`IUiRouter`、`IUiFactory`、`UiInteractionProfile`、`UiTransitionHandlerOptions` | 看页面栈、层级 UI、输入动作和 UI 转场契约 | +| `Routing/` `Storage/` `Asset/` `Enums/` | `13/13` 个类型声明已带 XML 注释 | `IRoute`、`IRouteContext`、`IFileStorage`、`IAssetRegistry`、`UiLayer`、`SceneTransitionType` | 看公共路由上下文、存储角色、资源注册表与共享枚举 | + +## 最小接入路径 + +### 1. 只在公共业务层声明游戏对象 + +```csharp +using GFramework.Game.Abstractions.Data; +using GFramework.Game.Abstractions.Scene; +using GFramework.Game.Abstractions.UI; + +public sealed class GameSaveData : IVersionedData +{ + public int Version { get; set; } = 1; + public DateTime LastModified { get; set; } = DateTime.UtcNow; +} + +public sealed class GameplayEnterParam : ISceneEnterParam +{ + public required string Seed { get; init; } +} + +public sealed class PauseMenuParam : IUiPageEnterParam +{ + public bool AllowRestart { get; init; } +} +``` + +### 2. 让 feature 包只依赖抽象 + +```csharp +using GFramework.Game.Abstractions.Data; +using GFramework.Game.Abstractions.Scene; + +public sealed class ContinueGameCommandHandler +{ + private readonly ISaveRepository _saveRepository; + private readonly ISceneRouter _sceneRouter; + + public ContinueGameCommandHandler( + ISaveRepository saveRepository, + ISceneRouter sceneRouter) + { + _saveRepository = saveRepository; + _sceneRouter = sceneRouter; + } +} +``` + +### 3. 什么时候切到运行时包 + +下面这些需求都属于 `GFramework.Game` 的职责，而不是本包： + +- 使用默认的 `JsonSerializer`、`FileStorage` 或 `ScopedStorage` +- 使用 `SettingsModel`、`SettingsSystem`、`SaveRepository` 等默认实现 +- 使用 `YamlConfigLoader`、`GameConfigBootstrap`、`GameConfigModule` +- 继承 `SceneRouterBase`、`UiRouterBase` 或默认转场处理器基类 + +## 阅读顺序 + +1. 先读本页，确认你是否真的只需要契约层 +2. 再看 [`../game/index.md`](../game/index.md) 了解默认运行时怎么组织这些契约 +3. 继续读具体专题页： + - [`../game/config-system.md`](../game/config-system.md) + - [`../game/data.md`](../game/data.md) + - [`../game/setting.md`](../game/setting.md) + - [`../game/scene.md`](../game/scene.md) + - [`../game/ui.md`](../game/ui.md) +4. 需要仓库侧入口时，回到： + - `GFramework.Game.Abstractions/README.md` + - `GFramework.Game/README.md` diff --git a/docs/zh-CN/game/index.md b/docs/zh-CN/game/index.md index 59a00443..4857a76c 100644 --- a/docs/zh-CN/game/index.md +++ b/docs/zh-CN/game/index.md @@ -1,3 +1,8 @@ +--- +title: Game +description: GFramework.Game family 的运行时入口、采用顺序与 XML 阅读基线。 +--- + # Game `Game` 栏目对应 `GFramework.Game` 与 `GFramework.Game.Abstractions` 这层游戏运行时能力。 @@ -98,6 +103,16 @@ IStorage storage = new FileStorage("GameData", serializer); 4. [setting](./setting.md) 5. [scene](./scene.md) 或 [ui](./ui.md) +## Game Family XML 覆盖基线 + +下面这份 inventory 记录的是 `2026-04-23` 对 `Game` family 做的一轮轻量 XML 盘点结果：只统计公开 / 内部类型声明是否带 XML 注释，用来建立 README / landing / API 阅读链路；成员级 `param`、`returns`、`exception` 与生命周期说明仍需要后续波次继续细化。 + +| 模块 | 基线状态 | 代表类型 | 阅读重点 | +| --- | --- | --- | --- | +| `GFramework.Game` | `56/56` 个类型声明已带 XML 注释 | `YamlConfigLoader`、`SettingsModel`、`SceneRouterBase`、`UiRouterBase` | 先看运行时默认实现、配置加载、设置编排和路由基类 | +| `GFramework.Game.Abstractions` | `80/80` 个类型声明已带 XML 注释 | `IConfigRegistry`、`ISaveRepository`、`ISettingsSystem`、`ISceneRouter`、`IUiRouter` | 再看契约层边界，决定项目哪些程序集只依赖接口 | +| `GFramework.Game.SourceGenerators` | `2/2` 个类型声明已带 XML 注释 | `SchemaConfigGenerator`、`ConfigSchemaDiagnostics` | 最后看 schema 生成入口与诊断模型，确认配置系统的编译期链路 | + ## 与真实接法的关系 这个栏目以源码、`*.csproj`、模块 `README.md` 与 `ai-libs/` 下已验证的参考接法为准。