mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-03-25 21:34:28 +08:00
a79f02c987
- 新增 Core API 参考文档，涵盖架构与模块、数据模型与系统、命令与查询等核心组件 - 添加事件系统接口详细文档，包括 IEvent、IEventBus、IUnRegister 等接口说明 - 提供完整的 API 使用示例路径、最佳实践与性能建议 - 包含架构图、依赖关系图与故障排查指南 - 添加测试用例参考与扩展方法说明 - [skip ci]
15 KiB
15 KiB
IGodotModule接口规范
**本文档引用的文件** - [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) - [IArchitectureModule.cs](file://GFramework.Core.Abstractions/architecture/IArchitectureModule.cs) - [IArchitectureLifecycle.cs](file://GFramework.Core.Abstractions/architecture/IArchitectureLifecycle.cs) - [IArchitecturePhaseAware.cs](file://GFramework.Core.Abstractions/architecture/IArchitecturePhaseAware.cs) - [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs) - [ArchitecturePhase.cs](file://GFramework.Core.Abstractions/enums/ArchitecturePhase.cs) - [NodeExtensions.cs](file://GFramework.Godot/extensions/NodeExtensions.cs) - [UnRegisterExtension.cs](file://GFramework.Godot/extensions/UnRegisterExtension.cs) - [godot-integration.md](file://docs/tutorials/godot-integration.md) - [godot-api.md](file://docs/api-reference/godot-api.md) - [AbstractModule.cs](file://GFramework.Game/architecture/AbstractModule.cs)目录
简介
IGodotModule接口是GFramework中Godot引擎模块化架构的核心接口，它定义了Godot引擎中模块的基本行为和属性。该接口继承自IArchitectureModule接口，专门为Godot引擎的节点系统设计，提供了模块与Godot场景树的深度集成能力。
IGodotModule接口的设计理念基于以下原则：
- 节点优先：模块通过Node属性直接暴露Godot节点，实现与场景树的无缝集成
- 生命周期管理：通过Install、OnAttach、OnDetach方法提供完整的模块生命周期控制
- 架构解耦：模块通过IArchitecture接口与架构交互，保持松耦合设计
- 异步支持：支持异步模块安装和节点管理
项目结构
GFramework的Godot模块系统采用分层架构设计，主要包含以下核心层次：
graph TB
subgraph "接口层"
IArch["IArchitectureModule"]
IGodot["IGodotModule"]
ILife["IArchitectureLifecycle"]
IPhase["IArchitecturePhaseAware"]
end
subgraph "抽象实现层"
AbsMod["AbstractModule"]
AbsGodot["AbstractGodotModule"]
AbsArch["AbstractArchitecture"]
end
subgraph "具体实现层"
Arch["Architecture"]
Anchor["ArchitectureAnchor"]
NodeExt["NodeExtensions"]
end
subgraph "Godot集成层"
AudioMod["AudioModule示例"]
UIReg["UI注册表"]
SceneReg["场景注册表"]
end
IArch --> IGodot
IArch --> ILife
IArch --> IPhase
AbsMod --> IArch
AbsGodot --> IGodot
AbsArch --> AbsGodot
Arch --> AbsArch
AbsGodot --> Anchor
Anchor --> NodeExt
IGodot --> AudioMod
AbsArch --> UIReg
AbsArch --> SceneReg
图表来源
章节来源
核心组件
IGodotModule接口定义
IGodotModule接口是Godot模块系统的核心，定义了模块与Godot引擎交互的标准契约：
classDiagram
class IGodotModule {
<<interface>>
+Node Node
+Install(architecture) void
+OnAttach(architecture) void
+OnDetach() void
}
class IArchitectureModule {
<<interface>>
+Install(architecture) void
+OnPhase(phase, architecture) void
+OnArchitecturePhase(phase) void
}
class IArchitectureLifecycle {
<<interface>>
+OnPhase(phase, architecture) void
}
class IArchitecturePhaseAware {
<<interface>>
+OnArchitecturePhase(phase) void
}
IArchitectureModule --|> IArchitectureLifecycle
IArchitectureModule --|> IArchitecturePhaseAware
IGodotModule --|> IArchitectureModule
图表来源
关键方法职责说明
Node属性
- 职责：返回模块关联的Godot节点实例
- 实现要求：必须返回有效的Godot Node对象
- 使用场景：作为模块在场景树中的可视化表现
Install方法
- 职责：将模块安装到指定的架构中
- 调用时机：在架构初始化过程中自动调用
- 实现要求：注册系统、工具等架构组件
OnAttach方法
- 职责：当模块被附加到架构时调用
- 调用时机：模块节点添加到场景树后调用
- 实现要求：执行模块的初始化逻辑
OnDetach方法
- 职责：当模块从架构分离时调用
- 调用时机：架构销毁或模块卸载时调用
- 实现要求：执行清理和资源释放
章节来源
架构概览
GFramework的Godot模块架构采用分层设计，通过AbstractArchitecture类管理模块的生命周期和节点管理：
sequenceDiagram
participant App as 应用程序
participant Arch as AbstractArchitecture
participant Mod as IGodotModule
participant Anchor as ArchitectureAnchor
participant Tree as Godot场景树
App->>Arch : Init()
Arch->>Arch : AttachToGodotLifecycle()
Arch->>Anchor : 创建锚点节点
Anchor->>Tree : 添加到场景树
App->>Arch : InstallModules()
Arch->>Mod : Install(this)
Mod-->>Arch : 安装完成
Arch->>Anchor : WaitUntilReady()
Anchor-->>Arch : 准备就绪
Arch->>Tree : AddChild(Mod.Node)
Tree-->>Mod : 节点添加完成
Arch->>Mod : OnAttach(this)
Mod-->>Arch : 附加完成
Note over Arch,Mod : 模块正常运行中
App->>Arch : Destroy()
Arch->>Mod : OnDetach()
Mod-->>Arch : 清理完成
Arch->>Tree : 移除锚点节点
图表来源
架构锚点机制
ArchitectureAnchor类是Godot模块系统的关键组件，它提供了以下功能：
- 生命周期绑定：通过_bind方法绑定节点退出时的回调
- 资源清理：在节点从场景树移除时执行清理操作
- 异步支持：提供WaitUntilReady方法支持异步节点管理
章节来源
详细组件分析
AbstractGodotModule抽象基类
AbstractGodotModule提供了IGodotModule接口的完整实现，包含以下特性：
classDiagram
class AbstractGodotModule {
<<abstract>>
+Node Node*
+Install(architecture)*
+OnAttach(architecture)
+OnDetach()
+OnPhase(phase, architecture)
+OnArchitecturePhase(phase)
}
class AbstractModule {
+Install(architecture)*
+OnPhase(phase, architecture)
+OnArchitecturePhase(phase)
}
class IGodotModule {
<<interface>>
+Node Node
+Install(architecture)
+OnAttach(architecture)
+OnDetach()
}
AbstractGodotModule --|> IGodotModule
AbstractModule --|> IArchitectureModule
AbstractGodotModule --|> AbstractModule
图表来源
模块安装流程
模块的安装过程遵循严格的生命周期管理：
flowchart TD
Start([开始安装]) --> CheckAnchor["检查架构锚点"]
CheckAnchor --> AnchorReady{"锚点已准备?"}
AnchorReady --> |否| ThrowError["抛出异常"]
AnchorReady --> |是| CallInstall["调用Install方法"]
CallInstall --> WaitReady["等待锚点就绪"]
WaitReady --> AddChild["添加模块节点到场景树"]
AddChild --> CallAttach["调用OnAttach方法"]
CallAttach --> AddToList["添加到扩展列表"]
AddToList --> Complete([安装完成])
ThrowError --> End([结束])
Complete --> End
图表来源
节点管理机制
GFramework提供了完善的节点管理机制，包括：
节点生命周期管理
- QueueFreeX：安全的节点释放方法，避免在当前帧中直接删除
- WaitUntilReady：异步等待节点进入场景树
- IsValidNode：检查节点的有效性状态
节点操作扩展
- AddChildX：异步添加子节点并等待准备就绪
- FindChildX：类型安全的子节点查找
- GetOrCreateNode：智能的节点获取或创建
章节来源
事件清理机制
GFramework提供了自动化的事件清理机制，确保节点退出时的资源正确释放：
sequenceDiagram
participant Node as Godot节点
participant Ext as UnRegisterExtension
participant Listener as 事件监听器
participant Bus as 事件总线
Node->>Ext : RegisterEvent(event).UnRegisterWhenNodeExitTree(this)
Ext->>Node : 订阅TreeExiting事件
Node->>Listener : 注册事件处理
Note over Node,Bus : 事件正常传递
Node->>Node : 从场景树移除
Node->>Ext : 触发TreeExiting事件
Ext->>Listener : 调用UnRegister()
Listener-->>Bus : 从事件总线注销
Note over Node,Bus : 资源清理完成
图表来源
章节来源
依赖关系分析
GFramework的Godot模块系统具有清晰的依赖层次结构：
graph TB
subgraph "外部依赖"
Godot[Godot引擎]
CSharp[C#运行时]
end
subgraph "核心抽象层"
CoreAbstractions[GFramework.Core.Abstractions]
Enums[枚举定义]
Interfaces[接口定义]
end
subgraph "核心实现层"
Core[GFramework.Core]
Architecture[Architecture基类]
Events[事件系统]
end
subgraph "Godot集成层"
GodotAbstractions[GFramework.Godot.Abstractions]
GodotCore[GFramework.Godot]
Extensions[扩展方法]
end
subgraph "应用层"
GameAbstractions[GFramework.Game.Abstractions]
GameCore[GFramework.Game]
Modules[模块实现]
end
Godot --> GodotCore
CSharp --> CoreAbstractions
CoreAbstractions --> Core
Enums --> Core
Interfaces --> Core
Core --> GodotCore
Architecture --> GodotCore
Events --> GodotCore
GodotCore --> GameCore
Extensions --> GameCore
Modules --> GameCore
GameAbstractions --> GameCore
GameCore --> Modules
图表来源
关键依赖关系
- Godot引擎依赖：所有Godot模块都直接依赖Godot引擎的Node类
- 架构抽象依赖：模块通过IArchitecture接口与架构交互
- 生命周期管理依赖：模块依赖IArchitectureLifecycle接口进行阶段管理
- 事件系统依赖：模块通过事件系统与其他组件通信
章节来源
性能考虑
异步节点管理
GFramework通过异步机制优化节点管理性能：
- 延迟执行：使用CallDeferred方法避免阻塞主线程
- 异步等待：WaitUntilReady方法提供非阻塞的节点就绪检测
- 批量操作：支持多个模块的并发安装
内存管理优化
- 智能释放：QueueFreeX方法确保节点安全释放
- 引用清理：自动清理事件监听器和信号连接
- 缓存策略：合理使用对象池减少GC压力
架构阶段优化
通过ArchitecturePhase枚举实现模块的有序初始化，避免不必要的资源竞争。
故障排除指南
常见问题及解决方案
模块安装失败
问题描述：模块无法正确安装到架构中 可能原因：
- 架构锚点未正确初始化
- 模块节点无效
- 架构已销毁
解决方法：
- 检查AbstractArchitecture的初始化过程
- 验证模块Node属性的有效性
- 确认架构状态
节点生命周期问题
问题描述：模块节点无法正确响应生命周期事件 可能原因：
- 事件监听器未正确注销
- 节点引用丢失
- 场景树状态异常
解决方法：
- 使用UnRegisterExtension确保事件正确清理
- 检查节点有效性检查
- 验证场景树状态
内存泄漏问题
问题描述：模块卸载后仍有内存占用 可能原因：
- 资源未正确释放
- 事件监听器未注销
- 对象循环引用
解决方法：
- 在OnDetach中执行完整清理
- 使用QueueFreeX安全释放节点
- 检查所有事件订阅的注销
章节来源
结论
IGodotModule接口规范为Godot引擎的模块化开发提供了清晰的架构指导。通过节点优先的设计理念、完整的生命周期管理和异步支持机制，该接口实现了模块与Godot场景树的深度集成。
关键设计要点包括：
- 明确的职责分离：接口定义清晰的方法职责
- 完善的生命周期管理：从安装到销毁的完整流程
- 异步编程支持：适应Godot的异步特性
- 资源安全保证：自动化的资源清理机制
该接口规范为开发者提供了可靠的模块化开发框架，有助于构建可维护、高性能的Godot游戏项目。
附录
接口实现最佳实践
设计模式推荐
- 模板方法模式：使用AbstractGodotModule提供默认实现
- 策略模式：通过不同的模块实现特定功能
- 观察者模式：利用事件系统实现松耦合通信
实现示例参考
完整的AudioModule实现示例可在以下文档中找到：
常见实现陷阱
- 过度耦合：避免直接依赖具体实现而非接口
- 资源泄漏：确保所有资源在OnDetach中正确释放
- 同步阻塞：避免在主线程中执行长时间操作
- 状态管理：不要在模块中存储全局状态