@netforge/engine 0.0.0-stage → 0.1.0

package/dist/runtime/render/decals.js

@@ -0,0 +1,222 @@
+import { AdditiveBlending, DoubleSide, DynamicDrawUsage, InstancedBufferAttribute, InstancedBufferGeometry, Mesh, MeshBasicNodeMaterial, NormalBlending, PlaneGeometry, } from "three/webgpu";
+import { abs, atan, clamp, cos, float, instancedBufferAttribute, length, max, mix, positionGeometry, pow, select, sin, smoothstep, step, uniform, uv, vec3, vec4, } from "three/tsl";
+import { ParticleRing } from "./particles.js";
+const DECAL_INDEX = { scorch: 0, splat: 1, ring: 2 };
+function quadGeometry(capacity) {
+    const quad = new PlaneGeometry(1, 1);
+    const g = new InstancedBufferGeometry();
+    g.index = quad.index;
+    g.setAttribute("position", quad.getAttribute("position"));
+    g.setAttribute("uv", quad.getAttribute("uv"));
+    g.instanceCount = capacity;
+    return g;
+}
+function vec4Attr(capacity) {
+    const a = new InstancedBufferAttribute(new Float32Array(capacity * 4), 4);
+    a.setUsage(DynamicDrawUsage);
+    return a;
+}
+function upload(ring, attrs) {
+    const ranges = ring.flush();
+    if (ranges.length === 0)
+        return;
+    for (const a of attrs) {
+        a.clearUpdateRanges();
+        for (const [s, c] of ranges)
+            a.addUpdateRange(s * 4, c * 4);
+        a.needsUpdate = true;
+    }
+}
+const hexRgb = (hex) => {
+    const r = ((hex >> 16) & 255) / 255;
+    const g = ((hex >> 8) & 255) / 255;
+    const b = (hex & 255) / 255;
+    return [r * r, g * g, b * b];
+};
+/**
+ * Ground decals (scorch marks, splats, rings) in one draw: flat quads on
+ * the floor, shapes drawn procedurally in the fragment stage (no textures),
+ * faded over their life. A ring buffer: the oldest decal is reused.
+ */
+export class GroundDecals {
+    time = uniform(0);
+    ring;
+    mesh;
+    a;
+    b;
+    c;
+    rand;
+    /** Height above the floor, m. */
+    floorY = 0.012;
+    constructor(parent, capacity = 256, random = Math.random, look) {
+        this.ring = new ParticleRing(capacity);
+        this.rand = random;
+        this.a = vec4Attr(capacity); // x, z, rotation, size
+        this.b = vec4Attr(capacity); // t0, life, kind, opacity
+        this.c = vec4Attr(capacity); // r, g, b, seed
+        for (let i = 0; i < capacity; i++)
+            this.b.array[i * 4 + 1] = 0;
+        const A = instancedBufferAttribute(this.a, "vec4");
+        const B = instancedBufferAttribute(this.b, "vec4");
+        const C = instancedBufferAttribute(this.c, "vec4");
+        const age = this.time.sub(B.x);
+        const life = max(B.y, float(1e-4));
+        const t = clamp(age.div(life), 0, 1);
+        const alive = step(0, age).mul(step(age, life));
+        const pop = smoothstep(0, 0.12, age).mul(0.25).add(0.75);
+        const size = A.w.mul(pop).mul(alive);
+        const cs = cos(A.z);
+        const sn = sin(A.z);
+        const cx = positionGeometry.x.mul(size);
+        const cz = positionGeometry.y.mul(size);
+        const mat = new MeshBasicNodeMaterial();
+        mat.positionNode = vec3(A.x.add(cx.mul(cs)).sub(cz.mul(sn)), float(this.floorY), A.y.add(cx.mul(sn)).add(cz.mul(cs)));
+        const p = uv().sub(0.5);
+        const r = length(p).mul(2);
+        const ang = atan(p.y, p.x).add(C.w);
+        const scorchEdge = float(0.78).add(sin(ang.mul(7)).mul(0.1)).add(sin(ang.mul(13).add(1.7)).mul(0.05));
+        const scorch = smoothstep(scorchEdge, scorchEdge.mul(0.35), r);
+        const lobes = pow(max(sin(ang.mul(5)), float(0)), float(3));
+        const splatEdge = float(0.5).add(lobes.mul(0.32)).add(sin(ang.mul(11).add(0.6)).mul(0.07));
+        const splat = smoothstep(splatEdge, splatEdge.sub(0.07), r);
+        const ringA = smoothstep(0.1, 0.0, abs(r.sub(0.82)));
+        const shape = select(B.z.lessThan(0.5), scorch, select(B.z.lessThan(1.5), splat, ringA));
+        const fade = float(1).sub(smoothstep(0.55, 1, t));
+        mat.colorNode = vec4(C.xyz, 1);
+        mat.opacityNode = shape.mul(fade).mul(B.w).mul(alive);
+        // An art style's decal look replaces the shading (same quads, same draw).
+        const styled = look?.({ uv: uv(), r, angle: ang, kind: B.z, t, color: C.xyz, shape, opacity: B.w.mul(alive) });
+        if (styled) {
+            mat.colorNode = vec4(styled.color, 1);
+            mat.opacityNode = styled.opacity;
+        }
+        mat.transparent = true;
+        mat.depthWrite = false;
+        mat.polygonOffset = true;
+        mat.polygonOffsetFactor = -2;
+        mat.polygonOffsetUnits = -2;
+        mat.blending = NormalBlending;
+        mat.side = DoubleSide;
+        this.mesh = new Mesh(quadGeometry(capacity), mat);
+        this.mesh.frustumCulled = false;
+        this.mesh.renderOrder = 1;
+        this.mesh.receiveShadow = false;
+        this.mesh.name = "GroundDecals";
+        parent.add(this.mesh);
+    }
+    /** Stamp a decal on the floor at (x, z). */
+    add(kind, x, z, opts = {}) {
+        const [s] = this.ring.alloc(1);
+        if (s === undefined)
+            return;
+        const o = s * 4;
+        const A = this.a.array;
+        const B = this.b.array;
+        const C = this.c.array;
+        A[o] = x;
+        A[o + 1] = z;
+        A[o + 2] = opts.rotation ?? this.rand() * Math.PI * 2;
+        A[o + 3] = opts.size ?? 1.6;
+        B[o] = this.time.value;
+        B[o + 1] = opts.life ?? 6;
+        B[o + 2] = DECAL_INDEX[kind];
+        B[o + 3] = opts.opacity ?? 0.75;
+        const [r, g, b] = hexRgb(opts.color ?? (kind === "scorch" ? 0x0a0806 : 0x6a2c08));
+        const glow = opts.glow ?? 1;
+        C[o] = r * glow;
+        C[o + 1] = g * glow;
+        C[o + 2] = b * glow;
+        C[o + 3] = this.rand() * 6.283;
+    }
+    update(timeSeconds) {
+        this.time.value = timeSeconds;
+        upload(this.ring, [this.a, this.b, this.c]);
+    }
+    dispose() {
+        this.mesh.removeFromParent();
+        this.mesh.geometry.dispose();
+        this.mesh.material.dispose();
+    }
+}
+/**
+ * Expanding shockwave rings on the floor (nova blasts, landings, dash
+ * starts): one additive draw, pooled. Generalized from EMBERWATCH's rings.
+ */
+export class GroundRings {
+    time = uniform(0);
+    ring;
+    mesh;
+    a;
+    b;
+    /** Rings fired so far (playtest checks). */
+    fired = 0;
+    constructor(parent, capacity = 32, look) {
+        this.ring = new ParticleRing(capacity);
+        this.a = vec4Attr(capacity); // x, z, t0, radius
+        this.b = vec4Attr(capacity); // r, g, b, duration
+        for (let i = 0; i < capacity; i++)
+            this.a.array[i * 4 + 2] = -1e6;
+        const A = instancedBufferAttribute(this.a, "vec4");
+        const B = instancedBufferAttribute(this.b, "vec4");
+        const age = this.time.sub(A.z);
+        const dur = max(B.w, float(1e-4));
+        const t = clamp(age.div(dur), 0, 1);
+        const alive = step(0, age).mul(step(age, dur));
+        const ease = float(1).sub(pow(float(1).sub(t), float(3)));
+        const scale = A.w.mul(mix(float(0.3), float(1), ease)).mul(2).mul(alive);
+        const mat = new MeshBasicNodeMaterial();
+        mat.positionNode = vec3(A.x.add(positionGeometry.x.mul(scale)), float(0.05), A.y.add(positionGeometry.y.mul(scale)));
+        const r = length(uv().sub(0.5)).mul(2);
+        const width = mix(float(0.22), float(0.06), t);
+        const band = smoothstep(float(1).sub(width), float(0.97), r).mul(smoothstep(1.0, 0.97, r));
+        const inner = smoothstep(0.2, 1, r).mul(0.18).mul(step(r, float(1)));
+        mat.colorNode = vec4(B.xyz, 1);
+        mat.opacityNode = band.add(inner).mul(float(1).sub(t)).mul(alive);
+        mat.transparent = true;
+        mat.depthWrite = false;
+        mat.blending = AdditiveBlending;
+        const styled = look?.({ uv: uv(), r, t, alive, color: B.xyz });
+        if (styled) {
+            mat.colorNode = vec4(styled.color, 1);
+            mat.opacityNode = styled.opacity;
+            if (styled.blending)
+                mat.blending = styled.blending === "add" ? AdditiveBlending : NormalBlending;
+        }
+        mat.side = DoubleSide;
+        mat.fog = false;
+        this.mesh = new Mesh(quadGeometry(capacity), mat);
+        this.mesh.frustumCulled = false;
+        this.mesh.renderOrder = 15;
+        this.mesh.name = "GroundRings";
+        parent.add(this.mesh);
+    }
+    /** A ring at (x, z) reaching `radius` m. */
+    fire(x, z, radius, opts = {}) {
+        const [s] = this.ring.alloc(1);
+        if (s === undefined)
+            return;
+        this.fired++;
+        const o = s * 4;
+        const A = this.a.array;
+        const B = this.b.array;
+        A[o] = x;
+        A[o + 1] = z;
+        A[o + 2] = this.time.value;
+        A[o + 3] = radius;
+        const [r, g, b] = hexRgb(opts.color ?? 0xffb347);
+        const glow = opts.glow ?? 1.6;
+        B[o] = r * glow;
+        B[o + 1] = g * glow;
+        B[o + 2] = b * glow;
+        B[o + 3] = opts.duration ?? 0.32;
+    }
+    update(timeSeconds) {
+        this.time.value = timeSeconds;
+        upload(this.ring, [this.a, this.b]);
+    }
+    dispose() {
+        this.mesh.removeFromParent();
+        this.mesh.geometry.dispose();
+        this.mesh.material.dispose();
+    }
+}

