grabowski
e4017ce2a8
Deploy web Studio / deploy (push) Successful in 3m52s
Joints: line_joint (util.rhai) applies the house-wall rules to fences and site walls, so pieces never overlap and the depth sort stays clean. - A corner is closed: the thicker piece (or, if equal, the one along world x) runs through, and the other stops at its face. - On a straight run, two pieces share one post. - At a T, the stem stops at the other piece's face without a post of its own. - A fence that ends at a site or house wall stops at the wall's face. Fence designs (prop style): mesh, wooden boards, steel bars, mesh on a stone base, cobble wall, and brick wall with pillars. Board, stone and brick joints are drawn on the face turned to the viewer. Brick pillars are separate sprites. Studio: line prefabs (walls, fences, hedges, roads) can be drawn as a run by clicking corner after corner. Double-click or Enter ends the run, clicking the first corner closes it, and Backspace drops the last corner. A run is one undo step. A drag still draws one piece. Corners and ends snap onto the ends and lines of the pieces they meet, and a marker shows where the next corner will snap. The house demo gets a brick front wall with gate pillars and wooden side fences in place of the old east fence, which ran over the road. Tests cover every design's corners, Ts, straight runs and wall stops, with no depth-sort cycles in any rotation, plus site walls. check_studio draws and closes a fence run, undoes it in one step, snaps a dragged spur, and picks a design.
176 lines
9.8 KiB
Markdown
176 lines
9.8 KiB
Markdown
# 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`).
|
||
- `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 (`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) |
|
||
| `to_world(x, y)`, `to_local(x, y)`, `local_of(o, x, y)` | 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) |
|
||
| `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`; 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).
|
||
|
||
## 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 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.
|