Juni scripting
Kerabit 3.0 scripts games in
Juni: a statically typed
language with Python-like indentation that Kerabit compiles to
WebAssembly in-process and runs in an embedded, fuel-limited
runtime. Type errors show up as file:line:col before
Play; a runaway loop traps instead of hanging a frame. The public Rust
API from 1.0 stays frozen.
Try it
cargo run -p kerabit --example hello_juni
cargo run -p spark
cargo run -p kerabit-juni --bin check_juni -- games/spark/scenes/spark.juni
hello_juni spins a cube.
Spark is the script-first proof game (WASD, goal pad,
hazards) — logic in games/spark/scenes/spark.juni.
check_juni type-checks a script against the host API
without opening a window.
Shape of a script
state:
cube: i32 = 0
t: f32 = 0.0
fn main() -> i32:
cube = entity("cube")
return 0
fn frame(dt: f32) -> i32:
if key_pressed("Escape"):
quit()
t = t + dt
rotate_y(cube, 1.1 * dt)
return 0
main runs once when the script loads (or hot-reloads);
frame runs every frame. Values that must survive between
frames live in the state: block. Entities are opaque
i32 handles from entity("name"); 0
means "no such entity" and every write to it is a no-op.
Attach a script
Put a path in extras.script (or
components.script) on the scene root or an
entity. Paths are relative to the
.kerabit.json file for both load_scene and
apply_scene.
{
"version": 1,
"extras": { "script": "game.juni" },
"entities": [{ "name": "player", "extras": { "script": "player.juni" } }]
}
Entity scripts get their owner from self_entity().
When they run
Each frame: Rust run closure, then every loaded
script, then render. Scripts read a snapshot of the world and queue
writes, which the engine applies after the last script. Type errors
fail load with positioned diagnostics; traps set
ctx.script_error() and pause that script until the file
hot-reloads on save (state resets).
Host API (Frozen for 3.0)
dt()·quit()·reload_scripts()·log(text)key_down(name)/key_pressed(name)·mouse_x()/mouse_y()·mouse_down(btn)/mouse_pressed(btn)entity(name)·self_entity()·exists(e)·enabled(e)·pos_x/y/z(e)·scale_x/y/z(e)·has_tag(e, tag)·tag_count(tag)/tag_at(tag, i)set_pos·translate·rotate_x/y/z·set_scale·set_enabled·add_tag/remove_tag(all take the handle first)despawn(e)·spawn_cube/spawn_cube_ex·spawn_plane(return the new handle) ·spawn_prefab(path, x, y, z)move_planar(e, dx, dz)·register_box(e)(static AABB from entity scale)play(path)/play_at(path, x, y, z)·spawn_particles(x, y, z, count, r, g, b)·set_camera(ex, ey, ez, tx, ty, tz)ui_text(x, y, size, r, g, b, text)/ui_rect(x, y, w, h, r, g, b, a)(normalized coords; ASCII text only)- Helpers written in Juni:
dist_xz·dist_between(a, b)·near(a, b, radius)
Juni builtins such as sqrt, clamp,
lerp, rand, str_len, and
print work as usual; Juno's browser-only canvas / WebGPU
builtins are rejected at load with a hint. The full table with
signatures is the prelude itself:
crates/kerabit-juni/juni/kerabit.juni.
Editor
Script menu → Show panel, Check (types + host API), Reload from disk. Play loads scripts and auto-reloads on file save. Details: Editor guide.
Contract: API.md · Language: Juni docs · Next: Editor guide