GFramework/docs/zh-CN/godot/scene.md

title, description

title	description
Godot 场景系统	以当前 GFramework.Godot 源码、Game 场景契约与 CoreGrid 接线为准，说明 PackedScene 场景工厂、行为包装和最小接入路径。

Godot 场景系统

GFramework.Godot 在场景这一层负责的是 Godot runtime 适配，而不是再提供一个 Godot 专属 router。

当前真正参与场景接线的核心类型是：

• IGodotSceneRegistry / GodotSceneRegistry
• GodotSceneFactory
• SceneBehaviorFactory
• SceneBehaviorBase<T> 及其 Node2D / Node3D / Control / Generic 实现
• 项目侧实现的 ISceneRoot
• 项目侧继承 SceneRouterBase 的 router

也就是说，Godot 集成页的重点不是“再造一套场景导航 API”，而是把 PackedScene、Node 和 GFramework.Game 的 ISceneRouter / ISceneBehavior 契约接起来。

当前公开入口

IGodotSceneRegistry

Godot 侧的场景资源表，底层是 IAssetRegistry<PackedScene>。它只负责：

• sceneKey -> PackedScene 映射
• 让 GodotSceneFactory 能按 key 实例化场景

框架当前不会自动扫描项目里的 .tscn 文件并填充 registry。

GodotSceneFactory

GodotSceneFactory.Create(string sceneKey) 的当前行为很明确：

1. 从 IGodotSceneRegistry 取出 PackedScene
2. 调用 Instantiate()
3. 如果节点实现了 ISceneBehaviorProvider，优先返回 provider.GetScene()
4. 否则回退到 SceneBehaviorFactory.Create(node, sceneKey)

这和旧文档里“必须有 Godot 专属 router / 专属 scene provider 才能工作”的说法不同。当前源码允许两条路径：

• 显式 provider：项目自己决定行为对象
• 自动包装：按节点类型回退到默认 behavior

SceneBehaviorBase<T>

SceneBehaviorBase<T> 是当前 Godot 场景行为包装基类。它把 ISceneBehavior 的生命周期接到 Node 上：

• OnLoadAsync
• OnEnterAsync
• OnPauseAsync
• OnResumeAsync
• OnExitAsync
• OnUnloadAsync

如果 owner 还实现了 IScene，这些阶段会继续转发到业务节点；如果没有实现 IScene，默认 behavior 仍会处理 Godot 节点的 process 开关和 QueueFreeX() 释放。

SceneBehaviorFactory

自动包装的选择规则来自当前实现：

• Node2D -> Node2DSceneBehavior
• Node3D -> Node3DSceneBehavior
• Control -> ControlSceneBehavior
• 其他 Node -> GenericSceneBehavior

这意味着 Godot runtime 确实能“自动给节点补一个 behavior”，但它不会替你补项目侧 router、root 或 registry。

最小接入路径

推荐按下面顺序接入。

1. 继续在项目层保留自己的 router

GFramework.Godot 当前没有 GodotSceneRouter 类型。消费者项目的实际做法，是在项目层继承 GFramework.Game.Scene.SceneRouterBase。

ai-libs/CoreGrid 的 router 就是这样：

using global::CoreGrid.global;
using LoggingTransitionHandler = GFramework.Game.Scene.Handler.LoggingTransitionHandler;

namespace CoreGrid.scripts.core.scene;

public partial class SceneRouter : SceneRouterBase
{
    [GetUtility] private IGodotSceneRegistry _sceneRegistry = null!;

    public Node? SceneRoot => Root as Node;

    protected override void RegisterHandlers()
    {
        __InjectContextBindings_Generated();
        RegisterHandler(new LoggingTransitionHandler());
        RegisterAroundHandler(
            new SceneTransitionAnimationHandler(() => SceneTransitionManager.Instance!, _sceneRegistry.GetAll()));
    }
}

这里可以看到，Godot 适配点在 factory / registry / root / transition handler 上，而 router 仍然是项目类。

2. 注册 IGodotSceneRegistry 与 ISceneFactory

最小 wiring 需要把 registry 和 factory 装进架构：

using GFramework.Game.Abstractions.Scene;
using GFramework.Godot.Scene;
using Godot;

public sealed class GameSceneRegistry : GodotSceneRegistry
{
    public GameSceneRegistry()
    {
        Register(nameof(SceneKey.MainMenu), GD.Load<PackedScene>("res://scenes/main_menu.tscn"));
        Register(nameof(SceneKey.Gameplay), GD.Load<PackedScene>("res://scenes/gameplay.tscn"));
    }
}

architecture.RegisterUtility<IGodotSceneRegistry>(new GameSceneRegistry());
architecture.RegisterUtility<ISceneFactory>(new GodotSceneFactory());
architecture.RegisterSystem(new SceneRouter());

项目用什么 key 类型、资源目录或配置表都可以，但最终要能落到 sceneKey -> PackedScene。

3. 提供 ISceneRoot

SceneRouterBase 只负责切换编排，真正把场景节点挂到 Godot 场景树的是项目自己的 ISceneRoot。

