Generated from the Utomata lexicon, the same source the engine is built from, so it lists the language exactly as implemented. This is a dictionary rather than a tutorial: the Manual explains the same vocabulary in prose.
The complete formal vocabulary of Utomata, organised by the construct each symbol belongs to. Syntax and usage are covered in the prose guides.
Constructs
Top-level named forms. Each is written as its marker followed by a name you choose — #heat, ~mesh, $speed.
| Construct | Description |
|---|---|
&alias |
reusable expression alias (macro) |
#field |
GPU-computed field |
~formation |
renderable geometry formation |
^viewport |
named camera / scene viewport |
$uniform |
runtime-controlled uniform parameter |
@trigger |
trigger block; parsed by TriggerParser (also a legacy abs-lookup token in expressions) |
<stream> |
external input stream; resolved by an app-level precompile pass |
Fields
Declared inside a #field { … } block.
Field values
Fixed values, set once in the #field { … } block. Not re-evaluated as the program runs.
| Property | Default | Description |
|---|---|---|
dim |
(256, 256, 1) |
grid dimensions (x, y, z) |
every |
1 |
advance the field once every N runtime ticks |
scale |
65536 |
fixed-point scale (int mode); harmless for float |
eps |
(0.0001, 0.0001, 0.0001) |
per-channel comparison tolerance for eql/lrg/sml (default 0.0001) |
Field expressions
Evaluated for every element, on every step.
| Property | Default | Description |
|---|---|---|
set |
(0.0, 0.0, 0.0) |
initial value; evaluated once when the field is (re)seeded |
run |
per-step update expression |
Field modes
Each of these takes one of a fixed set of values. The default applies when the property is omitted.
mode
field numeric type: F32 (default), I32 (deterministic fixed-point), F16 / U8 (narrower storage)
| Value | Description |
|---|---|
F32 (default) |
32-bit float — full precision (default) |
I32 |
32-bit fixed-point int — cross-device deterministic (see docs/INT-MODE-REVIVAL.md) |
F16 |
half-precision storage — half memory; float arithmetic |
U8 |
unorm8 storage — quarter memory; UNIT domain only; 0 and 1 exact (binary CA) |
val_dom
interpretation domain of stored values
| Value | Description |
|---|---|
UNIT |
values normalized to 0..1 |
SIGNED (default) |
values normalized to −1..1 |
REAL |
unbounded real values |
coord_dom
interpretation domain of coordinates
| Value | Description |
|---|---|
UNIT |
coordinates mapped over 0..1 |
SIGNED (default) |
coordinates mapped over −1..1 |
sample
coordinate frame used for cross-field lookups
| Value | Description |
|---|---|
SOURCE (default) |
read the previous (settled) frame |
DEST |
read the in-progress (current) frame |
bound
out-of-bounds addressing policy
| Value | Description |
|---|---|
WRAP (default) |
wrap around to the opposite edge |
CLAMP |
clamp to the nearest edge |
ZERO |
out-of-bounds reads return 0 (absorbing/zero-padded edges) |
Field built-ins
Identifiers available inside a field's set / run expressions, and metadata read from any field reference.
| Name | Role | Description |
|---|---|---|
C |
coord | current cell coordinate of the containing field |
step |
value | global simulation step counter (scheduler tick); available in any expression |
#field.dim |
read | the field's grid dimensions (x, y, z); swizzleable, e.g. #A.dim.x |
#field.step |
read | the field's own advancement step (its run count), distinct from the global step |
Reducers
Traverse a region of a field and accumulate an expression at each visited cell: #field.OP(lo, hi){ … }.
Operators
| Name | Description |
|---|---|
SUM |
sum of the visited values |
AVG |
mean of the visited values |
MIN |
per-channel minimum of the visited values |
MAX |
per-channel maximum of the visited values |
Region shapes
| Name | Description |
|---|---|
BOX (default) |
axis-aligned region between two corners; an axis with zero extent is not iterated (1D/2D/3D) |
RAD |
radial region from a per-axis radius — disc, sphere or ellipsoid; a zero axis is not iterated (1D/2D/3D) |
Body identifiers
| Name | Type | Description |
|---|---|---|
V |
value | value currently visited in the reduced field (ref: V) |
U |
coord | computing cell mapped into the reduced field (ref: U) |
I |
coord | destination-frame iteration coordinate (ref: I) |
Lattice
Evaluate an expression at regular lattice points and blend the results: LATT.GEOM.BLEND(…){ … }.
Families
| Name | Description |
|---|---|
LATT |
value-noise lattice family |
Geometries
| Name | Description |
|---|---|
RECT (default) |
2D rectangular lattice — bilinear over the cell's 4 corners |
CUBE |
3D cubic lattice — trilinear over the cell's 8 corners |
Blend modes
| Name | Description |
|---|---|
LINEAR |
linear interpolation between lattice points |
CUBIC |
cubic (smoothstep) interpolation |
QUINTIC (default) |
quintic interpolation (smoothest) |
Body identifiers
| Name | Type | Description |
|---|---|---|
P |
coord | current lattice-point position |
D |
coord | displacement from evaluation position to lattice point |
R |
value | deterministic random value at the lattice point |
Formations
Declared inside a ~formation { … } block.
Formation values
Fixed values, set once in the ~formation { … } block. Not re-evaluated as the program runs.
| Property | Default | Description |
|---|---|---|
dim |
(1, 1, 1) |
formation-domain dimensions |
i_geo |
(1, 0, -0.4615385) |
custom instance geometry form [profile, bias, silhouette]; overrides shape |
i_res |
(0, 2, 0) |
custom instance geometry resolution [rings, segments, twist]; overrides shape |
Formation expressions
Evaluated for every element, on every step.
| Property | Default | Description |
|---|---|---|
col |
(1.0, 1.0, 1.0) |
per-element colour expression |
disp |
C |
surface displacement expression |
pos |
(0.0, 0.0, 0.0) |
whole-formation position offset |
rot |
(0.0, 0.0, 0.0) |
whole-formation rotation |
scl |
(1.0, 1.0, 1.0) |
whole-formation scale |
i_pos |
C |
per-instance position expression |
i_rot |
(0.0, 0.0, 0.0) |
per-instance rotation expression |
i_scl |
(1.0, 1.0, 1.0) |
per-instance scale expression |
i_piv |
(0.0, 0.0, 0.0) |
per-instance pivot point (rotation/scale centre, in primitive-local space) |
Formation modes
Each of these takes one of a fixed set of values. The default applies when the property is omitted.
type
formation topology (surface vs instances)
| Value | Description |
|---|---|
SURFACE (default) |
connected quad-grid surface over the domain |
INSTANCE |
one primitive per domain element |
shape
instance primitive shape (lazy default QUAD downstream)
| Value | Description |
|---|---|
CUBE |
unit cube |
QUAD (default) |
flat quad (default; tiles to the surface span) |
CONE |
cone |
ICO |
icosphere (subdivided sphere) |
SPHERE |
sphere |
rot_unit
how rotation values are interpreted
| Value | Description |
|---|---|
TAU (default) |
raw radians; TAU radians is one full turn |
SIGNED |
normalized signed turn; -1.0..1.0 maps to -PI..PI radians |
UNIT |
normalized turn; 0.0..1.0 maps to 0..TAU radians |
coord_dom
how the C/UV projection coordinate maps (UNIT 0..1 vs SIGNED −1..1)
| Value | Description |
|---|---|
UNIT |
coordinates mapped over 0..1 |
SIGNED (default) |
coordinates mapped over −1..1 |
shade
surface normal shading: FACE (faceted) or SMOOTH (interpolated)
| Value | Description |
|---|---|
FACE (default) |
faceted: per-face geometric normal (screen-space derivatives) |
SMOOTH |
interpolated per-vertex normals from the displaced surface |
filter
field-sampling filter for rendering: NEAREST or INTERPOLATE (bilinear)
| Value | Description |
|---|---|
NEAREST (default) |
read the nearest texel (no filtering) |
INTERP |
bilinear-filter the sampled field (smooth low-res rendering) |
sample
coordinate frame used for cross-field lookups
| Value | Description |
|---|---|
SOURCE (default) |
read the previous (settled) frame |
DEST |
read the in-progress (current) frame |
cull
backface culling for instance primitives: AUTO (closed solids cull back, QUAD/custom both sides), or force NONE/BACK/FRONT
| Value | Description |
|---|---|
AUTO (default) |
derive from primitive: closed solids cull back, flat/custom render both sides |
NONE |
render both faces (no culling) |
BACK |
cull back faces |
FRONT |
cull front faces |
Formation built-ins
Identifiers available inside a formation's expressions.
| Name | Role | Description |
|---|---|---|
C |
coord | formation surface UV coordinate |
step |
value | global simulation step counter (scheduler tick); available in any expression |
Viewports
Declared inside a ^viewport { … } block. proj is (near, far, fov); a fov of 0 selects orthographic projection, nonzero selects perspective.
Viewport values
Fixed values, set once in the ^viewport { … } block. Not re-evaluated as the program runs.
| Property | Default | Description |
|---|---|---|
pos |
(0, 0, 2.4142) |
camera position |
look |
(0, 0, 0) |
camera look-at point |
up |
(0, 1, 0) |
camera up vector |
proj |
(0.1, 100, 0.5) |
(near, far, fov); fov 0 = orthographic |
bg |
(0.05, 0.05, 0.15) |
background colour |
light |
(0, 0, 0) |
key/diffuse light colour |
fill |
(1, 1, 1) |
ambient/fill light colour |
light_dir |
(1, -1, -0.5) |
directional light direction |
Triggers
Conditions
A @on(…) predicate compares runtime state. The accepted vocabulary:
| Predicate | Tokens | Operators |
|---|---|---|
| Field step property | step |
== |
| Global clock identifiers | step, tick |
== |
| Single-cell components | x, y, z |
<, > |
Actions
Actions a trigger may dispatch when its condition is met.
| Action | Phase | Description |
|---|---|---|
set(#field) |
immediate | re-apply a field's set (seed) expression |
run(#field) |
immediate | resume a stopped field (clears its pause; does not itself advance it) |
stop(#field) |
immediate | stop a field from advancing |
step(#field) |
immediate | advance a field exactly one step on the next tick, even while stopped or off its rate beat; does not resume it |
log(…) |
drain | emit a field read to an output channel; with the key omitted (log(#A[0,0])) emits a plain text log.text event instead |
flush(…) |
drain | commit the current run (client policy) |
end(…) |
drain | halt the scheduler and finalize |
next(…) |
drain | advance an input binding/stream |
halt(…) |
drain | stop the clock until an external resume() |
Operators
All operators take and return three-channel values; mathematically scalar results are splatted to all channels. Short spellings are canonical.
Arithmetic
| Signature | Description |
|---|---|
add(a, b, …) |
sum of one or more values, per channel; one arg is identity |
sub(a, b) |
a − b, per channel; one arg is identity |
mlt(a, b, …) |
product of one or more values, per channel; one arg is identity |
div(a, b) |
a ÷ b, per channel; one arg is identity |
pow(a, b) |
a raised to the power b |
sqt(a) |
square root |
log(a) |
natural logarithm |
mod(a, b) |
a modulo b |
frc(a) |
fractional part (a − floor(a)) |
flr(a) |
floor (round down) |
cil(a) |
ceiling (round up) |
rnd(a) |
round to nearest integer |
abs(a) |
absolute value |
sgn(a) |
sign: −1, 0, or 1 |
Comparison
| Signature | Description |
|---|---|
eql(a, b) |
equal → 1, else 0 (per channel) |
lrg(a, b) |
a > b → 1, else 0 (per channel) |
sml(a, b) |
a < b → 1, else 0 (per channel) |
min(a, b, …) |
one arg: minimum vector component splatted; multiple args: per-channel minimum |
max(a, b, …) |
one arg: maximum vector component splatted; multiple args: per-channel maximum |
Trigonometry
| Signature | Description |
|---|---|
sin(a) |
sine (radians) |
cos(a) |
cosine (radians) |
tan(a) |
tangent (radians) |
asn(a) |
arcsine (radians) |
acs(a) |
arccosine (radians) |
atn(a, b) |
arctangent; atn(y, x) for two args |
Vector
| Signature | Description |
|---|---|
dot(a, b) |
dot product (splat to all channels) |
dst(a, b) |
distance between a and b |
len(a) |
vector length |
nrm(a) |
normalize to unit length |
aim(a) |
rotation that aims along a direction |
sum(a) |
sum vector components, splatted to all channels |
avg(a, b, …) |
one arg: average vector components splatted; multiple args: per-channel average |
Domain
| Signature | Description |
|---|---|
dom_idx(a, b) |
domain partition index: floor(P ÷ span) |
dom_phs(a, b) |
domain phase: positive offset of P inside span, in [0, span) (alias: wrp) |
dom_del(a, b, c) |
shortest signed displacement from A to B across periodic spans |
fof(a, b) |
linear falloff: 1 at distance 0, 0 at radius and beyond |
clp(a, b, c) |
clamp into a range (lo,hi — or 0..hi) |
mix(a, b, c) |
linear interpolate a→b by t |
rmp(a, b, c, …) |
linear ramp: rmp(p, stop, stop, ...) samples evenly spaced stops by normalized p |
hsl(a, b, c) |
convert RGB → HSL; accepts one RGB vector or r,g,b |
rgb(a, b, c) |
convert HSL → RGB; accepts one HSL vector or h,s,l |
Random
| Signature | Description |
|---|---|
rand(a, b, c) |
deterministic per-cell random from a seed, [0,1) |
srand(a, b, c) |
signed deterministic per-cell random from a seed, [−1,1) |
Constants
Reserved value identifiers, available as bare names in any expression.
| Name | Description |
|---|---|
PI |
π ≈ 3.14159 |
TAU |
τ = 2π ≈ 6.28319 (one full turn) |
TWO_PI |
synonym of TAU (legacy) |
HALF_PI |
π/2 ≈ 1.5708 |
I/O
Sample external input streams (images, webcam, OSC) registered via the API.
| Signature | Description |
|---|---|
INPUT(a) |
sample a named input stream (image/webcam/OSC) set via the API |