GFramework/CLAUDE.md

CLAUDE.md

This file provides project understanding for AI agents working in this repository.

Project Overview

GFramework 是面向游戏开发的模块化 C# 框架，核心能力与引擎解耦。项目灵感参考 QFramework，并在模块边界、工程组织和可扩展性方面持续重构。

AI Agent Instructions

All coding rules are defined in:

@AGENTS.md

Follow them strictly.

Module Dependency Graph

GFramework (meta package) ─→ Core + Game
GFramework.Core ─→ Core.Abstractions
GFramework.Game ─→ Game.Abstractions, Core, Core.Abstractions
GFramework.Godot ─→ Core, Game, Core.Abstractions, Game.Abstractions
GFramework.Ecs.Arch ─→ Ecs.Arch.Abstractions, Core, Core.Abstractions
GFramework.SourceGenerators ─→ SourceGenerators.Common, SourceGenerators.Abstractions

• Abstractions projects (netstandard2.1): 只包含接口和契约定义，不承载运行时实现逻辑。
• Core / Game / Ecs.Arch (net8.0;net9.0;net10.0): 平台无关的核心实现层。
• Godot: Godot 引擎集成层，负责与节点、场景和引擎生命周期对接。
• SourceGenerators (netstandard2.1): Roslyn 增量源码生成器及其公共基础设施。

Architecture Pattern

框架核心采用 Architecture / Model / System / Utility 四层结构：

• IArchitecture: 顶层容器，负责生命周期管理、组件注册、模块安装和统一服务访问。
• IContextAware: 统一上下文访问接口，组件通过 SetContext(IArchitectureContext) 获取架构上下文。
• IModel: 数据与状态层，负责长期状态和业务数据建模。
• ISystem: 业务逻辑层，负责命令执行、流程编排和规则落地。
• IUtility: 通用无状态工具层，供其他层复用。

关键实现位于 GFramework.Core/Architectures/Architecture.cs，其职责是作为总协调器串联生命周期、组件注册和模块系统。

Architecture Details

Lifecycle

Architecture 负责统一生命周期编排，核心阶段包括：

• Init
• Ready
• Destroy

在实现层中，生命周期被拆分为更细粒度的初始化与销毁阶段，用于保证 Utility、Model、System、服务模块和钩子的顺序一致性。

Component Coordination

框架通过独立组件协作完成架构编排：

• ArchitectureLifecycle: 管理生命周期阶段、阶段转换和生命周期钩子。
• ArchitectureComponentRegistry: 管理 Model、System、Utility 的注册与解析。
• ArchitectureModules: 管理模块安装、服务模块接入和扩展点注册。

这组拆分的目标是降低单个核心类的职责密度，同时保持对外 API 稳定。

Context Propagation

IArchitectureContext 和相关 Provider 类型负责在组件之间传播上下文能力，使 Model、System 和外部扩展都能通过统一入口访问架构服务，而不直接耦合具体实现细节。

Key Patterns

CQRS

命令与查询分离，支持同步与异步执行。Mediator 模式通过源码生成器集成，以减少模板代码并保持调用路径清晰。

EventBus

类型安全事件总线支持事件发布、订阅、优先级、过滤器和弱引用订阅。它是模块之间松耦合通信的核心基础设施之一。

BindableProperty

响应式属性模型通过值变化通知驱动界面或业务层更新，适合表达轻量级状态同步。

Coroutine

帧驱动协程系统基于 IYieldInstruction 和调度器抽象，支持等待时间、事件和任务完成等常见模式。

IoC

依赖注入通过 MicrosoftDiContainer 对 Microsoft.Extensions.DependencyInjection 进行封装，用于统一组件注册和服务解析体验。

Service Modules

IServiceModule 模式用于向 Architecture 注册内置服务，例如 EventBus、CommandExecutor、QueryExecutor 等。这一模式承担“基础设施能力装配”的职责。

Source Generators

当前仓库包含多类 Roslyn 增量源码生成器：

• LoggerGenerator ([Log]): 自动生成日志字段和日志辅助方法。
• PriorityGenerator ([Priority]): 生成优先级比较相关实现。
• EnumExtensionsGenerator ([GenerateEnumExtensions]): 生成枚举扩展能力。
• ContextAwareGenerator ([ContextAware]): 自动实现 IContextAware 相关样板逻辑。

这些生成器的目标是减少重复代码，同时保持框架层 API 的一致性与可维护性。

Module Structure

仓库以“抽象层 + 实现层 + 集成层 + 生成器层”的方式组织：

• GFramework.Core.Abstractions / GFramework.Game.Abstractions: 约束接口和公共契约。
• GFramework.Core / GFramework.Game: 提供平台无关实现。
• GFramework.Godot: 提供与 Godot 运行时集成的适配实现。
• GFramework.Ecs.Arch: 提供 ECS Architecture 相关扩展。
• GFramework.SourceGenerators 及相关 Abstractions/Common: 提供代码生成能力。

这种结构的核心设计目标是让抽象稳定、实现可替换、引擎集成隔离、生成器能力可独立演进。

Documentation Structure

项目文档位于 docs/，中文内容位于 docs/zh-CN/。文档内容覆盖：

• 入门与安装
• Core / Game / Godot / ECS 各模块能力
• Source Generator 使用说明
• 教程、最佳实践与故障排查

阅读顺序通常建议先看根目录 README.md 和各子模块 README.md，再进入 docs/ 查阅专题说明。

Design Intent

GFramework 的设计重点不是把所有能力堆进单一核心类，而是通过清晰的模块边界、可组合的服务注册方式、稳定的抽象契约以及适度自动化的源码生成，构建一个适合长期演进的游戏开发基础框架。