GFramework/.qoder/repowiki/zh/content/API参考文档/Godot API 参考.md

Godot API 参考

**本文档引用的文件** - [GFramework.Godot.csproj](file://GFramework.Godot/GFramework.Godot.csproj) - [README.md](file://GFramework.Godot/README.md) - [IGodotModule.cs](file://GFramework.Godot/architecture/IGodotModule.cs) - [AbstractGodotModule.cs](file://GFramework.Godot/architecture/AbstractGodotModule.cs) - [AbstractArchitecture.cs](file://GFramework.Godot/architecture/AbstractArchitecture.cs) - [ArchitectureAnchor.cs](file://GFramework.Godot/architecture/ArchitectureAnchor.cs) - [NodeExtensions.cs](file://GFramework.Godot/extensions/NodeExtensions.cs) - [SignalBuilder.cs](file://GFramework.Godot/extensions/signal/SignalBuilder.cs) - [SignalFluentExtensions.cs](file://GFramework.Godot/extensions/signal/SignalFluentExtensions.cs) - [AbstractNodePoolSystem.cs](file://GFramework.Godot/pool/AbstractNodePoolSystem.cs) - [IPoolableNode.cs](file://GFramework.Godot/pool/IPoolableNode.cs) - [IGodotSceneRegistry.cs](file://GFramework.Godot/scene/IGodotSceneRegistry.cs) - [GodotSceneRegistry.cs](file://GFramework.Godot/scene/GodotSceneRegistry.cs) - [IGodotUiRegistry.cs](file://GFramework.Godot/ui/IGodotUiRegistry.cs) - [GodotUiRegistry.cs](file://GFramework.Godot/ui/GodotUiRegistry.cs) - [GodotUiFactory.cs](file://GFramework.Godot/ui/GodotUiFactory.cs) - [GodotFileStorage.cs](file://GFramework.Godot/storage/GodotFileStorage.cs) - [GodotLogger.cs](file://GFramework.Godot/logging/GodotLogger.cs) - [GodotLoggerFactory.cs](file://GFramework.Godot/logging/GodotLoggerFactory.cs)

目录

1. 简介
2. 项目结构
3. 核心组件
4. 架构总览
5. 详细组件分析
6. 依赖分析
7. 性能考虑
8. 故障排查指南
9. 结论
10. 附录

简介

本文件为 GFramework.Godot 模块的详细 API 参考，覆盖与 Godot 引擎集成的接口与类，包括架构集成接口（IArchitecture、IGodotModule）、节点扩展接口（NodeExtensions、SignalBuilder）、场景注册接口（IGodotSceneRegistry）、UI 注册接口（IGodotUiRegistry）、文件存储接口（IFileStorage）等。文档还详细说明 Godot 特有的扩展方法、信号处理机制、资源池化系统、UI 工厂接口、Godot 生命周期绑定、节点管理、场景管理的 API 文档，并提供 Godot 项目集成的完整指南与最佳实践，以及与 Unity 或其他游戏引擎的差异与迁移注意事项，最后包含 Godot 特有的性能优化与调试技巧。

项目结构

GFramework.Godot 作为 Godot 特定实现，主要包含以下模块：

• architecture：Godot 架构集成与模块系统
• extensions：节点扩展与信号流畅 API
• pool：节点对象池系统
• scene：场景注册表
• ui：UI 注册表与 UI 工厂
• storage：Godot 文件存储
• logging：Godot 日志系统

graph TB
subgraph "Godot 集成层"
Arch["AbstractArchitecture<br/>架构生命周期绑定"]
Mod["AbstractGodotModule / IGodotModule<br/>Godot 模块接口"]
Ext["NodeExtensions<br/>节点扩展方法"]
Sig["SignalBuilder / SignalFluentExtensions<br/>信号流畅 API"]
Pool["AbstractNodePoolSystem / IPoolableNode<br/>节点池化系统"]
SceneReg["IGodotSceneRegistry / GodotSceneRegistry<br/>场景注册表"]
UiReg["IGodotUiRegistry / GodotUiRegistry<br/>UI 注册表"]
UiFactory["GodotUiFactory<br/>UI 工厂"]
FileStore["GodotFileStorage<br/>文件存储"]
Loggers["GodotLogger / GodotLoggerFactory<br/>日志系统"]
end
Arch --> Mod
Arch --> Ext
Ext --> Sig
Mod --> Pool
Mod --> UiReg
UiReg --> UiFactory
Mod --> FileStore
Arch --> Loggers

图表来源

• AbstractArchitecture.cs
• AbstractGodotModule.cs
• NodeExtensions.cs
• SignalBuilder.cs
• AbstractNodePoolSystem.cs
• IGodotSceneRegistry.cs
• GodotSceneRegistry.cs
• IGodotUiRegistry.cs
• GodotUiRegistry.cs
• GodotUiFactory.cs
• GodotFileStorage.cs
• GodotLogger.cs
• GodotLoggerFactory.cs

章节来源

• GFramework.Godot.csproj
• README.md

核心组件

本节概览 GFramework.Godot 的核心接口与类，重点说明与 Godot 引擎交互的关键能力。

• 架构集成接口

  • IGodotModule：定义 Godot 模块的节点引用、附加/分离回调与安装方法
  • AbstractGodotModule：模块抽象基类，提供阶段回调与安装/附加/分离的默认实现
  • AbstractArchitecture：将架构与 Godot 生命周期绑定，创建架构锚点节点，安装模块并统一销毁
  • ArchitectureAnchor：架构锚点节点，提供退出场景树时的回调绑定与清理

• 节点扩展与信号

  • NodeExtensions：提供节点安全释放、等待就绪、节点查找与验证、输入处理、树遍历、延迟调用等扩展方法
  • SignalBuilder / SignalFluentExtensions：流畅的信号连接 API，支持链式调用、一次性连接、立即调用与生命周期绑定

• 资源与 UI

  • IGodotSceneRegistry / GodotSceneRegistry：基于键值的场景注册表，管理 PackedScene 资源
  • IGodotUiRegistry / GodotUiRegistry：基于键值的 UI 注册表，管理 PackedScene 资源
  • GodotUiFactory：UI 页面实例创建与缓存/池化管理，支持预加载、LRU/LFU 淘汰策略、命中率统计

• 资源池化

  • AbstractNodePoolSystem：基于场景实例化的节点池系统，继承通用对象池并实现节点特化创建
  • IPoolableNode：可池化节点接口，提供 Node 转换能力

• 文件存储

  • GodotFileStorage：支持 res://、user:// 与普通文件路径的文件存储，提供线程安全（按 key 锁）、序列化读写与存在性检查

• 日志系统

  • GodotLogger / GodotLoggerFactory：与 Godot 日志系统集成的日志记录器与工厂，按级别输出到控制台

章节来源

• IGodotModule.cs
• AbstractGodotModule.cs
• AbstractArchitecture.cs
• ArchitectureAnchor.cs
• NodeExtensions.cs
• SignalBuilder.cs
• SignalFluentExtensions.cs
• IGodotSceneRegistry.cs
• GodotSceneRegistry.cs
• IGodotUiRegistry.cs
• GodotUiRegistry.cs
• GodotUiFactory.cs
• AbstractNodePoolSystem.cs
• IPoolableNode.cs
• GodotFileStorage.cs
• GodotLogger.cs
• GodotLoggerFactory.cs

架构总览

GFramework.Godot 的架构通过 AbstractArchitecture 将框架生命周期与 Godot 场景树绑定，创建唯一的架构锚点节点，安装模块并将模块节点作为锚点子节点，实现与 Godot 生命周期的无缝衔接。模块通过 IGodotModule 接口声明自身节点与生命周期回调，支持阶段驱动的初始化与清理。

sequenceDiagram
participant Dev as "开发者代码"
participant Arch as "AbstractArchitecture"
participant Anchor as "ArchitectureAnchor"
participant Mod as "IGodotModule 实现"
participant Tree as "SceneTree"
Dev->>Arch : "Initialize()"
Arch->>Tree : "查找根节点"
Arch->>Arch : "生成唯一锚点名称"
Arch->>Anchor : "创建锚点节点"
Arch->>Anchor : "Bind(Destroy)"
Arch->>Tree.Root : "CallDeferred(AddChild, Anchor)"
Arch->>Mod : "Install(this)"
Arch->>Anchor : "WaitUntilReady()"
Arch->>Anchor : "CallDeferred(AddChild, Mod.Node)"
Arch->>Mod : "OnAttach(this)"
Note over Arch,Mod : "模块安装完成，随场景树销毁自动清理"

图表来源

• AbstractArchitecture.cs
• ArchitectureAnchor.cs

章节来源

• AbstractArchitecture.cs
• ArchitectureAnchor.cs

详细组件分析

架构集成接口（IArchitecture、IGodotModule）

• IGodotModule
  • Node：模块关联的 Godot 节点
  • OnAttach(Architecture)：模块附加到架构时调用
  • OnDetach()：模块从架构分离时调用
• AbstractGodotModule
  • Install(Architecture)：安装模块到架构
  • OnPhase(phase, architecture) / OnArchitecturePhase(phase)：阶段回调
  • OnAttach / OnDetach 默认空实现，便于按需覆写

classDiagram
class IGodotModule {
+Node Node
+Install(architecture)
+OnAttach(architecture)
+OnDetach()
}
class AbstractGodotModule {
+Node Node
+Install(architecture)
+OnPhase(phase, architecture)
+OnArchitecturePhase(phase)
+OnAttach(architecture)
+OnDetach()
}
IGodotModule <|.. AbstractGodotModule

图表来源

• IGodotModule.cs
• AbstractGodotModule.cs

章节来源

• IGodotModule.cs
• AbstractGodotModule.cs

节点扩展接口（NodeExtensions）

NodeExtensions 提供大量安全、便捷的节点操作扩展，覆盖节点释放、等待就绪、节点查找与验证、输入处理、树遍历、延迟调用与类型转换等。

• 节点释放与等待
  • QueueFreeX(node) / FreeX(node)：安全释放，带空值与有效性检查
  • WaitUntilReady(node)：未在场景树内时等待 Ready 信号
• 节点验证与查找
  • IsValidNode(node) / IsInvalidNode(node)：组合检查节点有效性
  • FindChildX(node, name, recursive)：安全递归查找子节点
• 输入与场景树控制
  • SetInputAsHandled(node)：标记输入已处理
  • DisableInput(node) / EnableInput(node)：控制 GUI 输入
  • Paused(node, paused)：设置场景树暂停状态
• 场景树操作
  • AddChildX(parent, child)：异步添加子节点并等待就绪
  • GetParentX(node) / GetRootNodeX(node)：安全获取父节点与根节点
  • ForEachChild(node, action)：按类型遍历子节点
• 调试与辅助
  • LogNodePath(node) / PrintTreeX(node, indent)：打印节点路径与树结构
  • SafeCallDeferred(node, method)：安全延迟调用
  • OfType(node)：类型转换并抛出异常

flowchart TD
Start(["调用入口"]) --> CheckNull["检查节点是否为空"]
CheckNull --> NullBranch{"为空？"}
NullBranch --> |是| ReturnVoid["直接返回"]
NullBranch --> |否| CheckValid["检查实例有效性"]
CheckValid --> ValidBranch{"有效？"}
ValidBranch --> |否| ReturnVoid
ValidBranch --> |是| CheckQueued["检查是否已在删除队列"]
CheckQueued --> QueuedBranch{"已排队？"}
QueuedBranch --> |是| ReturnVoid
QueuedBranch --> |否| CallFree["调用释放方法"]
CallFree --> End(["完成"])

图表来源

• NodeExtensions.cs

章节来源

• NodeExtensions.cs

信号处理机制（SignalBuilder、SignalFluentExtensions）

SignalBuilder 提供流畅的信号连接 API，支持：

• WithFlags(flags)：设置连接标志
• To(callable, flags?)：连接信号到可调用对象
• ToAndCall(callable, flags?, args)：连接后立即调用
• End()：显式结束，返回目标对象

SignalFluentExtensions 为 GodotObject 提供 Signal(object, signal) 扩展，快速创建 SignalBuilder。

sequenceDiagram
participant Dev as "开发者代码"
participant Obj as "GodotObject"
participant Builder as "SignalBuilder"
participant Target as "目标节点"
Dev->>Obj : "Signal(signal)"
Obj-->>Dev : "返回 SignalBuilder"
Dev->>Builder : "WithFlags(flags)"
Dev->>Builder : "To(callable)"
Builder-->>Target : "Connect(signal, callable)"
Note over Builder,Target : "支持一次性连接、立即调用与生命周期绑定"

图表来源

• SignalFluentExtensions.cs
• SignalBuilder.cs

章节来源

• SignalFluentExtensions.cs
• SignalBuilder.cs

资源池化系统（AbstractNodePoolSystem、IPoolableNode）

AbstractNodePoolSystem 为 Godot 节点对象池系统，继承通用对象池并实现基于场景实例化的创建逻辑；IPoolableNode 定义可池化节点的 Node 转换能力。

• 关键点
  • LoadScene(key)：抽象方法，用于加载 PackedScene
  • Create(key)：基于场景实例化节点
  • 与 Godot 节点生命周期配合，支持可见性切换、父节点移除与延迟释放

classDiagram
class AbstractObjectPoolSystem~TKey,TNode~ {
+Create(TKey) TNode
+Spawn(TKey) TNode
+Despawn(TNode)
}
class AbstractNodePoolSystem~TKey,TNode~ {
+LoadScene(TKey) PackedScene
+Create(TKey) TNode
}
class IPoolableNode {
+AsNode() Node
}
AbstractNodePoolSystem~TKey,TNode~ --|> AbstractObjectPoolSystem~TKey,TNode~
IPoolableNode <|.. TNode

图表来源

• AbstractNodePoolSystem.cs
• IPoolableNode.cs

章节来源

• AbstractNodePoolSystem.cs
• IPoolableNode.cs

场景注册接口（IGodotSceneRegistry、GodotSceneRegistry）

• IGodotSceneRegistry：基于键值的场景注册表接口，值类型为 PackedScene
• GodotSceneRegistry：继承键值注册表基类，使用字符串键与 PackedScene 值进行存储与访问

classDiagram
class IAssetRegistry~T~ {
+Get(key) T
+Set(key, value)
+Has(key) bool
}
class IGodotSceneRegistry {
}
class GodotSceneRegistry {
}
IAssetRegistry~PackedScene~ <|.. IGodotSceneRegistry
GodotSceneRegistry ..|> IGodotSceneRegistry

图表来源

• IGodotSceneRegistry.cs
• GodotSceneRegistry.cs

章节来源

• IGodotSceneRegistry.cs
• GodotSceneRegistry.cs

UI 注册与工厂（IGodotUiRegistry、GodotUiRegistry、GodotUiFactory）

• IGodotUiRegistry / GodotUiRegistry：基于键值的 UI 注册表，值类型为 PackedScene
• GodotUiFactory：UI 页面实例创建与缓存/池化管理
  • GetOrCreate(uiKey, policy)：根据策略创建或复用实例
  • Create(uiKey)：直接创建新实例
  • Preload(uiKey, count) / PreloadBatch(uiKeys)：批量预加载隐藏实例
  • Recycle(page)：回收实例到缓存池，更新统计与访问追踪
  • SetCacheConfig(uiKey, config) / GetCacheConfig(uiKey) / RemoveCacheConfig(uiKey)：缓存配置管理
  • ClearCache(uiKey) / ClearAllCache()：清理指定或全部缓存
  • HasCached(uiKey)：检查是否有缓存实例
  • GetCacheStatistics()：获取缓存命中率等统计信息
  • 淘汰策略：LRU（按访问时间）与 LFU（按访问次数），支持最大缓存大小与淘汰策略配置

flowchart TD
Start(["GetOrCreate(uiKey, policy)"]) --> Policy{"策略"}
Policy --> |AlwaysCreate| Create["Create(uiKey)"]
Policy --> |Reuse| Cached["HasCached(uiKey) ? 取缓存 : Create(uiKey)"]
Policy --> |Pooled| PoolCheck{"缓存为空？"}
PoolCheck --> |是| Preload["Preload(uiKey)"] --> Cached
PoolCheck --> |否| Cached
Cached --> End(["返回实例"])
Create --> End

图表来源

• GodotUiFactory.cs
• GodotUiFactory.cs

章节来源

• IGodotUiRegistry.cs
• GodotUiRegistry.cs
• GodotUiFactory.cs

文件存储接口（GodotFileStorage）

GodotFileStorage 实现 IStorage，支持：

• Delete(key)：删除文件（支持 res:// 与 user:// 虚拟路径与普通文件系统路径）
• Exists(key) / ExistsAsync(key)：检查文件是否存在
• Read(key) / Read(key, defaultValue) / ReadAsync(key)：读取并反序列化
• Write(key, value) / WriteAsync(key, value)：序列化并写入
• 线程安全：按绝对路径生成 keyLock，每个 key 对应独立锁
• 路径处理：清理非法字符、规范化路径、Godot 虚拟路径与本地文件系统路径分别处理

flowchart TD
Start(["Write<T>(key, value)"]) --> AbsPath["ToAbsolutePath(key)"]
AbsPath --> Lock["GetLock(path)"]
Lock --> Serialize["_serializer.Serialize(value)"]
Serialize --> CheckGodot{"是否 Godot 路径？"}
CheckGodot --> |是| OpenWrite["FileAccess.Open(path, Write)"]
CheckGodot --> |否| Local["Directory.CreateDirectory(...) / File.WriteAllText(...)"]
OpenWrite --> Store["file.StoreString(content)"]
Local --> Done(["完成"])
Store --> Done

图表来源

• GodotFileStorage.cs
• GodotFileStorage.cs

章节来源

• GodotFileStorage.cs

日志系统（GodotLogger、GodotLoggerFactory）

• GodotLogger：继承抽象日志器，按级别输出到 GD.Print、GD.PrintErr、GD.PushWarning、GD.PushError
• GodotLoggerFactory：创建 GodotLogger 实例，支持最小日志级别配置

classDiagram
class ILogger {
+Log(level, message, exception)
}
class AbstractLogger {
+Write(level, message, exception)
}
class GodotLogger {
+Write(level, message, exception)
}
class ILoggerFactory {
+GetLogger(name, minLevel) ILogger
}
class GodotLoggerFactory {
+GetLogger(name, minLevel) ILogger
}
AbstractLogger <|-- GodotLogger
ILogger <|.. GodotLogger
ILoggerFactory <|.. GodotLoggerFactory

图表来源

• GodotLogger.cs
• GodotLoggerFactory.cs

章节来源

• GodotLogger.cs
• GodotLoggerFactory.cs

依赖分析

GFramework.Godot 通过项目引用与接口契约与其他模块协作：

• 项目引用
  • GFramework.Game：游戏层实现与抽象
  • GFramework.Game.Abstractions：游戏抽象接口
  • GFramework.Core.Abstractions：核心抽象接口
• 关键依赖关系
  • AbstractArchitecture 依赖 Godot SceneTree 与 ArchitectureAnchor
  • GodotUiFactory 依赖 IGodotUiRegistry 与 IUiPageBehaviorProvider
  • GodotFileStorage 依赖 ISerializer 与 Godot 文件访问 API
  • 日志系统依赖 Godot 日志输出 API

graph TB
Proj["GFramework.Godot.csproj"]
Game["GFramework.Game"]
GameAb["GFramework.Game.Abstractions"]
CoreAb["GFramework.Core.Abstractions"]
Proj --> Game
Proj --> GameAb
Proj --> CoreAb

图表来源

• GFramework.Godot.csproj

章节来源

• GFramework.Godot.csproj

性能考虑

• 节点池化
  • 使用 AbstractNodePoolSystem 与 IPoolableNode 管理高频创建/销毁的节点，减少 GC 压力与卡顿
  • 预加载隐藏实例，降低 UI 切换与特效触发时的瞬时开销
• 缓存与淘汰
  • GodotUiFactory 支持 LRU/LFU 淘汰策略，结合最大缓存大小限制内存占用
  • 命中率统计帮助评估缓存效果，指导预加载数量与策略调整
• 文件存储
  • 按 key 锁保证并发安全，避免竞态；合理拆分 key，降低锁竞争
  • 读写采用 UTF-8 文本序列化，注意大文件与频繁 IO 的异步化
• 信号与事件
  • 使用 SignalBuilder 进行一次性连接与生命周期绑定，避免泄漏
  • 事件订阅建议在节点退出时自动解绑，减少内存泄漏风险

故障排查指南

• 节点释放与生命周期
  • 使用 QueueFreeX / FreeX 替代直接释放，避免在当前帧释放导致的异常
  • 确保节点在场景树内再进行操作，使用 WaitUntilReady 等待就绪
• 信号连接泄漏
  • 使用 SignalBuilder 链式 API 并在节点退出时自动解绑
  • 避免直接 += 事件订阅，推荐框架事件系统与自动清理扩展
• UI 缓存问题
  • 检查缓存配置与淘汰策略是否合理，必要时清理缓存或调整最大容量
  • 使用 GetCacheStatistics 观察命中率，定位缓存不足或过度缓存
• 文件存储错误
  • 检查路径合法性与 Godot 虚拟路径支持，避免 '..' 与空键
  • 注意并发写入时的锁竞争，必要时合并写入或使用异步接口
• 日志输出
  • 确认日志级别与工厂配置，避免过多低级别日志影响性能

章节来源

• NodeExtensions.cs
• SignalBuilder.cs
• GodotUiFactory.cs
• GodotFileStorage.cs
• GodotLogger.cs

结论

GFramework.Godot 通过清晰的接口与强大的扩展能力，实现了与 Godot 引擎的深度集成。架构生命周期绑定、节点扩展、信号流畅 API、资源池化、UI 工厂、文件存储与日志系统共同构成了一套高效、安全、可维护的开发体系。遵循本文档的最佳实践与性能建议，可显著提升开发效率与运行性能。

附录

• 与 Unity 的差异与迁移注意事项
  • 生命周期绑定：Godot 通过 SceneTree 与节点生命周期绑定，Unity 通过 MonoBehaviour 生命周期与协程管理；迁移时需将 Unity 的 Start/Awake 映射到 Godot 的 _Ready/_EnterTree 等
  • 信号与事件：Godot 使用 Connect/Disconnect 与 Signal 属性，Unity 使用 C# 事件或 UnityEvent；迁移时建议统一使用框架事件系统并配合自动清理扩展
  • 节点管理：Godot 的节点树与父子关系管理更为严格，迁移时需确保节点释放与场景树一致性
  • 资源加载：Godot 使用 GD.Load 与 PackedScene，Unity 使用 Addressables/Resource 系统；迁移时统一使用注册表与工厂模式
  • 日志：Godot 使用 GD.Print 系列，Unity 使用 UnityLog 或第三方日志库；迁移时统一使用框架日志工厂
• Godot 特有性能优化与调试技巧
  • 使用延迟调用（CallDeferred）避免在渲染帧中执行昂贵操作
  • 合理使用信号一次性连接（ConnectFlags.OneShot）减少回调开销
  • UI 预加载与缓存策略结合 LRU/LFU，平衡内存与性能
  • 文件存储采用 UTF-8 文本序列化，注意大文件异步读写
  • 使用节点树打印与路径日志辅助调试场景树问题