package/dist/runtime/render/highlight.d.ts

@@ -0,0 +1,29 @@
+import { Mesh } from "three/webgpu";
+import type { ColorRepresentation, Object3D } from "three/webgpu";
+export interface HeroHighlightOptions {
+    /** Rim glow colour, or null for none. Default warm white. */
+    readonly rim?: ColorRepresentation | null;
+    /** Rim brightness. Default 1.6 (bloom picks it up above 1). */
+    readonly rimStrength?: number;
+    /** Rim falloff exponent: higher is a thinner edge. Default 2.4. */
+    readonly rimPower?: number;
+    /** Outline colour, or null for none. Default near-black. */
+    readonly outline?: ColorRepresentation | null;
+    /** Outline thickness in metres (world). Default 0.03. */
+    readonly outlineWidth?: number;
+}
+export declare class HeroHighlight {
+    readonly root: Object3D;
+    /** The extra draws (outline hulls and rim shells), for tests and counting. */
+    readonly parts: Mesh[];
+    private readonly rimStrength;
+    private base;
+    constructor(root: Object3D, opts?: HeroHighlightOptions);
+    /** A draw of `mesh`'s geometry (and skeleton) with another material, as its child at identity. */
+    private extra;
+    /** 0..1 fade on top of the rim strength and outline (0 hides both). */
+    set strength(v: number);
+    /** Show or hide every extra draw. */
+    set visible(v: boolean);
+    dispose(): void;
+}

