---
title: Language Reference
navTitle: Language Reference
slug: reference/language
kind: reference
section: Reference
order: 420
status: active
summary: Every construct, property, operator, built-in, and trigger in Utomata, enumerated from the lexicon.
aliases: [language, syntax, grammar, ref]
generated: true
---

# Utomata Language Reference

> 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](../manual/foundations.md) 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 |