Balaur

A 2D & 3D node-based game engine, fully deterministic, with scripts that reload in milliseconds.

Written in Rust. Fast to run, fast to iterate, easy to use — and one file to ship.

Read the docs · Features · Principles · Download · Roadmap

Nodes and scenes A game is a tree of named nodes with scripts attached. Scenes are plain TOML.	Scripting in Rune Rust's syntax, no build step, async/await, and a debugger in the editor.	Instant hot reload Save a script while the game runs: the new code is live in milliseconds, state intact.
Determinism, always on Same inputs, same bits on every platform. Record a session and replay it, network replies included.	2D and 3D physics Rapier under both, stepped on a fixed 60 Hz tick, declared in scenes or driven from scripts.	Rendering 3D and 2D on wgpu: windowed, offscreen for screenshots and CI, or fully headless.
Animation and skeletons Clips and tweens, 2D bones with skinned polygons, 3D rigs from glTF, two-bone IK.	The editor Itself a Balaur project: scene tree, inspector, gizmos, timeline, rig tools, play-in-editor.	Networking HTTP and websockets with compression, delivered into the simulation once per tick.
Every platform Windows, macOS and Linux today; iOS, Android and the web are cross-compiled in CI on every push.	One file to ship Export fuses bytecode, scenes and assets onto the runtime: one self-contained binary per target, nothing to install.	Built on Rust Safe Rust throughout, and the ecosystem as it is: Rapier, wgpu, egui, rodio, Rune.

Quickstart

cargo run -p balaur_cli -- new my-game
cargo run -p balaur_cli -- run my-game                        # dev mode, hot reload on
cargo run -p balaur_cli --features window -- edit my-game     # open in the editor
cargo run -p balaur_cli -- export my-game --target linux-x64  # one file to ship

To see hot reload, run cargo run -p balaur_cli -- run examples/hello --headless and edit examples/hello/scripts/spinner.rn while it goes: the change is live the moment you save, state intact. Getting started has the rest — run modes, every command, the example projects, benchmarks.

What a game looks like

Scenes are declarative TOML, and plugins extend their vocabulary:

# scenes/main.toml
[[nodes]]
name = "Ball"
position = [0.0, 6.0, 0.0]
script = { source = "scripts/ball.rn", props = { speed = 3.5 } }
body3d = "dynamic"                                # from balaur_physics
collider3d = { kind = "ball", radius = 0.5 }      # from balaur_physics
shape3d = { kind = "ball", radius = 0.5 }         # from balaur_render

Scripts are Rune, attached to a node, with lifecycle methods:

// scripts/ball.rn
pub fn exports() { #{ speed: 2.0 } }              // what the inspector may tune

pub fn init(this) { this.angle = 0.0; }

pub fn update(this, dt) {                         // per frame; fixed_update is per 60 Hz tick
    this.angle += dt * this.speed;
    this.node.set_rotation_euler(0.0, this.angle, 0.0);
}

Documentation

The docs live at balaurengine.org:

• Getting started — build it, the CLI, the examples
• Manual — scenes, scripting, physics, animation, input, networking, the editor, shipping
• Reference — every script module, function, constant and scene component
• Architecture · Principles · Roadmap · Changelog

In this repository:

• ARCHITECTURE.md — every decision and why, hand-written
• docs/DETERMINISM.md — writing a game that reproduces, and the record/replay tools for when it does not
• docs/NAMING.md — what every name means and the rules new ones follow; it governs the other docs
• docs/generated/ — the script API, components, assets, crates and behaviour, written by python3 scripts/gen_docs.py; CI fails on drift
• docs/PLAN-*.md — the plan behind each subsystem

Contributing

See CONTRIBUTING.md. Balaur is MIT licensed.