diff --git a/GFramework.Ecs.Arch.Abstractions/README.md b/GFramework.Ecs.Arch.Abstractions/README.md new file mode 100644 index 00000000..d79bdf80 --- /dev/null +++ b/GFramework.Ecs.Arch.Abstractions/README.md @@ -0,0 +1,93 @@ +# GFramework.Ecs.Arch.Abstractions + +`GFramework.Ecs.Arch.Abstractions` 承载 Arch ECS 集成层的最小契约，用来让共享业务层、宿主循环或扩展模块在不依赖 +`GFramework.Ecs.Arch` 默认实现的前提下，仍然可以约定 ECS 模块边界。 + +如果你需要的是 `UseArch(...)` 扩展、`ArchSystemAdapter` 基类、`World` 注册和默认模块实现，请改为依赖 +`GFramework.Ecs.Arch`。 + +## 包定位 + +- 这是 `Ecs.Arch` 的契约层，不是默认实现层。 +- 适合让上层模块只面向 `IArchEcsModule`、`IArchSystemAdapter` 和 `ArchOptions` 编程。 +- 常见场景： + - 共享宿主循环只依赖更新契约，不直接引用 Arch runtime 实现 + - 多程序集之间需要共享 ECS 配置对象或接口边界 + - 测试替身、编辑器工具或外部适配层希望复用契约，但自行决定底层实现 + +## 与相邻包的关系 + +- `GFramework.Core.Abstractions` + - 本包直接依赖它，并复用 `IServiceModule`、`ISystem` 等基础契约。 +- `GFramework.Ecs.Arch.Abstractions` + - 只定义 Arch ECS 集成相关的最小契约和配置对象。 +- `GFramework.Ecs.Arch` + - 本包的默认实现层。 + - 负责 `UseArch(...)` 扩展、默认模块注册、Arch `World` 装配，以及系统适配器基类。 + +## 契约地图 + +| 文件 | 作用 | +| --- | --- | +| `IArchEcsModule.cs` | ECS 模块服务契约，负责统一驱动系统更新 | +| `IArchSystemAdapter.cs` | 让 ECS 系统适配到 GFramework `ISystem` 生命周期的接口 | +| `ArchOptions.cs` | `WorldCapacity`、`EnableStatistics`、`Priority` 等配置对象 | + +## 最小接入路径 + +### 1. 只想约定宿主循环与 ECS 模块边界 + +```csharp +using GFramework.Ecs.Arch.Abstractions; + +public sealed class EcsUpdateLoop +{ + private readonly IArchEcsModule _ecsModule; + + public EcsUpdateLoop(IArchEcsModule ecsModule) + { + _ecsModule = ecsModule; + } + + public void Tick(float deltaTime) + { + _ecsModule.Update(deltaTime); + } +} +``` + +### 2. 只想共享配置对象 + +```csharp +using GFramework.Ecs.Arch.Abstractions; + +var options = new ArchOptions +{ + WorldCapacity = 2048, + EnableStatistics = true, + Priority = 40 +}; +``` + +### 3. 什么时候要升级到 `GFramework.Ecs.Arch` + +一旦你需要下面任一项，就不该只停留在本包： + +- `UseArch(...)` 或其他 runtime 装配入口 +- `ArchSystemAdapter` 等默认基类 +- Arch `World` 的创建、注册和查询能力 +- 与 `GFramework` 架构生命周期绑定的默认模块实现 + +## 边界说明 + +- 本包不提供 Arch `World` 的默认构造与注册逻辑。 +- 本包不提供系统基类、扩展方法或默认服务实现。 +- 它回答的是“外部模块怎样与 Arch ECS 集成层约定边界”，不是“Arch ECS 默认怎么接入到项目里”。 + +## 对应文档入口 + +- 抽象接口总览：[`../docs/zh-CN/abstractions/index.md`](../docs/zh-CN/abstractions/index.md) +- Ecs.Arch 抽象层说明：[`../docs/zh-CN/abstractions/ecs-arch-abstractions.md`](../docs/zh-CN/abstractions/ecs-arch-abstractions.md) +- ECS 模块入口：[`../docs/zh-CN/ecs/index.md`](../docs/zh-CN/ecs/index.md) +- Arch ECS 集成：[`../docs/zh-CN/ecs/arch.md`](../docs/zh-CN/ecs/arch.md) +- 运行时实现入口：[`../GFramework.Ecs.Arch/README.md`](../GFramework.Ecs.Arch/README.md) diff --git a/README.md b/README.md index 2c4f8634..af805a2f 100644 --- a/README.md +++ b/README.md @@ -27,11 +27,22 @@ | `GFramework.Game.Abstractions` | `Game` 对应的契约层 | [README](GFramework.Game.Abstractions/README.md) | | `GFramework.Godot` | Godot 集成层，负责把框架能力接入节点、场景、UI、设置与存储 | [README](GFramework.Godot/README.md) | | `GFramework.Ecs.Arch` | Arch ECS 集成 | [README](GFramework.Ecs.Arch/README.md) | +| `GFramework.Ecs.Arch.Abstractions` | Arch ECS 集成对应的契约层，适合共享宿主循环与 ECS 模块边界 | [README](GFramework.Ecs.Arch.Abstractions/README.md) | | `GFramework.Core.SourceGenerators` | Core 侧通用源码生成器与分析器 | [README](GFramework.Core.SourceGenerators/README.md) | | `GFramework.Game.SourceGenerators` | 游戏内容配置 schema 生成器 | [README](GFramework.Game.SourceGenerators/README.md) | | `GFramework.Cqrs.SourceGenerators` | CQRS handler registry 生成器 | [README](GFramework.Cqrs.SourceGenerators/README.md) | | `GFramework.Godot.SourceGenerators` | Godot 场景专用源码生成器 | [README](GFramework.Godot.SourceGenerators/README.md) | +## 内部支撑模块 + +以下目录目前不是独立采用入口，而是跟随所属模块维护的内部支撑组件： + +| 目录 | 定位 | 跟随入口 | +| --- | --- | --- | +| `GFramework.Core.SourceGenerators.Abstractions` | `Core.SourceGenerators` 的内部契约层 | [GFramework.Core.SourceGenerators/README.md](GFramework.Core.SourceGenerators/README.md) | +| `GFramework.Godot.SourceGenerators.Abstractions` | `Godot.SourceGenerators` 的内部契约层 | [GFramework.Godot.SourceGenerators/README.md](GFramework.Godot.SourceGenerators/README.md) | +| `GFramework.SourceGenerators.Common` | 生成器家族共享的公共支撑代码 | [docs/zh-CN/source-generators/index.md](docs/zh-CN/source-generators/index.md) | + ## 文档导航 仓库根 README 与文档站点保持同一套栏目命名： @@ -119,10 +130,13 @@ GFramework.sln ├─ GFramework.Game.Abstractions/ ├─ GFramework.Godot/ ├─ GFramework.Ecs.Arch/ +├─ GFramework.Ecs.Arch.Abstractions/ ├─ GFramework.Core.SourceGenerators/ +├─ GFramework.Core.SourceGenerators.Abstractions/ ├─ GFramework.Game.SourceGenerators/ ├─ GFramework.Cqrs.SourceGenerators/ ├─ GFramework.Godot.SourceGenerators/ +├─ GFramework.Godot.SourceGenerators.Abstractions/ ├─ GFramework.SourceGenerators.Common/ └─ docs/ ``` diff --git a/ai-plan/public/README.md b/ai-plan/public/README.md index 74fad82f..f5efae2b 100644 --- a/ai-plan/public/README.md +++ b/ai-plan/public/README.md @@ -25,6 +25,11 @@ help the current worktree land on the right recovery documents without scanning - Purpose: continue the AI-First config runtime, generator, and consumer DX work for `GFramework.Game`. - Tracking: `ai-plan/public/ai-first-config-system/todos/ai-first-config-system-tracking.md` - Trace: `ai-plan/public/ai-first-config-system/traces/ai-first-config-system-trace.md` +- `documentation-full-coverage-governance` + - Purpose: govern full-coverage documentation inventory, module-wave remediation, and the README / docs / XML / + API-reference alignment baseline. + - Tracking: `ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md` + - Trace: `ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md` - `coroutine-optimization` - Purpose: continue the coroutine semantics, host integration, observability, regression coverage, and migration-doc follow-up work. @@ -58,6 +63,9 @@ help the current worktree land on the right recovery documents without scanning - Branch: `feat/data-repository-persistence` - Worktree hint: `GFramework-data-repository-persistence` - Priority 1: `data-repository-persistence` +- Branch: `docs/sdk-update-documentation` + - Worktree hint: `GFramework-update-documentation` + - Priority 1: `documentation-full-coverage-governance` ## Archived Topics - `cqrs-cache-docs-hardening` 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 new file mode 100644 index 00000000..1bddcd54 --- /dev/null +++ b/ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md @@ -0,0 +1,89 @@ +# Documentation Full Coverage Governance 跟踪 + +## 目标 + +建立一个长期 active topic，持续治理 `GFramework` 的 README、`docs/zh-CN`、站点导航、XML 文档和 API +参考链路，避免历史上的阶段性刷新完成后再次回漂。 + +- 用源码、测试、`*.csproj` 和必要的 `ai-libs/` 证据校正文档 +- 以模块族为单位闭环 README、landing page、专题页、教程入口和 API 参考链路 +- 明确哪些目录是可直接消费模块，哪些只是内部支撑模块 +- 把 XML 文档缺口纳入治理范围，而不是只刷新 Markdown + +## 当前恢复点 + +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-001` +- 当前阶段：`Phase 1 - Inventory And Governance Bootstrap` +- 当前焦点： + - 注册新的长期文档治理 topic，并把当前分支映射到该 topic + - 落第一版模块化 inventory、缺口分级和治理波次顺序 + - 立即补齐已确认的 README / 入口缺口：`GFramework.Ecs.Arch.Abstractions` + - 把 `api-reference` 页面改成真实的 API 链路入口，而不是失真的伪 API 列表 + +## 当前状态摘要 + +- 已归档的 `documentation-governance-and-refresh` 仅保留为历史证据，不再作为默认 `boot` 入口 +- 本轮已确认的消费属性结论： + - `GFramework.Ecs.Arch.Abstractions`：可打包直接消费模块，需要 README 和文档入口 + - `GFramework.Core.SourceGenerators.Abstractions`：`IsPackable=false`，按内部支撑模块处理 + - `GFramework.Godot.SourceGenerators.Abstractions`：`IsPackable=false`，按内部支撑模块处理 + - `GFramework.SourceGenerators.Common`：`IsPackable=false`，按内部支撑模块处理 +- 本轮已完成的治理动作： + - 新建 `GFramework.Ecs.Arch.Abstractions/README.md` + - 在根 `README.md` 中补齐 `GFramework.Ecs.Arch.Abstractions` 入口，并声明内部支撑模块 owner + - 为抽象接口栏目补齐 `Ecs.Arch.Abstractions` 页面与 sidebar 入口 + - 将 `docs/zh-CN/api-reference/index.md` 重写为模块到 XML / README / 教程的阅读链路入口 + +## Inventory（第一版） + +| 模块族 | 当前状态 | 当前证据 | 下一动作 | +| --- | --- | --- | --- | +| `Core` / `Core.Abstractions` | `已验证` | 根 README、模块 README、`docs/zh-CN/core/**`、`docs/zh-CN/abstractions/core-abstractions.md` 已存在 | 进入首轮波次时补 XML 文档 inventory | +| `Cqrs` / `Cqrs.Abstractions` / `Cqrs.SourceGenerators` | `待重写` | README 已存在；站内入口目前分散在 `docs/zh-CN/core/cqrs.md` 与 `docs/zh-CN/source-generators/**` | 在 `Cqrs` 波次里补 dedicated landing / API map 审计 | +| `Game` / `Game.Abstractions` / `Game.SourceGenerators` | `已验证` | 根 README、模块 README、`docs/zh-CN/game/**` 和 abstractions 页已存在 | 后续波次补 XML / 教程链路审计 | +| `Godot` / `Godot.SourceGenerators` | `已验证` | 上一轮归档 topic 已完成核心 landing / topic / tutorial 校验 | 进入巡检周期，重点看回漂 | +| `Ecs.Arch` / `Ecs.Arch.Abstractions` | `待重写` | runtime README 已存在；`Ecs.Arch.Abstractions` README 与抽象页已在本轮补齐；`docs/zh-CN/ecs/index.md` / `arch.md` 仍偏旧 | 在 `Ecs` 波次重写 runtime docs 并补 XML map | +| `SourceGenerators.Common` 与 `*.SourceGenerators.Abstractions` | `已判定为内部支撑` | `*.csproj` 明确 `IsPackable=false` | 由所属模块 README 与生成器栏目说明 owner，不建独立采用页 | + +## 缺口分级 + +- `P0` + - 错误采用路径、错误包关系、错误 API / 生命周期语义 + - 站点导航死链、空 landing page、明显错误的模块 owner +- `P1` + - 直接消费模块缺 README 或缺对应 docs 入口 + - README / docs 示例与源码实现不一致 + - 教程仍引用已经过时的默认接线方式 +- `P2` + - 结构重复、交叉链接不足、API 参考链路过薄 + - 站内页面存在事实正确但组织方式不利于定位的内容 + +## 当前风险 + +- `docs/zh-CN/ecs/index.md` 与 `docs/zh-CN/ecs/arch.md` 仍保留较多早期表述，本轮只先完成 inventory 与入口补齐 + - 缓解措施：把 `Ecs.Arch` 排进前五波次，并把 runtime docs 重写列为该波次的必做项 +- XML 文档尚未按模块做全量类型审计 + - 缓解措施：下一恢复点先从 `Core` 模块族建立“类型族 -> XML 覆盖状态”清单 +- 新功能分支若修改 README / docs / 公共 API 却不挂文档 topic，仍可能回漂 + - 缓解措施：将本 topic 作为长期 active topic 保留，并在后续巡检中记录回漂来源 + +## 验证说明 + +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions/index.md` +- 结果：通过 +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions/ecs-arch-abstractions.md` +- 结果：通过 +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/api-reference/index.md` +- 结果：通过 +- `cd docs && bun run build` +- 结果：通过 +- 备注：仅保留 VitePress 大 chunk warning，无构建失败 +- `dotnet build GFramework.Ecs.Arch.Abstractions/GFramework.Ecs.Arch.Abstractions.csproj -c Release -p:RestoreFallbackFolders=` +- 结果：通过 +- 备注：`0 Warning(s) / 0 Error(s)` + +## 下一步 + +1. 按波次顺序启动 `Core` / `Core.Abstractions` 的 XML 文档与 API 链路 inventory +2. 在 `Ecs` 波次重写 `docs/zh-CN/ecs/index.md` 与 `docs/zh-CN/ecs/arch.md` +3. 为每个模块族补一份“README / landing / tutorials / API reference / XML”对照表，持续清零 `P0` / `P1` 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 new file mode 100644 index 00000000..f87f45cd --- /dev/null +++ b/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md @@ -0,0 +1,35 @@ +# Documentation Full Coverage Governance Trace + +## 2026-04-22 + +### 当前恢复点：RP-001 + +- 按长期治理计划新建 active topic `documentation-full-coverage-governance` +- 在 `ai-plan/public/README.md` 中将当前分支 `docs/sdk-update-documentation` 映射到该 topic +- 复核已知缺口模块的 `*.csproj` 后确认： + - `GFramework.Ecs.Arch.Abstractions` 是可打包消费模块，需要独立 README + - `GFramework.Core.SourceGenerators.Abstractions`、`GFramework.Godot.SourceGenerators.Abstractions`、 + `GFramework.SourceGenerators.Common` 都是 `IsPackable=false` 的内部支撑模块 +- 基于该结论，本轮没有为内部支撑模块新增独立 README，而是在根 README 与 abstractions / API 入口中明确其 owner + +### 当前决策 + +- 新主题的完成条件采用长期治理口径：`P0` 清零、无 README 缺失、无导航死链，并完成连续两轮稳定巡检 +- 本轮先做治理基础设施与 inventory，不把整个长期计划伪装成单轮完成 +- `api-reference` 页面改为“模块 -> README / docs / XML / tutorial”的阅读链路入口，避免继续维护失真的伪签名列表 +- `Ecs.Arch` family 被列为高优先 backlog：抽象层入口已补齐，但 runtime docs 仍需按源码重写 + +### 当前验证 + +- 文档校验： + - `validate-all.sh docs/zh-CN/abstractions/index.md`：通过 + - `validate-all.sh docs/zh-CN/abstractions/ecs-arch-abstractions.md`：通过 + - `validate-all.sh docs/zh-CN/api-reference/index.md`：通过 +- 构建校验： + - `cd docs && bun run build`：通过 + - `dotnet build GFramework.Ecs.Arch.Abstractions/GFramework.Ecs.Arch.Abstractions.csproj -c Release -p:RestoreFallbackFolders=`：通过，`0 Warning(s) / 0 Error(s)` + +### 下一步 + +1. 进入 `Core` / `Core.Abstractions` 波次，先建立 XML 文档覆盖 inventory +2. 在 `Ecs` 波次重写运行时 docs，并把 `Ecs.Arch.Abstractions` 纳入完整模块闭环 diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 431f22f1..83795043 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -264,7 +264,8 @@ export default defineConfig({ text: '抽象接口', items: [ { text: 'Core Abstractions', link: '/zh-CN/abstractions/core-abstractions' }, - { text: 'Game Abstractions', link: '/zh-CN/abstractions/game-abstractions' } + { text: 'Game Abstractions', link: '/zh-CN/abstractions/game-abstractions' }, + { text: 'Ecs.Arch Abstractions', link: '/zh-CN/abstractions/ecs-arch-abstractions' } ] } ], diff --git a/docs/zh-CN/abstractions/ecs-arch-abstractions.md b/docs/zh-CN/abstractions/ecs-arch-abstractions.md new file mode 100644 index 00000000..63c04364 --- /dev/null +++ b/docs/zh-CN/abstractions/ecs-arch-abstractions.md @@ -0,0 +1,95 @@ +--- +title: Ecs.Arch Abstractions +description: GFramework.Ecs.Arch.Abstractions 的契约边界、包关系和最小接入路径。 +--- + +# Ecs.Arch Abstractions + +`GFramework.Ecs.Arch.Abstractions` 是 Arch ECS 集成层的契约包。 + +它建立在 `GFramework.Core.Abstractions` 之上，只定义 ECS 模块更新、系统适配和配置对象，不负责默认的 Arch +`World` 装配、扩展方法或系统基类。 + +如果你需要开箱即用的集成实现，请改为依赖 `GFramework.Ecs.Arch`。 + +## 什么时候单独依赖它 + +- 你在做共享宿主循环、工具层或 feature 包，只需要 `IArchEcsModule` +- 你想让不同程序集共享 `ArchOptions` 或系统适配契约，但不直接绑定默认 runtime +- 你需要为测试或外部适配层提供替身实现 + +## 包关系 + +- 契约层：`GFramework.Ecs.Arch.Abstractions` +- 运行时实现：`GFramework.Ecs.Arch` +- 底层基础契约：`GFramework.Core.Abstractions` + +## 契约地图 + +| 类型 | 作用 | +| --- | --- | +| `IArchEcsModule` | 统一更新 ECS 系统的服务模块契约 | +| `IArchSystemAdapter` | 让 ECS 系统适配到 `ISystem` 生命周期 | +| `ArchOptions` | 承载 `WorldCapacity`、`EnableStatistics`、`Priority` 等配置 | + +## 最小接入路径 + +### 1. 共享模块只依赖更新契约 + +```csharp +using GFramework.Ecs.Arch.Abstractions; + +public sealed class GameplayHost +{ + private readonly IArchEcsModule _ecsModule; + + public GameplayHost(IArchEcsModule ecsModule) + { + _ecsModule = ecsModule; + } + + public void Tick(float deltaTime) + { + _ecsModule.Update(deltaTime); + } +} +``` + +### 2. 共享配置对象 + +```csharp +using GFramework.Ecs.Arch.Abstractions; + +var options = new ArchOptions +{ + WorldCapacity = 2048, + EnableStatistics = true, + Priority = 40 +}; +``` + +### 3. 什么时候切到运行时包 + +下面这些需求都属于 `GFramework.Ecs.Arch` 的职责，而不是本包： + +- 通过 `UseArch(...)` 把模块挂进架构 +- 使用默认的 `ArchSystemAdapter` 基类 +- 访问 Arch `World` 与查询 API +- 使用默认的模块装配和生命周期实现 + +## 阅读顺序 + +1. 先读本页，确认你是否真的只需要契约层 +2. 如果需要默认实现，再看 [`../ecs/arch.md`](../ecs/arch.md) +3. 回到对应模块 README： + - `GFramework.Ecs.Arch.Abstractions/README.md` + - `GFramework.Ecs.Arch/README.md` + +## 边界提醒 + +- `GFramework.Core.SourceGenerators.Abstractions` +- `GFramework.Godot.SourceGenerators.Abstractions` +- `GFramework.SourceGenerators.Common` + +这些目录当前都不是独立消费模块，而是源码生成器家族的内部支撑组件。它们不属于抽象接口栏目里的独立采用入口， +应分别跟随 `Core.SourceGenerators`、`Godot.SourceGenerators` 或其他生成器模块的 README 与专题页维护。 diff --git a/docs/zh-CN/abstractions/index.md b/docs/zh-CN/abstractions/index.md index 38f9f7bc..4e1efc0c 100644 --- a/docs/zh-CN/abstractions/index.md +++ b/docs/zh-CN/abstractions/index.md @@ -1,3 +1,8 @@ +--- +title: 抽象接口 +description: GFramework 各抽象层模块的阅读入口与使用边界。 +--- + # 抽象接口 `GFramework.*.Abstractions` 用来承载跨模块协作所需的契约，而不是运行时实现。 @@ -12,9 +17,19 @@ - Core 抽象层：[`core-abstractions.md`](./core-abstractions.md) - Game 抽象层：[`game-abstractions.md`](./game-abstractions.md) +- Ecs.Arch 抽象层：[`ecs-arch-abstractions.md`](./ecs-arch-abstractions.md) ## 使用建议 - 如果你只是想直接使用框架功能，优先从对应运行时模块的 `README.md` 和栏目页开始。 - 只有在明确需要“契约层而非实现层”时，才单独依赖 `*.Abstractions` 包。 -- 抽象层页面会解释接口分组与职责；实际安装与接入路径，仍应以运行时模块 README 与 `getting-started` 为主。 \ No newline at end of file +- 抽象层页面会解释接口分组与职责；实际安装与接入路径，仍应以运行时模块 README 与 `getting-started` 为主。 + +## 当前边界 + +- `GFramework.Core.SourceGenerators.Abstractions` +- `GFramework.Godot.SourceGenerators.Abstractions` +- `GFramework.SourceGenerators.Common` + +这些目录当前不作为独立抽象接口栏目维护，而是作为源码生成器家族的内部支撑模块，分别跟随所属模块 README 和 +`source-generators` 栏目维护。 diff --git a/docs/zh-CN/api-reference/index.md b/docs/zh-CN/api-reference/index.md index 394ed10a..9dc1d72a 100644 --- a/docs/zh-CN/api-reference/index.md +++ b/docs/zh-CN/api-reference/index.md @@ -1,571 +1,81 @@ -# API 参考文档 - -本文档提供 GFramework 各模块的完整 API 参考。 - -## 核心命名空间 - -### GFramework.Core.architecture - -核心架构命名空间，包含所有基础组件。 - -#### 主要类型 - -| 类型 | 说明 | -|--------------------|--------| -| `Architecture` | 应用架构基类 | -| `AbstractModel` | 数据模型基类 | -| `AbstractSystem` | 业务系统基类 | -| `AbstractCommand` | 命令基类 | -| `AbstractQuery` | 查询基类 | -| `IController` | 控制器接口 | -| `IUtility` | 工具类接口 | - -### GFramework.Core.events - -事件系统命名空间。 - -#### 主要类型 - -| 类型 | 说明 | -|-------------------|----------| -| `IEvent` | 事件接口 | -| `IEventSystem` | 事件系统接口 | -| `TypeEventSystem` | 类型安全事件系统 | - -### GFramework.Core.property - -属性系统命名空间。 - -#### 主要类型 - -| 类型 | 说明 | -|-----------------------|--------| -| `BindableProperty` | 可绑定属性 | -| `IUnRegister` | 注销接口 | -| `IUnRegisterList` | 注销列表接口 | - -### GFramework.Core.ioc - -IoC 容器命名空间。 - -#### 主要类型 - -| 类型 | 说明 | -|--------------|------| -| `IContainer` | 容器接口 | -| `Container` | 容器实现 | - -### GFramework.Core.pool - -对象池命名空间。 - -#### 主要类型 - -| 类型 | 说明 | -|------------------|-------| -| `IObjectPool` | 对象池接口 | -| `ObjectPool` | 对象池实现 | - -### GFramework.Core.Localization - -本地化系统命名空间。 - -#### 主要类型 - -| 类型 | 说明 | -|--------------------------|----------| -| `ILocalizationManager` | 本地化管理器接口 | -| `ILocalizationTable` | 本地化表接口 | -| `ILocalizationString` | 本地化字符串接口 | -| `ILocalizationFormatter` | 格式化器接口 | -| `LocalizationConfig` | 本地化配置类 | -| `LocalizationManager` | 本地化管理器实现 | -| `LocalizationTable` | 本地化表实现 | -| `LocalizationString` | 本地化字符串实现 | - -## 常用 API - -### Architecture - -```csharp -public abstract class Architecture : IBelongToArchitecture -{ - // 初始化架构 - public void Initialize(); - - // 销毁架构 - public void Destroy(); - - // 注册模型 - public void RegisterModel(T model) where T : IModel; - - // 获取模型 - public T GetModel() where T : IModel; - - // 注册系统 - public void RegisterSystem(T system) where T : ISystem; - - // 获取系统 - public T GetSystem() where T : ISystem; - - // 注册工具 - public void RegisterUtility(T utility) where T : IUtility; - - // 获取工具 - public T GetUt>() where T : IUtility; - - // 发送命令 - public void SendCommand(T command) where T : ICommand; - - // 发送查询 - public TResult SendQuery(TQuery query) - where TQuery : IQuery; - - // 发送事件 - public void SendEvent(T e) where T : IEvent; -} -``` - -### AbstractModel - -```csharp -public abstract class AbstractModel : IBelongToArchitecture -{ - // 初始化模型 - protected abstract void OnInit(); - - // 销毁模型 - protected virtual void OnDestroy(); - - // 获取架构 - public IArchitecture GetArchitecture(); - - // 发送事件 - protected void SendEvent(T e) where T : IEvent; - - // 获取模型 - protected T GetModel() where T : IModel; - - // 获取系统 - protected T GetSystem() where T : ISystem; - - // 获取工具 - protected T GetUtility() where T : IUtility; -} -``` - -### AbstractSystem - -```csharp -public abstract class AbstractSystem : IBelongToArchitecture -{ - // 初始化系统 - protected abstract void OnInit(); - - // 销毁系统 - protected virtual void OnDestroy(); - - // 获取架构 - public IArchitecture GetArchitecture(); - - // 发送事件 - protected void SendEvent(T e) where T : IEvent; - - // 注册事件 - protected IUnRegister RegisterEvent(Action onEvent) - where T : IEvent; - - // 获取模型 - protected T GetModel() where T : IModel; - - // 获取系统 - protected T GetSystem() where T : ISystem; - - // 获取工具 - protected T GetUtility() where T : IUtility; -} -``` - -### AbstractCommand - -```csharp -public abstract class AbstractCommand : IBelongToArchitecture -{ - // 执行命令 - public void Execute(); - - // 命令实现 - protected abstract void OnDo(); - - // 获取架构 - public IArchitecture GetArchitecture(); - - // 发送事件 - protected void SendEvent(T e) where T : IEvent; - - // 获取模型 - protected T GetModel() where T : IModel; - - // 获取系统 - protected T GetSystem() where T : ISystem; - - // 获取工具 - protected T GetUtility() where T : IUtility; -} -``` - -### AbstractQuery`` - -```csharp -public abstract class AbstractQuery : IBelongToArchitecture -{ - // 执行查询 - public T Do(); - - // 查询实现 - protected abstract T OnDo(); - - // 获取架构 - public IArchitecture GetArchitecture(); - - // 获取模型 - protected T GetModel() where T : IModel; - - // 获取系统 - protected T GetSystem() where T : ISystem; - - // 获取工具 - protected T GetUtility() where T : IUtility; -} -``` - -### BindableProperty`` - -```csharp -public class BindableProperty -{ - // 构造函数 - public BindableProperty(T initialValue = default); - - // 获取或设置值 - public T Value { get; set; } - - // 注册监听器 - public IUnRegister Register(Action onValueChanged); - - // 注册监听器（包含初始值） - public IUnRegister RegisterWithInitValue(Action onValueChanged); - - // 获取当前值 - public T GetValue(); - - // 设置值 - public void SetValue(T newValue); -} -``` - -### ILocalizationManager - -```csharp -public interface ILocalizationManager : ISystem -{ - // 获取当前语言代码 - string CurrentLanguage { get; } - - // 获取当前文化信息 - CultureInfo CurrentCulture { get; } - - // 获取可用语言列表 - IReadOnlyList AvailableLanguages { get; } - - // 设置当前语言 - void SetLanguage(string languageCode); - - // 获取本地化表 - ILocalizationTable GetTable(string tableName); - - // 获取本地化文本 - string GetText(string table, string key); - - // 获取本地化字符串（支持变量） - ILocalizationString GetString(string table, string key); - - // 尝试获取本地化文本 - bool TryGetText(string table, string key, out string text); - - // 注册格式化器 - void RegisterFormatter(string name, ILocalizationFormatter formatter); - - // 订阅语言变化事件 - void SubscribeToLanguageChange(Action callback); - - // 取消订阅语言变化事件 - void UnsubscribeFromLanguageChange(Action callback); -} -``` - -### ILocalizationString - -```csharp -public interface ILocalizationString -{ - // 获取表名 - string Table { get; } - - // 获取键名 - string Key { get; } - - // 添加变量 - ILocalizationString WithVariable(string name, object value); - - // 批量添加变量 - ILocalizationString WithVariables(params (string name, object value)[] variables); - - // 格式化并返回文本 - string Format(); - - // 获取原始文本 - string GetRaw(); - - // 检查键是否存在 - bool Exists(); -} -``` - -### LocalizationConfig - -```csharp -public class LocalizationConfig -{ - // 默认语言代码 - public string DefaultLanguage { get; set; } = "eng"; - - // 回退语言代码 - public string FallbackLanguage { get; set; } = "eng"; - - // 本地化文件路径 - public string LocalizationPath { get; set; } = "res://localization"; - - // 用户覆盖路径 - public string OverridePath { get; set; } = "user://localization_override"; - - // 是否启用热重载 - public bool EnableHotReload { get; set; } = true; - - // 是否在加载时验证 - public bool ValidateOnLoad { get; set; } = true; -} -``` - -## 扩展方法 - -### 架构扩展 - -```csharp -// 发送命令 -public static void SendCommand(this IBelongToArchitecture self, T command) - where T : ICommand; - -// 发送查询 -public static TResult SendQuery( - this IBelongToArchitecture self, TQuery query) - where TQuery : IQuery; - -// 发送事件 -public static void SendEvent(this IBelongToArchitecture self, T e) - where T : IEvent; - -// 获取模型 -public static T GetModel(this IBelongToArchitecture self) - where T : IModel; - -// 获取系统 -public static T GetSystem(this IBelongToArchitecture self) - where T : ISystem; - -// 获取工具 -public static T GetUtility(this IBelongToArchitecture self) - where T : IUtility; - -// 注册事件 -public static IUnRegister RegisterEvent( - this IBelongToArchitecture self, Action onEvent) - where T : IEvent; -``` - -### 属性扩展 - -```csharp -// 添加到注销列表 -public static IUnRegister AddToUnregisterList( - this IUnRegister self, IUnRegisterList list); - -// 注销所有 -public static void UnRegisterAll(this IUnRegisterList self); -``` - -## 游戏模块 API - -### GFramework.Game - -游戏业务扩展模块。 - -#### 主要类型 - -| 类型 | 说明 | -|---------------|--------| -| `GameSetting` | 游戏设置 | -| `GameState` | 游戏状态 | -| `IGameModule` | 游戏模块接口 | - -## Godot 集成 API - -### GFramework.Godot - -Godot 引擎集成模块。 - -#### 主要类型 - -| 类型 | 说明 | -|------------------|------------| -| `GodotNode` | Godot 节点扩展 | -| `GodotCoroutine` | Godot 协程 | -| `GodotSignal` | Godot 信号 | - -## 源码生成器 - -### Source Generators 家族 - -自动代码生成工具按模块拆分为 `GFramework.Core.SourceGenerators`、`GFramework.Game.SourceGenerators`、 -`GFramework.Godot.SourceGenerators` 与 `GFramework.Cqrs.SourceGenerators`。面向业务代码声明的 Attribute -主要来自 `GFramework.Core.SourceGenerators.Abstractions.*` 与对应模块的 runtime/generator 包。 - -#### 支持的生成器 - -| 生成器 | 说明 | -|--------------------------------------------|-------------| -| `LoggingGenerator` | 日志生成器 | -| `EnumGenerator` | 枚举扩展生成器 | -| `RuleGenerator` | 规则生成器 | -| `AutoRegisterModuleGenerator` | 架构模块注册生成器 | -| `AutoUiPageGenerator` | UI 页面行为生成器 | -| `AutoSceneGenerator` | 场景行为生成器 | -| `AutoRegisterExportedCollectionsGenerator` | 导出集合批量注册生成器 | - -#### 常用 Attribute - -| Attribute | 说明 | 文档 | -|--------------------------------------------|-------------------------------------------|-------------------------------------------------------------------------------------------------------------| -| `AutoRegisterModuleAttribute` | 为模块类生成 `Install(IArchitecture)` | [AutoRegisterModule 生成器](../source-generators/auto-register-module-generator.md) | -| `RegisterModelAttribute` | 声明模块内自动注册的 `IModel` 类型 | [AutoRegisterModule 生成器](../source-generators/auto-register-module-generator.md) | -| `RegisterSystemAttribute` | 声明模块内自动注册的 `ISystem` 类型 | [AutoRegisterModule 生成器](../source-generators/auto-register-module-generator.md) | -| `RegisterUtilityAttribute` | 声明模块内自动注册的 `IUtility` 类型 | [AutoRegisterModule 生成器](../source-generators/auto-register-module-generator.md) | -| `AutoUiPageAttribute` | 为 `CanvasItem` 页面节点生成 `GetPage()` | [AutoUiPage 生成器](../source-generators/auto-ui-page-generator.md) | -| `AutoSceneAttribute` | 为场景根节点生成 `GetScene()` | [AutoScene 生成器](../source-generators/auto-scene-generator.md) | -| `AutoLoadAttribute` | 显式声明 `project.godot` AutoLoad 与 C# 节点类型映射 | [Godot 项目元数据生成器](../source-generators/godot-project-generator.md) | -| `AutoRegisterExportedCollectionsAttribute` | 为宿主类开启导出集合批量注册生成 | [AutoRegisterExportedCollections 生成器](../source-generators/auto-register-exported-collections-generator.md) | -| `RegisterExportedCollectionAttribute` | 指定集合与注册器成员的映射关系 | [AutoRegisterExportedCollections 生成器](../source-generators/auto-register-exported-collections-generator.md) | - -## 常见用法示例 - -### 创建架构 - -```csharp -public class MyArchitecture : Architecture -{ - protected override void Init() - { - RegisterModel(new PlayerModel()); - RegisterSystem(new PlayerSystem()); - RegisterUtility(new StorageUtility()); - } -} - -// 使用 -var arch = new MyArchitecture(); -arch.Initialize(); -``` - -### 发送命令 - -```csharp -public class AttackCommand : AbstractCommand -{ - public int Damage { get; set; } - - protected override void OnDo() - { - var player = this.GetModel(); - this.SendEvent(new AttackEvent { Damage = Damage }); - } -} - -// 使用 -arch.SendCommand(new AttackCommand { Damage = 10 }); -``` - -### 发送查询 - -```csharp -public class GetPlayerHealthQuery : AbstractQuery -{ - protected override int OnDo() - { - return this.GetModel().Health.Value; - } -} - -// 使用 -var health = arch.SendQuery(new GetPlayerHealthQuery()); -``` - -### 监听事件 - -```csharp -public class PlayerSystem : AbstractSystem -{ - protected override void OnInit() - { - this.RegisterEvent(OnPlayerDied); - } - - private void OnPlayerDied(PlayerDiedEvent e) - { - Console.WriteLine("Player died!"); - } -} -``` - -### 使用本地化 - -```csharp -// 初始化本地化管理器 -var config = new LocalizationConfig -{ - DefaultLanguage = "eng", - LocalizationPath = "res://localization" -}; -var locManager = new LocalizationManager(config); -locManager.Initialize(); - -// 获取简单文本 -string title = locManager.GetText("common", "game.title"); - -// 使用变量 -var message = locManager.GetString("common", "ui.message.welcome") - .WithVariable("playerName", "Alice") - .Format(); - -// 切换语言 -locManager.SetLanguage("zhs"); - -// 监听语言变化 -locManager.SubscribeToLanguageChange(language => -{ - Console.WriteLine($"Language changed to: {language}"); -}); -``` - +--- +title: API 参考 +description: GFramework 的 API 阅读入口，按模块映射 README、专题页、XML 文档和教程链路。 --- -更多详情请查看各模块的详细文档。 +# API 参考 + +这里不再维护一份脱离源码演化的“伪 API 列表”。 + +当前 `GFramework` 的 API 参考链路以四类证据协同为准： + +1. 模块 README：说明包关系、最小接入路径和目录边界 +2. `docs/zh-CN` 专题页：说明采用顺序、生命周期和使用建议 +3. 代码中的 XML 文档：说明公开 / 内部类型和关键成员的契约 +4. 教程页：说明这些 API 在真实接入路径中的组合方式 + +## 阅读顺序 + +### 想确认“该装哪个包、先看哪类 API” + +先读模块 README，再读对应 landing page： + +- 入门入口：[`../getting-started/index.md`](../getting-started/index.md) +- 根模块地图：仓库根 `README.md` + +### 想确认“这个功能属于哪个模块” + +按下面的模块映射进入对应入口： + +| 模块族 | 模块 README | 站内入口 | XML 文档关注点 | +| --- | --- | --- | --- | +| `Core` / `Core.Abstractions` | `GFramework.Core/README.md`、`GFramework.Core.Abstractions/README.md` | [`../core/index.md`](../core/index.md)、[`../abstractions/core-abstractions.md`](../abstractions/core-abstractions.md) | 架构入口、生命周期、命令 / 查询 / 事件 / 状态 / 资源 / 日志契约 | +| `Cqrs` / `Cqrs.Abstractions` / `Cqrs.SourceGenerators` | `GFramework.Cqrs/README.md`、`GFramework.Cqrs.Abstractions/README.md`、`GFramework.Cqrs.SourceGenerators/README.md` | [`../core/cqrs.md`](../core/cqrs.md)、[`../source-generators/index.md`](../source-generators/index.md) | request / notification / handler / pipeline / registry contract | +| `Game` / `Game.Abstractions` / `Game.SourceGenerators` | `GFramework.Game/README.md`、`GFramework.Game.Abstractions/README.md`、`GFramework.Game.SourceGenerators/README.md` | [`../game/index.md`](../game/index.md)、[`../abstractions/game-abstractions.md`](../abstractions/game-abstractions.md) | 配置、数据、设置、场景、UI、存储、序列化契约 | +| `Godot` / `Godot.SourceGenerators` | `GFramework.Godot/README.md`、`GFramework.Godot.SourceGenerators/README.md` | [`../godot/index.md`](../godot/index.md)、[`../source-generators/index.md`](../source-generators/index.md) | 节点扩展、场景 / UI 适配、资源 / 存储 / 日志接入 | +| `Ecs.Arch` / `Ecs.Arch.Abstractions` | `GFramework.Ecs.Arch/README.md`、`GFramework.Ecs.Arch.Abstractions/README.md` | [`../ecs/index.md`](../ecs/index.md)、[`../ecs/arch.md`](../ecs/arch.md)、[`../abstractions/ecs-arch-abstractions.md`](../abstractions/ecs-arch-abstractions.md) | ECS 模块契约、系统适配、配置对象和运行时装配边界 | + +## 先看 XML，还是先看教程 + +### 先看 XML 文档的情况 + +- 你在确认公开类型的约束、线程 / 生命周期语义、参数和返回值契约 +- 你需要区分“抽象层保证了什么”和“默认实现额外提供了什么” +- 你在做多模块拆分、测试替身或扩展适配层 + +优先关注这些类型族： + +- 架构 / 模块 / 服务入口 +- 生命周期、注册、路由、工厂、provider 契约 +- Source Generator 的 attribute、diagnostic 和 generated contract + +### 先看教程和专题页的情况 + +- 你要的是最小接入路径，而不是逐个类型审计 +- 你想确认模块组合方式、目录约定和推荐接线顺序 +- 你在做从旧入口迁移到新入口的采用决策 + +优先入口： + +- 教程概览：[`../tutorials/index.md`](../tutorials/index.md) +- 最佳实践：[`../best-practices/index.md`](../best-practices/index.md) +- 故障排查：[`../troubleshooting.md`](../troubleshooting.md) + +## 当前边界 + +- `GFramework.Core.SourceGenerators.Abstractions` +- `GFramework.Godot.SourceGenerators.Abstractions` +- `GFramework.SourceGenerators.Common` + +这些目录当前不是独立消费模块，因此不单独维护站内 API 参考入口。它们的公开说明跟随所属模块 README 和 +`source-generators` 栏目维护。 + +## 使用方式 + +把本页当成“API 阅读导航”而不是“签名快照”： + +- 先选模块 +- 再进 README 和专题页确认采用路径 +- 最后回到代码里的 XML 文档核对具体契约 + +当 README、专题页和 XML 文档出现冲突时，以源码和测试所反映的当前实现为准。