Build Process Reference

A request selects a game, engine, platform, architecture, build type and optional deployment. rustTools validates that combination, optionally exports assets, creates or updates the engine project, then builds, packages and deploys only when a deployment target was requested. The cache changes where a supported Axmol game build gets its engine libraries; it does not skip game code, Fission code, linking, assets or packaging.

Run project without arguments to choose a game and settings in the interactive menu. FISSION_PROJECT_DIR can pin the game directory for that flow. Command-line runs supply key:value settings. Run from the game directory, or set dir:<path> (or FISSION_PROJECT_DIR) to select it. The tool validates engine/platform and deployment support before starting work, then performs any deployment credential preflight.

For several architectures, the launcher may run an architecture-specific child process. macOS universal builds use the Axmol macOS path: separate slices are built and combined into one application.

Axmol setup selects the engine branch for v2 or v3 in source mode. The Axmol command creates a C++ scaffold; rustTools then writes the Fission CMake integration and build options, copies game content and icons, applies target-specific settings, and generates or builds the platform project. A cached v2 macOS run resolves packages first and uses imported CMake engine targets instead of adding Axmol core sources to the game build.

The generated Axmol tree is under the game's tmp/obj/ax output. The engine package cache lives outside that tree, so project regeneration does not remove shared packages. The generated CMake options retain the selected package paths across regeneration.

The Axmol command drives the native build. On cached macOS runs, rustTools configures an Xcode project in the correct architecture-specific build directory before asking Axmol to build it. This matters for packaged dependencies such as OpenAL: the generated project must use the Xcode generator and the build directory the Axmol command expects.

The game and Fission code still compile and link. The macOS build and packaging path produces the app, embeds the package's compiled shaders and soft_oal.framework, restores framework symlinks and checks architecture. Cached local apps are ad-hoc signed and verified; universal builds combine the arm64 and x64 app/framework slices and re-sign the result. A DMG is attempted for non-App Store output. Other platforms follow their existing packaging paths; iOS also invokes its Fastlane build step.

The interactive menu shows engine_cache only for engine:axmol on macOS. Its initial selection is source, unless a valid AXMOL_ENGINE_CACHE_MODE is already in the environment. Command-line runs set the environment variable directly; engine_cache is a menu setting, not a command-line build parameter.

The cache uses one immutable package per architecture and configuration. Its key covers the committed Axmol revision and submodules, engine build type and features, architecture, deployment target, toolchain/SDK and relevant compiler settings. Game names, assets and bundle identifiers are excluded, which lets compatible games share a package. Each package has a versioned manifest; every required library, header, CMake and resource payload is hash-checked before use. Builds use a private source snapshot, a per-key lock and atomic publication, so an incomplete package is never presented as a hit.

On macOS, packages default to ~/Library/Caches/rustTools/engines/axmol/<key>. Set RUSTTOOLS_ENGINE_CACHE_DIR to an absolute directory outside the game output to use another cache. Package contents include engine and transitive libraries, public/generated headers, CMake metadata, shaders and the OpenAL runtime.

In the project menu, choose Axmol, macOS and then engine_cache. Choose source for the standard path, automatic to reuse or prepare a package, or require-cached when a cache miss should stop the build. On the command line, run from the game directory and set the mode in the environment:

AXMOL_ENGINE_CACHE_MODE=automatic <project-binary> \
  engine:axmol platform:mac arch:arm64 build:debug \
  market:local export_assets:false

Omit market:local to generate the project without doing a local package build. Use arch:arm64,x64 for a universal macOS build; both matching packages are resolved separately. export_assets:false assumes that the game's exported asset artifacts already exist. The explicit prebuild path uses a normal single-architecture Axmol v2 macOS request with AXMOL_ENGINE_CACHE_PREBUILD=1; it prepares the engine package and exits before generating the game project.

Axmol runs print AXMOL_CACHE_PROFILE lines for engine setup, cleanup, staging, scaffold, CMake changes, content, target setup, scaffold sync, build/generate, packaging and total. Set AXMOL_CACHE_PROFILE=0 to suppress them. These phase timings cover generation and the Axmol build path; the entire project command also prints elapsed time at completion.

A validated hit currently hashes the full package, so validation itself has measurable cost: about 16 seconds for the 507 MB arm64 package in the recorded run, and about 33 seconds for two architectures. The roadmap covers the next performance work.

Implementation entry points: project/src/main.rs, plan.rs, engine/axmol/axmol_project.rs, engine/axmol/engine_cache.rs and engine/cache.rs in rustTools. For the work still ahead, see the Build Process Roadmap.