Scripting (Rhai) API

JETCARP runs scripts written in Rhai, a small scripting language made for Rust programs. A script makes worlds, runs them until something happens, saves pictures and scenes, starts searches and runs large parallel rule sweeps. The simulation itself runs in JETCARP’s own code, so a script stays fast even when it loops over thousands of rules; the script only decides what to do next. This page says how to run a script and then lists every function. For a worked example from start to finish, see the tutorial Scripting a rule sweep.

An example

// Hexagonal Life from a soup: a picture and a scene every `every` generations.
// Run: jetcarp script hex-life.rhai --set gens=600 --set every=200
let gens = params.gens ?? 300;
let every = params.every ?? 100;

let w = world(#{ tiling: "hex", size: [120, 80], boundary: "wrap", rng_seed: 7 });
w.add_ca("B2/S34", #{ seed: "random:0.35", palette: "Glacier" });

out_dir("hex-life");
while w.generation() < gens {
    w.step(every);
    let g = w.generation();
    w.save_png(`hex-${g}.png`, #{ size: [960, 640] });
    print(`generation ${g}: ${w.population()} live, hash ${w.hash()}`);
}
w.save_scene("hex-life.json");

// The same list of palettes the command line prints, through the API.
let names = jetcarp("reference.palettes").palettes.map(|p| p.name);
print(`${names.len()} palettes, the first ${names[0]}`);

$ jetcarp script hex-life.rhai --set gens=600 --set every=200
generation 200: 197 live, hash 9fd22c3b518fe0a5
generation 400: 209 live, hash c56126e522f752f6
generation 600: 197 live, hash f711a1e991a158b7
30 palettes, the first Ember
output: /home/ada/Pictures/JETCARP/2026-11-10_18-36-13_hex-life
time:   0.12s

The folder holds the three pictures, the scene (which jetcarp verify replays to the same hash) and run.json, the record of the run described below.

Running a script

From the command line, jetcarp script FILE runs a script. What it prints with print, log and debug goes to standard output as it happens; progress bars and, at the end, the output folders and the time taken go to standard error.

Pressing Ctrl-C once stops the script after the runs in flight; a sweep writes its manifest first, and JETCARP prints the command that carries it on. Pressing it again quits at once. A sweep folder can always be resumed: running the same sweep with folder: set to it skips the runs already done.

In the app, Tools → Scripts and sweeps… opens a window with three tabs: the Sweep builder, a form that builds a rule sweep without writing code; the Script editor, with New, Open…, Save, Save as… and an Examples menu of the scripts that ship with JETCARP; and the Function reference, the reference below with a search box. Ctrl+Enter runs the script. It runs in the background while the app keeps simulating, and show(w) puts a copy of a world in the main view.

From an AI assistant, the MCP tool run_script runs a script with a time limit (60 seconds by default) and a limit on world size, and reads files only from the output folder (see MCP tools).

Parameters: --set

Each --set key=value puts one entry in the map params. Numbers and true/false arrive as numbers and booleans; anything else arrives as text. A key that was not given reads as (), Rhai’s “nothing”, so params.gens ?? 300 gives a default:

$ jetcarp script sweep.rhai --set from=0 --set to=255 --set label=wolfram

Where scripts write: --out

Every file a script writes goes inside its output root: the folder given with --out, else JETCARP_OUT, else <Pictures>/JETCARP (see Folders). out_dir("label") makes a new folder in it named with the time and the label, such as 2026-11-10_18-36-13_hex-life, and from then on relative paths are relative to that folder; before the first out_dir, they are relative to the root itself. A path outside the root is refused:

error: line 3, column 3: scripts may only write inside /home/ada/Pictures/JETCARP (got /home/ada/elsewhere.png); use out_dir("label") for a new output folder

From the command line and the app a script may read files anywhere; through MCP, only from the output folder. A relative path to read is looked for next to the script first, then in the current output folder. Each output folder a script makes gets a run.json that records the script’s text, its parameters, the screen size, the thread count, the JETCARP version, the operating system, and when it started and finished (not the computer’s name, so the folder can be shared as it is). Sweeps write their own run.json and manifests.

Calling any operation: jetcarp(op, #{…})

Everything JETCARP can do has a named operation, shared by the command line, the app, the MCP tools and scripts (jetcarp api list lists them, and jetcarp api schema OP shows one’s input and output). A script calls one with jetcarp(op) or jetcarp(op, #{ … }), passing the input as a map, and gets the output back as a map:

let top = jetcarp("library.query", #{ class: "spaceship", limit: 5 }).patterns;
let entries = jetcarp("quickstart.list").entries;
jetcarp("world.new", #{ tiling: "hex", width: 20, height: 20, cas: ["Life"] });
let r = jetcarp("world.step", #{ generations: 100 });

The script’s rules on files apply, and the catalogue is the run’s own. The world operations (world.new, world.step, …) act on one private world kept for the whole run, not on a world w made with world(). An operation’s error becomes a script error with the operation’s message.

Reproducibility

A world made in a script is an ordinary JETCARP world: the same tiling, rules, seeds and random state (rng_seed) give the same states and the same hash, at any thread count. w.save_scene(path) writes a scene that jetcarp verify replays, and every PNG a script saves carries its scene and hash, as jetcarp run --png does (see Reproducibility).

The scripting API is not yet declared stable; that is planned for JETCARP 1.0, together with the scene format, the command line and the MCP tools. Until then a release may still change it.

Generated by docs/tools/gen-scripting.py from the program's own function reference (crates/jetcarp-script/src/help.md, which jetcarp script --functions prints) and from the functions the scripting engine registers (122 functions, 152 signatures). The generator refuses to write this part if the two disagree. Edit help.md, not this page.

Function reference

The language

Scripts are written in Rhai (https://rhai.rs): let x = 1;, for n in 0..10 { ... }, if a > b { ... } else { ... }, fn name(a, b) { ... }, lists [1, 2], maps #{ key: 1 }, closures |w, n| w.population() > 0, strings with +, and `text ${x}` interpolation. The simulation runs in Rust; the script only orchestrates. Statements end with ;.

Worlds

Running

Reading

Saving

Sweeps

sweep(#{ ... }) runs one world per rule in parallel on all cores and writes one PNG per run plus manifest.csv, manifest.json, and run.json into a new output folder. Returns a summary map (folder, runs, images, kept, errors, seconds, cancelled).

Reading a sweep back: manifest(folder) returns the rows as a list of maps (one per run, sorted by index; also while a sweep is still running), e.g. for r in manifest(s.folder) { if r.row_hint == "nested" { ... } }. manifest.json itself is #{ columns: [...], rows: [...] }. Missing values (JSON null) are () in Rhai: test r.period == (); Rhai has no null. Then library().promote_run(s.folder, r.rule) puts a run in the Quick Start.

File names are zero-padded to the series width: HexW3-08229.png, W030.png, HexT3-sum-0588.png; rule lists use <index>_<rule>.png. Manifest columns: index, n, rule, file, kept, generations, stopped, done, done_reason, hash, population, density, frac_0.. (Lenia: mass, mean_value), period, row_period, row_shift, periodic_from, distinct_rows, row_class, row_entropy, row_hint, png_bytes, error (and skipped), then any columns from keep.

Pattern library

The library is the SQLite catalog: JETCARP_LIBRARY if set (a folder, or a .sqlite file), else <data>/library.sqlite (see The pattern library and Folders). Records are verified exactly before they are stored. A pattern’s id does not depend on the rule: the same evolution found in several rules is one pattern, with rules (every rule it was verified in) and, for B/S and Generations rules, range (min_rule, max_rule, bitmasks, states_min/states_max: every rule it runs identically in).

Glider search and movers

Large sandpiles

Media and website export

Other

Index of functions

Every function the engine registers, with the types of its arguments in each form (int, float, string, bool, map (#{ … }), array ([ … ]), any). Methods of a world are called as w.name(…) and methods of a catalogue handle as lib.name(…); Rhai also accepts name(w, …). Worlds and catalogue handles can be printed with print(w).