AutoScene 生成器

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

概述

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

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

AutoScene 会在编译期生成这些固定样板。

基础使用

csharp

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

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

生成的代码

csharp

// <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

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

AutoScene 生成器 ​

概述 ​

基础使用 ​

生成的代码 ​

参数说明 ​

适用场景 ​

使用约束 ​

生命周期边界 ​

诊断信息 ​

与页面生成器的区别 ​

相关文档 ​