@chromatic-coherence/generative-engine 1.0.3 → 1.1.0

package/README.md

@@ -49,6 +49,46 @@ w.start();
 **The ink edition** (`theme: "light"`) still renders any recipe on paper instead of night —
 lightness inverts, strokes blend normally, SSAO becomes pencil shading. Bloom stays dark-only.
 
+## Objectives — scenes that know where they're going
+
+A scene gets a **goal** and the engine drives motion toward it; a live **movement meter**
+tells you whether the scene is moving or settled — and names what is moving.
+
+```ts
+import { createWorld, attachObjectives } from "@chromatic-coherence/generative-engine";
+
+const w = createWorld({ canvas });
+const obj = attachObjectives(w);
+
+obj.define("reveal", {
+  morph:  { group: "terrain", to: 1 },     // blend the terrain to its B shape
+  camera: { dist: 420, pitch: 0.62 },      // settle the camera in close
+  fade:   { group: "veil", to: 0 },        // dissolve the veil
+  pace: 3,                                 // seconds to ~95% of the way there
+});
+
+obj.onReading(r => {
+  // { name, progress, level, floor, moving, settled, driving: ["morph:terrain","camera",...] }
+  if (r.settled) console.log(`${r.name}: settled`);
+});
+
+// later — the goal itself moves; motion continues from the current state, no snap,
+// and the meter lights up again:
+obj.retarget("reveal", { camera: { dist: 300 } });
+```
+
+Channels: `transform` (group rigid-body spec) · `morph` · `fade` · `camera` · `custom`
+(an `apply(progress, dt)` escape hatch). `readings()` is the pull form of `onReading`.
+
+**The meter's semantics** come from the objective-movement measurement work this engine's
+org ran first as science: movement is a **level sustained above a settled floor**, not a
+discrete event. `driving` names the elevated channels — movement you can name; `settled`
+is the sustained fall to the floor. Options: `attachObjectives(w, { floor, settleAfter })`.
+
+The layer rides the frame loop as a `grow()` hook and drives the World through its public
+verbs only — the renderer is untouched, and everything composes with hand-written `grow()`
+animation.
+
 ## Demo
 
 `demo/index.html` — serve the package folder (`python -m http.server`) and open

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/objectives.d.ts

@@ -0,0 +1,96 @@
+import { V3, TransformSpec } from "./math.js";
+import type { World } from "./world.js";
+export type ObjectiveCamera = {
+    target?: V3;
+    dist?: number;
+    pitch?: number;
+    yaw?: number;
+};
+export type ObjectiveSpec = {
+    /** rigid-body goal for a named group — interpolated spec, applied via setTransform */
+    transform?: {
+        group: string;
+        to: TransformSpec;
+        from?: TransformSpec;
+    };
+    /** morph-weight goal for a named group (meshMorph geometry). Default from: 0. */
+    morph?: {
+        group: string;
+        to: number;
+        from?: number;
+    };
+    /** fade goal for a named group. Default from: 1. */
+    fade?: {
+        group: string;
+        to: number;
+        from?: number;
+    };
+    /** camera goal — absent fields keep the camera's current value */
+    camera?: ObjectiveCamera;
+    /** escape hatch — called every tick with eased progress 0..1 */
+    custom?: (progress: number, dt: number) => void;
+    /** seconds to ~95 % of the way there. Default 3. */
+    pace?: number;
+};
+/** One tick's reading for one objective — the movement meter's voice. */
+export type MovementReading = {
+    name: string;
+    /** eased approach to the goal, 0..1 */
+    progress: number;
+    /** movement level this tick (≈ 1 at a fresh goal, decaying toward 0) */
+    level: number;
+    /** the settled floor the level is read against */
+    floor: number;
+    /** level is above the floor */
+    moving: boolean;
+    /** level has stayed at/below the floor for settleAfter seconds */
+    settled: boolean;
+    /** the channels currently elevated — the movement you can name */
+    driving: string[];
+};
+export type ObjectivesOpts = {
+    /** the settled floor (movement level units). Default 0.02. */
+    floor?: number;
+    /** seconds the level must hold at/below the floor to read settled. Default 0.6. */
+    settleAfter?: number;
+};
+/** Channel writes, injected — a World in production, plain recorders in tests. */
+export type ChannelAppliers = {
+    transform(group: string, spec: TransformSpec): void;
+    morph(group: string, weight: number): void;
+    fade(group: string, alpha: number): void;
+    camera(c: ObjectiveCamera): void;
+};
+export declare class ObjectivesCore {
+    private apply;
+    private objs;
+    private listeners;
+    private floor;
+    private settleAfter;
+    constructor(apply: ChannelAppliers, opts?: ObjectivesOpts);
+    /** Define (or wholly replace) a named objective. The drive starts on the next tick. */
+    define(name: string, spec: ObjectiveSpec, camNow?: ObjectiveCamera): void;
+    /** Move a live objective's goal — progress restarts FROM THE CURRENT STATE (no snap)
+     *  and the meter lights up again. Channels absent from the patch keep their goal. */
+    retarget(name: string, patch: Partial<ObjectiveSpec>, camNow?: ObjectiveCamera): void;
+    /** Forget an objective — its channels stay wherever they were last driven to. */
+    remove(name: string): void;
+    /** Subscribe to per-tick readings (one call per live objective per tick). */
+    onReading(cb: (r: MovementReading) => void): () => void;
+    /** Pull the latest readings — the same objects the callbacks saw. */
+    readings(): MovementReading[];
+    /** Advance every objective by dt seconds and apply the driven values.
+     *  dt <= 0 (settle() stills) re-applies values without advancing the meter. */
+    tick(dt: number): void;
+}
+/** The user-facing facade returned by attachObjectives(). */
+export type Objectives = {
+    define(name: string, spec: ObjectiveSpec): void;
+    retarget(name: string, patch: Partial<ObjectiveSpec>): void;
+    remove(name: string): void;
+    onReading(cb: (r: MovementReading) => void): () => void;
+    readings(): MovementReading[];
+};
+/** Attach the objectives layer to a World. Rides the frame loop as a grow() hook and
+ *  drives the World through its public verbs — the renderer is untouched. */
+export declare function attachObjectives(world: World, opts?: ObjectivesOpts): Objectives;

