GFramework/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

GFramework.sln is the entry point for the full .NET solution. Runtime code lives in GFramework.Core/, GFramework.Game/, GFramework.Godot/, and GFramework.Ecs.Arch/. Interface-only contracts stay in the paired *.Abstractions/ projects. Roslyn generators are split across GFramework.SourceGenerators/, GFramework.Godot.SourceGenerators/, and GFramework.SourceGenerators.Common/. Tests mirror the runtime modules in GFramework.Core.Tests/, GFramework.Game.Tests/, GFramework.Ecs.Arch.Tests/, and GFramework.SourceGenerators.Tests/. Documentation is under docs/, Godot templates under Godot/script_templates/, and repository utilities under scripts/ and refactor-scripts/.

Build, Test, and Development Commands

• dotnet build GFramework.sln builds the full solution from the repo root.
• dotnet test GFramework.sln --no-build runs all NUnit test projects after a build.
• dotnet test GFramework.Core.Tests --filter "FullyQualifiedName~CommandExecutorTests.Execute" runs a focused NUnit test.
• bash scripts/validate-csharp-naming.sh checks PascalCase namespace and directory rules used by CI.
• cd docs && bun install && bun run dev starts the VitePress docs site locally.

Coding Style & Naming Conventions

Use standard C# formatting with 4-space indentation and one public type per file. The repository keeps ImplicitUsings disabled and Nullable enabled, so write explicit using directives and annotate nullability carefully. Follow PascalCase for types, methods, namespaces, directories, and constants; use _camelCase for private fields and camelCase for locals and parameters. Keep namespaces aligned with folders, for example GFramework.Core.Architectures.

Testing Guidelines

Tests use NUnit 4 with Microsoft.NET.Test.Sdk; some suites also use Moq. Place tests in the matching module test project and name files *Tests.cs. Prefer directory parity with production code, for example GFramework.Core/Logging/ and GFramework.Core.Tests/Logging/. Add or update tests for every behavior change, especially public APIs, source generators, and integration paths.

Commit & Pull Request Guidelines

Recent history follows Conventional Commits style such as feat(events): ..., refactor(localization): ..., docs(guide): ..., and test(localization): .... Keep commits scoped and imperative. PRs should explain the motivation, implementation, and validation commands run; link related issues; and include screenshots when docs, UI, or Godot-facing behavior changes.