Entry point for coding agents working in this repository, whichever tool runs them: what this is, how to build, test and land a change, and a map of where the rest lives. Read what the map points at when the task touches it, not everything up front.
CLAUDE.mdfor the engineering values, the conventions that invert other engines' habits, the debugging instruments, code style and working discipline; where files disagree, it wins.CONTRIBUTING.mdfor the short form of the rules, written for people, and the module layers..claude/rules/rendering.mdwhen touching the renderer, shaders or GPU debugging;ecs.mdfor ECS components and systems;editor-ui.mdfor editor UI, CSS, settings pages and asset mounts;scripting.mdfor the managed side;documentation.mdfordocs/.CodingStyle.mdfor naming and layout;BUILD.mdfor building from a fresh clone on every platform, the configurations and the sanitizers.- The workbench, the team's private workflow repository (sibling
../GameEngine-Workbench, orGE_WORKBENCH; nothing in the engine build reads it, and a contributor without it followsCONTRIBUTING.md):agent/pr-review-rules.mdbefore opening or reviewing a pull request;test-map/path-to-suite.mdfor which suites gate a path;agent/evidence-checklists.mdfor the captures visible work ships with;agent/coordination.mdwhen coordinating lanes, reviewing or merging.
A C++20 game engine: Vulkan-first GPU-driven renderer, archetype ECS, CoreCLR (.NET 10) hot-reload scripting, GUID-identified assets with pluggable parsers, a dependency graph for targeted hot reload and async streaming, and a CSS/XML-driven editor. Windows is the primary platform (Visual Studio 2026, CMake 3.25+, vcpkg in manifest mode); macOS, Linux and Steam Deck presets exist. Engine/Modules/ holds every subsystem as its own library, Engine/Include/ and Engine/Source/ the engine-level services, Engine/ECSModules/ the shared ECS components, Apps/Editor/ the editor, Apps/Player/ the runtime, Managed/ the C# side, Engine/Tests/ and Tests/ the engine-level and integration tests, docs/ user-facing documentation only.
cmake --preset vs2026-x64-local -DBUILD_TESTING=ON # tests are OFF by default
cmake --build --preset vs2026-x64-local --config DebugFast --target <Target> -j 12- DebugFast is the daily configuration: asserts live, warnings are errors. Release is the only configuration a performance number may come from, on both arms.
BUILD.md(Build configurations) has the others and the reasons. - Presets:
vs2026-x64-localis the daily driver (no unity build, one edit recompiles one file); the-unityvariants compile faster cold and slower per edit;-asanfor memory bugs;ninja-x64-local, from a Visual Studio developer shell, is the fastest for incremental iteration in a tree you keep. The build wrapper below sets-j 12: a command through it never carries a-j. - Build the targets the change needs, never the whole tree: every target that compiles a touched file, which means the focused suites' targets and
EditororPlayerfor an application source that no test target compiles, live check or not. - Build through
bash $GE_WORKBENCH/agent/tools/ge-build.sh <tree> <preset> <config> <log> <targets...>and run a suite throughbash $GE_WORKBENCH/agent/tools/ge-test.sh <exe> <xml>: the full log goes to a file in the evidence folder and only the summary enters the conversation (through the MCP server or thegeCLI, the same summary comes frombuild_enginefor a CMake build,get_build_statusfor the editor's game build andrun_testsfor a suite). Those summaries and the capture tools' record lines are the record of a run. Never read a whole build log, suite log, capture listing or saved tool output; read a tail, a count, a line range or one grep for the thing needed. - Never build in a checkout someone else is working in, and never while an editor runs from that build's output: the build overwrites DLLs the editor has loaded (a long-lived editor session runs from an isolated copy of the staged tree). Use one git worktree per change and keep it until the change merges. A fresh worktree configures with the shared toolchain path and its own vcpkg root (
-DCMAKE_TOOLCHAIN_FILE=<primary checkout>/dependencies/vcpkg/scripts/buildsystems/vcpkg.cmake -DBUILD_TESTING=ON, noVCPKG_INSTALLED_DIR); ports come from the machine-wide binary cache in about a minute, the engine compiles cold once. A configured tree is never renamed or moved and a build directory is never copied between trees: the cache and project files hold absolute paths. - Before every build, suite and editor start, run
bash $GE_WORKBENCH/agent/wait-ab-lock.shas its own call, again while it has not exited 0, and start the command only after it has (never chain it with;), or run both as one background command throughagent/tools/gate-then.sh(the workbench'sagent/lanes.md). The gate blocks while a timing measurement holds the machine (theAB-LOCKfile beside the worktrees). Builds and test runs never take that lock; only ms/fps measurements do, withtake-ab-lock.sh <id> <cap minutes> <"gates a merge"|"window">in the same folder (it claims the lock, lets running builds, suites and editors finish, then marks it taken),AB_LOCK_HOLDER=<id>exported for the holder's own launches, andrelease-ab-lock.sh <id>within the cap. The lock is never written by hand. - Runtime files live next to the executable under
build/<preset>/bin/<config>/, staged by the build (StageEditorAssets,ge_stage_runtime_dependencies,StageTestAssets). Never resolve a runtime path back into the repository, and never use the repository root as a project root: useApps/Editor/Player/or a dedicated test project.
./build/<preset>/bin/DebugFast/Tests/<Suite>.exe --gtest_output=xml:<path> # one process per suiteGoogle Test, one executable per module or responsibility; ctest --test-dir build/<preset> -C <config> -N lists everything. Tests run from the staged output with the build directory as working directory.
- Gate a change with its focused suites: the module-mapped suites in the workbench test map that exercise the touched code (a test reads or calls it). A suite that merely compiles a touched header is built, not run. Each focused suite runs whole, in one process: no
--gtest_filterinside it at a gate. A filter is for a red-first run, a mutant and a repeat of one failing test; a filter that matches nothing is void, not a pass. - Report declared = ran + disabled and name every skip with its file:line reason (skips = ran − passed); a suite that only skips is a false instrument. The gtest XML, attached to the change's evidence, is the record of a run.
- Each step of a multi-step branch and each fold round after a review runs the focused suites only; fix failures the change caused and rerun without asking. A fold that changes only comments, documentation or test code runs only the suite that holds a changed test. A code fold that can change what renders or how long a frame takes adds a focused capture pair or timing at the affected pose, never the full evidence set.
- The full mapped set is not a per-pull-request gate: it runs as the pre-release validation and as one batched run on main each day.
- CI is off on purpose: the local runs above are the only gate, an absent CI run is not a defect, and nobody proposes to turn CI on.
- A behavioural claim ships with a test that is red without the change and green with it; say which run was red. Keep tests to what the task asks for, sized like the neighbouring test files; scratch checks are not committed.
- At the end of a branch's last fold, follow the
merge-mainskill (.claude/skills/merge-main/SKILL.md): mergeorigin/maininto the branch once, never mid-stream, and build the merged tree before calling a change ready, or skip the merge and its rebuild when the skill's test shows that main's delta cannot reach the branch, and say so in the body. - Every path handed to a Windows program is a
C:/...path:--gtest_output=xml:, log files,APPDATAredirects. Git Bash does not convert a/c/...path inside such an argument, so it lands underC:\c\, a tree nothing reads; a run that produced one is void until rerun. - Anything visible ships with recorded-pose screenshots (build SHA and full pose on every capture) from an isolated editor instance on a verified-free port that the lane checks is still its own before every call (a freed port is reused by the next launch), stopped by its recorded process id; never kill an editor you did not launch.
- The owner works on this machine while agents run: never synthesise operating-system input (
SetCursorPos,keybd_event,SendInput,mouse_event) or capture the desktop; a synthetic keystroke lands in whatever window has the focus. Drive the editor through its debug port and the Player through its own flags and log, and take captures through the render graph readback. The debug server'sfocus_view, tab activation andmove_windowask the operating system for the foreground (issue #2064): do not call them; start the editor with the view you need active. A check that needs more is reported as not verified. - An evidence folder holds evidence: captures, test results, logs, notes. Scratch output (build logs, exit codes, draft pull request bodies) goes there too, never beside the checkouts, into the repository or into a worktree. Never configure a build or copy an editor build into one. Isolated editor copies live in a scratch folder of their own and are deleted when the editor that ran from them stops; the final report lists what is left on disk, with sizes.
- Before opening the pull request, run the
change-scrutinyskill over the diff and carry its "Reuse and surface" table in the body; a reviewer reads it first. - A change is complete when it builds in DebugFast with warnings as errors, its focused suites are green at the merging head on the merged tree, its live check (if owed) is recorded, and the pull request body states the user's problem in plain steps, the change, the verification table, and what is not verified. Impersonal phrasing.
- IMPORTANT: no attribution lines, tool signatures or session links in commit messages or pull request bodies. The repository's commit hook strips trailers by design.
- One purpose per pull request and per commit, and the purpose complete: a pull request is a whole reviewable step of a feature (a design row a user can see or a test can exercise), never a fix bundled with a refactor and never the thinnest commit that compiles. An arc whose intermediate steps would leave main with a half-feature lives on a feature branch (the workbench's
agent/coordination.md, Sizing a slice). Shader and GPU changes that each need a timing window, and fixes another team waits on, stay small. Branch fromorigin/main; plain commits after review, never a force-push of a shared branch. - A change taken over from a public pull request carries "(contributed by , OpenEngine #N)" in its title; a squash merge's author is the merger, so the title is where the credit lives.
- A pre-existing bug or improvement you notice is reported as a follow-up, not folded into the change, unless the requested behaviour cannot work without it.
- A change that makes authored data newly refused (a pipeline, a scene or a material that loaded yesterday and is rejected today) says so in the pull request body with the one-line fix for the data.
- User-facing text (labels, tooltips, notices, documentation) uses American spelling and never names another engine; import features keep their names.