isokit/docs/SCRIPTING.md

# Scripting and prefabs

Scenes and prefabs are written in [Rhai](https://rhai.rs/book/), a small
scripting language embedded in isokit. Nothing is compiled: save the file and
the Studio redraws.

## A prefab

A prefab is an object type that can be placed in the Studio. It is two
functions in a module that is listed in `isokit.toml` under `prelude`:

```rust
fn meta_kiosk() {                      // label, palette group and property form
    #{ label: "Gate kiosk", category: "Site", icon: "⌂", help: "…",
       props: [
         #{ key: "h", type: "float", def: 2.8, min: 2.2, max: 4.0, step: 0.1, label: "Height (m)" },
         #{ key: "boom", type: "bool", def: true, label: "Boom barrier" },
       ] }
}

fn prefab_kiosk(o) {                   // draw around (0, 0) in the object's own frame
    let s = sprite();                  // sprite ids default to the object id
    s.box(-1.4, -1.1, 1.4, 1.1, 0.0, o.p.h, "brick", #{ top: "roof3" });
}
```

- Property types: `float`, `int`, `bool`, `choice` (with `choices`),
  `material` (a theme material, optionally with `choices`), `text`.
  Write `def:` for the default (`default` is a reserved word in Rhai).
- How the Studio places it: `shape: "line"` (drag along the map: sets `rot`
  and the length prop `w`), `shape: "rect"` (drag a rectangle: sets `w` and
  `d`), default a click. `mount: ["house_wall"]`: the prefab sits on objects of
  those types; the Studio snaps it onto the nearest one and moves, turns,
  copies and deletes it with its host. `storey: true`: placed on the storey the
  view shows (level `1f` puts it at z = 1 × `storey_h`). `directed: true` (with
  `shape: "line"`): the way matters, so the Studio turns the piece to run from
  where the drag starts (rot 0, 90, 180 or 270; conveyors).
- `o` holds `id, type, name, x, y, z, rot, p` (the props with defaults
  filled in), `pts`, `tag`, `info`, `level`.
- The engine sets the object's frame before calling the prefab. All
  coordinates are local: the origin is the object's position, and local x and y
  turn with `rot`. `vis()`, `dv()`, `tag()` and `focus()` use the frame too.
- A prefab with the same name in the project overrides the built-in one.
- If a prefab fails, the engine logs a warning for that object and still draws the rest.

## Drawing API

Numbers can be ints or floats. Classes are CSS classes without the `iso-`
prefix (`"wall"` becomes `iso-wall`). A material sets the face colour, which is
shaded automatically by face direction.

### Scene

| Function | |
|---|---|
| `sprite()` / `sprite(id)` / `sprite(id, cls)` | new sprite (the unit of the depth sort) in the current layer |
| `ground()` | the shared unsorted ground sprite |
| `layer("ground" \| "floor" \| "main")`, `layer(name, #{sort, zfirst, cls, before})` | where new sprites go |
| `tag(x, y, z, text[, prio[, id[, kind]]])` | label; `kind` "signtag" / "warntag" always shows |
| `info(id, name[, detail])`, `info(id, #{name, detail, rows: [[k, v], …]})` | tooltip |
| `info_row(key, value)` | one row more in the tooltip of the object being drawn (a belt's speed) |
| `focus(x, y, z)`, `bounds(x0, y0, x1, y1[, depth])`, `defs(svg)`, `warn(msg)` | framing and extras |
| `level()`, `rot()`, `cfg()`, `cfg(name)`, `objects()` | inputs (`objects()`: every document object, props resolved) |
| `objects_of(types)` | objects of a type or a list of types shown on this level |
| `objects_at(types, x, y)` | … whose footprint (`p.w` × `p.d` around the origin) holds the world point |
| `objects_on(types, x, y, tol)` | … whose centre line (local x, length `p.w`) passes within `p.t / 2 + tol` of the point, with `u, v` = the point in their frame |
| `mount_of(o, hosts[, tol])` | the host o sits on (nearest centre line within `p.t / 2 + tol`, default 0.3 m, same height), with `u, v` = o's position in the host's frame; `()` if none |
| `mounted(h, types, hosts[, tol])` | the objects of `types` whose host is h, each with `u, v` |
| `frame(o)`, `frame(x, y, z, rot)` | draw in another frame from here on (a window draws in its wall's frame); `rot` is any angle in degrees (quarter turns stay exact) |
| `to_world(x, y)`, `to_local(x, y)`, `local_of(o, x, y)`, `world_of(o, u, v)` | between the current frame (or o's) and world plan coordinates |
| `vis(nx, ny)` | is a face with that outward normal turned to the viewer? |
| `dv(dx, dy, dz)` | screen vector of a world vector (CSS motion) |
| `along_x()` | should a mover run along x in this rotation? |
| `hash(x)`, `fmt(n)`, `round1(x)`, `fmin`, `fmax`, `clamp`, `px()` | helpers |
| `rect(x0, y0, x1, y1)`, `ellipse(cx, cy, a, b, n)`, `rsegs(r)`, `sides(x0, y0, x1, y1)` | geometry |

### Sprite methods (chainable)

| Method | |
|---|---|
| `box(x0, y0, x1, y1, z0, z1, mat[, #{id, top, side, no_top, no_side}])` | axis-aligned box |
| `prism(pts, z0, z1, mat[, opts])` | convex counter-clockwise footprint; z0/z1 one value or one per vertex |
| `cyl(cx, cy, r, z0, z1, mat[, opts])`, `frust(cx, cy, r0, r1, z0, z1, mat[, sides[, opts]])` | round things |
| `slope(x0, x1, y0, y1, za, zb, th, mat)` | ramp / stair flight |
| `face(pts3, mat[, #{id, two_sided}])` | any planar polygon, shaded and culled by its normal (roof slopes, gables) |
| `beam(a, b, n, w, mat)` | square bar `w` wide between 3D points a and b, `n` a direction across it (robot arms, trusses) |
| `poly(polys3, cls[, id])` | 3D polygons as one path (solar modules) |
| `flat(poly or polys, z, cls[, id])` | flat polygon(s); later ones cut holes |
| `open(a, b, [[u0, u1, z0, z1], …], cls[, id])` | windows / doors on the face a→b (outward normal on the right) |
| `lines(segs, z, cls)`, `disc(cx, cy, z, r, cls[, id])` | markings |
| `polyline(lines, z, cls)` | open lines through plan points at height z, or 3D points `[x, y, z]` (antlers): a dashed line stays one dash run round a curve |
| `circle(x, y, z, r_px, cls[, dx, dy])`, `stem(x, y, z0, z1, w_px, cls)` | screen-space details (crowns, poles) |
| `person(x, y, z[, cls])`, `sit(x, y, z, cls)`, `head(x, y, z, r)`, `led(x, y, z[, cls])` | figures |
| `puffs(x, y, z[, kind[, n, dur]])`, `fan(x, y, z, r)` | animated steam / smoke / fans |
| `swim(x, y, z, [#{ rx, ry, dur, delay, cw, len, cls[, shape] }, ...])` | fish going round ellipses (radii rx, ry along the object's axes) about (x, y) on the plane at z, one round per `dur` s, clockwise when `cw`; `cls` koi / koiw / koig (the pond); `shape` "bird" (wings `len` across, flapping), "fly" (a butterfly) or "bee" makes it a flock |
| `seq([[x, y, \|q\| …], …])` | items drawn back to front by their anchor |
| `group(cls[, css], \|q\| …)`, `begin(cls[, css])` … `end()` | `<g>` around parts (animation) |
| `travel(a, b, dur, [[s, e], …])` … `end()` | a mover on a straight piece: what is drawn (at a) slides to b during each window (fractions of the `dur`-second cycle, may wrap past 1) and is hidden otherwise |
| `ext_reset()` | forget the sort extent drawn so far (set it with `ext` afterwards) |
| `ext(x, y, z)`, `ext_box(…)` | widen the sort box |
| `raw([x, y, z,] svg)` | raw SVG (`{uid}` becomes the view's id) |

Library helpers (`stdlib/*.rhai`): `s.tree_at(x, y, r)`, `s.car(x0, y0, x1, y1, cls)`,
`s.drive(dx, dy, dur, delay)` … `s.end()`, `cut_walls(...)`, `win_list(...)`,
`floor_of(level)`, `building_windows`, `gable_roof`, `flat_roof_kit`; for house
parts (`stdlib/house.rhai`, `stdlib/furniture.rhai`): `storey_of(z)`,
`house_view(o)` (0 closed, 1 on the storey cut open, 2 above it: leave out),
`wall_top(w)`, `opening_at(o)`, `s.slab(a, b, th, z0, z1, mat)`,
`s.chair_at(x, y, bx, by, mat)`, `s.office_chair(x, y, mat)`.

## Joints of walls and fences

`line_joint(o, e, same, stops)` (util.rhai) tells a line piece (centre line
along local x, length `p.w`) how it meets others at its end `e` (-1 or 1):
`#{ ext, post }`, how far it reaches past the end and whether it draws its end
post. `same` are the types it joins with, `stops` the types it ends against;
half thicknesses come from `line_ht(o)` (`p.t / 2`, for fences the design's).
Alone a piece reaches half its thickness past the end; on a straight run the
lower piece runs through and draws the shared post; at a corner the thicker
piece (equal: the one along world x) runs through and the other stops at its
face; at a T the stem stops at the face without an end post; against a `stops`
piece it stops at the face and keeps its post. Pieces never overlap, which the
depth sort needs. `fence` (designs `style`: mesh, wood, bars, half stone,
cobble, brick) and the site `wall` use it; `house_wall` has its own version
(`wall_ext`, house.rhai).

### Diagonal pieces

Objects turn by any angle (`rot` in degrees); a box drawn in a turned frame
becomes a prism with its own four corners. Where a piece off the axes is
involved, `line_meet(o, e, same, stops)` (util.rhai) replaces the rules above
for that end: `#{ kind, ext, k, ... }` with kind `axis` (every piece there
keeps to the axes: use the old rules, so such scenes draw as before),
`free`, `run` (in line), `corner` (a mitre on the bisector; `owner` draws a
fence's corner post) or `tee` (stop at the other's face). The end is
slanted: the line `v` to the piece's left reaches `ext + k * v` past it.
`end_cut(w, e, m)` turns that into `#{ x, k }` and `s.cut_box(x0, k0, x1, k1,
y0, y1, z0, z1, mat[, opts])` draws a box with such ends. Fences put their
corner post (or brick pillar) in its own sprite and stop their panels at it;
stone bases and cobble walls are mitred. Helpers: `on_axes(rot)`,
`dir_of(o)`, `dot2(a, b)`.

The depth sort keeps diagonal pieces right through outlines: a sprite whose
plan outline is not its box (turned or mitred pieces) carries its convex
outline, and when two boxes overlap an outline edge that separates them
orders them, the one on the viewer's side going later. A long diagonal wall
therefore sorts right against everything on either side of it, and mitred
pieces against each other.

## Animals

`wildlife.rhai` draws animals as low-poly solids from faces. `s.loft(spine,
rs, n, [side, cap0, cap1])` sweeps an n-sided ring (radius r, or `[across,
up]`) along 3D points, keeping its turn round bends; `s.tube(a, b, ra, rb, n,
mat)` is a loft of two rings. `face` shades each face by its direction and
leaves out the ones turned away, so a solid needs no sorting of its own
faces; separate parts (legs, body, neck, head, antlers) are drawn back to
front by `draw_parts`, which sorts them by the depth of their anchors in the
view (`depth(x, y) + z`). The class `beast` edges each face in its own shade
instead of the dark outline, so a body reads as one surface.

`animal_parts(kind, sub)` returns `#{ body, up, down }` for an animal facing
+x: the parts that stay and two head poses. With grazing on, the poses sit in
two groups `iso-a iso-pose2 iso-pose0` and `iso-a iso-pose2` that take turns
(the CSS shows the first unanimated); each animal starts at its own point of
the cycle. `herd(o, kind, mix, graze)` scatters `n` animals in a sunflower
spread within `r` of the object, each facing its rotation give or take 70°,
each its own sprite. Flocks of birds, butterflies and bees use `swim` with a
`shape`.

Hamsters add three kinds of parts to `draw_parts`: `loft2` (a loft in two
colours: faces pointing down get the belly colour, see `loft2`), `eye` (a
shiny bead, or shut) and `flip` (a flipbook: one part list per pose, shown
0.1 s each in groups `iso-a iso-flip4 [iso-pose0]`, the step of the viewer's
light animation mode). `hamster_parts(run, sleep, n, np, delay, fur)` builds
one about 1.2 m long, `place_parts(parts, s, o)` scales and moves any part
list, and `s.hamster_at(x, z, size, run, sleep, fur, delay)` draws it
(`hamster_life()` = life size). `s.hamster_wheel(R, run, stand, fur, delay)`
draws a wheel with a hamster in it: the rungs join the wheel's two planes, so
they are a flipbook too, drawn behind or in front of the hamster pose by
pose; the spokes turn by CSS inside `vplane_g(ux, uy)`, a raw group mapping
a vertical plane onto the screen in metres.

Small things lose their shape to the drawing's 0.1-unit grid (2.5 cm): draw
them `fine_k(size)` times bigger between `s.fine_begin(x, y, z, fz, k, css)`
and `s.fine_end()` (a group that scales them back about the point), then set
the sort extent with `ext_reset()` and `ext_box()`. Screen-unit values
inside (stroke widths, `--bw` for the `beast` edges) are k times bigger too.

## Points (`pts`)

An object's `pts` are plan points relative to its x, y in its turned frame. A prefab that draws
them as its outline sets `outline: true` in its meta (Area): the Studio then offers Edit corners,
which turns its `w` x `d` rectangle into four points, and Rectangle again, which removes them.
Every selected object with `pts` shows handles: drag a point, drag the + of a side to add one,
double-click a point to remove it (an open route keeps 2, a closed outline 3). Route points say
whether they close with `props.closed`; any other `pts` are a closed outline.

## Groups and the drawing order

Objects of type `group` are never passed to scripts (they draw nothing), nor is anything inside a
hidden group (`Doc::hidden_in_groups`); prefabs never see the `group` field's effect. The order of
`scene.json` is the drawing order of the `ground` layer (unsorted): later ground pieces lie on
top. Sorted layers ignore it except for ties. The Studio keeps each group's members just before
the group object (`tree`, `flatten` in studio.js) and sends tree edits as one `order` op.

## Routes

`routes.rhai` (`route` prefab, meta `shape: "path"`: the Studio draws it point by point and
stores the points in the object's `pts`, relative to its x, y). The movers' path is one closed
line: a loop is offset to the left of the drawn line by the kind's lane (`keep: "right"` the
other way); an open route runs out on one side and back on the other, so it is a loop too, and
its two strips never overlap. Corners are rounded into pieces of at most 45° (`rt_round`;
people keep sharp corners, they look the same from every side).

Each straight piece is its own sprite in the piece's frame: for every group of movers that look
alike and are never on the piece together, `travel([0,0,0], [len,0,0], dur, wins)` with the
mover drawn at the start, then `ext_reset()` and the lane strip as its extent, mitred at both
ends so neighbouring pieces never overlap. Mover k is on a piece that starts `at` metres along
a loop of `total` metres while `(t / dur - at / total + k / n) mod 1` lies in `[0, len / total]`.
The renderer turns each travel into keyframes (visibility and translation, named by a hash of
their content, all in one `<style>` per view). Movers carry `iso-travel`, not `iso-a`: views
without animation (reduced motion, stopped, ghosted) pause them where they are instead of
hiding them.

## Production lines

`producer`, `conveyor` and `robot_arm` (stdlib/industry.rhai) work together
through the document, like house parts:

- A producer makes one of its `product` goods every 60 / `rate` seconds (its
  ram goes down once per item) and puts them out on its local +x side.
- A conveyor carries goods along its local +x at `speed` m/s. When its start
  lies on a producer's output side, it carries that producer's goods at its
  rate; when its start is at another conveyor's end, it carries on with what
  that one carries (followed back up to 12 belts). The gap between goods is
  speed / rate, so a faster belt spreads them out. A stopped producer or belt
  stops the goods after it. Alone a conveyor carries its own `item` every
  `gap` metres.
- Belts meeting at a corner do not overlap: the belt a feeding belt runs into
  runs through the corner and the feeding one stops at its side; at a T the
  belt stops at the side. `rise` lifts the end (an incline).
- The goods ride a group that moves one gap per loop (`iso-ride`), so their
  drawing order never changes; the first fades in, the last fades out.
  Tooltips show speed, rate and where the goods come from (`info_row`).
- A robot arm picks goods off the end of the nearest conveyor within `reach`
  (+0.4 m) and puts them on the start of another conveyor within reach, or on
  a pallet a quarter turn on (`pick` / `put`: auto or a side of the arm). It
  makes one move per item coming in (`cycle` 0) or every `cycle` seconds, and
  waits while the line before it stands. The belt it puts on carries its goods
  and starts its loop when they land, so arm and belts stay in step.
- The arm is a flipbook: 16 poses (two-link inverse kinematics, links drawn
  with `beam`), each shown for a sixteenth of the cycle by a stepped CSS
  animation (`iso-flip`); a rotation cannot turn a 3D arm in this projection.
  Poses pointing away from the viewer are drawn before the base, the others
  after it.

## Streets

`road`, `road_curve` and `roundabout` (stdlib/streets.rhai; `road` lives in
ground.rhai) meet by their centre lines:

- Each street is a centre line (a polyline or a true arc) with the
  carriageway `d` wide around it; `walk` (none, both, left, right, looking
  along local +x) adds sidewalks `walk_w` wide behind the kerbs: 12 cm high
  paving with the kerb face drawn where it is turned to the viewer. Arcs stay
  arcs when cut and offset, so a curve meets a straight road exactly.
- End to end (a curve continuing a road, a road continuing a roundabout arm)
  the pieces carry on, overlapping by 4 cm so no hairline shows.
- A street ending on a road's centre line makes a T, at any angle: the road
  leaves a gap in its kerb and sidewalk on that side (slanted along the
  street coming in), the street ends its asphalt on the road's centre line,
  its centre line and kerbs at the road's edge and its sidewalks at the
  road's sidewalk.
- Two streets ending at one point at any angle meet in a mitre on the
  bisector (thin seam patches reach over it, so no hairline shows).
- Every part of a street end is a cut `#{ e, k }`: the line `w` to the left
  looking out reaches `e + k * w` past the end (`street_join`); gaps are
  `#{ lo, hi, c }` ranges that slant with the side offset (`street_gaps`).
- A roundabout's arms end `r + arm_len` from its centre, along its local
  +x, +y, -x, -y. Its kerbs flare into the ring with a fillet; splitter
  islands and give-way lines sit on the entry side for `drive` left or right.
- The prefab meta `corner: "road_curve"` on `road` tells the Studio to round
  each corner of a road run with a curve (up to its default radius, less
  where the pieces next to a corner are short).
- `street_ends(o)`, `street_join(o, end, others)`, `street_gaps(o, others)`
  and `street_path(o, line, j0, j1, gaps)` are there for your own street
  prefabs; tooltips list the streets each one meets (`Meets`).

## House parts

`house_wall`, `window`, `door`, `floor`, `roof`, `stairs` and the furniture
prefabs work together through the document, not through a parent object:

- A window or door at a point on a wall's centre line (within the wall's half
  thickness + 0.3 m, same height) sits on that wall (`mount_of`). The wall
  leaves a gap for it (`mounted`), the window draws the opening in the wall's
  frame with the wall's height, thickness and material. On no wall it stands
  alone as a short wall piece. Its rotation relative to the wall picks a
  door's swing side (0, 90: towards the wall's +y side) and hinge (0, 180:
  at the low end).
- Wall ends adapt to the walls they meet, so no two walls overlap (the depth
  sort needs them apart): along a line two walls just meet, at a T the stem
  stops at the other wall's face, at a corner the wall along world x runs
  through and the other stops at it.
- A part's storey is `floor((z + 0.5) / storey_h)` (`storey_h`: project
  parameter, default 3 m). On level `gf` (`1f`, …) the parts on that storey
  are cut open: a wall stays full height only when a floor lies on the
  viewer's side of it and none behind it (it is a back wall), all others are
  cut to 1 m. Roofs on that storey become an outline on the floor, parts on
  storeys above are left out, the storeys below stay closed.
- Ground-level floors and rugs go to the `floor` layer; upper floors are slabs
  whose top is at the object's z. Furniture starts 0.02 m above its z.

## Rules that keep the depth sort right

These are lessons from the CNX/Mooban views, and the engine relies on them:

- **One sprite per thing that can stand in front of another.** Split long walls,
  fences and solar rows into pieces (≤ 30 m). One big sprite overlapping many
  others creates sort cycles (`isokit check` reports them).
- **Things under a cover belong in the cover's sprite**: draw cars under a carport
  before its posts and roof (see `prefab_carport`).
- **Floors of cut-open storeys go in the `floor` layer** (ground floor) or in
  the same sprite as the storey below. Start walls and furniture standing on
  them a little above the floor (+0.02 m).
- **Movers** (`drive`) run along the axis the sort compares second
  (`along_x()`). Along the other axis (and on diagonals) they stay still.
- **Diagonal pieces** sort by their outlines (see Diagonal pieces), so they
  need no extra splitting; things standing exactly on a wall's line still
  interpenetrate it and sort by their centres.
- Street furniture stays off drive areas, and pipe runs end on walls or supports.

## Themes

`theme.toml` stacks on the built-in palette:

```toml
[palette.dark]
brick = "#8a4f3e"
[palette.light]
brick = "#b8664c"
[materials]
brick = "brick"          # class iso-brick, colour var(--iso-brick)
[rules]
".iso-svg .iso-sign2" = "fill: #ffcc00; stroke: none"
```

`isokit check` warns about any class in the drawing that has no style.