Build Process Roadmap

Starting point

delivered

The current implementation can build, validate and reuse standalone Axmol v2 packages for macOS arm64 and x64. A generated game project imports the matching package, while the source path remains the default. macOS scaffold regeneration retains compatible build products. Christmas 17 and Pinecreek Hills Park reused one arm64 package; universal Park Ranger 18 and Pinecreek builds exercised both architecture slices. The reference describes those shipped behaviors in detail.

Rollout rule Keep source as the default until supported combinations have equivalent behavior, reliable recovery paths and measured end-to-end benefits. The roadmap adds support in validated steps; dates and speedup percentages are not yet committed.

Make reuse worth the lookup

next measurement

Strict package validation currently rehashes every file on a hit. In the recorded macOS run, that cost about 16 seconds for one 507 MB package and about 33 seconds for a universal pair. The next performance pass should reduce validated-hit cost without allowing stale or changed payloads to be consumed.

MeasureRepeat the same four-game workload with cold cache, warm cache, repeat build and project regeneration, recording the host, toolchain, engine revision and cache state. SeparateRecord engine compilation, game/Fission compilation, linking, package validation and packaging separately. The earlier total time mixes those costs. AcceptOnly count a speedup when equivalent source and cached builds are compared under controlled conditions and the resulting apps pass the same architecture, signing and startup checks.

Extend Axmol by target

planned

Each target needs its own package recipe, native dependencies and consumer checks. Axmol v3 is a separate configuration and must be validated independently of v2. Automatic mode currently stays on the source path outside v2 macOS; require-cached reports that package consumption is unavailable.

Target	Implementation work	Exit check
Windows	MSVC toolset/runtime identity, architecture-specific libraries, DLLs and shaders.	CLI and Visual Studio builds; application launch.
iOS	Device and simulator packages, deployment targets, native libraries and resources.	Simulator launch and signed device archive.
Android / Fire	Per-ABI packages matched to NDK/native API settings and Gradle/Android Studio consumption.	Applicable APK/AAB output and application launch.
Web	Emscripten version, threading/SIMD and final-link requirements, JavaScript support and resources.	Browser startup, asset loading and representative engine behavior.
Axmol v3	Independent recipe and dependency/resource inventory on each supported target.	Source comparison and warm-cache build with no vendor engine compilation.

For every supported combination, verify that public engine requirements reach both game and Fission compilation, compare source and package behavior, and inspect a warm-cache build to confirm vendor engine sources are absent.

Add everyday cache operations

planned

The current prebuild flag is useful for preparing one macOS package. The next operator-facing layer should expose status, prebuild, rebuild and clean through existing CLI/menu conventions, report hits and misses clearly, and explain which input changed a key. Failed builds and concurrent requests must remain predictable, and routine pruning must protect packages still referenced by generated projects.

Exit condition A developer should be able to inspect a package, prepare a missing one, recover from a bad one and return to source without editing generated CMake files.

CI transport and default rollout

planned

Build packages on suitable host runners, upload only validated artifacts, then restore by exact fingerprint and check integrity. Verify that package paths remain portable across machines. Invalidation tests should change vendor revision, engine features, architecture and toolchain inputs one at a time.

Use cold-cache, warm-cache and cross-game timings to decide whether automatic caching should become the default for a particular validated combination. Keep the source mode available for diagnosis and unsupported cases. A warm cache still incurs game compilation, linking, asset work and packaging.

Later backend expansion

after Axmol

The shared manifest, fingerprint, locking and publication code is backend-neutral. After the Axmol rollout, measure build costs for cocos2d-x, raylib, bgfx and Magnum, select the next worthwhile backend, and add its package recipe and build integration. The current plan does not require a second backend to complete Axmol support.

Source plan in rustTools: docs/AXMOL_ENGINE_CACHE_PLAN.md. This page tracks the intended direction; the Build Process Reference remains the authority for what is available now.