Assets and Shinra

Hands-on walkthroughs: First mesh and material, Assets in Play.

Source and runtime assets

Games keep source assets under their package, normally src/games/example/assets/:

Shinra also cooks scenes (.shinscene) and prefabs (.shinprefab). Wire details: Asset formats.

The engine's runtime asset APIs are in src/hikari/src/assets/. Three layers:

1. Game / engine — only AssetStore / AssetRef / scene_document (no packaging knowledge). Load is retain* / release* / pinPath; has* is a bool probe, never a borrowed pointer.
2. Asset facade — AssetStore caches and decodes; all raw IO goes through assets/io.AssetIo.
3. Backend — default assets/backends/shinra_io.zig (comptime) implements packs + loose/data trees. Wire formats live in assets/formats/; .shinbundle open lives under assets/bundle/ and is only used by that backend.

The editor live loop uses assets/asset_pipeline_daemon.zig (tool protocol; brand isolated there).

Asset pipeline (Shinra tool)

Shinra (src/shinra) is the Rust asset compiler. Kaji builds it to bin/shinra/<platform-arch>/shinra. It processes inputs in parallel, supports sidecar metadata, watch mode, deterministic manifests, optional bundles, and validation. --target macos-metal|windows-d3d12|linux-vulkan drives texture compression (not runtime asset code). Kawa scripts cook via --kawac <path> (Kaji passes the staged kawac) or $KAWAC when invoking Shinra directly.

All independent asset work uses one batch-outcome contract, including plugin assets (audio, textures, models, scripts, fonts), authoring companions, particles, scenes, prefabs, and shader specifications. A source-local parse/import/compile failure records only that source as failed; sibling work and later phases continue, every successful output is published immediately, and the manifest is generated from the usable output tree before the batch reports an aggregate error. An outer pipeline error is reserved for infrastructure failures that prevent a phase from running, such as an unreadable input tree or unavailable required tool. Watch mode follows the same isolation rule: a failed change never invalidates sibling outputs, and atomic producers retain the failed source's last-known-good artifact.

On Windows, Kaji sets LIBCLANG_PATH from known LLVM / Visual Studio Clang install paths when building Shinra (bindgen needs libclang.dll). An existing valid LIBCLANG_PATH is left unchanged. The same pass sets CMAKE (and prepends its directory to PATH) from the Visual Studio CMake component or a standalone CMake install so opusic-sys can compile libopus. An existing valid CMAKE or a cmake already on PATH is left unchanged.

Shinra also needs a working C toolchain on every build host: ufbx is compiled through cc (same as intel_tex_2 / audiopus). The generated Rust bindings carry no rustdoc — read ufbx.h for semantics. audiopus is the Flakebi/audiopus git fork (pinned rev in Cargo.toml) for Windows-friendly linking; do not switch to crates.io-only without validating Windows builds. Ogg sources sniff OpusHead vs Vorbis ident: Vorbis decodes (lewton) then cooks; Opus + format: OpusOgg pass through into .shinaudio; Opus + PCM format is a hard error (use WAV/Vorbis). Do not feed Opus Ogg through lewton.

Kaji builds Shinra as release by default even when the product is --config=debug (host tool). To debug the pipeline itself:

bin/kaji/kaji editor --project=src/games/example --shinra:config=debug
# equivalent:
bin/kaji/kaji editor --project=src/games/example --dep-config=shinra:debug
bin/kaji/kaji shinra --shinra:config=debug

Sidecar files use <filename>.shinmeta.json. They configure texture mipmaps/sRGB/premultiplication/compression quality, audio normalization/sample rate/format/streaming, and model LOD/optimization/compression behavior. Model allow_cpu_access defaults to false; enable it only when runtime code must inspect decoded render geometry. Static rendering and separately cooked collision do not need it.

Common command shape

shinra --input assets/ --target macos-metal
shinra --input assets/ --output build/assets --target windows-d3d12 --validate
shinra --input assets/ --target macos-metal --watch
shinra --input assets/ --target windows-d3d12 --bundle game --compression zstd
# Domain pack (product seal / Kaji --resources=bundles): logical root ≠ output
shinra pack --name scenes --root data/ --output data/bundles/ --subdir scenes --include-ext shinscene

