القائمة
Build and run the Adventure headless unit-test suite (doctest via CTest). Use after changing anything in adventure_lib (Lua engine, metrics, systems) to check for regressions before committing.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Add or change a player input action (a key/mouse-driven control) the right way — routed through the rebindable input action map, never a hard-coded key. Use whenever you introduce a new control (a new key/button the player presses) or change how an existing control is read, so it stays rebindable via keybindings.cfg.
Authoritative reference for the TrenchBroom/Quake Valve 220 .map format and Adventure's map conventions. Use when authoring, generating, editing, debugging, or validating a .map file, or wiring TrenchBroom to the project. TrenchBroom has no MCP server or CLI/scripting API — .map is plain text, so we generate/validate it ourselves (parser: src/world/MapParser).
Bootstrap a new contributor (or a fresh machine) into the Adventure project — install the toolchain, set environment variables, build, and verify everything works. Use when someone is setting up the project for the first time, or when a clean-machine setup / environment problem needs fixing.
Produce/export game sprites (billboard atlases, viewmodels) with Aseprite via the ASEPRITE env var, so scripts stay machine-independent. Use when creating or batch-exporting sprite sheets, or setting up Aseprite CLI automation for the asset pipeline.
Keep the project's documentation current after a code change — the subsystem CLAUDE.md files, the root CLAUDE.md, and docs/design. Use at the end of any feature or structural change (it's the final step of adv-feature), or whenever architecture, commands, conventions, or milestone status shift.
The end-to-end harness for building a requested feature in Adventure autonomously — design it, implement it under SRP, test it thoroughly, gate it on performance, verify it, and commit. Use this whenever the user requests a new gameplay/engine feature (a system, mechanic, weapon, enemy, level element, etc.) rather than a trivial fix. It defines the required steps and quality gates so the work is reliable and doesn't regress performance.
| name | adv-test |
| description | Build and run the Adventure headless unit-test suite (doctest via CTest). Use after changing anything in adventure_lib (Lua engine, metrics, systems) to check for regressions before committing. |
The tests link adventure_lib and never open a window, so they run anywhere.
# build (configure first if needed: cmake --preset mingw-debug)
cmake --build build/mingw-debug
# run via CTest
ctest --test-dir build/mingw-debug --output-on-failure
For richer output, run the test exe directly (doctest reporter):
./build/mingw-debug/adventure_tests.exe # summary
./build/mingw-debug/adventure_tests.exe -s # list successful assertions too
./build/mingw-debug/adventure_tests.exe -tc="watchdog*" # filter by test-case name
The adventure_bench target is a headless micro-benchmark harness that returns nonzero if any case
exceeds its ms budget. It's registered as a CTest test only for optimized builds (Debug is too noisy),
so run it in Release:
cmake --preset mingw-release && cmake --build build/mingw-release
ctest --test-dir build/mingw-release -C Release --output-on-failure # tests + bench gate
./build/mingw-release/adventure_bench.exe # raw numbers
Add a bench case for any new hot-path code: ADV_BENCH(name, iters, budgetMs) { ...one iteration... }
in a bench/*.cpp, listed in the adventure_bench target. Budgets are ceilings with headroom, not
targets — they catch regressions.
To profile the real render loop headlessly: ADVENTURE_PROFILE=300 ./adventure.exe writes profile.csv
(frame avg/p50/p95/max, RSS, Lua bytes, per-section ms).
CI runs the headless tests under AddressSanitizer + UndefinedBehaviorSanitizer (Linux/gcc) — the net that catches use-after-free / UB our unit tests can't. To reproduce locally on Linux/WSL:
cmake -S . -B build/asan -G Ninja -DCMAKE_BUILD_TYPE=Debug \
-DCMAKE_C_FLAGS="-fsanitize=address,undefined -fno-sanitize-recover=all" \
-DCMAKE_CXX_FLAGS="-fsanitize=address,undefined -fno-sanitize-recover=all" \
-DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address,undefined"
cmake --build build/asan --target adventure_tests
ASAN_OPTIONS=detect_leaks=0 ctest --test-dir build/asan -R adventure_tests --output-on-failure
The Lua sandbox is a security boundary — tests/test_sandbox.cpp adversarially tries to escape/exhaust it;
keep it green when touching src/lua.
0xc0000139 (entrypoint not found), a wrong runtime DLL is on PATH — the static link should prevent it.error('boom')); a
green summary (Status: SUCCESS!) is what matters..cpp in tests/, list it in adventure_tests in CMakeLists.txt.
Keep logic testable by injecting time/IO (see Metrics::setClock).