v0.7.1 (build 925)
Koya home

Koya

High‑level overview of the KOYA engine and how the pieces fit together.

Koya is a Vulkan-powered UI engine for Wayland compositors (Hyprland, Sway, Weston, and others). It is designed for programmable surfaces, animations, and interactions on embedded and desktop Linux.

It uses QuickJS for scripting, so behaviour is defined in code instead of CSS themes. All UI rendering, animation, and overlays are handled in-engine on the GPU.

Koya supports multiple independent surfaces (bar, overlay, background, window), each with its own renderer, while sharing a single scripting context.

Upgrading an existing application? Read the 0.5.0 → 0.6.0 migration guide before replacing the runtime. Mouse/touch input APIs changed in 0.6.0; see the changelog.

Async API model #

Koya's JS API is mostly promise-based. Runtime calls in Helix/*, Koya/*, and Module/* are generally asynchronous and awaited, with synchronous exceptions noted in module docs.

  • Use await for compositor, UI, image, screenshot, assets, and other runtime operations.
  • Helix/Random, Helix/Geometry, and Helix/Profiler helpers are synchronous and do not require await.
  • Event handlers (Helix/Event, virtual input callbacks, animation-end callbacks) are invoked asynchronously by the runtime.
  • API reference pages may describe resolved return values; operationally these functions return Promise<...>.

Architecture at a glance #

  • Renderer: Vulkan renderer with shader/texture pools for efficient batching.
  • Engine: frame clock, animation system, coordinate transforms, renderable primitives, and renderer-local GPU particle pools.
  • Services: logging, assets (virtual FS), and scripting bridge.
  • Scripting: modules expose engine capabilities to JS (Helix/*, Koya/*, and Module/*).
  • System: Wayland client + layer‑shell integration.

See Rendering, FPS & Frame Scheduling for details on render-on-change hashing, frame callbacks, and dynamic FPS.

Production / Embedded notes #

  • Runtime model: one process can host multiple Wayland surfaces while sharing one scripting runtime, which simplifies cross-surface coordination.
  • Asset strategy: package static assets in /rom/...; generate or cache runtime textures in /ram/... (see Koya/Assets and Koya/Image).
  • Power and thermal behaviour: render-on-change plus display-synced presentation helps reduce unnecessary GPU work on mostly static screens.
  • Observability: use Helix/Log for runtime logs and Helix/Profiler for engine timings, scripting work, and queue pressure.
  • Integration boundary: keep UI/render behaviour in Helix/* and Koya/*; connect platform capabilities through Module/* plugins (HTTP, DB, process, IPC, and more).
  • Capability model: OS, host filesystem, and network access are intentionally module-gated. Core UI/render scripts do not require direct host access.
  • Deployment pattern: kiosk and HMI deployments typically run Koya under a service manager for restart policy, boot ordering, and controlled environment variables.

Field notes from production kiosks #

  • OTA-friendly assets: mounted zip packs can target the same virtual namespace, so /rom content can be patched incrementally instead of replacing one monolithic asset bundle.
  • Compositor-backed deployment: a common production stack is systemd + Weston + kiosk desktop/shell, with Koya as the UI application layer.
  • System-level workflows: in controlled appliance environments, Koya can run with elevated privileges so kiosk UX can trigger OS-managed operations (for example, network configuration) through standard Linux services.
  • Migration path: compositor-based deployments and direct KMS/DRM deployments can share most UI logic; teams can ship on compositor-first legacy targets and migrate later when direct scanout paths are ready.
  • Assets-first history: early deployments used the asset virtual filesystem as the only file access path. Host filesystem access was later relaxed through modules to support select desktop workflows.
Warning

The module boundary is the primary risk-control surface. If running as root, keep module/plugin trust and update/signing policy strict.

Ecosystem #

Quickstart (60 seconds) ->