The default output mirrors source folders and emits assets.shinmanifest.json plus packs.shinplan.json (resolved pack membership). Kaji product cook always runs --bundle game, writing intermediate game.shinbundle + game.shinbundle.json under the cook work tree and .engine/staged/shinra (TOC membership only — no per-stem .map.json). That intermediate is not a product catalog stem; seal strips any copy that lands under data/bundles/. Editor watch (--watch) does not pass --bundle.

Product builds seal logical domain packs via Kaji --resources=bundles|loose (default bundles): configs/layout.json (v2) defines each pack's membership globs, delivery (packed or loose), deps and labels; Kaji always seals engine on full game builds. With no layout.json the whole project ships as one packed pack. Seal places what the plan says and writes {stem}.shinbundle (v3, TOC embedded; the .shinbundle.json beside it is informational), then writes the product.shinbundle.map.json v3 catalog: per pack delivery, deps, labels and loose root — a packed pack's membership is its own TOC, which the runtime maps at store open (not a mega-pack, not the cook game stem). See Product resource layout.

Scene documents (JSON + HSC1)

• Authoring: scenes/*.json with kind: com.hikari.scene (editor always has UTF-8).
• Cook: Shinra owns it — pass --scenes <project>/scenes (Kaji does this on product asset builds). Emits only under cook/work output/scenes/*.shinscene (HSC1), same as other cooked assets — not next to authoring JSON. Product stages into data/scenes/ (then seal may pack). Watch mode re-cooks into the cache/work tree.
• Runtime load: only via AssetStore (scene_document.loadFromStore): HSC1 .shinscene in non-Debug builds, with authoring .json fallback only in Debug. Loose / data_root / bundle — store decides.

Prefab documents (JSON + HSC1)

Full expand/diff/variants/editor/runtime contract: Prefabs.

• Authoring: assets/prefabs/**/*.prefab.json with kind: com.hikari.prefab (editor always has UTF-8).
• Cook: Shinra --prefabs <project>/assets/prefabs (Kaji when the directory exists). Emits only under cook/work output/prefabs/**/*.shinprefab (same HSC1 wire as scenes; envelope validates prefab fields). Product stages into data/prefabs/. Watch re-cooks into the cache/work tree.
• Runtime load: AssetStore retainBlobKind(…, .prefab) prefers .shinprefab; World.retainPrefab decodes HSC1 without JSON. Authoring .prefab.json only in Debug.

Asset URIs and packs

Game modules use typed hi.AssetRef for dynamic binds; scene JSON stores the same URI strings. See Game-facing refs.

Cooked assets are asset:// only. content:// (AssetStore tables under content_dirs), writable://, and project:// (filesystem) are ContentRef, not cooked-asset URIs.

Two asset:// prefixes (no pack-search / .../ form). Bare paths are an unscoped alias:

