isokit: project layer, Studio GUI, MCP server, viewer, CLI, demo project and docs

docs/SCRIPTING.md

@@ -0,0 +1,117 @@
+# 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).
+- `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 |
+| `focus(x, y, z)`, `bounds(x0, y0, x1, y1[, depth])`, `defs(svg)`, `warn(msg)` | framing and extras |
+| `level()`, `rot()`, `cfg()`, `cfg(name)`, `objects()` | inputs |
+| `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) |
+| `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 |
+| `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 |
+| `seq([[x, y, \|q\| …], …])` | items drawn back to front by their anchor |
+| `group(cls[, css], \|q\| …)`, `begin(cls[, css])` … `end()` | `<g>` around parts (animation) |
+| `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`.
+
+## 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 they stay still.
+- 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.