mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-05-06 16:16:44 +08:00
docs(governance): 建立长期文档治理入口
- 新增 documentation-full-coverage-governance active topic 与首轮 inventory、trace 入口 - 补充 GFramework.Ecs.Arch.Abstractions README、抽象接口页面与导航映射 - 更新 API 参考页与根 README，明确内部支撑模块 owner 和阅读链路
This commit is contained in:
GeWuYou
parent
45a87c6988
commit
cc49b8638f
93
GFramework.Ecs.Arch.Abstractions/README.md
Normal file
93
GFramework.Ecs.Arch.Abstractions/README.md
Normal file
@ -0,0 +1,93 @@
|
|||||||
|
# GFramework.Ecs.Arch.Abstractions
|
||||||
|
|
||||||
|
`GFramework.Ecs.Arch.Abstractions` 承载 Arch ECS 集成层的最小契约，用来让共享业务层、宿主循环或扩展模块在不依赖
|
||||||
|
`GFramework.Ecs.Arch` 默认实现的前提下，仍然可以约定 ECS 模块边界。
|
||||||
|
|
||||||
|
如果你需要的是 `UseArch(...)` 扩展、`ArchSystemAdapter<T>` 基类、`World` 注册和默认模块实现，请改为依赖
|
||||||
|
`GFramework.Ecs.Arch`。
|
||||||
|
|
||||||
|
## 包定位
|
||||||
|
|
||||||
|
- 这是 `Ecs.Arch` 的契约层，不是默认实现层。
|
||||||
|
- 适合让上层模块只面向 `IArchEcsModule`、`IArchSystemAdapter<T>` 和 `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<T>` 等默认基类
|
||||||
|
- 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)
|
||||||
14
README.md
14
README.md
@ -27,11 +27,22 @@
|
|||||||
| `GFramework.Game.Abstractions` | `Game` 对应的契约层 | [README](GFramework.Game.Abstractions/README.md) |
|
| `GFramework.Game.Abstractions` | `Game` 对应的契约层 | [README](GFramework.Game.Abstractions/README.md) |
|
||||||
| `GFramework.Godot` | Godot 集成层，负责把框架能力接入节点、场景、UI、设置与存储 | [README](GFramework.Godot/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` | 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.Core.SourceGenerators` | Core 侧通用源码生成器与分析器 | [README](GFramework.Core.SourceGenerators/README.md) |
|
||||||
| `GFramework.Game.SourceGenerators` | 游戏内容配置 schema 生成器 | [README](GFramework.Game.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.Cqrs.SourceGenerators` | CQRS handler registry 生成器 | [README](GFramework.Cqrs.SourceGenerators/README.md) |
|
||||||
| `GFramework.Godot.SourceGenerators` | Godot 场景专用源码生成器 | [README](GFramework.Godot.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 与文档站点保持同一套栏目命名：
|
仓库根 README 与文档站点保持同一套栏目命名：
|
||||||
@ -119,10 +130,13 @@ GFramework.sln
|
|||||||
├─ GFramework.Game.Abstractions/
|
├─ GFramework.Game.Abstractions/
|
||||||
├─ GFramework.Godot/
|
├─ GFramework.Godot/
|
||||||
├─ GFramework.Ecs.Arch/
|
├─ GFramework.Ecs.Arch/
|
||||||
|
├─ GFramework.Ecs.Arch.Abstractions/
|
||||||
├─ GFramework.Core.SourceGenerators/
|
├─ GFramework.Core.SourceGenerators/
|
||||||
|
├─ GFramework.Core.SourceGenerators.Abstractions/
|
||||||
├─ GFramework.Game.SourceGenerators/
|
├─ GFramework.Game.SourceGenerators/
|
||||||
├─ GFramework.Cqrs.SourceGenerators/
|
├─ GFramework.Cqrs.SourceGenerators/
|
||||||
├─ GFramework.Godot.SourceGenerators/
|
├─ GFramework.Godot.SourceGenerators/
|
||||||
|
├─ GFramework.Godot.SourceGenerators.Abstractions/
|
||||||
├─ GFramework.SourceGenerators.Common/
|
├─ GFramework.SourceGenerators.Common/
|
||||||
└─ docs/
|
└─ docs/
|
||||||
```
|
```
|
||||||
|
|||||||
@ -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`.
|
- 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`
|
- 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`
|
- 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`
|
- `coroutine-optimization`
|
||||||
- Purpose: continue the coroutine semantics, host integration, observability, regression coverage, and migration-doc
|
- Purpose: continue the coroutine semantics, host integration, observability, regression coverage, and migration-doc
|
||||||
follow-up work.
|
follow-up work.
|
||||||
@ -58,6 +63,9 @@ help the current worktree land on the right recovery documents without scanning
|
|||||||
- Branch: `feat/data-repository-persistence`
|
- Branch: `feat/data-repository-persistence`
|
||||||
- Worktree hint: `GFramework-data-repository-persistence`
|
- Worktree hint: `GFramework-data-repository-persistence`
|
||||||
- Priority 1: `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
|
## Archived Topics
|
||||||
|
|
||||||
- `cqrs-cache-docs-hardening`
|
- `cqrs-cache-docs-hardening`
|
||||||
|
|||||||
@ -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`
|
||||||
@ -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` 纳入完整模块闭环
|
||||||
@ -264,7 +264,8 @@ export default defineConfig({
|
|||||||
text: '抽象接口',
|
text: '抽象接口',
|
||||||
items: [
|
items: [
|
||||||
{ text: 'Core Abstractions', link: '/zh-CN/abstractions/core-abstractions' },
|
{ 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' }
|
||||||
]
|
]
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
|
|||||||
95
docs/zh-CN/abstractions/ecs-arch-abstractions.md
Normal file
95
docs/zh-CN/abstractions/ecs-arch-abstractions.md
Normal file
@ -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<T>` | 让 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<T>` 基类
|
||||||
|
- 访问 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 与专题页维护。
|
||||||
@ -1,3 +1,8 @@
|
|||||||
|
---
|
||||||
|
title: 抽象接口
|
||||||
|
description: GFramework 各抽象层模块的阅读入口与使用边界。
|
||||||
|
---
|
||||||
|
|
||||||
# 抽象接口
|
# 抽象接口
|
||||||
|
|
||||||
`GFramework.*.Abstractions` 用来承载跨模块协作所需的契约，而不是运行时实现。
|
`GFramework.*.Abstractions` 用来承载跨模块协作所需的契约，而不是运行时实现。
|
||||||
@ -12,9 +17,19 @@
|
|||||||
|
|
||||||
- Core 抽象层：[`core-abstractions.md`](./core-abstractions.md)
|
- Core 抽象层：[`core-abstractions.md`](./core-abstractions.md)
|
||||||
- Game 抽象层：[`game-abstractions.md`](./game-abstractions.md)
|
- Game 抽象层：[`game-abstractions.md`](./game-abstractions.md)
|
||||||
|
- Ecs.Arch 抽象层：[`ecs-arch-abstractions.md`](./ecs-arch-abstractions.md)
|
||||||
|
|
||||||
## 使用建议
|
## 使用建议
|
||||||
|
|
||||||
- 如果你只是想直接使用框架功能，优先从对应运行时模块的 `README.md` 和栏目页开始。
|
- 如果你只是想直接使用框架功能，优先从对应运行时模块的 `README.md` 和栏目页开始。
|
||||||
- 只有在明确需要“契约层而非实现层”时，才单独依赖 `*.Abstractions` 包。
|
- 只有在明确需要“契约层而非实现层”时，才单独依赖 `*.Abstractions` 包。
|
||||||
- 抽象层页面会解释接口分组与职责；实际安装与接入路径，仍应以运行时模块 README 与 `getting-started` 为主。
|
- 抽象层页面会解释接口分组与职责；实际安装与接入路径，仍应以运行时模块 README 与 `getting-started` 为主。
|
||||||
|
|
||||||
|
## 当前边界
|
||||||
|
|
||||||
|
- `GFramework.Core.SourceGenerators.Abstractions`
|
||||||
|
- `GFramework.Godot.SourceGenerators.Abstractions`
|
||||||
|
- `GFramework.SourceGenerators.Common`
|
||||||
|
|
||||||
|
这些目录当前不作为独立抽象接口栏目维护，而是作为源码生成器家族的内部支撑模块，分别跟随所属模块 README 和
|
||||||
|
`source-generators` 栏目维护。
|
||||||
|
|||||||
@ -1,571 +1,81 @@
|
|||||||
# API 参考文档
|
---
|
||||||
|
title: API 参考
|
||||||
本文档提供 GFramework 各模块的完整 API 参考。
|
description: GFramework 的 API 阅读入口，按模块映射 README、专题页、XML 文档和教程链路。
|
||||||
|
|
||||||
## 核心命名空间
|
|
||||||
|
|
||||||
### GFramework.Core.architecture
|
|
||||||
|
|
||||||
核心架构命名空间，包含所有基础组件。
|
|
||||||
|
|
||||||
#### 主要类型
|
|
||||||
|
|
||||||
| 类型 | 说明 |
|
|
||||||
|--------------------|--------|
|
|
||||||
| `Architecture` | 应用架构基类 |
|
|
||||||
| `AbstractModel` | 数据模型基类 |
|
|
||||||
| `AbstractSystem` | 业务系统基类 |
|
|
||||||
| `AbstractCommand` | 命令基类 |
|
|
||||||
| `AbstractQuery<T>` | 查询基类 |
|
|
||||||
| `IController` | 控制器接口 |
|
|
||||||
| `IUtility` | 工具类接口 |
|
|
||||||
|
|
||||||
### GFramework.Core.events
|
|
||||||
|
|
||||||
事件系统命名空间。
|
|
||||||
|
|
||||||
#### 主要类型
|
|
||||||
|
|
||||||
| 类型 | 说明 |
|
|
||||||
|-------------------|----------|
|
|
||||||
| `IEvent` | 事件接口 |
|
|
||||||
| `IEventSystem` | 事件系统接口 |
|
|
||||||
| `TypeEventSystem` | 类型安全事件系统 |
|
|
||||||
|
|
||||||
### GFramework.Core.property
|
|
||||||
|
|
||||||
属性系统命名空间。
|
|
||||||
|
|
||||||
#### 主要类型
|
|
||||||
|
|
||||||
| 类型 | 说明 |
|
|
||||||
|-----------------------|--------|
|
|
||||||
| `BindableProperty<T>` | 可绑定属性 |
|
|
||||||
| `IUnRegister` | 注销接口 |
|
|
||||||
| `IUnRegisterList` | 注销列表接口 |
|
|
||||||
|
|
||||||
### GFramework.Core.ioc
|
|
||||||
|
|
||||||
IoC 容器命名空间。
|
|
||||||
|
|
||||||
#### 主要类型
|
|
||||||
|
|
||||||
| 类型 | 说明 |
|
|
||||||
|--------------|------|
|
|
||||||
| `IContainer` | 容器接口 |
|
|
||||||
| `Container` | 容器实现 |
|
|
||||||
|
|
||||||
### GFramework.Core.pool
|
|
||||||
|
|
||||||
对象池命名空间。
|
|
||||||
|
|
||||||
#### 主要类型
|
|
||||||
|
|
||||||
| 类型 | 说明 |
|
|
||||||
|------------------|-------|
|
|
||||||
| `IObjectPool<T>` | 对象池接口 |
|
|
||||||
| `ObjectPool<T>` | 对象池实现 |
|
|
||||||
|
|
||||||
### 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>(T model) where T : IModel;
|
|
||||||
|
|
||||||
// 获取模型
|
|
||||||
public T GetModel<T>() where T : IModel;
|
|
||||||
|
|
||||||
// 注册系统
|
|
||||||
public void RegisterSystem<T>(T system) where T : ISystem;
|
|
||||||
|
|
||||||
// 获取系统
|
|
||||||
public T GetSystem<T>() where T : ISystem;
|
|
||||||
|
|
||||||
// 注册工具
|
|
||||||
public void RegisterUtility<T>(T utility) where T : IUtility;
|
|
||||||
|
|
||||||
// 获取工具
|
|
||||||
public T GetUt>() where T : IUtility;
|
|
||||||
|
|
||||||
// 发送命令
|
|
||||||
public void SendCommand<T>(T command) where T : ICommand;
|
|
||||||
|
|
||||||
// 发送查询
|
|
||||||
public TResult SendQuery<TQuery, TResult>(TQuery query)
|
|
||||||
where TQuery : IQuery<TResult>;
|
|
||||||
|
|
||||||
// 发送事件
|
|
||||||
public void SendEvent<T>(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>(T e) where T : IEvent;
|
|
||||||
|
|
||||||
// 获取模型
|
|
||||||
protected T GetModel<T>() where T : IModel;
|
|
||||||
|
|
||||||
// 获取系统
|
|
||||||
protected T GetSystem<T>() where T : ISystem;
|
|
||||||
|
|
||||||
// 获取工具
|
|
||||||
protected T GetUtility<T>() 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>(T e) where T : IEvent;
|
|
||||||
|
|
||||||
// 注册事件
|
|
||||||
protected IUnRegister RegisterEvent<T>(Action<T> onEvent)
|
|
||||||
where T : IEvent;
|
|
||||||
|
|
||||||
// 获取模型
|
|
||||||
protected T GetModel<T>() where T : IModel;
|
|
||||||
|
|
||||||
// 获取系统
|
|
||||||
protected T GetSystem<T>() where T : ISystem;
|
|
||||||
|
|
||||||
// 获取工具
|
|
||||||
protected T GetUtility<T>() where T : IUtility;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### AbstractCommand
|
|
||||||
|
|
||||||
```csharp
|
|
||||||
public abstract class AbstractCommand : IBelongToArchitecture
|
|
||||||
{
|
|
||||||
// 执行命令
|
|
||||||
public void Execute();
|
|
||||||
|
|
||||||
// 命令实现
|
|
||||||
protected abstract void OnDo();
|
|
||||||
|
|
||||||
// 获取架构
|
|
||||||
public IArchitecture GetArchitecture();
|
|
||||||
|
|
||||||
// 发送事件
|
|
||||||
protected void SendEvent<T>(T e) where T : IEvent;
|
|
||||||
|
|
||||||
// 获取模型
|
|
||||||
protected T GetModel<T>() where T : IModel;
|
|
||||||
|
|
||||||
// 获取系统
|
|
||||||
protected T GetSystem<T>() where T : ISystem;
|
|
||||||
|
|
||||||
// 获取工具
|
|
||||||
protected T GetUtility<T>() where T : IUtility;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### AbstractQuery`<T>`
|
|
||||||
|
|
||||||
```csharp
|
|
||||||
public abstract class AbstractQuery<T> : IBelongToArchitecture
|
|
||||||
{
|
|
||||||
// 执行查询
|
|
||||||
public T Do();
|
|
||||||
|
|
||||||
// 查询实现
|
|
||||||
protected abstract T OnDo();
|
|
||||||
|
|
||||||
// 获取架构
|
|
||||||
public IArchitecture GetArchitecture();
|
|
||||||
|
|
||||||
// 获取模型
|
|
||||||
protected T GetModel<T>() where T : IModel;
|
|
||||||
|
|
||||||
// 获取系统
|
|
||||||
protected T GetSystem<T>() where T : ISystem;
|
|
||||||
|
|
||||||
// 获取工具
|
|
||||||
protected T GetUtility<T>() where T : IUtility;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### BindableProperty`<T>`
|
|
||||||
|
|
||||||
```csharp
|
|
||||||
public class BindableProperty<T>
|
|
||||||
{
|
|
||||||
// 构造函数
|
|
||||||
public BindableProperty(T initialValue = default);
|
|
||||||
|
|
||||||
// 获取或设置值
|
|
||||||
public T Value { get; set; }
|
|
||||||
|
|
||||||
// 注册监听器
|
|
||||||
public IUnRegister Register(Action<T> onValueChanged);
|
|
||||||
|
|
||||||
// 注册监听器（包含初始值）
|
|
||||||
public IUnRegister RegisterWithInitValue(Action<T> onValueChanged);
|
|
||||||
|
|
||||||
// 获取当前值
|
|
||||||
public T GetValue();
|
|
||||||
|
|
||||||
// 设置值
|
|
||||||
public void SetValue(T newValue);
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### ILocalizationManager
|
|
||||||
|
|
||||||
```csharp
|
|
||||||
public interface ILocalizationManager : ISystem
|
|
||||||
{
|
|
||||||
// 获取当前语言代码
|
|
||||||
string CurrentLanguage { get; }
|
|
||||||
|
|
||||||
// 获取当前文化信息
|
|
||||||
CultureInfo CurrentCulture { get; }
|
|
||||||
|
|
||||||
// 获取可用语言列表
|
|
||||||
IReadOnlyList<string> 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<string> callback);
|
|
||||||
|
|
||||||
// 取消订阅语言变化事件
|
|
||||||
void UnsubscribeFromLanguageChange(Action<string> 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<T>(this IBelongToArchitecture self, T command)
|
|
||||||
where T : ICommand;
|
|
||||||
|
|
||||||
// 发送查询
|
|
||||||
public static TResult SendQuery<TQuery, TResult>(
|
|
||||||
this IBelongToArchitecture self, TQuery query)
|
|
||||||
where TQuery : IQuery<TResult>;
|
|
||||||
|
|
||||||
// 发送事件
|
|
||||||
public static void SendEvent<T>(this IBelongToArchitecture self, T e)
|
|
||||||
where T : IEvent;
|
|
||||||
|
|
||||||
// 获取模型
|
|
||||||
public static T GetModel<T>(this IBelongToArchitecture self)
|
|
||||||
where T : IModel;
|
|
||||||
|
|
||||||
// 获取系统
|
|
||||||
public static T GetSystem<T>(this IBelongToArchitecture self)
|
|
||||||
where T : ISystem;
|
|
||||||
|
|
||||||
// 获取工具
|
|
||||||
public static T GetUtility<T>(this IBelongToArchitecture self)
|
|
||||||
where T : IUtility;
|
|
||||||
|
|
||||||
// 注册事件
|
|
||||||
public static IUnRegister RegisterEvent<T>(
|
|
||||||
this IBelongToArchitecture self, Action<T> 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<PlayerModel>();
|
|
||||||
this.SendEvent(new AttackEvent { Damage = Damage });
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
// 使用
|
|
||||||
arch.SendCommand(new AttackCommand { Damage = 10 });
|
|
||||||
```
|
|
||||||
|
|
||||||
### 发送查询
|
|
||||||
|
|
||||||
```csharp
|
|
||||||
public class GetPlayerHealthQuery : AbstractQuery<int>
|
|
||||||
{
|
|
||||||
protected override int OnDo()
|
|
||||||
{
|
|
||||||
return this.GetModel<PlayerModel>().Health.Value;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
// 使用
|
|
||||||
var health = arch.SendQuery(new GetPlayerHealthQuery());
|
|
||||||
```
|
|
||||||
|
|
||||||
### 监听事件
|
|
||||||
|
|
||||||
```csharp
|
|
||||||
public class PlayerSystem : AbstractSystem
|
|
||||||
{
|
|
||||||
protected override void OnInit()
|
|
||||||
{
|
|
||||||
this.RegisterEvent<PlayerDiedEvent>(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}");
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
更多详情请查看各模块的详细文档。
|
# 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 文档出现冲突时，以源码和测试所反映的当前实现为准。
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user