trid3d 0.2.0 → 0.3.0

package/trid/render/shapes.js

@@ -364,67 +364,134 @@ export function triangulate(pts) {
  * centered on the origin: blades, axes, keys, stars, letters, floor plans.
  * The outline may go either way round and may be concave (no holes).
  *
+ * Options:
+ * - `bevel`: cuts the edges between the sides and the front / back by this
+ *   much, so they catch the light (and a blade gets a thin edge). Up to half
+ *   the depth.
+ * - `bevelSegments`: 1 is a flat chamfer, more makes a rounded edge.
+ * - `taper`: size of the back compared to the front (1 = same, 0.5 = half
+ *   as big), scaled around the middle of the outline's bounding box.
+ *
  * Texture coordinates: the front and back map the outline's bounding box,
- * the sides wrap u along the outline and v across the depth. Edges are the
- * front and back outlines plus a line at each corner.
+ * the sides wrap u along the outline and v from front to back. Edges are
+ * the outline at each step plus a line along each corner.
  *
  * @example
  * const star = Array.from({ length: 10 }, (_, i) => {
  *   const a = (i / 10) * Math.PI * 2, r = i % 2 ? 0.2 : 0.5;
  *   return { x: Math.cos(a) * r, y: Math.sin(a) * r };
  * });
- * scene.add({ mesh: extrude(star, 0.15), material: { fill: "#fc5" } });
+ * scene.add({ mesh: extrude(star, 0.15, { bevel: 0.03, bevelSegments: 3 }), material: { fill: "#fc5", smooth: true } });
  *
  * @param {{x:number, y:number}[]} outline - The flat shape (3 points or more)
  * @param {number} [depth=0.2] - Thickness along Z
+ * @param {Object} [opts]
+ * @param {number} [opts.bevel=0] - How much the edges are cut (clamped to half the depth)
+ * @param {number} [opts.bevelSegments=1] - Steps around a bevel (1 = flat chamfer)
+ * @param {number} [opts.taper=1] - Size of the back compared to the front
  * @returns {import("../index.d.ts").Mesh}
  */
-export function extrude(outline, depth = 0.2) {
+export function extrude(outline, depth = 0.2, { bevel = 0, bevelSegments = 1, taper = 1 } = {}) {
   const pts = signedArea(outline) < 0 ? [...outline].reverse() : outline;
   const n = pts.length;
+  const half = depth / 2;
+  const b = Math.max(0, Math.min(bevel, half));
+  const steps = Math.max(1, Math.floor(bevelSegments));
+
+  const xs = pts.map((p) => p.x), ys = pts.map((p) => p.y);
+  const x0 = Math.min(...xs), y0 = Math.min(...ys);
+  const w = Math.max(...xs) - x0 || 1, h = Math.max(...ys) - y0 || 1;
+  const cx = x0 + w / 2, cy = y0 + h / 2;
+
+  // The profile from front (-z) to back (+z): how far each ring is pulled in, and its z.
+  // A bevel is a quarter circle (or a chamfer) at each end.
+  const profile = [];
+  if (b > 0) {
+    for (let i = 0; i <= steps; i++) {
+      const a = (i / steps) * (Math.PI / 2);
+      profile.push({ inset: steps === 1 ? b * (1 - i) : b * (1 - Math.sin(a)), z: -half + (steps === 1 ? b * i : b * (1 - Math.cos(a))) });
+    }
+    // Skip the straight middle when the bevels meet
+    const backStart = b < half - 1e-9 ? 0 : 1;
+    for (let i = backStart; i <= steps; i++) {
+      const a = (i / steps) * (Math.PI / 2);
+      profile.push({ inset: steps === 1 ? b * i : b * (1 - Math.cos(a)), z: half - (steps === 1 ? b * (1 - i) : b * (1 - Math.sin(a))) });
+    }
+  } else {
+    profile.push({ inset: 0, z: -half }, { inset: 0, z: half });
+  }
+
+  // Inward direction at each corner (the outline is counter-clockwise, so inside is on the left)
+  const inward = pts.map((p, i) => {
+    const prev = pts[(i + n - 1) % n], next = pts[(i + 1) % n];
+    const n1 = leftNormal(prev, p), n2 = leftNormal(p, next);
+    let mx = n1.x + n2.x, my = n1.y + n2.y;
+    const ml = Math.hypot(mx, my) || 1;
+    mx /= ml; my /= ml;
+    // Miter: longer at sharp corners, but capped so they don't spike
+    const k = Math.min(3, 1 / Math.max(0.2, mx * n1.x + my * n1.y));
+    return { x: mx * k, y: my * k };
+  });
+
   const vertices = [];
   const faces = [];
   const uvs = [];
   const faceUVs = [];
   const uv = (u, v) => uvs.push({ u, v }) - 1;
-
-  // 0..n-1 at the front (-z), n..2n-1 at the back (+z)
-  for (const p of pts) vertices.push({ x: p.x, y: p.y, z: -depth / 2 });
-  for (const p of pts) vertices.push({ x: p.x, y: p.y, z: depth / 2 });
-
-  const xs = pts.map((p) => p.x), ys = pts.map((p) => p.y);
-  const x0 = Math.min(...xs), y0 = Math.min(...ys);
-  const w = Math.max(...xs) - x0 || 1, h = Math.max(...ys) - y0 || 1;
-  const capUV = (i) => uv((pts[i].x - x0) / w, (pts[i].y - y0) / h);
+  // Ring r is vertices r*n .. r*n+n-1
+  for (const { inset, z } of profile) {
+    const t = depth > 0 ? (z + half) / depth : 0;
+    const k = 1 + (taper - 1) * t;
+    for (let i = 0; i < n; i++) {
+      const x = pts[i].x + inward[i].x * inset, y = pts[i].y + inward[i].y * inset;
+      vertices.push({ x: cx + (x - cx) * k, y: cy + (y - cy) * k, z });
+    }
+  }
+  const last = (profile.length - 1) * n;
 
   // Caps: counter-clockwise outlines look clockwise from the back (+z), so the
   // back cap keeps that order and the front cap (seen from -z) is reversed
-  for (const [a, b, c] of triangulate(pts)) {
-    faces.push([n + a, n + b, n + c]);
-    faceUVs.push([capUV(a), capUV(b), capUV(c)]);
-    faces.push([c, b, a]);
-    faceUVs.push([capUV(c), capUV(b), capUV(a)]);
+  const capUV = (i) => uv((pts[i].x - x0) / w, (pts[i].y - y0) / h);
+  for (const [a, c1, c2] of triangulate(profile[0].inset > 0 ? vertices.slice(0, n) : pts)) {
+    faces.push([last + a, last + c1, last + c2]);
+    faceUVs.push([capUV(a), capUV(c1), capUV(c2)]);
+    faces.push([c2, c1, a]);
+    faceUVs.push([capUV(c2), capUV(c1), capUV(a)]);
   }
 
-  // Sides, u by length along the outline
+  // Sides between each pair of rings, u by length along the outline, v by length along the profile
   const len = [0];
   for (let i = 0; i < n; i++) len.push(len[i] + Math.hypot(pts[(i + 1) % n].x - pts[i].x, pts[(i + 1) % n].y - pts[i].y));
   const total = len[n] || 1;
-  for (let i = 0; i < n; i++) {
-    const j = (i + 1) % n;
-    const ua = len[i] / total, ub = len[i + 1] / total;
-    faces.push([n + j, n + i, i, j]);
-    faceUVs.push([uv(ub, 1), uv(ua, 1), uv(ua, 0), uv(ub, 0)]);
+  const along = [0];
+  for (let r = 1; r < profile.length; r++) {
+    along.push(along[r - 1] + Math.hypot(profile[r].inset - profile[r - 1].inset, profile[r].z - profile[r - 1].z));
+  }
+  const vTotal = along[along.length - 1] || 1;
+  for (let r = 0; r < profile.length - 1; r++) {
+    const f0 = r * n, f1 = (r + 1) * n;
+    const va = along[r] / vTotal, vb = along[r + 1] / vTotal;
+    for (let i = 0; i < n; i++) {
+      const j = (i + 1) % n;
+      const ua = len[i] / total, ub = len[i + 1] / total;
+      faces.push([f1 + j, f1 + i, f0 + i, f0 + j]);
+      faceUVs.push([uv(ub, vb), uv(ua, vb), uv(ua, va), uv(ub, va)]);
+    }
   }
 
   const edges = [
-    pts.map((_, i) => i),
-    pts.map((_, i) => n + i),
-    ...pts.map((_, i) => [i, n + i]),
+    ...profile.map((_, r) => pts.map((_, i) => r * n + i)),
+    ...pts.flatMap((_, i) => profile.slice(1).map((_, r) => [r * n + i, (r + 1) * n + i])),
   ];
   return { vertices, edges, faces, uvs, faceUVs };
 }
 
+/** Unit normal on the left of the edge a → b (inside, for a counter-clockwise outline). */
+function leftNormal(a, b) {
+  const dx = b.x - a.x, dy = b.y - a.y, l = Math.hypot(dx, dy) || 1;
+  return { x: -dy / l, y: dx / l };
+}
+
 /**
  * Scales a mesh along the X, Y, and Z axes.
  *
@@ -452,6 +519,7 @@ export function scaleMesh(mesh, sx = 1, sy = 1, sz = 1) {
     v.y *= sy;
     v.z *= sz;
   }
+  mesh.dirty = true; // so the WebGL renderer uploads the new positions
   return mesh;
 }
 

package/trid/render/webglRenderer.js

@@ -1,28 +1,28 @@
 import { DEFAULT_FOV, DEFAULT_NEAR } from "../math/transform.js";
+import { normalMatrix, determinantMat4 } from "../math/matrix.js";
+import { worldObjects } from "../sceneGraph.js";
 import { clear, edgeSegments, wireEdges } from "./draw.js";
 import { parseColor } from "./color.js";
 import { DEFAULT_LIGHT, DEFAULT_AMBIENT, materialsOf } from "./canvasRenderer.js";
 import { uvsFor, uvTransform, mappingKey } from "./uvMapping.js";
 import { newell, cornerNormals, creaseOf } from "./normals.js";
 import { SURFACE_GLSL, buildEffects, effectsKey } from "./effects.js";
-import { textureReady, textureSize, textureIsLive } from "../loaders/texture.js";
+import { textureReady, textureSize, textureIsLive, textureVersion } from "../loaders/texture.js";
 
 /** Farthest distance drawn by the WebGL renderer, unless the camera sets `far`. */
 export const DEFAULT_FAR = 1000;
 
-// Trid's transform pipeline, written in GLSL. It matches localToWorld,
-// worldToCamera and project() exactly, so tools and picking line up.
+// Trid's transform pipeline, written in GLSL. It matches the objects' world
+// matrices, worldToCamera and project() exactly, so tools and picking line up.
 const COMMON = `
-uniform vec3 uPos, uRot, uScale;
+uniform mat4 uModel; // the object's world matrix (its parents' transforms included)
 uniform vec3 uCamPos;
 uniform vec2 uCamRot; // yaw, pitch
 uniform float uF, uAspect, uNear, uFar;
 
 vec3 rotX(vec3 p, float a) { float c = cos(a), s = sin(a); return vec3(p.x, p.y * c - p.z * s, p.y * s + p.z * c); }
 vec3 rotY(vec3 p, float a) { float c = cos(a), s = sin(a); return vec3(p.x * c - p.z * s, p.y, p.x * s + p.z * c); }
-vec3 rotZ(vec3 p, float a) { float c = cos(a), s = sin(a); return vec3(p.x * c - p.y * s, p.x * s + p.y * c, p.z); }
-vec3 rotXYZ(vec3 p) { return rotZ(rotY(rotX(p, uRot.x), uRot.y), uRot.z); }
-vec3 toWorld(vec3 v) { return rotXYZ(v * uScale) + uPos; }
+vec3 toWorld(vec3 v) { return (uModel * vec4(v, 1.0)).xyz; }
 vec3 toCamera(vec3 p) { return rotX(rotY(p - uCamPos, uCamRot.x), uCamRot.y); }
 vec4 toClip(vec3 p) {
   float a = (uFar + uNear) / (uFar - uNear);
@@ -40,9 +40,10 @@ varying vec3 vWorld;
 varying vec3 vLocal;
 varying vec2 vUV;
 uniform mat3 uUVTransform; // textureRepeat, textureOffset, textureRotation
+uniform mat3 uNormalMatrix; // keeps normals right on stretched and mirrored objects
 ${COMMON}
 void main() {
-  vNormal = rotXYZ(aNormal / uScale); // inverse scale keeps normals right on stretched objects
+  vNormal = uNormalMatrix * aNormal;
   vLocal = aPos;
   vUV = (uUVTransform * vec3(aUV, 1.0)).xy;
   vWorld = toWorld(aPos);
@@ -108,7 +109,7 @@ ${fx.calls}
   return { source, uniforms: fx.uniforms };
 }
 
-const FACE_UNIFORMS = ["uUVTransform", "uLight", "uAmbient", "uShade", "uTime", "uBackground", "uCamWorld", "uTexture", "uUseTexture"];
+const FACE_UNIFORMS = ["uUVTransform", "uNormalMatrix", "uLight", "uAmbient", "uShade", "uTime", "uBackground", "uCamWorld", "uTexture", "uUseTexture"];
 
 // Each line segment is a thin rectangle facing the screen, `uWidth` pixels wide
 const LINE_VS = `
@@ -144,7 +145,7 @@ void main() {
 }
 `;
 
-const UNIFORMS = ["uPos", "uRot", "uScale", "uCamPos", "uCamRot", "uF", "uAspect", "uNear", "uFar", "uColor"];
+const UNIFORMS = ["uModel", "uCamPos", "uCamRot", "uF", "uAspect", "uNear", "uFar", "uColor"];
 
 /**
  * Draws a scene with WebGL, on the graphics card.
@@ -160,6 +161,12 @@ const UNIFORMS = ["uPos", "uRot", "uScale", "uCamPos", "uCamRot", "uF", "uAspect
  *
  * Meshes are sent to the graphics card once and reused. After changing
  * a mesh's vertices, edges or faces in place, set `mesh.dirty = true`.
+ * Textures are sent once too (videos every frame): after redrawing a canvas,
+ * call `updateTexture(canvas)`.
+ *
+ * Meshes and textures that haven't been drawn for `releaseAfter` frames
+ * are freed from the graphics card, so replacing them (`obj.mesh = newMesh`)
+ * doesn't fill its memory. They're sent again if they come back.
  *
  * @example
  * const scene = new Scene(canvas, { renderer: new WebGLRenderer() });
@@ -178,9 +185,13 @@ export class WebGLRenderer {
   /**
    * @param {Object} [opts]
    * @param {boolean} [opts.antialias=true] - Smooth edges
+   * @param {number} [opts.releaseAfter=300] - Free meshes and textures not drawn for this many frames
+   *   (about 5 s at 60 fps). `Infinity` keeps everything until `dispose()`
    * @throws {Error} If WebGL isn't available (check `WebGLRenderer.isSupported()` first)
    */
-  constructor({ antialias = true } = {}) {
+  constructor({ antialias = true, releaseAfter = 300 } = {}) {
+    /** Frames a mesh or texture can go undrawn before it's freed (Infinity: never). */
+    this.releaseAfter = releaseAfter;
     /** The hidden canvas WebGL draws on. */
     this.canvas = document.createElement("canvas");
     this._options = { antialias, alpha: true, premultipliedAlpha: true, depth: true };
@@ -210,6 +221,9 @@ export class WebGLRenderer {
     this._buffers = new Set();
     this._textures = new WeakMap(); // image / canvas / video → GL texture
     this._glTextures = new Set();
+    // Last frame each mesh / texture source was drawn, to free the ones no longer used
+    this._meshUse = new Map();
+    this._textureUse = new Map();
     this._warned = new WeakSet();
     this._frame = 0;
 
@@ -266,13 +280,17 @@ export class WebGLRenderer {
 
     // Opaque things first; see-through ones after, without writing depth
     const opaque = [], clear2 = [];
-    for (const obj of scene.objects) {
+    // Every object with a mesh, groups' children included, with its world matrix
+    const drawn = worldObjects(scene).filter((o) => o.mesh);
+    for (const obj of drawn) {
       const geo = this._geometry(obj.mesh);
       const lineColor = this._color(ctx, obj.color ?? scene.color);
       const lineWidth = obj.lineWidth ?? scene.lineWidth;
       const mats = materialsOf(obj);
 
       if (mats) {
+        // Normals turn with the object; a mirrored one has its faces' winding reversed
+        const place = { normals: normalMatrix(obj.world), mirrored: determinantMat4(obj.world) < 0 };
         // One draw per group of faces sharing a material (mesh.faceMaterials)
         const groups = geo.groups.map((g) => {
           const k = g.index >= 0 && g.index < mats.length && mats[g.index] ? g.index : 0;
@@ -280,7 +298,7 @@ export class WebGLRenderer {
         });
         for (const g of groups) {
           const fill = this._color(ctx, g.mat.fill ?? (g.mat.texture ? "#ffffff" : scene.color));
-          (fill[3] < 1 ? clear2 : opaque).push({ kind: "face", obj, geo, color: fill, mat: g.mat, first: g.first, count: g.count });
+          (fill[3] < 1 ? clear2 : opaque).push({ kind: "face", obj, geo, color: fill, mat: g.mat, first: g.first, count: g.count, place });
         }
         const lines = (buf) => (lineColor[3] < 1 ? clear2 : opaque).push({ kind: "line", obj, buf, color: lineColor, width: lineWidth });
         if (groups.every((g) => g.mat.wireframe)) lines(this._lineBuffer(geo, "outlines", () => outlinePairs(geo.faceList ?? [])));
@@ -300,7 +318,49 @@ export class WebGLRenderer {
     ctx.drawImage(this.canvas, 0, 0);
 
     // Meshes marked as changed have been sent again
-    for (const obj of scene.objects) if (obj.mesh.dirty) obj.mesh.dirty = false;
+    for (const obj of drawn) if (obj.mesh.dirty) obj.mesh.dirty = false;
+
+    if (this._frame % 60 === 0) this._sweep();
+  }
+
+  /**
+   * What the renderer keeps on the graphics card right now.
+   *
+   * @returns {{ meshes:number, buffers:number, textures:number }}
+   */
+  get memory() {
+    return { meshes: this._meshUse.size, buffers: this._buffers.size, textures: this._glTextures.size };
+  }
+
+  /**
+   * Frees a mesh's buffers or a texture's image on the graphics card now,
+   * instead of waiting for `releaseAfter`. If it's drawn again, it's sent again.
+   *
+   * @param {Object} item - A mesh, or a texture source (image, canvas, video)
+   */
+  release(item) {
+    if (!item || this._disposed) return;
+    const geo = this._meshes.get(item);
+    if (geo) {
+      for (const b of buffersOf(geo)) this._free(b);
+      this._meshes.delete(item);
+    }
+    this._meshUse.delete(item);
+    const t = this._textures.get(item);
+    if (t) {
+      this.gl.deleteTexture(t.tex);
+      this._glTextures.delete(t.tex);
+      this._textures.delete(item);
+    }
+    this._textureUse.delete(item);
+  }
+
+  /** Frees what hasn't been drawn for `releaseAfter` frames. */
+  _sweep() {
+    if (!(this.releaseAfter < Infinity)) return;
+    const oldest = this._frame - this.releaseAfter;
+    for (const [item, frame] of this._meshUse) if (frame < oldest) this.release(item);
+    for (const [item, frame] of this._textureUse) if (frame < oldest) this.release(item);
   }
 
   /** Frees the graphics card memory. The renderer can't be used afterwards. */
@@ -312,6 +372,8 @@ export class WebGLRenderer {
     for (const t of this._glTextures) gl.deleteTexture(t);
     this._glTextures.clear();
     this._buffers.clear();
+    this._meshUse.clear();
+    this._textureUse.clear();
     for (const p of new Set(this._faces.values())) gl.deleteProgram(p.program);
     gl.deleteProgram(this._line.program);
     gl.getExtension("WEBGL_lose_context")?.loseContext();
@@ -330,10 +392,7 @@ export class WebGLRenderer {
 
     gl.useProgram(prog.program);
     const u = prog.uniforms;
-    const { pos, rot, scale } = d.obj;
-    gl.uniform3f(u.uPos, pos.x, pos.y, pos.z);
-    gl.uniform3f(u.uRot, rot.x, rot.y, rot.z);
-    gl.uniform3f(u.uScale, scale.x, scale.y, scale.z);
+    gl.uniformMatrix4fv(u.uModel, false, d.obj.world);
     gl.uniform3fv(u.uCamPos, view.camPos);
     gl.uniform2fv(u.uCamRot, view.camRot);
     gl.uniform1f(u.uF, view.f);
@@ -348,6 +407,8 @@ export class WebGLRenderer {
     if (isFace) {
       const m = uvTransform(d.mat) ?? [1, 0, 0, 1, 0, 0];
       gl.uniformMatrix3fv(u.uUVTransform, false, [m[0], m[1], 0, m[2], m[3], 0, m[4], m[5], 1]);
+      gl.uniformMatrix3fv(u.uNormalMatrix, false, d.place.normals);
+      gl.frontFace(d.place.mirrored ? gl.CCW : gl.CW);
       gl.uniform3fv(u.uLight, light);
       gl.uniform1f(u.uAmbient, ambient);
       gl.uniform1f(u.uShade, d.mat.shade === false ? 0 : 1);
@@ -364,7 +425,7 @@ export class WebGLRenderer {
       if (a.aNormal >= 0) gl.vertexAttribPointer(a.aNormal, 3, gl.FLOAT, false, 32, 12);
       if (a.aUV >= 0) gl.vertexAttribPointer(a.aUV, 2, gl.FLOAT, false, 32, 24);
       const tex = d.mat.texture
-        ? this._texture(d.mat.texture, !!d.mat.pixelated, d.obj.mesh, !!uvsFor(d.obj.mesh, d.mat.mapping).faceUVs)
+        ? this._texture(d.mat.texture, d.mat, d.obj.mesh, !!uvsFor(d.obj.mesh, d.mat.mapping).faceUVs)
         : null;
       gl.activeTexture(gl.TEXTURE0);
       gl.bindTexture(gl.TEXTURE_2D, tex);
@@ -417,8 +478,9 @@ export class WebGLRenderer {
    * (canvases and videos: every frame). Null while it isn't ready,
    * or if the mesh has no texture coordinates.
    */
-  _texture(src, pixelated, mesh, hasUVs) {
+  _texture(src, mat, mesh, hasUVs) {
     const gl = this.gl;
+    const pixelated = !!mat.pixelated;
     if (!textureReady(src)) return null;
     if (!hasUVs) {
       if (!this._warned.has(mesh)) {
@@ -429,24 +491,29 @@ export class WebGLRenderer {
     }
 
     let t = this._textures.get(src);
-    const live = textureIsLive(src);
-    if (!t || live || t.failed) {
+    const live = textureIsLive(src, mat);
+    const version = textureVersion(src);
+    this._textureUse.set(src, this._frame);
+    // Sent once, then again after updateTexture(src), or every frame when live
+    if (!t || live || t.version !== version || t.failed) {
       if (t?.failed) return null;
       let { w, h } = textureSize(src);
       if (!t) {
-        t = { tex: gl.createTexture(), frame: -1 };
+        t = { tex: gl.createTexture(), frame: -1, version: -1 };
         this._textures.set(src, t);
         this._glTextures.add(t.tex);
       }
       if (t.frame !== this._frame) {
+        const changed = t.version !== version;
         t.frame = this._frame;
+        t.version = version;
         gl.bindTexture(gl.TEXTURE_2D, t.tex);
         // Bigger than the graphics card allows: upload a smaller copy
         let pixels = src;
         const max = gl.getParameter(gl.MAX_TEXTURE_SIZE);
         if (w > max || h > max) {
           const k = max / Math.max(w, h);
-          if (!t.small || live) t.small = shrink(src, Math.floor(w * k), Math.floor(h * k), t.small);
+          if (!t.small || live || changed) t.small = shrink(src, Math.floor(w * k), Math.floor(h * k), t.small);
           if (!t.warned) {
             t.warned = true;
             console.warn(`Trid: a ${w} × ${h} texture is bigger than this graphics card allows (${max}), so it's drawn at ${t.small.width} × ${t.small.height}`);
@@ -496,14 +563,13 @@ export class WebGLRenderer {
 
   /** Graphics card buffers for a mesh, built once and rebuilt when it changes. */
   _geometry(mesh) {
+    this._meshUse.set(mesh, this._frame);
     let geo = this._meshes.get(mesh);
     const stale = !geo || mesh.dirty || geo.vertices !== mesh.vertices || geo.faceList !== mesh.faces
       || geo.edgeList !== mesh.edges || geo.faceMats !== mesh.faceMaterials || geo.counts !== countsOf(mesh);
     if (!stale) return geo;
 
-    if (geo) {
-      for (const b of [...geo.lines.values(), ...geo.faceBuffers.values(), ...geo.groupOutlines.values()]) this._free(b);
-    }
+    if (geo) for (const b of buffersOf(geo)) this._free(b);
     const faces = mesh.faces ?? [];
 
     // Faces grouped by material index, in the order the face buffers store them
@@ -631,6 +697,11 @@ export class WebGLRenderer {
   }
 }
 
+/** Every graphics card buffer of a mesh's geometry. */
+function buffersOf(geo) {
+  return [...geo.lines.values(), ...geo.faceBuffers.values(), ...geo.groupOutlines.values()];
+}
+
 /** A short string that changes when a mesh's arrays grow or shrink. */
 function countsOf(mesh) {
   return `${mesh.vertices.length}/${mesh.edges?.length ?? 0}/${mesh.faces?.length ?? 0}`;

package/trid/scene.js

@@ -1,6 +1,7 @@
 import { CanvasRenderer, DEFAULT_LIGHT, DEFAULT_AMBIENT } from "./render/canvasRenderer.js";
 import { loop } from "./render/loop.js";
 import { ToolManager } from "./tools/manager.js";
+import { linkTree } from "./sceneGraph.js";
 import { screenshot, record } from "./export/capture.js";
 
 /**
@@ -71,27 +72,37 @@ export class Scene {
   }
 
   /**
-   * Adds an object to the scene, filling in missing transform fields.
+   * Adds an object to the scene, filling in missing transform fields
+   * (down its `children` too).
    *
-   * @param {{ mesh:{ vertices:{x:number,y:number,z:number}[], edges:number[][] } }} obj - Mesh instance
+   * An object can be a group: give it `children`, objects placed relative
+   * to it, and leave out `mesh` if it's only there to hold them. Moving it
+   * moves them all. See `trid/sceneGraph.js`.
+   *
+   * @example
+   * const car = scene.add({ children: [{ mesh: body }, { mesh: wheel, pos: { x: 0.4, y: -0.2, z: 0 } }] });
+   * car.pos.x += 0.1; // the body and the wheel move together
+   *
+   * @param {Object} obj - An object: `mesh` and/or `children`, plus pos, rot, scale, material...
    * @returns The same object, so it can be kept and animated
    */
   add(obj) {
-    obj.pos ??= { x: 0, y: 0, z: 0 };
-    obj.rot ??= { x: 0, y: 0, z: 0 };
-    obj.scale ??= { x: 1, y: 1, z: 1 };
+    linkTree(obj, null);
     this.objects.push(obj);
     return obj;
   }
 
   /**
-   * Removes an object from the scene. Does nothing if it isn't in it.
+   * Removes an object: from the scene's top level, or from its group's
+   * `children`. Its own children go with it. Does nothing if it isn't there.
    *
-   * @param {Object} obj - Object previously passed to `add`
+   * @param {Object} obj - Object previously added (or a child of one)
    */
   remove(obj) {
-    const i = this.objects.indexOf(obj);
-    if (i !== -1) this.objects.splice(i, 1);
+    const list = obj.parent ? obj.parent.children : this.objects;
+    const i = list?.indexOf(obj) ?? -1;
+    if (i !== -1) list.splice(i, 1);
+    if (obj.parent) obj.parent = null;
   }
 
   /**

package/trid/sceneGraph.js

@@ -0,0 +1,131 @@
+import { mat4FromTransform, mulMat4, transformPoint } from "./math/matrix.js";
+
+/**
+ * Groups: any object can have `children`, placed relative to it. An object
+ * without a `mesh` is just a group. Moving, turning or scaling an object
+ * moves its whole subtree.
+ *
+ *   const sword = scene.add({ pos, children: [
+ *     { mesh: blade },
+ *     { name: "hilt", children: [{ mesh: guard }, { mesh: grip, pos: { x: 0, y: -0.12, z: 0 } }] },
+ *   ] });
+ *   sword.rot.y += dt; // everything turns
+ *
+ * `children` is a plain array, read every frame: push and splice freely.
+ * Each object gets two read-only-by-convention fields, kept up to date every
+ * frame (and set right away by `scene.add`):
+ * - `parent`: the object it's a child of, or null at the top
+ * - `world`: its world matrix (parent's world matrix × its own transform)
+ * Both are non-enumerable, so they don't show up in JSON or `{ ...obj }`.
+ *
+ * `visible: false` hides an object and everything under it.
+ */
+
+/** Sets a field without making it enumerable (keeps objects clean for JSON and spreads). */
+function hidden(obj, key, value) {
+  if (Object.prototype.hasOwnProperty.call(obj, key)) obj[key] = value;
+  else Object.defineProperty(obj, key, { value, writable: true, configurable: true, enumerable: false });
+}
+
+/** Fills missing transform fields, like `scene.add` does. */
+function fill(obj) {
+  obj.pos ??= { x: 0, y: 0, z: 0 };
+  obj.rot ??= { x: 0, y: 0, z: 0 };
+  obj.scale ??= { x: 1, y: 1, z: 1 };
+}
+
+/**
+ * An object's world matrix, worked out now from its own transform and its
+ * parents' (following `obj.parent`). Use it between frames, after changing
+ * a transform; renderers keep `obj.world` up to date on their own.
+ *
+ * @param {Object} obj - A scene object
+ * @returns {number[]} 4×4 matrix (see `trid/math/matrix.js`)
+ */
+export function worldMatrix(obj) {
+  const own = mat4FromTransform(obj);
+  return obj.parent ? mulMat4(worldMatrix(obj.parent), own) : own;
+}
+
+/**
+ * Where an object's origin is in the world, now (with its parents).
+ *
+ * @param {Object} obj - A scene object
+ * @returns {{x:number, y:number, z:number}}
+ */
+export function worldPosition(obj) {
+  return transformPoint(worldMatrix(obj), { x: 0, y: 0, z: 0 });
+}
+
+/**
+ * Calls `fn(obj, world)` for every visible object under some roots, parents
+ * before children, with each one's world matrix. Changes nothing: objects
+ * don't need to be in a scene.
+ *
+ * @param {Object[]} roots - Top objects
+ * @param {(root:Object) => number[]|null} baseOf - Matrix a root's own transform goes under (null: none)
+ * @param {(obj:Object, world:number[], parent:Object|null) => void} fn
+ */
+export function forEachPlaced(roots, baseOf, fn) {
+  const visit = (obj, parent, parentWorld) => {
+    if (!obj || typeof obj !== "object") return;
+    const world = parentWorld ? mulMat4(parentWorld, mat4FromTransform(obj)) : mat4FromTransform(obj);
+    if (obj.visible === false) return;
+    fn(obj, world, parent);
+    if (Array.isArray(obj.children)) for (const child of obj.children) visit(child, obj, world);
+  };
+  for (const root of roots) visit(root, root?.parent ?? null, baseOf(root));
+}
+
+/**
+ * Every visible object of a scene (or of a list of objects and their
+ * subtrees), parents before their children, with `parent` and `world` set
+ * and missing transforms filled in. Groups without a mesh are included;
+ * renderers skip them.
+ *
+ * Objects given in a list keep their place in the scene: an object that is
+ * a child of a group still gets its parents' transforms.
+ *
+ * @param {Object|Object[]} input - A Scene, a scene object or a list of them
+ * @returns {Object[]} The objects, flattened
+ */
+export function worldObjects(input) {
+  const roots = Array.isArray(input) ? input : Array.isArray(input?.objects) ? input.objects : input ? [input] : [];
+  // The scene's own list is the top: those have no parent
+  if (roots === input?.objects) for (const obj of roots) if (obj && obj.parent) hidden(obj, "parent", null);
+  const out = [];
+  forEachPlaced(roots, (root) => (root.parent ? worldMatrix(root.parent) : null), (obj, world, parent) => {
+    fill(obj);
+    if (obj.parent !== parent) hidden(obj, "parent", parent);
+    hidden(obj, "world", world);
+    out.push(obj);
+  });
+  // Hidden objects still get their links (so a hidden group's children know their parent)
+  for (const root of roots) if (root?.visible === false) linkTree(root, root.parent ?? null);
+  return out;
+}
+
+/**
+ * Sets `parent` links and fills transforms down a subtree, right away.
+ * `scene.add` calls it, so `obj.parent` works before the first frame.
+ *
+ * @param {Object} obj
+ * @param {Object|null} [parent=null]
+ */
+export function linkTree(obj, parent = null) {
+  fill(obj);
+  if (obj.parent !== parent) hidden(obj, "parent", parent);
+  if (Array.isArray(obj.children)) for (const child of obj.children) linkTree(child, obj);
+}
+
+/**
+ * The chain from an object up to the top of its tree: `[obj, parent, ..., root]`.
+ *
+ * @param {Object} obj
+ * @returns {Object[]}
+ */
+export function ancestors(obj) {
+  const path = [];
+  for (let o = obj; o; o = o.parent) path.push(o);
+  return path;
+}