@jgengine/core 0.18.0 → 0.18.1

package/dist/physics/physicsWorldBackend.js

@@ -0,0 +1,485 @@
+import { IDENTITY_QUAT, isIdentityQuat, shapeHalfExtents, } from "./physicsBackend.js";
+import { PhysicsWorld } from "./physicsWorld.js";
+const ALL_LAYERS = 0xffffffff;
+const CAPABILITIES = {
+    rotation: false,
+    shapes: ["box", "sphere", "capsule", "convex", "trimesh", "heightfield"],
+    ccd: false,
+    joints: ["fixed", "hinge", "ball", "distance", "spring"],
+};
+function slabRay(ox, oy, oz, dx, dy, dz, minX, minY, minZ, maxX, maxY, maxZ) {
+    let tMin = 0;
+    let tMax = Number.POSITIVE_INFINITY;
+    let axis = -1;
+    let sign = 0;
+    const origin = [ox, oy, oz];
+    const dir = [dx, dy, dz];
+    const mins = [minX, minY, minZ];
+    const maxs = [maxX, maxY, maxZ];
+    for (let i = 0; i < 3; i += 1) {
+        const o = origin[i];
+        const d = dir[i];
+        if (Math.abs(d) < 1e-12) {
+            if (o < mins[i] || o > maxs[i])
+                return null;
+            continue;
+        }
+        const inv = 1 / d;
+        let t1 = (mins[i] - o) * inv;
+        let t2 = (maxs[i] - o) * inv;
+        let entrySign = -1;
+        if (t1 > t2) {
+            const tmp = t1;
+            t1 = t2;
+            t2 = tmp;
+            entrySign = 1;
+        }
+        // `>=` so a shape resting exactly on a face still reports the contact at t=0 (grounding needs it).
+        if (t1 >= tMin) {
+            tMin = t1;
+            axis = i;
+            sign = entrySign;
+        }
+        tMax = Math.min(tMax, t2);
+        if (tMin > tMax)
+            return null;
+    }
+    return { t: tMin, axis, sign };
+}
+/**
+ * `PhysicsWorld` behind the {@link PhysicsBackend} interface: zero dependencies, translation-only. Capsules,
+ * convex hulls, meshes, and heightfields collide as their bounding boxes; rotation, angular velocity, CCD, and
+ * hinge limits are accepted and ignored (see {@link PhysicsBackend.capabilities}). Reach for `@jgengine/rapier`
+ * when a game needs those for real; the seam is the same.
+ *
+ * @capability physics-world-backend the zero-dependency PhysicsWorld solver exposed through the PhysicsBackend seam
+ */
+export function createPhysicsWorldBackend(options) {
+    const world = new PhysicsWorld({
+        capacity: options.capacity,
+        bounds: options.bounds,
+        ...(options.gravity === undefined ? {} : { gravity: options.gravity[1] }),
+        ...(options.fixedDt === undefined ? {} : { fixedDt: options.fixedDt }),
+        ...(options.maxSubsteps === undefined ? {} : { maxSubsteps: options.maxSubsteps }),
+        ...(options.precision === undefined ? {} : { precision: options.precision }),
+        ...(options.friction === undefined ? {} : { friction: options.friction }),
+        ...(options.restitution === undefined ? {} : { restitution: options.restitution }),
+    });
+    const records = new Map();
+    const handleOfIndex = new Map();
+    const joints = new Map();
+    const masses = new Map();
+    let nextHandle = 1;
+    let nextJoint = 1;
+    let warnedRotation = false;
+    let warnedShape = false;
+    let contactListener = null;
+    const contactEvent = {
+        a: 0,
+        b: 0,
+        normal: [0, 0, 0],
+        approachSpeed: 0,
+        impulse: 0,
+    };
+    const warn = options.warn ?? true;
+    function noteRotation(rotation) {
+        if (warnedRotation || !warn || isIdentityQuat(rotation))
+            return;
+        warnedRotation = true;
+        console.warn("[jgengine:physics] PhysicsWorld backend ignores rotation; use @jgengine/rapier for rotating bodies.");
+    }
+    function noteShape(shape) {
+        if (warnedShape || !warn || shape.kind === "box" || shape.kind === "sphere")
+            return;
+        warnedShape = true;
+        console.warn(`[jgengine:physics] PhysicsWorld backend collides "${shape.kind}" shapes as their bounding box.`);
+    }
+    function record(handle) {
+        const rec = records.get(handle);
+        if (rec === undefined)
+            throw new Error(`physics: unknown body handle ${handle}`);
+        return rec;
+    }
+    function insert(handle, desc, sleeping) {
+        const kind = desc.kind ?? "dynamic";
+        const half = shapeHalfExtents(desc.shape);
+        const index = world.addBody(desc.shape.kind === "sphere"
+            ? {
+                shape: "sphere",
+                radius: desc.shape.radius,
+                position: desc.position,
+                ...(desc.velocity === undefined ? {} : { velocity: desc.velocity }),
+                mass: desc.mass ?? 1,
+                static: kind !== "dynamic",
+                asleep: sleeping,
+            }
+            : {
+                shape: "box",
+                halfExtents: half,
+                position: desc.position,
+                ...(desc.velocity === undefined ? {} : { velocity: desc.velocity }),
+                mass: desc.mass ?? 1,
+                static: kind !== "dynamic",
+                asleep: sleeping,
+            });
+        records.set(handle, {
+            index,
+            shape: desc.shape,
+            kind,
+            layers: desc.layers ?? 1,
+            mask: desc.mask ?? ALL_LAYERS,
+            userData: desc.userData,
+            half,
+            kinematicVelocity: [0, 0, 0],
+            kinematicTarget: null,
+        });
+        handleOfIndex.set(index, handle);
+        masses.set(handle, desc.mass ?? 1);
+    }
+    function addJointToWorld(desc) {
+        const a = record(desc.bodyA).index;
+        const base = {
+            bodyA: a,
+            ...(desc.bodyB === undefined ? {} : { bodyB: record(desc.bodyB).index }),
+            ...(desc.anchorA === undefined ? {} : { anchorA: desc.anchorA }),
+            ...(desc.anchorB === undefined ? {} : { anchorB: desc.anchorB }),
+            ...(desc.restLength === undefined ? {} : { restLength: desc.restLength }),
+            ...(desc.stiffness === undefined ? {} : { stiffness: desc.stiffness }),
+            ...(desc.damping === undefined ? {} : { damping: desc.damping }),
+            ...(desc.axis === undefined ? {} : { axis: desc.axis }),
+        };
+        switch (desc.kind) {
+            case "hinge":
+                return world.hingeJoint(base);
+            case "distance":
+                return world.distanceJoint(base);
+            case "spring":
+                return world.springJoint(base);
+            default:
+                return world.fixedJoint(base);
+        }
+    }
+    function bodyMatches(rec, mask, exclude, handle) {
+        if (exclude === handle)
+            return false;
+        if (mask !== undefined && (rec.layers & mask) === 0)
+            return false;
+        return world.isAlive(rec.index);
+    }
+    world.onCollision((event) => {
+        if (contactListener === null)
+            return;
+        const a = handleOfIndex.get(event.a);
+        const b = handleOfIndex.get(event.b);
+        if (a === undefined || b === undefined)
+            return;
+        contactEvent.a = a;
+        contactEvent.b = b;
+        contactEvent.normal[0] = event.nx;
+        contactEvent.normal[1] = event.ny;
+        contactEvent.normal[2] = event.nz;
+        contactEvent.approachSpeed = event.approachSpeed;
+        contactEvent.impulse = event.impulse;
+        contactListener(contactEvent);
+    });
+    const backend = {
+        name: "physics-world",
+        capabilities: CAPABILITIES,
+        addBody(desc) {
+            noteRotation(desc.rotation);
+            noteShape(desc.shape);
+            const handle = nextHandle;
+            nextHandle += 1;
+            insert(handle, desc, desc.asleep === true);
+            return handle;
+        },
+        removeBody(handle) {
+            const rec = records.get(handle);
+            if (rec === undefined)
+                return;
+            for (const [jointHandle, joint] of joints) {
+                if (joint.desc.bodyA === handle || joint.desc.bodyB === handle) {
+                    world.removeJoint(joint.id);
+                    joints.delete(jointHandle);
+                }
+            }
+            world.removeBody(rec.index);
+            handleOfIndex.delete(rec.index);
+            records.delete(handle);
+            masses.delete(handle);
+        },
+        hasBody: (handle) => records.has(handle),
+        body(handle, out) {
+            const rec = records.get(handle);
+            if (rec === undefined)
+                return null;
+            const i = rec.index;
+            const velocity = rec.kind === "kinematic" ? rec.kinematicVelocity : [world.velX[i], world.velY[i], world.velZ[i]];
+            const state = out ?? {
+                position: [0, 0, 0],
+                rotation: IDENTITY_QUAT,
+                velocity: [0, 0, 0],
+                angularVelocity: [0, 0, 0],
+                sleeping: false,
+            };
+            state.position = [world.posX[i], world.posY[i], world.posZ[i]];
+            state.rotation = IDENTITY_QUAT;
+            state.velocity = velocity;
+            state.angularVelocity = [0, 0, 0];
+            state.sleeping = world.isSleeping(i);
+            return state;
+        },
+        userDataOf: (handle) => records.get(handle)?.userData,
+        setPosition(handle, position) {
+            world.setPosition(record(handle).index, position[0], position[1], position[2]);
+        },
+        setRotation(_handle, rotation) {
+            noteRotation(rotation);
+        },
+        setVelocity(handle, velocity) {
+            world.setVelocity(record(handle).index, velocity[0], velocity[1], velocity[2]);
+        },
+        setAngularVelocity() { },
+        applyImpulse(handle, impulse) {
+            const rec = record(handle);
+            if (rec.kind !== "dynamic")
+                return;
+            const i = rec.index;
+            const invMass = world.invMass[i];
+            world.setVelocity(i, world.velX[i] + impulse[0] * invMass, world.velY[i] + impulse[1] * invMass, world.velZ[i] + impulse[2] * invMass);
+        },
+        setKinematicTarget(handle, position) {
+            const rec = record(handle);
+            rec.kinematicTarget = [position[0], position[1], position[2]];
+        },
+        wake(handle) {
+            world.wake(record(handle).index);
+        },
+        addJoint(desc) {
+            const handle = nextJoint;
+            nextJoint += 1;
+            joints.set(handle, { id: addJointToWorld(desc), desc });
+            return handle;
+        },
+        removeJoint(handle) {
+            const joint = joints.get(handle);
+            if (joint === undefined)
+                return;
+            world.removeJoint(joint.id);
+            joints.delete(handle);
+        },
+        step(dt) {
+            if (!(dt > 0))
+                return;
+            for (const rec of records.values()) {
+                if (rec.kind !== "kinematic")
+                    continue;
+                const target = rec.kinematicTarget;
+                const i = rec.index;
+                if (target === null) {
+                    rec.kinematicVelocity[0] = 0;
+                    rec.kinematicVelocity[1] = 0;
+                    rec.kinematicVelocity[2] = 0;
+                    continue;
+                }
+                rec.kinematicVelocity[0] = (target[0] - world.posX[i]) / dt;
+                rec.kinematicVelocity[1] = (target[1] - world.posY[i]) / dt;
+                rec.kinematicVelocity[2] = (target[2] - world.posZ[i]) / dt;
+                world.setPosition(i, target[0], target[1], target[2]);
+                rec.kinematicTarget = null;
+            }
+            world.step(dt);
+        },
+        raycast(desc) {
+            const len = Math.hypot(desc.direction[0], desc.direction[1], desc.direction[2]);
+            if (!(len > 0))
+                return null;
+            const dx = desc.direction[0] / len;
+            const dy = desc.direction[1] / len;
+            const dz = desc.direction[2] / len;
+            let best = null;
+            for (const [handle, rec] of records) {
+                if (!bodyMatches(rec, desc.mask, desc.exclude, handle))
+                    continue;
+                const i = rec.index;
+                const px = world.posX[i];
+                const py = world.posY[i];
+                const pz = world.posZ[i];
+                let t;
+                let normal;
+                if (rec.shape.kind === "sphere") {
+                    const r = rec.shape.radius;
+                    const ox = desc.origin[0] - px;
+                    const oy = desc.origin[1] - py;
+                    const oz = desc.origin[2] - pz;
+                    const b = ox * dx + oy * dy + oz * dz;
+                    const c = ox * ox + oy * oy + oz * oz - r * r;
+                    const disc = b * b - c;
+                    if (disc < 0)
+                        continue;
+                    t = -b - Math.sqrt(disc);
+                    if (t < 0)
+                        continue;
+                    const hx = ox + dx * t;
+                    const hy = oy + dy * t;
+                    const hz = oz + dz * t;
+                    normal = [hx / r, hy / r, hz / r];
+                }
+                else {
+                    const hit = slabRay(desc.origin[0], desc.origin[1], desc.origin[2], dx, dy, dz, px - rec.half[0], py - rec.half[1], pz - rec.half[2], px + rec.half[0], py + rec.half[1], pz + rec.half[2]);
+                    if (hit === null || hit.axis < 0)
+                        continue;
+                    t = hit.t;
+                    normal = [hit.axis === 0 ? hit.sign : 0, hit.axis === 1 ? hit.sign : 0, hit.axis === 2 ? hit.sign : 0];
+                }
+                if (t > desc.maxDistance)
+                    continue;
+                if (best !== null && t >= best.distance)
+                    continue;
+                best = {
+                    body: handle,
+                    distance: t,
+                    point: [desc.origin[0] + dx * t, desc.origin[1] + dy * t, desc.origin[2] + dz * t],
+                    normal,
+                };
+            }
+            return best;
+        },
+        shapecast(desc) {
+            noteRotation(desc.rotation);
+            const castHalf = shapeHalfExtents(desc.shape);
+            const [mx, my, mz] = desc.motion;
+            const motionLen = Math.hypot(mx, my, mz);
+            let best = null;
+            for (const [handle, rec] of records) {
+                if (!bodyMatches(rec, desc.mask, desc.exclude, handle))
+                    continue;
+                const i = rec.index;
+                const minX = world.posX[i] - rec.half[0] - castHalf[0];
+                const minY = world.posY[i] - rec.half[1] - castHalf[1];
+                const minZ = world.posZ[i] - rec.half[2] - castHalf[2];
+                const maxX = world.posX[i] + rec.half[0] + castHalf[0];
+                const maxY = world.posY[i] + rec.half[1] + castHalf[1];
+                const maxZ = world.posZ[i] + rec.half[2] + castHalf[2];
+                const [ox, oy, oz] = desc.position;
+                const inside = ox > minX && ox < maxX && oy > minY && oy < maxY && oz > minZ && oz < maxZ;
+                let toi;
+                let normal;
+                if (inside) {
+                    const pens = [ox - minX, maxX - ox, oy - minY, maxY - oy, oz - minZ, maxZ - oz];
+                    let least = 0;
+                    for (let k = 1; k < 6; k += 1)
+                        if (pens[k] < pens[least])
+                            least = k;
+                    toi = 0;
+                    normal = [
+                        least === 0 ? -1 : least === 1 ? 1 : 0,
+                        least === 2 ? -1 : least === 3 ? 1 : 0,
+                        least === 4 ? -1 : least === 5 ? 1 : 0,
+                    ];
+                }
+                else {
+                    if (!(motionLen > 0))
+                        continue;
+                    const hit = slabRay(ox, oy, oz, mx, my, mz, minX, minY, minZ, maxX, maxY, maxZ);
+                    if (hit === null || hit.axis < 0 || hit.t > 1)
+                        continue;
+                    toi = hit.t;
+                    normal = [hit.axis === 0 ? hit.sign : 0, hit.axis === 1 ? hit.sign : 0, hit.axis === 2 ? hit.sign : 0];
+                }
+                if (best !== null && toi >= best.toi)
+                    continue;
+                best = {
+                    body: handle,
+                    toi,
+                    distance: toi * motionLen,
+                    point: [ox + mx * toi - normal[0] * castHalf[0], oy + my * toi - normal[1] * castHalf[1], oz + mz * toi - normal[2] * castHalf[2]],
+                    normal,
+                };
+            }
+            return best;
+        },
+        overlap(desc) {
+            const half = shapeHalfExtents(desc.shape);
+            const out = [];
+            for (const [handle, rec] of records) {
+                if (!bodyMatches(rec, desc.mask, desc.exclude, handle))
+                    continue;
+                const i = rec.index;
+                if (Math.abs(world.posX[i] - desc.position[0]) >= rec.half[0] + half[0])
+                    continue;
+                if (Math.abs(world.posY[i] - desc.position[1]) >= rec.half[1] + half[1])
+                    continue;
+                if (Math.abs(world.posZ[i] - desc.position[2]) >= rec.half[2] + half[2])
+                    continue;
+                out.push(handle);
+            }
+            return out;
+        },
+        onContact(listener) {
+            contactListener = listener;
+        },
+        retune() {
+            // PhysicsWorld fixes its solver knobs at construction; retune is a no-op here and a real call on native backends.
+        },
+        snapshot() {
+            const bodies = [];
+            for (const [handle, rec] of records) {
+                const i = rec.index;
+                bodies.push({
+                    handle,
+                    shape: rec.shape,
+                    kind: rec.kind,
+                    layers: rec.layers,
+                    mask: rec.mask,
+                    userData: rec.userData,
+                    mass: masses.get(handle) ?? 1,
+                    position: [world.posX[i], world.posY[i], world.posZ[i]],
+                    velocity: [world.velX[i], world.velY[i], world.velZ[i]],
+                    sleeping: world.isSleeping(i),
+                });
+            }
+            return {
+                nextHandle,
+                nextJoint,
+                bodies,
+                joints: Array.from(joints, ([handle, joint]) => ({ handle, desc: joint.desc })),
+            };
+        },
+        restore(state) {
+            const saved = state;
+            world.clear();
+            records.clear();
+            handleOfIndex.clear();
+            joints.clear();
+            masses.clear();
+            nextHandle = saved.nextHandle;
+            nextJoint = saved.nextJoint;
+            for (const body of saved.bodies) {
+                insert(body.handle, {
+                    shape: body.shape,
+                    kind: body.kind,
+                    position: body.position,
+                    velocity: body.velocity,
+                    mass: body.mass,
+                    layers: body.layers,
+                    mask: body.mask,
+                    userData: body.userData,
+                }, body.sleeping);
+            }
+            for (const joint of saved.joints) {
+                joints.set(joint.handle, { id: addJointToWorld(joint.desc), desc: joint.desc });
+            }
+        },
+        dispose() {
+            world.onCollision(null);
+            contactListener = null;
+            world.clear();
+            records.clear();
+            handleOfIndex.clear();
+            joints.clear();
+            masses.clear();
+        },
+    };
+    return backend;
+}

