mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-03-22 10:34:30 +08:00
docs: rewrite root README for accuracy and structure
This commit is contained in:
gewuyou
parent
c8be4b317d
commit
bb971e98ae
353
README.md
353
README.md
@ -1,332 +1,97 @@
|
||||
# GFramework
|
||||
|
||||
> 专为游戏开发场景设计的综合性C#游戏开发框架，Core 模块与平台无关
|
||||
> 面向游戏开发场景的模块化 C# 框架，核心能力与具体引擎解耦，可按需组合 Core / Game / Godot / Source Generators。
|
||||
|
||||
[](https://www.nuget.org/packages/GeWuYou.GFramework.Core/)
|
||||
[](https://www.nuget.org/packages/GeWuYou.GFramework)
|
||||
[](https://godotengine.org/)
|
||||
[](https://dotnet.microsoft.com/)
|
||||
[](LICENSE)
|
||||
[](https://zread.ai/GeWuYou/GFramework)
|
||||
|
||||
[](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<PlayerModel>();
|
||||
}
|
||||
|
||||
// 监听属性变化
|
||||
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<PlayerModel>();
|
||||
var enemyModel = this.GetModel<EnemyModel>();
|
||||
|
||||
// 业务逻辑
|
||||
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<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());
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
欢迎提交 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<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 项目
|
||||
|
||||
```csharp
|
||||
// 使用 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
|
||||
本项目采用 [Apache License 2.0](LICENSE)。
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user