---
title: AutoScene 生成器
description: 介绍 AutoScene 生成器如何生成场景包装入口与统一场景键声明。
---

# AutoScene 生成器

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

## 概述

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

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

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

## 基础使用

```csharp
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();
    }
}
```

## 生成的代码

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

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

## 相关文档

- [源码生成器总览](./index.md)
- [AutoUiPage 生成器](./auto-ui-page-generator.md)