GFramework/GFramework.Godot

GFramework.Godot

GFramework.Godot 是 GFramework 在 Godot 宿主侧的运行时适配包。

它建立在 GFramework.Game、GFramework.Game.Abstractions 与 GFramework.Core.Abstractions 之上，把框架已有的架构、 Scene / UI、配置、存储、设置、日志与协程能力接到 Node、SceneTree、PackedScene、FileAccess 与 AudioServer 等 Godot 运行时对象上。

如果你需要的是 [GetNode]、[BindNodeSignal]、AutoLoads 或 InputActions 这类编译期能力，请改为同时安装 GFramework.Godot.SourceGenerators。这些能力不属于本包。

包定位

当前包解决的是 Godot 运行时接线，而不是重新定义一套 Godot 专属框架：

• 架构生命周期与场景树绑定：AbstractArchitecture、ArchitectureAnchor
• 节点运行时辅助：WaitUntilReadyAsync()、AddChildXAsync()、QueueFreeX()、UnRegisterWhenNodeExitTree(...)
• Godot 风格的 Scene / UI 工厂与 registry：GodotSceneFactory、GodotUiFactory
• Godot 特化的配置、存储与设置实现：GodotYamlConfigLoader、GodotFileStorage、GodotAudioSettings
• 宿主侧辅助能力：Signal(...) fluent API、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 运行时适配：

dotnet add package GeWuYou.GFramework
dotnet add package GeWuYou.GFramework.Godot

如果你还需要 project.godot 强类型入口、节点字段注入和信号绑定，再额外安装：

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/architecture.md
• 场景系统：docs/zh-CN/godot/scene.md
• UI 系统：docs/zh-CN/godot/ui.md
• 节点扩展：docs/zh-CN/godot/extensions.md
• 信号系统：docs/zh-CN/godot/signal.md
• 日志系统：docs/zh-CN/godot/logging.md
• 集成教程：docs/zh-CN/tutorials/godot-integration.md
• 生成器入口：../GFramework.Godot.SourceGenerators/README.md

什么时候不该把它当成主入口

以下场景更适合先回到其他包：

• 只需要 Scene / UI / 配置契约，不需要 Godot 宿主：
  • 选 GFramework.Game.Abstractions
• 需要默认运行时实现，但暂时不接 Godot：
  • 选 GFramework.Game
• 需要的是 project.godot 元数据、节点字段注入或编译期样板：
  • 选 GFramework.Godot.SourceGenerators