package/dist/runtime/render/highlight.js

@@ -0,0 +1,110 @@
+/**
+ * Make one character pop off the scene (the local hero, a selected unit):
+ * an inverted-hull outline and an additive rim glow, both as extra draws
+ * that share each mesh's geometry (and skeleton, so they follow the
+ * animation). The character's own materials are never touched, so a model
+ * shared with teammates stays as it was.
+ *
+ *   const hl = new HeroHighlight(character.root, { rim: "#ffe6a8", outline: "#1a0f05" });
+ *   hl.strength = 0.5;   // fade it (iframes, downed)
+ *   hl.dispose();        // remove the extra draws
+ */
+import { isSprite } from "./sprite.js";
+import { AdditiveBlending, BackSide, Color, FrontSide, Mesh, MeshBasicNodeMaterial, SkinnedMesh } from "three/webgpu";
+import { abs, dot, float, normalLocal, normalView, positionLocal, positionViewDirection, pow, uniform, vec3 } from "three/tsl";
+/** Product of the scales from `mesh` up to and including `root` (world size of one local unit). */
+function scaleTo(mesh, root) {
+    let s = 1;
+    for (let o = mesh; o; o = o.parent) {
+        s *= Math.max(Math.abs(o.scale.x), Math.abs(o.scale.y), Math.abs(o.scale.z)) || 1;
+        if (o === root)
+            break;
+    }
+    return s;
+}
+export class HeroHighlight {
+    root;
+    /** The extra draws (outline hulls and rim shells), for tests and counting. */
+    parts = [];
+    rimStrength = uniform(1);
+    base;
+    constructor(root, opts = {}) {
+        this.root = root;
+        const rim = opts.rim === undefined ? "#fff1cc" : opts.rim;
+        const outline = opts.outline === undefined ? "#120a04" : opts.outline;
+        const width = opts.outlineWidth ?? 0.03;
+        this.base = opts.rimStrength ?? 1.6;
+        this.rimStrength.value = this.base;
+        const meshes = [];
+        root.traverse((o) => {
+            // Sprites (render/sprite.ts) draw their own 1 px rim; a hull around a flat quad would cover it.
+            if (o.isMesh && !isSprite(o.geometry))
+                meshes.push(o);
+        });
+        const outlineColor = outline === null ? null : new Color(outline);
+        const rimColor = rim === null ? null : new Color(rim);
+        const facing = abs(dot(normalView, positionViewDirection));
+        const edge = pow(float(1).sub(facing), opts.rimPower ?? 2.4);
+        for (const mesh of meshes) {
+            // Widths are world metres; each mesh inflates in its own local units.
+            const unit = scaleTo(mesh, root);
+            const made = [];
+            if (outlineColor) {
+                const m = new MeshBasicNodeMaterial({ side: BackSide });
+                m.colorNode = vec3(outlineColor.r, outlineColor.g, outlineColor.b);
+                m.positionNode = positionLocal.add(normalLocal.mul(float(width / unit)));
+                made.push([this.extra(mesh, m), "HeroOutline"]);
+            }
+            if (rimColor) {
+                const m = new MeshBasicNodeMaterial({ side: FrontSide, transparent: true, depthWrite: false, blending: AdditiveBlending });
+                m.colorNode = vec3(rimColor.r, rimColor.g, rimColor.b).mul(edge).mul(this.rimStrength);
+                m.positionNode = positionLocal.add(normalLocal.mul(float(0.003 / unit)));
+                made.push([this.extra(mesh, m), "HeroRim"]);
+            }
+            for (const [extra, name] of made) {
+                extra.name = name;
+                // The outline draws before the body, the rim after it.
+                extra.renderOrder = name === "HeroOutline" ? -1 : 1;
+                mesh.add(extra);
+                this.parts.push(extra);
+            }
+        }
+    }
+    /** A draw of `mesh`'s geometry (and skeleton) with another material, as its child at identity. */
+    extra(mesh, material) {
+        let extra;
+        if (mesh.isSkinnedMesh === true) {
+            const s = mesh;
+            const e = new SkinnedMesh(mesh.geometry, material);
+            e.bindMode = s.bindMode;
+            e.bind(s.skeleton, s.bindMatrix);
+            extra = e;
+        }
+        else
+            extra = new Mesh(mesh.geometry, material);
+        extra.castShadow = false;
+        extra.receiveShadow = false;
+        extra.frustumCulled = false;
+        return extra;
+    }
+    /** 0..1 fade on top of the rim strength and outline (0 hides both). */
+    set strength(v) {
+        const k = Math.max(0, Math.min(1, v));
+        this.rimStrength.value = this.base * k;
+        for (const p of this.parts)
+            if (p.name === "HeroOutline")
+                p.visible = k > 0.05;
+    }
+    /** Show or hide every extra draw. */
+    set visible(v) {
+        for (const p of this.parts)
+            p.visible = v;
+    }
+    dispose() {
+        for (const p of this.parts) {
+            p.removeFromParent();
+            p.material.dispose();
+        }
+        this.parts.length = 0;
+    }
+}

