Rhai Scripting API Reference (v0.3.0)

This reference documents the complete Rhai scripting API for Conchordal’s Life Engine. Scenarios are scripts that define species, spawn agent groups, control the timeline, and tune global parameters.

Registered Types

Preset Species

Global constants available in every script:

let voice = derive(harmonic).amp(0.4).brightness(0.7);

Species Definition

derive(parent) -> SpeciesHandle

Clone a preset or existing species for modification.

let pluck = derive(harmonic).amp(0.3).adsr(0.01, 0.1, 0.3, 0.2);

All species methods are chainable and return SpeciesHandle.

Body and Amplitude

let pad = derive(harmonic).amp(0.5).brightness(0.6).spread(0.02).voices(3);
let bell = derive(modal).modes(stiff_string_modes(0.02).count(8));

Pitch Control

let glider = derive(sine).pitch_mode("free").pitch_core("hill_climb")
    .pitch_apply("glide").pitch_glide(0.1);

Hill-Climb Tuning

Peak Sampler Tuning

Crowding

let social = derive(harmonic)
    .crowding(0.8)
    .crowding_target(true, true)
    .leave_self_out(true).leave_self_out_mode("approx");

Brain (Articulation)

Phonation

Phonation is configured in three tiers of increasing detail.

Tier 1 – Presets:

Tier 2 – Explicit when/duration:

Tier 3 – Expert tuning:

let pulsed = derive(harmonic).repeat().pulse(3.0).sync(0.6).social(0.3);
let fielded = derive(sine).field().field_window(0.2, 0.8);

Lifecycle

let pluck = derive(harmonic).metabolism(0.5).adsr(0.01, 0.1, 0.3, 0.2);

Rhythm

Respawn

Telemetry

Sustain Drive

Mode Patterns

Mode patterns define frequency relationships for modal synthesis bodies.

Constructors

All constructors return ModePattern.

Modifiers

All modifiers are chainable and return ModePattern.

let bell_modes = stiff_string_modes(0.03).count(12).jitter(5.0);
let adaptive = landscape_density_modes().count(6).range(1.0, 8.0).gamma(2.0);

Spawn Strategies

Strategies define how frequencies are allocated when spawning a group.

Constructors

All constructors return SpawnStrategy.

Modifiers

reject_targets wraps any strategy: targets_st is an array of semitone offsets from anchor_hz, exclusion_st is the exclusion zone width in semitones, and max_tries is the retry limit.

let strat = consonance(220.0).range(1.0, 3.0).min_dist(0.9);
create(harmonic, 6).place(strat);

let density = consonance_density_pmf(100.0, 800.0).min_dist(1.0);
create(sine, 8).place(density);

// Avoid octaves and fifths of 220 Hz
let filtered = random_log(100.0, 1000.0)
    .reject_targets(220.0, [0.0, 12.0, 7.0, 19.0], 0.5, 50);

Group Creation and Operations

create(species, count) -> GroupHandle

Create a draft group of count agents. The group spawns on the next flush() or wait() call.

let g = create(sine, 4).amp(0.3);
flush();  // spawns the group

place(strategy) -> GroupHandle

Set spawn strategy (draft only).

create(harmonic, 6).place(consonance(220.0).range(1.0, 4.0));

release(group)

Release a live group. Agents enter their release phase and fade out.

let g = create(sine, 1).freq(440.0);
flush();
wait(2.0);
release(g);

Draft vs. Live Methods

Group methods work in two contexts:

• Draft (before flush()/wait()): configures the group before spawning.
• Live (after spawning): patches parameters on running agents.

Live-patchable (work in both draft and live):

amp, energy, freq, landscape_weight, neighbor_step_cents, tessitura_gravity, sustain_drive, pitch_smooth, exploration, persistence, anneal_temp, temperature, move_cost, move_cost_exp, improvement_threshold, proposal_interval, window_cents, top_k, sigma_cents, random_candidates, brightness, spread, voices, pitch_glide, leave_self_out, leave_self_out_mode, leave_self_out_harmonics, crowding, crowding_target, global_peaks, ratio_candidates, move_cost_time_scale, pitch_apply_mode, pitch_apply

Draft-only (ignored with a warning if called on a live group):

brain, pitch_mode, mode, pitch_core, sustain, repeat, once, pulse, while_alive, gates, field, sync, social, field_window, field_curve, field_drop, metabolism, adsr, rhythm_coupling, rhythm_coupling_vitality, rhythm_reward, respawn_random, respawn_hereditary, modes, place

let g = create(harmonic, 4)
    .brightness(0.7)          // draft: sets initial value
    .brain("entrain")         // draft-only
    .place(consonance(220.0));
flush();

g.brightness(0.3);            // live: patches running agents
wait(2.0);
release(g);

Timeline and Control Flow

wait(seconds)

Flush pending groups, then advance the timeline cursor.

create(sine, 1).freq(440.0);
wait(2.0);  // spawn + wait 2 seconds

flush()

Commit pending draft groups without advancing time.

create(sine, 1).freq(440.0);
flush();  // spawn immediately at current cursor

seed(value)

Set the random seed for reproducible scenarios.

seed(42);

scene(name, callback)

Named scope with automatic group release when the callback returns.

scene("Intro", || {
    create(sine, 2).freq(220.0);
    flush();
    wait(4.0);
    // all groups auto-released here
});

play(callback [, args…])

Scoped callback execution with automatic cleanup. Accepts 0–3 positional arguments, or an array.

let chord = |root| {
    create(sine, 1).freq(root);
    create(sine, 1).freq(root * 1.25);
    create(sine, 1).freq(root * 1.5);
    flush();
};

play(chord, 220.0);
wait(2.0);
// groups auto-released when play scope ends

parallel(callbacks)

Execute closures on parallel timelines. Each branch starts at the current cursor. The cursor advances to the latest branch end.

parallel([
    || {
        create(sine, 1).freq(220.0);
        wait(1.0);
    },
    || {
        create(sine, 1).freq(330.0);
        wait(3.0);
    },
]);
// cursor is now at +3.0 seconds

Global Parameters

set_harmonicity_mirror_weight(0.0);  // overtone-dominant (major)
wait(4.0);
set_harmonicity_mirror_weight(1.0);  // undertone-dominant (minor)

Complete Example

seed(1);

// Define species
let anchor = derive(sine).amp(0.6).sustain();
let voice = derive(harmonic)
    .amp(0.3)
    .brightness(0.5)
    .pitch_mode("free")
    .pitch_core("hill_climb")
    .pitch_apply("glide").pitch_glide(0.08)
    .crowding(0.5)
    .metabolism(0.4)
    .adsr(0.05, 0.1, 0.7, 0.3)
    .repeat().pulse(2.25).sync(0.5);

scene("Opening", || {
    // Anchor drone
    let root = create(anchor, 1).freq(220.0);
    flush();
    wait(1.0);

    // Consonant voices
    let strat = consonance(220.0).range(1.0, 3.0).min_dist(0.9);
    create(voice, 6).place(strat);
    wait(4.0);

    // Shift to undertone mode
    set_harmonicity_mirror_weight(1.0);
    wait(4.0);
});

scene("Development", || {
    let dense = derive(voice).exploration(0.8).anneal_temp(0.5);
    let strat = consonance_density_pmf(100.0, 800.0).min_dist(0.8);
    create(dense, 12).place(strat);
    wait(8.0);
});