package/dist/physics/worldColliders.d.ts

@@ -0,0 +1,13 @@
+import type { GameContext } from "../runtime/gameContextTypes.js";
+import type { PhysicsBackend } from "./physicsBackend.js";
+/** Handle for synchronizing authored static world collision with a physics backend. */
+export interface WorldColliderSync {
+    /** Rebuild static terrain and object bodies from the current context. */
+    sync(): void;
+    /** Remove all bodies owned by this synchronizer and stop reacting to scene changes. */
+    dispose(): void;
+}
+/** Mirrors static scene-object physical colliders and the context's ground field into a physics backend.
+ * @capability world-physics-colliders Synchronize terrain and authored static colliders with a physics backend.
+ */
+export declare function syncWorldColliders(backend: PhysicsBackend, ctx: GameContext): WorldColliderSync;

package/dist/physics/worldColliders.js

@@ -0,0 +1,96 @@
+import { colliderWorldCenter, resolveColliders } from "../scene/colliders.js";
+const TERRAIN_SEGMENTS = 32;
+function bodyShape(shape) {
+    if (shape.kind === "sphere")
+        return { kind: "sphere", radius: shape.radius };
+    if (shape.kind === "aabb")
+        return { kind: "box", halfExtents: shape.halfExtents };
+    return { kind: "trimesh", vertices: shape.mesh.positions, indices: shape.mesh.indices };
+}
+function bodyPosition(shape, position, rotationY) {
+    return colliderWorldCenter({ name: "body", purpose: "physical", shape, damageEligible: false, blocks: true }, position, rotationY);
+}
+/** Mirrors static scene-object physical colliders and the context's ground field into a physics backend.
+ * @capability world-physics-colliders Synchronize terrain and authored static colliders with a physics backend.
+ */
+export function syncWorldColliders(backend, ctx) {
+    const objectBodies = new Map();
+    let terrainBody = null;
+    let disposed = false;
+    function rebuildTerrain() {
+        if (terrainBody !== null)
+            backend.removeBody(terrainBody);
+        terrainBody = null;
+        const bounds = ctx.world.ground.bounds;
+        if (bounds === undefined)
+            return;
+        const columns = TERRAIN_SEGMENTS + 1;
+        const rows = TERRAIN_SEGMENTS + 1;
+        const heights = new Float32Array(columns * rows);
+        for (let row = 0; row < rows; row += 1) {
+            const z = -bounds.d / 2 + (row / TERRAIN_SEGMENTS) * bounds.d;
+            for (let column = 0; column < columns; column += 1) {
+                const x = -bounds.w / 2 + (column / TERRAIN_SEGMENTS) * bounds.w;
+                heights[row * columns + column] = ctx.world.ground.sampleHeight(x, z);
+            }
+        }
+        terrainBody = backend.addBody({
+            shape: { kind: "heightfield", rows, columns, heights, scale: [bounds.w / TERRAIN_SEGMENTS, 1, bounds.d / TERRAIN_SEGMENTS] },
+            position: [0, 0, 0],
+            kind: "static",
+            userData: { kind: "terrain" },
+        });
+    }
+    function syncObject(objectId) {
+        const old = objectBodies.get(objectId);
+        if (old !== undefined) {
+            backend.removeBody(old);
+            objectBodies.delete(objectId);
+        }
+        const object = ctx.scene.object.get(objectId);
+        if (object === null)
+            return;
+        const body = resolveColliders(ctx.scene.object.collidersOf(objectId)).find((collider) => collider.purpose === "physical");
+        if (body === undefined)
+            return;
+        const handle = backend.addBody({
+            shape: bodyShape(body.shape),
+            position: bodyPosition(body.shape, object.position, object.rotationY),
+            rotation: [0, Math.sin(object.rotationY / 2), 0, Math.cos(object.rotationY / 2)],
+            kind: "static",
+            userData: { kind: "object", instanceId: object.instanceId, catalogId: object.catalogId },
+        });
+        objectBodies.set(objectId, handle);
+    }
+    function sync() {
+        if (disposed)
+            return;
+        rebuildTerrain();
+        const ids = new Set(ctx.scene.object.ids());
+        for (const [objectId, handle] of objectBodies) {
+            if (!ids.has(objectId)) {
+                backend.removeBody(handle);
+                objectBodies.delete(objectId);
+            }
+        }
+        for (const objectId of ids)
+            syncObject(objectId);
+    }
+    const unsubscribe = ctx.scene.object.subscribe(sync);
+    sync();
+    return {
+        sync,
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            unsubscribe();
+            if (terrainBody !== null)
+                backend.removeBody(terrainBody);
+            terrainBody = null;
+            for (const handle of objectBodies.values())
+                backend.removeBody(handle);
+            objectBodies.clear();
+        },
+    };
+}

