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/src/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/src/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/src/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 yes, Tenkai2D no).

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 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. All 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.

Stage model

Typed plans in src/kaji/src/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, design in resources-layout-and-logical-packs.

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

Pin: 3rd-party/zig/VERSION, which must match src/hikari/build/Hikari.kaji.cs.

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 and skips Akari shader compile. Not a product peer (Platforms).

Smoke matrices: build/test-build-macos.sh runs clean debug/release × dynamic/monolithic (dynamic via kaji game, monolithic via kaji editor, every cell with --project=). build/test-build-windows.ps1 runs the same grid but omits --project= on its game cells, so it is not yet a green peer. Both first run the Tenkai3D physics gate (python3 src/tenkai3d/test.py --soak; needs Python 3 and Odin on PATH) and stop on a physics failure (physics verification).

Local engine build tasks

From src/hikari, direct Zig tasks remain useful for focused validation: zig build test -Dgame-src=<abs game src>, 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.