package/dist/runtime/render/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @netforge/engine/runtime render module: lighting
+ * with a following shadow, post-processing (bloom, grade, tone mapping,
+ * FXAA, outline), atmosphere, quality tiers and dynamic resolution, GPU
+ * particles, ground decals and rings, skinned and VAT-animated characters,
+ * and `createRenderStack`, which wires them in one call.
+ * WebGPU first, WebGL2 fallback: everything here runs on both backends.
+ */
+export { createRenderStack } from "./stack.js";
+export type { RenderStack, RenderStackOptions } from "./stack.js";
+export { LightingRig, snapToTexel } from "./lighting.js";
+export type { LightingOptions } from "./lighting.js";
+export { PostFX } from "./post.js";
+export type { PostFXOptions } from "./post.js";
+export { Atmosphere } from "./atmosphere.js";
+export type { AtmosphereOptions } from "./atmosphere.js";
+export { QualityManager, DynamicResolution, detectTier, browserHints, qualitySettings, QUALITY_TIERS } from "./quality.js";
+export type { QualityTier, QualitySettings, DeviceHints, DynamicResolutionOptions } from "./quality.js";
+export { GpuParticles, ParticleRing, PARTICLE_PRESETS } from "./particles.js";
+export type { ParticleBurstOptions as GpuBurstOptions, ParticlePreset, ParticlePresetName, GpuParticlesOptions, ParticleShade, ParticleShadeInput, ParticleShadeOutput } from "./particles.js";
+export { GroundDecals, GroundRings } from "./decals.js";
+export type { DecalKind, DecalOptions, RingOptions } from "./decals.js";
+export { AnimatedCharacter, locomotionState, DEFAULT_LOCOMOTION } from "./animation.js";
+export type { AnimatedCharacterOptions, LocomotionState, LocomotionThresholds, PlayOptions as AnimationPlayOptions } from "./animation.js";
+export { bakeVertexAnimation, VatCrowd } from "./vat.js";
+export type { VertexAnimation, VatClip, BakeOptions, VatCrowdOptions } from "./vat.js";
+export { applyCrowdMotion, AnimatedCrowd, toNodeMaterial } from "./crowd-motion.js";
+export type { CrowdMotionOptions, CrowdAttributes } from "./crowd-motion.js";
+export { billboardWorld, isSprite, markSprite, markSpriteMaterial, SPRITE_TEXEL, spriteBillboardNode, spriteScale } from "./sprite.js";
+export { HeroHighlight } from "./highlight.js";
+export type { HeroHighlightOptions } from "./highlight.js";
+export { buildSegmentRig } from "./rig.js";
+export type { SegmentRig, SegmentRigOptions } from "./rig.js";
+export { resolveLook, LOOK_PRESETS } from "./presets.js";
+export type { Look, LookPreset, LightingPreset, AtmospherePreset, GradePreset } from "./presets.js";

