trid3d 0.1.1 → 0.2.0

package/trid/render/canvasRenderer.js

@@ -1,11 +1,26 @@
 import { localToWorld, worldToCamera, cameraToScreen, clipNear, rotateXYZ, DEFAULT_NEAR } from "../math/transform.js";
-import { clear, drawInstance, edgeSegments } from "./draw.js";
+import { clear, drawInstance, edgeSegments, wireEdges } from "./draw.js";
 import { parseColor } from "./color.js";
 import { newell, cornerNormals, creaseOf } from "./normals.js";
 import { textureReady, textureSize, textureIsLive } from "../loaders/texture.js";
+import { uvsFor, uvTransform, applyUVTransform } from "./uvMapping.js";
 
 export { newell };
 
+/**
+ * An object's materials as a list (`material` can be one material or a
+ * list of them, picked per face by `mesh.faceMaterials`). Null when the
+ * object is a wireframe.
+ *
+ * @returns {Material[]|null}
+ */
+export function materialsOf(obj) {
+  const m = obj.material;
+  if (!m) return null;
+  if (!Array.isArray(m)) return [m];
+  return m.length && m[0] ? m : null;
+}
+
 /** Direction light comes from when the scene doesn't set one: above, left, in front. */
 export const DEFAULT_LIGHT = { x: -0.5, y: 1, z: -0.8 };
 
@@ -16,6 +31,10 @@ export const DEFAULT_AMBIENT = 0.25;
  * Material: how an object's faces look. Objects without one are drawn
  * as wireframes using their `color` and `lineWidth`.
  *
