Imported from Xian55/Adventure (
.claude/skills/adv-onboard/SKILL.md). Install upstream withnpx skills add Xian55/Adventure --skill adv-onboard. Copyright stays with the author.
adv-onboard — set up the Adventure project from scratch
Goal: from nothing to a green build + running game. Windows is the primary target. Do the steps in order; each ends in a check.
1. Prerequisites (install if missing)
- git ≥ 2.4, CMake ≥ 3.24, Ninja ≥ 1.11.
- A C++17 toolchain — either:
- MinGW-w64 UCRT (WinLibs) —
winget install BrechtSanders.WinLibs.POSIX.UCRT(gcc on PATH), or - Visual Studio 2022 (MSVC, Desktop C++ workload).
- MinGW-w64 UCRT (WinLibs) —
- Optional (asset work): Aseprite (sprites), TrenchBroom (levels).
Verify:
cmake --version,git --version, andgcc --version(MinGW) or a VS Developer prompt (MSVC).
2. Clone
git clone https://github.com/Xian55/Adventure.git
cd Adventure
Note: assets/ binaries are gitignored (kept local); the build still works (only the .gitkeep skeleton
is tracked).
3. Environment variables (User scope, persistent)
Set the tool paths the skills reference — adjust to your install locations:
# Aseprite (only if you'll export sprites) — used by adv-sprite / the asset pipeline
[Environment]::SetEnvironmentVariable("ASEPRITE","C:\Program Files\Aseprite\Aseprite.exe","User")
Open a new shell so the variables take effect. Verify: $env:ASEPRITE.
(See memory/docs for the current canonical list; keep this in sync when a new tool env var is added.)
4. Build (first run fetches raylib 5.5 + EnTT + doctest — needs network, a few minutes)
cmake --preset mingw-debug # or: msvc-debug
cmake --build build/mingw-debug
5. Verify — all three must pass
# unit tests (headless)
ctest --test-dir build/mingw-debug --output-on-failure
# perf gate (Release)
cmake --preset mingw-release && cmake --build build/mingw-release
ctest --test-dir build/mingw-release -C Release --output-on-failure
# run the game (F3 = metrics overlay)
./build/mingw-debug/adventure.exe
Expected: tests + bench green; a window shows a pixelated, fogged scene; console prints
ScriptEngine selfTest OK.
6. Editor / formatting
- Install clang-format 19 (VS ships one; or
pip install clang-format==19.1.5) soadv-formatand the CI format gate agree. Enable "format on save" pointed at the repo.clang-formatif your editor supports it. .editorconfigis respected by most editors (tabs, LF, final newline).
7. Learn the project (read in this order)
CLAUDE.md(root) — commands, layout, conventions, gotchas.docs/design/VISION.md,ARCHITECTURE.md,ROADMAP.md,DEVELOPMENT_LOOP.md.- The subsystem
src/<name>/CLAUDE.mdfor whatever you'll touch. - Skills:
adv-feature(the dev loop),adv-test,adv-build,adv-new-module,adv-format,adv-docs,adv-map,adv-sprite.
Troubleshooting
0xc0000139running tests → wrong MinGW runtime DLL on PATH; the static link should prevent it (rebuild).- CMake can't find a compiler → use a preset matching your toolchain (
mingw-*vsmsvc-*); for MSVC run from a Developer prompt or viavcvars64.bat. - First configure fails offline → the dep fetch needs network once; then it's cached.