package/dist/runtime/render/index.js

@@ -0,0 +1,22 @@
+/**
+ * @netforge/engine/runtime render module: lighting
+ * with a following shadow, post-processing (bloom, grade, tone mapping,
+ * FXAA, outline), atmosphere, quality tiers and dynamic resolution, GPU
+ * particles, ground decals and rings, skinned and VAT-animated characters,
+ * and `createRenderStack`, which wires them in one call.
+ * WebGPU first, WebGL2 fallback: everything here runs on both backends.
+ */
+export { createRenderStack } from "./stack.js";
+export { LightingRig, snapToTexel } from "./lighting.js";
+export { PostFX } from "./post.js";
+export { Atmosphere } from "./atmosphere.js";
+export { QualityManager, DynamicResolution, detectTier, browserHints, qualitySettings, QUALITY_TIERS } from "./quality.js";
+export { GpuParticles, ParticleRing, PARTICLE_PRESETS } from "./particles.js";
+export { GroundDecals, GroundRings } from "./decals.js";
+export { AnimatedCharacter, locomotionState, DEFAULT_LOCOMOTION } from "./animation.js";
+export { bakeVertexAnimation, VatCrowd } from "./vat.js";
+export { applyCrowdMotion, AnimatedCrowd, toNodeMaterial } from "./crowd-motion.js";
+export { billboardWorld, isSprite, markSprite, markSpriteMaterial, SPRITE_TEXEL, spriteBillboardNode, spriteScale } from "./sprite.js";
+export { HeroHighlight } from "./highlight.js";
+export { buildSegmentRig } from "./rig.js";
+export { resolveLook, LOOK_PRESETS } from "./presets.js";

