labelle-assembler

Code generator and build assembler for the labelle game toolkit.

Reads a game project's project.labelle configuration and materializes the .labelle/<backend>_<platform>/ build directory with all generated build files (build.zig, build.zig.zon, main.zig, plugin manifests, copied source trees). Designed to be invoked as a subprocess by the labelle CLI launcher, so generator versions can evolve independently of the CLI binary.

See the RFC: Split the assembler from the CLI (tracking issue #122) for the architectural plan and migration phases.

Writing a plugin? See the plugin authoring guide for the end-to-end Controller + plugin.labelle walk-through, and examples/plugin-controllers/ for a minimal working example that exercises every layer the assembler wires up.

Build

Requires Zig 0.15.2+.

zig build

The binary is written to zig-out/bin/labelle-assembler.

Usage

./zig-out/bin/labelle-assembler --help
./zig-out/bin/labelle-assembler --protocol-version
./zig-out/bin/labelle-assembler generate --project-root /path/to/game

Generate options

Flag	Description
--project-root <path>	Path to game project (containing project.labelle)
--scene <name>	Override the initial prefab
--platform <name>	Override target platform (desktop, wasm, ios, android)
--backend <name>	Override graphics backend (raylib, sokol, sdl, bgfx, wgpu, null)

The null backend is a headless test/CI backend with no graphics, audio, input, or window subsystem — every backend module is a no-op stub. The generated main() runs the engine's tick loop for LABELLE_NULL_FRAMES frames (default 5) and exits cleanly so defer-bound teardown actually runs. Use .backend = .null in project.labelle for lifecycle / integration / determinism tests that don't exercise rendering — see examples/plugin-controllers/ for a worked example and backends/null/ for the implementation.

Run tests

zig build test

Release binaries

Pre-built binaries are published on the Releases page when a version tag is pushed. Binary naming convention:

• labelle-assembler-macos-aarch64
• labelle-assembler-macos-x86_64
• labelle-assembler-linux-aarch64
• labelle-assembler-linux-x86_64