package/dist/random/rng.d.ts

@@ -20,10 +20,21 @@ export declare function randomSeedFrom(seed: number): RandomSeed;
  * instead of closing over a generator.
  */
 export declare function stepRandomSeed(seed: RandomSeed): readonly [value: number, next: RandomSeed];
+/** A {@link seededRng} stream: callable like any `() => number`, with its cursor readable and restorable for snapshots and replay. */
+export interface SeededRng {
+    (): number;
+    /** The current cursor; feed it back to {@link restore} (or a fresh stream's `restore`) to resume the exact sequence. */
+    state(): number;
+    restore(cursor: number): void;
+}
 /** Deterministic pseudo-random generator seeded from a string or number — same seed, same sequence.
  *
  * @capability seeded-random injected deterministic randomness for game logic — never `Math.random` in a simulation
  */
-export declare function seededRng(seed: string | number): () => number;
+export declare function seededRng(seed: string | number): SeededRng;
+/** The cursor of a seeded stream, or `null` for a generator that carries no state (an injected closure, `Math.random`). */
+export declare function rngStateOf(rng: () => number): number | null;
+/** Restore a seeded stream's cursor; a no-op for generators that carry no state. */
+export declare function restoreRng(rng: () => number, cursor: number): void;
 /** Derives independent, deterministic {@link seededRng} streams from one base seed, keyed by stream name. */
 export declare function seededStreams(seed: string | number): (stream: string) => () => number;

