Build and packaging

One conductor: Kaji

Kaji is the only product build tool. Run it from the repository root:

# Game, monolithic debug build (staged under bin/game/)
bin/kaji/kaji game --workspace="$PWD" --project="$PWD/../hikari-games/example" --type=monolithic --config=debug

# Project-bound editor: develop a game with Play/Edit, scene authoring, recompile
bin/kaji/kaji editor --workspace="$PWD" --project="$PWD/../hikari-games/example" --type=dynamic --config=debug --run

# Standalone editor (no project; boots the project selector)
bin/kaji/kaji editor --workspace="$PWD" --type=dynamic --config=debug --run

# Shippable artifacts
bin/kaji/kaji game --workspace="$PWD" --project="$PWD/../hikari-games/example" --type=monolithic --config=release --package=bundle
bin/kaji/kaji editor --workspace="$PWD" --type=monolithic --config=release --vendor:zig=fetch+bundle --package=bundle

Kaji builds vendor units, the native bridge, Opus, Kawa, Shinra, Akari, the engine core, shader packages, and the native frontends as one dependency graph. Units that do not read each other's outputs build concurrently. Zig emits application and plugin objects; Kaji owns the final executable link on every host. Build units are *.kaji.cs files stored beside their source; vendors enter the graph only through KajiUnitCatalog.RegisterVendor (Tenkai3D).

The platform scripts under build/ (build-game-macos.sh, build-editor-windows.ps1, …) only bootstrap Kaji and forward options. Product policy lives in Kaji, never in those scripts.

Product options

Profiler and diagnostics switches

Older spellings (--profiler, --profiler:modules, --residency) are rejected.

Plan and explain

Host packaging, editor shader staging, the asset toolchain, the game cook and seal, and the distribution package are nodes of the same graph with declared inputs and outputs, so a rebuild that changed nothing runs none of them and explain reports why one would.

kaji localization [--project=<dir>] runs only the localization unit: it compiles assets/localization/<domain>/<locale>.localization.json into .engine/localization/ for the editor and, with --project, the game. zig build roots editor_text/game_text at those generated files and fails configure when a generated Id enum no longer matches its source catalog, naming this command; it never regenerates them itself.

kaji plan game|editor [options] prints the lowered action graph (every command, input, and output) without running anything. kaji explain … adds each action's cache verdict, so "why did that rebuild" is answered before the build. Both take the product options above plus --json.

Graphics diagnostics (D3D12 / Metal)

--d3d12-* and --metal-* are aliases for the same knobs; only the host backend emits defines. The flags in this table are build-time, accept --flag, --flag=true, or --flag=false, and work in either configuration.

Notes:

• Metal validation is process-wide and also wraps AppKit/QuartzCore encoders. On macOS 26 those emit false unused binding warnings at startup, so the warning channel defaults to ignore. Validation errors always log. Use --metal-warning-mode=nslog for an audit, or assert to halt inside the first offending call under a debugger. The mode is compiled in with setenv(…, 0), so MTL_DEBUG_LAYER_WARNING_MODE=ignore ./hikari-editor … overrides it per run.
• Two known false positives in Metal's own bookkeeping (acceleration-structure encoders and MetalFX-opened encoders) are corrected by shims in src/hikari/src/native/macOS/src/MetalDebug.m. Each logs a one-shot "obsolete on this OS, delete it" line if an OS update fixes the layer itself.
• Attribution help in a markers build: the once-a-second encoder census (encoders opened by kind, how many were empty, how many vendor encodes ran) and the per-pass empty-encoder report. If Metal prints an empty-encoder warning and the report does not name a pass, the encoder is not ours.
• On Windows the native logger also appends to %TEMP%\hikari-d3d12-debug.log when the debug layer is compiled in, since a windowed process has no console. D3D12 INFO chatter is filtered at the info-queue storage filter.
• Changing any of these flags rewrites the product-settings stamp and rebuilds the native bridge, so a toggle always takes effect. .cpp/.m edits are tracked build inputs and do not need --clean.

