mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-05-07 00:39:00 +08:00
6ab32032bc
- 重命名 local-plan 为 ai-plan，并收口 public 与 private 的目录语义 - 更新 AGENTS、README 与 boot skill 的恢复文档路径和安全约束 - 迁移共享 tracking 与 trace 文件到 ai-plan/public，并补充治理说明文档
141 lines
7.8 KiB
Markdown
141 lines
7.8 KiB
Markdown
# GFramework
|
||
|
||
> 面向游戏开发场景的模块化 C# 框架，按运行时、抽象层、引擎集成和源码生成器拆分能力。
|
||
|
||
[](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)
|
||
|
||
## 从哪里开始
|
||
|
||
- 第一次接触框架：[`docs/zh-CN/getting-started/index.md`](docs/zh-CN/getting-started/index.md)
|
||
- 想先跑一个最小例子：[`docs/zh-CN/getting-started/quick-start.md`](docs/zh-CN/getting-started/quick-start.md)
|
||
- 已经知道要用哪个模块：直接进入对应模块目录下的 `README.md`
|
||
|
||
## 模块地图
|
||
|
||
| 模块 | 作用 | 入口 |
|
||
| --- | --- | --- |
|
||
| `GFramework.Core` | 架构、命令、查询、事件、状态、日志、资源、协程等基础运行时 | [README](GFramework.Core/README.md) |
|
||
| `GFramework.Core.Abstractions` | `Core` 对应的契约层，适合面向接口开发或做模块拆分 | [README](GFramework.Core.Abstractions/README.md) |
|
||
| `GFramework.Cqrs` | 新版 CQRS runtime，提供 request dispatcher、notification publish 与 handler 注册 | [README](GFramework.Cqrs/README.md) |
|
||
| `GFramework.Cqrs.Abstractions` | CQRS 消息、处理器、pipeline 行为等契约 | [README](GFramework.Cqrs.Abstractions/README.md) |
|
||
| `GFramework.Game` | 面向游戏项目的配置、数据、路由、场景、UI、设置和存储运行时 | [README](GFramework.Game/README.md) |
|
||
| `GFramework.Game.Abstractions` | `Game` 对应的契约层 | [README](GFramework.Game.Abstractions/README.md) |
|
||
| `GFramework.Godot` | Godot 集成层，负责把框架能力接入节点、场景、UI、设置与存储 | [README](GFramework.Godot/README.md) |
|
||
| `GFramework.Ecs.Arch` | Arch ECS 集成 | [README](GFramework.Ecs.Arch/README.md) |
|
||
| `GFramework.Core.SourceGenerators` | Core 侧通用源码生成器与分析器 | [README](GFramework.Core.SourceGenerators/README.md) |
|
||
| `GFramework.Game.SourceGenerators` | 游戏内容配置 schema 生成器 | [README](GFramework.Game.SourceGenerators/README.md) |
|
||
| `GFramework.Cqrs.SourceGenerators` | CQRS handler registry 生成器 | [README](GFramework.Cqrs.SourceGenerators/README.md) |
|
||
| `GFramework.Godot.SourceGenerators` | Godot 场景专用源码生成器 | [README](GFramework.Godot.SourceGenerators/README.md) |
|
||
|
||
## 文档导航
|
||
|
||
仓库根 README 与文档站点保持同一套栏目命名：
|
||
|
||
- 入门指南：[`docs/zh-CN/getting-started/index.md`](docs/zh-CN/getting-started/index.md)
|
||
- Core：[`docs/zh-CN/core/index.md`](docs/zh-CN/core/index.md)
|
||
- Game：[`docs/zh-CN/game/index.md`](docs/zh-CN/game/index.md)
|
||
- Godot：[`docs/zh-CN/godot/index.md`](docs/zh-CN/godot/index.md)
|
||
- 教程：[`docs/zh-CN/tutorials/index.md`](docs/zh-CN/tutorials/index.md)
|
||
- 源码生成器：[`docs/zh-CN/source-generators/index.md`](docs/zh-CN/source-generators/index.md)
|
||
- ECS：[`docs/zh-CN/ecs/index.md`](docs/zh-CN/ecs/index.md)
|
||
- 抽象接口：[`docs/zh-CN/abstractions/index.md`](docs/zh-CN/abstractions/index.md)
|
||
- 最佳实践：[`docs/zh-CN/best-practices/index.md`](docs/zh-CN/best-practices/index.md)
|
||
- API 参考：[`docs/zh-CN/api-reference/index.md`](docs/zh-CN/api-reference/index.md)
|
||
- FAQ：[`docs/zh-CN/faq.md`](docs/zh-CN/faq.md)
|
||
- 故障排查：[`docs/zh-CN/troubleshooting.md`](docs/zh-CN/troubleshooting.md)
|
||
- 贡献：[`docs/zh-CN/contributing.md`](docs/zh-CN/contributing.md)
|
||
|
||
## 包选择
|
||
|
||
- `GeWuYou.GFramework`
|
||
当前是聚合元包，只聚合 `GFramework.Core` 与 `GFramework.Game` 这两层运行时，适合快速试用。
|
||
- `GeWuYou.GFramework.Core`
|
||
推荐的最小起步包。先从核心运行时开始，再按需叠加 `Cqrs`、`Game`、`Godot` 和 Source Generators。
|
||
- `GeWuYou.GFramework.*.Abstractions`
|
||
适合需要单独依赖契约层、插件化、测试替身或多模块解耦的场景。
|
||
- `GeWuYou.GFramework.*.SourceGenerators`
|
||
只在需要编译期生成代码时安装，版本应与运行时包保持一致。
|
||
|
||
## 最小安装组合
|
||
|
||
```bash
|
||
# 最小起步
|
||
dotnet add package GeWuYou.GFramework.Core
|
||
dotnet add package GeWuYou.GFramework.Core.Abstractions
|
||
|
||
# 新版 CQRS
|
||
dotnet add package GeWuYou.GFramework.Cqrs
|
||
dotnet add package GeWuYou.GFramework.Cqrs.Abstractions
|
||
|
||
# 游戏层运行时
|
||
dotnet add package GeWuYou.GFramework.Game
|
||
dotnet add package GeWuYou.GFramework.Game.Abstractions
|
||
|
||
# Godot 集成
|
||
dotnet add package GeWuYou.GFramework.Godot
|
||
|
||
# 按需安装源码生成器
|
||
dotnet add package GeWuYou.GFramework.Core.SourceGenerators
|
||
dotnet add package GeWuYou.GFramework.Game.SourceGenerators
|
||
dotnet add package GeWuYou.GFramework.Cqrs.SourceGenerators
|
||
dotnet add package GeWuYou.GFramework.Godot.SourceGenerators
|
||
```
|
||
|
||
## 可选全局 using
|
||
|
||
NuGet 消费项目可显式开启模块级自动导入：
|
||
|
||
```xml
|
||
<PropertyGroup>
|
||
<EnableGFrameworkGlobalUsings>true</EnableGFrameworkGlobalUsings>
|
||
</PropertyGroup>
|
||
```
|
||
|
||
如果只想排除部分命名空间：
|
||
|
||
```xml
|
||
<ItemGroup>
|
||
<GFrameworkExcludedUsing Include="GFramework.Core.Environment" />
|
||
<GFrameworkExcludedUsing Include="GFramework.Godot.Extensions" />
|
||
</ItemGroup>
|
||
```
|
||
|
||
> 该能力主要面向 NuGet 消费场景。仓库内 `ProjectReference` 方式仍建议显式维护自己的 `GlobalUsings.cs`。
|
||
|
||
## 仓库结构
|
||
|
||
```text
|
||
GFramework.sln
|
||
├─ GFramework.Core/
|
||
├─ GFramework.Core.Abstractions/
|
||
├─ GFramework.Cqrs/
|
||
├─ GFramework.Cqrs.Abstractions/
|
||
├─ GFramework.Game/
|
||
├─ GFramework.Game.Abstractions/
|
||
├─ GFramework.Godot/
|
||
├─ GFramework.Ecs.Arch/
|
||
├─ GFramework.Core.SourceGenerators/
|
||
├─ GFramework.Game.SourceGenerators/
|
||
├─ GFramework.Cqrs.SourceGenerators/
|
||
├─ GFramework.Godot.SourceGenerators/
|
||
├─ GFramework.SourceGenerators.Common/
|
||
└─ docs/
|
||
```
|
||
|
||
## 贡献
|
||
|
||
提交功能或行为变更时，请把代码、测试和文档一起更新：
|
||
|
||
1. 先阅读对应模块目录下的 `README.md`
|
||
2. 如果改动影响采用路径、安装方式、公共 API 或目录结构，同时更新 `docs/zh-CN/`
|
||
3. 对跨模块或多阶段任务，维护 `ai-plan/public/todos/` 与 `ai-plan/public/traces/`
|
||
|
||
## 许可证
|
||
|
||
本仓库当前采用 [Apache License 2.0](LICENSE)。
|