mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-05-07 00:39:00 +08:00
docs(godot): 刷新 Godot 文档入口
- 更新 GFramework.Godot README，使包定位、相邻包关系与最小接入路径与当前源码和测试一致 - 重写 GFramework.Godot.SourceGenerators README，补齐 project.godot、节点注入、行为包装与批量注册入口 - 补充 API 参考与 ai-plan 恢复点，确保 Godot 相关入口能直接落到专题页
This commit is contained in:
gewuyou
GeWuYou
parent
7d6ff77ff4
commit
9295480866
@ -1,181 +1,176 @@
|
|||||||
# GFramework.Godot.SourceGenerators
|
# GFramework.Godot.SourceGenerators
|
||||||
|
|
||||||
面向 Godot 场景的源码生成扩展模块，减少模板代码。
|
`GFramework.Godot.SourceGenerators` 负责把 Godot 项目里的重复样板迁移到编译期。
|
||||||
|
|
||||||
## 主要功能
|
当前包覆盖三类核心场景：
|
||||||
|
|
||||||
- 与 Godot 场景相关的编译期生成能力
|
- `project.godot` 元数据入口：生成 `AutoLoads` 与 `InputActions`
|
||||||
- 基于 Roslyn 的增量生成器实现
|
- 节点字段与信号接线：`[GetNode]`、`[BindNodeSignal]`
|
||||||
- `project.godot` 项目元数据生成，产出 AutoLoad 与 Input Action 的强类型访问入口
|
- Scene / UI 与启动注册样板：`[AutoScene]`、`[AutoUiPage]`、`[AutoRegisterExportedCollections]`
|
||||||
- `[GetNode]` 字段注入，减少 `_Ready()` 里的 `GetNode<T>()` 样板代码
|
|
||||||
- `[BindNodeSignal]` 方法绑定，减少 `_Ready()` / `_ExitTree()` 中重复的事件订阅样板代码
|
|
||||||
|
|
||||||
## 使用建议
|
它是 Analyzer 包，不是运行时库。
|
||||||
|
|
||||||
- 仅在 Godot + C# 项目中启用
|
## 包定位
|
||||||
- 非 Godot 项目可只使用 GFramework.SourceGenerators
|
|
||||||
- 当项目通过 NuGet 包引用本模块时，根目录下的 `project.godot` 会被自动加入 `AdditionalFiles`
|
|
||||||
- 当项目通过 `ProjectReference(OutputItemType=Analyzer)` 直接引用生成器时，需要手动把 `project.godot` 加入
|
|
||||||
`AdditionalFiles`
|
|
||||||
|
|
||||||
## project.godot 集成
|
当前生成器主要减少这些重复代码：
|
||||||
|
|
||||||
默认情况下，生成器会读取 Godot 项目根目录下的 `project.godot`，并生成：
|
- 从 `project.godot` 手写 AutoLoad / Input Action 字符串
|
||||||
|
- 在 `_Ready()` 里重复写 `GetNode<T>()`
|
||||||
|
- 在 `_Ready()` / `_ExitTree()` 里重复写 CLR event 订阅与解绑
|
||||||
|
- 为 Godot 场景根节点和页面根节点重复声明 `GetScene()` / `GetPage()` 样板
|
||||||
|
- 在启动入口里重复遍历导出集合并逐项注册到 registry
|
||||||
|
|
||||||
|
它不负责：
|
||||||
|
|
||||||
|
- 提供运行时 Scene / UI / 配置实现
|
||||||
|
- 自动接管完整生命周期方法
|
||||||
|
- 代替 `GFramework.Godot` 的宿主适配逻辑
|
||||||
|
|
||||||
|
## 与相邻包的关系
|
||||||
|
|
||||||
|
- `GFramework.Godot`
|
||||||
|
- 负责 Godot 运行时适配。
|
||||||
|
- 本包只负责编译期入口和样板生成。
|
||||||
|
- `GFramework.Godot.SourceGenerators.Abstractions`
|
||||||
|
- 特性定义所在位置。
|
||||||
|
- 当前 `IsPackable=false`，按内部支撑模块处理，不作为独立消费包推广。
|
||||||
|
- `GFramework.SourceGenerators.Common`
|
||||||
|
- 提供公共生成器基础设施与部分类级诊断支持。
|
||||||
|
- 同样按内部支撑模块处理。
|
||||||
|
|
||||||
|
## 子系统地图
|
||||||
|
|
||||||
|
### `GodotProjectMetadataGenerator`
|
||||||
|
|
||||||
|
读取 `project.godot`，生成：
|
||||||
|
|
||||||
- `GFramework.Godot.Generated.AutoLoads`
|
- `GFramework.Godot.Generated.AutoLoads`
|
||||||
- `GFramework.Godot.Generated.InputActions`
|
- `GFramework.Godot.Generated.InputActions`
|
||||||
|
|
||||||
如果你需要覆盖默认项目文件路径，可以在 MSBuild 中设置：
|
这是项目级元数据入口，不处理节点字段注入或信号绑定。
|
||||||
|
|
||||||
- 路径可以调整到项目根目录下的其他位置
|
### `GetNodeGenerator` 与 `BindNodeSignalGenerator`
|
||||||
- 文件名必须仍然是 `project.godot`，否则生成器会发出警告并忽略该文件
|
|
||||||
|
|
||||||
```xml
|
- `[GetNode]` 负责生成节点字段注入代码
|
||||||
<PropertyGroup>
|
- `[BindNodeSignal]` 负责生成 CLR event 绑定 / 解绑辅助方法
|
||||||
<GFrameworkGodotProjectFile>Config/project.godot</GFrameworkGodotProjectFile>
|
|
||||||
</PropertyGroup>
|
|
||||||
```
|
|
||||||
|
|
||||||
如果你在仓库内通过 analyzer 形式直接引用本项目，则需要显式配置：
|
这两项能力通常一起使用，但职责不同：
|
||||||
|
|
||||||
|
- `[GetNode]` 解决“怎么拿到字段实例”
|
||||||
|
- `[BindNodeSignal]` 解决“字段可用后怎么订阅 / 解绑事件”
|
||||||
|
|
||||||
|
### `Behavior/`
|
||||||
|
|
||||||
|
- `AutoSceneGenerator`
|
||||||
|
- `AutoUiPageGenerator`
|
||||||
|
|
||||||
|
用于给场景根节点和 UI 页面根节点生成稳定的 `GetScene()` / `GetPage()` 包装入口。
|
||||||
|
|
||||||
|
### `Registration/`
|
||||||
|
|
||||||
|
- `AutoRegisterExportedCollectionsGenerator`
|
||||||
|
|
||||||
|
用于把“遍历导出集合并逐项调用 registry 方法”的启动样板收敛成生成方法。
|
||||||
|
|
||||||
|
### `Diagnostics/`
|
||||||
|
|
||||||
|
当前诊断围绕这些方向组织：
|
||||||
|
|
||||||
|
- `project.godot` 文件与元数据约束
|
||||||
|
- `GetNode` / `BindNodeSignal` 的目标成员合法性
|
||||||
|
- `AutoScene` / `AutoUiPage` 的宿主类型与参数合法性
|
||||||
|
- 导出集合注册的成员形状与方法匹配约束
|
||||||
|
|
||||||
|
## 最小接入路径
|
||||||
|
|
||||||
|
### 1. 安装生成器包
|
||||||
|
|
||||||
|
常规 NuGet 引用方式：
|
||||||
|
|
||||||
```xml
|
```xml
|
||||||
<ItemGroup>
|
<ItemGroup>
|
||||||
|
<PackageReference Include="GeWuYou.GFramework.Godot.SourceGenerators"
|
||||||
|
Version="x.y.z"
|
||||||
|
PrivateAssets="all"
|
||||||
|
ExcludeAssets="runtime" />
|
||||||
|
</ItemGroup>
|
||||||
|
```
|
||||||
|
|
||||||
|
通常还会同时引用：
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<PackageReference Include="GeWuYou.GFramework.Godot" Version="x.y.z" />
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. 让 `project.godot` 进入 `AdditionalFiles`
|
||||||
|
|
||||||
|
通过 NuGet 包使用时，`GeWuYou.GFramework.Godot.SourceGenerators.targets` 会自动尝试把项目根目录下的 `project.godot`
|
||||||
|
加入 `AdditionalFiles`。
|
||||||
|
|
||||||
|
如果你是仓库内直接通过 `ProjectReference(OutputItemType=Analyzer)` 引用生成器项目，需要手动加入：
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<ItemGroup>
|
||||||
|
<ProjectReference Include="..\GFramework.Godot.SourceGenerators\GFramework.Godot.SourceGenerators.csproj"
|
||||||
|
OutputItemType="Analyzer"
|
||||||
|
ReferenceOutputAssembly="false" />
|
||||||
<AdditionalFiles Include="project.godot" />
|
<AdditionalFiles Include="project.godot" />
|
||||||
</ItemGroup>
|
</ItemGroup>
|
||||||
```
|
```
|
||||||
|
|
||||||
## AutoLoad 强类型访问
|
### 3. 在节点脚本里显式接生成方法
|
||||||
|
|
||||||
当某个 AutoLoad 无法仅靠类型名唯一推断到 C# 节点类型时，可以使用 `[AutoLoad]` 显式声明映射：
|
当前最重要的生命周期约束是：
|
||||||
|
|
||||||
```csharp
|
- `[GetNode]` 在类型手写 `_Ready()` 时，需要显式调用 `__InjectGetNodes_Generated()`
|
||||||
using GFramework.Godot.SourceGenerators.Abstractions;
|
- `[BindNodeSignal]` 在手写 `_Ready()` / `_ExitTree()` 时，需要显式调用
|
||||||
using Godot;
|
`__BindNodeSignals_Generated()` 与 `__UnbindNodeSignals_Generated()`
|
||||||
|
- `[AutoScene]`、`[AutoUiPage]`、`[AutoRegisterExportedCollections]` 都只生成辅助入口，不会替你织入生命周期
|
||||||
|
|
||||||
[AutoLoad("GameServices")]
|
也就是说，本包负责生成辅助方法，但调用时机仍由项目侧决定。
|
||||||
public partial class GameServices : Node
|
|
||||||
{
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
对应 `project.godot`：
|
### 4. 按场景选特性
|
||||||
|
|
||||||
```ini
|
- 项目级元数据：
|
||||||
[autoload]
|
- `project.godot` -> `AutoLoads`、`InputActions`
|
||||||
GameServices="*res://autoload/game_services.tscn"
|
- 固定节点字段：
|
||||||
AudioBus="*res://autoload/audio_bus.gd"
|
- `[GetNode]`
|
||||||
```
|
- 固定 CLR event 订阅：
|
||||||
|
- `[BindNodeSignal]`
|
||||||
|
- Godot 场景根节点：
|
||||||
|
- `[AutoScene]`
|
||||||
|
- Godot UI 页面根节点：
|
||||||
|
- `[AutoUiPage]`
|
||||||
|
- 启动入口中的集合批量注册：
|
||||||
|
- `[AutoRegisterExportedCollections]`
|
||||||
|
|
||||||
生成器会产出统一入口：
|
## 当前约束
|
||||||
|
|
||||||
```csharp
|
- `GFrameworkGodotProjectFile` 可以改相对路径，但文件名必须仍然是 `project.godot`
|
||||||
using GFramework.Godot.Generated;
|
- `[GetNode]` 与 `[BindNodeSignal]` 都要求宿主类型是顶层 `partial class`
|
||||||
|
- `[BindNodeSignal]` 面向 CLR event，不会自动调用 `Connect()` / `Disconnect()`
|
||||||
|
- `[AutoScene]` 与 `[AutoUiPage]` 只生成行为包装入口，不会替代 `SceneRouterBase` 或 `UiRouterBase`
|
||||||
|
- `[AutoRegisterExportedCollections]` 只适合“集合 -> registry -> 单参数注册方法”这类稳定形状
|
||||||
|
|
||||||
var gameServices = AutoLoads.GameServices;
|
## 文档入口
|
||||||
|
|
||||||
if (AutoLoads.TryGetAudioBus(out var audioBus))
|
- 生成器总览：[docs/zh-CN/source-generators/index.md](../docs/zh-CN/source-generators/index.md)
|
||||||
{
|
- Godot 项目元数据：[docs/zh-CN/source-generators/godot-project-generator.md](../docs/zh-CN/source-generators/godot-project-generator.md)
|
||||||
}
|
- `GetNode`：[docs/zh-CN/source-generators/get-node-generator.md](../docs/zh-CN/source-generators/get-node-generator.md)
|
||||||
```
|
- `BindNodeSignal`：[docs/zh-CN/source-generators/bind-node-signal-generator.md](../docs/zh-CN/source-generators/bind-node-signal-generator.md)
|
||||||
|
- `AutoScene`：[docs/zh-CN/source-generators/auto-scene-generator.md](../docs/zh-CN/source-generators/auto-scene-generator.md)
|
||||||
|
- `AutoUiPage`：[docs/zh-CN/source-generators/auto-ui-page-generator.md](../docs/zh-CN/source-generators/auto-ui-page-generator.md)
|
||||||
|
- `AutoRegisterExportedCollections`：[docs/zh-CN/source-generators/auto-register-exported-collections-generator.md](../docs/zh-CN/source-generators/auto-register-exported-collections-generator.md)
|
||||||
|
- Godot 运行时入口：[../GFramework.Godot/README.md](../GFramework.Godot/README.md)
|
||||||
|
- 集成教程：[docs/zh-CN/tutorials/godot-integration.md](../docs/zh-CN/tutorials/godot-integration.md)
|
||||||
|
|
||||||
- 显式 `[AutoLoad]` 映射优先于隐式类型名推断
|
## 什么时候不该先看这个包
|
||||||
- 若同名映射冲突，生成器会给出诊断并退化为 `Godot.Node` 访问
|
|
||||||
- 若无法映射到 C# 节点类型，仍会生成可用的 `Godot.Node` 访问器
|
|
||||||
|
|
||||||
## Input Action 常量生成
|
以下场景更适合先回到其他入口：
|
||||||
|
|
||||||
`project.godot` 的 `[input]` 段会自动生成稳定常量，避免手写字符串：
|
- 你在确认 Godot 运行时 Scene / UI / 存储 / 设置的默认实现：
|
||||||
|
- 先看 `GFramework.Godot`
|
||||||
```ini
|
- 你只需要 `Game` 契约，不需要 Godot 宿主或生成器：
|
||||||
[input]
|
- 先看 `GFramework.Game` 或 `GFramework.Game.Abstractions`
|
||||||
move_up={
|
- 你在确认项目接线顺序，而不是单个生成器契约：
|
||||||
}
|
- 先看 `docs/zh-CN/tutorials/godot-integration.md`
|
||||||
ui_cancel={
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
```csharp
|
|
||||||
using GFramework.Godot.Generated;
|
|
||||||
|
|
||||||
if (Input.IsActionJustPressed(InputActions.MoveUp))
|
|
||||||
{
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- 动作名会转换为可补全的 C# 标识符，例如 `move_up -> MoveUp`
|
|
||||||
- 当多个动作名映射到同一标识符时，会追加稳定后缀并给出警告
|
|
||||||
|
|
||||||
## GetNode 用法
|
|
||||||
|
|
||||||
```csharp
|
|
||||||
using GFramework.Godot.SourceGenerators.Abstractions;
|
|
||||||
using Godot;
|
|
||||||
|
|
||||||
public partial class TopBar : HBoxContainer
|
|
||||||
{
|
|
||||||
[GetNode]
|
|
||||||
private HBoxContainer _leftContainer = null!;
|
|
||||||
|
|
||||||
[GetNode]
|
|
||||||
private HBoxContainer _rightContainer = null!;
|
|
||||||
|
|
||||||
public override void _Ready()
|
|
||||||
{
|
|
||||||
__InjectGetNodes_Generated();
|
|
||||||
OnReadyAfterGetNode();
|
|
||||||
}
|
|
||||||
|
|
||||||
private void OnReadyAfterGetNode()
|
|
||||||
{
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
当未显式填写路径时，生成器会默认将字段名推导为唯一名路径：
|
|
||||||
|
|
||||||
- `_leftContainer` -> `%LeftContainer`
|
|
||||||
- `m_rightContainer` -> `%RightContainer`
|
|
||||||
|
|
||||||
## BindNodeSignal 用法
|
|
||||||
|
|
||||||
```csharp
|
|
||||||
using GFramework.Godot.SourceGenerators.Abstractions;
|
|
||||||
using Godot;
|
|
||||||
|
|
||||||
public partial class Hud : Control
|
|
||||||
{
|
|
||||||
[GetNode]
|
|
||||||
private Button _startButton = null!;
|
|
||||||
|
|
||||||
[GetNode]
|
|
||||||
private SpinBox _startOreSpinBox = null!;
|
|
||||||
|
|
||||||
[BindNodeSignal(nameof(_startButton), nameof(Button.Pressed))]
|
|
||||||
private void OnStartButtonPressed()
|
|
||||||
{
|
|
||||||
}
|
|
||||||
|
|
||||||
[BindNodeSignal(nameof(_startOreSpinBox), nameof(SpinBox.ValueChanged))]
|
|
||||||
private void OnStartOreValueChanged(double value)
|
|
||||||
{
|
|
||||||
}
|
|
||||||
|
|
||||||
public override void _Ready()
|
|
||||||
{
|
|
||||||
__InjectGetNodes_Generated();
|
|
||||||
__BindNodeSignals_Generated();
|
|
||||||
}
|
|
||||||
|
|
||||||
public override void _ExitTree()
|
|
||||||
{
|
|
||||||
__UnbindNodeSignals_Generated();
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
生成器会产出两个辅助方法：
|
|
||||||
|
|
||||||
- `__BindNodeSignals_Generated()`：负责统一订阅事件
|
|
||||||
- `__UnbindNodeSignals_Generated()`：负责统一解绑事件
|
|
||||||
|
|
||||||
当前设计只处理 CLR event 形式的 Godot 事件绑定，不会自动调用 `Connect()` / `Disconnect()`。
|
|
||||||
|
|||||||
@ -1,19 +1,161 @@
|
|||||||
# GFramework.Godot
|
# GFramework.Godot
|
||||||
|
|
||||||
GFramework 框架的 Godot 引擎集成模块，提供Godot特定的功能和扩展。
|
`GFramework.Godot` 是 `GFramework` 在 Godot 宿主侧的运行时适配包。
|
||||||
|
|
||||||
## 主要功能
|
它建立在 `GFramework.Game`、`GFramework.Game.Abstractions` 与 `GFramework.Core.Abstractions` 之上，把框架已有的架构、
|
||||||
|
Scene / UI、配置、存储、设置、日志与协程能力接到 `Node`、`SceneTree`、`PackedScene`、`FileAccess` 与 `AudioServer`
|
||||||
|
等 Godot 运行时对象上。
|
||||||
|
|
||||||
- **Extensions** - Godot节点扩展方法，简化常见开发任务
|
如果你需要的是 `[GetNode]`、`[BindNodeSignal]`、`AutoLoads` 或 `InputActions` 这类编译期能力，请改为同时安装
|
||||||
- **Signal** - 流畅的信号连接API，支持链式调用
|
`GFramework.Godot.SourceGenerators`。这些能力不属于本包。
|
||||||
- **Storage** - Godot文件存储系统，支持虚拟路径
|
|
||||||
- **Settings** - Godot设置系统，管理音频和图形设置
|
|
||||||
|
|
||||||
## 依赖关系
|
## 包定位
|
||||||
|
|
||||||
- 依赖 GFramework.Core
|
当前包解决的是 Godot 运行时接线，而不是重新定义一套 Godot 专属框架：
|
||||||
- 依赖 GFramework.Core.Abstractions
|
|
||||||
|
|
||||||
## 详细文档
|
- 架构生命周期与场景树绑定：`AbstractArchitecture`、`ArchitectureAnchor`
|
||||||
|
- 节点运行时辅助：`WaitUntilReadyAsync()`、`AddChildXAsync()`、`QueueFreeX()`、`UnRegisterWhenNodeExitTree(...)`
|
||||||
|
- Godot 风格的 Scene / UI 工厂与 registry：`GodotSceneFactory`、`GodotUiFactory`
|
||||||
|
- Godot 特化的配置、存储与设置实现：`GodotYamlConfigLoader`、`GodotFileStorage`、`GodotAudioSettings`
|
||||||
|
- 宿主侧辅助能力：`Signal(...)` fluent API、Godot 时间源、暂停处理、富文本效果
|
||||||
|
|
||||||
参见 [docs/zh-CN/godot/](../docs/zh-CN/godot/) 目录下的详细文档。
|
它不负责：
|
||||||
|
|
||||||
|
- 自动生成节点字段注入代码
|
||||||
|
- 自动生成 `_Ready()` / `_ExitTree()` 接线
|
||||||
|
- 自动扫描所有场景或页面并完成统一注册
|
||||||
|
- 提供 `GodotSceneRouter` 或 `GodotUiRouter` 这类额外 router 类型
|
||||||
|
|
||||||
|
## 与相邻包的关系
|
||||||
|
|
||||||
|
- `GFramework.Game`
|
||||||
|
- 提供 Scene / UI / 配置 / 数据等默认运行时契约与基类。
|
||||||
|
- `GFramework.Godot` 负责把这些能力落到 Godot 宿主。
|
||||||
|
- `GFramework.Game.Abstractions`
|
||||||
|
- 提供 `ISceneFactory`、`IUiFactory`、设置与配置相关契约。
|
||||||
|
- 本包的大部分工厂和适配层都实现这些接口。
|
||||||
|
- `GFramework.Core.Abstractions`
|
||||||
|
- 提供架构、日志、环境等基础契约。
|
||||||
|
- `AbstractArchitecture` 与日志 provider 都建立在这层之上。
|
||||||
|
- `GFramework.Godot.SourceGenerators`
|
||||||
|
- 提供 `project.godot` 元数据、`[GetNode]`、`[BindNodeSignal]`、`[AutoScene]`、`[AutoUiPage]` 等编译期样板生成。
|
||||||
|
- 推荐与本包配套使用，但职责边界要分开理解。
|
||||||
|
|
||||||
|
## 子系统地图
|
||||||
|
|
||||||
|
### `Architectures/`
|
||||||
|
|
||||||
|
- `AbstractArchitecture`
|
||||||
|
- `AbstractGodotModule`
|
||||||
|
- `ArchitectureAnchor`
|
||||||
|
- `IGodotModule`
|
||||||
|
|
||||||
|
用于把架构生命周期绑定到 `SceneTree`，并在需要时把 Godot 模块挂到场景树。
|
||||||
|
|
||||||
|
### `Scene/` 与 `UI/`
|
||||||
|
|
||||||
|
- `GodotSceneFactory`、`GodotSceneRegistry`
|
||||||
|
- `GodotUiFactory`、`GodotUiRegistry`
|
||||||
|
- `SceneBehaviorFactory`、`UiPageBehaviorFactory`
|
||||||
|
|
||||||
|
这部分负责把 `PackedScene`、`Control`、`CanvasLayer` 等 Godot 对象接入 `GFramework.Game` 的 Scene / UI 契约。
|
||||||
|
|
||||||
|
### `Config/`、`Storage/` 与 `Setting/`
|
||||||
|
|
||||||
|
- `GodotYamlConfigLoader`
|
||||||
|
- `GodotFileStorage`
|
||||||
|
- `GodotAudioSettings`、`GodotGraphicsSettings`、`GodotLocalizationSettings`
|
||||||
|
|
||||||
|
这部分解决的是 Godot 文件系统、音频总线、图形与本地化设置等宿主差异。
|
||||||
|
|
||||||
|
### `Extensions/`、`Coroutine/`、`Logging/`、`Pause/`、`Text/`、`Pool/`
|
||||||
|
|
||||||
|
- 节点扩展与 `Signal(...)` fluent API
|
||||||
|
- `GodotTimeSource` 与协程时间分段
|
||||||
|
- Godot 日志 provider
|
||||||
|
- 暂停处理、节点池与富文本效果支持
|
||||||
|
|
||||||
|
这些目录都是“宿主适配层”，不是新的 gameplay 抽象层。
|
||||||
|
|
||||||
|
## 最小接入路径
|
||||||
|
|
||||||
|
### 1. 先区分运行时包和生成器包
|
||||||
|
|
||||||
|
如果你只需要 Godot 运行时适配：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
dotnet add package GeWuYou.GFramework
|
||||||
|
dotnet add package GeWuYou.GFramework.Godot
|
||||||
|
```
|
||||||
|
|
||||||
|
如果你还需要 `project.godot` 强类型入口、节点字段注入和信号绑定，再额外安装：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
dotnet add package GeWuYou.GFramework.Core.SourceGenerators
|
||||||
|
dotnet add package GeWuYou.GFramework.Godot.SourceGenerators
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. 保持原有架构注册方式，只把宿主协作接到 Godot
|
||||||
|
|
||||||
|
常规模块继续使用 `InstallModule(...)`。
|
||||||
|
|
||||||
|
只有模块自身暴露 `Node`、需要挂到 `ArchitectureAnchor`，或要在 `OnAttach(...)` / `OnDetach()` 里处理 Godot 生命周期副作用时，
|
||||||
|
再使用 `InstallGodotModule(...)`。
|
||||||
|
|
||||||
|
`GFramework.Godot.Tests/Architectures/AbstractArchitectureModuleInstallationTests.cs` 已覆盖一个关键边界：锚点缺失时会先抛
|
||||||
|
`InvalidOperationException`，不会继续执行模块安装。
|
||||||
|
|
||||||
|
### 3. Scene / UI 继续沿用 `Game` 契约
|
||||||
|
|
||||||
|
当前真实边界是：
|
||||||
|
|
||||||
|
- 没有 `GodotSceneRouter`
|
||||||
|
- 没有 `GodotUiRouter`
|
||||||
|
- `GodotSceneFactory` 在 provider 缺失时回退到 `SceneBehaviorFactory`
|
||||||
|
- `GodotUiFactory` 仍要求 `IUiPageBehaviorProvider`
|
||||||
|
|
||||||
|
也就是说，项目通常仍然继承 `GFramework.Game.Scene.SceneRouterBase` 与 `GFramework.Game.UI.UiRouterBase`，只是把工厂和行为落到
|
||||||
|
Godot 上。
|
||||||
|
|
||||||
|
### 4. 按需接入配置、存储和设置
|
||||||
|
|
||||||
|
当项目已经使用 `Game` family 的配置、存储、设置契约时，再补 Godot 侧实现：
|
||||||
|
|
||||||
|
- 配置：`GodotYamlConfigLoader`
|
||||||
|
- 存储：`GodotFileStorage`
|
||||||
|
- 设置：`GodotAudioSettings`、`GodotGraphicsSettings`、`GodotLocalizationSettings`
|
||||||
|
|
||||||
|
不要把这些宿主实现误写成 `Game` family 的默认行为。
|
||||||
|
|
||||||
|
## `ai-libs/` 里的参考接入线索
|
||||||
|
|
||||||
|
`ai-libs/CoreGrid` 仍是当前最直接的消费者证据来源：
|
||||||
|
|
||||||
|
- 架构侧保持普通模块注册，再按需挂接 Godot 宿主
|
||||||
|
- `project.godot` 元数据与节点样板交给 `GFramework.Godot.SourceGenerators`
|
||||||
|
- Scene / UI 继续沿用 `Game` family 的 router 语义
|
||||||
|
|
||||||
|
当 `ai-libs/` 与源码或测试冲突时，应以当前源码与测试为准。
|
||||||
|
|
||||||
|
## 文档入口
|
||||||
|
|
||||||
|
- Godot 运行时总览：[docs/zh-CN/godot/index.md](../docs/zh-CN/godot/index.md)
|
||||||
|
- 架构集成：[docs/zh-CN/godot/architecture.md](../docs/zh-CN/godot/architecture.md)
|
||||||
|
- 场景系统：[docs/zh-CN/godot/scene.md](../docs/zh-CN/godot/scene.md)
|
||||||
|
- UI 系统：[docs/zh-CN/godot/ui.md](../docs/zh-CN/godot/ui.md)
|
||||||
|
- 节点扩展：[docs/zh-CN/godot/extensions.md](../docs/zh-CN/godot/extensions.md)
|
||||||
|
- 信号系统：[docs/zh-CN/godot/signal.md](../docs/zh-CN/godot/signal.md)
|
||||||
|
- 日志系统：[docs/zh-CN/godot/logging.md](../docs/zh-CN/godot/logging.md)
|
||||||
|
- 集成教程：[docs/zh-CN/tutorials/godot-integration.md](../docs/zh-CN/tutorials/godot-integration.md)
|
||||||
|
- 生成器入口：[../GFramework.Godot.SourceGenerators/README.md](../GFramework.Godot.SourceGenerators/README.md)
|
||||||
|
|
||||||
|
## 什么时候不该把它当成主入口
|
||||||
|
|
||||||
|
以下场景更适合先回到其他包：
|
||||||
|
|
||||||
|
- 只需要 Scene / UI / 配置契约，不需要 Godot 宿主：
|
||||||
|
- 选 `GFramework.Game.Abstractions`
|
||||||
|
- 需要默认运行时实现，但暂时不接 Godot：
|
||||||
|
- 选 `GFramework.Game`
|
||||||
|
- 需要的是 `project.godot` 元数据、节点字段注入或编译期样板：
|
||||||
|
- 选 `GFramework.Godot.SourceGenerators`
|
||||||
|
|||||||
@ -12,12 +12,12 @@
|
|||||||
|
|
||||||
## 当前恢复点
|
## 当前恢复点
|
||||||
|
|
||||||
- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-010`
|
- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-011`
|
||||||
- 当前阶段：`Phase 5 - Governance Maintenance`
|
- 当前阶段：`Phase 5 - Governance Maintenance`
|
||||||
- 当前焦点：
|
- 当前焦点：
|
||||||
- 将 `Godot` family 的关键恢复摘要回填到 active topic，避免后续 `boot` 默认依赖 archive 才能恢复核心上下文
|
- 继续巡检 `Godot` / `Game` 相关 README、landing page 与 API reference 的 cross-link 是否回漂
|
||||||
- 保留 `documentation-governance-and-refresh` archive 的细节历史，但在 active topic 中记录足够的页面范围、owner 与运行时边界
|
- 保持 `Godot` family 的模块 README、生成器 README 与站内专题页使用同一套 owner / adoption path 叙述
|
||||||
- 继续抽查 README / landing page / API reference 之间的 cross-link 是否出现新的漂移
|
- 仅在发现新的入口漂移时补最小修复，不重复改写已经稳定的 landing page
|
||||||
|
|
||||||
## 当前状态摘要
|
## 当前状态摘要
|
||||||
|
|
||||||
@ -39,6 +39,10 @@
|
|||||||
- `docs/zh-CN/godot/index.md`、`architecture.md`、`scene.md`、`ui.md`、`signal.md`、`extensions.md`、`logging.md` 与 `docs/zh-CN/tutorials/godot-integration.md` 是当前需要保留的核心页面集
|
- `docs/zh-CN/godot/index.md`、`architecture.md`、`scene.md`、`ui.md`、`signal.md`、`extensions.md`、`logging.md` 与 `docs/zh-CN/tutorials/godot-integration.md` 是当前需要保留的核心页面集
|
||||||
- `GFramework.Godot.SourceGenerators` 继续作为 `[GetNode]`、`[BindNodeSignal]`、`AutoLoads` 与 `InputActions` 的 owner；`GFramework.Godot.SourceGenerators.Abstractions` 仍按内部支撑模块处理
|
- `GFramework.Godot.SourceGenerators` 继续作为 `[GetNode]`、`[BindNodeSignal]`、`AutoLoads` 与 `InputActions` 的 owner；`GFramework.Godot.SourceGenerators.Abstractions` 仍按内部支撑模块处理
|
||||||
- `Godot` Scene / UI 采用边界已经稳定：当前没有 `GodotSceneRouter` 或 `GodotUiRouter`；`GodotSceneFactory` 在 provider 缺失时会回退到 `SceneBehaviorFactory`，而 `GodotUiFactory` 仍要求 `IUiPageBehaviorProvider`
|
- `Godot` Scene / UI 采用边界已经稳定：当前没有 `GodotSceneRouter` 或 `GodotUiRouter`；`GodotSceneFactory` 在 provider 缺失时会回退到 `SceneBehaviorFactory`，而 `GodotUiFactory` 仍要求 `IUiPageBehaviorProvider`
|
||||||
|
- `2026-04-23` 的交叉链接巡检新增结论：
|
||||||
|
- `GFramework.Godot/README.md` 仍停留在旧版简略描述，缺少当前包关系、子系统地图、最小接入路径与 `docs/zh-CN` 入口
|
||||||
|
- `GFramework.Godot.SourceGenerators/README.md` 虽有示例，但没有覆盖 `AutoScene`、`AutoUiPage`、`AutoRegisterExportedCollections` 等当前生成器分组，也没有把运行时 / 生成器边界说清
|
||||||
|
- `docs/zh-CN/api-reference/index.md` 的 `Godot` 行此前只把生成器入口指向泛化的 `source-generators/index.md`，不利于从 API 参考直接落到 `Godot` 专题页
|
||||||
- 本轮已完成的治理动作：
|
- 本轮已完成的治理动作：
|
||||||
- 新建 `GFramework.Ecs.Arch.Abstractions/README.md`
|
- 新建 `GFramework.Ecs.Arch.Abstractions/README.md`
|
||||||
- 在根 `README.md` 中补齐 `GFramework.Ecs.Arch.Abstractions` 入口，并声明内部支撑模块 owner
|
- 在根 `README.md` 中补齐 `GFramework.Ecs.Arch.Abstractions` 入口，并声明内部支撑模块 owner
|
||||||
@ -67,6 +71,9 @@
|
|||||||
- 记录当前环境偏差：本会话 `git.exe` 可解析但执行会触发 `Exec format error`，而 plain Linux `git` 会命中 worktree 路径翻译错误，需要显式仓库绑定
|
- 记录当前环境偏差：本会话 `git.exe` 可解析但执行会触发 `Exec format error`，而 plain Linux `git` 会命中 worktree 路径翻译错误，需要显式仓库绑定
|
||||||
- 完成 `Game` family 巡检，确认 `docs/zh-CN/game/config-system.md`、`scene.md`、`ui.md` 与 `docs/zh-CN/source-generators/index.md` 的核心采用说明、包关系与交叉引用仍与当前源码 / README 一致，没有发现需要立刻修正的回漂
|
- 完成 `Game` family 巡检，确认 `docs/zh-CN/game/config-system.md`、`scene.md`、`ui.md` 与 `docs/zh-CN/source-generators/index.md` 的核心采用说明、包关系与交叉引用仍与当前源码 / README 一致，没有发现需要立刻修正的回漂
|
||||||
- 将 `Godot` family 的最小恢复摘要迁回 active topic，保留核心页面集、生成器 owner、Scene / UI 真实边界与归档指针，避免长期治理默认恢复路径继续依赖 archive 明细
|
- 将 `Godot` family 的最小恢复摘要迁回 active topic，保留核心页面集、生成器 owner、Scene / UI 真实边界与归档指针，避免长期治理默认恢复路径继续依赖 archive 明细
|
||||||
|
- 重写 `GFramework.Godot/README.md`，补齐包定位、相邻包关系、子系统地图、最小接入路径与站内文档入口，并明确它不拥有生成器职责
|
||||||
|
- 重写 `GFramework.Godot.SourceGenerators/README.md`，按 `project.godot` 元数据、节点注入 / 信号绑定、行为包装与批量注册四组能力重建入口
|
||||||
|
- 更新 `docs/zh-CN/api-reference/index.md` 的 `Godot` 模块映射，使 API 参考能直接落到 `Godot` 专用生成器专题页，而不是仅回到总览页
|
||||||
|
|
||||||
## Inventory（第一版）
|
## Inventory（第一版）
|
||||||
|
|
||||||
@ -75,7 +82,7 @@
|
|||||||
| `Core` / `Core.Abstractions` | `README / landing / 类型族级 XML inventory 已收口，成员级审计待补齐` | 根 README、模块 README、`docs/zh-CN/core/**`、`docs/zh-CN/abstractions/core-abstractions.md` 已对齐当前目录与类型族基线 | 进入巡检；如有新 API 变更，再追加成员级 XML 审计 |
|
| `Core` / `Core.Abstractions` | `README / landing / 类型族级 XML inventory 已收口，成员级审计待补齐` | 根 README、模块 README、`docs/zh-CN/core/**`、`docs/zh-CN/abstractions/core-abstractions.md` 已对齐当前目录与类型族基线 | 进入巡检；如有新 API 变更，再追加成员级 XML 审计 |
|
||||||
| `Cqrs` / `Cqrs.Abstractions` / `Cqrs.SourceGenerators` | `README / landing / generator topic / 类型族级 XML inventory 已收口，成员级审计待补齐` | `GFramework.Cqrs/README.md`、`GFramework.Cqrs.Abstractions/README.md`、`GFramework.Cqrs.SourceGenerators/README.md`、`docs/zh-CN/core/cqrs.md`、`docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`、`docs/zh-CN/api-reference/index.md` 已对齐当前源码与测试 | 转入巡检；下一波切到 `Game` family 的 XML / 教程链路审计 |
|
| `Cqrs` / `Cqrs.Abstractions` / `Cqrs.SourceGenerators` | `README / landing / generator topic / 类型族级 XML inventory 已收口，成员级审计待补齐` | `GFramework.Cqrs/README.md`、`GFramework.Cqrs.Abstractions/README.md`、`GFramework.Cqrs.SourceGenerators/README.md`、`docs/zh-CN/core/cqrs.md`、`docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`、`docs/zh-CN/api-reference/index.md` 已对齐当前源码与测试 | 转入巡检；下一波切到 `Game` family 的 XML / 教程链路审计 |
|
||||||
| `Game` / `Game.Abstractions` / `Game.SourceGenerators` | `README / landing / abstractions / 类型族级 XML inventory 已收口，成员级审计待补齐` | `GFramework.Game/README.md`、`GFramework.Game.Abstractions/README.md`、`GFramework.Game.SourceGenerators/README.md`、`docs/zh-CN/game/index.md`、`docs/zh-CN/abstractions/game-abstractions.md` 已对齐当前源码与目录基线 | 转入巡检；优先抽查 `config-system`、`scene`、`ui` 与 `source-generators` 交叉链路是否回漂 |
|
| `Game` / `Game.Abstractions` / `Game.SourceGenerators` | `README / landing / abstractions / 类型族级 XML inventory 已收口，成员级审计待补齐` | `GFramework.Game/README.md`、`GFramework.Game.Abstractions/README.md`、`GFramework.Game.SourceGenerators/README.md`、`docs/zh-CN/game/index.md`、`docs/zh-CN/abstractions/game-abstractions.md` 已对齐当前源码与目录基线 | 转入巡检；优先抽查 `config-system`、`scene`、`ui` 与 `source-generators` 交叉链路是否回漂 |
|
||||||
| `Godot` / `Godot.SourceGenerators` | `核心 landing / topic / tutorial 已校验，active topic 已回填最小恢复摘要` | `docs/zh-CN/godot/index.md`、`architecture.md`、`scene.md`、`ui.md`、`signal.md`、`extensions.md`、`logging.md`、`docs/zh-CN/tutorials/godot-integration.md`，以及归档 topic 中的 `Godot` 治理历史 | 进入巡检周期，优先抽查 cross-link 与源码回漂；详细历史继续留在 archive |
|
| `Godot` / `Godot.SourceGenerators` | `README / 生成器 README / landing / topic / tutorial / API reference 入口已重新对齐，成员级 XML 审计不在本轮范围` | `GFramework.Godot/README.md`、`GFramework.Godot.SourceGenerators/README.md`、`docs/zh-CN/godot/index.md`、`architecture.md`、`scene.md`、`ui.md`、`signal.md`、`extensions.md`、`logging.md`、`docs/zh-CN/tutorials/godot-integration.md` | 进入巡检周期，优先观察后续分支是否再次把 README / API 入口写回过时边界 |
|
||||||
| `Ecs.Arch` / `Ecs.Arch.Abstractions` | `README / landing / abstractions / 类型族级 XML inventory 已收口，成员级审计待补齐` | `GFramework.Ecs.Arch/README.md`、`GFramework.Ecs.Arch.Abstractions/README.md`、`docs/zh-CN/ecs/**`、`docs/zh-CN/abstractions/ecs-arch-abstractions.md` 已对齐当前源码与测试 | 转入巡检；后续仅在运行时公共 API 变动时补成员级 XML 细审 |
|
| `Ecs.Arch` / `Ecs.Arch.Abstractions` | `README / landing / abstractions / 类型族级 XML inventory 已收口，成员级审计待补齐` | `GFramework.Ecs.Arch/README.md`、`GFramework.Ecs.Arch.Abstractions/README.md`、`docs/zh-CN/ecs/**`、`docs/zh-CN/abstractions/ecs-arch-abstractions.md` 已对齐当前源码与测试 | 转入巡检；后续仅在运行时公共 API 变动时补成员级 XML 细审 |
|
||||||
| `SourceGenerators.Common` 与 `*.SourceGenerators.Abstractions` | `已判定为内部支撑` | `*.csproj` 明确 `IsPackable=false` | 由所属模块 README 与生成器栏目说明 owner，不建独立采用页 |
|
| `SourceGenerators.Common` 与 `*.SourceGenerators.Abstractions` | `已判定为内部支撑` | `*.csproj` 明确 `IsPackable=false` | 由所属模块 README 与生成器栏目说明 owner，不建独立采用页 |
|
||||||
|
|
||||||
@ -115,7 +122,7 @@
|
|||||||
- 结果：通过；PR `#271` 已关闭，latest reviewed commit 为 `df91d3706ba9db71737e803ef2f40f4841ecbbf1`，当前 `2` 条 open thread 都是已被本地文件满足的陈旧信号，不再构成本轮阻塞
|
- 结果：通过；PR `#271` 已关闭，latest reviewed commit 为 `df91d3706ba9db71737e803ef2f40f4841ecbbf1`，当前 `2` 条 open thread 都是已被本地文件满足的陈旧信号，不再构成本轮阻塞
|
||||||
- 最新构建结论：
|
- 最新构建结论：
|
||||||
- `2026-04-23` `cd docs && bun run build`
|
- `2026-04-23` `cd docs && bun run build`
|
||||||
- 结果：通过；仅保留既有 VitePress 大 chunk warning，无构建失败
|
- 结果：通过；在 `Godot` README / API 入口修复后再次验证通过，仅保留既有 VitePress 大 chunk warning，无构建失败
|
||||||
- 最新恢复治理结论：
|
- 最新恢复治理结论：
|
||||||
- `2026-04-23` 重新读取 `ai-plan/public/archive/documentation-governance-and-refresh/**`
|
- `2026-04-23` 重新读取 `ai-plan/public/archive/documentation-governance-and-refresh/**`
|
||||||
- 结果：通过；确认 `Godot` family 适合把最小恢复摘要迁回 active topic，但不需要把整段归档历史重新放回默认 `boot` 路径
|
- 结果：通过；确认 `Godot` family 适合把最小恢复摘要迁回 active topic，但不需要把整段归档历史重新放回默认 `boot` 路径
|
||||||
@ -124,9 +131,14 @@
|
|||||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`：通过
|
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`：通过
|
||||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/ecs/index.md`：通过
|
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/ecs/index.md`：通过
|
||||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions/ecs-arch-abstractions.md`：通过
|
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions/ecs-arch-abstractions.md`：通过
|
||||||
|
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Godot/README.md`：通过
|
||||||
|
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-code-blocks.sh GFramework.Godot/README.md`：通过
|
||||||
|
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Godot.SourceGenerators/README.md`：通过
|
||||||
|
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-code-blocks.sh GFramework.Godot.SourceGenerators/README.md`：通过
|
||||||
|
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/api-reference/index.md`：通过
|
||||||
|
|
||||||
## 下一步
|
## 下一步
|
||||||
|
|
||||||
1. 继续抽查 README / landing page / API reference 的 cross-link 是否出现新的漂移，优先覆盖 `Godot` 与 `Game` 相关入口
|
1. 继续抽查 `Game` 与 `Godot` 相邻入口，优先看根 `README.md`、`docs/zh-CN/source-generators/index.md` 与教程页之间是否仍有旧 owner 描述
|
||||||
2. 当后续分支再修改 README / docs / 公共 API 时，回到对应 module family 追加 targeted 巡检与验证
|
2. 当后续分支再修改 `Godot` / `Game` family 的 README、docs 或公共 API 时，回到对应模块追加 targeted 巡检与验证
|
||||||
3. 仅在需要阶段级细节时再读取 `documentation-governance-and-refresh` archive，而不是把 archive 重新当作默认 `boot` 入口
|
3. 仅在需要阶段级细节时再读取 `documentation-governance-and-refresh` archive，而不是把 archive 重新当作默认 `boot` 入口
|
||||||
|
|||||||
@ -352,3 +352,46 @@
|
|||||||
|
|
||||||
1. 抽查 `Godot` 与 `Game` 相关 README / landing page / API reference 的 cross-link 是否出现新的漂移
|
1. 抽查 `Godot` 与 `Game` 相关 README / landing page / API reference 的 cross-link 是否出现新的漂移
|
||||||
2. 当后续分支修改相关 README / docs / 公共 API 时，回到对应 module family 追加 targeted 巡检与验证
|
2. 当后续分支修改相关 README / docs / 公共 API 时，回到对应 module family 追加 targeted 巡检与验证
|
||||||
|
|
||||||
|
### 当前恢复点：RP-011
|
||||||
|
|
||||||
|
- 继续按 `boot` 恢复后的默认下一步执行 `Godot` / `Game` cross-link 巡检，并额外补读：
|
||||||
|
- `GFramework.Godot/README.md`
|
||||||
|
- `GFramework.Godot.SourceGenerators/README.md`
|
||||||
|
- `docs/zh-CN/api-reference/index.md`
|
||||||
|
- `docs/zh-CN/godot/index.md`
|
||||||
|
- `docs/zh-CN/source-generators/index.md`
|
||||||
|
- 结合 `GFramework.Godot.csproj`、`GFramework.Godot.SourceGenerators.csproj`、相关测试与 `scan_module_evidence.py` 输出，确认新的漂移点集中在入口 README：
|
||||||
|
- `GFramework.Godot/README.md` 仍是旧版简略说明，没有记录当前包关系、子系统地图、最小接入路径与 `docs/zh-CN` 入口
|
||||||
|
- `GFramework.Godot.SourceGenerators/README.md` 没有覆盖 `AutoScene`、`AutoUiPage`、`AutoRegisterExportedCollections` 这些当前已发布的生成器分组
|
||||||
|
- `docs/zh-CN/api-reference/index.md` 的 `Godot` 映射仍只把生成器入口落到泛化总览页，恢复效率偏低
|
||||||
|
- 因此本轮执行最小修复集：
|
||||||
|
- 重写 `GFramework.Godot/README.md`
|
||||||
|
- 重写 `GFramework.Godot.SourceGenerators/README.md`
|
||||||
|
- 更新 `docs/zh-CN/api-reference/index.md` 的 `Godot` 行
|
||||||
|
|
||||||
|
### 当前决策（RP-011）
|
||||||
|
|
||||||
|
- 这轮不改 `docs/zh-CN/godot/**` landing / topic 页面，因为站内页面本身没有发现新的事实漂移，问题集中在仓库 README 与 API 入口的回退
|
||||||
|
- `GFramework.Godot` README 必须和 `Game` / `Godot` 真实边界一致，明确它不是生成器 owner，也不引入虚构的 router 类型
|
||||||
|
- `GFramework.Godot.SourceGenerators` README 采用“元数据 / 节点注入与信号绑定 / 行为包装 / 批量注册”四段式入口，避免读者只看到旧的三项能力
|
||||||
|
- API 参考页对 `Godot` 生成器入口直接给出专题页链接，而不是仅要求读者再从总览页二次分流
|
||||||
|
|
||||||
|
### 当前验证（RP-011）
|
||||||
|
|
||||||
|
- 模块扫描：
|
||||||
|
- `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Godot`：通过
|
||||||
|
- `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Godot.SourceGenerators`：通过
|
||||||
|
- 文档校验：
|
||||||
|
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Godot/README.md`：通过
|
||||||
|
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-code-blocks.sh GFramework.Godot/README.md`：通过
|
||||||
|
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Godot.SourceGenerators/README.md`：通过
|
||||||
|
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-code-blocks.sh GFramework.Godot.SourceGenerators/README.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，无构建失败
|
||||||
|
|
||||||
|
### 下一步
|
||||||
|
|
||||||
|
1. 继续抽查根 `README.md`、`docs/zh-CN/source-generators/index.md` 与 `docs/zh-CN/tutorials/godot-integration.md` 是否仍把 `Godot` owner 写回旧边界
|
||||||
|
2. 当后续分支继续修改 `Game` / `Godot` family 入口时，沿用当前 README -> landing -> API reference 的最小修复顺序
|
||||||
|
|||||||
@ -32,7 +32,7 @@ description: GFramework 的 API 阅读入口，按模块映射 README、专题
|
|||||||
| `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) | 架构入口、生命周期、命令 / 查询 / 事件 / 状态 / 资源 / 日志 / 配置 / 并发契约 |
|
| `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/cqrs-handler-registry-generator.md`](../source-generators/cqrs-handler-registry-generator.md) | request / notification / handler / pipeline / registry / fallback contract |
|
| `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/cqrs-handler-registry-generator.md`](../source-generators/cqrs-handler-registry-generator.md) | request / notification / handler / pipeline / registry / fallback 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、存储、序列化契约 |
|
| `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 适配、资源 / 存储 / 日志接入 |
|
| `Godot` / `Godot.SourceGenerators` | `GFramework.Godot/README.md`、`GFramework.Godot.SourceGenerators/README.md` | [`../godot/index.md`](../godot/index.md)、[`../source-generators/godot-project-generator.md`](../source-generators/godot-project-generator.md)、[`../source-generators/get-node-generator.md`](../source-generators/get-node-generator.md)、[`../source-generators/bind-node-signal-generator.md`](../source-generators/bind-node-signal-generator.md) | 节点扩展、场景 / UI 适配、配置 / 存储 / 设置接线、Godot 生成器入口 |
|
||||||
| `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 模块契约、系统适配、配置对象和运行时装配边界 |
|
| `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，还是先看教程
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user