v0.7.1 (build 925)
Koya home

Koya/Runtime

How modules load, command-line flags, engine loop and asset mounts.

This page explains how JavaScript modules are loaded and how native plugins integrate with the engine.

Imports #

Shared engine modules use the Helix/ prefix; Koya-specific modules use the Koya/ prefix:

import * as Log from 'Helix/Log';          // shared (helix-base)
import * as UI from 'Helix/UserInterface';   // shared (helix-base)
import * as Compositor from 'Koya/Compositor'; // koya-specific

Native plugins are loaded with the Module/ prefix and map to shared libraries. The engine searches for libhx-<name>.so in: (1) system library paths, (2) the executable's directory, (3) the directory given by -n if set.

import * as Http from 'Module/http';
import * as Process from 'Module/process';

Command-line flags #

  • -m <path> (repeatable): Add an explicit mount source into /rom. These mounts override the automatically discovered application archive.
  • --default-mounts: Opt into the legacy XDG, user configuration, and ./assets mount locations. They are disabled by default.
  • -i <file>: Set the bootstrap JavaScript module (relative to /rom/). Defaults to index.js. The file is executed as an ES module; its default export can be a function you call or perform side effects on import.
  • -n <path>: Directory to search for native modules (Module/...). When you import a Module/<name> module, the engine looks for libhx-<name>.so in system paths, then the executable directory, then this path.
  • -- [args...]: Any arguments after -- are forwarded as a string array to the bootstrap module's default export. For example, koya -m ./app -i app.js -- --port 8080 foo passes ['--port', '8080', 'foo'] to the default function.

Engine loop and hooks #

  • The engine runs a single-threaded JavaScript loop. Some modules expose async APIs that deliver results back on the JS thread.
  • You normally don't need to call any manual drain() functions; use the Promise/event-style APIs provided.

Bootstrap pattern #

Warning

Do not call Engine.quit() in the bootstrap synchronously; quitting there prevents the loop from starting and Promises/events will never resolve.

  • The bootstrap module specified with -i is imported and its default export is invoked with a single argument: an array of strings from the command line (everything after --). The array is empty when no extra arguments are given.
  • Set up your environment (event handlers, timers, async calls) in the bootstrap and let the engine drive resolution.
  • If you need to exit after an async task completes (e.g., in tests), schedule the quit from within the async chain or on a later tick.
import * as Engine from 'Helix/Engine';
export default (args) => {
  console.log('Script args:', args);
  doAsyncWork().then(() => {
    setTimeout(() => Engine.quit(), 0);
  });
};

Input dispatch #

  • Wayland input (pointer/keyboard/touch) is pumped once per frame and dispatched to active windows.
  • Virtual handlers enable hit testing and receive one event object. See /helix-input for recognition and ownership.
  • To accept pointer input, create the window with { acceptPointerEvents: true } or call Compositor.setPointerEvents(win, true).
  • Control the pointer cursor per window with Compositor.setCursor(win, shape), where shape is a common name like 'arrow', 'hand', 'text', etc., or a raw cursor theme name such as 'left_ptr'.

Error handling #

  • Engine API functions throw JavaScript RangeError or TypeError when arguments are invalid or a resource cannot be found. Always validate IDs and paths.
  • Plugin functions typically return Promises for async operations and reject with an object or string explaining the failure.

Assets and paths #

  • Paths starting with /rom/... refer to bundled assets. An archive appended to the running executable is discovered and mounted there automatically.
  • No ambient locations are mounted by default. --default-mounts enables the legacy XDG, user configuration, and ./assets locations.
  • Later mounts override earlier ones: the application archive is the base, followed by optional legacy defaults, explicit -m sources, and bootstrap-time mounts.
  • Filesystem-accessing features operate on the host filesystem and should be restricted to trusted locations.
<- Helix/EngineHelix/Event ->