gewuyou/GFramework
1
0
Fork 0
mirror of https://github.com/GeWuYou/GFramework.git synced 2026-03-26 06:16:43 +08:00
Code Issues Packages Projects Releases Wiki Activity
GFramework/.qoder/repowiki/zh/content/平台集成模块/平台集成模块.md
GeWuYou a79f02c987 docs(api): 添加 Core API 参考文档与事件系统接口文档 
- 新增 Core API 参考文档，涵盖架构与模块、数据模型与系统、命令与查询等核心组件
- 添加事件系统接口详细文档，包括 IEvent、IEventBus、IUnRegister 等接口说明
- 提供完整的 API 使用示例路径、最佳实践与性能建议
- 包含架构图、依赖关系图与故障排查指南
- 添加测试用例参考与扩展方法说明
- [skip ci]
2026-01-21 23:45:10 +08:00

480 lines
24 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 平台集成模块
<cite>
**本文引用的文件**
- [GFramework.Godot/architecture/AbstractArchitecture.cs](file://GFramework.Godot/architecture/AbstractArchitecture.cs)
- [GFramework.Godot/architecture/AbstractGodotModule.cs](file://GFramework.Godot/architecture/AbstractGodotModule.cs)
- [GFramework.Godot/architecture/ArchitectureAnchor.cs](file://GFramework.Godot/architecture/ArchitectureAnchor.cs)
- [GFramework.Godot/architecture/IGodotModule.cs](file://GFramework.Godot/architecture/IGodotModule.cs)
- [GFramework.Godot/coroutine/CoroutineExtensions.cs](file://GFramework.Godot/coroutine/CoroutineExtensions.cs)
- [GFramework.Godot/coroutine/GodotTimeSource.cs](file://GFramework.Godot/coroutine/GodotTimeSource.cs)
- [GFramework.Godot/extensions/NodeExtensions.cs](file://GFramework.Godot/extensions/NodeExtensions.cs)
- [GFramework.Godot/extensions/signal/SignalBuilder.cs](file://GFramework.Godot/extensions/signal/SignalBuilder.cs)
- [GFramework.Godot/extensions/GodotPathExtensions.cs](file://GFramework.Godot/extensions/GodotPathExtensions.cs)
- [GFramework.Godot/storage/GodotFileStorage.cs](file://GFramework.Godot/storage/GodotFileStorage.cs)
- [GFramework.Godot/scene/GodotSceneRegistry.cs](file://GFramework.Godot/scene/GodotSceneRegistry.cs)
- [GFramework.Godot/ui/GodotUiFactory.cs](file://GFramework.Godot/ui/GodotUiFactory.cs)
- [GFramework.Godot/ui/GodotUiRegistry.cs](file://GFramework.Godot/ui/GodotUiRegistry.cs)
- [GFramework.Godot.SourceGenerators.Abstractions/GodotModuleMarker.cs](file://GFramework.Godot.SourceGenerators.Abstractions/GodotModuleMarker.cs)
- [GFramework.Godot/README.md](file://GFramework.Godot/README.md)
</cite>
## 目录
1. [引言](#引言)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [组件详解](#组件详解)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 引言
本文件面向希望在Godot引擎中集成GFramework平台的开发者，系统性阐述GFramework.Godot模块的设计与实现，覆盖架构适配、模块系统、节点扩展、信号处理、路径扩展、生命周期绑定、协程集成、资源与UI注册体系，以及源码生成器的使用与配置。同时提供从其他平台迁移到Godot的实践建议与注意事项。
## 项目结构
GFramework.Godot位于仓库的GFramework.Godot目录，围绕“架构适配 + 扩展能力 + 资源与UI管理 + 协程与时间源”的主题组织代码，采用按功能域分层的结构：
- architecture：Godot架构适配与模块系统
- extensions：节点扩展、信号构建器、路径扩展等
- storage：Godot文件存储实现
- scene/ui：场景与UI注册表、UI工厂
- coroutine：协程扩展与时间源
- SourceGenerators.Abstractions：Godot模块标记类型（用于生成器识别）
```mermaid
graph TB
subgraph "Godot集成层"
AA["AbstractArchitecture<br/>架构适配"]
AGM["AbstractGodotModule<br/>模块基类"]
IAM["IGodotModule<br/>模块接口"]
AN["ArchitectureAnchor<br/>架构锚点"]
NE["NodeExtensions<br/>节点扩展"]
SB["SignalBuilder<br/>信号构建器"]
GPE["GodotPathExtensions<br/>路径扩展"]
GFS["GodotFileStorage<br/>文件存储"]
GSR["GodotSceneRegistry<br/>场景注册表"]
GUIR["GodotUiRegistry<br/>UI注册表"]
GUF["GodotUiFactory<br/>UI工厂"]
CE["CoroutineExtensions<br/>协程扩展"]
GTS["GodotTimeSource<br/>时间源"]
GMM["GodotModuleMarker<br/>模块标记(生成器)"]
end
AA --> AN
AA --> IAM
AGM --> IAM
AA --> AGM
NE --> AA
SB --> NE
GFS --> NE
GSR --> GUF
GUIR --> GUF
CE --> GTS
GMM --> AGM
```
图表来源
- [GFramework.Godot/architecture/AbstractArchitecture.cs](file://GFramework.Godot/architecture/AbstractArchitecture.cs#L14-L140)
- [GFramework.Godot/architecture/AbstractGodotModule.cs](file://GFramework.Godot/architecture/AbstractGodotModule.cs#L11-L55)
- [GFramework.Godot/architecture/ArchitectureAnchor.cs](file://GFramework.Godot/architecture/ArchitectureAnchor.cs#L9-L35)
- [GFramework.Godot/architecture/IGodotModule.cs](file://GFramework.Godot/architecture/IGodotModule.cs#L10-L27)
- [GFramework.Godot/extensions/NodeExtensions.cs](file://GFramework.Godot/extensions/NodeExtensions.cs#L8-L259)
- [GFramework.Godot/extensions/signal/SignalBuilder.cs](file://GFramework.Godot/extensions/signal/SignalBuilder.cs#L10-L65)
- [GFramework.Godot/extensions/GodotPathExtensions.cs](file://GFramework.Godot/extensions/GodotPathExtensions.cs#L3-L22)
- [GFramework.Godot/storage/GodotFileStorage.cs](file://GFramework.Godot/storage/GodotFileStorage.cs#L15-L291)
- [GFramework.Godot/scene/GodotSceneRegistry.cs](file://GFramework.Godot/scene/GodotSceneRegistry.cs#L11-L12)
- [GFramework.Godot/ui/GodotUiRegistry.cs](file://GFramework.Godot/ui/GodotUiRegistry.cs#L11-L12)
- [GFramework.Godot/ui/GodotUiFactory.cs](file://GFramework.Godot/ui/GodotUiFactory.cs#L16-L463)
- [GFramework.Godot/coroutine/CoroutineExtensions.cs](file://GFramework.Godot/coroutine/CoroutineExtensions.cs#L7-L66)
- [GFramework.Godot/coroutine/GodotTimeSource.cs](file://GFramework.Godot/coroutine/GodotTimeSource.cs#L9-L44)
- [GFramework.Godot.SourceGenerators.Abstractions/GodotModuleMarker.cs](file://GFramework.Godot.SourceGenerators.Abstractions/GodotModuleMarker.cs#L1-L6)
章节来源
- [GFramework.Godot/README.md](file://GFramework.Godot/README.md#L1-L200)
## 核心组件
- AbstractArchitecture：在Godot场景树中创建并绑定架构锚点，统一管理模块安装、生命周期与销毁；提供InstallGodotModule以异步挂载模块节点。
- AbstractGodotModule：模块基类，定义模块节点、安装与附加/分离回调，以及架构阶段变更通知。
- ArchitectureAnchor：轻量节点，提供Bind与_exit_tree回调，确保节点从场景树移除时触发清理。
- IGodotModule：Godot模块接口，暴露Node、OnAttach、OnDetach。
- NodeExtensions：提供节点安全操作、Ready等待、父子节点查找、输入处理、树遍历、延迟调用等扩展。
- SignalBuilder：流畅式信号连接API，支持一次性连接、立即调用、生命周期绑定。
- GodotPathExtensions：Godot路径判断工具（user://、res://）。
- GodotFileStorage：支持res://、user://与普通文件路径的存储实现，提供线程安全的读写与存在性检查。
- GodotSceneRegistry/GodotUiRegistry：基于键值注册表的场景与UI资源管理。
- GodotUiFactory：UI页面实例的创建、缓存、预加载、回收与淘汰策略（LRU/LFU）。
- CoroutineExtensions/GodotTimeSource：协程扩展与时间源，提供与Godot生命周期一致的时间推进与协程取消。
- GodotModuleMarker：生成器标记类型，用于识别Godot模块命名空间。
章节来源
- [GFramework.Godot/architecture/AbstractArchitecture.cs](file://GFramework.Godot/architecture/AbstractArchitecture.cs#L14-L140)
- [GFramework.Godot/architecture/AbstractGodotModule.cs](file://GFramework.Godot/architecture/AbstractGodotModule.cs#L11-L55)
- [GFramework.Godot/architecture/ArchitectureAnchor.cs](file://GFramework.Godot/architecture/ArchitectureAnchor.cs#L9-L35)
- [GFramework.Godot/architecture/IGodotModule.cs](file://GFramework.Godot/architecture/IGodotModule.cs#L10-L27)
- [GFramework.Godot/extensions/NodeExtensions.cs](file://GFramework.Godot/extensions/NodeExtensions.cs#L8-L259)
- [GFramework.Godot/extensions/signal/SignalBuilder.cs](file://GFramework.Godot/extensions/signal/SignalBuilder.cs#L10-L65)
- [GFramework.Godot/extensions/GodotPathExtensions.cs](file://GFramework.Godot/extensions/GodotPathExtensions.cs#L3-L22)
- [GFramework.Godot/storage/GodotFileStorage.cs](file://GFramework.Godot/storage/GodotFileStorage.cs#L15-L291)
- [GFramework.Godot/scene/GodotSceneRegistry.cs](file://GFramework.Godot/scene/GodotSceneRegistry.cs#L11-L12)
- [GFramework.Godot/ui/GodotUiRegistry.cs](file://GFramework.Godot/ui/GodotUiRegistry.cs#L11-L12)
- [GFramework.Godot/ui/GodotUiFactory.cs](file://GFramework.Godot/ui/GodotUiFactory.cs#L16-L463)
- [GFramework.Godot/coroutine/CoroutineExtensions.cs](file://GFramework.Godot/coroutine/CoroutineExtensions.cs#L7-L66)
- [GFramework.Godot/coroutine/GodotTimeSource.cs](file://GFramework.Godot/coroutine/GodotTimeSource.cs#L9-L44)
- [GFramework.Godot.SourceGenerators.Abstractions/GodotModuleMarker.cs](file://GFramework.Godot.SourceGenerators.Abstractions/GodotModuleMarker.cs#L1-L6)
## 架构总览
GFramework.Godot通过AbstractArchitecture将框架生命周期与Godot场景树绑定，使用ArchitectureAnchor作为根节点承载模块节点，确保节点退出场景树时自动清理。模块通过AbstractGodotModule实现安装、附加与分离回调，并在架构阶段变更时响应。
```mermaid
classDiagram
class AbstractArchitecture {
-IGodotModule[] _extensions
-ArchitectureAnchor _anchor
-string _architectureAnchorName
-bool _destroyed
+Init()
+InstallModules()
+InstallGodotModule~TModule~
+Destroy()
}
class ArchitectureAnchor {
-Action _onExit
+Bind(onExit)
+_ExitTree()
}
class IGodotModule {
<<interface>>
+Node Node
+OnAttach(architecture)
+OnDetach()
}
class AbstractGodotModule {
+Node Node
+Install(architecture)
+OnAttach(architecture)
+OnDetach()
+OnPhase(phase, architecture)
+OnArchitecturePhase(phase)
}
AbstractArchitecture --> ArchitectureAnchor : "创建并绑定"
AbstractArchitecture --> IGodotModule : "安装/跟踪"
AbstractGodotModule ..|> IGodotModule
```
图表来源
- [GFramework.Godot/architecture/AbstractArchitecture.cs](file://GFramework.Godot/architecture/AbstractArchitecture.cs#L14-L140)
- [GFramework.Godot/architecture/ArchitectureAnchor.cs](file://GFramework.Godot/architecture/ArchitectureAnchor.cs#L9-L35)
- [GFramework.Godot/architecture/IGodotModule.cs](file://GFramework.Godot/architecture/IGodotModule.cs#L10-L27)
- [GFramework.Godot/architecture/AbstractGodotModule.cs](file://GFramework.Godot/architecture/AbstractGodotModule.cs#L11-L55)
## 组件详解
### 架构适配与模块系统
- AbstractArchitecture
- 生成唯一锚点名称，避免重复挂载
- 通过AttachToGodotLifecycle在场景树根节点下创建ArchitectureAnchor并绑定Destroy回调
- InstallGodotModule负责安装模块、等待锚点就绪、将模块节点作为子节点添加，并调用OnAttach
- Destroy遍历已安装模块调用OnDetach并清空列表
- AbstractGodotModule
- Node暴露模块关联的Godot节点
- Install定义模块安装逻辑
- OnAttach/OnDetach分别在模块附加/分离时回调
- OnPhase/OnArchitecturePhase响应架构阶段变化
- IGodotModule
- 继承IArchitectureModule，要求Node、OnAttach、OnDetach
- ArchitectureAnchor
- Bind记录退出回调，_ExitTree触发并清理
```mermaid
sequenceDiagram
participant Arch as "AbstractArchitecture"
participant Tree as "SceneTree.Root"
participant Anchor as "ArchitectureAnchor"
participant Mod as "IGodotModule"
Arch->>Arch : Init()
Arch->>Tree : 创建并添加Anchor
Anchor-->>Arch : Bind(Destroy)
Arch->>Arch : InstallModules()
Arch->>Mod : Install(this)
Arch->>Anchor : CallDeferred(AddChild(Mod.Node))
Anchor-->>Mod : OnAttach(this)
Note over Arch,Mod : 模块安装完成，随场景树销毁自动清理
```
图表来源
- [GFramework.Godot/architecture/AbstractArchitecture.cs](file://GFramework.Godot/architecture/AbstractArchitecture.cs#L56-L119)
- [GFramework.Godot/architecture/ArchitectureAnchor.cs](file://GFramework.Godot/architecture/ArchitectureAnchor.cs#L17-L34)
- [GFramework.Godot/architecture/IGodotModule.cs](file://GFramework.Godot/architecture/IGodotModule.cs#L10-L27)
章节来源
- [GFramework.Godot/architecture/AbstractArchitecture.cs](file://GFramework.Godot/architecture/AbstractArchitecture.cs#L14-L140)
- [GFramework.Godot/architecture/AbstractGodotModule.cs](file://GFramework.Godot/architecture/AbstractGodotModule.cs#L11-L55)
- [GFramework.Godot/architecture/ArchitectureAnchor.cs](file://GFramework.Godot/architecture/ArchitectureAnchor.cs#L9-L35)
- [GFramework.Godot/architecture/IGodotModule.cs](file://GFramework.Godot/architecture/IGodotModule.cs#L10-L27)
### 节点扩展与信号处理
- NodeExtensions
- 安全释放：QueueFreeX/Freex，带空值与有效性检查
- Ready等待：WaitUntilReady，若不在树内则等待Ready信号
- 节点验证：IsValidNode/IsInvalidNode
- 输入处理：SetInputAsHandled、Paused、DisableInput/EnableInput
- 路径与树遍历：FindChildX、GetOrCreateNode、AddChildX、GetParentX、GetRootNodeX、ForEachChild
- 树打印与延迟调用：LogNodePath、PrintTreeX、SafeCallDeferred、OfType
- SignalBuilder
- WithFlags设置连接标志
- To连接到Callable，ToAndCall连接后立即调用
- End返回目标对象
- GodotPathExtensions
- IsUserPath/IsResPath/IsGodotPath
```mermaid
flowchart TD
Start(["开始"]) --> CheckNode["检查节点是否有效"]
CheckNode --> |无效| End(["结束"])
CheckNode --> |有效| ChooseOp{"选择操作"}
ChooseOp --> |等待Ready| WaitReady["等待Ready信号"]
ChooseOp --> |安全释放| SafeFree["QueueFreeX/Freex"]
ChooseOp --> |查找子节点| FindChild["FindChildX/GetOrCreateNode"]
ChooseOp --> |遍历| ForEach["ForEachChild"]
WaitReady --> End
SafeFree --> End
FindChild --> End
ForEach --> End
```
图表来源
- [GFramework.Godot/extensions/NodeExtensions.cs](file://GFramework.Godot/extensions/NodeExtensions.cs#L14-L259)
- [GFramework.Godot/extensions/signal/SignalBuilder.cs](file://GFramework.Godot/extensions/signal/SignalBuilder.cs#L10-L65)
- [GFramework.Godot/extensions/GodotPathExtensions.cs](file://GFramework.Godot/extensions/GodotPathExtensions.cs#L3-L22)
章节来源
- [GFramework.Godot/extensions/NodeExtensions.cs](file://GFramework.Godot/extensions/NodeExtensions.cs#L8-L259)
- [GFramework.Godot/extensions/signal/SignalBuilder.cs](file://GFramework.Godot/extensions/signal/SignalBuilder.cs#L10-L65)
- [GFramework.Godot/extensions/GodotPathExtensions.cs](file://GFramework.Godot/extensions/GodotPathExtensions.cs#L3-L22)
### 协程集成与时间源
- CoroutineExtensions
- RunCoroutine：启动协程，支持Segment与tag
- CancelWith：在节点销毁时自动取消协程（单节点、双节点、多节点）
- GodotTimeSource
- ITimeSource实现，提供CurrentTime/DeltaTime
- Update根据传入的增量时间函数推进时间，Reset重置
```mermaid
sequenceDiagram
participant Node as "Node"
participant Ext as "CoroutineExtensions"
participant Timing as "Timing"
participant TS as "GodotTimeSource"
Node->>Ext : RunCoroutine(coroutine, segment, tag)
Ext->>Timing : RunCoroutine(coroutine, segment, tag)
loop 每帧
Timing->>TS : Update()
TS-->>Timing : CurrentTime/DeltaTime
end
Node->>Ext : CancelWith(node)
Ext->>Timing : IsNodeAlive(node)
alt 节点存活
Ext-->>Node : yield return Current
else 节点销毁
Ext-->>Node : 结束协程
end
```
图表来源
- [GFramework.Godot/coroutine/CoroutineExtensions.cs](file://GFramework.Godot/coroutine/CoroutineExtensions.cs#L12-L66)
- [GFramework.Godot/coroutine/GodotTimeSource.cs](file://GFramework.Godot/coroutine/GodotTimeSource.cs#L28-L44)
章节来源
- [GFramework.Godot/coroutine/CoroutineExtensions.cs](file://GFramework.Godot/coroutine/CoroutineExtensions.cs#L7-L66)
- [GFramework.Godot/coroutine/GodotTimeSource.cs](file://GFramework.Godot/coroutine/GodotTimeSource.cs#L9-L44)
### 资源管理与UI注册
- GodotFileStorage
- Delete/Exists/Read/Write支持res://、user://与普通路径
- 使用key级锁保证线程安全
- ToAbsolutePath处理路径规范化与校验
- GodotSceneRegistry/GodotUiRegistry
- 基于键值注册表，以字符串为键、PackedScene为值
- GodotUiFactory
- 支持三种实例策略：AlwaysCreate、Reuse、Pooled
- 预加载、回收、统计与淘汰（LRU/LFU），并维护实例追踪与访问时间/计数
```mermaid
classDiagram
class GodotFileStorage {
-ConcurrentDictionary~string,object~ _keyLocks
-ISerializer _serializer
+Delete(key)
+Exists(key)
+Read~T~(key)
+Write~T~(key, value)
}
class GodotSceneRegistry {
+继承KeyValueRegistryBase~string, PackedScene~
}
class GodotUiRegistry {
+继承KeyValueRegistryBase~string, PackedScene~
}
class GodotUiFactory {
-Dictionary~string,Queue~ _cachedInstances
-Dictionary~string,HashSet~ _allInstances
-Dictionary~string,UiCacheConfig~ _cacheConfigs
-Dictionary~string,List~ _accessTimeQueue
-Dictionary~IUiPageBehavior,int~ _accessCount
+GetOrCreate(uiKey, policy)
+Create(uiKey)
+Preload(uiKey, count)
+Recycle(page)
+GetCacheConfig(uiKey)
+SetCacheConfig(uiKey, config)
+ClearCache(uiKey)
+ClearAllCache()
+HasCached(uiKey)
+GetCacheStatistics()
}
GodotUiFactory --> GodotUiRegistry : "依赖"
GodotFileStorage --> GodotPathExtensions : "路径判断"
```
图表来源
- [GFramework.Godot/storage/GodotFileStorage.cs](file://GFramework.Godot/storage/GodotFileStorage.cs#L15-L291)
- [GFramework.Godot/scene/GodotSceneRegistry.cs](file://GFramework.Godot/scene/GodotSceneRegistry.cs#L11-L12)
- [GFramework.Godot/ui/GodotUiRegistry.cs](file://GFramework.Godot/ui/GodotUiRegistry.cs#L11-L12)
- [GFramework.Godot/ui/GodotUiFactory.cs](file://GFramework.Godot/ui/GodotUiFactory.cs#L16-L463)
- [GFramework.Godot/extensions/GodotPathExtensions.cs](file://GFramework.Godot/extensions/GodotPathExtensions.cs#L3-L22)
章节来源
- [GFramework.Godot/storage/GodotFileStorage.cs](file://GFramework.Godot/storage/GodotFileStorage.cs#L15-L291)
- [GFramework.Godot/scene/GodotSceneRegistry.cs](file://GFramework.Godot/scene/GodotSceneRegistry.cs#L11-L12)
- [GFramework.Godot/ui/GodotUiRegistry.cs](file://GFramework.Godot/ui/GodotUiRegistry.cs#L11-L12)
- [GFramework.Godot/ui/GodotUiFactory.cs](file://GFramework.Godot/ui/GodotUiFactory.cs#L16-L463)
### 源码生成器与模块标记
- GodotModuleMarker
- 作为Godot模块命名空间的占位类型，便于生成器识别与扫描
- 使用建议
- 在Godot模块所在命名空间引入该类型，确保生成器扫描到模块类型
- 与AbstractGodotModule配合，实现模块的自动发现与装配（如通过生成器扩展）
章节来源
- [GFramework.Godot.SourceGenerators.Abstractions/GodotModuleMarker.cs](file://GFramework.Godot.SourceGenerators.Abstractions/GodotModuleMarker.cs#L1-L6)
## 依赖关系分析
- 架构层
- AbstractArchitecture依赖ArchitectureAnchor进行生命周期绑定
- 通过IGodotModule约束模块行为，模块通过AbstractGodotModule实现
- 扩展层
- NodeExtensions广泛被模块与控制器使用，提供安全的节点操作
- SignalBuilder依赖NodeExtensions的Ready等待与生命周期绑定能力
- 资源与UI
- GodotUiFactory依赖GodotUiRegistry/GodotSceneRegistry进行场景实例化
- GodotFileStorage依赖GodotPathExtensions进行路径判断
- 协程与时间
- CoroutineExtensions依赖GodotTimeSource推进时间，Timing用于节点存活检测与协程调度
```mermaid
graph LR
AA["AbstractArchitecture"] --> AN["ArchitectureAnchor"]
AA --> IAM["IGodotModule"]
IAM --> AGM["AbstractGodotModule"]
NE["NodeExtensions"] --> AA
NE --> SB["SignalBuilder"]
GFS["GodotFileStorage"] --> GPE["GodotPathExtensions"]
GUF["GodotUiFactory"] --> GUIR["GodotUiRegistry"]
GUF --> GSR["GodotSceneRegistry"]
CE["CoroutineExtensions"] --> GTS["GodotTimeSource"]
```
图表来源
- [GFramework.Godot/architecture/AbstractArchitecture.cs](file://GFramework.Godot/architecture/AbstractArchitecture.cs#L14-L140)
- [GFramework.Godot/architecture/AbstractGodotModule.cs](file://GFramework.Godot/architecture/AbstractGodotModule.cs#L11-L55)
- [GFramework.Godot/architecture/IGodotModule.cs](file://GFramework.Godot/architecture/IGodotModule.cs#L10-L27)
- [GFramework.Godot/extensions/NodeExtensions.cs](file://GFramework.Godot/extensions/NodeExtensions.cs#L8-L259)
- [GFramework.Godot/extensions/signal/SignalBuilder.cs](file://GFramework.Godot/extensions/signal/SignalBuilder.cs#L10-L65)
- [GFramework.Godot/storage/GodotFileStorage.cs](file://GFramework.Godot/storage/GodotFileStorage.cs#L15-L291)
- [GFramework.Godot/extensions/GodotPathExtensions.cs](file://GFramework.Godot/extensions/GodotPathExtensions.cs#L3-L22)
- [GFramework.Godot/ui/GodotUiRegistry.cs](file://GFramework.Godot/ui/GodotUiRegistry.cs#L11-L12)
- [GFramework.Godot/scene/GodotSceneRegistry.cs](file://GFramework.Godot/scene/GodotSceneRegistry.cs#L11-L12)
- [GFramework.Godot/ui/GodotUiFactory.cs](file://GFramework.Godot/ui/GodotUiFactory.cs#L16-L463)
- [GFramework.Godot/coroutine/CoroutineExtensions.cs](file://GFramework.Godot/coroutine/CoroutineExtensions.cs#L7-L66)
- [GFramework.Godot/coroutine/GodotTimeSource.cs](file://GFramework.Godot/coroutine/GodotTimeSource.cs#L9-L44)
## 性能考量
- 节点安全与延迟调用
- 使用QueueFreeX/Freex避免在当前帧直接释放导致的不稳定
- AddChildX/WaitUntilReady确保子节点就绪再继续逻辑
- 协程与时间源
- GodotTimeSource按帧推进，避免额外时间轮询开销
- CancelWith在节点销毁时自动取消协程，减少无效执行
- 资源与UI
- GodotFileStorage使用key级锁，降低并发冲突
- GodotUiFactory的预加载与缓存策略（LRU/LFU）减少频繁实例化成本
- 路径处理
- GodotPathExtensions快速判断路径类型，避免不必要的IO开销
## 故障排查指南
- 模块未安装或节点未就绪
- 症状：模块节点未出现在场景树或未触发OnAttach
- 排查：确认InstallGodotModule调用顺序与锚点Ready状态
- 节点释放异常
- 症状：QueueFree后仍访问节点引发异常
- 排查：使用QueueFreeX/Freex，避免重复释放
- 信号泄漏
- 症状：节点销毁后仍收到信号回调
- 排查：使用SignalBuilder链路或UnRegisterWhenNodeExitTree确保自动解绑
- 协程未停止
- 症状：节点销毁后协程仍在运行
- 排查：在协程中使用CancelWith(node)，或在模块OnDetach中显式取消
- 资源路径错误
- 症状：读写失败或找不到文件
- 排查：使用GodotPathExtensions判断路径类型，确保res://或user://格式正确
章节来源
- [GFramework.Godot/architecture/AbstractArchitecture.cs](file://GFramework.Godot/architecture/AbstractArchitecture.cs#L100-L119)
- [GFramework.Godot/extensions/NodeExtensions.cs](file://GFramework.Godot/extensions/NodeExtensions.cs#L14-L46)
- [GFramework.Godot/extensions/signal/SignalBuilder.cs](file://GFramework.Godot/extensions/signal/SignalBuilder.cs#L31-L55)
- [GFramework.Godot/coroutine/CoroutineExtensions.cs](file://GFramework.Godot/coroutine/CoroutineExtensions.cs#L23-L54)
- [GFramework.Godot/storage/GodotFileStorage.cs](file://GFramework.Godot/storage/GodotFileStorage.cs#L40-L66)
## 结论
GFramework.Godot通过AbstractArchitecture与ArchitectureAnchor实现了与Godot生命周期的无缝绑定，模块系统以IGodotModule/AbstractGodotModule为核心，提供清晰的安装、附加与分离流程。配套的NodeExtensions、SignalBuilder、GodotFileStorage、GodotUiFactory与协程时间源共同构成完整的平台适配能力，既保持了GFramework的强类型与架构一致性，又充分发挥Godot在节点系统、信号与场景管理方面的优势。
## 附录
### 项目集成流程与最佳实践
- 架构集成
- 继承AbstractArchitecture，重写Init与InstallModules
- 在InstallModules中调用InstallGodotModule安装Godot模块
- 模块开发
- 继承AbstractGodotModule，实现Node与Install
- 在OnAttach中初始化模块逻辑，在OnDetach中清理
- 节点与信号
- 使用NodeExtensions进行安全节点操作
- 使用SignalBuilder进行流畅信号连接与生命周期绑定
- 资源与UI
- 使用GodotFileStorage进行跨路径读写
- 使用GodotUiFactory的缓存与预加载策略提升UI切换性能
- 协程与时间
- 使用RunCoroutine启动协程，使用CancelWith在节点销毁时自动取消
- 使用GodotTimeSource与框架时间源保持一致
章节来源
- [GFramework.Godot/README.md](file://GFramework.Godot/README.md#L66-L200)
### 从其他平台移植到Godot的迁移指南
- 架构层
- 将平台无关的模型、系统、工具注册逻辑迁移至AbstractArchitecture.Init
- 将平台特定的模块封装为AbstractGodotModule并使用InstallGodotModule安装
- 资源与存储
- 将文件读写抽象映射到GodotFileStorage，注意res://与user://路径差异
- UI与场景
- 将UI页面注册到GodotUiRegistry/GodotSceneRegistry，使用GodotUiFactory进行实例化与缓存
- 事件与信号
- 将事件系统与Godot信号桥接，使用SignalBuilder进行连接与自动解绑
- 协程与时间
- 将异步等待与延时替换为Godot协程与GodotTimeSource推进
章节来源
- [GFramework.Godot/README.md](file://GFramework.Godot/README.md#L200-L893)
Reference in New Issue View Git Blame Copy Permalink