mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-05-06 16:16:44 +08:00
43b95c7513
- 新增配置系统架构说明，涵盖 YAML 源文件、JSON Schema 结构描述、运行时只读查询等核心功能 - 完善推荐目录结构和 Schema 示例，包括怪物、物品配置表的标准定义方式 - 提供完整的接入模板，包含 csproj 配置、GameConfigHost 生命周期管理、GameConfigRuntime 读取入口 - 添加运行时校验行为说明，支持必填字段、类型匹配、数值范围、字符串长度、正则表达式、数组长度等多种约束 - 集成跨表引用功能，支持通过 x-gframework-ref-table 声明关联关系并进行有效性检查 - 添加开发期热重载支持，可自动监听配置目录和 schema 文件变更并重载对应表格 - 提供 VS Code 工具集成说明，包括配置浏览、raw 编辑、schema 打开、表单入口等功能 - 补充生成器接入约定，从 *.schema.json 自动生成配置类型、表包装、注册辅助等代码 - 添加完整的 Analyzer 规则文档，涵盖 GF_ConfigSchema_001 到 GF_ConfigSchema_008 等错误诊断码 - 增加单元测试验证，确保消费者项目可以正常使用生成的聚合注册辅助和强类型访问入口
GFramework
面向游戏开发场景的模块化 C# 框架，核心能力与具体引擎解耦，可按需组合 Core / Game / Godot / Source Generators。
项目简介
GFramework 采用清晰分层与模块化设计，强调：
- 架构分层（Architecture / Model / System / Utility）
- 命令与查询分离（CQRS）
- 类型安全事件机制
- 可绑定属性与响应式数据流
- 可扩展的 IOC/生命周期管理
- 基于 Roslyn 的源码生成能力
项目灵感参考自 QFramework，并在模块边界、工程组织和可扩展性方面进行了持续重构。
功能模块
| 模块 | 说明 | 文档 |
|---|---|---|
GFramework.Core |
平台无关的核心架构能力（架构、命令、查询、事件、属性、IOC、日志等） | 查看 |
GFramework.Core.Abstractions |
Core 对应的抽象接口定义 | 查看 |
GFramework.Game |
游戏业务侧扩展（状态、配置、存储、UI 等） | 查看 |
GFramework.Game.Abstractions |
Game 模块抽象接口定义 | 查看 |
GFramework.Godot |
Godot 集成层（节点扩展、场景/设置/存储适配等） | 查看 |
GFramework.SourceGenerators |
通用源码生成器（日志、枚举扩展、规则等） | 查看 |
GFramework.Godot.SourceGenerators |
Godot 场景下的源码生成器扩展 | 查看 |
文档导航
- 入门教程：
docs/zh-CN/tutorials/getting-started.md - Godot 集成：
docs/zh-CN/godot/index.md - 进阶模式：
docs/zh-CN/core/index.md - 最佳实践：
docs/zh-CN/best-practices/architecture-patterns.md - API 参考：
docs/zh-CN/api-reference/
如果你更偏好按模块阅读，建议从各子项目
README.md开始，再回到docs/查阅专题文档。
包选择说明（避免混淆）
GeWuYou.GFramework：聚合元包（Meta Package），用于一键引入常用能力集合，适合快速试用或原型阶段。GeWuYou.GFramework.Core：核心起步包，适合希望按模块精细控制依赖的项目（推荐生产项目从此起步）。
如果你已明确技术栈，建议优先按模块安装（Core / Game / Godot / SourceGenerators），避免不必要依赖。
快速安装
按实际需求选择依赖：
# 核心能力（推荐最小起步）
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
# Godot 集成（仅 Godot 项目需要）
dotnet add package GeWuYou.GFramework.Godot
# 源码生成器（可选，但推荐）
dotnet add package GeWuYou.GFramework.SourceGenerators
可选模块导入
发布后的运行时包支持可选的模块级自动导入，但默认关闭，避免在普通项目里无意污染命名空间。
在 NuGet 消费项目中显式开启：
<PropertyGroup>
<EnableGFrameworkGlobalUsings>true</EnableGFrameworkGlobalUsings>
</PropertyGroup>
启用后，项目已引用的 GFramework 运行时模块会通过 buildTransitive 自动注入其推荐命名空间。
如果某几个命名空间不想导入，可以局部排除：
<ItemGroup>
<GFrameworkExcludedUsing Include="GFramework.Core.Environment" />
<GFrameworkExcludedUsing Include="GFramework.Godot.Extensions" />
</ItemGroup>
该能力面向 NuGet 包消费场景。若你在本地解决方案中直接使用
ProjectReference，仍建议保留自己的GlobalUsings.cs或手写using。
仓库结构
GFramework.sln
├─ GFramework.Core/
├─ GFramework.Core.Abstractions/
├─ GFramework.Game/
├─ GFramework.Game.Abstractions/
├─ GFramework.Godot/
├─ GFramework.SourceGenerators/
├─ GFramework.Godot.SourceGenerators/
├─ docs/
└─ docfx/
兼容性
- 运行时/工具链：基于 .NET 生态，具体以各项目
*.csproj的TargetFramework为准。 - 引擎集成：当前提供 Godot 集成模块，Core 层可迁移至其他 .NET 场景。
贡献
欢迎提交 Issue 与 Pull Request：
- Fork 本仓库并创建特性分支
- 补充必要的测试或文档更新
- 提交 PR，描述变更背景、方案与验证结果
许可证
本项目采用 Apache License 2.0。