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]
14 KiB
14 KiB
Godot集成教程
**本文档引用的文件** - [GFramework.Godot/README.md](file://GFramework.Godot/README.md) - [GFramework.Godot/architecture/AbstractGodotModule.cs](file://GFramework.Godot/architecture/AbstractGodotModule.cs) - [GFramework.Godot/architecture/AbstractArchitecture.cs](file://GFramework.Godot/architecture/AbstractArchitecture.cs) - [GFramework.Godot/architecture/IGodotModule.cs](file://GFramework.Godot/architecture/IGodotModule.cs) - [GFramework.Godot/architecture/ArchitectureAnchor.cs](file://GFramework.Godot/architecture/ArchitectureAnchor.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/coroutine/CoroutineExtensions.cs](file://GFramework.Godot/coroutine/CoroutineExtensions.cs) - [GFramework.Godot/pool/AbstractNodePoolSystem.cs](file://GFramework.Godot/pool/AbstractNodePoolSystem.cs) - [GFramework.Godot/ui/GodotUiFactory.cs](file://GFramework.Godot/ui/GodotUiFactory.cs) - [GFramework.Godot/scene/GodotSceneRegistry.cs](file://GFramework.Godot/scene/GodotSceneRegistry.cs) - [GFramework.Godot/logging/GodotLogger.cs](file://GFramework.Godot/logging/GodotLogger.cs) - [docs/tutorials/godot-integration.md](file://docs/tutorials/godot-integration.md) - [docs/tutorials/getting-started.md](file://docs/tutorials/getting-started.md)目录
简介
本教程面向希望在Godot引擎中集成GFramework的开发者，提供从项目设置到高级特性的完整指导。GFramework.Godot将框架的架构优势与Godot引擎的节点系统、信号机制和场景管理能力深度融合，为开发者提供类型安全、性能优化且开发高效的解决方案。
项目结构
GFramework.Godot采用模块化架构设计，主要包含以下核心模块：
graph TB
subgraph "Godot集成层"
A[AbstractArchitecture] --> B[AbstractGodotModule]
A --> C[ArchitectureAnchor]
D[NodeExtensions] --> E[SignalBuilder]
F[CoroutineExtensions] --> G[GodotTimeSource]
H[GodotUiFactory] --> I[GodotSceneRegistry]
J[GodotLogger] --> K[GodotLoggerFactory]
end
subgraph "核心框架层"
L[Architecture] --> M[IArchitecture]
N[System] --> O[IContextUtility]
P[EventBus] --> Q[IEventBus]
R[CoroutineScheduler] --> S[IYieldInstruction]
end
A -.-> L
B -.-> N
H -.-> P
图表来源
- GFramework.Godot/architecture/AbstractArchitecture.cs
- GFramework.Godot/architecture/AbstractGodotModule.cs
章节来源
核心组件
AbstractGodotModule - Godot模块基类
AbstractGodotModule是Godot模块系统的核心抽象基类，定义了模块与Godot节点的集成接口：
classDiagram
class AbstractGodotModule {
<<abstract>>
+Node Node
+OnPhase(phase, architecture) void
+OnArchitecturePhase(phase) void
+Install(architecture) void
+OnDetach() void
+OnAttach(architecture) void
}
class IGodotModule {
<<interface>>
+Node Node
+OnAttach(architecture) void
+OnDetach() void
}
class AbstractArchitecture {
<<abstract>>
-IGodotModule[] _extensions
-ArchitectureAnchor _anchor
+InstallGodotModule~TModule~(module) Task
+Destroy() void
}
AbstractGodotModule ..|> IGodotModule
AbstractArchitecture --> AbstractGodotModule : "管理模块"
图表来源
章节来源
AbstractArchitecture - 架构生命周期管理
AbstractArchitecture负责将GFramework架构与Godot生命周期无缝集成：
sequenceDiagram
participant Scene as "Godot场景"
participant Arch as "AbstractArchitecture"
participant Anchor as "ArchitectureAnchor"
participant Module as "IGodotModule"
Scene->>Arch : Initialize()
Arch->>Arch : Init()
Arch->>Arch : AttachToGodotLifecycle()
Arch->>Anchor : 创建锚点节点
Anchor->>Scene : 添加到场景树
Arch->>Arch : InstallModules()
Arch->>Module : Install(this)
Arch->>Arch : WaitUntilReady()
Arch->>Anchor : AddChild(Module.Node)
Module->>Module : OnAttach(this)
Note over Scene,Module : 场景销毁时自动清理
Scene->>Anchor : _ExitTree()
Anchor->>Arch : Destroy()
Arch->>Module : OnDetach() 循环调用
图表来源
- GFramework.Godot/architecture/AbstractArchitecture.cs
- GFramework.Godot/architecture/ArchitectureAnchor.cs
章节来源
架构概览
Godot模块系统集成流程
GFramework.Godot提供完整的模块化架构系统，支持Godot特有的节点生命周期管理：
flowchart TD
Start([架构初始化]) --> CreateAnchor["创建ArchitectureAnchor"]
CreateAnchor --> InstallModules["安装Godot模块"]
InstallModules --> WaitReady["等待锚点就绪"]
WaitReady --> AddChild["添加模块节点到场景树"]
AddChild --> CallAttach["调用OnAttach回调"]
CallAttach --> Ready([模块就绪])
Ready --> SceneExit{"场景退出?"}
SceneExit --> |否| Ready
SceneExit --> |是| CallDetach["调用OnDetach回调"]
CallDetach --> Cleanup["清理模块资源"]
Cleanup --> End([架构销毁])
图表来源
- GFramework.Godot/architecture/AbstractArchitecture.cs
- GFramework.Godot/architecture/AbstractGodotModule.cs
章节来源
详细组件分析
节点扩展系统
GFramework.Godot提供50+个实用的Node扩展方法，大幅简化Godot开发中的常见操作：
安全节点操作扩展
flowchart TD
NodeOp[节点操作] --> ValidateNode{"节点有效?"}
ValidateNode --> |否| ReturnNull["返回null/跳过操作"]
ValidateNode --> |是| SafeOp["执行安全操作"]
SafeOp --> QueueFree["QueueFreeX"]
SafeOp --> Free["FreeX"]
SafeOp --> WaitReady["WaitUntilReady"]
SafeOp --> GetNode["GetNodeX/FindChildX"]
QueueFree --> Deferred["CallDeferred"]
Free --> Immediate["立即释放"]
WaitReady --> Signal["ToSignal Ready"]
GetNode --> Cast["类型转换"]
图表来源
章节来源
信号系统集成
SignalBuilder提供流畅的信号连接API，支持类型安全的信号管理：
SignalBuilder使用流程
sequenceDiagram
participant Controller as "控制器"
participant Builder as "SignalBuilder"
participant Target as "目标节点"
participant Handler as "事件处理器"
Controller->>Builder : CreateSignalBuilder(signal)
Builder->>Builder : WithFlags(flags)
Builder->>Builder : CallImmediately()
Builder->>Target : Connect(handler)
Target->>Handler : 触发信号
Handler->>Controller : 处理事件
Controller->>Builder : UnRegisterWhenNodeExitTree()
图表来源
章节来源
协程调度系统
GFramework.Godot的协程系统与Godot的生命周期深度集成：
协程取消机制
flowchart TD
Start([启动协程]) --> CheckNode{"节点存活?"}
CheckNode --> |是| MoveNext["执行MoveNext()"]
MoveNext --> YieldCurrent["yield return Current"]
YieldCurrent --> CheckNode
CheckNode --> |否| Cancel["自动取消协程"]
Cancel --> Cleanup["清理资源"]
Cleanup --> End([协程结束])
YieldCurrent --> Process["处理当前指令"]
Process --> CheckNode
图表来源
章节来源
UI系统架构
GodotUiFactory提供完整的UI页面管理功能，支持多种缓存策略：
UI实例管理流程
stateDiagram-v2
[*] --> 创建实例
创建实例 --> 预加载缓存 : Preload()
创建实例 --> 直接使用 : AlwaysCreate
创建实例 --> 复用缓存 : Reuse
预加载缓存 --> 等待使用
复用缓存 --> 等待使用
直接使用 --> 使用中
等待使用 --> 使用中 : GetOrCreate()
使用中 --> 回收到缓存 : Recycle()
使用中 --> 销毁实例 : ClearCache()
回收到缓存 --> 等待使用
销毁实例 --> [*]
图表来源
章节来源
资源管理系统
Godot场景注册表提供类型安全的场景管理功能：
章节来源
依赖关系分析
模块间依赖关系
graph TB
subgraph "外部依赖"
A[Godot Engine]
B[.NET Runtime]
end
subgraph "GFramework核心"
C[GFramework.Core]
D[GFramework.Core.Abstractions]
end
subgraph "游戏框架"
E[GFramework.Game]
F[GFramework.Game.Abstractions]
end
subgraph "Godot集成"
G[GFramework.Godot]
H[GFramework.Godot.Abstractions]
end
A --> G
B --> G
C --> G
D --> G
E --> G
F --> G
G --> H
图表来源
- GFramework.Godot/architecture/AbstractArchitecture.cs
- GFramework.Godot/architecture/AbstractGodotModule.cs
章节来源
性能考虑
节点池化策略
推荐使用AbstractNodePoolSystem管理高频创建的对象：
- 预加载场景：在初始化时预加载所有需要的场景
- 批量创建：使用Preload方法批量创建实例
- 智能回收：实现CanDespawn方法确保只有空闲实例被回收
- 缓存配置：根据UI类型设置合适的缓存大小和淘汰策略
资源管理优化
- 使用Godot的异步加载机制避免主线程阻塞
- 实现资源优先级队列，确保关键资源优先加载
- 定期清理未使用的资源，避免内存泄漏
故障排除指南
常见问题及解决方案
模块未正确初始化
问题：模块的OnAttach方法没有被调用 解决方案：
- 确保InstallGodotModule方法在InstallModules中正确调用
- 检查模块的Node属性返回有效的Godot节点
- 验证架构锚点已正确创建和添加到场景树
信号连接泄漏
问题：节点销毁后信号处理器仍在执行 解决方案：
- 使用UnRegisterWhenNodeExitTree方法自动清理
- 避免使用传统的+=事件订阅方式
- 确保所有信号连接都在节点生命周期内管理
协程取消问题
问题：协程在节点销毁后仍在运行 解决方案：
- 使用CancelWith扩展方法绑定节点生命周期
- 在协程中定期检查节点存活状态
- 实现适当的异常处理机制
章节来源
结论
GFramework.Godot为Godot引擎提供了深度集成的架构解决方案，通过模块化设计、类型安全的API和完善的生命周期管理，帮助开发者构建高性能、可维护的游戏应用。建议在实际项目中遵循模块化设计原则，合理使用节点池化和资源管理策略，并充分利用SignalBuilder等工具提升开发效率。
附录
快速开始模板
// 架构定义
public class MyGameArchitecture : AbstractArchitecture
{
protected override void InstallModules()
{
InstallGodotModule(new InputModule());
InstallGodotModule(new AudioManager());
}
}
// 模块实现
public partial class InputModule : AbstractGodotModule
{
public override Node Node => this;
public override void Install(IArchitecture architecture)
{
architecture.RegisterSystem(new InputSystem());
}
}
最佳实践清单
- 模块化设计：每个模块专注于单一功能领域
- 生命周期管理：始终使用自动清理机制
- 类型安全：利用GFramework的强类型特性
- 性能优化：合理使用池化和缓存策略
- 错误处理：实现完善的异常处理和日志记录