@chromatic-coherence/generative-engine 1.7.2 → 1.9.1

package/README.md

@@ -48,6 +48,8 @@ w.start();
 | **Real water** | `w.water` — the scene renders a second time through the reflected camera (flocks included) under a wave-displaced fresnel surface. Carve a basin, get a lake. |
 | **Skeletal figures** | `humanoid()` / `quadruped()` / your own rig + `w.figure()` — bones grown from code, bent in the vertex stage, with `walkPose` / `trotPose` procedural cycles. |
 | **Objectives** | `attachObjectives(w)` — give a scene a goal and it drives itself there; a live movement meter tells you what is moving and when it has settled. |
+| **Collision control** | `mesh(geo, { collider: true })` registers the mesh's bounding sphere; `addCollider(p, r, group?)` places invisible ones. Query with `collide(p, r)` (push-out normal + overlap depth), `collideAll`, and `rayHit(o, dir, maxDist?, r?)` — pass `r` to sweep a moving sphere. Colliders ride their group's `setTransform`. The pure kit (`sphereHit` · `raySphere` · `boundingSphere`) is exported and node-tested. |
+| **Poster frames** | `w.poster(t?)` renders the window's first frame as a still — HTML video's `poster`, for worlds. `capturePoster(opts, build, width, height, t?)` renders it off-screen and returns a PNG data URL with the GL context released: paint the poster at page load, build the live world only when the window is watched. |
 | **Cinema + flight** | Depth of field, camera motion blur, filmic grade — and `controls: "fly"`: drag to look, scroll to fly. |
 | **The carried light model** | Everything the chart edition learned rides along: GGX + Fresnel specular, procedural micro-relief, the perfusion term (`blood`, `bloodPulse`), pore noise, subsurface rim, coloured hemispheric ambient, fog — now resolving toward a real background colour the engine owns. |
 
@@ -164,6 +166,19 @@ The engine's founding frontiers are landed. What comes next, the scenes will ask
 organisation. Full terms in [LICENSE](./LICENSE); commercial licensing:
 [hello@chromaticcoherence.ai](mailto:hello@chromaticcoherence.ai).
 
+## Versions
+
+- **1.9.1** — docs: this version ledger.
+- **1.9.0** — **collision control**: `mesh(geo, { collider: true })` bounding-sphere registration,
+  `addCollider` / `removeCollider`, `collide` / `collideAll` (push-out normal + depth),
+  `rayHit` (swept-sphere via `r`); colliders ride their group's `setTransform`. The pure kit
+  (`sphereHit` · `raySphere` · `boundingSphere`) exported and node-tested.
+- **1.8.0** — **poster frames**: `World.poster(t)` renders the window's first frame as a still;
+  `capturePoster(opts, build, width, height, t?)` renders it off-screen → PNG data URL with the
+  GL context released.
+- **1.7.x** — the third engine: HDR post chain (bloom, SSAO, filmic, FXAA), hardware-PCF shadows,
+  GPU crowds and flight, real water, skeletal figures, objectives.
+
 ---
 
 <div align="center">

package/dist/collision.d.ts

@@ -0,0 +1,19 @@
+import { type V3 } from "./math.js";
+import type { Mesh } from "./geometry.js";
+export type Sphere = {
+    p: V3;
+    r: number;
+};
+/** Overlap between two spheres — null when apart; otherwise the contact:
+ *  `n` points from b to a (the push-out direction for a), `depth` the overlap. */
+export declare function sphereHit(a: Sphere, b: Sphere): {
+    n: V3;
+    depth: number;
+} | null;
+/** Ray vs sphere: nearest hit distance t ≥ 0 along a UNIT dir, or null.
+ *  Pass `r` to sweep a moving sphere of that radius instead of a point;
+ *  a ray starting inside reports the exit hit. */
+export declare function raySphere(o: V3, dir: V3, s: Sphere, r?: number, maxDist?: number): number | null;
+/** The bounding sphere of a mesh — vertex centroid + max distance. Not the
+ *  minimal sphere, but stable and cheap; grown once at registration. */
+export declare function boundingSphere(m: Mesh): Sphere;

