# Engine documentation 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. ## How this tree is organized | Folder | Audience | Contents | |--------|----------|----------| | [tutorials/](/docs/tutorials.md) | New game authors | Short onboarding paths | | [guides/](/docs/guides.md) | Artists, game developers, and engine developers | How to build, configure, author, extend | | [systems/](/docs/systems.md) | Engine / gameplay systems work | How subsystems behave and compose | | [reference/](/docs/reference.md) | Language authors | Akari and Kawa language references | | reports/ | Engine developers | Measured benchmark records with reproduction commands | Paths in these pages are relative to the repository root unless noted. --- ## Start with your role | You want to… | Start here | Continue with | |---|---|---| | Build levels, import art, tune a scene, or design UI without code | [Working in the editor](/docs/guides/editor-workflow.md) | [UI documents](/docs/tutorials/first-ui-document.md), [Localization](/docs/guides/localization.md#localization-window), [Time of day](/docs/guides/time-of-day.md#scene-authoring-and-editor-preview) | | Write gameplay or extend a game | [First project](/docs/tutorials/first-project.md), then [First entity](/docs/tutorials/first-entity.md) | [Gameplay API](/docs/guides/gameplay-api.md), [Tutorials](/docs/tutorials.md), [Build and packaging](/docs/guides/build-and-packaging.md) | | Change the engine, editor, or build tools | [Architecture](/docs/systems/architecture.md), then [Development](/docs/guides/development.md) | [Lifecycle](/docs/systems/lifecycle.md), [Systems](/docs/systems.md), and the relevant subsystem reference | Coming from another engine? Use [Migration from Unity / Unreal](/docs/guides/migration.md) for terminology, and [Coordinate space](/docs/systems/coordinate-space.md) for axes, cameras, and units. Code samples use the current Hikari SDK. A complete file names its location; shorter fragments belong inside the callback or function described beside them. Commands run from the engine repository root unless a page says otherwise. `hikari-games` is a sibling repository; example paths name content from that separate checkout. --- ## Guides | Guide | Covers | |-------|--------| | [Working in the editor](/docs/guides/editor-workflow.md) | Open, place, edit, test, and save without code | | [Development](/docs/guides/development.md) | Change seams, validation, `hikari_std` | | [Gameplay AI tasks](/docs/guides/ai-tasks.md) | Typed actions shared by Zig and Brain assets, safe completion and door encounter | | [Game AI](/docs/guides/game-ai.md) | First playable guard, game-contributed Noise Probe, and state/task kernel | | [Brain assets](/docs/guides/brain-assets.md) | Shared AI programs, editor authoring, parameters, and decision history | | [Swarm AI](/docs/guides/swarm-ai.md) | Compact population Brain execution, budgeted sensing and moving crowd example | | [Gameplay API](/docs/guides/gameplay-api.md) | Actors, components, callbacks, typed fields | | [Concurrency](/docs/guides/concurrency.md) | OS threads, worker jobs, events, and suspendable gameplay routines | | [Component lifecycle](/docs/guides/component-lifecycle.md) | Initialization, updates, activation, and cleanup | | [Localization](/docs/guides/localization.md) | Translation editor, catalogs, and game text | | [Component storage](/docs/guides/component-storage.md) | Choose attachable, embedded, or swarm, with examples | | [Build and packaging](/docs/guides/build-and-packaging.md) | Kaji flags, products, packages | | [Project file](/docs/guides/project-file.md) | `hikari.project.json`, `configs/`, version axes | | [Plugins](/docs/guides/plugins.md) | Source-composed packages, manifests, packaging | | [Plugin API](/docs/guides/plugin-api.md) | Author-facing editor/render/gameplay plugin contracts | | [Data, JSON, and modding](/docs/guides/data-and-modding.md) | `ContentRef`, path roots, loose `resources/` | | [Scripting with Kawa](/docs/guides/scripting-kawa.md) | Engine integration for scripts | | [Actor communication](/docs/systems/entity-messaging.md) | `hi.actors` / `Actors.*` — find, messages, component fields | | [Shader authoring](/docs/guides/shaders.md) | Packages, layouts, manifests, product pipeline | | [Choosing and scaling shadows](/docs/guides/shadows.md) | VSM, Hybrid and RT decisions, quality controls and performance | | [Time of day](/docs/guides/time-of-day.md) | Astronomical clock, atmosphere, sun/moon lights | | [User interface](/docs/guides/user-interface.md) | Game UI hub (lifecycle, themes, ownership) | | [UI layout](/docs/guides/ui-layout.md) · [UI widgets](/docs/guides/ui-widgets.md) | Coordinates/stacks · controls/focus/modals | | [Game cursors](/docs/guides/ui-cursors.md) | Custom native sprites, UI hover roles, and game overrides | | [Migration](/docs/guides/migration.md) | Unity / Unreal → Hikari concepts | --- ## Systems (engine behaviour) ### Runtime and session - [Architecture](/docs/systems/architecture.md) - [Lifecycle](/docs/systems/lifecycle.md) - [Frontends and drivers](/docs/systems/frontends-and-drivers.md) - [Platforms](/docs/systems/platforms.md) - [Session services](/docs/systems/session-services.md) - [Scenes and gameplay](/docs/systems/scenes-and-gameplay.md) — entities, [active / enable trio](/docs/systems/scenes-and-gameplay.md#active--enable-trio) - [Actor communication](/docs/systems/entity-messaging.md) — `hi.actors` / `Actors.*`, messages, name-keyed fields - [Refs](/docs/systems/refs.md) — `AssetRef` / `ContentRef` / `SceneRef` / `PrefabRef` / `ActorRef` - [Replication wire version](/docs/systems/replication-wire-version.md) — current hook and codec limits ### Presentation and simulation - [Coordinate space](/docs/systems/coordinate-space.md) — RH Y-up −Z-forward, reverse-Z, euler, view-right - [Rendering](/docs/systems/rendering.md) — pipeline, G-buffer, composability contracts - [Renderer architecture](/docs/systems/renderer-architecture.md) — layers, RHI, graph, sync - [Frame governor](/docs/systems/frame-governor.md) — resolution / rays / indirect-resolution levers - [Pipeline compilation](/docs/systems/pipeline-compilation.md) — parallel asynchronous builds, deferred features, background warm-up, persistent caches - [Skeletal animation](/docs/systems/animation.md) — skeletons, clips, graphs, layers, events, foot IK, root motion, joint sockets - [GPU particles](/docs/systems/particles.md) — authoring, specialized SPT2 cook, simulation, indirect rendering - [UI documents](/docs/systems/ui-documents.md) — `.ui.json` screens interpreted through the immediate UI: slots, events, animation, the designer window - [Visual Zones](/docs/systems/visual-zones.md) — spatial / global look blending - [Volumetric media](/docs/systems/volumetric-fog.md) — global fog and bounded smoke, lights, shadows - [Input](/docs/systems/input.md) - [Audio](/docs/systems/audio.md) - [Physics](/docs/systems/physics.md) - [Motion Kit](/docs/systems/motion-kit.md) · [Temporal Kit](/docs/systems/temporal-kit.md) ### Assets - [Assets and Shinra](/docs/systems/assets-and-shinra.md) — pipeline, URIs, soft refs - [Prefabs](/docs/systems/prefabs.md) — expand/diff/variants, editor plane, runtime spawn - [Asset residency](/docs/systems/asset-residency.md) — refcounts, budgets, scene replace - [Asset formats](/docs/systems/asset-formats.md) - [Document schemas](/docs/systems/document-schemas.md) — JSON Schema for every authored document kind; read before writing JSON ### Editor host - [UI and editor](/docs/systems/ui-and-editor.md) — chrome, contributions, Play/Edit, profiler - [Editor asset hot reload](/docs/systems/editor-asset-hot-reload.md) - [Editor project selector](/docs/systems/editor-project-selector.md) --- ## Reference - [Akari language](/docs/reference/akari-language.md) — `.akari` language ([EBNF](https://github.com/Flying-Rat/hikari/blob/develop/src/akari/syntax.ebnf)) - [Akari GPU ABI](/docs/reference/akari-abi.md) — buffer layout, alignment, and CPU/GPU packing rules - [Kawa language and embedding](/docs/reference/kawa-language.md) --- ## Reports Point-in-time benchmark records. Each names its hardware and toolchain and includes the command that reproduces it. - [Shared AI perception benchmark](/docs/reports/ai-perception-benchmark.md) - [Swarm Brain benchmark](/docs/reports/ai-population-benchmark.md) - [Routine scheduler benchmark](/docs/reports/routines-benchmark.md) --- ## Conventions | Surface | Location | |---------|----------| | Game-facing Zig API | `src/hikari/sdk/src/hikari_game.zig` | | Engine/host API barrel | `src/hikari/src/hikari_api.zig` | | Thin SDK pack tree | `src/hikari/sdk/` | | Product `std` | `const std = @import("hikari_std")` — see [Development](/docs/guides/development.md#product-zig-std-hikari_std) | Docs describe **implemented** behaviour. A directory or future RHI type is not a shipping feature.