FlaxEngine/AGENTS.md

AGENTS.md

Repo Purpose

Flax Engine is a modern 3D game engine written in C++ and C#. This repository contains the engine, editor, tooling, shaders, tests, assets, and platform-specific sources, excluding NDA-protected platform support.

High-Level Structure

• Source/Engine/: engine runtime code and managed/runtime integration.
• Source/Editor/: editor code in both C++ and C#.
• Source/Tools/: build system and developer tooling, including Flax.Build.
• Source/Platforms/: platform-specific code, dependencies, and binaries.
• Source/ThirdParty/: vendored third-party code. Avoid changes here unless the task explicitly requires it.
• Source/Engine/Tests/: native and managed engine tests.
• Source/Tools/Flax.Build.Tests/: .NET tests for the build tool.
• Content/: engine/editor assets.
• Development/Scripts/: helper scripts for project generation and builds.

Working Assumptions

• Generated solutions and project files are not committed. On a clean clone, generate them first.
• Git LFS is required. The Windows build scripts explicitly check for LFS-populated files.
• On Windows, the main entry points are GenerateProjectFiles.bat and Development\Scripts\Windows\CallBuildTool.bat.
• Prefer edits in Source/Engine, Source/Editor, Source/Tools, or docs. Do not modify Binaries/, Cache/, or generated project files unless the task explicitly targets generated output.

Windows Setup And Build

Use these commands from the repo root.

Generate project files:

.\GenerateProjectFiles.bat -vs2022 -log -verbose -printSDKs -dotnet=8

Alternative default generation:

.\GenerateProjectFiles.bat

Build the editor target:

.\Development\Scripts\Windows\CallBuildTool.bat -build -log -dotnet=8 -arch=x64 -platform=Windows -configuration=Development -buildtargets=FlaxEditor

Run the editor:

.\Binaries\Editor\Win64\Development\FlaxEditor.exe

Visual Studio workflow after generation:

• Open Flax.sln.
• Use solution configuration Editor.Development and platform Win64.
• Set Flax or FlaxEngine as the startup project.

Tests And Validation

The checked-in CI workflow in .github/workflows/tests.yml is the most reliable source for current validation commands.

Build native tests:

.\Development\Scripts\Windows\CallBuildTool.bat -build -log -dotnet=8 -arch=x64 -platform=Windows -configuration=Development -buildtargets=FlaxTestsTarget

Run native tests:

.\Binaries\Editor\Win64\Development\FlaxTests.exe -headless

Build Flax.Build tests:

dotnet msbuild Source\Tools\Flax.Build.Tests\Flax.Build.Tests.csproj /m /t:Restore,Build /p:Configuration=Debug /p:Platform=AnyCPU /nologo

Run Flax.Build tests:

dotnet test -f net8.0 Binaries\Tests\Flax.Build.Tests.dll

Run managed engine tests after copying runtime dependencies:

xcopy /y Binaries\Editor\Win64\Development\FlaxEngine.CSharp.dll Binaries\Tests
xcopy /y Binaries\Editor\Win64\Development\FlaxEngine.CSharp.runtimeconfig.json Binaries\Tests
xcopy /y Binaries\Editor\Win64\Development\Newtonsoft.Json.dll Binaries\Tests
dotnet test -f net8.0 Binaries\Tests\FlaxEngine.CSharp.dll

If a change is localized, prefer the narrowest possible target build and only run the relevant tests for that area.

Style And Conventions

• The root Source/.editorconfig sets CRLF line endings, UTF-8, final newline, and spaces for indentation.
• Use 4 spaces for C++, C#, shaders, and Python. Use 2 spaces for XAML and MSBuild files.
• Keep the existing copyright header in source files.
• Public APIs in both C++ headers and C# commonly use XML-style documentation comments such as /// <summary>.
• Preserve local file style instead of mass-normalizing. The C# codebase mixes block namespaces and file-scoped namespaces.
• Follow existing naming patterns: PascalCase for types and public members; private C# fields often use _camelCase.
• In C++ headers, prefer forward declarations where practical and keep includes minimal.

Build System Notes

• FlaxEditor is the main standalone editor target.
• FlaxGame is the standalone game target.
• FlaxTestsTarget builds the native test executable.
• Flax.Build supports project generation switches such as -vs2022, -vs2026, -vscode, and -rider.
• GenerateProjectFiles.bat also builds C# bindings for FlaxEditor on Windows.

Agent Guidance

• Treat .github/workflows/tests.yml as the source of truth for CI-backed validation.
• Do not assume generated artifacts already exist in the repo.
• Avoid broad style-only rewrites.
• Avoid touching Source/ThirdParty/ unless explicitly requested.
• If a change affects developer workflow or build/test steps, update the relevant root docs as part of the task.
• No dedicated repo-wide formatter or linter command is checked in. Prefer build and test validation over inventing formatting steps.
• PVS-Studio is mentioned in README.md, but it is not wired here as a standard local validation command.