From bb971e98ae2516486cc67a9e3ffff000558e181e Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Thu, 5 Feb 2026 20:13:23 +0800 Subject: [PATCH] docs: rewrite root README for accuracy and structure --- README.md | 353 +++++++++--------------------------------------------- 1 file changed, 59 insertions(+), 294 deletions(-) diff --git a/README.md b/README.md index 17573d2..b0caf3a 100644 --- a/README.md +++ b/README.md @@ -1,332 +1,97 @@ # GFramework -> 专为游戏开发场景设计的综合性C#游戏开发框架，Core 模块与平台无关 +> 面向游戏开发场景的模块化 C# 框架，核心能力与具体引擎解耦，可按需组合 Core / Game / Godot / Source Generators。 -[![NuGet](https://img.shields.io/badge/NuGet-GeWuYou.GFramework-blue)](https://www.nuget.org/packages/GeWuYou.GFramework.Core/) +[![NuGet](https://img.shields.io/badge/NuGet-GeWuYou.GFramework-blue)](https://www.nuget.org/packages/GeWuYou.GFramework) [![Godot](https://img.shields.io/badge/Godot-4.5+-green)](https://godotengine.org/) [![.NET](https://img.shields.io/badge/.NET-6.0+-purple)](https://dotnet.microsoft.com/) [![License](https://img.shields.io/badge/License-Apache%202.0-blue)](LICENSE) -[![zread](https://img.shields.io/badge/Ask_Zread-_.svg?style=flat&color=00b0aa&labelColor=000000&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTQuOTYxNTYgMS42MDAxSDIuMjQxNTZDMS44ODgxIDEuNjAwMSAxLjYwMTU2IDEuODg2NjQgMS42MDE1NiAyLjI0MDFWNC45NjAxQzEuNjAxNTYgNS4zMTM1NiAxLjg4ODEgNS42MDAxIDIuMjQxNTYgNS42MDAxSDQuOTYxNTZDNS4zMTUwMiA1LjYwMDEgNS42MDE1NiA1LjMxMzU2IDUuNjAxNTYgNC45NjAxVjIuMjQwMUM1LjYwMTU2IDEuODg2NjQgNS4zMTUwMiAxLjYwMDEgNC45NjE1NiAxLjYwMDFaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00Ljk2MTU2IDEwLjM5OTlIMi4yNDE1NkMxLjg4ODEgMTAuMzk5OSAxLjYwMTU2IDEwLjY4NjQgMS42MDE1NiAxMS4wMzk5VjEzLjc1OTlDMS42MDE1NiAxNC4xMTM0IDEuODg4MSAxNC4zOTk5IDIuMjQxNTYgMTQuMzk5OUg0Ljk2MTU2QzUuMzE1MDIgMTQuMzk5OSA1LjYwMTU2IDE0LjExMzQgNS42MDE1NiAxMy43NTk5VjExLjAzOTlDNS42MDE1NiAxMC42ODY0IDUuMzE1MDIgMTAuMzk5OSA0Ljk2MTU2IDEwLjM5OTlaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik0xMy43NTg0IDEuNjAwMUgxMS4wMzg0QzEwLjY4NSAxLjYwMDEgMTAuMzk4NCAxLjg4NjY0IDEwLjM5ODQgMi4yNDAxVjQuOTYwMUMxMC4zOTg0IDUuMzEzNTYgMTAuNjg1IDUuNjAwMSAxMS4wMzg0IDUuNjAwMUgxMy43NTg0QzE0LjExMTkgNS42MDAxIDE0LjM5ODQgNS4zMTM1NiAxNC4zOTg0IDQuOTYwMVYyLjI0MDFDMTQuMzk4NCAxLjg4NjY0IDE0LjExMTkgMS42MDAxIDEzLjc1ODQgMS42MDAxWiIgZmlsbD0iI2ZmZiIvPgo8cGF0aCBkPSJNNCAxMkwxMiA0TDQgMTJaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00IDEyTDEyIDQiIHN0cm9rZT0iI2ZmZiIgc3Ryb2tlLXdpZHRoPSIxLjUiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIvPgo8L3N2Zz4K&logoColor=ffffff)](https://zread.ai/GeWuYou/GFramework) -[![Scanned with Feluda](https://img.shields.io/badge/Scanned%20with-Feluda-brightgreen)](https://github.com/GeWuYou/GFramework) +--- -本项目参考(CV)自[QFramework](https://github.com/liangxiegame/QFramework)，并进行了模块化重构和功能增强。 +## 项目简介 -## 🚀 快速导航 +GFramework 采用清晰分层与模块化设计，强调： -### 📚 学习路径 +- **架构分层（Architecture / Model / System / Utility）** +- **命令与查询分离（CQRS）** +- **类型安全事件机制** +- **可绑定属性与响应式数据流** +- **可扩展的 IOC/生命周期管理** +- **基于 Roslyn 的源码生成能力** -#### 🎯 新手入门 +项目灵感参考自 [QFramework](https://github.com/liangxiegame/QFramework)，并在模块边界、工程组织和可扩展性方面进行了持续重构。 -1. 📚 [从零开始教程](docs/tutorials/getting-started.md) - 完整的项目创建和开发指南 -2. 📖 [基本概念](GFramework.Core/README.md#核心概念) - 理解核心概念 -3. 💡 [快速示例](#快速开始-getting-started) - 5分钟上手体验 +## 功能模块 -#### 🏗️ 进阶开发 +| 模块 | 说明 | 文档 | +| --- | --- | --- | +| `GFramework.Core` | 平台无关的核心架构能力（架构、命令、查询、事件、属性、IOC、日志等） | [查看](GFramework.Core/README.md) | +| `GFramework.Core.Abstractions` | Core 对应的抽象接口定义 | [查看](GFramework.Core.Abstractions/README.md) | +| `GFramework.Game` | 游戏业务侧扩展（状态、配置、存储、UI 等） | [查看](GFramework.Game/README.md) | +| `GFramework.Game.Abstractions` | Game 模块抽象接口定义 | 源码目录：`GFramework.Game.Abstractions/` | +| `GFramework.Godot` | Godot 集成层（节点扩展、场景/设置/存储适配等） | [查看](GFramework.Godot/README.md) | +| `GFramework.SourceGenerators` | 通用源码生成器（日志、枚举扩展、规则等） | [查看](GFramework.SourceGenerators/README.md) | +| `GFramework.Godot.SourceGenerators` | Godot 场景下的源码生成器扩展 | 源码目录：`GFramework.Godot.SourceGenerators/` | -4. 📖 [Godot 集成教程](docs/tutorials/godot-integration.md) - 深度 Godot 集成和最佳实践 -5. ⚡ [高级模式教程](docs/tutorials/advanced-patterns.md) - CQRS、事件溯源、插件系统等 -6. 🏗️ [架构模式最佳实践](docs/best-practices/architecture-patterns.md) - 推荐的架构设计模式 -7. 🏗️ [性能优化技巧](docs/best-practices/performance-tips.md) - 内存和性能优化 +## 文档导航 -#### 🏗️ 专家指南 +- 入门教程：[`docs/tutorials/getting-started.md`](docs/tutorials/getting-started.md) +- Godot 集成：[`docs/tutorials/godot-integration.md`](docs/tutorials/godot-integration.md) +- 进阶模式：[`docs/tutorials/advanced-patterns.md`](docs/tutorials/advanced-patterns.md) +- 最佳实践：[`docs/best-practices/architecture-patterns.md`](docs/best-practices/architecture-patterns.md) +- API 参考：[`docs/api-reference/`](docs/api-reference/) -8. 📊 [API 参考](docs/api-reference/) - 详细的类和接口说明 +> 如果你更偏好按模块阅读，建议从各子项目 `README.md` 开始，再回到 `docs/` 查阅专题文档。 -### 📖 详细文档 +## 快速安装 -#### 🏛️ 核心项目 Core Projects - -- [📖 **GFramework.Core** - 核心框架功能，架构、事件、命令、查询等（平台无关）](GFramework.Core/README.md) -- [📖 **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 +按实际需求选择依赖： ```bash -# 安装核心包（平台无关） +# 核心能力（推荐最小起步） 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项目需要） +# Godot 集成（仅 Godot 项目需要） dotnet add package GeWuYou.GFramework.Godot + +# 源码生成器（可选，但推荐） +dotnet add package GeWuYou.GFramework.SourceGenerators ``` -### 2️⃣ 基本使用 Basic Usage +## 仓库结构 -```csharp -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(); - } - - // 监听属性变化 - public void Initialize() - { - _playerModel.Health.RegisterWithInitValue(hp => UpdateHealthDisplay(hp)); - } - - private void UpdateHealthDisplay(int hp) - { - // 更新 UI 显示 - Console.WriteLine($"Health: {hp}"); - } -} +```text +GFramework.sln +├─ GFramework.Core/ +├─ GFramework.Core.Abstractions/ +├─ GFramework.Game/ +├─ GFramework.Game.Abstractions/ +├─ GFramework.Godot/ +├─ GFramework.SourceGenerators/ +├─ GFramework.Godot.SourceGenerators/ +├─ docs/ +└─ docfx/ ``` -### 3️⃣ 命令和查询 Command & Query +## 兼容性 -```csharp -// 定义命令 -public class AttackCommand : AbstractCommand -{ - protected override void OnExecute() - { - var playerModel = this.GetModel(); - var enemyModel = this.GetModel(); - - // 业务逻辑 - int damage = playerModel.AttackPower.Value; - enemyModel.Health.Value -= damage; - - // 发送事件 - this.SendEvent(new DamageDealtEvent { Damage = damage }); - } -} +- **运行时/工具链**：基于 .NET 生态，具体以各项目 `*.csproj` 的 `TargetFramework` 为准。 +- **引擎集成**：当前提供 Godot 集成模块，Core 层可迁移至其他 .NET 场景。 -// 定义查询 -public class CanAttackQuery : AbstractQuery -{ - protected override bool OnDo() - { - var playerModel = this.GetModel(); - 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()); - } - } -} -``` +欢迎提交 Issue 与 Pull Request： -### 4️⃣ 事件系统 Event System +1. Fork 本仓库并创建特性分支 +2. 补充必要的测试或文档更新 +3. 提交 PR，描述变更背景、方案与验证结果 -```csharp -// 定义事件 -public struct DamageDealtEvent -{ - public int Damage; - public Vector3 Position; -} +## 许可证 -// 发送事件 -this.SendEvent(new DamageDealtEvent { Damage = 100, Position = position }); - -// 注册事件监听 -this.RegisterEvent(OnDamageDealt); - -private void OnDamageDealt(DamageDealtEvent e) -{ - ShowDamageNumber(e.Damage, e.Position); -} -``` - -## 📦 项目架构 Architecture - -框架遵循清洁架构原则，具有以下层次： - -``` -┌─────────────────────────────────────────┐ -│ View / UI │ UI 层：用户界面 -├─────────────────────────────────────────┤ -│ Controller │ 控制层：处理用户输入 -├─────────────────────────────────────────┤ -│ System │ 逻辑层：业务逻辑 -├─────────────────────────────────────────┤ -│ Model │ 数据层：游戏状态 -├─────────────────────────────────────────┤ -│ Utility │ 工具层：无状态工具 -├─────────────────────────────────────────┤ -│ Command / Query │ 横切关注点 -└─────────────────────────────────┘ -``` - -## 🔧 平台集成 Platform Integration - -### Godot 项目 - -```csharp -// 使用 GFramework.Godot 获取 Godot 特定功能 -using GFramework.Godot; - -public class GodotPlayerController : Node, IController -{ - public IArchitecture GetArchitecture() => GameArchitecture.Interface; - - public override void _Ready() - { - // 使用 Godot 特定的扩展方法 - this.RegisterEvent(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 \ No newline at end of file +本项目采用 [Apache License 2.0](LICENSE)。