From 7dafec72be83c068e9aa0000eee479e3fc4db777 Mon Sep 17 00:00:00 2001 From: GeWuYou <95328647+GeWuYou@users.noreply.github.com> Date: Tue, 14 Apr 2026 08:22:28 +0800 Subject: [PATCH] =?UTF-8?q?docs(docs):=20=E6=B7=BB=E5=8A=A0=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E9=85=8D=E7=BD=AE=E5=92=8CAPI=E5=8F=82=E8=80=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增.vitepress/config.mts配置文件，包含本地搜索、代码块保护等功能 - 添加API参考文档，涵盖核心架构、事件系统、属性系统等完整API - 添加源码生成器文档，介绍Log、ContextAware、EnumExtensions等生成器用法 - 配置多语言导航和侧边栏结构，完善文档站点设置 - 添加代码示例和使用指南，提供完整的框架使用参考 --- AGENTS.md | 21 +++ docs/.vitepress/config.mts | 1 + docs/zh-CN/api-reference/index.md | 21 +-- .../godot-project-generator.md | 169 ++++++++++++++++++ docs/zh-CN/source-generators/index.md | 60 +++++++ docs/zh-CN/tutorials/godot-integration.md | 21 ++- 6 files changed, 282 insertions(+), 11 deletions(-) create mode 100644 docs/zh-CN/source-generators/godot-project-generator.md diff --git a/AGENTS.md b/AGENTS.md index 8e2d97b3..c63a2bfa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,6 +19,27 @@ All AI agents and contributors must follow these rules when writing, reviewing, - After resolving the host Windows Git path, prefer an explicit session-local binding for subsequent commands so the shell does not fall back to Linux `/usr/bin/git` later in the same WSL session. +## Subagent Usage Rules + +- Use subagents only when the task is complex, the context is likely to grow too large, or the work can be split into + independent parallel subtasks. +- The main agent MUST identify the critical path first. Do not delegate the immediate blocking task if the next local + step depends on that result. +- Use `explorer` subagents for read-only discovery, comparison, tracing, and narrow codebase questions. +- Use `worker` subagents only for bounded implementation tasks with an explicit file or module ownership boundary. +- Every delegation MUST specify: + - the concrete objective + - the expected output format + - the files or subsystem the subagent owns + - any constraints about tests, diagnostics, or compatibility +- Subagents are not allowed to revert or overwrite unrelated changes from the user or other agents. They must adapt to + concurrent work instead of assuming exclusive ownership of the repository. +- Prefer lightweight models such as `gpt-5.1-codex-mini` for narrow exploration, indexing, and comparison tasks. +- Prefer stronger models such as `gpt-5.4` for cross-module design work, non-trivial refactors, and tasks that require + higher confidence reasoning. +- The main agent remains responsible for reviewing and integrating subagent output. Unreviewed subagent conclusions do + not count as final results. + ## Commenting Rules (MUST) All generated or modified code MUST include clear and meaningful comments where required by the rules below. diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 3b93e141..bcac727e 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -251,6 +251,7 @@ export default defineConfig({ { text: 'ContextAware 生成器', link: '/zh-CN/source-generators/context-aware-generator' }, { text: 'Priority 生成器', link: '/zh-CN/source-generators/priority-generator' }, { text: 'Context Get 注入', link: '/zh-CN/source-generators/context-get-generator' }, + { text: 'Godot 项目元数据', link: '/zh-CN/source-generators/godot-project-generator' }, { text: 'GetNode 生成器 (Godot)', link: '/zh-CN/source-generators/get-node-generator' }, { text: 'BindNodeSignal 生成器 (Godot)', link: '/zh-CN/source-generators/bind-node-signal-generator' } ] diff --git a/docs/zh-CN/api-reference/index.md b/docs/zh-CN/api-reference/index.md index b491cc5a..6ecbafe8 100644 --- a/docs/zh-CN/api-reference/index.md +++ b/docs/zh-CN/api-reference/index.md @@ -452,16 +452,17 @@ Godot 引擎集成模块。 #### 常用 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) | -| `AutoRegisterExportedCollectionsAttribute` | 为宿主类开启导出集合批量注册生成 | [AutoRegisterExportedCollections 生成器](../source-generators/auto-register-exported-collections-generator.md) | -| `RegisterExportedCollectionAttribute` | 指定集合与注册器成员的映射关系 | [AutoRegisterExportedCollections 生成器](../source-generators/auto-register-exported-collections-generator.md) | +| 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) | ## 常见用法示例 diff --git a/docs/zh-CN/source-generators/godot-project-generator.md b/docs/zh-CN/source-generators/godot-project-generator.md new file mode 100644 index 00000000..96bc19b1 --- /dev/null +++ b/docs/zh-CN/source-generators/godot-project-generator.md @@ -0,0 +1,169 @@ +# Godot 项目元数据生成器 + +> 从 `project.godot` 生成 AutoLoad 与 Input Action 的强类型访问入口。 + +## 概述 + +`GFramework.Godot.SourceGenerators` 会读取 Godot 项目根目录下的 `project.godot`，并把其中最常用的项目级元数据暴露为稳定的编译期 +API。 + +当前覆盖： + +- `[autoload]` 段：生成 `GFramework.Godot.Generated.AutoLoads` +- `[input]` 段：生成 `GFramework.Godot.Generated.InputActions` + +这项能力的目标不是替代场景级生成器，而是把 Godot 工程配置和 C# 代码之间的字符串约定收敛到编译期。 + +## 接入方式 + +### NuGet 引用 + +当项目通过 NuGet 引用 `GeWuYou.GFramework.Godot.SourceGenerators` 时，生成器会默认把项目根目录下的 `project.godot` 加入 +`AdditionalFiles`。 + +如需覆盖默认路径，可以设置： + +```xml + + project.godot + +``` + +### 仓库内直接引用生成器 + +如果你通过 `ProjectReference(OutputItemType=Analyzer)` 直接引用生成器项目，则需要手动加入： + +```xml + + + +``` + +## AutoLoad 访问层 + +### 基础行为 + +假设 `project.godot` 中声明了： + +```ini +[autoload] +GameServices="*res://autoload/game_services.tscn" +AudioBus="*res://autoload/audio_bus.gd" +``` + +生成器会产出： + +```csharp +using GFramework.Godot.Generated; + +var gameServices = AutoLoads.GameServices; + +if (AutoLoads.TryGetAudioBus(out var audioBus)) +{ +} +``` + +- 对于能唯一映射到 C# 节点类型的条目，属性会是强类型的 +- 对于无法映射或对应非 C# 脚本的条目，属性会退化为 `Godot.Node` +- 生成器通过 `Godot.Engine.GetMainLoop()` 与当前 `SceneTree.Root` 解析 `/root/` 节点 + +### 显式映射 + +当 AutoLoad 名称无法仅靠类名唯一推断时，可以使用 `[AutoLoad]` 明确指定： + +```csharp +using GFramework.Godot.SourceGenerators.Abstractions; +using Godot; + +[AutoLoad("GameServices")] +public partial class GameServices : Node +{ +} +``` + +规则如下： + +- 显式 `[AutoLoad]` 映射优先于隐式类名推断 +- 标记了 `[AutoLoad]` 的类型必须继承 `Godot.Node` +- 若多个类型映射到同一个 AutoLoad，生成器会报告诊断，并退化为 `Godot.Node` 访问器，直到映射唯一 + +## Input Action 常量 + +### 基础行为 + +假设 `project.godot` 中有： + +```ini +[input] +move_up={ +} +ui_cancel={ +} +``` + +生成器会产出： + +```csharp +using GFramework.Godot.Generated; + +if (Input.IsActionJustPressed(InputActions.MoveUp)) +{ +} +``` + +转换规则： + +- `move_up` -> `MoveUp` +- `ui_cancel` -> `UiCancel` +- 非法字符会被清理后再转换为 PascalCase +- 如果多个动作名落到同一个标识符，生成器会追加稳定数字后缀，例如 `MoveUp_2` + +## 与现有 Godot 生成器的关系 + +这项能力和现有的场景级生成器是互补的： + +- `AutoLoads` / `InputActions` 解决的是项目级元数据访问 +- `[GetNode]` 解决的是场景节点引用注入 +- `[BindNodeSignal]` 解决的是节点事件订阅样板 + +推荐组合方式： + +```csharp +using GFramework.Godot.Generated; +using GFramework.Godot.SourceGenerators.Abstractions; +using Godot; + +public partial class MainHud : Control +{ + [GetNode] + private Button _startButton = null!; + + public override void _Ready() + { + __InjectGetNodes_Generated(); + + if (Input.IsActionPressed(InputActions.UiCancel)) + { + } + + var services = AutoLoads.GameServices; + } +} +``` + +## 诊断与约束 + +当前会重点报告以下问题： + +- `[AutoLoad]` 标记在非 `Godot.Node` 类型上 +- 多个类型映射到同一个 AutoLoad 名称 +- 不同 AutoLoad 名称或 Input Action 名称在清洗后发生标识符冲突 +- `project.godot` 内部重复声明同名 AutoLoad 或 Input Action + +这些诊断的目的不是阻断所有生成，而是在可能的情况下保留稳定输出，同时把不确定性显式暴露出来。 + +## 相关文档 + +- [GetNode 生成器](./get-node-generator) +- [BindNodeSignal 生成器](./bind-node-signal-generator) +- [Godot 集成教程](../tutorials/godot-integration) diff --git a/docs/zh-CN/source-generators/index.md b/docs/zh-CN/source-generators/index.md index 60aada08..8fd91e66 100644 --- a/docs/zh-CN/source-generators/index.md +++ b/docs/zh-CN/source-generators/index.md @@ -16,6 +16,7 @@ GFramework.SourceGenerators 是 GFramework 框架的源代码生成器包，通 - [Priority 属性生成器](#priority-属性生成器) - [Context Get 注入生成器](#context-get-注入生成器) - [AutoRegisterModule 生成器](#autoregistermodule-生成器) +- [Godot 项目元数据生成](#godot-项目元数据生成) - [GetNode 生成器 (Godot)](#getnode-生成器) - [BindNodeSignal 生成器 (Godot)](#bindnodesignal-生成器) - [AutoUiPage 生成器 (Godot)](#autouipage-生成器) @@ -52,6 +53,7 @@ GFramework.SourceGenerators 利用 Roslyn 源代码生成器技术，在编译 ### Godot 专用生成器 +- **Godot 项目元数据生成 (Godot)**：从 `project.godot` 生成 AutoLoad 与 Input Action 的强类型访问入口 - **[GetNode] 属性 (Godot)**：自动获取 Godot 节点引用，支持多种查找模式 - **[BindNodeSignal] 属性 (Godot)**：自动生成 Godot 节点信号绑定与解绑逻辑 - **[AutoUiPage] 属性 (Godot)**：自动生成 UI 页面行为包装与页面 Key @@ -435,6 +437,64 @@ public enum PlayerState | GenerateIsMethods | bool | true | 是否为每个枚举值生成 IsX 方法 | | GenerateIsInMethod | bool | true | 是否生成 IsIn 方法 | +## Godot 项目元数据生成 + +Godot 项目元数据生成器会读取 `project.godot`，把项目级配置转换为稳定的编译期 API。 + +当前生成两个统一入口： + +- `GFramework.Godot.Generated.AutoLoads` +- `GFramework.Godot.Generated.InputActions` + +默认情况下，NuGet 包引用会自动把项目根目录下的 `project.godot` 加入 `AdditionalFiles`。如果你是在仓库内通过 analyzer +形式直接引用生成器，则需要手动加入： + +```xml + + + +``` + +### AutoLoad 映射 + +当某个 AutoLoad 不能仅靠类名唯一推断到 C# 节点类型时，可以使用 `[AutoLoad]` 指定映射： + +```csharp +using GFramework.Godot.SourceGenerators.Abstractions; +using Godot; + +[AutoLoad("GameServices")] +public partial class GameServices : Node +{ +} +``` + +生成后可以直接使用： + +```csharp +using GFramework.Godot.Generated; + +var services = AutoLoads.GameServices; + +if (AutoLoads.TryGetAudioBus(out var audioBus)) +{ +} +``` + +### Input Action 常量 + +`[input]` 段会被转换为强类型常量： + +```csharp +using GFramework.Godot.Generated; + +if (Input.IsActionPressed(InputActions.MoveUp)) +{ +} +``` + +完整说明请见：[Godot 项目元数据生成器](./godot-project-generator) + ## GetNode 生成器 GetNode 生成器为标记了 `[GetNode]` 特性的字段自动生成 Godot 节点获取代码，无需手动调用 `GetNode()` 方法。 diff --git a/docs/zh-CN/tutorials/godot-integration.md b/docs/zh-CN/tutorials/godot-integration.md index d1d90d93..b9352ac8 100644 --- a/docs/zh-CN/tutorials/godot-integration.md +++ b/docs/zh-CN/tutorials/godot-integration.md @@ -14,6 +14,25 @@ ## Godot 特定功能 +### 0. project.godot 编译期接入 + +如果项目引用了 `GFramework.Godot.SourceGenerators`，现在可以直接把 `project.godot` 中的 AutoLoad 与 Input Action 暴露为强类型 +API： + +```csharp +using GFramework.Godot.Generated; + +var services = AutoLoads.GameServices; + +if (Input.IsActionPressed(InputActions.MoveUp)) +{ +} +``` + +这项能力适合和 `[GetNode]`、`[BindNodeSignal]` 一起使用：前者解决项目级配置入口，后两者解决场景级节点和事件样板。 + +详细说明见：[Godot 项目元数据生成器](../source-generators/godot-project-generator) + ### 1. 节点生命周期绑定 GFramework.Godot 提供了与 Godot 节点生命周期的无缝集成，确保框架初始化与 Godot 场景树同步。 @@ -1335,4 +1354,4 @@ public class GodotPerformanceTests --- **教程版本**: 1.0.0 -**更新日期**: 2026-01-12 \ No newline at end of file +**更新日期**: 2026-01-12