Build your own house: walls, windows, doors, floors, roof, stairs, furniture

House parts (stdlib isokit/house): house_wall drawn along a line, with ends
that adapt at corners, T-junctions and straight runs so no two walls
overlap; window and door that sit on a wall and cut its opening (door
styles panel, glass, double, sliding, opening; swing and hinge by
rotation); floor (boards, tiles, carpet, stone); roof (hip, gable, flat,
optional solar); stairs.

Furniture (stdlib isokit/furniture): chair, sofa / armchair, table with
chairs, desk with monitor and chair, TV, bed, cupboard, bookshelf, kitchen
run, bathtub, shower, toilet, washbasin, plant, rug, floor lamp.

Cut-open levels: on gf / 1f the walls in front of a room are cut low
(rooms are found by their floors), the roof becomes an outline on the
floor, and storeys above are left out. A part's storey comes from z
(storey_h, default 3 m).

Scripting: objects_of, objects_at, objects_on, mount_of, mounted, frame,
to_world, to_local, local_of. Prefab meta: shape (line / rect), mount,
storey.

Studio: drag to draw lines and rectangles (walls, roads, fences, hedges,
floors, areas, buildings, roofs). The Room tool draws a floor plus walls,
without doubling walls that already stand on an edge. Windows and doors
snap onto walls with a hover preview, and they move, turn, copy and
delete with their wall in one undo step. New parts land on the storey
the view shows. Palette categories collapse, and the palette scrolls
apart from the object list.

The MCP instructions explain house building, and list_prefabs shows
sits_on. examples/house is a furnished bungalow; the web Studio gets a
House demo button. Tests: wall corners and junctions, zero depth-sort
cycles in every view, cut levels, and the house demo in every view;
check_studio covers the room / window / door / storey flow, check_web
the House demo.

crates/isokit-script/src/api.rs

@@ -3,7 +3,7 @@
 use crate::conv::*;
 use crate::State;
 use isokit_core::fmt::{hash, round1, thousands};
-use isokit_core::{classes, LayerOpts, Sprite, C};
+use isokit_core::{classes, LayerOpts, Sprite, Xf, C};
 use rhai::{Array, Dynamic, Engine, FnPtr, Map, NativeCallContext};
 use std::cell::RefCell;
 use std::rc::Rc;
@@ -702,6 +702,7 @@ pub(crate) fn register_scene(e: &mut Engine, st: &Shared) {
     });
     let s = st.clone();
     e.register_fn("objects", move || s.borrow().all_objects.clone());
+    register_objects(e, st);
     // is a face with outward normal (nx, ny) (object coordinates) turned towards the viewer?
     let s = st.clone();
     e.register_fn("vis", move |nx: D, ny: D| -> RR<bool> {
@@ -783,3 +784,202 @@ pub(crate) fn register_scene(e: &mut Engine, st: &Shared) {
         Ok(m)
     });
 }