Windows: D3D12 Agility SDK

Windows stages copy the pinned Agility redistributable into bin/game/D3D12/ (D3D12Core.dll, d3d12SDKLayers.dll) and WinPixEventRuntime.dll beside the executables. The frontends export D3D12SDKVersion / D3D12SDKPath so the system loader picks them up. Pins: 3rd-party/d3d12-agility/, 3rd-party/winpix-event-runtime/.

Logging under --run

1. Terminal: product stdio is inherited. Build steps capture their own output; only the final process streams live.
2. Editor UI: the bottom console sink stays registered.
3. File: NDJSON. The editor defaults to <project>/.engine/logs/editor-latest.json once a project is open; the game needs --log=<path>.

Engine-side contract: Frontends and drivers.

Configuration and environment

Product behavior uses explicit options. Native frontends parse launch arguments, copy them into validated startup configuration, and share the host-owned configuration with dynamic drivers. They reject unknown arguments. The same runtime flags above work when launching the executable directly; omit Kaji's --run. The game frontend's --write-package-manifest is a standalone packaging command and cannot be combined with launch flags.

Shinra carries compiler paths in pipeline configuration (--akari-sc=<path>, --kawac=<path>) and passes shader profiles explicitly (--shaders-config=debug|release). Akari accepts compile --dxc=<path> and --config=debug|release; its cache includes the Akari executable identity and native compiler version. Compiler overrides and profiles no longer use project-specific environment aliases.

Child processes do not inherit your shell. Each receives only host plumbing (PATH, home and temp directories, proxies, CARGO_HOME/RUSTUP_HOME, DEVELOPER_DIR, Windows system variables) plus the overrides its toolchain declares, and only those overrides enter the action cache digest. Variables such as CPATH, SDKROOT, RUSTFLAGS, or a Developer prompt's INCLUDE never reach a tool, so they cannot change an output without a rebuild. Toolchains are keyed by their resolved executable and full version line, so a patch release, a dev build, or a different install of the same version rebuilds. Parallel actions never mutate the conductor's environment.

The remaining environment interfaces serve the operating system, external tools, or isolated test harnesses:

Source generation is explicit: zig build generate-document-schemas and zig build generate-cooked-layouts from src/hikari; Shinra fixture regeneration uses its named ignored tests. Ordinary freshness tests never rewrite source fixtures. Build smoke scripts accept --games=<path>, native-style wrappers accept a leading --zig=<path> and --llvm=<root>, and the shader formatter harness accepts its shader tree as an argument.

Stage model

Typed plans in src/kaji/src/Conductors/HikariBuildPlans.cs choose the host and build units. Engine build products install under bin/hikari/; the runnable stage is bin/game/; distribution artifacts land under bin/packages/.

• Dynamic stages separate application, platform, windowing, input, renderer, physics, scripting, and game-UI libraries. Monolithic links them into the executable. The two modes exercise different ownership and loading paths; a monolithic success is not evidence for a dynamic module lifecycle change.
• The editor always dlopens the project's game module after open/recompile. --type= never bakes game code into the editor.
• ProjectConfig emits the driver package manifest from the same typed recipes runtime selection uses, so the stage list cannot drift from configuration.
• Game modules built under the editor pass -Deditor-contrib=true, exposing hi.editor. kaji game omits it, so editor-only game code stays out of shipping binaries (Game editor SDK).
• Plugins are source-composed into the game module from hikari.plugins.json; native link and runtime staging inputs come only from the generated hikari-plugin-artifacts.json (Plugins).

Distribution packages

Without --package, Kaji stops at the staged bin/game/ tree. With it, Kaji filters the stage into a shippable payload and asks the host packager for an artifact:

bin/packages/<slug>-<version>-<platform>-<arch>-<config>/
  Sample.app | Editor.app | *.msix | *.zip

