GFramework

专为游戏开发场景设计的综合性C#游戏开发框架，Core 模块与平台无关

本项目参考(CV)自QFramework，并进行了模块化重构和功能增强。

🚀 快速导航

📚 学习路径

🎯 新手入门

1. 📚 从零开始教程 - 完整的项目创建和开发指南
2. 📖 基本概念 - 理解核心概念
3. 💡 快速示例 - 5分钟上手体验

🏗️ 进阶开发

4. 📖 Godot 集成教程 - 深度 Godot 集成和最佳实践
5. ⚡ 高级模式教程 - CQRS、事件溯源、插件系统等
6. 🏗️ 架构模式最佳实践 - 推荐的架构设计模式
7. 🏗️ 性能优化技巧 - 内存和性能优化

🏗️ 专家指南

8. 📊 API 参考 - 详细的类和接口说明

📖 详细文档

🏛️ 核心项目 Core Projects

• 📖 GFramework.Core - 核心框架功能，架构、事件、命令、查询等（平台无关）
• [📖 GFramework.Core.Abstractions - 核心接口定义
• [📖 GFramework.Game - 游戏特定抽象和系统
• [📖 GFramework.Game.Abstractions - 游戏抽象接口定义
• [📖 GFramework.Godot - Godot 特定实现（Node扩展、GodotLogger 等）
• [📖 GFramework.SourceGenerators - 通用源代码生成器
• [📖 GFramework.Godot.SourceGenerators - Godot 特定的代码生成器

📖 源代码生成器 Source Generators

• [📖 日志生成器 - 自动 ILogger 字段生成
• [📖 上下文感知生成器 - 自动 IContextAware 实现
• [📖 枚举扩展生成器 - 自动枚举扩展方法

📖 API 参考

• [📖 Core API 参考 - 核心类和接口详细说明
• [📖 Godot API 参考 - Godot 模块 API 详细说明
• [📖 Source Generators API 参考 - 源码生成器 API 详细说明
• [📖 Game API 参考 - Game 模块 API 详细说明

🏗️ 教程和指南

• [🏗️ 架构模式最佳实践 - 推荐的架构设计模式
• [🏗️ 性能优化技巧 - 内存和性能优化

🏗️ 常见问题解决

• [🏗️ 错误处理策略 - 异常处理和错误恢复
• [🏗️ 调试技巧 - 调试和测试指南

✨ 主要特性

🏗️ 核心架构 Core Architecture

• 依赖注入 Dependency Injection: 内置IoC容器管理对象生命周期
• 事件系统 Event System: 类型安全的事件系统，实现松耦合
• 属性绑定 Property Binding: 可绑定属性，支持响应式编程
• 日志框架 Logging Framework: 结构化日志，支持多个日志级别
• 生命周期管理 Lifecycle Management: 阶段式的架构生命周期管理
• 命令查询分离 CQRS: 命令和查询的职责分离

🎮 游戏开发特性 Game Development Features

• 资产管理 Asset Management: 集中化资产目录系统
• 资源工厂 Resource Factory: 工厂模式的资源创建模式
• 架构模式 Architecture Pattern: 关注点分离的清晰架构
• 模块化 Module System: 支持架构模块安装和扩展
• 源码生成 Source Generators: 零运行时开销的代码生成

🌐 平台无关 Platform Agnostic

• 纯 .NET 实现: Core 模块无任何平台特定依赖
• Godot 集成 Godot Integration: GFramework.Godot 提供 Godot 特定功能
• 可移植 Portable: 可以轻松移植到 Unity、.NET MAUI 等平台

🚀 快速开始 Getting Started

1️⃣ 安装 Installation

# 安装核心包（平台无关）
dotnet add package GeWuYou.GFramework.Core
dotnet add package GeWuYou.GFramework.Core.Abstractions

# 安装游戏包
dotnet add package GeWuYou.GFramework.Game
dotnet add package GeWuYou.GFramework.Game.Abstractions

# 安装源码生成器（推荐）
dotnet add package GeWuYou.GFramework.SourceGenerators
dotnet add package GeWuYou.GFramework.SourceGenerators.Attributes

# 安装Godot包（仅Godot项目需要）
dotnet add package GeWuYou.GFramework.Godot

2️⃣ 基本使用 Basic Usage

using GFramework.Core.architecture;
using GFramework.SourceGenerators.Attributes;

// 1. 定义架构（继承 Architecture 基类）
public class GameArchitecture : Architecture
{
    protected override void Init()
    {
        // 注册 Model - 游戏数据
        RegisterModel(new PlayerModel());
        RegisterModel(new GameModel());
        
        // 注册 System - 业务逻辑
        RegisterSystem(new CombatSystem());
        RegisterSystem(new UISystem());
        
        // 注册 Utility - 工具类
        RegisterUtility(new StorageUtility());
    }
}

// 2. 创建并初始化架构
var architecture = new GameArchitecture();
architecture.Initialize();

// 3. 通过依赖注入在Controller中使用
[Log]
[ContextAware]
public partial class PlayerController : IController
{
    private PlayerModel _playerModel;
    
    public PlayerController(IArchitecture architecture)
    {
        _playerModel = architecture.GetModel<PlayerModel>();
    }
    
    // 监听属性变化
    public void Initialize()
    {
        _playerModel.Health.RegisterWithInitValue(hp => UpdateHealthDisplay(hp));
    }
    
    private void UpdateHealthDisplay(int hp)
    {
        // 更新 UI 显示
        Console.WriteLine($"Health: {hp}");
    }
}

3️⃣ 命令和查询 Command & Query

// 定义命令
public class AttackCommand : AbstractCommand
{
    protected override void OnExecute()
    {
        var playerModel = this.GetModel<PlayerModel>();
        var enemyModel = this.GetModel<EnemyModel>();
        
        // 业务逻辑
        int damage = playerModel.AttackPower.Value;
        enemyModel.Health.Value -= damage;
        
        // 发送事件
        this.SendEvent(new DamageDealtEvent { Damage = damage });
    }
}

// 定义查询
public class CanAttackQuery : AbstractQuery<bool>
{
    protected override bool OnDo()
    {
        var playerModel = this.GetModel<PlayerModel>();
        return playerModel.Health.Value > 0 && !playerModel.IsStunned.Value;
    }
}

// 使用命令和查询
public class CombatController : IController
{
    private readonly IArchitecture _architecture;
    
    public CombatController(IArchitecture architecture)
    {
        _architecture = architecture;
    }
    
    public void OnAttackButtonPressed()
    {
        // 先查询
        if (_architecture.SendQuery(new CanAttackQuery()))
        {
            // 再执行命令
            _architecture.SendCommand(new AttackCommand());
        }
    }
}

4️⃣ 事件系统 Event System

// 定义事件
public struct DamageDealtEvent
{
    public int Damage;
    public Vector3 Position;
}

// 发送事件
this.SendEvent(new DamageDealtEvent { Damage = 100, Position = position });

// 注册事件监听
this.RegisterEvent<DamageDealtEvent>(OnDamageDealt);

private void OnDamageDealt(DamageDealtEvent e)
{
    ShowDamageNumber(e.Damage, e.Position);
}

📦 项目架构 Architecture

框架遵循清洁架构原则，具有以下层次：

┌─────────────────────────────────────────┐
│           View / UI                      │  UI 层：用户界面
├─────────────────────────────────────────┤
│            Controller                    │  控制层：处理用户输入
├─────────────────────────────────────────┤
│             System                       │ 逻辑层：业务逻辑
├─────────────────────────────────────────┤
│              Model                       │  数据层：游戏状态
├─────────────────────────────────────────┤
│             Utility                      │  工具层：无状态工具
├─────────────────────────────────────────┤
│         Command / Query                  │  横切关注点
└─────────────────────────────────┘

🔧 平台集成 Platform Integration

Godot 项目

// 使用 GFramework.Godot 获取 Godot 特定功能
using GFramework.Godot;

public class GodotPlayerController : Node, IController
{
    public IArchitecture GetArchitecture() => GameArchitecture.Interface;
    
    public override void _Ready()
    {
        // 使用 Godot 特定的扩展方法
        this.RegisterEvent<DamageDealtEvent>(OnDamageDealt)
            .UnRegisterWhenNodeExitTree(this);
    }
}

移植到其他平台

GFramework.Core 是纯 .NET 库，可以轻松移植到：

• Unity（使用 Unity 容器替代 Godot 节点）
• .NET MAUI（用于跨平台 UI 应用）
• 任何其他 .NET 应用

---

📖 版本历史 Version History

v1.0.0 (2026-01-12)

• ✅ 完整的文档体系创建完成
• ✅ 核心项目文档完善
• ✅ 源码生成器文档完成
• ✅ 最佳实践指南创建
• ✅ API 参考文档生成
• ✅ 从零开始教程完善

计划中的任务

• [📝 待完成任务] - 2 个低优先级任务
• [📝 进行中的任务] - 0 个

---

🎯 如果这个项目对你有帮助，请给我们一个 ⭐！

Fork 本仓库并创建 Pull Request
Report Issues 报告 Bug 或功能请求
Star 给我们一个 Star！

---

📚 文档统计

• 新增文档: 10+ 个文件
• 代码示例: 150+ 个可直接使用的代码片段
• 文档总量: 6000+ 行
• 覆盖项目: 100% 项目文档覆盖

---

许可证: Apache 2.0
更新日期: 2026-01-12