package/dist/runtime/render/lighting.d.ts

@@ -0,0 +1,50 @@
+import { AmbientLight, DirectionalLight, HemisphereLight, Object3D } from "three/webgpu";
+import type { Scene, WebGPURenderer } from "three/webgpu";
+import type { LightingPreset, LookPreset } from "./presets.js";
+export type Vec3Tuple = [number, number, number];
+/**
+ * Snap a world point to the shadow map's texel grid in light space, so a
+ * shadow camera that follows the player moves in whole texels and the
+ * shadow edges never shimmer. `dir` is the light's travel-from direction
+ * (unit), `texel` the world size of one shadow texel.
+ */
+export declare function snapToTexel(p: readonly [number, number, number], dir: readonly [number, number, number], texel: number): Vec3Tuple;
+export interface LightingOptions {
+    readonly preset?: LookPreset;
+    /** Override pieces of the preset. */
+    readonly overrides?: Partial<LightingPreset>;
+    /** Shadow map size in texels; 0 turns shadows off. Default 2048. */
+    readonly shadowMapSize?: number;
+    /** Half-size of the square area around the focus that receives shadows, m. Default 26. */
+    readonly shadowExtent?: number;
+}
+/**
+ * Hemisphere + one directional light whose single shadow map follows a
+ * focus point (the player), snapped to texels. Sized for a top-down or
+ * third-person view: one tuned map beats cascades at this camera distance.
+ */
+export declare class LightingRig {
+    private readonly renderer;
+    readonly root: Object3D<import("three").Object3DEventMap>;
+    readonly hemi: HemisphereLight;
+    readonly sun: DirectionalLight;
+    readonly ambient: AmbientLight;
+    private dir;
+    private extent;
+    private mapSize;
+    private readonly distance;
+    constructor(renderer: WebGPURenderer, scene: Scene, opts?: LightingOptions);
+    /** World size of one shadow texel at the current settings. */
+    get texel(): number;
+    get shadowsOn(): boolean;
+    /** Change the shadow resolution (quality tier); 0 turns shadows off. */
+    setShadowMapSize(size: number): void;
+    /** Half-size of the shadowed square around the focus, m (fit it to what the camera shows). */
+    setShadowExtent(extent: number): void;
+    private applyExtent;
+    /** Move the shadowed area to follow a focus point (texel-snapped). */
+    follow(x: number, y: number, z: number): void;
+    /** Switch the preset colors and intensities in place. */
+    setPreset(preset: LookPreset, overrides?: Partial<LightingPreset>): void;
+    dispose(): void;
+}

package/dist/runtime/render/lighting.js

