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/ | New game authors | Short onboarding paths |
| guides/ | Artists, game developers, and engine developers | How to build, configure, author, extend |
| systems/ | Engine / gameplay systems work | How subsystems behave and compose |
| reference/ | 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 | UI documents, Localization, Time of day |
| Write gameplay or extend a game | First project, then First entity | Gameplay API, Tutorials, Build and packaging |
| Change the engine, editor, or build tools | Architecture, then Development | Lifecycle, Systems, and the relevant subsystem reference |
Coming from another engine? Use Migration from Unity / Unreal for terminology, and Coordinate space 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 | Open, place, edit, test, and save without code |
| Development | Change seams, validation, hikari_std |
| Gameplay AI tasks | Typed actions shared by Zig and Brain assets, safe completion and door encounter |
| Game AI | First playable guard, game-contributed Noise Probe, and state/task kernel |
| Brain assets | Shared AI programs, editor authoring, parameters, and decision history |
| Swarm AI | Compact population Brain execution, budgeted sensing and moving crowd example |
| Gameplay API | Actors, components, callbacks, typed fields |
| Concurrency | OS threads, worker jobs, events, and suspendable gameplay routines |
| Component lifecycle | Initialization, updates, activation, and cleanup |
| Localization | Translation editor, catalogs, and game text |
| Component storage | Choose attachable, embedded, or swarm, with examples |
| Build and packaging | Kaji flags, products, packages |
| Project file | hikari.project.json, configs/, version axes |
| Plugins | Source-composed packages, manifests, packaging |
| Plugin API | Author-facing editor/render/gameplay plugin contracts |
| Data, JSON, and modding | ContentRef, path roots, loose resources/ |
| Scripting with Kawa | Engine integration for scripts |
| Actor communication | hi.actors / Actors.* — find, messages, component fields |
| Shader authoring | Packages, layouts, manifests, product pipeline |
| Choosing and scaling shadows | VSM, Hybrid and RT decisions, quality controls and performance |
| Time of day | Astronomical clock, atmosphere, sun/moon lights |
| User interface | Game UI hub (lifecycle, themes, ownership) |
| UI layout · UI widgets | Coordinates/stacks · controls/focus/modals |
| Game cursors | Custom native sprites, UI hover roles, and game overrides |
| Migration | Unity / Unreal → Hikari concepts |
Systems (engine behaviour)
Runtime and session
- Architecture
- Lifecycle
- Frontends and drivers
- Platforms
- Session services
- Scenes and gameplay — entities, active / enable trio
- Actor communication —
hi.actors/Actors.*, messages, name-keyed fields - Refs —
AssetRef/ContentRef/SceneRef/PrefabRef/ActorRef - Replication wire version — current hook and codec limits
Presentation and simulation
- Coordinate space — RH Y-up −Z-forward, reverse-Z, euler, view-right
- Rendering — pipeline, G-buffer, composability contracts
- Renderer architecture — layers, RHI, graph, sync
- Frame governor — resolution / rays / indirect-resolution levers
- Pipeline compilation — parallel asynchronous builds, deferred features, background warm-up, persistent caches
- Skeletal animation — skeletons, clips, graphs, layers, events, foot IK, root motion, joint sockets
- GPU particles — authoring, specialized SPT2 cook, simulation, indirect rendering
- UI documents —
.ui.jsonscreens interpreted through the immediate UI: slots, events, animation, the designer window - Visual Zones — spatial / global look blending
- Volumetric media — global fog and bounded smoke, lights, shadows
- Input
- Audio
- Physics
- Motion Kit · Temporal Kit
Assets
- Assets and Shinra — pipeline, URIs, soft refs
- Prefabs — expand/diff/variants, editor plane, runtime spawn
- Asset residency — refcounts, budgets, scene replace
- Asset formats
- Document schemas — JSON Schema for every authored document kind; read before writing JSON
Editor host
- UI and editor — chrome, contributions, Play/Edit, profiler
- Editor asset hot reload
- Editor project selector
Reference
- Akari language —
.akarilanguage (EBNF) - Akari GPU ABI — buffer layout, alignment, and CPU/GPU packing rules
- Kawa language and embedding
Reports
Point-in-time benchmark records. Each names its hardware and toolchain and includes the command that reproduces it.
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 describe implemented behaviour. A directory or future RHI type is not a shipping feature.