mirror of https://github.com/GeWuYou/GFramework.git synced 2026-03-26 06:16:43 +08:00

GeWuYou a79f02c987 docs(api): 添加 Core API 参考文档与事件系统接口文档

- 新增 Core API 参考文档，涵盖架构与模块、数据模型与系统、命令与查询等核心组件
- 添加事件系统接口详细文档，包括 IEvent、IEventBus、IUnRegister 等接口说明
- 提供完整的 API 使用示例路径、最佳实践与性能建议
- 包含架构图、依赖关系图与故障排查指南
- 添加测试用例参考与扩展方法说明
- [skip ci]

2026-01-21 23:45:10 +08:00

24 KiB

Raw Blame History

平台集成模块

**本文引用的文件** - [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)

引言

本文件面向希望在Godot引擎中集成GFramework平台的开发者，系统性阐述GFramework.Godot模块的设计与实现，覆盖架构适配、模块系统、节点扩展、信号处理、路径扩展、生命周期绑定、协程集成、资源与UI注册体系，以及源码生成器的使用与配置。同时提供从其他平台迁移到Godot的实践建议与注意事项。

项目结构

GFramework.Godot位于仓库的GFramework.Godot目录，围绕“架构适配 + 扩展能力 + 资源与UI管理 + 协程与时间源”的主题组织代码，采用按功能域分层的结构：

architecture：Godot架构适配与模块系统
extensions：节点扩展、信号构建器、路径扩展等
storage：Godot文件存储实现
scene/ui：场景与UI注册表、UI工厂
coroutine：协程扩展与时间源
SourceGenerators.Abstractions：Godot模块标记类型（用于生成器识别）

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/README.md

核心组件

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通过AbstractArchitecture将框架生命周期与Godot场景树绑定，使用ArchitectureAnchor作为根节点承载模块节点，确保节点退出场景树时自动清理。模块通过AbstractGodotModule实现安装、附加与分离回调，并在架构阶段变更时响应。

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

图表来源

组件详解

架构适配与模块系统

AbstractArchitecture
- 生成唯一锚点名称，避免重复挂载
- 通过AttachToGodotLifecycle在场景树根节点下创建ArchitectureAnchor并绑定Destroy回调
- InstallGodotModule负责安装模块、等待锚点就绪、将模块节点作为子节点添加，并调用OnAttach
- Destroy遍历已安装模块调用OnDetach并清空列表
AbstractGodotModule
- Node暴露模块关联的Godot节点
- Install定义模块安装逻辑
- OnAttach/OnDetach分别在模块附加/分离时回调
- OnPhase/OnArchitecturePhase响应架构阶段变化
IGodotModule
- 继承IArchitectureModule，要求Node、OnAttach、OnDetach
ArchitectureAnchor
- Bind记录退出回调，_ExitTree触发并清理

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 : 模块安装完成，随场景树销毁自动清理

图表来源

章节来源

节点扩展与信号处理

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

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

图表来源

章节来源

协程集成与时间源

CoroutineExtensions
- RunCoroutine：启动协程，支持Segment与tag
- CancelWith：在节点销毁时自动取消协程（单节点、双节点、多节点）
GodotTimeSource
- ITimeSource实现，提供CurrentTime/DeltaTime
- Update根据传入的增量时间函数推进时间，Reset重置

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

图表来源

章节来源

资源管理与UI注册

GodotFileStorage
- Delete/Exists/Read/Write支持res://、user://与普通路径
- 使用key级锁保证线程安全
- ToAbsolutePath处理路径规范化与校验
GodotSceneRegistry/GodotUiRegistry
- 基于键值注册表，以字符串为键、PackedScene为值
GodotUiFactory
- 支持三种实例策略：AlwaysCreate、Reuse、Pooled
- 预加载、回收、统计与淘汰（LRU/LFU），并维护实例追踪与访问时间/计数

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 : "路径判断"

图表来源

章节来源

源码生成器与模块标记

GodotModuleMarker
- 作为Godot模块命名空间的占位类型，便于生成器识别与扫描
使用建议
- 在Godot模块所在命名空间引入该类型，确保生成器扫描到模块类型
- 与AbstractGodotModule配合，实现模块的自动发现与装配（如通过生成器扩展）

章节来源

GFramework.Godot.SourceGenerators.Abstractions/GodotModuleMarker.cs

依赖关系分析

架构层
- AbstractArchitecture依赖ArchitectureAnchor进行生命周期绑定
- 通过IGodotModule约束模块行为，模块通过AbstractGodotModule实现
扩展层
- NodeExtensions广泛被模块与控制器使用，提供安全的节点操作
- SignalBuilder依赖NodeExtensions的Ready等待与生命周期绑定能力
资源与UI
- GodotUiFactory依赖GodotUiRegistry/GodotSceneRegistry进行场景实例化
- GodotFileStorage依赖GodotPathExtensions进行路径判断
协程与时间
- CoroutineExtensions依赖GodotTimeSource推进时间，Timing用于节点存活检测与协程调度

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"]

图表来源

性能考量

节点安全与延迟调用
- 使用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通过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

从其他平台移植到Godot的迁移指南

架构层
- 将平台无关的模型、系统、工具注册逻辑迁移至AbstractArchitecture.Init
- 将平台特定的模块封装为AbstractGodotModule并使用InstallGodotModule安装
资源与存储
- 将文件读写抽象映射到GodotFileStorage，注意res://与user://路径差异
UI与场景
- 将UI页面注册到GodotUiRegistry/GodotSceneRegistry，使用GodotUiFactory进行实例化与缓存
事件与信号
- 将事件系统与Godot信号桥接，使用SignalBuilder进行连接与自动解绑
协程与时间
- 将异步等待与延时替换为Godot协程与GodotTimeSource推进

章节来源

GFramework.Godot/README.md

24 KiB Raw Blame History Unescape Escape

平台集成模块

目录

引言

项目结构

核心组件

架构总览

组件详解

架构适配与模块系统

节点扩展与信号处理

协程集成与时间源

资源管理与UI注册

源码生成器与模块标记

依赖关系分析

性能考量

故障排查指南

结论

附录

项目集成流程与最佳实践

从其他平台移植到Godot的迁移指南

24 KiB

Raw Blame History