mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-05-08 09:34:30 +08:00
3d169ca91f
- 新增 AutoRegisterExportedCollections 生成器文档 - 新增 AutoRegisterModule 生成器文档 - 新增 AutoScene 生成器文档 - 新增 AutoUiPage 生成器文档 - 更新源码生成器总览索引文档 - 添加各生成器的使用示例和参数说明 - 补充诊断信息和使用约束说明
120 lines
3.4 KiB
Markdown
120 lines
3.4 KiB
Markdown
# 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
|
||
|
||
一个类型通常只应承担一种路由语义。不要把纯页面节点和纯场景根节点混为一体。
|
||
|
||
## 相关文档
|
||
|
||
- [源码生成器总览](./index)
|
||
- [AutoUiPage 生成器](./auto-ui-page-generator)
|