package/dist/objectives.js

@@ -0,0 +1,174 @@
+// generative-engine — objectives.ts: THE OBJECTIVES LAYER. A scene gets a goal and the
+// engine drives motion toward it; a live movement meter reads whether the scene is
+// moving or settled, and names what is moving.
+//
+// Two layers, deliberately split:
+//   ObjectivesCore  — pure logic, no GL, no DOM. Channel writes go through injected
+//                     appliers, so the core runs (and is tested) under bare node.
+//   attachObjectives(world) — the binder: wires the core to a World through its PUBLIC
+//                     verbs only (grow / setTransform / morph / fade / cam). world.ts
+//                     is untouched by this layer.
+//
+// The meter's lineage (documented, not mystified): it is the regime measure from the
+// objective-movement work (science/walk/station-23) carried into engineering — movement
+// is a LEVEL sustained above a settled FLOOR, not a discrete event. `driving` names the
+// elevated channels — the movement you can name; `settled` is the sustained fall to the
+// floor: the turn you cannot name is the stop.
+import { v3, clamp } from "./math.js";
+const lerp = (a, b, t) => a + (b - a) * t;
+const lerpV3 = (a, b, t) => v3(lerp(a.x, b.x, t), lerp(a.y, b.y, t), lerp(a.z, b.z, t));
+const asV3 = (s, d) => s == null ? v3(d, d, d) : typeof s === "number" ? v3(s, s, s) : s;
+function lerpSpec(a, b, t) {
+    return {
+        translate: lerpV3(a.translate ?? v3(), b.translate ?? v3(), t),
+        rotateX: lerp(a.rotateX ?? 0, b.rotateX ?? 0, t),
+        rotateY: lerp(a.rotateY ?? 0, b.rotateY ?? 0, t),
+        rotateZ: lerp(a.rotateZ ?? 0, b.rotateZ ?? 0, t),
+        scale: lerpV3(asV3(a.scale, 1), asV3(b.scale, 1), t),
+    };
+}
+export class ObjectivesCore {
+    constructor(apply, opts = {}) {
+        this.apply = apply;
+        this.objs = new Map();
+        this.listeners = [];
+        this.floor = opts.floor ?? 0.02;
+        this.settleAfter = opts.settleAfter ?? 0.6;
+    }
+    /** Define (or wholly replace) a named objective. The drive starts on the next tick. */
+    define(name, spec, camNow) {
+        this.objs.set(name, {
+            name, spec,
+            k: 3 / Math.max(0.05, spec.pace ?? 3),
+            progress: 0, level: 1, atFloorFor: 0,
+            camFrom: spec.camera ? (camNow ?? {}) : null,
+            reading: { name, progress: 0, level: 1, floor: this.floor, moving: true, settled: false, driving: [] },
+        });
+    }
+    /** Move a live objective's goal — progress restarts FROM THE CURRENT STATE (no snap)
+     *  and the meter lights up again. Channels absent from the patch keep their goal. */
+    retarget(name, patch, camNow) {
+        const o = this.objs.get(name);
+        if (!o)
+            throw new Error(`generative-engine objectives: retarget of unknown objective "${name}"`);
+        const s = o.spec, p = o.progress;
+        const next = { ...s, ...patch };
+        // continuity: each patched channel's new `from` is the value currently applied
+        if (patch.transform && s.transform)
+            next.transform = { ...patch.transform, from: lerpSpec(s.transform.from ?? {}, s.transform.to, p) };
+        if (patch.morph && s.morph)
+            next.morph = { ...patch.morph, from: lerp(s.morph.from ?? 0, s.morph.to, p) };
+        if (patch.fade && s.fade)
+            next.fade = { ...patch.fade, from: lerp(s.fade.from ?? 1, s.fade.to, p) };
+        const camFrom = patch.camera ? (camNow ?? o.camFrom ?? {}) : o.camFrom;
+        this.objs.set(name, {
+            name, spec: next,
+            k: 3 / Math.max(0.05, next.pace ?? 3),
+            progress: 0, level: 1, atFloorFor: 0,
+            camFrom,
+            reading: o.reading,
+        });
+    }
+    /** Forget an objective — its channels stay wherever they were last driven to. */
+    remove(name) { this.objs.delete(name); }
+    /** Subscribe to per-tick readings (one call per live objective per tick). */
+    onReading(cb) {
+        this.listeners.push(cb);
+        return () => { const i = this.listeners.indexOf(cb); if (i >= 0)
+            this.listeners.splice(i, 1); };
+    }
+    /** Pull the latest readings — the same objects the callbacks saw. */
+    readings() {
+        return [...this.objs.values()].map(o => o.reading);
+    }
+    /** Advance every objective by dt seconds and apply the driven values.
+     *  dt <= 0 (settle() stills) re-applies values without advancing the meter. */
+    tick(dt) {
+        for (const o of this.objs.values()) {
+            if (dt > 0) {
+                o.progress += (1 - o.progress) * Math.min(1, dt * o.k);
+                // the level is the drive still outstanding — ≈1 at a fresh goal, easing to 0.
+                // A retarget resets progress, so the level re-elevates: movement is a REGIME.
+                o.level = 1 - o.progress;
+                if (o.level <= this.floor)
+                    o.atFloorFor += dt;
+                else
+                    o.atFloorFor = 0;
+            }
+            const p = o.progress, s = o.spec;
+            const driving = [];
+            const moving = o.level > this.floor;
+            if (s.transform) {
+                this.apply.transform(s.transform.group, lerpSpec(s.transform.from ?? {}, s.transform.to, p));
+                if (moving)
+                    driving.push(`transform:${s.transform.group}`);
+            }
+            if (s.morph) {
+                this.apply.morph(s.morph.group, clamp(lerp(s.morph.from ?? 0, s.morph.to, p), 0, 1));
+                if (moving)
+                    driving.push(`morph:${s.morph.group}`);
+            }
+            if (s.fade) {
+                this.apply.fade(s.fade.group, clamp(lerp(s.fade.from ?? 1, s.fade.to, p), 0, 1));
+                if (moving)
+                    driving.push(`fade:${s.fade.group}`);
+            }
+            if (s.camera && o.camFrom) {
+                const c = s.camera, f = o.camFrom, out = {};
+                if (c.target)
+                    out.target = lerpV3(f.target ?? c.target, c.target, p);
+                if (c.dist != null)
+                    out.dist = lerp(f.dist ?? c.dist, c.dist, p);
+                if (c.pitch != null)
+                    out.pitch = lerp(f.pitch ?? c.pitch, c.pitch, p);
+                if (c.yaw != null)
+                    out.yaw = lerp(f.yaw ?? c.yaw, c.yaw, p);
+                this.apply.camera(out);
+                if (moving)
+                    driving.push("camera");
+            }
+            if (s.custom) {
+                s.custom(p, Math.max(0, dt));
+                if (moving)
+                    driving.push("custom");
+            }
+            o.reading = {
+                name: o.name, progress: p, level: o.level, floor: this.floor,
+                moving, settled: !moving && o.atFloorFor >= this.settleAfter, driving,
+            };
+            for (const cb of this.listeners)
+                cb(o.reading);
+        }
+    }
+}
+/** Attach the objectives layer to a World. Rides the frame loop as a grow() hook and
+ *  drives the World through its public verbs — the renderer is untouched. */
+export function attachObjectives(world, opts = {}) {
+    const core = new ObjectivesCore({
+        transform: (g, spec) => world.setTransform(g, spec),
+        morph: (g, w) => world.morph(g, w),
+        fade: (g, a) => world.fade(g, a),
+        camera: (c) => {
+            if (c.target)
+                world.cam.target = c.target;
+            if (c.dist != null)
+                world.cam.distT = c.dist;
+            if (c.pitch != null)
+                world.cam.pitch = c.pitch;
+            if (c.yaw != null)
+                world.cam.yawBase = c.yaw;
+        },
+    }, opts);
+    const camNow = () => ({
+        target: world.cam.target, dist: world.cam.distT,
+        pitch: world.cam.pitch, yaw: world.cam.yawBase,
+    });
+    world.grow((_t, dt) => core.tick(dt));
+    return {
+        define: (name, spec) => core.define(name, spec, camNow()),
+        retarget: (name, patch) => core.retarget(name, patch, camNow()),
+        remove: (name) => core.remove(name),
+        onReading: (cb) => core.onReading(cb),
+        readings: () => core.readings(),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chromatic-coherence/generative-engine",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "THE THIRD ENGINE — a zero-dependency WebGL2 graphics engine grown from generative-charts-3d: HDR + bloom + SSAO post chain, hardware-PCF shadow maps, a geometry stdlib, ribbon strokes, group transforms and morph targets. The charts API rides on top unchanged.",
   "type": "module",
   "main": "./dist/index.js",