+ * An object's `material` can also be a list: each face then uses the
+ * entry `mesh.faceMaterials[face]` points at (the first one by default).
+ * Built-in cubes and boxes number their sides 0 to 5.
+ *
  * @typedef {Object} Material
  * @property {string} [fill] - Face color, any CSS color (default: the scene's color)
  * @property {boolean} [shade=true] - Darken faces that turn away from the light
@@ -26,6 +45,11 @@ export const DEFAULT_AMBIENT = 0.25;
  * @property {CanvasImageSource} [texture] - Image drawn on the faces (needs texture coordinates:
  *   built-in shapes and OBJ files with `vt` have them). `fill` tints it (default white).
  * @property {boolean} [pixelated=false] - Keep texture pixels sharp instead of smoothing them
+ * @property {import("./uvMapping.js").Mapping} [mapping="uv"] - Where texture coordinates come
+ *   from: the mesh's own ("uv"), or made from its shape ("planar", "box", "sphere", "cylinder")
+ * @property {number|{u:number,v:number}} [textureRepeat=1] - How many times the image repeats across
+ * @property {{u:number,v:number}} [textureOffset] - Moves the image (1 = its whole width or height)
+ * @property {number} [textureRotation=0] - Turns the image around its center, in radians
  * @property {Object[]} [effects] - Effects applied in order, like `[toon(), rim()]`.
  *   See trid/render/effects.js. The canvas renderer runs them once per face.
  */
@@ -79,7 +103,7 @@ export class CanvasRenderer {
     this._frame++;
 
     // Wireframes only: nothing to sort
-    if (!scene.objects.some((o) => o.material)) {
+    if (!scene.objects.some((o) => materialsOf(o))) {
       for (const obj of scene.objects) {
         drawInstance(ctx, obj, camera, w, h, obj.color ?? scene.color, obj.lineWidth ?? scene.lineWidth);
       }
@@ -97,17 +121,17 @@ export class CanvasRenderer {
     const background = this._rgba(ctx, scene.background);
 
     for (const obj of scene.objects) {
+      const mats = materialsOf(obj);
       // Split big faces (cached per mesh); extra vertices are midpoints of existing ones
-      const split = obj.material && this.maxFaceSize ? this._split(obj.mesh) : null;
+      const split = mats && this.maxFaceSize ? this._split(obj.mesh) : null;
       const verts = split ? withMidpoints(obj.mesh.vertices, split.mids) : obj.mesh.vertices;
       const world = verts.map((v) => localToWorld(v, obj));
       const cam = world.map((p) => worldToCamera(p, camera));
       const color = obj.color ?? scene.color;
       const lineWidth = obj.lineWidth ?? scene.lineWidth;
-      const mat = obj.material;
 
-      if (!mat) {
-        for (const [i, j] of edgeSegments(obj.mesh.edges)) {
+      if (!mats) {
+        for (const [i, j] of edgeSegments(wireEdges(obj.mesh))) {
           const seg = clipNear(cam[i], cam[j], near);
           if (!seg) continue;
           items.push({
@@ -119,19 +143,14 @@ export class CanvasRenderer {
         continue;
       }
 
-      const fill = mat.fill ?? (mat.texture ? "#ffffff" : scene.color);
-      const shade = mat.shade !== false;
-      const outline = mat.wireframe ? color : null;
-
-      // Smooth shading: a normal per face corner (split faces get midpoints' normals by averaging)
-      const crease = shade ? creaseOf(mat.smooth) : null;
-      const corners = crease ? cornerNormals(obj.mesh, crease) : null;
       const sourceFaces = obj.mesh.faces ?? [];
       const base = obj.mesh.vertices.length;
-      const normalAt = (F, i) => {
+
+      // Smooth shading: a normal per face corner (split faces get midpoints' normals by averaging)
+      const normalAt = (corners, F, i) => {
         if (i < base) return corners[F][sourceFaces[F].indexOf(i)];
         const [a, b] = split.mids[i - base];
-        const na = normalAt(F, a), nb = normalAt(F, b);
+        const na = normalAt(corners, F, a), nb = normalAt(corners, F, b);
         return normalize({ x: na.x + nb.x, y: na.y + nb.y, z: na.z + nb.z });
       };
       const lightAt = (n, back) => {
@@ -140,47 +159,69 @@ export class CanvasRenderer {
         const d = (back ? -1 : 1) * (r.x * light.x + r.y * light.y + r.z * light.z);
         return ambient + (1 - ambient) * Math.max(0, d);
       };
-
-      // Textures: each triangle is filled with the image, mapped by its corners' texture coordinates
-      const meshUVs = obj.mesh.uvs, faceUVs = obj.mesh.faceUVs;
-      let tex = null;
-      if (mat.texture && textureReady(mat.texture)) {
-        if (faceUVs && meshUVs) tex = mat.texture;
-        else if (!this._warned.has(obj.mesh)) {
-          this._warned.add(obj.mesh);
-          console.warn("Trid: this mesh has no texture coordinates (uvs / faceUVs), so its texture isn't drawn");
-        }
-      }
-      const uvAt = (F, i) => {
-        const t = faceUVs?.[F];
-        if (!t || !meshUVs) return null;
-        if (i < base) return meshUVs[t[sourceFaces[F].indexOf(i)]];
-        const [a, b] = split.mids[i - base];
-        const ta = uvAt(F, a), tb = uvAt(F, b);
-        return ta && tb ? { u: (ta.u + tb.u) / 2, v: (ta.v + tb.v) / 2 } : null;
-      };
       const flatLight = (face, back) => {
         const nw = normalize(newell(face.map((i) => world[i])));
         const d = (back ? -1 : 1) * (nw.x * light.x + nw.y * light.y + nw.z * light.z);
         return ambient + (1 - ambient) * Math.max(0, d);
       };
-
-      // Effects run once per face, at its center (see trid/render/effects.js)
-      const effects = mat.effects?.length ? mat.effects : null;
       const toWorldNormal = (n) =>
         normalize(rotateXYZ({ x: n.x / obj.scale.x, y: n.y / obj.scale.y, z: n.z / obj.scale.z }, obj.rot));
 
+      // Everything a material needs, worked out once per object and frame
+      const prepare = (mat) => {
+        const shade = mat.shade !== false;
+        const crease = shade ? creaseOf(mat.smooth) : null;
+        // Texture coordinates: the mesh's own, or made from its shape (mat.mapping)
+        const { uvs: meshUVs, faceUVs } = uvsFor(obj.mesh, mat.mapping);
+        const xf = uvTransform(mat);
+        const rawUV = (F, i) => {
+          const t = faceUVs?.[F];
+          if (!t || !meshUVs) return null;
+          if (i < base) return meshUVs[t[sourceFaces[F].indexOf(i)]];
+          const [a, b] = split.mids[i - base];
+          const ta = rawUV(F, a), tb = rawUV(F, b);
+          return ta && tb ? { u: (ta.u + tb.u) / 2, v: (ta.v + tb.v) / 2 } : null;
+        };
+        let tex = null;
+        if (mat.texture && textureReady(mat.texture)) {
+          if (faceUVs && meshUVs) tex = mat.texture;
+          else if (!this._warned.has(obj.mesh)) {
+            this._warned.add(obj.mesh);
+            console.warn("Trid: this mesh has no texture coordinates (uvs / faceUVs), so its texture isn't drawn. Set material.mapping to make some.");
+          }
+        }
+        return {
+          mat, shade, tex,
+          fill: mat.fill ?? (mat.texture ? "#ffffff" : scene.color),
+          outline: mat.wireframe ? color : null,
+          corners: crease ? cornerNormals(obj.mesh, crease) : null,
+          effects: mat.effects?.length ? mat.effects : null,
+          uvAt: (F, i) => applyUVTransform(xf, rawUV(F, i)),
+        };
+      };
+      // Which material each face uses (mesh.faceMaterials), prepared when first needed
+      const looks = new Array(mats.length);
+      const faceMats = obj.mesh.faceMaterials;
+      const lookOf = (F) => {
+        let k = faceMats?.[F] ?? 0;
+        if (!(k >= 0 && k < mats.length && mats[k])) k = 0;
+        return (looks[k] ??= prepare(mats[k]));
+      };
+
       const faces = split ? split.faces : sourceFaces;
       for (let f = 0; f < faces.length; f++) {
         const face = faces[f];
         if (face.length < 3) continue;
+        const F = split ? split.origins[f] : f; // the mesh face this one comes from
+        const L = lookOf(F);
+        const { fill, shade, outline, corners } = L;
         const pts = face.map((i) => cam[i]);
 
         // Seen from behind? (camera sits at the origin of camera space)
         const n = newell(pts);
         const c = centroid(pts);
         const back = n.x * c.x + n.y * c.y + n.z * c.z >= 0;
-        if (back && !mat.doubleSided) continue;
+        if (back && !L.mat.doubleSided) continue;
 
         const clipped = clipPolygon(pts, near);
         if (clipped.length < 3) continue;
@@ -188,13 +229,13 @@ export class CanvasRenderer {
         // Which edges are real outlines (split faces have extra inner edges); null = all
         const edges = split && clipped === pts ? split.masks[f] : null;
 
-        if (tex && clipped === pts) {
-          const F = split ? split.origins[f] : f;
-          const ts = face.map((i) => uvAt(F, i));
+        // Textures: each triangle is filled with the image, mapped by its corners' texture coordinates
+        if (L.tex && clipped === pts) {
+          const ts = face.map((i) => L.uvAt(F, i));
           if (ts.every(Boolean)) {
             let lit;
             if (!shade) lit = face.map(() => 1);
-            else if (corners) lit = face.map((i) => lightAt(normalAt(F, i), back));
+            else if (corners) lit = face.map((i) => lightAt(normalAt(corners, F, i), back));
             else lit = face.map(() => flatLight(face, back));
             const screen = pts.map(toScreen);
             const n = face.length;
@@ -203,7 +244,7 @@ export class CanvasRenderer {
               items.push({
                 depth: c.z,
                 poly: [screen[0], screen[k], screen[k + 1]],
-                texture: { src: tex, uvs: [ts[0], ts[k], ts[k + 1]], pixelated: !!mat.pixelated, tint: fill },
+                texture: { src: L.tex, uvs: [ts[0], ts[k], ts[k + 1]], pixelated: !!L.mat.pixelated, tint: fill },
                 lit: [lit[0], lit[k], lit[k + 1]],
                 outline, lineWidth,
                 edges: n === 3 ? edges : fan,
@@ -213,12 +254,12 @@ export class CanvasRenderer {
           }
         }
 
-        if (effects) {
+        // Effects run once per face, at its center (see trid/render/effects.js)
+        if (L.effects) {
           // Normal: the face's own, or the average of its corners when smooth
           let nw;
           if (corners) {
-            const F = split ? split.origins[f] : f;
-            const sum = face.map((i) => toWorldNormal(normalAt(F, i)))
+            const sum = face.map((i) => toWorldNormal(normalAt(corners, F, i)))
               .reduce((a, b) => ({ x: a.x + b.x, y: a.y + b.y, z: a.z + b.z }), { x: 0, y: 0, z: 0 });
             nw = normalize(sum);
           } else {
@@ -230,16 +271,16 @@ export class CanvasRenderer {
           const toCam = { x: camPos.x - position.x, y: camPos.y - position.y, z: camPos.z - position.z };
           const diffuse = Math.max(0, nw.x * light.x + nw.y * light.y + nw.z * light.z);
           const lit = shade ? ambient + (1 - ambient) * diffuse : 1;
-          const base = this._rgba(ctx, fill);
+          const rgba = this._rgba(ctx, fill);
           const s = {
-            base, normal: nw, position, local: centroid(face.map((i) => verts[i])),
+            base: rgba, normal: nw, position, local: centroid(face.map((i) => verts[i])),
             view: normalize(toCam), lightDir: light, diffuse, light: lit, ambient,
-            uv: centerUV(face.map((i) => uvAt(split ? split.origins[f] : f, i))),
+            uv: centerUV(face.map((i) => L.uvAt(F, i))),
             depth: Math.hypot(toCam.x, toCam.y, toCam.z), time, background,
             rgba: (v) => (typeof v === "string" ? this._rgba(ctx, v) : Array.isArray(v) ? v : [v.x, v.y, v.z, 1]),
           };
-          let col = [base[0] * lit, base[1] * lit, base[2] * lit, base[3]];
-          for (const e of effects) if (e.canvas) col = e.canvas(col, s, e.uniforms ?? {});
+          let col = [rgba[0] * lit, rgba[1] * lit, rgba[2] * lit, rgba[3]];
+          for (const e of L.effects) if (e.canvas) col = e.canvas(col, s, e.uniforms ?? {});
           const k = col.map((x) => Math.min(1, Math.max(0, x)));
           items.push({
             depth: c.z,
@@ -251,8 +292,7 @@ export class CanvasRenderer {
         }
 
         if (corners) {
-          const F = split ? split.origins[f] : f;
-          const lit = face.map((i) => lightAt(normalAt(F, i), back));
+          const lit = face.map((i) => lightAt(normalAt(corners, F, i), back));
           if (clipped === pts) {
             // One gradient per triangle: brightness changes linearly across a triangle
             const screen = pts.map(toScreen);
@@ -276,14 +316,7 @@ export class CanvasRenderer {
           continue;
         }
 
-        let brightness = 1;
-        if (shade) {
-          const nw = normalize(newell(face.map((i) => world[i])));
-          const s = back ? -1 : 1;
-          const d = s * (nw.x * light.x + nw.y * light.y + nw.z * light.z);
-          brightness = ambient + (1 - ambient) * Math.max(0, d);
-        }
-
+        const brightness = shade ? flatLight(face, back) : 1;
         items.push({
           depth: c.z,
           poly: clipped.map(toScreen),

package/trid/render/draw.js

@@ -59,11 +59,11 @@ export function line(ctx, p1, p2, color, width = 4) {
  * - An edge with 3+ indices is a closed loop: the last index
  *   connects back to the first
  *
- * @param {number[][]} edges - Edge definitions using vertex indices
+ * @param {number[][]} [edges] - Edge definitions using vertex indices (none: no segments)
  * @returns {Generator<[number, number]>} Index pairs to connect
  */
 export function* edgeSegments(edges) {
-  for (const e of edges) {
+  for (const e of edges ?? []) {
     const closed = e.length > 2;
     const count = closed ? e.length : e.length - 1;
     for (let i = 0; i < count; i++) {
@@ -72,6 +72,17 @@ export function* edgeSegments(edges) {
   }
 }
 
+/**
+ * The lines to draw for a mesh shown as a wireframe: its `edges`, or the
+ * outline of each face when it has no `edges` (a face-only mesh).
+ *
+ * @param {{ edges?: number[][], faces?: number[][] }} mesh
+ * @returns {number[][]} Edge definitions (faces are closed loops)
+ */
+export function wireEdges(mesh) {
+  return mesh.edges ?? mesh.faces ?? [];
+}
+
 /**
  * Draws a wireframe object by connecting projected vertices
  * using index-based edge definitions.
@@ -115,7 +126,7 @@ export function drawWireframe(ctx, points2, edges, color, width = 4) {
  *
  * @param {CanvasRenderingContext2D} ctx - Canvas 2D context
  * @param {{
- *   mesh:{ vertices:{x:number,y:number,z:number}[], edges:number[][] },
+ *   mesh:{ vertices:{x:number,y:number,z:number}[], edges?:number[][], faces?:number[][] },
  *   pos:{x:number,y:number,z:number},
  *   rot:{x:number,y:number,z:number},
  *   scale:{x:number,y:number,z:number}
@@ -134,7 +145,7 @@ export function drawInstance(ctx, inst, camera, w, h, color, lineWidth = 3) {
   ctx.strokeStyle = color;
 
   ctx.beginPath();
-  for (const [i, j] of edgeSegments(inst.mesh.edges)) {
+  for (const [i, j] of edgeSegments(wireEdges(inst.mesh))) {
     const seg = clipNear(ptsCam[i], ptsCam[j], near);
     if (!seg) continue;
     const a = cameraToScreen(seg[0], camera, w, h);

package/trid/render/shapes.js

@@ -45,6 +45,8 @@ function rectPrismWire(w = 0.6, h = 0.3, d = 0.4) {
       [0, 3, 7, 4], // right
       [1, 5, 6, 2], // left
     ],
+    // Which material each face uses when `material` is a list: one per side, in the order above
+    faceMaterials: [0, 1, 2, 3, 4, 5],
   };
   return withFaceUVs(mesh);
 }
@@ -161,6 +163,268 @@ function sphereWire(radius = 0.35, rings = 10, segments = 16) {
   return { vertices, edges, faces, uvs, faceUVs };
 }
 
+/**
+ * Spins a profile around the Y axis: vases, bottles, cups, columns, chess
+ * pieces. Cylinders, cones and tori are built with it.
+ *
+ * Walk the profile so the outside is on its right in the (r, y) plane:
+ * bottom to top for a vase. Faces are clockwise as seen from outside.
+ *
+ * Texture coordinates: u goes around, v follows the profile's length.
+ * Caps map the texture as a disc. Edges are the profile's rings plus one
+ * line along the profile per segment.
+ *
+ * @example
+ * // A vase
+ * const vase = lathe(
+ *   [{ r: 0.2, y: -0.5 }, { r: 0.35, y: -0.2 }, { r: 0.15, y: 0.3 }, { r: 0.2, y: 0.5 }],
+ *   { capBottom: true },
+ * );
+ *
+ * @param {{r:number, y:number}[]} profile - Points: distance from the Y axis and height
+ * @param {Object} [opts]
+ * @param {number} [opts.segments=32] - Points around the axis
+ * @param {boolean} [opts.capBottom=false] - Close the bottom with a flat cap
+ * @param {boolean} [opts.capTop=false] - Close the top with a flat cap
+ * @param {boolean} [opts.closed=false] - The last point joins the first (torus-like shapes)
+ * @returns {import("../index.d.ts").Mesh}
+ */
+export function lathe(profile, { segments = 32, capBottom = false, capTop = false, closed = false } = {}) {
+  segments = Math.max(3, Math.floor(segments));
+  const vertices = [];
+  const edges = [];
+  const faces = [];
+  const uvs = [];
+  const faceUVs = [];
+  const uv = (u, v) => uvs.push({ u, v }) - 1;
+
+  // v along the profile, by length
+  const pts = closed ? [...profile, profile[0]] : profile;
+  const lengths = [0];
+  for (let i = 1; i < pts.length; i++) {
+    lengths.push(lengths[i - 1] + Math.hypot(pts[i].r - pts[i - 1].r, pts[i].y - pts[i - 1].y));
+  }
+  const total = lengths[lengths.length - 1] || 1;
+
+  for (const p of profile) {
+    for (let s = 0; s < segments; s++) {
+      const t = (s / segments) * Math.PI * 2;
+      vertices.push({ x: Math.cos(t) * p.r, y: p.y, z: Math.sin(t) * p.r });
+    }
+  }
+
+  const rows = pts.length - 1;
+  for (let r = 0; r < rows; r++) {
+    const a = r * segments;
+    const b = ((r + 1) % profile.length) * segments;
+    for (let s = 0; s < segments; s++) {
+      const s1 = (s + 1) % segments;
+      faces.push([a + s, b + s, b + s1, a + s1]);
+      const u0 = s / segments, u1 = (s + 1) / segments;
+      const v0 = lengths[r] / total, v1 = lengths[r + 1] / total;
+      faceUVs.push([uv(u0, v0), uv(u0, v1), uv(u1, v1), uv(u1, v0)]);
+    }
+  }
+
+  // Rings (skipped where the profile touches the axis) and lines along the profile
+  profile.forEach((p, r) => {
+    if (p.r > 1e-5) edges.push(Array.from({ length: segments }, (_, s) => r * segments + s));
+  });
+  for (let s = 0; s < segments; s++) {
+    if (closed && profile.length > 2) edges.push(profile.map((_, r) => r * segments + s));
+    else for (let r = 0; r < profile.length - 1; r++) edges.push([r * segments + s, (r + 1) * segments + s]);
+  }
+
+  const disc = (s) => {
+    const t = (s / segments) * Math.PI * 2;
+    return uv(0.5 + Math.cos(t) * 0.5, 0.5 + Math.sin(t) * 0.5);
+  };
+  if (capBottom && !closed && profile[0].r > 0) {
+    const c = vertices.push({ x: 0, y: profile[0].y, z: 0 }) - 1;
+    for (let s = 0; s < segments; s++) {
+      faces.push([c, s, (s + 1) % segments]);
+      faceUVs.push([uv(0.5, 0.5), disc(s), disc(s + 1)]);
+    }
+  }
+  const last = profile.length - 1;
+  if (capTop && !closed && profile[last].r > 0) {
+    const c = vertices.push({ x: 0, y: profile[last].y, z: 0 }) - 1;
+    const a = last * segments;
+    for (let s = 0; s < segments; s++) {
+      faces.push([c, a + (s + 1) % segments, a + s]);
+      faceUVs.push([uv(0.5, 0.5), disc(s + 1), disc(s)]);
+    }
+  }
+
+  return { vertices, edges, faces, uvs, faceUVs };
+}
+
+/** A capped cylinder along Y, centered on the origin. */
+function cylinder(r = 0.3, h = 0.8, segments = 32) {
+  return lathe([{ r, y: -h / 2 }, { r, y: h / 2 }], { segments, capBottom: true, capTop: true });
+}
+
+/** A cone along Y with its tip up, or a tapered cylinder when `rTop` > 0. */
+function cone(r = 0.35, h = 0.8, segments = 32, rTop = 0) {
+  // A tiny top ring keeps the tip's faces non-degenerate for UVs and normals
+  const profile = [{ r, y: -h / 2 }, { r: rTop > 0 ? rTop : 1e-6, y: h / 2 }];
+  return lathe(profile, { segments, capBottom: true, capTop: rTop > 0 });
+}
+
+/** A ring in the XZ plane: `R` from the center to the middle of the tube. */
+function torus(R = 0.35, tube = 0.12, segments = 48, tubeSegments = 20) {
+  tubeSegments = Math.max(3, Math.floor(tubeSegments));
+  const profile = [];
+  for (let i = 0; i < tubeSegments; i++) {
+    const p = (i / tubeSegments) * Math.PI * 2;
+    profile.push({ r: R + Math.cos(p) * tube, y: Math.sin(p) * tube });
+  }
+  return lathe(profile, { segments, closed: true });
+}
+
+/**
+ * A flat grid in the XZ plane facing +Y, `size` wide, with `div` cells per
+ * side. `height(x, z)` lifts each vertex (terrain). The texture covers the
+ * whole grid once.
+ */
+function plane(size = 1, div = 8, height = null) {
+  div = Math.max(1, Math.floor(div));
+  const vertices = [];
+  const uvs = [];
+  const n = div + 1;
+  const k = (i, j) => j * n + i;
+  for (let j = 0; j < n; j++) {
+    for (let i = 0; i < n; i++) {
+      const x = (i / div - 0.5) * size, z = (j / div - 0.5) * size;
+      vertices.push({ x, y: height ? height(x, z) : 0, z });
+      uvs.push({ u: i / div, v: j / div });
+    }
+  }
+  const faces = [];
+  const edges = [];
+  for (let j = 0; j < div; j++) {
+    for (let i = 0; i < div; i++) faces.push([k(i + 1, j + 1), k(i + 1, j), k(i, j), k(i, j + 1)]);
+  }
+  for (let j = 0; j < n; j++) {
+    for (let i = 0; i < div; i++) {
+      edges.push([k(i, j), k(i + 1, j)]);
+      edges.push([k(j, i), k(j, i + 1)]);
+    }
+  }
+  // Grid vertices and UVs share indices
+  return { vertices, edges, faces, uvs, faceUVs: faces.map((f) => [...f]) };
+}
+
+/** Twice the signed area: > 0 when the points go counter-clockwise (x right, y up). */
+function signedArea(pts) {
+  let a = 0;
+  for (let i = 0; i < pts.length; i++) {
+    const p = pts[i], q = pts[(i + 1) % pts.length];
+    a += p.x * q.y - q.x * p.y;
+  }
+  return a;
+}
+
+/**
+ * Cuts a simple polygon (no holes, sides don't cross) into triangles, by
+ * ear clipping. Works for concave outlines. Falls back to a fan if the
+ * outline crosses itself.
+ *
+ * @param {{x:number, y:number}[]} pts - The outline, counter-clockwise (x right, y up)
+ * @returns {number[][]} Index triples into `pts`, counter-clockwise too
+ */
+export function triangulate(pts) {
+  const idx = pts.map((_, i) => i);
+  const tris = [];
+  const cross = (a, b, c) => (b.x - a.x) * (c.y - a.y) - (b.y - a.y) * (c.x - a.x);
+  const inside = (p, a, b, c) => cross(a, b, p) >= 0 && cross(b, c, p) >= 0 && cross(c, a, p) >= 0;
+
+  let guard = idx.length * idx.length;
+  while (idx.length > 3 && guard-- > 0) {
+    let clipped = false;
+    for (let i = 0; i < idx.length; i++) {
+      const i0 = idx[(i + idx.length - 1) % idx.length], i1 = idx[i], i2 = idx[(i + 1) % idx.length];
+      const a = pts[i0], b = pts[i1], c = pts[i2];
+      if (cross(a, b, c) <= 1e-12) continue; // reflex or flat corner
+      if (idx.some((j) => j !== i0 && j !== i1 && j !== i2 && inside(pts[j], a, b, c))) continue;
+      tris.push([i0, i1, i2]);
+      idx.splice(i, 1);
+      clipped = true;
+      break;
+    }
+    if (!clipped) break;
+  }
+  if (idx.length === 3) tris.push([idx[0], idx[1], idx[2]]);
+  else for (let i = 1; i < idx.length - 1; i++) tris.push([idx[0], idx[i], idx[i + 1]]);
+  return tris;
+}
+
+/**
+ * Turns a flat outline in the XY plane into a solid `depth` thick along Z,
+ * centered on the origin: blades, axes, keys, stars, letters, floor plans.
+ * The outline may go either way round and may be concave (no holes).
+ *
+ * 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.
+ *
+ * @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" } });
+ *
+ * @param {{x:number, y:number}[]} outline - The flat shape (3 points or more)
+ * @param {number} [depth=0.2] - Thickness along Z
+ * @returns {import("../index.d.ts").Mesh}
+ */
+export function extrude(outline, depth = 0.2) {
+  const pts = signedArea(outline) < 0 ? [...outline].reverse() : outline;
+  const n = pts.length;
+  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);
+
+  // 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)]);
+  }
+
+  // Sides, u by length along the outline
+  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 edges = [
+    pts.map((_, i) => i),
+    pts.map((_, i) => n + i),
+    ...pts.map((_, i) => [i, n + i]),
+  ];
+  return { vertices, edges, faces, uvs, faceUVs };
+}
+
 /**
  * Scales a mesh along the X, Y, and Z axes.
  *
@@ -192,32 +456,26 @@ export function scaleMesh(mesh, sx = 1, sy = 1, sz = 1) {
 }
 
 /**
- * Factory function that creates a predefined wireframe shape.
- *
- * This provides a unified API for constructing different meshes
- * (cube, box, sphere) while keeping the rendering pipeline generic.
- *
- * Supported shapes:
- * - "cube"   → wireframe cube
- * - "box"    → rectangular prism (box)
- * - "sphere" → wireframe sphere
+ * Creates a built-in shape, centered on the origin.
  *
- * Each shape type accepts its own configuration options via `opts`.
- * Unspecified options fall back to sensible defaults.
+ * | Kind | Options (defaults) |
+ * | --- | --- |
+ * | `"cube"` | `size` (0.5) |
+ * | `"box"` | `w`, `h`, `d` (0.6 each) |
+ * | `"sphere"` | `r` (0.45), `rings` (12), `segments` (24) |
+ * | `"cylinder"` | `r` (0.3), `h` (0.8), `segments` (32) |
+ * | `"cone"` | `r` (0.35), `h` (0.8), `segments` (32), `rTop` (0: pointed; > 0: tapered cylinder) |
+ * | `"torus"` | `R` (0.35, center to tube middle), `tube` (0.12), `segments` (48), `tubeSegments` (20) |
+ * | `"plane"` | `size` (1), `div` (8 cells per side), `height` ((x, z) => y, optional) |
  *
- * @param {string} kind - Shape type identifier
- * @param {Object} opts - Shape configuration options
- * @param {number} [opts.size] - Cube size
- * @param {number} [opts.w] - Box width
- * @param {number} [opts.h] - Box height
- * @param {number} [opts.d] - Box depth
- * @param {number} [opts.r] - Sphere radius
- * @param {number} [opts.rings] - Number of latitude rings (sphere)
- * @param {number} [opts.segments] - Segments per ring (sphere)
- *
- * @returns {{ vertices: {x:number,y:number,z:number}[], edges: number[][] }}
- *          A wireframe mesh object
+ * Cylinders, cones and tori stand along Y; the plane lies in XZ facing +Y.
+ * Every shape has edges (for wireframes), faces (clockwise from outside)
+ * and texture coordinates. For other round or flat shapes, see `lathe`
+ * and `extrude`.
  *
+ * @param {string} kind - Shape name (case doesn't matter)
+ * @param {Object} [opts] - Size options for that shape (see the table)
+ * @returns {import("../index.d.ts").Mesh}
  * @throws {Error} If the shape type is not supported
  */
 export function makeShape(kind, opts = {}) {
@@ -225,6 +483,10 @@ export function makeShape(kind, opts = {}) {
     case "cube":  return cubeWire(opts.size ?? 0.5);
     case "box":   return rectPrismWire(opts.w ?? 0.6, opts.h ?? 0.6, opts.d ?? 0.6);
     case "sphere":return sphereWire(opts.r ?? 0.45, opts.rings ?? 12, opts.segments ?? 24);
+    case "cylinder": return cylinder(opts.r, opts.h, opts.segments);
+    case "cone":  return cone(opts.r, opts.h, opts.segments, opts.rTop);
+    case "torus": return torus(opts.R, opts.tube, opts.segments, opts.tubeSegments);
+    case "plane": return plane(opts.size, opts.div, opts.height);
     default: throw new Error("Unknown shape: " + kind);
   }
 }