# Hikari

> A GPU-driven renderer, a live editor, and an agent that works in your project.

Hikari is in development and currently closed for internal use. The project has committed to open-sourcing the engine later. These files describe the current implementation, not a released compatibility contract. Documentation is English-only. All readers share the canonical Markdown exports under /docs/. Follow the links below for command syntax, configuration, and implementation details.

## Overview

- [Engine documentation](https://hikari.dev/docs/index.md): Public documentation for implemented engine behavior. Public pages are published by the Hikari website; proposals, roadmaps, maintainer checklists, and design archives are excluded from publication.
- [Routine scheduler benchmark](https://hikari.dev/docs/reports/routines-benchmark.md): Local macOS arm64 run, 2026-09-16, Zig 0.16.0 ReleaseFast. Reproduce from src/hikari with zig build routines-bench -Dgame-src=<absolute-game-src> -Doptimize=fast (one command). This is a synthetic hea
- [Shared AI perception benchmark](https://hikari.dev/docs/reports/ai-perception-benchmark.md): Measured 2026-09-07 on Apple M5 Max, macOS 26.6.2, Zig 0.16.0, ReleaseFast.
- [Swarm Brain benchmark](https://hikari.dev/docs/reports/ai-population-benchmark.md): Measured 2026-09-22 on Apple M5 Max (arm64), Zig 0.16.0, ReleaseFast.

## Tutorials

- [Tutorials](https://hikari.dev/docs/tutorials.md): Hands-on onboarding for game packages. Sample project: hikari-games/example/. Deep behaviour lives in systems/; authoring how-to in guides/.
- [Tutorial: Play, Edit, and scenes](https://hikari.dev/docs/tutorials/play-edit-and-scenes.md): Editor mode and scene loading are the most common sources of “my script did nothing” / “Stop wiped my level.” This page covers the rules you need day one.
- [Tutorial: first UI document](https://hikari.dev/docs/tutorials/first-ui-document.md): A UI document is a screen authored as data. You build it in the editor, place it in a scene, and drive it from code through named slots and events. Reference: UI documents; the widget vocabulary is th
- [Tutorial: first game project](https://hikari.dev/docs/tutorials/first-project.md): What you need for a new game package the editor and Kaji can open. The sample under hikari-games/example/ is the reference layout.
- [Tutorial: first entity](https://hikari.dev/docs/tutorials/first-entity.md): An entity is an archetype (string id) plus a tuple of components. Engine capabilities (hi.ComponentRender, hi.ComponentPhysics, …) and game logic (defineComponent) are listed together. The build recur
- [Tutorial: component properties and the inspector](https://hikari.dev/docs/tutorials/first-user-data.md): Supported logic-component fields become inspector properties automatically. For the default attachable storage, the scene saves them under components.<component_name>. metadata.properties is optional 
- [Tutorial: first mesh and material](https://hikari.dev/docs/tutorials/first-mesh-material.md): Rendered actors need an explicit mesh and material in scene JSON when the archetype lists hi.ComponentRender. Paths use asset:// URIs (hi.AssetRef at runtime).
- [Tutorial: first physics body and trigger](https://hikari.dev/docs/tutorials/first-physics.md): Opt into physics with hi.ComponentPhysics on the archetype, then author a physics block under scene "components". Scene-authored physics defaults to Static when body_type is omitted (or the whole bloc
- [Tutorial: first character controller](https://hikari.dev/docs/tutorials/first-character-controller.md): Drive a capsule with collide-and-slide instead of a dynamic rigid body. Author a physics actor with is_character_controller, set desired velocity each tick via hi.world().setVelocity, and read grounde
- [Tutorial: first session services](https://hikari.dev/docs/tutorials/first-session-services.md): The engine has no “global entity” archetype. Cross-scene state and HUD belong on the optional GameSubsystem, which outlives scene replace. Scene JSON is for placeable content only.
- [Tutorial: first UI](https://hikari.dev/docs/tutorials/first-ui.md): Runtime UI is immediate-mode: each frame you rebuild widgets through the bound UI facade (const ui = hi.ui();). Nest controls in stacks (ui.vStack / ui.hStack) and always defer ui.end(scope).
- [Tutorial: first input action](https://hikari.dev/docs/tutorials/first-input.md): Gameplay code should read named actions, not raw key codes. Bindings live in JSON; Zig and Kawa both resolve the same ids.
- [Tutorial: first messages](https://hikari.dev/docs/tutorials/first-messaging.md): Prefer hi.actors / Actors.* for find, send, and (when needed) name-keyed component fields. Delivery is deferred until after entity updates in the same Play tick. Zig and Kawa both use the World event 
- [Tutorial: first runtime spawn](https://hikari.dev/docs/tutorials/first-runtime-spawn.md): Scene JSON is not the only way to create actors. Spawn at runtime from session code or an entity when content is dynamic (pickups, VFX hosts, debug helpers).
- [Tutorial: first motion](https://hikari.dev/docs/tutorials/first-motion.md): Motion Kit (hi.motion, hi.Tween, hi.Spring, …) animates values you own — entity fields, subsystem HUD state, editor chrome. Do not hang timelines on UiContext.
- [Tutorial: first skeletal animation](https://hikari.dev/docs/tutorials/first-skeletal-animation.md): Cook a skinned glTF into a .shinmodel with skeleton + clips, place it with hi.ComponentRender + hi.ComponentAnimation, and either play a clip by name or bind an animation graph.
- [Tutorial: assets in Play (soft refs and hot reload)](https://hikari.dev/docs/tutorials/assets-in-play.md): Content refs fail softly; the editor can hot-reload Shinra output. Play mode defers applying asset reloads until Stop (or when Edit allows).
- [Tutorial: dynamic editor recompile](https://hikari.dev/docs/tutorials/dynamic-recompile.md): Every editor build loads game code as a dynamic module, regardless of the host linkage selected by --type. The toolbar Recompile rebuilds that module and swaps it when Edit mode allows — without resta

## Guides

- [Guides](https://hikari.dev/docs/guides.md): Task-oriented guides for editor users, game programmers, and engine contributors. Start with the guide matching your work; implementation-heavy guides are not prerequisites for editing a scene.
- [Working in the editor](https://hikari.dev/docs/guides/editor-workflow.md): For artists, level designers, and other team members who work without writing code. This guide covers opening a prepared project, placing and editing content, testing it, and saving your work. You do 
- [Development guide](https://hikari.dev/docs/guides/development.md): Read the closest AGENTS.md before changing a subsystem. The root guide describes repository-level build/platform rules; engine, Kaji, Kawa, Shinra, and physics packages have local constraints.
- [Gameplay API](https://hikari.dev/docs/guides/gameplay-api.md): defineActor defines an actor type by composing components. Spawning creates an instance. defineComponent declares ordinary Zig data, optional lifecycle hooks, and a generated scene/editor schema. Cont
- [Actor and component lifecycle](https://hikari.dev/docs/guides/component-lifecycle.md): hi.defineActor composes component types. It does not accept actor-level lifecycle functions: implement optional pub fn hooks on a component's Data struct and put that component in the actor's .compone
- [Threads, jobs, events, and routines](https://hikari.dev/docs/guides/concurrency.md): Use Flow/Timer for tiny caller-driven state and delays. Use routines when keeping ordinary locals, loops, and nested calls makes gameplay code easier to write. Events can update state that a routine o
- [Gameplay AI tasks](https://hikari.dev/docs/guides/ai-tasks.md): hi.ai.tasks extends the Brain executor with game-defined actions. The same action can run from a cooked Brain asset or a hi.ai.brain.compile definition in Zig. Built-in move_to and wait remain availab
- [Game AI: perception and movement playground](https://hikari.dev/docs/guides/game-ai.md): The example game's AI Perception & Brains scene demonstrates noise investigation, visual pursuit, last-seen search, and return to patrol. An in-game panel owns the instructions, noise controls, and gu
- [Brain assets](https://hikari.dev/docs/guides/brain-assets.md): A Brain is a reusable AI state/task program. Author a .brain.json document, assign it through a component's Brain picker, and let Shinra compile it to .shinbrain. Actors share the immutable compiled p
- [Brain execution for swarm populations](https://hikari.dev/docs/guides/swarm-ai.md): A defineSwarm population can run the same Brain definitions as actors. Each member owns execution state; one population owner supplies the immutable program, sensing, target positions, scheduling and 
- [Localization](https://hikari.dev/docs/guides/localization.md): Author translations as UTF-8 JSON; Shinra compiles them before Zig compilation and during asset cooking. Hikari never parses localization JSON or message patterns at runtime. The editor and games use 
- [Game cursors](https://hikari.dev/docs/guides/ui-cursors.md): Games own cursor artwork and gameplay meaning. UI controls provide automatic cursor roles. Games choose native OS rendering or software rendering through the game UI on macOS and Windows. Cursor appea
- [Choosing component storage](https://hikari.dev/docs/guides/component-storage.md): Use attachable components for ordinary gameplay, embedded components for permanent actor state, and swarms for large populations that can operate without full actor services.
- [Build and packaging](https://hikari.dev/docs/guides/build-and-packaging.md): Kaji is the only product build tool. Run it from the repository root:
- [Project file](https://hikari.dev/docs/guides/project-file.md): Hands-on walkthrough: Tutorials — First project.
- [Plugins](https://hikari.dev/docs/guides/plugins.md): Hikari plugins are source-composed packages. Enabling a plugin adds Zig modules and native middleware declarations to the project game module build; it does not install a runtime Zig plugin loader.
- [Hikari Plugin API](https://hikari.dev/docs/guides/plugin-api.md): Product front door for author-facing plugin contracts. Composition (manifests, roles, packaging) lives in Plugins.
- [Data-driven content, JSON, and paths](https://hikari.dev/docs/guides/data-and-modding.md): Game modules get two complementary tools:
- [Scripting with Kawa](https://hikari.dev/docs/guides/scripting-kawa.md): Editor highlighting for .kawa: tools/vscode-extensions/kawa (VS Code / Cursor), tools/nvim-plugins/kawa (Neovim / Vim).
- [Shader authoring](https://hikari.dev/docs/guides/shaders.md): Akari (src/akari/) owns the shader product path end-to-end: shader package sources under shaders/akari/packages/*.akari, shared modules under shaders/akari/modules/*.akari, transpile → MSL/HLSL (bindi
- [Choosing and scaling shadows](https://hikari.dev/docs/guides/shadows.md): Hikari has two geometry-shadow backends: virtual shadow maps (VSM) and ray tracing (RT). Hybrid combines them. Choose the backend for the target hardware and lighting workload, then tune its quality i
- [Time of day](https://hikari.dev/docs/guides/time-of-day.md): Hikari treats a dynamic sky as one environment source, not as a sequence of skybox swaps. AtmosphereSettings drives the visible clear sky, diffuse environment lighting, specular environment fallback, 
- [User interface](https://hikari.dev/docs/guides/user-interface.md): Immediate-mode game UI. Describe layout during update; results return immediately; geometry draws as the final pass of the frame.
- [UI layout](https://hikari.dev/docs/guides/ui-layout.md): Coordinates, responsive lengths, stacks, alignment, and scrolling for immediate-mode UI.
- [UI widgets](https://hikari.dev/docs/guides/ui-widgets.md): Controls, focus navigation, modals, and stable IDs for immediate-mode UI.
- [Migration from Unity / Unreal](https://hikari.dev/docs/guides/migration.md): Concept map for teams coming from Unity or Unreal Engine. Canonical behaviour lives in the linked docs; this page only translates vocabulary and mental models.

## Systems

- [Systems](https://hikari.dev/docs/systems.md): Technical references for engine contributors and game programmers who need subsystem behavior, ownership, or performance details. For scene and asset editing without code, start with Working in the ed
- [Architecture](https://hikari.dev/docs/systems/architecture.md): This repository is a polyglot desktop game-engine workspace. The game owns its project configuration, entities, scene data, source assets, and optional global subsystem. The engine owns runtime orches
- [Application lifecycle](https://hikari.dev/docs/systems/lifecycle.md): The native macOS (src/hikari/src/native_frontends/macOS/main.mm) and Windows (src/hikari/src/native_frontends/Windows/main.cpp) frontends create the process and receive OS events. They only call the o
- [Frontends and drivers](https://hikari.dev/docs/systems/frontends-and-drivers.md): The engine uses native desktop process frontends with a small opaque C ABI:
- [Platforms and support](https://hikari.dev/docs/systems/platforms.md): macOS products ship with LSMinimumSystemVersion 26.0 (Kaji packaging default). Akari compiles MSL with -std=metal4.0 and -mmacosx-version-min=26.0. Device creation requires MTLGPUFamilyMetal4 and argu
- [Session services and cross-scene state](https://hikari.dev/docs/systems/session-services.md): Hands-on walkthrough: Tutorials — First session services.
- [Scenes and gameplay](https://hikari.dev/docs/systems/scenes-and-gameplay.md): Hands-on walkthrough: Tutorials — First entity.
- [Actor communication (hi.actors)](https://hikari.dev/docs/systems/entity-messaging.md): Hands-on walkthrough: Tutorials — First messages.
- [Game-facing refs](https://hikari.dev/docs/systems/refs.md): Game-facing identity handles. The only way game code (Zig / Kawa) references things.
- [Save / replication wire version](https://hikari.dev/docs/systems/replication-wire-version.md): This axis is independent of:
- [Coordinate space and camera conventions](https://hikari.dev/docs/systems/coordinate-space.md): Engine standard (unreleased; no +Z-forward or non-reverse-Z path):
- [Rendering](https://hikari.dev/docs/systems/rendering.md): Every pipeline builds asynchronously in the native layer, in parallel, and binding waits for an unfinished build; see Pipeline compilation. Scene material pipelines are adopted only once their build i
- [Renderer architecture map](https://hikari.dev/docs/systems/renderer-architecture.md): Map of how Hikari owns rendering: layers, RHI vocabulary, render graph, passes, and sync points. Behavior details and pass gates live in Rendering; this page is the structural overview.
- [Frame governor](https://hikari.dev/docs/systems/frame-governor.md): The one closed loop between measured GPU cost and rendered quality. Everything that trades image quality for frame time goes through it. A per-subsystem budget cannot answer "does this frame fit", bec
- [Pipeline compilation](https://hikari.dev/docs/systems/pipeline-compilation.md): A shader artifact is not GPU code. A metallib holds AIR and a D3D12 shader holds DXIL; the driver translates either into the GPU's instruction set when a pipeline is built from it. That translation is
- [Skeletal animation](https://hikari.dev/docs/systems/animation.md): Reference for skinned characters: how skeletons and clips are cooked, how animation graphs evaluate, and what game code can drive and read back. For a step-by-step first character, start with Tutorial
- [GPU particles](https://hikari.dev/docs/systems/particles.md): Hikari particles are GPU-resident effects with CPU orchestration. The CPU advances one fixed-step clock per system and publishes compact emitter commands; it never stores, updates, compacts, or reads 
- [Visual Zones](https://hikari.dev/docs/systems/visual-zones.md): Spatial and global ownership of the look stack: exposure, bloom, fog, tonemap, color grading, and film grain. Project RenderLook is the baseline; zones blend overrides at the primary camera.
- [Volumetric media](https://hikari.dev/docs/systems/volumetric-fog.md): Shared froxel participating-media system: global height fog and bounded smoke volumes feed the same inject → integrate → composite path, with clustered lights, soft geometry shadows, shafts, and emiss
- [Input](https://hikari.dev/docs/systems/input.md): Hands-on walkthrough: Tutorials — First input action.
- [Audio](https://hikari.dev/docs/systems/audio.md): Software mixer + platform device I/O, selected like every other driver. Game code admits requests and posts commands; a dedicated worker owns decode and buffers; the device callback owns playback stat
- [Physics](https://hikari.dev/docs/systems/physics.md): Hands-on walkthroughs: Tutorials — First physics, First character controller.
- [Motion Kit](https://hikari.dev/docs/systems/motion-kit.md): Hands-on walkthrough: Tutorials — First motion.
- [Temporal Kit](https://hikari.dev/docs/systems/temporal-kit.md): Shared time utilities for gameplay, session services, and host clocks. Implementation lives under src/hikari/sdk/src/temporal/. Exports: hi.temporal plus aliases hi.Timer / hi.Interval / hi.Cooldown /
- [UI documents](https://hikari.dev/docs/systems/ui-documents.md): A UI document is an in-game UI screen authored as data: a .ui.json asset that Shinra cooks to .shinui and the runtime interprets every frame through the same immediate-mode context game code draws wit
- [Assets and Shinra](https://hikari.dev/docs/systems/assets-and-shinra.md): Hands-on walkthroughs: First mesh and material, Assets in Play.
- [Prefabs](https://hikari.dev/docs/systems/prefabs.md): A prefab is a reusable actor subtree asset. A scene references an instance and records what differs from the template; the engine expands it at load (prefab/hydrate.zig). Expanded actors exist in memo
- [Asset residency](https://hikari.dev/docs/systems/asset-residency.md): How shared assets stay in memory, who holds them, and what happens at free-at-zero.
- [Asset formats (Shinra pipeline)](https://hikari.dev/docs/systems/asset-formats.md): The Shinra tool (src/shinra) produces binary engine assets and validates them before packaging. Every authored JSON document (materials, scenes, particles, configs, …) has a rendered JSON Schema under
- [Document schemas](https://hikari.dev/docs/systems/document-schemas.md): Every JSON file the engine, editor, Shinra or Kaji read is a document kind: a file with a kind tag (com.hikari.material), an integer version, and a shape described by a JSON Schema (draft 2020-12) ren
- [UI and editor](https://hikari.dev/docs/systems/ui-and-editor.md): Scene opening in Edit mode presents progressively, including replacement loads: geometry uses the pink error material while native material pipelines compile, then adopts the finished pipelines betwee
- [Editor asset hot reload](https://hikari.dev/docs/systems/editor-asset-hot-reload.md): The editor implements live visual asset swapping through a thread-safe, daemon-to-edit event queue and a render-thread-paused re-instantiation path. This page describes the current flow and the invari
- [Editor Project Selector](https://hikari.dev/docs/systems/editor-project-selector.md): Launching hikari-editor without --project boots a full-screen project selector: the engine brand mark, an Open Project… action, and Exit.

## Reference

- [Reference](https://hikari.dev/docs/reference.md): Reference
- [Akari GPU ABI](https://hikari.dev/docs/reference/akari-abi.md): Self-contained layout rules. Akari never links engine code; hosts must match these offsets on the CPU.
- [Akari language reference](https://hikari.dev/docs/reference/akari-language.md): Akari is the engine’s pure shader language: one .akari source emits Metal (MSL), D3D12 (HLSL) and Vulkan (HLSL in its Vulkan dialect, compiled to SPIR-V), then platform compilers produce bytecode. Pro
- [Kawa language reference](https://hikari.dev/docs/reference/kawa-language.md): Kawa is the C scripting runtime used by the engine's current scripting adapter. This page is the language surface: syntax, types, and the stdlib binds the compiler/VM actually expose. Engine attach (e