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]
13 KiB
13 KiB
AbstractGodotModule模块系统
**本文档引用的文件** - [AbstractGodotModule.cs](file://GFramework.Godot/architecture/AbstractGodotModule.cs) - [IGodotModule.cs](file://GFramework.Godot/architecture/IGodotModule.cs) - [AbstractArchitecture.cs](file://GFramework.Godot/architecture/AbstractArchitecture.cs) - [ArchitectureAnchor.cs](file://GFramework.Godot/architecture/ArchitectureAnchor.cs) - [AbstractModule.cs](file://GFramework.Game/architecture/AbstractModule.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) - [AbstractNodePoolSystem.cs](file://GFramework.Godot/pool/AbstractNodePoolSystem.cs) - [IPoolableNode.cs](file://GFramework.Godot/pool/IPoolableNode.cs) - [NodeExtensions.cs](file://GFramework.Godot/extensions/NodeExtensions.cs) - [godot-api.md](file://docs/api-reference/godot-api.md) - [godot-integration.md](file://docs/tutorials/godot-integration.md) - [architecture-patterns.md](file://docs/best-practices/architecture-patterns.md)目录
简介
AbstractGodotModule模块系统是GFramework在Godot引擎环境下实现的模块化架构解决方案。该系统通过抽象基类和接口定义，为Godot游戏开发提供了强大的模块化支持，实现了架构与具体Godot节点的深度集成。
该模块系统的核心设计理念是将传统的架构模块概念与Godot的节点树结构相结合，通过IGodotModule接口定义模块与Godot节点的关系，通过AbstractGodotModule抽象基类提供模块生命周期管理的基础实现。
项目结构
GFramework模块系统采用分层架构设计，主要包含以下核心层次：
graph TB
subgraph "核心抽象层"
A[IArchitectureModule]
B[IArchitectureLifecycle]
C[IArchitecturePhaseAware]
end
subgraph "Godot集成层"
D[IGodotModule]
E[AbstractGodotModule]
F[AbstractArchitecture]
G[ArchitectureAnchor]
end
subgraph "游戏业务层"
H[AbstractModule]
end
subgraph "基础设施层"
I[Architecture]
J[AbstractNodePoolSystem]
K[NodeExtensions]
end
A --> D
B --> E
C --> E
D --> E
E --> F
F --> G
H --> A
I --> A
J --> K
图表来源
章节来源
核心组件
模块接口体系
模块系统的核心接口定义了模块与架构之间的契约关系：
classDiagram
class IArchitectureModule {
<<interface>>
+Install(architecture) void
+OnPhase(phase, architecture) void
+OnArchitecturePhase(phase) void
}
class IGodotModule {
<<interface>>
+Node Node
+OnAttach(architecture) void
+OnDetach() void
}
class IArchitectureLifecycle {
<<interface>>
+OnPhase(phase, architecture) void
}
class IArchitecturePhaseAware {
<<interface>>
+OnArchitecturePhase(phase) void
}
IArchitectureModule --|> IArchitectureLifecycle
IArchitectureModule --|> IArchitecturePhaseAware
IGodotModule --|> IArchitectureModule
图表来源
模块基类实现
AbstractGodotModule作为Godot模块的抽象基类，提供了模块生命周期管理的核心功能：
章节来源
架构概览
AbstractArchitecture作为Godot架构的抽象实现，负责模块的安装、管理和生命周期控制：
sequenceDiagram
participant Client as 客户端代码
participant Arch as AbstractArchitecture
participant Module as IGodotModule
participant Anchor as ArchitectureAnchor
participant SceneTree as Godot场景树
Client->>Arch : InstallGodotModule(module)
Arch->>Module : Install(this)
Arch->>Arch : WaitUntilReady()
Arch->>Anchor : CallDeferred(AddChild, module.Node)
Arch->>Module : OnAttach(this)
Module-->>Arch : 模块就绪
Note over SceneTree,Anchor : 场景树销毁时
SceneTree->>Anchor : _ExitTree()
Anchor->>Arch : Destroy()
Arch->>Module : OnDetach() (逐个调用)
图表来源
章节来源
详细组件分析
AbstractGodotModule模块基类
AbstractGodotModule定义了Godot模块的核心行为规范：
关键特性
- 节点关联性: 通过Node属性明确模块与Godot节点的绑定关系
- 生命周期回调: 提供OnAttach和OnDetach方法处理模块的附加和分离
- 阶段感知: 支持架构阶段变化的通知机制
实现模式
flowchart TD
Start([模块创建]) --> Install["Install(architecture)"]
Install --> NodeCreation["创建/获取模块节点"]
NodeCreation --> Attach["OnAttach(architecture)"]
Attach --> Ready["模块就绪"]
Ready --> PhaseChange["架构阶段变化"]
PhaseChange --> Callback["OnPhase/OnArchitecturePhase"]
Ready --> Detach["OnDetach()"]
Detach --> Destroy["架构销毁"]
Destroy --> Cleanup["资源清理"]
Cleanup --> End([结束])
图表来源
章节来源
AbstractArchitecture架构管理
AbstractArchitecture负责Godot模块的完整生命周期管理：
核心功能
- 架构锚点管理: 通过ArchitectureAnchor确保模块节点正确绑定到Godot生命周期
- 异步模块安装: 提供InstallGodotModule方法实现模块的异步安装机制
- 资源清理: 在架构销毁时自动调用所有模块的OnDetach方法
安装流程
flowchart TD
A[调用InstallGodotModule] --> B[module.Install(this)]
B --> C{_anchor是否初始化?}
C --> |否| D[抛出InvalidOperationException]
C --> |是| E[await _anchor.WaitUntilReady()]
E --> F[CallDeferred(AddChild, module.Node)]
F --> G[module.OnAttach(this)]
G --> H[_extensions.Add(module)]
H --> I[安装完成]
图表来源
章节来源
ArchitectureAnchor锚点机制
ArchitectureAnchor作为Godot场景树的生命周期锚点：
设计原理
- 回调绑定: 通过Bind方法注册场景树销毁时的回调
- 安全释放: 在_exit_tree信号触发时执行清理操作
- 警告机制: 防止重复绑定导致的回调覆盖
章节来源
模块节点管理策略
节点创建与管理
模块节点的创建遵循以下策略：
- 延迟添加: 使用CallDeferred确保节点在下一帧添加到场景树
- 父子关系: 模块节点作为架构锚点的子节点管理
- 资源清理: 通过QueueFree方法安全释放节点资源
对象池集成
classDiagram
class AbstractNodePoolSystem {
<<abstract>>
+LoadScene(key) PackedScene
+Create(key) TNode
}
class IPoolableNode {
<<interface>>
+AsNode() Node
}
class Node {
<<Godot>>
}
AbstractNodePoolSystem --> IPoolableNode
IPoolableNode --> Node
图表来源
章节来源
依赖关系分析
模块间通信机制
模块系统采用事件驱动的松耦合通信方式：
graph LR
subgraph "模块A"
A1[CombatModule]
A2[CombatSystem]
end
subgraph "模块B"
B1[AudioModule]
B2[AudioSystem]
end
subgraph "事件总线"
E1[EventBus]
end
A2 --> |发送事件| E1
E1 --> |接收事件| B2
B2 -.->|播放音效| A2
图表来源
依赖注入与解耦
模块系统通过依赖注入实现组件间的解耦：
章节来源
性能考虑
异步安装优化
- 延迟执行: 使用CallDeferred避免阻塞当前帧
- 等待机制: WaitUntilReady确保节点完全初始化后再进行操作
- 批量处理: 支持多个模块的并发安装
内存管理
- 对象池: 通过AbstractNodePoolSystem减少节点创建开销
- 资源清理: 自动调用OnDetach确保资源及时释放
- 垃圾回收: 使用QueueFree替代直接删除
最佳实践
- 模块职责单一: 每个模块专注于特定功能领域
- 事件驱动通信: 避免模块间直接依赖
- 异步处理: 大量计算或IO操作使用异步模式
故障排除指南
常见问题与解决方案
模块安装失败
问题: 模块安装时报"Anchor not initialized"错误 原因: 架构锚点未正确初始化 解决: 确保在架构初始化完成后调用InstallGodotModule
资源泄漏问题
问题: 模块分离后资源未正确释放 原因: 未正确实现OnDetach方法 解决: 在OnDetach中调用QueueFree清理节点
生命周期冲突
问题: 模块在错误时机访问资源 解决: 使用WaitUntilReady确保节点准备就绪
章节来源
结论
AbstractGodotModule模块系统通过精心设计的架构，成功地将传统架构模块概念与Godot引擎的节点树结构相结合。该系统提供了：
- 清晰的模块边界: 通过IGodotModule接口明确定义模块与Godot节点的关系
- 完善的生命周期管理: 支持模块的安装、附加、分离和销毁
- 异步安装机制: 通过ArchitectureAnchor确保模块节点的正确初始化
- 事件驱动通信: 通过事件总线实现模块间的松耦合通信
- 资源安全管理: 自动化的资源清理和内存管理
该系统为Godot游戏开发提供了强大而灵活的模块化基础，开发者可以基于此架构快速构建复杂的游戏系统。
附录
开发示例
创建自定义Godot模块
[ContextAware]
[Log]
public partial class CustomModule : AbstractGodotModule
{
private AudioStreamPlayer _audioPlayer;
public override Node Node => this;
public override void Install(IArchitecture architecture)
{
// 注册系统和工具
architecture.RegisterSystem(new CustomSystem());
architecture.RegisterUtility(new CustomUtility());
}
public override void OnAttach(Architecture architecture)
{
// 创建模块节点
_audioPlayer = new AudioStreamPlayer();
AddChild(_audioPlayer);
}
public override void OnDetach(Architecture architecture)
{
// 清理资源
_audioPlayer?.QueueFree();
}
public override void OnPhase(ArchitecturePhase phase, IArchitecture architecture)
{
switch (phase)
{
case ArchitecturePhase.Ready:
PlayStartupSound();
break;
}
}
}
章节来源
模块开发最佳实践
- 单一职责原则: 每个模块专注于特定功能
- 事件驱动设计: 通过事件与其他模块通信
- 异步处理: 大量操作使用异步模式
- 资源管理: 确保OnDetach中正确清理资源
- 错误处理: 实现健壮的错误恢复机制