package/dist/random/rng.js

@@ -35,11 +35,28 @@ export function stepRandomSeed(seed) {
  */
 export function seededRng(seed) {
     let cursor = randomSeedFrom(hashSeed(seed));
-    return () => {
-        const [value, next] = stepRandomSeed(cursor);
-        cursor = next;
+    const next = () => {
+        const [value, following] = stepRandomSeed(cursor);
+        cursor = following;
         return value;
     };
+    const rng = next;
+    rng.state = () => cursor;
+    rng.restore = (value) => {
+        cursor = randomSeedFrom(value);
+    };
+    return rng;
+}
+/** The cursor of a seeded stream, or `null` for a generator that carries no state (an injected closure, `Math.random`). */
+export function rngStateOf(rng) {
+    const candidate = rng;
+    return typeof candidate.state === "function" ? candidate.state() : null;
+}
+/** Restore a seeded stream's cursor; a no-op for generators that carry no state. */
+export function restoreRng(rng, cursor) {
+    const candidate = rng;
+    if (typeof candidate.restore === "function")
+        candidate.restore(cursor);
 }
 /** Derives independent, deterministic {@link seededRng} streams from one base seed, keyed by stream name. */
 export function seededStreams(seed) {

package/dist/render/environment.d.ts

@@ -0,0 +1,23 @@
+/** A declarative source for image-based scene lighting. */
+export type EnvironmentSource = 
+/** Procedural two-color sky probe, preserving the engine default. */
+{
+    kind: "gradient";
+    sky: string;
+    ground: string;
+    sun?: string;
+    intensity?: number;
+}
+/** Equirectangular HDR or EXR environment map loaded from `url`. */
+ | {
+    kind: "hdri";
+    url: string;
+    rotation?: number;
+    intensity?: number;
+}
+/** Six faces of a cube environment map, in three.js cube-loader order. */
+ | {
+    kind: "cube";
+    urls: [string, string, string, string, string, string];
+    intensity?: number;
+};

package/dist/render/environment.js

@@ -0,0 +1 @@
+export {};