Game slug is the packaging title; the editor slug is editor. A standalone editor package ships the host plus project selector. A project-bound editor package (--project=<game> --package) uses that game's packaging.editor block.

Product resource layout. After cook and shaders, Kaji seals packs under data/bundles/ with the catalog product.shinbundle.map.json (bundles mode) or stages the same paths loose. Without configs/layout.json there is one game pack plus product-sealed engine shaders. With one, each pack declares membership globs, delivery (packed or loose), deps, and labels; a loose pack stages as a directory and stays moddable. Cooked art no pack claims joins default_pack and is reported, never a build failure. Content dirs marked bundled: true may enter the content pack; bundled: false always stages loose under data/<path>/. Details: Data, JSON, and modding, Project file, Product pack layout.

Zig bundling for self-contained editor packages that compile game modules offline:

Pin: 3rd-party/zig/VERSION, which must match the Zig minimum in src/kaji/src/Build/KajiVocabulary.cs (0.17.0).

Host details. Loose and MSIX staging hardlink where the volume allows; the macOS .app copies because codesign rewrites Mach-O in place. Inside an .app, binaries live in Contents/MacOS/ and content in Contents/Resources/data/ with a MacOS/data symlink so exe_dir/data/… lookups keep working. A PNG or .icns icon becomes AppIcon.icns; an Icon Composer .icon (packaging.macos.icon) is compiled with actool into Assets.car plus a fallback .icns and CFBundleIconName, so macOS 26 renders Liquid Glass. Windows .msix requires the Windows 10/11 SDK; certificate selection is left to your release pipeline. Packagers live under src/kaji/src/Packaging/ (IPlatformPackager per host).

Packaging identity

Shipping identity is product-owned JSON that Kaji reads without compiling the game:

Fields: title, product_version, identifier, icon, authors/publisher, macos / windows blocks, optional startup_background_color (#RRGGBB, default black; the solid cover a standalone game shows while the first scene loads; embedded at build time, so rebuild after changing it). See Project file.

Host support

• macOS: Apple Silicon (aarch64) only, Metal 4 MSL, product floor macOS 26. Tenkai3D compiles with Homebrew Odin plus llvm@22 / lld@22. An unversioned brew install llvm produces a stub libtenkai3d.dylib (every export is brk); Kaji fails that at the Odin step. Repair with brew install llvm@22 && brew reinstall odin.
• Windows: x86_64, D3D12 with the Agility SDK staged beside the exe.
• Linux: x86_64 build plumbing exists, but the runtime is incomplete; Vulkan shader cooking is available. Not a product peer (Platforms).

Smoke matrices: build/test-build-macos.sh and build/test-build-windows.ps1 run clean game/editor × debug/release × dynamic/monolithic builds, always passing the Example project explicitly. Pass --games=<path> to select a different games checkout. Game cells verify the cooked bundle catalog; editor cells verify the staged toolchain and reloadable game module without starting the editor. Both first run the Tenkai3D physics gate (python3 src/tenkai3d/tools/test_physics.py --soak; needs Python 3 and Odin on PATH) and stop on a physics failure (physics verification).

Local engine build tasks

Zig 0.17 uses -Doptimize=debug|safe|fast|small for direct build tasks. Windows/MSVC bindings use explicit C preprocessing in src/hikari/build/c_bindings.zig before translation to preserve pointer qualifiers; included headers remain tracked dependencies.

From src/hikari, direct Zig tasks remain useful for focused validation: zig build test -Dgame-src=<abs game src>, zig build test-graphics …, zig build entity-bench …, zig build check-windows …. Use Kaji for real game and editor products; do not assemble ad hoc links. See Development → Validation.

Rust dependency resolution

Akari and Shinra keep their Cargo.lock files in version control. Kaji invokes Cargo with --locked, so a build fails if a manifest change requires a different dependency resolution. Update the affected lockfile explicitly with the dependency change and include it in the same commit.