package/dist/collision.js

@@ -0,0 +1,58 @@
+// generative-engine — COLLISION CONTROL, the pure kit: bounding spheres grown
+// from geometry, sphere/sphere overlap, and ray / swept-sphere casts. The World
+// rides on top (addCollider / collide / rayHit) applying group transforms;
+// this file stays DOM-free and node-testable, like the rest of the math kit.
+import { v3, sub, dot, len, scale } from "./math.js";
+/** Overlap between two spheres — null when apart; otherwise the contact:
+ *  `n` points from b to a (the push-out direction for a), `depth` the overlap. */
+export function sphereHit(a, b) {
+    const d = sub(a.p, b.p);
+    const dist = len(d);
+    const depth = a.r + b.r - dist;
+    if (depth <= 0)
+        return null;
+    return { n: dist > 1e-9 ? scale(d, 1 / dist) : v3(0, 1, 0), depth };
+}
+/** Ray vs sphere: nearest hit distance t ≥ 0 along a UNIT dir, or null.
+ *  Pass `r` to sweep a moving sphere of that radius instead of a point;
+ *  a ray starting inside reports the exit hit. */
+export function raySphere(o, dir, s, r = 0, maxDist = Infinity) {
+    const R = s.r + r;
+    const oc = sub(o, s.p);
+    const b = dot(oc, dir);
+    const c = dot(oc, oc) - R * R;
+    const disc = b * b - c; // unit dir → a = 1
+    if (disc < 0)
+        return null;
+    const sq = Math.sqrt(disc);
+    let t = -b - sq;
+    if (t < 0)
+        t = -b + sq;
+    if (t < 0 || t > maxDist)
+        return null;
+    return t;
+}
+/** The bounding sphere of a mesh — vertex centroid + max distance. Not the
+ *  minimal sphere, but stable and cheap; grown once at registration. */
+export function boundingSphere(m) {
+    const n = m.pos.length / 3;
+    if (n === 0)
+        return { p: v3(), r: 0 };
+    let cx = 0, cy = 0, cz = 0;
+    for (let i = 0; i < m.pos.length; i += 3) {
+        cx += m.pos[i];
+        cy += m.pos[i + 1];
+        cz += m.pos[i + 2];
+    }
+    cx /= n;
+    cy /= n;
+    cz /= n;
+    let r2 = 0;
+    for (let i = 0; i < m.pos.length; i += 3) {
+        const dx = m.pos[i] - cx, dy = m.pos[i + 1] - cy, dz = m.pos[i + 2] - cz;
+        const d2 = dx * dx + dy * dy + dz * dz;
+        if (d2 > r2)
+            r2 = d2;
+    }
+    return { p: v3(cx, cy, cz), r: Math.sqrt(r2) };
+}

package/dist/index.d.ts

@@ -3,3 +3,4 @@ export * from "./geometry.js";
 export * from "./world.js";
 export * from "./objectives.js";
 export * from "./skeletal.js";
+export * from "./collision.js";

package/dist/index.js

@@ -6,3 +6,4 @@ export * from "./geometry.js";
 export * from "./world.js";
 export * from "./objectives.js";
 export * from "./skeletal.js";
+export * from "./collision.js";

package/dist/world.d.ts

