GFramework/docs/zh-CN/source-generators/auto-scene-generator.md

AutoScene 生成器

为场景根节点生成 GetScene() 样板，统一场景键声明与行为包装。

概述

AutoScene 面向 GFramework 的场景路由与场景行为包装场景。 对于一个可切换、可识别的场景根节点，开发者通常需要重复声明：

• 场景 Key
• 场景行为缓存字段
• GetScene() 包装方法

AutoScene 会在编译期生成这些固定样板。 该特性当前位于 GFramework.Godot.SourceGenerators.Abstractions.UI 命名空间。

基础使用

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

[AutoScene(nameof(SceneKey.Gameplay))]
public partial class GameplayRoot : Node2D
{
    public override void _Ready()
    {
        _ = GetScene();
    }
}

生成的代码

// <auto-generated />
#nullable enable

partial class GameplayRoot
{
    private global::GFramework.Game.Abstractions.Scene.ISceneBehavior? __autoSceneBehavior_Generated;

    public static string SceneKeyStr => "Gameplay";

    public global::GFramework.Game.Abstractions.Scene.ISceneBehavior GetScene()
    {
        return __autoSceneBehavior_Generated
            ??= global::GFramework.Godot.Scene.SceneBehaviorFactory.Create(this, SceneKeyStr);
    }
}

参数说明

[AutoScene] 只接收一个字符串参数：

参数	类型	说明
key	string	场景 Key，例如 "Gameplay"

推荐使用 nameof(SceneKey.Gameplay) 而不是裸字符串。

适用场景

推荐用于：

• 主玩法根场景
• 主菜单根场景
• 局内关卡根节点
• 使用 GFramework 场景路由管理的切换目标

不推荐用于：

• 普通子节点或容器节点
• 只会被父节点内部消费、没有独立场景语义的脚本
• 行为创建需要额外动态参数的场景包装

使用约束

• 目标类型必须是 partial class
• 不支持嵌套类
• 目标类型必须继承 Godot.Node
• 不要自行声明 GetScene()
• 不要自行声明同名保留成员，例如 SceneKeyStr

生命周期边界

AutoScene 不会自动改写或生成：

• _Ready()
• _EnterTree()
• _ExitTree()
• 场景切换调用链

它只负责提供稳定的场景行为访问入口。何时调用 GetScene()，仍由你的节点生命周期和场景系统决定。

诊断信息

诊断 ID	含义
GF_Common_Class_001	目标类型不是 partial，生成被跳过
GF_Common_Class_002	宿主类型已声明 GetScene() 或保留成员名，和生成代码冲突
GF_AutoBehavior_001	AutoScene 不支持嵌套类
GF_AutoBehavior_002	目标类型没有继承 Godot.Node
GF_AutoBehavior_004	AutoSceneAttribute 参数数量或类型不符合要求

如果你自己声明了 SceneKeyStr、__autoSceneBehavior_Generated 或 GetScene()，编译阶段还会出现成员冲突错误或对应的冲突诊断。

与页面生成器的区别

• AutoUiPage 生成的是 IUiPageBehavior 与 UiLayer
• AutoScene 生成的是 ISceneBehavior 与场景 Key

一个类型通常只应承担一种路由语义。不要把纯页面节点和纯场景根节点混为一体。

相关文档

• 源码生成器总览
• AutoUiPage 生成器