mirror of https://github.com/GeWuYou/GFramework.git synced 2026-05-07 00:39:00 +08:00

gewuyou 5d436694f8 docs(godot): 收口 Godot 入口与架构文档

- 更新 Godot landing page，使包关系、最小接入路径与运行时边界回到源码与测试契约

- 重写 Godot architecture 页面，明确锚点生命周期、模块挂接顺序与 IGodotModule 契约边界

- 更新 documentation-governance topic 的 RP-014 跟踪与验证记录，标记下一轮收口目标

2026-04-22 12:50:05 +08:00

6.9 KiB

Raw Blame History

title, description

title	description
Godot 运行时集成	以当前 GFramework.Godot 源码、测试与 CoreGrid 接线为准，说明 Godot 运行时包的定位、最小接入路径和文档入口。

Godot 运行时集成

模块定位

GFramework.Godot 是 GFramework 在 Godot 侧的运行时适配层。它负责把框架已有的 Core / Game 能力接到 Godot 的 Node、SceneTree、PackedScene、FileAccess 和 AudioServer 上，而不是重新定义一套独立架构。

当前仓库里仍然成立的 Godot 运行时职责，主要集中在这些方向：

架构生命周期与场景树绑定：AbstractArchitecture、ArchitectureAnchor
节点运行时辅助：WaitUntilReadyAsync()、AddChildXAsync()、QueueFreeX()、UnRegisterWhenNodeExitTree(...)
Godot 风格的 Scene / UI 工厂与 registry：GodotSceneFactory、GodotUiFactory
Godot 特化的存储、设置与配置加载：GodotFileStorage、GodotAudioSettings、GodotYamlConfigLoader
少量面向运行时交互的扩展：Signal(...) fluent API、暂停处理、富文本效果、协程时间源

它不是 [GetNode]、[BindNodeSignal]、AutoLoads、InputActions 的来源。这些能力属于 GFramework.Godot.SourceGenerators。

包关系

GeWuYou.GFramework：聚合运行时包，提供 Core / Game 常用能力
GeWuYou.GFramework.Godot：当前页面对应的 Godot 运行时适配层
GeWuYou.GFramework.Core.SourceGenerators：[ContextAware]、[GetModel]、[GetSystem] 等 Core 侧生成器
GeWuYou.GFramework.Godot.SourceGenerators：project.godot 元数据、[GetNode]、[BindNodeSignal]

从当前 GFramework.Godot.csproj 看，Godot 运行时包直接依赖：

GFramework.Game
GFramework.Game.Abstractions
GFramework.Core.Abstractions
GodotSharp

这意味着它更像是“把现有框架能力接到 Godot 宿主”的桥接层，而不是单独的 gameplay 框架。

最小接入路径

1. 先区分运行时包和生成器包

如果你只需要 Godot 运行时辅助，可以先安装：

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

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

dotnet add package GeWuYou.GFramework.Core.SourceGenerators
dotnet add package GeWuYou.GFramework.Godot.SourceGenerators

只装运行时包时，不会生成 AutoLoads、InputActions、__InjectGetNodes_Generated() 或 __BindNodeSignals_Generated()。

2. 让架构继续负责注册，让 Godot 节点负责场景接线

ai-libs/CoreGrid 当前的真实做法，是让架构继承 AbstractArchitecture，但模块注册依然使用普通的 InstallModule(...)：

using GFramework.Core.Abstractions.Architectures;
using GFramework.Core.Abstractions.Environment;
using GFramework.Godot.Architectures;

namespace MyGame.Scripts.Core;

public sealed class GameArchitecture(
    IArchitectureConfiguration configuration,
    IEnvironment environment)
    : AbstractArchitecture(configuration, environment)
{
    protected override void InstallModules()
    {
        InstallModule(new UtilityModule());
        InstallModule(new ModelModule());
        InstallModule(new GameplayModule());
        InstallModule(new SystemModule());
    }
}

也就是说，GFramework.Godot 的默认接入点不是“把所有注册都改成 Godot 模块”，而是“保持现有架构注册方式，只把需要 Godot 生命周期协作的部分接到场景树上”。

3. 只在真的需要 Godot 节点挂接时使用 `InstallGodotModule(...)`

InstallGodotModule(...) 适合这类模块：

模块自身暴露一个 Node
模块希望在架构锚点就绪后被挂到场景树
模块需要在 OnAttach(...) / OnDetach() 里处理 Godot 生命周期副作用

如果模块只是注册 Model、System、Utility，继续使用普通 InstallModule(...) 更符合当前消费者接法。

4. 节点脚本用运行时辅助，静态样板交给生成器

当前最常见的运行时入口是：

UnRegisterWhenNodeExitTree(this Node node)：把框架事件解绑挂到节点退出树
WaitUntilReadyAsync()：等待节点真正进入场景树
AddChildXAsync()：添加子节点后等待 ready
Signal(...)：对 GodotObject.Connect(...) 的 fluent 包装

using GFramework.Godot.Extensions;
using GFramework.Godot.Extensions.Signal;
using Godot;

public partial class SettingsPanel : Control
{
    public override async void _Ready()
    {
        var button = GetNode<Button>("%ApplyButton");
        await button.WaitUntilReadyAsync();

        button.Signal(Button.SignalName.Pressed)
              .To(Callable.From(OnApplyPressed));
    }

    private void OnApplyPressed()
    {
    }
}

字段注入、project.godot 解析和 signal 自动绑订仍应交给生成器，不要把它们写成 GFramework.Godot 运行时包的默认职责。

关键入口

架构锚点与模块挂接：Godot 架构集成
Scene / PackedScene 工厂与行为封装：Godot 场景系统
UI page 行为、layer 语义与工厂：Godot UI 系统
Godot 文件路径与持久化适配：Godot 存储系统
音频、图形与本地化设置接线：Godot 设置系统
Signal(...) fluent API 与动态连接边界：Godot 信号系统

如果你要核对项目级接线，而不是运行时 API，本页之后优先看：

当前边界

AbstractArchitecture 会在 SceneTree.Root 下创建 ArchitectureAnchor，并在锚点退出场景树时触发架构销毁观察流程
InstallGodotModule(...) 会先检查锚点是否存在；测试覆盖了“锚点缺失时直接抛 InvalidOperationException，且不会执行 module.Install(...)”这一路径
Signal(...) 是当前 fluent API 入口，不是旧文档里的 CreateSignalBuilder(...)
NodeExtensions 目前保留的是 FindChildX<T>()、GetParentX<T>()、GetOrCreateNode<T>()、QueueFreeX()、 FreeX()、WaitUntilReadyAsync() 这一类运行时辅助；不要再把它描述成一个“默认覆盖所有 Godot 节点操作”的大而全层
Scene / UI 工厂依赖显式 registry 与 PackedScene 资源，不存在“运行时自动扫描所有场景并完成统一注册”的当前契约
[GetNode]、[BindNodeSignal]、AutoLoads、InputActions 来自 GFramework.Godot.SourceGenerators，不属于本包

6.9 KiB Raw Blame History Unescape Escape