Syncromesh — SyncroMesh Documentation

Syncromesh is a scriptable 2D game runtime built on the Helix/Koya engine stack. It combines Vulkan rendering, Box2D physics, SDL3 windowing, and QuickJS scripting into a single executable for building 2D games and interactive simulations on Linux.

Behaviour is defined in JavaScript (ES modules). The runtime provides sprite rendering, tile maps, a physics simulation, camera control, and an optional Koya UI overlay — all composited on the GPU.

Async API model #

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

Use await for entity, simulation, camera, window, and asset operations.
Helix/Random and Helix/Geometry helpers are synchronous and do not require await.
Event handlers (Helix/Event, mouse/keyboard callbacks, animation-end callbacks) are invoked asynchronously by the runtime.
API reference pages describe resolved return values; operationally these functions return Promise<...>.

Architecture at a glance #

Renderer: Vulkan renderer with sprite/tile pipelines, renderer-local GPU particle pools, texture pools, and optional Koya UI overlay.
Simulation: Box2D physics world, entity pool (up to 10k slots), camera, and per-entity update handlers.
Services: logging, assets (virtual FS), and scripting bridge (inherited from Helix).
Scripting: modules expose runtime capabilities to JS (Syncromesh/* for game-specific, Helix/* for shared engine).
System: SDL3 compositor with Vulkan windows and input routing.

Module map #

Syncromesh exposes two families of JS modules:

Namespace	Modules	Docs
Syncromesh/*	Entity, Simulation, Camera, Assets, Audio, Data, Navigation, Network, Window	This documentation
Helix/*	Event, Log, Geometry, Random, Renderable, UserInterface	Shared modules; renderable extensions are documented under Text Colour Areas and GPU Particles

CLI #

Syncromesh is a command-line executable with mount-based asset loading:

Flag	Description
`-m PATH`	Add a mount source (repeatable). Later entries take precedence on collision.
`-i FILE`	Bootstrap script file (default: `index.js`). Resolved under `/rom`.
`-n PATH`	Directory to search for native modules (`Module/...`) before the executable directory.
`--default-mounts`	Opt into legacy platform, user configuration, and `./assets` mounts.
`--verbose CHANNELS`	Enable debug channels. Use `all` or comma-separated values (e.g. `ui,layout,vulkan,mouse-events`).

Engine lifecycle #

On startup the engine self-mounts an appended application archive when present, applies explicit mounts, starts the script thread, and fires a ready event.
The main loop runs solve (physics), update (entity handlers), and render (sprites + tiles + UI) each frame.
Setting the run state to RELOAD tears down the script context and re-bootstraps without restarting the process.
Setting the run state to QUIT performs cleanup and exits.

Native modules #

Import native shared libraries as Module/name in JS. The runtime loads libhx-name.so from the -n path (if set) or the executable directory. Each native module must export an helix_plugin_integrate(ctx, name, host, instance) function and can register hooks (render, render_begin, solve, update, cleanup).

Shared Types →