mirror of https://github.com/GeWuYou/GFramework.git synced 2026-05-07 00:39:00 +08:00

GeWuYou e691c9c855 docs(api): 添加 GFramework API 参考文档和源代码生成器文档

- 新增 API 参考文档，包含核心命名空间、常用 API、游戏模块 API、Godot 集成 API
- 详细介绍架构、模型、系统、命令、查询等核心类型及其用法示例
- 添加本地化系统 API 文档，包含管理器、字符串、配置等相关接口
- 新增源代码生成器完整文档，涵盖 Log、Config Schema、ContextAware 等生成器
- 详细说明各生成器的使用方法、配置选项和诊断信息
- 提供完整的 Godot 专用生成器文档，包括 GetNode、BindNodeSignal、AutoUiPage 等
- 添加使用示例和最佳实践指南，展示完整的游戏控制器和枚举状态管理示例

2026-04-13 19:16:28 +08:00

3.3 KiB

Raw Blame History

AutoScene 生成器

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

概述

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

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

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

基础使用

using GFramework.Godot.SourceGenerators.Abstractions;
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

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

3.3 KiB Raw Blame History Unescape Escape