CoreGrid 的 SceneRoot 当前做了两件关键事：

• 在 _Ready() 时调用 _sceneRouter.BindRoot(this)
• 在 AddScene / RemoveScene 里把 scene.Original 当作 Node 挂入或移出树

最小形态可以写成：

public sealed class SceneRoot : Node2D, ISceneRoot
{
    [GetSystem] private ISceneRouter _sceneRouter = null!;

    public override void _Ready()
    {
        __InjectContextBindings_Generated();
        _sceneRouter.BindRoot(this);
    }

    public void AddScene(ISceneBehavior scene)
    {
        if (scene.Original is not Node node)
            throw new InvalidOperationException("SceneBehavior must inherit Godot Node.");

        if (node.GetParent() == null)
            AddChild(node);
    }

    public void RemoveScene(ISceneBehavior scene)
    {
        if (scene.Original is Node node && node.GetParent() == this)
            RemoveChild(node);
    }
}

4. 让场景节点提供 behavior

当前有两种可行方式。

方式 A：实现 ISceneBehaviorProvider

如果你想显式控制 behavior 类型，直接实现 GetScene()：

public partial class GameplayRoot : Node2D, ISceneBehaviorProvider, IScene
{
    private ISceneBehavior? _scene;

    public ISceneBehavior GetScene()
    {
        return _scene ??= SceneBehaviorFactory.Create(this, nameof(SceneKey.Gameplay));
    }

    public ValueTask OnLoadAsync(ISceneEnterParam? param)
    {
        return ValueTask.CompletedTask;
    }

    public ValueTask OnEnterAsync()
    {
        return ValueTask.CompletedTask;
    }

    public ValueTask OnPauseAsync()
    {
        return ValueTask.CompletedTask;
    }

    public ValueTask OnResumeAsync()
    {
        return ValueTask.CompletedTask;
    }

    public ValueTask OnExitAsync()
    {
        return ValueTask.CompletedTask;
    }

    public ValueTask OnUnloadAsync()
    {
        return ValueTask.CompletedTask;
    }
}

方式 B：用 [AutoScene] 让生成器补样板

当前更贴近真实消费者 wiring 的方式，是让 GFramework.Godot.SourceGenerators 生成 SceneKeyStr 和 GetScene()：

using GFramework.Game.Abstractions.Scene;
using GFramework.Godot.SourceGenerators.Abstractions.UI;
using Godot;

[AutoScene(nameof(SceneKey.Gameplay))]
public partial class GameplayRoot : Node2D, ISceneBehaviorProvider, IScene
{
    public ValueTask OnLoadAsync(ISceneEnterParam? param)
    {
        return ValueTask.CompletedTask;
    }

    public ValueTask OnEnterAsync()
    {
        return ValueTask.CompletedTask;
    }

    public ValueTask OnPauseAsync()
    {
        return ValueTask.CompletedTask;
    }

    public ValueTask OnResumeAsync()
    {
        return ValueTask.CompletedTask;
    }

    public ValueTask OnExitAsync()
    {
        return ValueTask.CompletedTask;
    }

    public ValueTask OnUnloadAsync()
    {
        return ValueTask.CompletedTask;
    }
}

生成器当前会补出与源码一致的 GetScene()：

public ISceneBehavior GetScene()
{
    return __autoSceneBehavior_Generated ??= SceneBehaviorFactory.Create(this, SceneKeyStr);
}

要注意两点：

• [AutoScene] 只生成方法和 key，不会替你自动补 : ISceneBehaviorProvider
• IScene 仍然是业务生命周期契约；不实现它时，默认 behavior 只会保留基础节点切换语义

5. 从业务代码发起导航

一旦 registry、factory、router、root 都装好，导航入口仍然是 ISceneRouter：

await sceneRouter.ReplaceAsync(nameof(SceneKey.MainMenu));
await sceneRouter.ReplaceAsync(nameof(SceneKey.Gameplay), new GameplayEnterParam());
await sceneRouter.PushAsync(nameof(SceneKey.PauseMenu));
await sceneRouter.PopAsync();

当前边界

没有 GodotSceneRouter

仓库当前不存在 GodotSceneRouter 类型。旧文档里把它写成默认入口是失真的；实际入口仍然是项目侧继承 SceneRouterBase 的 router。

没有自动注册所有场景

当前运行时只认识你注册进 IGodotSceneRegistry 的 PackedScene。它不会扫描目录、不会从脚本类型自动反推出注册表。

provider 是“优先路径”，不是“唯一路径”

GodotSceneFactory 会优先使用 ISceneBehaviorProvider，但没有 provider 时仍会按节点类型自动包装。这个行为和 UI 系统不同； UI 工厂当前没有同等的自动回退。

root 仍然是项目职责

ISceneRoot 的实现决定：

• 节点挂到哪里
• 移除时如何释放
• 是否保留额外的当前视图引用

Godot runtime 不会替项目生成统一的 root 节点。

继续阅读

1. Godot 运行时集成
2. Godot 架构集成
3. Game 场景系统
4. AutoScene 生成器