@@ -25,6 +25,29 @@ export type FaceOpts = {
     gloss?: number;
     /** per-face perfusion 0..1: blood near the surface (ruddiness, subsurface bleed, pulse) */
     blood?: number;
+    /** COLLISION CONTROL: register this mesh's bounding sphere as a collider.
+     *  Attached to the mesh's group, so setTransform moves it with the geometry.
+     *  (Static meshes only — instanced crowds are not auto-registered.) */
+    collider?: boolean;
+};
+/** COLLISION CONTROL — a registered sphere collider (world space at rest;
+ *  its group's transform is applied at query time). */
+export type Collider = {
+    id: number;
+    p: V3;
+    r: number;
+    gi: number;
+};
+export type CollisionHit = {
+    collider: Collider;
+    p: V3;
+    n: V3;
+    depth: number;
+};
+export type RayHitResult = {
+    collider: Collider;
+    t: number;
+    p: V3;
 };
 export type RibbonOpts = {
     hue: number;
@@ -248,6 +271,23 @@ export declare class World {
     /** Set a named group's model transform — a mat4 or a {translate, rotateY, scale...} spec.
      *  Geometry in the group moves rigidly with NO CPU re-tessellation. */
     setTransform(name: string, m: M4 | TransformSpec): void;
+    private colliders;
+    private colliderSeq;
+    /** Register an invisible sphere collider. Attach it to a named group and it
+     *  rides that group's setTransform exactly like the geometry. Returns an id. */
+    addCollider(p: V3, r: number, group?: string): number;
+    removeCollider(id: number): void;
+    /** A collider as it stands RIGHT NOW — group transform applied to its centre,
+     *  the matrix's largest axis scale applied to its radius. */
+    private colliderNow;
+    /** Deepest overlap between a probe sphere and the colliders, or null.
+     *  `n` is the push-out direction for the probe; `p` the collider's centre. */
+    collide(p: V3, r?: number): CollisionHit | null;
+    /** Every collider the probe sphere currently overlaps. */
+    collideAll(p: V3, r?: number): CollisionHit[];
+    /** Nearest ray hit against the colliders (dir need not be unit). Pass `r`
+     *  to sweep a moving sphere of that radius instead of a point. */
+    rayHit(o: V3, dir: V3, maxDist?: number, r?: number): RayHitResult | null;
     W: number;
     H: number;
     private mx;
@@ -359,6 +399,12 @@ export declare class World {
     resume(): void;
     /** Render one deterministic frame at time t (no loop) — stills, tests, screenshots. */
     settle(t: number): void;
+    /** The POSTER FRAME — the still a window shows before its animation starts
+     *  (HTML video's `poster`, for worlds). Renders the recipe once at `t`
+     *  (default 0 — the scene's own first frame, its initial background) without
+     *  starting the loop; a later start()/resume() takes over live. Two passes:
+     *  the first primes sizing and buffers, the second is the frame that stays. */
+    poster(t?: number): void;
     /** Stop the world. `releaseContext: true` also LOSES the GL context immediately —
      *  browsers cap live contexts per page and reclaim them only at GC, so many-canvas
      *  pages must release on teardown. A lost context is permanently dead on its canvas:
@@ -366,3 +412,13 @@ export declare class World {
     dispose(releaseContext?: boolean): void;
 }
 export declare function createWorld(o: WorldOpts): World;
+/** Render a recipe's poster frame OFF-SCREEN and return it as a PNG data URL —
+ *  the placeholder-image pattern: paint it into the window (an <img> beneath
+ *  the live canvas) at page load, and build the live world only when the
+ *  window scrolls into view. The scratch world renders on a hidden staged
+ *  canvas (sizing reads clientWidth, so it must be in the DOM) and its GL
+ *  context is released before returning — a page can poster every window it
+ *  owns without spending its live-context budget. Overlay labels (drawLabel)
+ *  are not part of a poster. Returns null when WebGL is unavailable — callers
+ *  keep their CSS fallback. */
+export declare function capturePoster(o: Omit<WorldOpts, "canvas" | "controls">, build: (w: World) => void, width: number, height: number, t?: number): string | null;

package/dist/world.js

@@ -3,7 +3,8 @@
 // WebGL2 renderer: HDR scene target + post chain (bloom, SSAO, composite, FXAA),
 // hardware-PCF depth-texture shadows, per-group transforms + morph targets in the
 // vertex stage, mesh + ribbon primitives. Zero third-party imports, on purpose.
-import { v3, add, sub, scale, cross, norm, clamp, hsl, mIdent, mPerspective, mLookAt, mMul, mCompose, mInvert, normalMat3, } from "./math.js";
+import { v3, add, sub, scale, cross, norm, clamp, hsl, mIdent, mPerspective, mLookAt, mMul, mCompose, mInvert, normalMat3, applyM4, } from "./math.js";
+import { sphereHit, raySphere, boundingSphere } from "./collision.js";
 import { FACE_VS, FACE_FS, DEPTH_VS, DEPTH_FS, LINE_VS, LINE_FS, PT_VS, PT_FS, RIBBON_VS, RIBBON_FS, FACE_INST_VS, DEPTH_INST_VS, WATER_VS, WATER_FS, FACE_SKIN_VS, DEPTH_SKIN_VS, } from "./shaders.js";
 import { composePose } from "./skeletal.js";
 import { PInfo, PostChain } from "./post.js";
@@ -33,6 +34,64 @@ export class World {
         this.groupMat.set(mat, i * 16);
         this.groupNM.set(normalMat3(mat), i * 9);
     }
+    /** Register an invisible sphere collider. Attach it to a named group and it
+     *  rides that group's setTransform exactly like the geometry. Returns an id. */
+    addCollider(p, r, group) {
+        const id = this.colliderSeq++;
+        this.colliders.push({ id, p: v3(p.x, p.y, p.z), r, gi: this.idxFor(group) });
+        return id;
+    }
+    removeCollider(id) {
+        const i = this.colliders.findIndex((c) => c.id === id);
+        if (i >= 0)
+            this.colliders.splice(i, 1);
+    }
+    /** A collider as it stands RIGHT NOW — group transform applied to its centre,
+     *  the matrix's largest axis scale applied to its radius. */
+    colliderNow(c) {
+        const m = this.groupMat.subarray(c.gi * 16, c.gi * 16 + 16);
+        const s = Math.max(Math.hypot(m[0], m[1], m[2]), Math.hypot(m[4], m[5], m[6]), Math.hypot(m[8], m[9], m[10]));
+        return { p: applyM4(m, c.p), r: c.r * s };
+    }
+    /** Deepest overlap between a probe sphere and the colliders, or null.
+     *  `n` is the push-out direction for the probe; `p` the collider's centre. */
+    collide(p, r = 0) {
+        let best = null;
+        for (const c of this.colliders) {
+            const s = this.colliderNow(c);
+            const h = sphereHit({ p, r }, s);
+            if (h && (!best || h.depth > best.depth)) {
+                best = { collider: c, p: s.p, n: h.n, depth: h.depth };
+            }
+        }
+        return best;
+    }
+    /** Every collider the probe sphere currently overlaps. */
+    collideAll(p, r = 0) {
+        const out = [];
+        for (const c of this.colliders) {
+            const s = this.colliderNow(c);
+            const h = sphereHit({ p, r }, s);
+            if (h)
+                out.push({ collider: c, p: s.p, n: h.n, depth: h.depth });
+        }
+        return out;
+    }
+    /** Nearest ray hit against the colliders (dir need not be unit). Pass `r`
+     *  to sweep a moving sphere of that radius instead of a point. */
+    rayHit(o, dir, maxDist = Infinity, r = 0) {
+        const d = norm(dir);
+        let bestT = maxDist;
+        let bestC = null;
+        for (const c of this.colliders) {
+            const t = raySphere(o, d, this.colliderNow(c), r, bestT);
+            if (t != null && t <= bestT) {
+                bestT = t;
+                bestC = c;
+            }
+        }
+        return bestC ? { collider: bestC, t: bestT, p: add(o, scale(d, bestT)) } : null;
+    }
     constructor(o) {
         this.flyMode = false;
         this.pitchMin = 0.18;
@@ -129,6 +188,9 @@ export class World {
         this.groupMorphT = new Float32Array(8);
         this.groupMat = new Float32Array(8 * 16);
         this.groupNM = new Float32Array(8 * 9);
+        // ── COLLISION CONTROL — sphere colliders that ride their group's transform ──
+        this.colliders = [];
+        this.colliderSeq = 1;
         this.W = 0;
         this.H = 0;
         this.mx = 0;
@@ -374,6 +436,10 @@ export class World {
     }
     /** Upload a whole Mesh (geometry.ts builders) as static faces in one call. */
     mesh(geo, o) {
+        if (o.collider) { // collision control: the mesh's bounding
+            const bs = boundingSphere(geo); // sphere rides the same group transform
+            this.addCollider(bs.p, bs.r, o.group);
+        }
         const P = geo.pos, N = geo.nrm;
         for (let i = 0; i < P.length; i += 9) {
             this.pushFace(this.sFace, v3(P[i], P[i + 1], P[i + 2]), v3(P[i + 3], P[i + 4], P[i + 5]), v3(P[i + 6], P[i + 7], P[i + 8]), o, v3(N[i], N[i + 1], N[i + 2]), v3(N[i + 3], N[i + 4], N[i + 5]), v3(N[i + 6], N[i + 7], N[i + 8]));
@@ -1126,6 +1192,12 @@ export class World {
     }
     /** Render one deterministic frame at time t (no loop) — stills, tests, screenshots. */
     settle(t) { this.renderFrame(t, 0); }
+    /** The POSTER FRAME — the still a window shows before its animation starts
+     *  (HTML video's `poster`, for worlds). Renders the recipe once at `t`
+     *  (default 0 — the scene's own first frame, its initial background) without
+     *  starting the loop; a later start()/resume() takes over live. Two passes:
+     *  the first primes sizing and buffers, the second is the frame that stays. */
+    poster(t = 0) { this.settle(Math.min(0.02, t)); this.settle(t); }
     /** Stop the world. `releaseContext: true` also LOSES the GL context immediately —
      *  browsers cap live contexts per page and reclaim them only at GC, so many-canvas
      *  pages must release on teardown. A lost context is permanently dead on its canvas:
@@ -1160,3 +1232,35 @@ export class World {
     }
 }
 export function createWorld(o) { return new World(o); }
+/** Render a recipe's poster frame OFF-SCREEN and return it as a PNG data URL —
+ *  the placeholder-image pattern: paint it into the window (an <img> beneath
+ *  the live canvas) at page load, and build the live world only when the
+ *  window scrolls into view. The scratch world renders on a hidden staged
+ *  canvas (sizing reads clientWidth, so it must be in the DOM) and its GL
+ *  context is released before returning — a page can poster every window it
+ *  owns without spending its live-context budget. Overlay labels (drawLabel)
+ *  are not part of a poster. Returns null when WebGL is unavailable — callers
+ *  keep their CSS fallback. */
+export function capturePoster(o, build, width, height, t = 0) {
+    const stage = document.createElement("div");
+    stage.style.cssText = "position:fixed;left:-99999px;top:0;visibility:hidden;pointer-events:none;"
+        + `width:${Math.max(2, Math.round(width))}px;height:${Math.max(2, Math.round(height))}px;`;
+    const canvas = document.createElement("canvas");
+    canvas.style.cssText = "width:100%;height:100%;display:block;";
+    stage.appendChild(canvas);
+    document.body.appendChild(stage);
+    let w = null;
+    try {
+        w = createWorld({ ...o, canvas, controls: false, maxDpr: 1 });
+        build(w);
+        w.poster(t);
+        return canvas.toDataURL("image/png"); // same task as the render — buffer intact
+    }
+    catch {
+        return null;
+    }
+    finally {
+        w?.dispose(true);
+        stage.remove();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chromatic-coherence/generative-engine",
-  "version": "1.7.2",
+  "version": "1.9.1",
   "description": "A zero-dependency WebGL2 graphics engine where everything is grown from code — no models, no textures, no asset pipeline. Real light and shadow with a cinematic HDR finish (bloom, SSAO, filmic grade, depth of field, motion blur), a geometry stdlib, GPU crowds (instanced wind, ten-thousand-bird flocks), real water with planar reflections, skeletal figures with procedural walk cycles, free-flight controls, and scenes that drive themselves toward objectives. The Generative Charts API rides on top unchanged.",
   "type": "module",
   "main": "./dist/index.js",