./ is not FS-relative (not “next to this model / this scene file”). It means no pack segment in the URI. The path is still absolute under the product data root (models/cube). Shinra bakes multi-mesh GLB companions this way (asset://./scenes/…/DamagedHelmet_img0) so pack membership can move without rewriting every companion ref.

Engine-owned meshes do not enter Shinra or scene preload residency. In addition to asset://_engine/meshes/unit_plane, scenes can request an indexed displacement grid as asset://_engine/meshes/grid_plane_<segments> (1–512). Shared vertices make a 256×256 surface roughly one sixth of the vertex upload and vertex-shader work of triangle soup.

Resolve rules (packs mode)

1. Explicit asset://shared/models/cube → use pack shared if retained, else fail (PackNotRetained).
2. Unscoped asset://./models/cube → look up models/cube in the product catalog (one path → one pack at seal). That pack must be retained, else fail. Does not search across open packs.
3. Uncatalogued path inside a loose pack's root → resolves from disk while that pack is retained. This is the mod case: a file the seal never saw behaves exactly like a sealed member.
4. Anything else uncatalogued (content dirs, always-loose leftovers) resolves from the data plane as before.
5. Seal dual-home is a build error: one logical path, one pack. Valid catalogs never need "first retained pack wins".

Scenes do not declare packs

A scene document has no packs field. Which packs a scene needs is computed at load from the assets it references:

closure(scene) = { packOf(ref) : ref ∈ scene refs }  then + deps of each, transitively

scene/scene_pack_closure.zig does the first half; the backend's retainPack does the second. Consequences worth knowing:

• A scene cannot name a pack that does not exist, or drift from configs/layout.json.
• A scene authored after the build — by a modder, with no cook and no seal — resolves like one that shipped.
• The walk is shallow: only the scene's own references are visible, because a model document's meshes live inside a pack and reading them would need it open already. Packs are directory-shaped in practice; where they genuinely are not, the owning pack declares a dep. Per-pack deps are O(packs) to author, where per-scene lists were O(scenes).
• An older document's packs array is ignored with a validation warning.

The editor's Scene Packs tab (left dock) shows the closure and which reference pulled each pack in.

Shared art is referenced either as asset://shared/models/cube (pack explicit, greppable) or asset://./models/cube (catalog maps path → shared). Neither needs a scene-side declaration.

Editor live tree: the store opens with the cook plan as its catalog (packs.shinplan.json, read by BundleCatalog.loadPlan), so hasPack, packOf, packsForLabel and hi.host_api.packs() answer exactly as the product will. Retains are advisory there — nothing is mapped and no read is ever gated — but they are counted, so stat and the handle API behave the same in Play-in-editor as in a packed build. A tree that has not cooked yet has an empty catalog and stays fully readable.

Opening packs from game code

hi.host_api.packs() — open(stem), openLabel(label), close(handle), stat(stem), list, handlePacks. Handle-based so a retain is attributable and Play/Stop can drop what game code held. open makes assets resolvable; it is not a load — use the residency API or a scene load to wait for bytes. Delivery is invisible at this layer: a loose (moddable) pack and a packed one open, count and close identically. stat and list are two catalog lookups with no allocation (AssetIo.packRefs / packStems), so polling them per frame is fine.

Every scene load — sync, job, and the preload bridge — retains its closure through one function, scene_pack_closure.retainPacks, and every walk over a scene's references (closure, Scene Packs tab, tests) goes through scene/scene_asset_refs.zig. A reference added to an actor descriptor is added there and nowhere else.

One place resolves membership

configs/layout.json is authored; packs.shinplan.json is resolved. The Shinra cook matches the include globs against the cook tree once and writes the plan beside assets.shinmanifest.json. Kaji seals what the plan says; the editor reads it in Project Settings → Packs and in the Scene Packs tab. Neither matches a glob, so the partition the editor shows is the partition the product ships. Watch mode rewrites the plan when the cook tree changes and when layout.json is saved.

Implementation: assets/asset_ref.zig, assets/backends/shinra_io.zig, assets/bundle/catalog.zig, scene/scene_pack_closure.zig, game_api/host_bind/packs_api.zig, Shinra pipeline/pack_plan.rs, Kaji ProductResourcePacker + PackPlan.

Asset residency (refcount)

Shared CPU decode lives in AssetStore: retain/release, optional pin, immediate free at refs == 0 when unpinned. Materials, bound meshes, skybox/probes, audio, shaders, and scene loaders are the consumers.

Full overview (what is tracked, who holds what, refs → 0 policy, overlap/streaming, diagnostics): Asset residency.

Game and editor behavior

Launch matrix (first-class; no dual-read fallback)

One rule: the stage on disk is the product. Kaji (Shinra cook + Akari + seal) writes it; the runtime opens whatever layout is present. --run is optional — the same tree is what a manual launch or host package (.app) uses. --clean wipes stages; rebuild restages; open never invents a second cooked root at load time.

Runtime selection is self-describing (runtime_session/assets.zig):

1. loose_assets_root set → editor live (cooked tree only; project/content FS is a separate plane for authoring/content://, not a second look-up for cooked binaries).
2. else data/bundles/product.shinbundle.map.json present → product packs.
3. else → product loose (entire cooked tree under content_root = data/).

There is no “try packs then fall back to loose files for packed domains,” and no “read engine shaders from product data while the live tree is empty.” Missing engine metallibs in the live tree are materialized once into that tree from the product install, then opened as the single cooked root.

Editor watch layout (under the project .engine/ tree — do not commit):

All project-local engine artifacts live under <project>/.engine/ (clean cut — project root is source only: no data/ stage, no assets/.shinra, no cooked siblings):

Shipped / runnable product still stages under bin/…/data/ (runtime exe_dir/data), including packs in data/bundles/ when --resources=bundles.

Batch CLI runs still default shader cache to <output>/.shader-cache unless those flags are set.

Editor live protocol

Shinra watch mode speaks a line protocol on stdout (human logs on stderr). Handshake is @shinra hello v3:

The editor supervises the child over pipes, coalesces events per path (bounded, 8192 unique paths), defers apply while Play is active (@shinra busy is UI status only), and reloads the scene only when a terminal event references authored actors. Dropped queue notifications trigger one @cmd rebuild-all per overflow burst (debounced through busy→idle / catalog); daemon disconnect keeps soft-pending (child process_all on restart recovers). Stdin accepts @cmd quit, @cmd rebuild-all, and @cmd rebuild <source_rel> (also used for portable Windows shutdown via quit + stdin EOF).

Toolbar asset-pipeline pill hover opens a list tip (popup chrome): caption header, relative stem rows with trailing kind meta from AssetStore (Shinra type= / path suffix / explicit retain), capped with an overflow footer. That is the set the editor has observed via Shinra events or soft open misses — not Shinra’s full internal cook queue.

Invariant: every @asset pending is paired with a later available/rebuilt/failed/removed for that key (watch requeues mid-flight saves).

failed is source-scoped, never batch-scoped: Shinra must not fan one failed source out across unrelated cooked keys. A partial batch may therefore emit both rebuilt events for successful assets and failed for the bad source before returning a non-zero batch result. Shader packages additionally commit their native libraries atomically, so a rejected replacement cannot truncate the library that the running editor is using.

Authoring materials / model docs (.material.json → .shinmaterial, .model.json → .shinmodeldoc) are not plugin work items. On initial process_all (watch mode start, including kaji editor … --clean --run):

1. They cook before the parallel model/texture pass so the live work tree has materials while the editor still binds the project scene (game-module compile splash often overlaps Shinra).
2. Each successful cook emits a terminal event for both the authoring JSON key and the cooked binary: available on a byte-identical cache hit, otherwise rebuilt. Soft-miss / pink error stand-ins upgrade without a full scene reload.
3. @asset catalog at end of the pass also triggers a soft rebind pass (notifyAssetsMayBeReady) so any residual stand-ins retry once the work tree is complete.

Graph-authored materials add an offline lowering step to that same material path. Shinra probes each .material.json for a com.hikari.material-graph payload before parsing it strictly — that ordering is what separates an ordinary hand-authored Akari material (skipped, correctly) from a graph this build cannot read (reported as a failure). It then validates node ids, slots, types, sampler-slot uniqueness and acyclicity, and writes generated Akari plus a target-specific transient spec under --shader-cache-dir/material-graphs/. Generated source is cache output, never project source; sources whose material was deleted or renamed are pruned on every pass. Batch builds merge the transient spec with the explicit project/engine specs.

Watch mode is scoped twice, and both matter for editor latency. A graph save that lowers to byte-identical Akari compiles nothing — every node drag is one of these, because positions live only in the authoring document and never reach the shader. When the lowering does differ, only the generated spec is recompiled: the engine and game specs cannot have changed, and compiling the merged set meant one compiler process per spec per debounced keystroke. Successful native libraries publish atomically; an invalid graph leaves the last-known-good library live and fails only that material source.

Soft refs and load/hot-reload recovery

Content references (mesh, material, texture, shader, script, archetype) are soft: a missing or failed asset must not crash the process or abort the whole scene. Authored paths stay in the scene document; runtime binds best-effort and recovers when the asset reappears.

Shader cooks follow the same rule per package. Shinra publishes every library Akari produced even when another package fails, and live watch retains the failed package's last-known-good library. Only the changed source is reported failed; unrelated shader-library keys are completed as rebuilt, so one bad material cannot invalidate the renderer's engine libraries. A clean cook has no previous binary for the failed package, so that package alone uses the normal soft fallback until fixed.

Shared runtime (editor preview world and packaged game use the same path): AssetStore states, soft material retain, soft mesh bind, soft script attach, soft archetype spawn, pink error shader, skybox color fallback.

Editor-only: Shinra watch / hot-reload apply, hierarchy/inspector health UI, game-module Recompile + archetype audit, deferred apply while Play is active.

Implementation: assets/ref_status.zig, ref_log.zig (once-per-issue logs), ref_consumers.zig, actor_health.zig, error_mesh.zig, material_cache.zig, scene/scene_loader.zig, editor/editor_app/hot_reload.zig.

Status model

Editor startup: while Shinra is still processing the queue, absences are pending, not missing — console must not spam “texture/mesh missing”. Terminal only after @asset failed / removed or a hard decode failure.

state_generation bumps on state change so the editor can refresh health icons without thrashing every frame.

Cause → result (by asset kind)

Each row is cause → result. Viewport/runtime behavior is the same in editor and game unless noted.

Mesh (.shinmodel)

The mesh path cooks unique vertices plus meshlet topology. Import normalizes non-indexed source primitives to an index list, optimize_mesh welds identical attribute vertices and removes degenerate triangles, then SRM1 v5 writes vertices, 64-byte meshlet descriptors, remaps, and packed micro-triangles — no index buffer on disk. Hikari converts each unique vertex once into the engine layout, materializes a u32 index stream from the meshlets for BLAS and physics only, concatenates per-LOD slices, and uploads the meshlet topology used by every scene-mesh raster lane. Static CPU staging is released after the GPU snapshot unless the model explicitly sets allow_cpu_access; render residency never creates a triangle-corner copy.

Editor: hierarchy destructive only when mesh is failed (not while pending).
Game: same viewport; no hierarchy/inspector chrome.

Material (.material.json)

Editor / game: same soft retain and pink stand-in.
Editor only: health banner + hierarchy warning when material is the error stand-in or path is missing.

Shader (compiled package / library)

Editor: pipeline events drive store + in-place material/pipeline rebind; console gets once-logs.
Game: no live shader recompile loop; missing packaged shader → pink at first material load.
Log noise: successful pink fallback for pending packages is often debug (see config section).

Texture (.shintexture)

Editor / game: same bind + fallback textures.
Editor: hierarchy broken only for failed slots, not pending in-flight.

Script (.kawa → .kawabc)

Editor / game: same soft attach.
Editor only: live Shinra recompiles scripts; health can show script pending/broken.

Zig archetype (game entity type)

Editor (dynamic): Recompile button + staged dylib + restore path. The compile and the swap each log their wall-clock time (game module gen-N built in … ms from the frontend, game module swap took … ms from the session under the game.module_swap profiler zone). Frame pacing drops to the idle cap while the compile runs so the editor does not compete with zig build for cores.
Editor (monolithic): no game-module hot reload.
Game: no recompile; unknown archetype at load still soft-spawns _missing if builtins registered (engine always registers core placeables empty / light / camera / visual_zone plus soft hosts _missing / _asset / _script / _audio).

Hot-reload pipeline edge cases (editor)

Game: no Shinra watch daemon; assets are load-time only from bundle/loose config. No deferred Play queue.

Cold load vs hot reload

Editor vs game (summary)

Debug vs release config

Soft behavior (placeholders, continue scene, no crash on content) is the same in debug and release builds.

There is no separate “strict fail content in release” mode: shipping builds still soft-bind so a bad asset does not take down the process. Fix content and rebuild packages for clean shipping data.

Recovery cheatsheet

Asset authoring rules

• Keep raw assets and sidecars in the game package; do not write generated assets into engine source folders.
• Treat Shinra output and bundles as generated artifacts.
• Keep platform-specific compression in Shinra configuration, not in runtime asset consumers.
• Validate output after format or bundle changes.
• Use the engine's checked-in shader packages for required renderer passes; add game packages only for game materials/effects.