@@ -0,0 +1,142 @@
+import { AmbientLight, Color, DirectionalLight, HemisphereLight, Object3D, PCFShadowMap } from "three/webgpu";
+import { resolveLook } from "./presets.js";
+/**
+ * Snap a world point to the shadow map's texel grid in light space, so a
+ * shadow camera that follows the player moves in whole texels and the
+ * shadow edges never shimmer. `dir` is the light's travel-from direction
+ * (unit), `texel` the world size of one shadow texel.
+ */
+export function snapToTexel(p, dir, texel) {
+    const [dx, dy, dz] = normalize(dir);
+    // A right/up basis perpendicular to the light direction.
+    let rx = dz;
+    let ry = 0;
+    let rz = -dx;
+    const rl = Math.hypot(rx, ry, rz);
+    if (rl < 1e-6) {
+        rx = 1;
+        ry = 0;
+        rz = 0;
+    }
+    else {
+        rx /= rl;
+        rz /= rl;
+    }
+    // up = dir x right
+    const ux = dy * rz - dz * ry;
+    const uy = dz * rx - dx * rz;
+    const uz = dx * ry - dy * rx;
+    const a = p[0] * rx + p[1] * ry + p[2] * rz;
+    const b = p[0] * ux + p[1] * uy + p[2] * uz;
+    const c = p[0] * dx + p[1] * dy + p[2] * dz;
+    const sa = texel > 0 ? Math.round(a / texel) * texel : a;
+    const sb = texel > 0 ? Math.round(b / texel) * texel : b;
+    return [rx * sa + ux * sb + dx * c, ry * sa + uy * sb + dy * c, rz * sa + uz * sb + dz * c];
+}
+function normalize(v) {
+    const l = Math.hypot(v[0], v[1], v[2]) || 1;
+    return [v[0] / l, v[1] / l, v[2] / l];
+}
+/**
+ * Hemisphere + one directional light whose single shadow map follows a
+ * focus point (the player), snapped to texels. Sized for a top-down or
+ * third-person view: one tuned map beats cascades at this camera distance.
+ */
+export class LightingRig {
+    renderer;
+    root = new Object3D();
+    hemi;
+    sun;
+    ambient;
+    dir;
+    extent;
+    mapSize;
+    distance = 60;
+    constructor(renderer, scene, opts = {}) {
+        this.renderer = renderer;
+        const p = { ...resolveLook(opts.preset).lighting, ...opts.overrides };
+        this.hemi = new HemisphereLight(p.sky, p.ground, p.hemi);
+        this.sun = new DirectionalLight(p.sun, p.sunIntensity);
+        this.ambient = new AmbientLight(p.ambientColor, p.ambient);
+        this.dir = normalize(p.sunDir);
+        this.extent = opts.shadowExtent ?? 26;
+        this.mapSize = 0;
+        this.root.name = "LightingRig";
+        this.root.add(this.hemi, this.sun, this.sun.target, this.ambient);
+        scene.add(this.root);
+        renderer.shadowMap.type = PCFShadowMap;
+        this.setShadowMapSize(opts.shadowMapSize ?? 2048);
+        this.sun.shadow.intensity = p.shadowStrength;
+        this.follow(0, 0, 0);
+    }
+    /** World size of one shadow texel at the current settings. */
+    get texel() {
+        return this.mapSize > 0 ? (this.extent * 2) / this.mapSize : 0;
+    }
+    get shadowsOn() {
+        return this.mapSize > 0;
+    }
+    /** Change the shadow resolution (quality tier); 0 turns shadows off. */
+    setShadowMapSize(size) {
+        const s = Math.max(0, Math.floor(size));
+        if (s === this.mapSize)
+            return;
+        this.mapSize = s;
+        const on = s > 0;
+        this.renderer.shadowMap.enabled = on || this.renderer.shadowMap.enabled;
+        this.sun.castShadow = on;
+        if (!on)
+            return;
+        const sh = this.sun.shadow;
+        sh.mapSize.set(s, s);
+        // Bias tuned for a 1-2 texel slope at these extents; normalBias kills acne on curved crowds.
+        sh.bias = -0.0005;
+        sh.normalBias = 0.03;
+        sh.radius = 2.5;
+        this.applyExtent();
+        // A resized map needs a new render target.
+        sh.map?.dispose();
+        sh.map = null;
+    }
+    /** Half-size of the shadowed square around the focus, m (fit it to what the camera shows). */
+    setShadowExtent(extent) {
+        this.extent = Math.max(2, extent);
+        this.applyExtent();
+    }
+    applyExtent() {
+        const cam = this.sun.shadow.camera;
+        cam.left = -this.extent;
+        cam.right = this.extent;
+        cam.top = this.extent;
+        cam.bottom = -this.extent;
+        cam.near = 1;
+        cam.far = this.distance * 2 + 20;
+        cam.updateProjectionMatrix();
+    }
+    /** Move the shadowed area to follow a focus point (texel-snapped). */
+    follow(x, y, z) {
+        const [sx, sy, sz] = snapToTexel([x, y, z], this.dir, this.texel);
+        const d = this.distance;
+        this.sun.position.set(sx + this.dir[0] * d, sy + this.dir[1] * d, sz + this.dir[2] * d);
+        this.sun.target.position.set(sx, sy, sz);
+        this.sun.updateMatrixWorld();
+        this.sun.target.updateMatrixWorld();
+    }
+    /** Switch the preset colors and intensities in place. */
+    setPreset(preset, overrides = {}) {
+        const p = { ...resolveLook(preset).lighting, ...overrides };
+        this.hemi.color = new Color(p.sky);
+        this.hemi.groundColor = new Color(p.ground);
+        this.hemi.intensity = p.hemi;
+        this.sun.color = new Color(p.sun);
+        this.sun.intensity = p.sunIntensity;
+        this.ambient.color = new Color(p.ambientColor);
+        this.ambient.intensity = p.ambient;
+        this.sun.shadow.intensity = p.shadowStrength;
+        this.dir = normalize(p.sunDir);
+    }
+    dispose() {
+        this.sun.shadow.map?.dispose();
+        this.root.removeFromParent();
+    }
+}