mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-05-06 16:16:44 +08:00
docs(reader-facing): 统一站内入口与公开术语
- 更新入口页的 reader-facing 骨架，统一起步路线、阅读顺序与站内导航 - 收口公开 README 与 Godot 页面中的内部口吻、文件名式表述和术语噪音 - 移除 docs/zh-CN 中残留的 GitHub README 外链，并同步刷新文档治理恢复状态
This commit is contained in:
gewuyou
parent
5befaf707b
commit
979db3b5a5
@ -1,6 +1,6 @@
|
||||
# GFramework.Cqrs.Abstractions
|
||||
|
||||
`GFramework.Cqrs.Abstractions` 提供 GFramework CQRS 的最小契约层。它只包含消息接口、处理器接口、运行时 seam 和管道契约，不包含默认 dispatcher、处理器扫描或任何 `GFramework.Core` 运行时实现。适合以下场景：
|
||||
`GFramework.Cqrs.Abstractions` 提供 GFramework CQRS 的最小契约层。它只包含消息接口、处理器接口、运行时协作接口和管道契约，不包含默认 dispatcher、处理器扫描或任何 `GFramework.Core` 运行时实现。适合以下场景：
|
||||
|
||||
- 你的业务程序集只需要声明 Command、Query、Notification、Stream Request 或处理器接口。
|
||||
- 你希望把消息契约放在更稳定的基础层，避免直接依赖默认 runtime 实现。
|
||||
@ -43,7 +43,7 @@
|
||||
- `Cqrs/IRequestHandler.cs`
|
||||
- `Cqrs/INotificationHandler.cs`
|
||||
- `Cqrs/IStreamRequestHandler.cs`
|
||||
- 运行时 seam
|
||||
- 运行时协作接口
|
||||
- `Cqrs/ICqrsRuntime.cs`
|
||||
- `Cqrs/ICqrsContext.cs`
|
||||
- `Cqrs/ICqrsHandlerRegistrar.cs`
|
||||
@ -93,7 +93,7 @@ public sealed class GetPlayerProfileHandler
|
||||
|
||||
- 只引用本包时，没有 `CommandBase<TInput, TResponse>`、`QueryBase<TInput, TResponse>`、`NotificationBase<TInput>` 等消息基类。
|
||||
- 只引用本包时，没有 `AbstractCommandHandler`、`AbstractQueryHandler`、`AbstractNotificationHandler` 等处理器基类。
|
||||
- `ICqrsContext` 当前是轻量 marker seam；默认 runtime 在需要向 `IContextAware` 处理器注入上下文时，仍要求传入的上下文同时实现 `IArchitectureContext`。
|
||||
- `ICqrsContext` 当前是轻量 marker 接口；默认 runtime 在需要向 `IContextAware` 处理器注入上下文时，仍要求传入的上下文同时实现 `IArchitectureContext`。
|
||||
|
||||
## 文档入口
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# GFramework.Ecs.Arch
|
||||
|
||||
`GFramework.Ecs.Arch` 是 `GFramework` 当前 Arch ECS family 的默认运行时实现包。
|
||||
`GFramework.Ecs.Arch` 是 `GFramework` 当前 Arch ECS 集成的默认运行时实现包。
|
||||
|
||||
它负责把 Arch `World`、GFramework 的服务模块生命周期，以及 `ArchSystemAdapter<T>` 系统桥接到同一条采用路径中。
|
||||
如果你需要的只是共享契约，请改为依赖 `GFramework.Ecs.Arch.Abstractions`。
|
||||
|
||||
@ -25,8 +25,7 @@
|
||||
- `FileStorage`、`ScopedStorage`、`JsonSerializer`、`SettingsModel<TRepository>`、`SaveRepository<TSaveData>`、`SceneRouterBase`、`UiRouterBase`、`YamlConfigLoader` 等都在实现这里的契约。
|
||||
- 引擎适配包或项目代码
|
||||
- `IUiFactory`、`ISceneFactory`、`IUiRoot`、`ISceneRoot`、资源注册表等通常由引擎适配层或游戏项目自己实现。
|
||||
- 仓库内 `ai-libs/` 下的只读参考实现通常也是这样组织：页面 / 场景 factory、root、registry 在项目层，
|
||||
运行时基类和契约来自 `GFramework.Game` 与本包。
|
||||
- 常见做法也是这样组织：页面 / 场景 factory、root、registry 在项目层，运行时基类和契约来自 `GFramework.Game` 与本包。
|
||||
|
||||
## 子系统地图
|
||||
|
||||
@ -209,9 +208,9 @@ public sealed class ContinueGameCommandHandler
|
||||
|
||||
也就是说，本包回答的是“项目各层如何约定”，`GFramework.Game` 回答的是“这些约定默认怎么跑起来”。
|
||||
|
||||
## `ai-libs/` 里的参考接入线索
|
||||
## 典型分层方式
|
||||
|
||||
`ai-libs/` 下的只读参考实现对本包的使用方式，能比较清楚地说明它的职责边界：
|
||||
典型项目对本包的使用方式，通常能清楚体现它的职责边界：
|
||||
|
||||
- 公共脚本广泛引用：
|
||||
- `IUiRouter`
|
||||
|
||||
@ -31,8 +31,7 @@
|
||||
- 引擎适配包或项目内适配层
|
||||
- 本包提供的是“引擎无关”的核心逻辑和基类。
|
||||
- 真正和 Godot、Unity、MonoGame 等引擎对象打交道的工厂、根节点、资源注册表，通常在相邻引擎包或游戏项目内实现。
|
||||
- 仓库内 `ai-libs/` 下的只读参考实现通常也是这样接入：配置文件 IO 由 `GFramework.Godot.Config` 适配，
|
||||
UI / Scene factory 与 root 由项目自己提供。
|
||||
- 典型项目里，配置文件 IO 会交给宿主适配层处理，UI / Scene 的 factory 与 root 则继续由项目自己提供。
|
||||
|
||||
## 子系统地图
|
||||
|
||||
@ -73,7 +72,7 @@
|
||||
- `SaveConfiguration`
|
||||
- 槽位目录、文件名、前缀等约定
|
||||
|
||||
`ai-libs/` 下已验证参考实现的常见接法：
|
||||
常见接法：
|
||||
|
||||
- 设置持久化使用 `UnifiedSettingsDataRepository`
|
||||
- 存档使用 `SaveRepository<GameSaveData>`
|
||||
@ -96,7 +95,7 @@
|
||||
- `Setting/Events/*`
|
||||
- 设置初始化、应用、保存、重置相关事件
|
||||
|
||||
`ai-libs/` 下已验证参考实现的常见接法：
|
||||
常见接法：
|
||||
|
||||
- 在模型模块中创建 `SettingsModel<ISettingsDataRepository>`
|
||||
- 注册多个 applicator
|
||||
@ -122,7 +121,7 @@
|
||||
对应文档：
|
||||
|
||||
- [存储系统](../docs/zh-CN/game/storage.md)
|
||||
- [Storage 子模块说明](./Storage/ReadMe.md)
|
||||
- [存储系统专题](../docs/zh-CN/game/storage.md)
|
||||
|
||||
### `Serializer/`
|
||||
|
||||
@ -149,7 +148,7 @@
|
||||
- `Scene/Handler/*`、`UI/Handler/*`
|
||||
- 默认转换处理器基类与日志处理器
|
||||
|
||||
`ai-libs/` 下已验证参考实现的常见接法：
|
||||
常见接法：
|
||||
|
||||
- 项目自定义 `SceneRouter : SceneRouterBase`
|
||||
- 项目自定义 `UiRouter : UiRouterBase`
|
||||
@ -266,7 +265,7 @@ await settingsSystem.ApplyAll();
|
||||
await settingsSystem.SaveAll();
|
||||
```
|
||||
|
||||
`ai-libs/` 下的只读参考实现目前也是按这个思路接入，只是底层存储换成了 Godot 适配实现。
|
||||
在 Godot 项目中也可以沿用同一思路，只是底层存储通常换成宿主侧适配实现。
|
||||
|
||||
### 3. 接入静态 YAML 配置
|
||||
|
||||
@ -324,9 +323,9 @@ public sealed class MyUiRouter : UiRouterBase
|
||||
|
||||
这类 router 适合作为你的项目层或引擎适配层代码，而不是直接修改本包。
|
||||
|
||||
## `ai-libs/` 里的参考接入线索
|
||||
## 典型项目分层方式
|
||||
|
||||
当前仓库内的只读参考实现，对本包的使用大致分成三层：
|
||||
典型项目对本包的使用大致分成三层：
|
||||
|
||||
- 配置
|
||||
- 项目级配置宿主类型使用生成表元数据与 YAML loader 完成配置注册
|
||||
|
||||
@ -119,23 +119,19 @@ Godot 上。
|
||||
|
||||
### 4. 按需接入配置、存储和设置
|
||||
|
||||
当项目已经使用 `Game` family 的配置、存储、设置契约时，再补 Godot 侧实现：
|
||||
当项目已经使用 `Game` 模块的配置、存储、设置契约时，再补 Godot 侧实现：
|
||||
|
||||
- 配置：`GodotYamlConfigLoader`
|
||||
- 存储：`GodotFileStorage`
|
||||
- 设置：`GodotAudioSettings`、`GodotGraphicsSettings`、`GodotLocalizationSettings`
|
||||
|
||||
不要把这些宿主实现误写成 `Game` family 的默认行为。
|
||||
不要把这些宿主实现误写成 `Game` 模块的默认行为。
|
||||
|
||||
## `ai-libs/` 里的参考接入线索
|
||||
|
||||
`ai-libs/CoreGrid` 仍是当前最直接的消费者证据来源：
|
||||
## 典型接入方式
|
||||
|
||||
- 架构侧保持普通模块注册，再按需挂接 Godot 宿主
|
||||
- `project.godot` 元数据与节点样板交给 `GFramework.Godot.SourceGenerators`
|
||||
- Scene / UI 继续沿用 `Game` family 的 router 语义
|
||||
|
||||
当 `ai-libs/` 与源码或测试冲突时，应以当前源码与测试为准。
|
||||
- Scene / UI 继续沿用 `Game` 模块的路由语义
|
||||
|
||||
## 文档入口
|
||||
|
||||
|
||||
@ -12,13 +12,13 @@
|
||||
|
||||
## 当前恢复点
|
||||
|
||||
- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-041`
|
||||
- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-042`
|
||||
- 当前阶段：`Phase 5 - Governance Maintenance`
|
||||
- 当前焦点：
|
||||
- 继续以最新 `origin/main`（`617e0bf`，`2026-04-26 12:17:15 +08:00`）作为 baseline，当前批处理 stop condition 仍是 branch diff vs baseline 接近 `50` changed files
|
||||
- 本轮低风险切片聚焦 3 组 reader-facing 收口：安装页选包矩阵补齐、公开 README 的 XML 阅读入口去治理化、`config-system` / 基础教程入口的维护者口吻改写
|
||||
- 当前 committed branch diff vs `origin/main` 已为 `9` files / `191` changed lines，仍明显低于 `50` 文件阈值；工作树只剩未纳入本批次的 `tools/gframework-config-tool/gframework-config-tool-0.0.3.vsix` untracked 打包产物
|
||||
- 当前已知 PR `#292` 远端 review 剩余上下文仍主要集中在 config tool adoption surface；本轮未继续抓取远端 review，而是优先收口本地可验证的 reader-facing 一致性问题
|
||||
- 本轮已扩成 3 个连续低风险切片：入口页 reader-facing 改写、公开 README / Godot 页面去内部口吻，以及剩余 GitHub blob README 外链改回站内导航
|
||||
- 当前工作树相对 `origin/main` 的 tracked diff 已到 `36` files / `500` changed lines；仍低于 `50` 文件阈值，但继续扩批前应先提交当前稳定批次，避免 review 面继续发散
|
||||
- 已接受 subagent 结论：当前最划算的修正不是扩新栏目，而是统一入口页骨架、清掉公开页面中的治理口吻、以及把站外 README 入口降回站内专题页
|
||||
|
||||
## 当前状态摘要
|
||||
|
||||
@ -34,6 +34,9 @@
|
||||
- `2026-04-27` `docs/zh-CN/getting-started/installation.md` 已补齐当前公开选包矩阵，新增 `Core.Abstractions`、`Game.Abstractions`、`Ecs.Arch`、`Ecs.Arch.Abstractions` 的 reader-facing 安装说明，并把 `Godot` 常见问题里的旧版 `>= 4.5` 提示收敛到当前 `4.6.2` 基线。
|
||||
- `2026-04-27` `GFramework.Core.Abstractions/README.md`、`GFramework.Game.Abstractions/README.md`、`GFramework.Game.SourceGenerators/README.md`、`GFramework.Ecs.Arch.Abstractions/README.md` 当前都已把 XML 阅读入口改写为“代表类型 + 阅读重点”，不再暴露覆盖计数、日期或 `已覆盖` 这类治理字段。
|
||||
- `2026-04-27` `docs/zh-CN/game/config-system.md` 与 `docs/zh-CN/tutorials/basic/index.md` 已把维护者 / 指挥式措辞改成中性的采用建议与阅读入口，避免公开页面继续暴露内部决策口吻。
|
||||
- `2026-04-27` `docs/zh-CN/getting-started/index.md`、`core/index.md`、`game/index.md`、`api-reference/index.md`、`source-generators/index.md` 已统一收敛为“适用场景 / 起步路线 / 继续阅读”式 reader-facing 入口，不再把 GitHub blob README 或治理说明当作主导航。
|
||||
- `2026-04-27` `GFramework.Game/README.md`、`GFramework.Game.Abstractions/README.md`、`GFramework.Godot/README.md`、`GFramework.Cqrs.Abstractions/README.md`、`GFramework.Ecs.Arch/README.md` 已收口 `ai-libs`、`family`、`seam`、`ReadMe.md` 等内部化或文件名式表述。
|
||||
- `2026-04-27` `docs/zh-CN` 当前已清空所有指向 `github.com/GeWuYou/GFramework/blob/main/.../README.md` 的公开外链，相关入口统一回到站内栏目页、专题页或 API 导航。
|
||||
- `2026-04-25` 当前批次已补齐 meta-package / 安装面：`GFramework.csproj` 不再保留占位描述，`README.md`、`docs/zh-CN/index.md`、`docs/zh-CN/getting-started/installation.md` 当前明确说明聚合元包只聚合 `Core` + `Game`，并把安装入口更新到当前 `net8.0/net9.0/net10.0` 与 Godot `4.6.2` 基线。
|
||||
- `2026-04-25` `docs/zh-CN/game/config-tool.md` 已新增为 reader-facing 工具页，`docs/zh-CN/game/index.md`、`config-system.md`、`docs/.vitepress/config.mts` 与 `tools/gframework-config-tool/README.md` 当前把 VS Code 配置工具纳入 `Game` 配置工作流入口。
|
||||
- `2026-04-25` source-generators 栏目已修正 4 处真实契约问题：`GetNode` 显式路径 / `Lookup` 语义、枚举生成器实际开关、`Context Get` 集合注入边界，以及 `GFramework.SourceGenerators.Common` / `*.SourceGenerators.Abstractions` 的共享支撑层说明。
|
||||
@ -84,6 +87,36 @@
|
||||
- 结果：通过；`config-system.md` 的工具形态建议改写后页面校验通过。
|
||||
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/basic`
|
||||
- 结果：通过；基础教程入口的阅读路径改写后栏目校验通过。
|
||||
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Game/README.md GFramework.Game.Abstractions/README.md GFramework.Godot/README.md GFramework.Cqrs.Abstractions/README.md GFramework.Ecs.Arch/README.md`
|
||||
- 结果：通过；本轮 5 个模块 README 的 reader-facing 术语与入口改写后链接目标有效。
|
||||
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/index.md`
|
||||
- 结果：通过；教程页受众表述改写后页面校验通过。
|
||||
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/ui.md`
|
||||
- 结果：通过；Godot UI 页的接法示例与 reader-facing 术语改写后页面校验通过。
|
||||
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/scene.md`
|
||||
- 结果：通过；Godot 场景页的接法示例与 reader-facing 术语改写后页面校验通过。
|
||||
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/signal.md`
|
||||
- 结果：通过；信号页切回站内生成器入口后页面校验通过。
|
||||
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions`
|
||||
- 结果：通过；3 个抽象层页改回站内入口后栏目校验通过。
|
||||
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators`
|
||||
- 结果：通过；生成器栏目及受影响专题页改回站内入口后栏目校验通过。
|
||||
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/index.md`
|
||||
- 结果：通过；Core 入口页 reader-facing 改写后页面校验通过。
|
||||
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/index.md`
|
||||
- 结果：通过；Game 入口页 reader-facing 改写后页面校验通过。
|
||||
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/api-reference/index.md`
|
||||
- 结果：通过；API 入口页导航改写后页面校验通过。
|
||||
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/getting-started/quick-start.md`
|
||||
- 结果：通过；快速开始页切回站内安装入口后页面校验通过。
|
||||
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/cqrs.md`
|
||||
- 结果：通过；CQRS 页继续阅读入口改写后页面校验通过。
|
||||
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/scene.md`
|
||||
- 结果：通过；Game 场景页相关推荐改回站内入口后页面校验通过。
|
||||
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/ui.md`
|
||||
- 结果：通过；Game UI 页相关推荐改回站内入口后页面校验通过。
|
||||
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/ecs/arch.md`
|
||||
- 结果：通过；ECS Arch 页入口改写后页面校验通过。
|
||||
- `2026-04-27` `bun run build`（工作目录：`docs/`）
|
||||
- 结果：通过；本轮 README、安装页与公开文案改写后站点仍可构建，仅保留既有大 chunk warning。
|
||||
- `2026-04-25` `bun run build`（工作目录：`docs/`）
|
||||
@ -172,8 +205,8 @@
|
||||
|
||||
## 下一步
|
||||
|
||||
1. 重新抓取 `$gframework-pr-review`，确认 PR `#292` 的 latest-head review 是否已自动关闭或仅剩过期线程。
|
||||
2. 若 branch diff vs `origin/main` 在提交后仍明显低于 `50` 文件阈值，继续优先扫描公开文档中的维护者口吻、治理式表格字段与过时安装说明，而不是扩新栏目。
|
||||
1. 提交当前 `36` files / `500` changed lines 的稳定批次后，重新计算 branch diff；若仍低于 `50` 且 reviewability 可接受，再继续选择一组不超过 `10` files 的 reader-facing 收口。
|
||||
2. 优先扫描还残留 `ai-libs`、`旧文档`、`README.md` / 路径式标签或内部术语的公开页面，而不是扩新栏目。
|
||||
3. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、
|
||||
`storage.md`、`serialization.md`、`setting.md` 与 landing page 是否仍保持同一套职责边界。
|
||||
4. 若后续分支继续调整 `Godot` generator 接法，优先复核 `GFramework.Godot.SourceGenerators/README.md`、
|
||||
|
||||
@ -2,6 +2,50 @@
|
||||
|
||||
## 2026-04-27
|
||||
|
||||
### 当前恢复点：RP-042
|
||||
|
||||
- 用户明确要求在当前阈值内循环推进，并允许使用 subagent 降低主线程上下文压力；因此本轮在主线程保留实现与验证，把热点识别委派给 3 个 explorer。
|
||||
- 接受的 subagent 结论主要有三类：
|
||||
- 入口页最划算的改法是统一 reader-facing 骨架，而不是继续保留治理说明或负向 framing。
|
||||
- 若站内已有栏目页与专题页，GitHub blob README 不应继续作为公开文档主导航。
|
||||
- `GFramework.Game` / `Game.Abstractions` / `Godot` 等 README 仍有 `ai-libs`、`family`、`seam`、`ReadMe.md` 等对外不友好的措辞，适合在同一轮里收口。
|
||||
- 基于这些结论，本轮连续落地 3 组低风险切片：入口页 reader-facing 改写、README / Godot 页去内部口吻、剩余 GitHub blob README 外链改回站内入口。
|
||||
|
||||
### 当前决策（RP-042）
|
||||
|
||||
- 继续保持 critical path 本地执行，不让 subagent 直接改文件；subagent 只负责热点排序与问题归类。
|
||||
- stop condition 继续沿用 `origin/main` + `50` changed files；当前工作树相对 baseline 的 tracked diff 已到 `36` files / `500` changed lines，意味着还能再做一小批，但应先提交当前稳定批次。
|
||||
- 当前批次不扩展到新栏目、新导航层或大段内容重写，只做 reader-facing 入口、术语和站内导航连通性收口。
|
||||
|
||||
### 当前验证（RP-042）
|
||||
|
||||
- README 链接校验：
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Game/README.md GFramework.Game.Abstractions/README.md GFramework.Godot/README.md GFramework.Cqrs.Abstractions/README.md GFramework.Ecs.Arch/README.md`
|
||||
- 结果：通过；本轮 5 个 README 的 reader-facing 改写后链接目标有效。
|
||||
- 教程 / Godot 页面校验：
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/index.md`
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/ui.md`
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/scene.md`
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/signal.md`
|
||||
- 结果：通过；受影响页面的 frontmatter、链接与代码块校验通过。
|
||||
- 入口与专题页校验：
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/index.md`
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/index.md`
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/api-reference/index.md`
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/getting-started/quick-start.md`
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/cqrs.md`
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/scene.md`
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/ui.md`
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/ecs/arch.md`
|
||||
- 结果：通过；入口页和相关推荐入口改写后页面校验通过。
|
||||
- 栏目级校验：
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions`
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators`
|
||||
- 结果：通过；抽象层与生成器栏目改回站内入口后栏目校验通过。
|
||||
- 站点构建：
|
||||
- `bun run build`（工作目录：`docs/`）
|
||||
- 结果：通过；本轮 3 组 reader-facing 文档批次后站点仍可构建，仅保留既有大 chunk warning。
|
||||
|
||||
### 当前恢复点：RP-041
|
||||
|
||||
- 通过 `$gframework-batch-boot 50` 重新进入后，先按仓库规则读取 `AGENTS.md`、`.ai/environment/tools.ai.yaml`、`ai-plan/public/README.md` 与 active topic tracking / trace，并继续使用显式 `--git-dir` / `--work-tree` 绑定确认当前分支仍为 `docs/sdk-update-documentation`。
|
||||
|
||||
@ -97,7 +97,7 @@ public sealed class DiagnosticsFeature
|
||||
|
||||
1. 先读本页，确认你是否真的只需要契约层
|
||||
2. 再看 [Core 模块总览](../core/index.md) 了解默认运行时怎么组织这些契约
|
||||
3. 回到模块 README：
|
||||
- [Core 抽象层说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.Abstractions/README.md)
|
||||
- [Core 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core/README.md)
|
||||
3. 再按需要回到：
|
||||
- [入门指南](../getting-started/index.md)
|
||||
- [Core 模块总览](../core/index.md)
|
||||
4. 需要统一导航时，再看 [API 参考](../api-reference/index.md)
|
||||
|
||||
@ -89,6 +89,6 @@ var options = new ArchOptions
|
||||
|
||||
1. 先读本页，确认你是否真的只需要契约层
|
||||
2. 如果需要默认实现，再看 [Arch ECS 集成](../ecs/arch.md)
|
||||
3. 回到对应模块 README：
|
||||
- [ECS 抽象层说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Ecs.Arch.Abstractions/README.md)
|
||||
- [Ecs.Arch 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Ecs.Arch/README.md)
|
||||
3. 需要统一入口时，再看：
|
||||
- [ECS 模块总览](../ecs/index.md)
|
||||
- [入门指南](../getting-started/index.md)
|
||||
|
||||
@ -116,6 +116,6 @@ public sealed class ContinueGameCommandHandler
|
||||
- [设置系统](../game/setting.md)
|
||||
- [场景系统](../game/scene.md)
|
||||
- [UI 系统](../game/ui.md)
|
||||
4. 需要仓库侧入口时，回到：
|
||||
- [Game 抽象层说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.Abstractions/README.md)
|
||||
- [Game 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)
|
||||
4. 需要统一入口时，回到：
|
||||
- [Game 模块总览](../game/index.md)
|
||||
- [入门指南](../getting-started/index.md)
|
||||
|
||||
@ -5,35 +5,34 @@ description: GFramework 的 API 阅读入口，按模块映射 README、专题
|
||||
|
||||
# API 参考
|
||||
|
||||
这里不再维护一份脱离源码演化的“伪 API 列表”。
|
||||
这页不是签名索引，而是“先看哪个模块入口、再回哪里读 XML 文档”的导航页。
|
||||
|
||||
当前 `GFramework` 的 API 参考链路以四类证据协同为准：
|
||||
最常见的阅读顺序是：
|
||||
|
||||
1. 模块 README：说明包关系、最小接入路径和目录边界
|
||||
2. `docs/zh-CN` 专题页：说明采用顺序、生命周期和使用建议
|
||||
3. 代码中的 XML 文档：说明公开 / 内部类型和关键成员的契约
|
||||
4. 教程页：说明这些 API 在真实接入路径中的组合方式
|
||||
1. 先按模块找到对应栏目入口
|
||||
2. 再进专题页确认安装、生命周期和推荐接线方式
|
||||
3. 最后回到源码中的 XML 文档核对具体契约
|
||||
|
||||
## 阅读顺序
|
||||
|
||||
### 想确认“该装哪个包、先看哪类 API”
|
||||
|
||||
先读模块 README，再读对应栏目入口页：
|
||||
先读站内入口页：
|
||||
|
||||
- 入门入口：[入门指南](../getting-started/index.md)
|
||||
- 根模块地图：[仓库总览](https://github.com/GeWuYou/GFramework/blob/main/README.md)
|
||||
- 安装与选包：[安装配置](../getting-started/installation.md)
|
||||
|
||||
### 想确认“这个功能属于哪个模块”
|
||||
|
||||
按下面的模块映射进入对应入口：
|
||||
|
||||
| 模块族 | 模块 README | 站内入口 | XML 文档关注点 |
|
||||
| 模块族 | 先看什么 | 继续深入 | XML 文档关注点 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Core` / `Core.Abstractions` | [Core 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core/README.md)、[Core 抽象层说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.Abstractions/README.md) | [Core 栏目](../core/index.md)、[Core 抽象层说明](../abstractions/core-abstractions.md) | 架构入口、生命周期、命令 / 查询 / 事件 / 状态 / 资源 / 日志 / 配置 / 并发契约 |
|
||||
| `Cqrs` / `Cqrs.Abstractions` / `Cqrs.SourceGenerators` | [CQRS 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Cqrs/README.md)、[CQRS 抽象层说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Cqrs.Abstractions/README.md)、[CQRS 源码生成器说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Cqrs.SourceGenerators/README.md) | [CQRS 栏目](../core/cqrs.md)、[CQRS Handler Registry 生成器](../source-generators/cqrs-handler-registry-generator.md) | request / notification / handler / pipeline / registry / fallback contract |
|
||||
| `Game` / `Game.Abstractions` / `Game.SourceGenerators` | [Game 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)、[Game 抽象层说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.Abstractions/README.md)、[Game 源码生成器说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.SourceGenerators/README.md) | [Game 模块总览](../game/index.md)、[Game 抽象层说明](../abstractions/game-abstractions.md) | 配置、数据、设置、场景、UI、存储、序列化契约 |
|
||||
| `Godot` / `Godot.SourceGenerators` | [Godot 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot/README.md)、[Godot 源码生成器说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md) | [Godot 模块总览](../godot/index.md)、[Godot 项目生成器](../source-generators/godot-project-generator.md)、[GetNode 生成器](../source-generators/get-node-generator.md)、[BindNodeSignal 生成器](../source-generators/bind-node-signal-generator.md) | 节点扩展、场景 / UI 适配、配置 / 存储 / 设置接线、Godot 生成器入口 |
|
||||
| `Ecs.Arch` / `Ecs.Arch.Abstractions` | [Ecs.Arch 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Ecs.Arch/README.md)、[ECS 抽象层说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Ecs.Arch.Abstractions/README.md) | [ECS 模块总览](../ecs/index.md)、[Arch ECS 集成](../ecs/arch.md)、[Ecs.Arch 抽象层说明](../abstractions/ecs-arch-abstractions.md) | ECS 模块契约、系统适配、配置对象和运行时装配边界 |
|
||||
| `Core` / `Core.Abstractions` | [Core 模块](../core/index.md) | [Core 抽象层说明](../abstractions/core-abstractions.md)、[快速开始](../getting-started/quick-start.md) | 架构入口、生命周期、命令 / 查询 / 事件 / 状态 / 资源 / 日志 / 配置 / 并发契约 |
|
||||
| `Cqrs` / `Cqrs.Abstractions` / `Cqrs.SourceGenerators` | [CQRS 运行时](../core/cqrs.md) | [CQRS Handler Registry 生成器](../source-generators/cqrs-handler-registry-generator.md)、[协程系统](../core/coroutine.md) | request / notification / handler / pipeline / registry / fallback contract |
|
||||
| `Game` / `Game.Abstractions` / `Game.SourceGenerators` | [Game 模块总览](../game/index.md) | [Game 抽象层说明](../abstractions/game-abstractions.md)、[配置系统](../game/config-system.md) | 配置、数据、设置、场景、UI、存储、序列化契约 |
|
||||
| `Godot` / `Godot.SourceGenerators` | [Godot 模块总览](../godot/index.md) | [Godot 项目生成器](../source-generators/godot-project-generator.md)、[GetNode 生成器](../source-generators/get-node-generator.md)、[BindNodeSignal 生成器](../source-generators/bind-node-signal-generator.md) | 节点扩展、场景 / UI 适配、配置 / 存储 / 设置接线、Godot 生成器入口 |
|
||||
| `Ecs.Arch` / `Ecs.Arch.Abstractions` | [ECS 模块总览](../ecs/index.md) | [Arch ECS 集成](../ecs/arch.md)、[Ecs.Arch 抽象层说明](../abstractions/ecs-arch-abstractions.md) | ECS 模块契约、系统适配、配置对象和运行时装配边界 |
|
||||
|
||||
## 先看 XML，还是先看教程
|
||||
|
||||
@ -61,31 +60,23 @@ description: GFramework 的 API 阅读入口，按模块映射 README、专题
|
||||
- 最佳实践：[最佳实践](../best-practices/index.md)
|
||||
- 故障排查：[故障排查](../troubleshooting.md)
|
||||
|
||||
## 当前边界
|
||||
## 共享支撑层怎么看
|
||||
|
||||
- `GFramework.Core.SourceGenerators.Abstractions`
|
||||
- `GFramework.Godot.SourceGenerators.Abstractions`
|
||||
- `GFramework.SourceGenerators.Common`
|
||||
|
||||
这些目录当前不是独立消费模块，因此不单独维护站内 API 参考入口。它们的公开说明跟随所属模块 README 和
|
||||
`source-generators` 栏目维护。
|
||||
|
||||
更准确地说：
|
||||
这些目录当前不作为独立采用入口；阅读它们时，优先回到所属模块页和 `source-generators` 栏目，再根据需要下钻到具体源码目录。
|
||||
|
||||
- `*.SourceGenerators.Abstractions`
|
||||
- 主要定义公开 attribute 和最小契约，供对应生成器与消费端项目共享。
|
||||
- `GFramework.SourceGenerators.Common`
|
||||
- 主要提供共享生成器基类、通用 diagnostics，以及生成方法冲突等跨模块约束。
|
||||
|
||||
如果你在 `Core`、`CQRS`、`Game`、`Godot` 的生成器页面里遇到相似的 diagnostics 或冲突语义，优先把它理解为共享
|
||||
支撑层在复用同一套规则，而不是把这些目录当成新的安装入口。
|
||||
|
||||
## 使用方式
|
||||
|
||||
把本页当成“API 阅读导航”而不是“签名快照”：
|
||||
|
||||
- 先选模块
|
||||
- 再进 README 和专题页确认采用路径
|
||||
- 再进专题页确认采用路径
|
||||
- 最后回到代码里的 XML 文档核对具体契约
|
||||
|
||||
当 README、专题页和 XML 文档出现冲突时，以源码和测试所反映的当前实现为准。
|
||||
|
||||
@ -214,4 +214,4 @@ RegisterCqrsPipelineBehavior<LoggingBehavior<,>>();
|
||||
- 上下文入口：[Context 上下文](./context.md)
|
||||
- 生成器专题：[CQRS Handler Registry 生成器](../source-generators/cqrs-handler-registry-generator.md)
|
||||
- 协程接法：[协程系统](./coroutine.md)
|
||||
- 模块说明：[CQRS 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Cqrs/README.md)
|
||||
- 选包与入口：[入门指南](../getting-started/index.md)
|
||||
|
||||
@ -8,7 +8,7 @@ description: GFramework.Core 与 GFramework.Core.Abstractions 的运行时入口
|
||||
`Core` 栏目对应 `GFramework` 的基础运行时层，主要覆盖 `GFramework.Core` 与 `GFramework.Core.Abstractions`，以及与之直接相邻的旧版
|
||||
`Command` / `Query` 执行器和新版 `CQRS` 迁移入口。
|
||||
|
||||
如果你第一次接入框架，建议先把这里当作“运行时底座说明”，再按需进入 `Game`、`Godot` 或 Source Generators 栏目。
|
||||
如果你第一次接入框架，可以先把这里当作“运行时底座说明”：先确认 `Core` 解决什么问题、最小安装组合是什么，再决定什么时候转向 `CQRS`、`Game`、`Godot` 或源码生成器。
|
||||
|
||||
## 模块与包关系
|
||||
|
||||
@ -32,7 +32,7 @@ dotnet add package GeWuYou.GFramework.Core.Abstractions
|
||||
|
||||
## 栏目覆盖范围
|
||||
|
||||
`Core` 栏目不是旧版“完整框架教程”的镜像，而是当前实现的入口导航。这里的页面按能力域组织：
|
||||
这里的页面按能力域组织，适合按“我要接什么能力”而不是“我要读完所有目录”的方式进入：
|
||||
|
||||
- 架构与生命周期
|
||||
- [架构](./architecture.md)
|
||||
@ -71,7 +71,7 @@ dotnet add package GeWuYou.GFramework.Core.Abstractions
|
||||
|
||||
如果你已经知道模块归属，但想确认公开类型的契约边界，建议按下面顺序阅读：
|
||||
|
||||
1. 先看[Core 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core/README.md)，确认包关系和目录边界
|
||||
1. 先读本页与 [Core 抽象层说明](../abstractions/core-abstractions.md)，确认运行时和契约层边界
|
||||
2. 再看本栏目对应专题页，确认采用顺序、生命周期与推荐接线方式
|
||||
3. 最后回到源码中的 XML 文档，重点核对这些类型族：
|
||||
- `Architecture` / `IArchitectureContext`
|
||||
@ -148,7 +148,8 @@ public sealed class CounterArchitecture : Architecture
|
||||
|
||||
## 对应模块入口
|
||||
|
||||
- [Core 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core/README.md)
|
||||
- [Core 抽象层说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.Abstractions/README.md)
|
||||
- [入门指南](../getting-started/index.md)
|
||||
- [Core 抽象层说明](../abstractions/core-abstractions.md)
|
||||
- [CQRS 运行时](./cqrs.md)
|
||||
- [源码生成器总览](../source-generators/index.md)
|
||||
- [API 参考入口](../api-reference/index.md)
|
||||
- [仓库总览](https://github.com/GeWuYou/GFramework/blob/main/README.md)
|
||||
|
||||
@ -140,5 +140,5 @@ ecsModule.Update(deltaTime);
|
||||
|
||||
- ECS 模块总览：[ECS 模块总览](./index.md)
|
||||
- 抽象契约页：[ECS 抽象层说明](../abstractions/ecs-arch-abstractions.md)
|
||||
- 仓库模块说明：[Ecs.Arch 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Ecs.Arch/README.md)
|
||||
- 选包与接入顺序：[入门指南](../getting-started/index.md)
|
||||
- 统一 API / XML 导航：[API 参考](../api-reference/index.md)
|
||||
|
||||
@ -25,7 +25,7 @@ description: GFramework.Game family 的运行时入口、采用顺序与源码
|
||||
|
||||
## 栏目覆盖范围
|
||||
|
||||
`Game` 栏目聚焦“游戏项目该怎么接这些运行时能力”，不再保留与当前实现脱节的泛化模块示例。
|
||||
`Game` 栏目聚焦“游戏项目该怎么把这些运行时能力接起来”，适合先按目标判断你要接入的是配置、设置与存档、Scene / UI 路由，还是文件存储与序列化。
|
||||
|
||||
当前栏目主要入口：
|
||||
|
||||
@ -115,20 +115,16 @@ IStorage storage = new FileStorage("GameData", serializer);
|
||||
| `GFramework.Game.Abstractions` | `IConfigRegistry`、`ISaveRepository<TSaveData>`、`ISettingsSystem`、`ISceneRouter`、`IUiRouter` | 契约层边界，以及项目中哪些程序集只应依赖接口 |
|
||||
| `GFramework.Game.SourceGenerators` | `SchemaConfigGenerator`、`ConfigSchemaDiagnostics` | schema 生成入口与诊断模型，确认配置系统的编译期链路 |
|
||||
|
||||
## 与真实接法的关系
|
||||
## 运行时与生成器如何配合
|
||||
|
||||
本栏目内容以源码、`*.csproj`、模块说明页与 `ai-libs/` 下已验证的参考接法为准。
|
||||
|
||||
例如当前文档应优先和以下已验证事实保持一致：
|
||||
|
||||
- 配置系统采用 `YAML + JSON Schema + Source Generator`
|
||||
- 设置持久化通常通过 `UnifiedSettingsDataRepository`
|
||||
- 场景与 UI 路由依赖项目自己的 factory / root，而不是框架替你绑定引擎对象
|
||||
|
||||
如果某个旧页面与这些事实冲突，应以源码和模块说明页为准，并在同一轮里修正文档。
|
||||
- 运行时入口主要来自 `GFramework.Game`
|
||||
- 只依赖接口或拆分业务层时，补充 `GFramework.Game.Abstractions`
|
||||
- 需要静态内容配置类型和表包装生成时，再追加 `GFramework.Game.SourceGenerators`
|
||||
- 需要编辑器侧内容维护工作流时，再看 [VS Code 配置工具](./config-tool.md)
|
||||
|
||||
## 对应模块入口
|
||||
|
||||
- [Game 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)
|
||||
- [Game 抽象层说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.Abstractions/README.md)
|
||||
- [仓库总览](https://github.com/GeWuYou/GFramework/blob/main/README.md)
|
||||
- [入门指南](../getting-started/index.md)
|
||||
- [Game 抽象层说明](../abstractions/game-abstractions.md)
|
||||
- [源码生成器总览](../source-generators/index.md)
|
||||
- [API 参考入口](../api-reference/index.md)
|
||||
|
||||
@ -258,5 +258,5 @@ await sceneRouter.PopAsync();
|
||||
|
||||
1. [Game 模块总览](./index.md)
|
||||
2. [UI 系统](./ui.md)
|
||||
3. [Game 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)
|
||||
4. [Game 抽象层说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.Abstractions/README.md)
|
||||
3. [Game 抽象层说明](../abstractions/game-abstractions.md)
|
||||
4. [API 参考](../api-reference/index.md)
|
||||
|
||||
@ -329,5 +329,5 @@ uiRouter.Hide(modalHandle, UiLayer.Modal);
|
||||
1. [Game 模块总览](./index.md)
|
||||
2. [场景系统](./scene.md)
|
||||
3. [AutoUiPage 生成器](../source-generators/auto-ui-page-generator.md)
|
||||
4. [Game 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)
|
||||
5. [Game 抽象层说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.Abstractions/README.md)
|
||||
4. [Game 抽象层说明](../abstractions/game-abstractions.md)
|
||||
5. [API 参考](../api-reference/index.md)
|
||||
|
||||
@ -5,17 +5,19 @@ description: 概览 GFramework 的模块组成、最小接入路径与继续阅
|
||||
|
||||
# 入门指南
|
||||
|
||||
这一部分只回答三个问题：
|
||||
如果你第一次接触 `GFramework`，或者还在判断“应该先装哪些包、先看哪一组文档”，先从这里开始最省时间。
|
||||
|
||||
1. `GFramework` 由哪些模块组成
|
||||
2. 第一次接入应该从哪个包开始
|
||||
3. 最小可运行路径是什么
|
||||
这组页面的目标只有一个：帮你用最短路径找到适合当前项目的运行时入口、安装组合和下一步阅读顺序。
|
||||
|
||||
如果你还没决定具体用法，先阅读本栏目；如果你已经明确要用某个模块，直接进入对应模块的说明页会更快。
|
||||
## 适合谁先读本栏
|
||||
|
||||
## 推荐起步路径
|
||||
- 第一次接入 `GFramework`，还没决定该从 `Core`、`Game`、`Godot` 还是 `CQRS` 开始
|
||||
- 想先确认最小安装组合，再决定是否追加源码生成器
|
||||
- 想先跑通一个可运行骨架，再深入某个专题页
|
||||
|
||||
### 只想先把架构跑起来
|
||||
## 按目标选择起步路线
|
||||
|
||||
### 基础运行时起步
|
||||
|
||||
从 `Core` 开始：
|
||||
|
||||
@ -33,8 +35,9 @@ description: 概览 GFramework 的模块组成、最小接入路径与继续阅
|
||||
|
||||
- [Core 模块总览](../core/index.md)
|
||||
- [快速开始](./quick-start.md)
|
||||
- [安装配置](./installation.md)
|
||||
|
||||
### 想用新版 CQRS
|
||||
### 新版 CQRS 请求流
|
||||
|
||||
在 `Core` 基础上补：
|
||||
|
||||
@ -51,9 +54,9 @@ description: 概览 GFramework 的模块组成、最小接入路径与继续阅
|
||||
对应文档：
|
||||
|
||||
- [CQRS 运行时](../core/cqrs.md)
|
||||
- 模块说明：[CQRS 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Cqrs/README.md)
|
||||
- [安装配置](./installation.md)
|
||||
|
||||
### 想做游戏运行时
|
||||
### 游戏运行时与内容配置
|
||||
|
||||
在 `Core` 基础上按需补：
|
||||
|
||||
@ -70,9 +73,10 @@ description: 概览 GFramework 的模块组成、最小接入路径与继续阅
|
||||
对应文档：
|
||||
|
||||
- [Game 模块总览](../game/index.md)
|
||||
- 模块说明：[Game 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)
|
||||
- [配置系统](../game/config-system.md)
|
||||
- [安装配置](./installation.md)
|
||||
|
||||
### 想接入 Godot
|
||||
### Godot 项目接入
|
||||
|
||||
继续叠加：
|
||||
|
||||
@ -81,9 +85,10 @@ description: 概览 GFramework 的模块组成、最小接入路径与继续阅
|
||||
对应文档：
|
||||
|
||||
- [Godot 模块总览](../godot/index.md)
|
||||
- 模块说明：[Godot 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot/README.md)
|
||||
- [Godot 集成教程](../tutorials/godot-integration.md)
|
||||
- [安装配置](./installation.md)
|
||||
|
||||
## Source Generators 什么时候装
|
||||
## 什么时候追加源码生成器
|
||||
|
||||
只在需要编译期生成代码时再装：
|
||||
|
||||
@ -99,14 +104,15 @@ description: 概览 GFramework 的模块组成、最小接入路径与继续阅
|
||||
- 为 CQRS handlers 生成注册表
|
||||
- 生成 Godot 节点、场景和 UI 包装代码
|
||||
|
||||
继续阅读：
|
||||
|
||||
- [源码生成器总览](../source-generators/index.md)
|
||||
- [配置系统](../game/config-system.md)
|
||||
- [CQRS Handler Registry 生成器](../source-generators/cqrs-handler-registry-generator.md)
|
||||
|
||||
## 建议阅读顺序
|
||||
|
||||
1. [快速开始](./quick-start.md)
|
||||
2. 你准备使用的模块说明页
|
||||
3. 对应栏目页，例如 `core`、`game`、`godot`
|
||||
4. 需要更完整示例时，再进入 `tutorials/`
|
||||
|
||||
## 注意
|
||||
|
||||
- 旧文档里有一些早期示例已经和当前 API 漂移。本栏目以后只保留经过代码或测试核对的最小路径。
|
||||
- 若根 README、模块 README 与某篇专题页冲突，以模块 README 和当前代码为准。
|
||||
2. [安装配置](./installation.md)
|
||||
3. 按你的目标进入 [基础运行时](../core/index.md)、[游戏运行时](../game/index.md)、[Godot 集成](../godot/index.md) 或 [源码生成器](../source-generators/index.md)
|
||||
4. 需要完整示例时，再进入 [教程总览](../tutorials/index.md)
|
||||
|
||||
@ -107,4 +107,4 @@ Console.WriteLine(count); // 1
|
||||
|
||||
- 新功能的请求 / 通知处理：看 [CQRS 运行时](../core/cqrs.md)
|
||||
- 游戏层能力与接入顺序：看 [Game 模块总览](../game/index.md)
|
||||
- 包目录与最小安装组合：看 [Core 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core/README.md)
|
||||
- 包目录与最小安装组合：看 [安装配置](./installation.md)
|
||||
|
||||
@ -1,11 +1,11 @@
|
||||
---
|
||||
title: Godot 场景系统
|
||||
description: 以当前 GFramework.Godot 源码、Game 场景契约与 CoreGrid 接线为准，说明 PackedScene 场景工厂、行为包装和最小接入路径。
|
||||
description: 说明 GFramework.Godot 当前如何把 Game 场景契约接到 PackedScene、行为包装和最小接入路径上。
|
||||
---
|
||||
|
||||
# Godot 场景系统
|
||||
|
||||
`GFramework.Godot` 在场景这一层负责的是 Godot runtime 适配，而不是再提供一个 Godot 专属 router。
|
||||
`GFramework.Godot` 在场景这一层负责的是 Godot runtime 适配，而不是再提供一套 Godot 专用路由器类型。
|
||||
|
||||
当前真正参与场景接线的核心类型是：
|
||||
|
||||
@ -14,7 +14,7 @@ description: 以当前 GFramework.Godot 源码、Game 场景契约与 CoreGrid
|
||||
- `SceneBehaviorFactory`
|
||||
- `SceneBehaviorBase<T>` 及其 `Node2D` / `Node3D` / `Control` / `Generic` 实现
|
||||
- 项目侧实现的 `ISceneRoot`
|
||||
- 项目侧继承 `SceneRouterBase` 的 router
|
||||
- 项目侧继承 `SceneRouterBase` 的路由器
|
||||
|
||||
也就是说，Godot 集成页的重点不是“再造一套场景导航 API”，而是把 `PackedScene`、`Node` 和 `GFramework.Game` 的
|
||||
`ISceneRouter` / `ISceneBehavior` 契约接起来。
|
||||
@ -39,7 +39,7 @@ Godot 侧的场景资源表，底层是 `IAssetRegistry<PackedScene>`。它只
|
||||
3. 如果节点实现了 `ISceneBehaviorProvider`，优先返回 `provider.GetScene()`
|
||||
4. 否则回退到 `SceneBehaviorFactory.Create(node, sceneKey)`
|
||||
|
||||
这和旧文档里“必须有 Godot 专属 router / 专属 scene provider 才能工作”的说法不同。当前源码允许两条路径：
|
||||
当前源码允许两条路径：
|
||||
|
||||
- 显式 provider：项目自己决定行为对象
|
||||
- 自动包装：按节点类型回退到默认 behavior
|
||||
@ -67,24 +67,23 @@ process 开关和 `QueueFreeX()` 释放。
|
||||
- `Control` -> `ControlSceneBehavior`
|
||||
- 其他 `Node` -> `GenericSceneBehavior`
|
||||
|
||||
这意味着 Godot runtime 确实能“自动给节点补一个 behavior”，但它不会替你补项目侧 router、root 或 registry。
|
||||
这意味着 Godot runtime 确实能“自动给节点补一个 behavior”，但它不会替你补项目侧路由器、root 或 registry。
|
||||
|
||||
## 最小接入路径
|
||||
|
||||
推荐按下面顺序接入。
|
||||
|
||||
### 1. 继续在项目层保留自己的 router
|
||||
### 1. 继续在项目层保留自己的路由器
|
||||
|
||||
`GFramework.Godot` 当前没有 `GodotSceneRouter` 类型。消费者项目的实际做法，是在项目层继承
|
||||
`GFramework.Game.Scene.SceneRouterBase`。
|
||||
|
||||
`ai-libs/CoreGrid` 的 router 就是这样：
|
||||
最小形态通常就是：
|
||||
|
||||
```csharp
|
||||
using global::CoreGrid.global;
|
||||
using LoggingTransitionHandler = GFramework.Game.Scene.Handler.LoggingTransitionHandler;
|
||||
|
||||
namespace CoreGrid.scripts.core.scene;
|
||||
namespace GameProject.Scene;
|
||||
|
||||
public partial class SceneRouter : SceneRouterBase
|
||||
{
|
||||
@ -102,7 +101,7 @@ public partial class SceneRouter : SceneRouterBase
|
||||
}
|
||||
```
|
||||
|
||||
这里可以看到，Godot 适配点在 factory / registry / root / transition handler 上，而 router 仍然是项目类。
|
||||
这里可以看到，Godot 适配点在 factory / registry / root / transition handler 上，而路由器仍然是项目类。
|
||||
|
||||
### 2. 注册 `IGodotSceneRegistry` 与 `ISceneFactory`
|
||||
|
||||
|
||||
@ -104,7 +104,7 @@ slider.Signal(Range.SignalName.ValueChanged)
|
||||
|
||||
### 4. 静态场景绑定优先交给 `[BindNodeSignal]`
|
||||
|
||||
从 [Godot 源码生成器说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md) 和 `ai-libs/CoreGrid` 的当前接法看，静态场景按钮、滑条、菜单项这类固定
|
||||
从 [源码生成器总览](../source-generators/index.md) 和当前 Godot 接线方式看，静态场景按钮、滑条、菜单项这类固定
|
||||
节点，更常见的路径仍然是 `[BindNodeSignal]`：
|
||||
|
||||
```csharp
|
||||
|
||||
@ -1,12 +1,12 @@
|
||||
---
|
||||
title: Godot UI 系统
|
||||
description: 以当前 GFramework.Godot 源码、Game UI 契约与 CoreGrid 接线为准，说明 PackedScene UI 工厂、页面行为和层级接入路径。
|
||||
description: 说明 GFramework.Godot 当前如何把 Game UI 契约接到 PackedScene、页面行为和层级 UI 接入路径上。
|
||||
---
|
||||
|
||||
# Godot UI 系统
|
||||
|
||||
`GFramework.Godot.UI` 当前负责的是把 `GFramework.Game` 的 UI 路由契约接到 `Control` / `CanvasLayer` /
|
||||
`PackedScene` 上，而不是定义一个 Godot 专属 router。
|
||||
`PackedScene` 上，而不是再提供一套 Godot 专用路由器类型。
|
||||
|
||||
当前真正参与这条链路的核心类型是：
|
||||
|
||||
@ -16,7 +16,7 @@ description: 以当前 GFramework.Godot 源码、Game UI 契约与 CoreGrid 接
|
||||
- `UiPageBehaviorFactory`
|
||||
- `Page` / `Overlay` / `Modal` / `Toast` / `Topmost` 五类 layer behavior
|
||||
- 项目侧实现的 `IUiRoot`
|
||||
- 项目侧继承 `UiRouterBase` 的 router
|
||||
- 项目侧继承 `UiRouterBase` 的路由器
|
||||
|
||||
## 当前公开入口
|
||||
|
||||
@ -83,16 +83,16 @@ Godot runtime 的页面行为包装基类。它把 `IUiPageBehavior` 的这些
|
||||
|
||||
## 最小接入路径
|
||||
|
||||
### 1. 继续在项目层保留自己的 router
|
||||
### 1. 继续在项目层保留自己的路由器
|
||||
|
||||
仓库当前不存在 `GodotUiRouter` 类型。实际做法仍然是项目侧继承 `GFramework.Game.UI.UiRouterBase`。
|
||||
|
||||
`ai-libs/CoreGrid` 的 `UiRouter` 目前就是：
|
||||
最小形态通常就是：
|
||||
|
||||
```csharp
|
||||
using LoggingTransitionHandler = GFramework.Game.UI.Handler.LoggingTransitionHandler;
|
||||
|
||||
namespace CoreGrid.scripts.core.ui;
|
||||
namespace GameProject.UI;
|
||||
|
||||
[Log]
|
||||
public partial class UiRouter : UiRouterBase
|
||||
@ -105,7 +105,7 @@ public partial class UiRouter : UiRouterBase
|
||||
}
|
||||
```
|
||||
|
||||
Godot runtime 自身并不接管这层 router 的定义。
|
||||
Godot runtime 自身并不接管这层路由器定义。
|
||||
|
||||
### 2. 注册 `IGodotUiRegistry` 与 `IUiFactory`
|
||||
|
||||
|
||||
@ -220,4 +220,4 @@ public List<IntConfig>? Values { get; } = new();
|
||||
1. [源码生成器总览](./index.md)
|
||||
2. [配置系统](../game/config-system.md)
|
||||
3. [Godot 项目生成器](./godot-project-generator.md)
|
||||
4. [Godot 源码生成器说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md)
|
||||
4. [Godot 模块总览](../godot/index.md)
|
||||
|
||||
@ -189,4 +189,4 @@ private void OnAnyButtonPressed()
|
||||
1. [GetNode 生成器](./get-node-generator.md)
|
||||
2. [Godot 项目生成器](./godot-project-generator.md)
|
||||
3. [Godot UI 系统](../godot/ui.md)
|
||||
4. [Godot 源码生成器说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md)
|
||||
4. [Godot 模块总览](../godot/index.md)
|
||||
|
||||
@ -195,4 +195,4 @@ finally
|
||||
1. [ContextGet 生成器](./context-get-generator.md)
|
||||
2. [日志生成器](./logging-generator.md)
|
||||
3. [Core 模块总览](../core/index.md)
|
||||
4. [Core 源码生成器说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.SourceGenerators/README.md)
|
||||
4. [源码生成器总览](./index.md)
|
||||
|
||||
@ -215,4 +215,4 @@ public override void _Ready()
|
||||
1. [BindNodeSignal 生成器](./bind-node-signal-generator.md)
|
||||
2. [Godot 项目生成器](./godot-project-generator.md)
|
||||
3. [Godot UI 系统](../godot/ui.md)
|
||||
4. [Godot 源码生成器说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md)
|
||||
4. [Godot 模块总览](../godot/index.md)
|
||||
|
||||
@ -217,4 +217,4 @@ AutoLoad 名称也遵循同样的冲突处理策略。
|
||||
1. [GetNode 生成器](./get-node-generator.md)
|
||||
2. [BindNodeSignal 生成器](./bind-node-signal-generator.md)
|
||||
3. [Godot 集成教程](../tutorials/godot-integration.md)
|
||||
4. [Godot 源码生成器说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md)
|
||||
4. [Godot 模块总览](../godot/index.md)
|
||||
|
||||
@ -7,7 +7,7 @@ description: 按模块梳理 GFramework 当前发布的源码生成器包、运
|
||||
|
||||
`Source Generators` 栏目对应 `GFramework` 当前按模块拆分发布的编译期工具链。
|
||||
|
||||
这里的重点不是“存在一个统一的大生成器包”，而是帮助你确认应该安装哪个生成器包、它服务哪个运行时模块，以及继续去看哪一类专题页。
|
||||
如果你当前最关心的是“我该装哪个生成器包、它服务哪个运行时、接下来该去哪看示例或专题页”，先看这一页。
|
||||
|
||||
## 当前包拆分
|
||||
|
||||
@ -20,33 +20,14 @@ GFramework 当前发布的生成器包是：
|
||||
|
||||
不存在 `GeWuYou.GFramework.SourceGenerators` 或 `*.SourceGenerators.Attributes` 这类聚合包。
|
||||
|
||||
## 共享支撑模块
|
||||
|
||||
除了上面的可直接安装包，仓库里还有三类跟随这些生成器共同演化的支撑目录：
|
||||
|
||||
- `GFramework.SourceGenerators.Common`
|
||||
- 承载跨生成器共享的基类、通用 diagnostics 和生成冲突规则。
|
||||
- `GFramework.Core.SourceGenerators.Abstractions`
|
||||
- 承载 `Core` 侧生成器特性定义，例如 `[Log]`、`[ContextAware]`、`[GetModel]`、`[GenerateEnumExtensions]`。
|
||||
- `GFramework.Godot.SourceGenerators.Abstractions`
|
||||
- 承载 Godot 侧生成器特性定义，例如 `[GetNode]`、`[BindNodeSignal]`、`[AutoScene]`、`[AutoUiPage]`。
|
||||
|
||||
这些目录当前不是新的安装入口。对读者更重要的是先判断：
|
||||
|
||||
- 应该安装哪个 `*.SourceGenerators` 包
|
||||
- 当前看到的 attribute 和 diagnostics 属于哪条生成链
|
||||
- 继续阅读时应该回到哪个运行时或专题页
|
||||
|
||||
## 先按场景选包
|
||||
|
||||
- 想减少日志、上下文注入、模块自动注册等 Core 侧样板代码：
|
||||
- 选择 `GeWuYou.GFramework.Core.SourceGenerators`
|
||||
- 想把 `schemas/**/*.schema.json` 生成成配置类型和表包装：
|
||||
- 选择 `GeWuYou.GFramework.Game.SourceGenerators`
|
||||
- 想让 CQRS handler registry 在编译期生成，缩小运行时反射扫描范围：
|
||||
- 选择 `GeWuYou.GFramework.Cqrs.SourceGenerators`
|
||||
- 想在 Godot 项目里生成 AutoLoad / Input Action 入口、节点 / 信号样板，或补齐 Scene/UI 包装与导出集合注册辅助：
|
||||
- 选择 `GeWuYou.GFramework.Godot.SourceGenerators`
|
||||
| 使用场景 | 安装包 | 继续阅读 |
|
||||
| --- | --- | --- |
|
||||
| 减少日志、上下文注入、模块自动注册等 Core 侧样板代码 | `GeWuYou.GFramework.Core.SourceGenerators` | [Core 模块](../core/index.md)、[日志生成器](./logging-generator.md)、[ContextAware 生成器](./context-aware-generator.md) |
|
||||
| 把 `schemas/**/*.schema.json` 生成成配置类型和表包装 | `GeWuYou.GFramework.Game.SourceGenerators` | [配置系统](../game/config-system.md)、[VS Code 配置工具](../game/config-tool.md) |
|
||||
| 让 CQRS handler registry 在编译期生成，缩小运行时反射扫描范围 | `GeWuYou.GFramework.Cqrs.SourceGenerators` | [CQRS 运行时](../core/cqrs.md)、[CQRS Handler Registry 生成器](./cqrs-handler-registry-generator.md) |
|
||||
| 在 Godot 项目里生成 AutoLoad / Input Action 入口、节点 / 信号样板，或补齐 Scene/UI 包装与导出集合注册辅助 | `GeWuYou.GFramework.Godot.SourceGenerators` | [Godot 模块总览](../godot/index.md)、[Godot 项目生成器](./godot-project-generator.md)、[GetNode 生成器](./get-node-generator.md) |
|
||||
|
||||
## 与运行时的关系
|
||||
|
||||
@ -72,11 +53,22 @@ GFramework 当前发布的生成器包是：
|
||||
|
||||
其他生成器包的安装模式相同。
|
||||
|
||||
`GFramework.SourceGenerators.Common` 和两个 `*.SourceGenerators.Abstractions` 目录当前都跟随对应生成器模块维护：
|
||||
## 共享支撑模块
|
||||
|
||||
- 不是额外安装的独立包选择题
|
||||
- 主要用于承载 attribute、共享基类和跨生成器共用 diagnostics
|
||||
- 读者只需要在排查 attribute 语义、冲突规则或生成失败原因时回到这些源码目录确认契约
|
||||
除了上面的可直接安装包，仓库里还有三类跟随这些生成器共同演化的支撑目录：
|
||||
|
||||
- `GFramework.SourceGenerators.Common`
|
||||
- 承载跨生成器共享的基类、通用 diagnostics 和生成冲突规则。
|
||||
- `GFramework.Core.SourceGenerators.Abstractions`
|
||||
- 承载 `Core` 侧生成器特性定义，例如 `[Log]`、`[ContextAware]`、`[GetModel]`、`[GenerateEnumExtensions]`。
|
||||
- `GFramework.Godot.SourceGenerators.Abstractions`
|
||||
- 承载 Godot 侧生成器特性定义，例如 `[GetNode]`、`[BindNodeSignal]`、`[AutoScene]`、`[AutoUiPage]`。
|
||||
|
||||
这些目录当前都不是新的安装入口。更实用的理解方式是：
|
||||
|
||||
- 先判断你要装哪个 `*.SourceGenerators` 包
|
||||
- 再根据 attribute 或 diagnostics 回到对应专题页
|
||||
- 只有在排查生成失败原因时，才继续下钻到这些共享支撑目录
|
||||
|
||||
## 这个栏目怎么读
|
||||
|
||||
@ -124,7 +116,7 @@ GFramework 当前发布的生成器包是：
|
||||
|
||||
## 对应模块入口
|
||||
|
||||
- [Core 源码生成器说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.SourceGenerators/README.md)
|
||||
- [Game 源码生成器说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.SourceGenerators/README.md)
|
||||
- [CQRS 源码生成器说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Cqrs.SourceGenerators/README.md)
|
||||
- [Godot 源码生成器说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md)
|
||||
- [Core 模块](../core/index.md)
|
||||
- [Game 模块总览](../game/index.md)
|
||||
- [CQRS 运行时](../core/cqrs.md)
|
||||
- [Godot 模块总览](../godot/index.md)
|
||||
|
||||
@ -213,4 +213,4 @@ public sealed class DynamicPrioritySystem : IPrioritized
|
||||
1. [ContextAware 生成器](./context-aware-generator.md)
|
||||
2. [ContextGet 生成器](./context-get-generator.md)
|
||||
3. [Core 模块总览](../core/index.md)
|
||||
4. [Core 源码生成器说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.SourceGenerators/README.md)
|
||||
4. [源码生成器总览](./index.md)
|
||||
|
||||
@ -39,7 +39,7 @@ description: 汇总 GFramework 的基础与进阶教程入口，帮助按学习
|
||||
|
||||
- 已完成基础教程的开发者
|
||||
- 正在把现有 Godot C# 项目接入 GFramework 的开发者
|
||||
- 需要厘清 `project.godot`、`[GetNode]`、`[BindNodeSignal]` 边界的维护者
|
||||
- 需要厘清 `project.godot`、`[GetNode]`、`[BindNodeSignal]` 接入边界的开发者
|
||||
|
||||
**学习内容**：
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user