Build-system DX: preset restructure + tiered dependency acquisition (+ Windows dev path)

[painfulexistence]

Goal

Developer-experience overhaul of the build system: CMake presets (including the first-class Windows dev path), third-party dependency acquisition, a tinygltf supply-chain fix, and CI made to validate the same dependency universe developers build against. Distribution (WIN32 subsystem / static triplet / packaging) stays out of scope.

---

Part 1 — Presets: vcpkg base → generator families

Problems: no MSVC path (the documented dev preset used ccache + GCC-only flags cl.exe rejects); the canonical workflow lived in CMakeUserPresets.json (the machine-local file CMake says to gitignore) while the shared file held only plumbing; workflow and generator names were mixed in one flat list.

Final shape — one hidden vcpkg toolchain base (bundled submodule — the single supported path) + an opt-in ccache mixin grow two generator families; build presets pick the config:

configure	generator	build presets	notes
ninja	Ninja Multi-Config	debug / release	all desktop OSes; MSVC on Windows (VS x64 prompt or VS Code kit)
vs (Windows-gated)	Visual Studio 2022 x64	vs-debug / vs-release	.sln in build-vs/; locates MSVC itself; separate tree (CMake won't share a build dir across generators)

• Configure presets set no CMAKE_BUILD_TYPE — every configure-time read sits in if(EMSCRIPTEN) blocks (verified) — so the ninja family is genuinely multi-config: configure once, build Debug and Release.
• dev is now a personal name: CMakeUserPresets.json.example ships dev (= ninja + ccache), dev-release, and dev-global (system vcpkg via $VCPKG_ROOT, moved out of the shared file since it's a machine choice; implemented as a cacheVariables override because an inherits-mixin would be silently beaten by precedence).

  cp CMakeUserPresets.json.example CMakeUserPresets.json   # gitignored, adjust freely
  

• README documents cmake --preset ninja + cmake --build --preset debug; .vscode/launch.json debugs the CMake Tools launch target (cppvsdbg on Windows).

Part 2 — Dependency acquisition: tiered, justified, inline

Acquisition was scattered through a 680-line Engine/CMakeLists.txt across three mechanisms with no stated policy. It now lives as a single "Dependencies" section inside Engine/CMakeLists.txt (no extra files — repo convention is one CMakeLists per directory, read top-to-bottom), grouped by mechanism, with rationale kept in this PR description rather than in-file comments:

• vcpkg manifest (default): glm, Tracy, Bullet, Box2D, fmt, spdlog, RmlUi, flatbuffers, tinyexr, nlohmann-json, glad, networking's curl + libwebsockets.
• FetchContent (each with a reason vcpkg can't serve): SDL3 (Android Gradle copies the Java scaffolding out of the source tree, which the vcpkg port doesn't install; tag pinned to the vendored imgui backend) · Lua (per-platform source build: LUA_USE_POSIX/LUA_USE_IOS, wasm cross-compile, pinned) · sol2 (must bind to our lua_static, not vcpkg lua) · FastNoiseLite + TinyUSDZ (no vcpkg port exists) · tinygltf (supply-chain — see Part 3) · Basis Universal (transcoder-only with wasm size-trimming defines + host-arch encoder while cross-compiling).
• Vendored Engine/external/: raudio (no port; iOS ObjC compile patch), imgui (compiled into the engine as sources, upgraded by hand with the SDL3 pin), stb.
• Named exception: FFmpeg is a deliberate system dependency via pkg-config (the vcpkg port is enormous).

The root's Android per-ABI triplet synthesis stays in the root CMakeLists.txt (between project() and the vcpkg toolchain include — order matters). The dead if(!MSVC) (never-true condition — that -Werror flag has never applied) carries a one-line FIXME; fixing it is a behavior change (Clang-only flag) for a separate PR.

Part 3 — tinygltf: vcpkg port → FetchContent (hash-drift fix)

Cold builds (first hit on Windows) started failing at the vcpkg download step: the tinygltf 2.9.7 GitHub release .tar.gz no longer matches the SHA512 pinned in the portfile. GitHub regenerates those archives lazily, so the bytes — and hash — can drift under a fixed tag; upstream vcpkg moved the port to 3.0.0 in March 2026 and only maintains hashes there, so the 2.9.7 pin stays broken forever. A git clone is content-addressed and immune.

• tinygltf v2.9.7 via FetchContent (git tag, same version the port carried — pure acquisition change, no API movement), consumed as an include dir like FastNoiseLite; symmetric with the same author's TinyUSDZ.
• nlohmann-json becomes an explicit vcpkg dependency + linked target. It was only ever installed transitively by the tinygltf port, and its headers resolved through accidental include-root leakage — while the engine's own scene layer (json_deserializer.hpp, scene_blueprint.hpp) depends on it directly. Now declared, found, and linked PUBLIC (it appears in public headers).
• Both tinygltf TUs set TINYGLTF_NO_INCLUDE_JSON and include the same nlohmann as the scene code (the vcpkg port used to patch that include; the fetched source is unpatched), so one json type flows through the whole build.
• Dropped dead Engine/external/nlohmann/json.hpp (24.7k lines; never on any include path).

Part 4 — CI: pinned vcpkg + caches that actually hit

Two related fixes, landed as two commits:

• Binary cache instead of dead paths (62e3f0f): every job cached vcpkg/installed + vcpkg/packages, which manifest mode never reads back (installs go to build/vcpkg_installed) — so every run rebuilt every port. All seven cache steps now carry vcpkg's ABI-hashed binary cache (VCPKG_DEFAULT_BINARY_CACHE → workspace .vcpkg-cache), under a fresh vcpkg-bin-* key namespace so stale entries never restore.
• Pinned submodule instead of floating master (9a010f5): every workflow checked out microsoft/vcpkg master rather than the repo's pinned submodule, so CI validated a drifting dependency set — this is why tinygltf broke on dev machines while CI stayed green (CI was on the 3.0.0 port entirely). Checkouts now use submodules: true; sparse lists gain the vcpkg path; release.yml's sparse list also gains cmake/ + triplets/, which the root CMakeLists has required since the helpers refactor.

Net effect: CI green now means "builds against the pinned baseline developers actually get", and the second run per platform restores prebuilt ports instead of compiling them. The first run per platform is one-time cold (~all ports from source).

Verification

• Presets: cmake --list-presets (configure+build) on CMake 3.28, with and without the example copied in; host conditions verified.
• Deps reorganization is mechanical with machine checks: blocks moved verbatim by content-anchored scripts; command-count parity across the file set before/after; comment-trim pass verified by comparing comment-stripped files byte-for-byte; a configure with -DVCPKG_MANIFEST_INSTALL=OFF parses the full chain and fails only at the first find_package(glm), exactly as expected without installed deps.
• tinygltf migration: the exact FetchContent block was run end-to-end (git clone of v2.9.7 succeeds; fetched tiny_gltf.h is byte-identical to the release header), and both TUs' define/include sequences were compiled with -fsyntax-only against that header + nlohmann 3.11.3.
• Workflows: YAML-validated; no microsoft/vcpkg checkout remains anywhere.
• CI on the pre-CI-change commits: 21/22 green with the single failure being a transient curl-60 TLS error downloading spdlog's patch on one Windows job (three sibling Windows jobs fetched the same file fine minutes later).
• Remaining honest gap: no CI job runs cmake --preset ninja itself yet (the follow-up below).

Follow-ups (open for steer)

• Preset-based Windows CI job.
• Fix the if(!MSVC) dead condition properly (Clang-gated warning flag) — separate small PR.
• Reconcile docs/documentation/getting-started.html preset names (desktop ↔ ninja).
• README: OS-aware vcpkg bootstrap (.bat vs .sh); flip "Windows (planned)" once CI proves it.
• .vscode tasks/settings/extensions + C++20 fix to c_cpp_properties.json (held pending your call).

Separate from PR #97 (Android publishing); branched off main.

🤖 Generated with Claude Code