+
+// ---------------------------------------------------------------- objects and frames
+
+/// A type name or a list of them.
+fn kinds(d: &Dynamic) -> Vec<String> {
+    match d.read_lock::<Array>() {
+        Some(a) => a.iter().map(|v| v.to_string()).collect(),
+        None => vec![d.to_string()],
+    }
+}
+
+fn fnum(m: &Map, k: &str) -> f64 {
+    m.get(k).and_then(|v| n(v).ok()).unwrap_or(0.0)
+}
+
+fn sget(m: &Map, k: &str) -> String {
+    m.get(k).map(|v| v.to_string()).unwrap_or_default()
+}
+
+/// A number prop of a document object (`o.p.<k>`).
+fn prop(m: &Map, k: &str) -> Option<f64> {
+    m.get("p").and_then(|p| {
+        p.read_lock::<Map>()
+            .and_then(|p| p.get(k).and_then(|v| n(v).ok()))
+    })
+}
+
+/// The placement frame of a document object.
+fn xf_of(m: &Map) -> Xf {
+    Xf::new(fnum(m, "x"), fnum(m, "y"), fnum(m, "z"), fnum(m, "rot"))
+}
+
+fn of_type(d: &Dynamic, ks: &[String]) -> bool {
+    d.read_lock::<Map>()
+        .is_some_and(|m| ks.iter().any(|k| *k == sget(&m, "type")))
+}
+
+/// The object with (u, v), its position in another object's frame.
+fn with_uv(d: &Dynamic, u: f64, v: f64) -> Dynamic {
+    let mut m = d.read_lock::<Map>().map(|m| m.clone()).unwrap_or_default();
+    m.insert("u".into(), Dynamic::from_float(u));
+    m.insert("v".into(), Dynamic::from_float(v));
+    Dynamic::from_map(m)
+}
+
+/// The host `o` sits on: of the objects of the `hosts` types at the same
+/// height, the one whose centre line (local x, length `p.w`) passes within
+/// `p.t / 2 + tol` of o's position; the nearest wins, then the first.
+/// Returns its index and o's position (u, v) in the host's frame.
+fn host_index(objs: &[Dynamic], o: &Map, hosts: &[String], tol: f64) -> Option<(usize, f64, f64)> {
+    let (x, y, z) = (fnum(o, "x"), fnum(o, "y"), fnum(o, "z"));
+    let id = sget(o, "id");
+    let mut best: Option<(usize, f64, f64)> = None;
+    for (i, d) in objs.iter().enumerate() {
+        let Some(h) = d.read_lock::<Map>() else {
+            continue;
+        };
+        if !hosts.iter().any(|k| *k == sget(&h, "type")) || sget(&h, "id") == id {
+            continue;
+        }
+        let xf = xf_of(&h);
+        if (z - xf.z).abs() > 0.5 {
+            continue;
+        }
+        let l = xf.inv(x, y);
+        let half = prop(&h, "w").unwrap_or(1.0) / 2.0;
+        let lim = prop(&h, "t").unwrap_or(0.0) / 2.0 + tol;
+        if l[0].abs() <= half + 1e-6
+            && l[1].abs() <= lim + 1e-6
+            && best.is_none_or(|b| l[1].abs() < b.2.abs() - 1e-9)
+        {
+            best = Some((i, l[0], l[1]));
+        }
+    }
+    best
+}
+
+/// Queries over the document objects shown on this level, and frames.
+fn register_objects(e: &mut Engine, st: &Shared) {
+    // objects of a type (or a list of types) shown on this level
+    let s = st.clone();
+    e.register_fn("objects_of", move |k: D| -> Array {
+        let ks = kinds(&k);
+        s.borrow()
+            .objects
+            .iter()
+            .filter(|d| of_type(d, &ks))
+            .cloned()
+            .collect()
+    });
+    // ... whose footprint (p.w x p.d around the origin) holds the world point
+    let s = st.clone();
+    e.register_fn("objects_at", move |k: D, x: D, y: D| -> RR<Array> {
+        let (ks, x, y) = (kinds(&k), n(&x)?, n(&y)?);
+        Ok(s.borrow()
+            .objects
+            .iter()
+            .filter(|d| {
+                of_type(d, &ks)
+                    && d.read_lock::<Map>().is_some_and(|m| {
+                        let (Some(w), Some(dd)) = (prop(&m, "w"), prop(&m, "d")) else {
+                            return false;
+                        };
+                        let l = xf_of(&m).inv(x, y);
+                        l[0].abs() <= w / 2.0 + 1e-6 && l[1].abs() <= dd / 2.0 + 1e-6
+                    })
+            })
+            .cloned()
+            .collect())
+    });
+    // ... whose centre line (local x, length p.w) passes within p.t / 2 + tol
+    // of the world point, each with (u, v): the point in its frame
+    let s = st.clone();
+    e.register_fn("objects_on", move |k: D, x: D, y: D, tol: D| -> RR<Array> {
+        let (ks, x, y, tol) = (kinds(&k), n(&x)?, n(&y)?, n(&tol)?);
+        Ok(s.borrow()
+            .objects
+            .iter()
+            .filter(|d| of_type(d, &ks))
+            .filter_map(|d| {
+                let m = d.read_lock::<Map>()?;
+                let l = xf_of(&m).inv(x, y);
+                let half = prop(&m, "w").unwrap_or(1.0) / 2.0;
+                let lim = prop(&m, "t").unwrap_or(0.0) / 2.0 + tol;
+                (l[0].abs() <= half + 1e-6 && l[1].abs() <= lim + 1e-6)
+                    .then(|| with_uv(d, l[0], l[1]))
+            })
+            .collect())
+    });
+    // the host an object sits on (with u, v: the object's position in the
+    // host's frame), or ()
+    fn mount_of(s: &Shared, o: &Map, hosts: &D, tol: f64) -> Dynamic {
+        let b = s.borrow();
+        match host_index(&b.objects, o, &kinds(hosts), tol) {
+            Some((i, u, v)) => with_uv(&b.objects[i], u, v),
+            None => Dynamic::UNIT,
+        }
+    }
+    let s = st.clone();
+    e.register_fn("mount_of", move |o: Map, hosts: D| {
+        mount_of(&s, &o, &hosts, 0.3)
+    });
+    let s = st.clone();
+    e.register_fn("mount_of", move |o: Map, hosts: D, tol: D| -> RR<Dynamic> {
+        Ok(mount_of(&s, &o, &hosts, n(&tol)?))
+    });
+    // the objects of the given types that sit on host h (each with u, v)
+    fn mounted(s: &Shared, h: &Map, k: &D, hosts: &D, tol: f64) -> Array {
+        let b = s.borrow();
+        let (ks, hs, hid) = (kinds(k), kinds(hosts), sget(h, "id"));
+        b.objects
+            .iter()
+            .filter(|d| of_type(d, &ks))
+            .filter_map(|d| {
+                let m = d.read_lock::<Map>()?;
+                let (i, u, v) = host_index(&b.objects, &m, &hs, tol)?;
+                let on = b.objects[i]
+                    .read_lock::<Map>()
+                    .is_some_and(|x| sget(&x, "id") == hid);
+                on.then(|| with_uv(d, u, v))
+            })
+            .collect()
+    }
+    let s = st.clone();
+    e.register_fn("mounted", move |h: Map, k: D, hosts: D| {
+        mounted(&s, &h, &k, &hosts, 0.3)
+    });
+    let s = st.clone();
+    e.register_fn(
+        "mounted",
+        move |h: Map, k: D, hosts: D, tol: D| -> RR<Array> {
+            Ok(mounted(&s, &h, &k, &hosts, n(&tol)?))
+        },
+    );
+    // draw in another frame from here on (sprites made later, vis, tags)
+    let s = st.clone();
+    e.register_fn("frame", move |o: Map| {
+        s.borrow_mut().xf = xf_of(&o);
+    });
+    let s = st.clone();
+    e.register_fn("frame", move |x: D, y: D, z: D, rot: D| -> RR<()> {
+        s.borrow_mut().xf = Xf::new(n(&x)?, n(&y)?, n(&z)?, n(&rot)?);
+        Ok(())
+    });
+    let s = st.clone();
+    e.register_fn("to_world", move |x: D, y: D| -> RR<Array> {
+        let p = s.borrow().xf.p(n(&x)?, n(&y)?);
+        Ok(vec![Dynamic::from_float(p[0]), Dynamic::from_float(p[1])])
+    });
+    let s = st.clone();
+    e.register_fn("to_local", move |x: D, y: D| -> RR<Array> {
+        let p = s.borrow().xf.inv(n(&x)?, n(&y)?);
+        Ok(vec![Dynamic::from_float(p[0]), Dynamic::from_float(p[1])])
+    });
+    e.register_fn("local_of", |o: Map, x: D, y: D| -> RR<Array> {
+        let p = xf_of(&o).inv(n(&x)?, n(&y)?);
+        Ok(vec![Dynamic::from_float(p[0]), Dynamic::from_float(p[1])])
+    });
+}