@netforge/engine 0.0.0-stage → 0.1.0

package/dist/runtime/interpolate.js

@@ -0,0 +1,13 @@
+/** Linear interpolation. */
+export const lerp = (a, b, t) => a + (b - a) * t;
+/** Interpolate angles along the shortest arc (radians). */
+export function lerpAngle(a, b, t) {
+    let d = (b - a) % (Math.PI * 2);
+    if (d > Math.PI)
+        d -= Math.PI * 2;
+    else if (d < -Math.PI)
+        d += Math.PI * 2;
+    return a + d * t;
+}
+/** Frame-rate independent exponential smoothing factor for a rate in 1/s. */
+export const damp = (rate, dt) => 1 - Math.exp(-rate * dt);

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

@@ -0,0 +1,63 @@
+import { AnimationMixer } from "three/webgpu";
+import type { AnimationClip, Object3D } from "three/webgpu";
+export type LocomotionState = "idle" | "walk" | "run";
+export interface LocomotionThresholds {
+    /** Speed (m/s) at and above which the character walks. Default 0.4. */
+    readonly walk: number;
+    /** Speed at and above which it runs. Default 4. */
+    readonly run: number;
+    /** Hysteresis band, m/s, so speeds near a threshold do not flicker. Default 0.25. */
+    readonly band: number;
+}
+export declare const DEFAULT_LOCOMOTION: LocomotionThresholds;
+/** The locomotion state for a speed, with hysteresis around the current state. Pure. */
+export declare function locomotionState(speed: number, current: LocomotionState, t?: LocomotionThresholds): LocomotionState;
+export interface AnimatedCharacterOptions {
+    /** Clip names for each locomotion state. Default "idle", "walk", "run". */
+    readonly clips?: Partial<Record<LocomotionState, string>>;
+    readonly thresholds?: Partial<LocomotionThresholds>;
+    /** Speed (m/s) at which the walk and run clips play at timeScale 1 (foot speed matching). */
+    readonly walkSpeed?: number;
+    readonly runSpeed?: number;
+    /** Default crossfade, s. Default 0.2. */
+    readonly fade?: number;
+}
+export interface PlayOptions {
+    readonly fade?: number;
+    readonly loop?: "repeat" | "once";
+    readonly timeScale?: number;
+}
+/**
+ * A skinned character (glTF or procedural) with an AnimationMixer:
+ * `setSpeed(mps)` drives idle/walk/run with crossfades and playback rate
+ * matched to ground speed; `oneShot("attack")` plays once and blends back
+ * to locomotion; `play(name)` for anything else. Call `update(dt)` per frame.
+ */
+export declare class AnimatedCharacter {
+    readonly root: Object3D;
+    readonly mixer: AnimationMixer;
+    private readonly actions;
+    private readonly names;
+    private readonly th;
+    private readonly walkSpeed;
+    private readonly runSpeed;
+    private readonly fade;
+    private current;
+    private loco;
+    private oneShotAction;
+    private speed;
+    constructor(root: Object3D, clips: readonly AnimationClip[], opts?: AnimatedCharacterOptions);
+    has(name: string): boolean;
+    get state(): LocomotionState;
+    get playing(): string | null;
+    /** Crossfade to a clip. Returns false if the clip does not exist. */
+    play(name: string, opts?: PlayOptions): boolean;
+    /** Play a clip once (attack, hit), then return to locomotion. */
+    oneShot(name: string, opts?: Omit<PlayOptions, "loop">): boolean;
+    /** Ground speed in m/s; picks the locomotion clip and its playback rate. */
+    setSpeed(mps: number): void;
+    private rateFor;
+    private enterLocomotion;
+    update(dt: number): void;
+    dispose(): void;
+}

package/dist/runtime/render/animation.js

@@ -0,0 +1,128 @@
+import { AnimationMixer, LoopOnce, LoopRepeat } from "three/webgpu";
+export const DEFAULT_LOCOMOTION = { walk: 0.4, run: 4, band: 0.25 };
+/** The locomotion state for a speed, with hysteresis around the current state. Pure. */
+export function locomotionState(speed, current, t = DEFAULT_LOCOMOTION) {
+    const up = (th) => speed >= th + t.band;
+    const down = (th) => speed < th - t.band;
+    switch (current) {
+        case "idle":
+            return up(t.run) ? "run" : up(t.walk) ? "walk" : "idle";
+        case "walk":
+            return up(t.run) ? "run" : down(t.walk) ? "idle" : "walk";
+        case "run":
+            return down(t.walk) ? "idle" : down(t.run) ? "walk" : "run";
+    }
+}
+/**
+ * A skinned character (glTF or procedural) with an AnimationMixer:
+ * `setSpeed(mps)` drives idle/walk/run with crossfades and playback rate
+ * matched to ground speed; `oneShot("attack")` plays once and blends back
+ * to locomotion; `play(name)` for anything else. Call `update(dt)` per frame.
+ */
+export class AnimatedCharacter {
+    root;
+    mixer;
+    actions = new Map();
+    names;
+    th;
+    walkSpeed;
+    runSpeed;
+    fade;
+    current = null;
+    loco = "idle";
+    oneShotAction = null;
+    speed = 0;
+    constructor(root, clips, opts = {}) {
+        this.root = root;
+        this.mixer = new AnimationMixer(root);
+        for (const c of clips)
+            this.actions.set(c.name, this.mixer.clipAction(c));
+        this.names = { idle: "idle", walk: "walk", run: "run", ...opts.clips };
+        this.th = { ...DEFAULT_LOCOMOTION, ...opts.thresholds };
+        this.walkSpeed = opts.walkSpeed ?? 2;
+        this.runSpeed = opts.runSpeed ?? 6;
+        this.fade = opts.fade ?? 0.2;
+        this.mixer.addEventListener("finished", (e) => {
+            if (e.action === this.oneShotAction) {
+                this.oneShotAction = null;
+                this.enterLocomotion(this.fade, true);
+            }
+        });
+        this.enterLocomotion(0, true);
+    }
+    has(name) {
+        return this.actions.has(name);
+    }
+    get state() {
+        return this.loco;
+    }
+    get playing() {
+        return this.current?.getClip().name ?? null;
+    }
+    /** Crossfade to a clip. Returns false if the clip does not exist. */
+    play(name, opts = {}) {
+        const next = this.actions.get(name);
+        if (!next)
+            return false;
+        const fade = opts.fade ?? this.fade;
+        next.reset();
+        next.enabled = true;
+        next.setEffectiveWeight(1);
+        next.setEffectiveTimeScale(opts.timeScale ?? 1);
+        if (opts.loop === "once") {
+            next.setLoop(LoopOnce, 1);
+            next.clampWhenFinished = true;
+        }
+        else
+            next.setLoop(LoopRepeat, Infinity);
+        if (this.current && this.current !== next && fade > 0)
+            next.crossFadeFrom(this.current, fade, true);
+        else if (this.current && this.current !== next)
+            this.current.stop();
+        next.play();
+        this.current = next;
+        return true;
+    }
+    /** Play a clip once (attack, hit), then return to locomotion. */
+    oneShot(name, opts = {}) {
+        if (!this.play(name, { ...opts, loop: "once" }))
+            return false;
+        this.oneShotAction = this.current;
+        return true;
+    }
+    /** Ground speed in m/s; picks the locomotion clip and its playback rate. */
+    setSpeed(mps) {
+        this.speed = Math.max(0, mps);
+        if (this.oneShotAction)
+            return;
+        const next = locomotionState(this.speed, this.loco, this.th);
+        if (next !== this.loco) {
+            this.loco = next;
+            this.enterLocomotion(this.fade, false);
+        }
+        this.current?.setEffectiveTimeScale(this.rateFor(this.loco));
+    }
+    rateFor(s) {
+        if (s === "walk")
+            return Math.min(2, Math.max(0.5, this.speed / this.walkSpeed));
+        if (s === "run")
+            return Math.min(2, Math.max(0.6, this.speed / this.runSpeed));
+        return 1;
+    }
+    enterLocomotion(fade, recompute) {
+        if (recompute)
+            this.loco = locomotionState(this.speed, "idle", this.th);
+        const want = this.names[this.loco];
+        const name = this.actions.has(want) ? want : this.names.idle;
+        if (this.current?.getClip().name === name && this.current.isRunning())
+            return;
+        this.play(name, { fade, timeScale: this.rateFor(this.loco) });
+    }
+    update(dt) {
+        this.mixer.update(dt);
+    }
+    dispose() {
+        this.mixer.stopAllAction();
+        this.mixer.uncacheRoot(this.root);
+    }
+}

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

@@ -0,0 +1,32 @@
+import { Color } from "three/webgpu";
+import type { Scene } from "three/webgpu";
+import type { AtmospherePreset, LookPreset } from "./presets.js";
+export interface AtmosphereOptions {
+    readonly preset?: LookPreset;
+    readonly overrides?: Partial<AtmospherePreset>;
+    /** Draw the sky gradient as the background (default true). */
+    readonly sky?: boolean;
+}
+/**
+ * Fog matched to a sky gradient, so the far ground melts into the
+ * background instead of meeting a hard color. Linear or exp2 distance fog,
+ * plus an optional low height fog (ground mist). Values live in uniforms:
+ * changing them never recompiles a shader.
+ */
+export declare class Atmosphere {
+    private readonly scene;
+    private readonly opts;
+    readonly fogColor: import("three/webgpu").UniformNode<"color", Color>;
+    readonly skyTop: import("three/webgpu").UniformNode<"color", Color>;
+    readonly near: import("three/webgpu").UniformNode<"float", number>;
+    readonly far: import("three/webgpu").UniformNode<"float", number>;
+    readonly density: import("three/webgpu").UniformNode<"float", number>;
+    readonly heightDensity: import("three/webgpu").UniformNode<"float", number>;
+    readonly heightTop: import("three/webgpu").UniformNode<"float", number>;
+    private mode;
+    private height;
+    constructor(scene: Scene, opts?: AtmosphereOptions);
+    setPreset(preset: LookPreset, overrides?: Partial<AtmospherePreset>): void;
+    private build;
+    dispose(): void;
+}

package/dist/runtime/render/atmosphere.js

@@ -0,0 +1,59 @@
+import { Color } from "three/webgpu";
+import { densityFogFactor, exponentialHeightFogFactor, fog, max, mix, rangeFogFactor, screenUV, smoothstep, uniform, } from "three/tsl";
+import { resolveLook } from "./presets.js";
+/**
+ * Fog matched to a sky gradient, so the far ground melts into the
+ * background instead of meeting a hard color. Linear or exp2 distance fog,
+ * plus an optional low height fog (ground mist). Values live in uniforms:
+ * changing them never recompiles a shader.
+ */
+export class Atmosphere {
+    scene;
+    opts;
+    fogColor = uniform(new Color());
+    skyTop = uniform(new Color());
+    near = uniform(30);
+    far = uniform(90);
+    density = uniform(0.015);
+    heightDensity = uniform(0);
+    heightTop = uniform(1);
+    mode = "linear";
+    height = false;
+    constructor(scene, opts = {}) {
+        this.scene = scene;
+        this.opts = opts;
+        this.setPreset(opts.preset ?? "studio", opts.overrides);
+    }
+    setPreset(preset, overrides = {}) {
+        const a = { ...resolveLook(preset).atmosphere, ...overrides };
+        this.fogColor.value.setHex(a.fog);
+        this.skyTop.value.setHex(a.skyTop);
+        this.near.value = a.near;
+        this.far.value = a.far;
+        this.density.value = a.density;
+        this.heightDensity.value = a.heightFog;
+        this.heightTop.value = a.heightFogTop;
+        const height = a.heightFog > 0;
+        const rebuild = a.mode !== this.mode || height !== this.height || this.scene.fogNode === undefined || this.scene.fogNode === null;
+        this.mode = a.mode;
+        this.height = height;
+        if (rebuild)
+            this.build(a.heightFog > 0);
+    }
+    build(height) {
+        const distance = this.mode === "exp2" ? densityFogFactor(this.density) : rangeFogFactor(this.near, this.far);
+        const factor = height ? max(distance, exponentialHeightFogFactor(this.heightDensity, this.heightTop)) : distance;
+        this.scene.fog = null;
+        this.scene.fogNode = fog(this.fogColor, factor);
+        if (this.opts.sky ?? true) {
+            // Screen-space gradient: horizon (fog) color low on screen, sky color at the top.
+            this.scene.backgroundNode = mix(this.skyTop, this.fogColor, smoothstep(0, 0.85, screenUV.y));
+        }
+        // A plain background color as well, for readers of scene.background.
+        this.scene.background = new Color(this.fogColor.value);
+    }
+    dispose() {
+        this.scene.fogNode = null;
+        this.scene.backgroundNode = null;
+    }
+}

package/dist/runtime/render/crowd-motion.d.ts

@@ -0,0 +1,68 @@
+import { InstancedBufferAttribute, Mesh, MeshStandardNodeMaterial } from "three/webgpu";
+import type { BufferGeometry, Material, MeshStandardMaterial, Node, Object3D } from "three/webgpu";
+export interface CrowdMotionOptions {
+    /** Vertical hop per step at full speed, m. Default 0.12. */
+    readonly bob?: number;
+    /** Side-to-side roll per step at full speed, radians. Default 0.18. */
+    readonly waddle?: number;
+    /** Forward lean at full speed, radians. Default 0.16. */
+    readonly lean?: number;
+    /** Squash on a hit (0..1 of height). Default 0.32. */
+    readonly squash?: number;
+    /** Steps per second at a standstill and per m/s of speed. Default [1.2, 0.9]. */
+    readonly cadence?: readonly [number, number];
+    /** Speed (m/s) treated as "full speed". Default 4. */
+    readonly fullSpeed?: number;
+    /** Idle breathing scale amplitude. Default 0.03. */
+    readonly breathe?: number;
+    /** Emissive added at full hit flash. Default 2.5. */
+    readonly flash?: number;
+    /** Draw as camera-facing sprites (render/sprite.ts): no roll or lean, mirrored to face the way they walk. Default: from the geometry. */
+    readonly billboard?: boolean;
+}
+/** The per-instance attributes a crowd-motion material reads. */
+export interface CrowdAttributes {
+    /** x, y, z, yaw. */
+    readonly xform: InstancedBufferAttribute;
+    /** phase (0..1), speed (m/s), hit (0..1 squash), flash (0..1 emissive). */
+    readonly anim: InstancedBufferAttribute;
+    /** uniform scale, unused x3. */
+    readonly extra: InstancedBufferAttribute;
+}
+type MotionMaterial = Material & {
+    positionNode: Node | null;
+    emissiveNode?: Node | null;
+};
+/**
+ * Vertex animation for crowds without skeletons: bob, waddle, forward
+ * lean and step cadence from each instance's speed, a squash-and-stretch on
+ * hit, a hit flash, idle breathing. Applied to an existing node material
+ * (positionNode, emissiveNode); geometry stands on y = 0 and faces -z.
+ */
+export declare function applyCrowdMotion(material: MotionMaterial, attrs: CrowdAttributes, time: Node<"float">, opts?: CrowdMotionOptions): MotionMaterial;
+/** Copy a classic MeshStandardMaterial into a node material (so positionNode can be set). */
+export declare function toNodeMaterial(m: MeshStandardMaterial): MeshStandardNodeMaterial;
+/**
+ * An instanced crowd with procedural animation: one draw, per-instance
+ * position, yaw, scale, phase, speed, hit squash and flash. Write instances
+ * between `begin()` and `end(time)` each frame; only the written range uploads.
+ */
+export declare class AnimatedCrowd {
+    readonly capacity: number;
+    readonly mesh: Mesh;
+    readonly time: import("three/webgpu").UniformNode<"float", number>;
+    readonly attrs: CrowdAttributes;
+    count: number;
+    constructor(geometry: BufferGeometry, material: MeshStandardMaterial | MeshStandardNodeMaterial, capacity: number, opts?: CrowdMotionOptions);
+    begin(): void;
+    /**
+     * One instance. `phase` 0..1 desyncs steps (use a hash of the id),
+     * `speed` m/s drives cadence and amplitude, `hit` 0..1 squashes,
+     * `flash` 0..1 brightens.
+     */
+    push(x: number, y: number, z: number, yaw: number, phase: number, speed: number, hit?: number, flash?: number, scale?: number): void;
+    end(timeSeconds: number): void;
+    addTo(parent: Object3D): this;
+    dispose(): void;
+}
+export {};

package/dist/runtime/render/crowd-motion.js

@@ -0,0 +1,163 @@
+import { DynamicDrawUsage, InstancedBufferAttribute, InstancedBufferGeometry, Mesh, MeshStandardNodeMaterial, } from "three/webgpu";
+import { abs, clamp, cos, float, floor, max, instancedBufferAttribute, materialEmissive, positionGeometry, select, sin, uniform, varying, vec3, } from "three/tsl";
+import { billboardWorld, isSprite } from "./sprite.js";
+/**
+ * Vertex animation for crowds without skeletons: bob, waddle, forward
+ * lean and step cadence from each instance's speed, a squash-and-stretch on
+ * hit, a hit flash, idle breathing. Applied to an existing node material
+ * (positionNode, emissiveNode); geometry stands on y = 0 and faces -z.
+ */
+export function applyCrowdMotion(material, attrs, time, opts = {}) {
+    const o = {
+        bob: 0.12,
+        waddle: 0.18,
+        lean: 0.16,
+        squash: 0.32,
+        cadence: [1.2, 0.9],
+        fullSpeed: 4,
+        breathe: 0.03,
+        flash: 2.5,
+        ...opts,
+    };
+    const X = instancedBufferAttribute(attrs.xform, "vec4");
+    const A = instancedBufferAttribute(attrs.anim, "vec4");
+    const E = instancedBufferAttribute(attrs.extra, "vec4");
+    const speed = A.y;
+    const amp = clamp(speed.div(o.fullSpeed), 0, 1);
+    const cadence = float(o.cadence[0]).add(speed.mul(o.cadence[1]));
+    const ph = A.x.mul(6.2832).add(float(time).mul(cadence).mul(6.2832));
+    const s = sin(ph);
+    const breath = sin(float(time).mul(2.1).add(A.x.mul(6.2832))).mul(o.breathe).mul(float(1).sub(amp));
+    const hit = A.z;
+    const sy = float(1).add(breath).add(s.mul(0.06).mul(amp)).sub(hit.mul(o.squash));
+    const sxz = float(1).add(hit.mul(o.squash * 0.5)).sub(breath.mul(0.5));
+    const g = positionGeometry;
+    const px = g.x.mul(sxz);
+    const py = g.y.mul(sy);
+    const pz = g.z.mul(sxz);
+    // Roll about the forward axis (waddle), then pitch forward (lean): the top moves toward -z.
+    const roll = s.mul(o.waddle).mul(amp);
+    const cr = cos(roll);
+    const sr = sin(roll);
+    const rx = px.mul(cr).sub(py.mul(sr));
+    const ry = px.mul(sr).add(py.mul(cr));
+    const lean = amp.mul(o.lean).add(hit.mul(-0.25));
+    const cl = cos(lean);
+    const sl = sin(lean);
+    const ly = ry.mul(cl).add(pz.mul(sl));
+    const lz = pz.mul(cl).sub(ry.mul(sl));
+    const scale = E.x;
+    const bob = abs(s).mul(o.bob).mul(amp);
+    if (opts.billboard) {
+        // A sprite keeps its bob and squash; it faces the camera and turns to the side it walks toward (yaw -pi/2 is +x).
+        const flip = select(sin(X.w).greaterThan(0.05), float(-1), float(1));
+        // Whole multiples only (an elite's 1.5 draws at 2): one sprite texel stays one picture pixel.
+        const whole = max(float(1), floor(scale.add(0.5)));
+        material.positionNode = billboardWorld(vec3(X.x, X.y.add(bob), X.z), px.mul(whole), py.mul(whole), flip);
+        if ("emissiveNode" in material)
+            material.emissiveNode = materialEmissive.add(vec3(varying(A.w)).mul(o.flash));
+        return material;
+    }
+    const cy = cos(X.w);
+    const syaw = sin(X.w);
+    const wx = rx.mul(cy).add(lz.mul(syaw)).mul(scale);
+    const wz = rx.mul(syaw).negate().add(lz.mul(cy)).mul(scale);
+    material.positionNode = vec3(wx.add(X.x), ly.mul(scale).add(X.y).add(bob), wz.add(X.z));
+    if ("emissiveNode" in material)
+        material.emissiveNode = materialEmissive.add(vec3(varying(A.w)).mul(o.flash));
+    return material;
+}
+/** Copy a classic MeshStandardMaterial into a node material (so positionNode can be set). */
+export function toNodeMaterial(m) {
+    const n = new MeshStandardNodeMaterial();
+    n.color.copy(m.color);
+    n.emissive.copy(m.emissive);
+    n.emissiveIntensity = m.emissiveIntensity;
+    n.roughness = m.roughness;
+    n.metalness = m.metalness;
+    n.flatShading = m.flatShading;
+    n.map = m.map;
+    n.transparent = m.transparent;
+    n.opacity = m.opacity;
+    n.side = m.side;
+    n.alphaTest = m.alphaTest;
+    return n;
+}
+/**
+ * An instanced crowd with procedural animation: one draw, per-instance
+ * position, yaw, scale, phase, speed, hit squash and flash. Write instances
+ * between `begin()` and `end(time)` each frame; only the written range uploads.
+ */
+export class AnimatedCrowd {
+    capacity;
+    mesh;
+    time = uniform(0);
+    attrs;
+    count = 0;
+    constructor(geometry, material, capacity, opts = {}) {
+        this.capacity = capacity;
+        const g = new InstancedBufferGeometry();
+        if (geometry.index)
+            g.setIndex(geometry.index);
+        for (const [name, a] of Object.entries(geometry.attributes))
+            g.setAttribute(name, a);
+        g.instanceCount = 0;
+        const mk = () => {
+            const a = new InstancedBufferAttribute(new Float32Array(capacity * 4), 4);
+            a.setUsage(DynamicDrawUsage);
+            return a;
+        };
+        this.attrs = { xform: mk(), anim: mk(), extra: mk() };
+        const mat = material.isNodeMaterial ? material : toNodeMaterial(material);
+        applyCrowdMotion(mat, this.attrs, this.time, { billboard: isSprite(geometry), ...opts });
+        this.mesh = new Mesh(g, mat);
+        this.mesh.frustumCulled = false;
+        this.mesh.castShadow = true;
+        this.mesh.receiveShadow = false;
+        this.mesh.name = "AnimatedCrowd";
+    }
+    begin() {
+        this.count = 0;
+    }
+    /**
+     * One instance. `phase` 0..1 desyncs steps (use a hash of the id),
+     * `speed` m/s drives cadence and amplitude, `hit` 0..1 squashes,
+     * `flash` 0..1 brightens.
+     */
+    push(x, y, z, yaw, phase, speed, hit = 0, flash = 0, scale = 1) {
+        if (this.count >= this.capacity)
+            return;
+        const o = this.count * 4;
+        const X = this.attrs.xform.array;
+        const A = this.attrs.anim.array;
+        const E = this.attrs.extra.array;
+        X[o] = x;
+        X[o + 1] = y;
+        X[o + 2] = z;
+        X[o + 3] = yaw;
+        A[o] = phase;
+        A[o + 1] = speed;
+        A[o + 2] = hit < 0 ? 0 : hit > 1 ? 1 : hit;
+        A[o + 3] = flash < 0 ? 0 : flash > 1 ? 1 : flash;
+        E[o] = scale;
+        this.count++;
+    }
+    end(timeSeconds) {
+        this.time.value = timeSeconds;
+        this.mesh.geometry.instanceCount = this.count;
+        for (const a of [this.attrs.xform, this.attrs.anim, this.attrs.extra]) {
+            a.clearUpdateRanges();
+            if (this.count > 0)
+                a.addUpdateRange(0, this.count * 4);
+            a.needsUpdate = true;
+        }
+    }
+    addTo(parent) {
+        parent.add(this.mesh);
+        return this;
+    }
+    dispose() {
+        this.mesh.removeFromParent();
+        this.mesh.geometry.dispose();
+    }
+}

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

@@ -0,0 +1,64 @@
+import { Mesh } from "three/webgpu";
+import type { Object3D } from "three/webgpu";
+import { ParticleRing } from "./particles.js";
+import type { DecalLook, RingLook } from "../styles/kit.js";
+export type DecalKind = "scorch" | "splat" | "ring";
+export interface DecalOptions {
+    /** Diameter, m. Default 1.6. */
+    size?: number;
+    color?: number;
+    /** Seconds before it has faded out. Default 6. */
+    life?: number;
+    /** Peak opacity 0..1. Default 0.75. */
+    opacity?: number;
+    /** Rotation about y, radians (default random). */
+    rotation?: number;
+    /** Color multiplier above 1 makes it glow under bloom. Default 1. */
+    glow?: number;
+}
+/**
+ * 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 declare class GroundDecals {
+    readonly time: import("three/webgpu").UniformNode<"float", number>;
+    readonly ring: ParticleRing;
+    readonly mesh: Mesh;
+    private readonly a;
+    private readonly b;
+    private readonly c;
+    private readonly rand;
+    /** Height above the floor, m. */
+    floorY: number;
+    constructor(parent: Object3D, capacity?: number, random?: () => number, look?: DecalLook);
+    /** Stamp a decal on the floor at (x, z). */
+    add(kind: DecalKind, x: number, z: number, opts?: DecalOptions): void;
+    update(timeSeconds: number): void;
+    dispose(): void;
+}
+export interface RingOptions {
+    color?: number;
+    /** Seconds to expand and fade. Default 0.32. */
+    duration?: number;
+    /** Brightness multiplier (bloom). Default 1.6. */
+    glow?: number;
+}
+/**
+ * Expanding shockwave rings on the floor (nova blasts, landings, dash
+ * starts): one additive draw, pooled. Generalized from EMBERWATCH's rings.
+ */
+export declare class GroundRings {
+    readonly time: import("three/webgpu").UniformNode<"float", number>;
+    readonly ring: ParticleRing;
+    readonly mesh: Mesh;
+    private readonly a;
+    private readonly b;
+    /** Rings fired so far (playtest checks). */
+    fired: number;
+    constructor(parent: Object3D, capacity?: number, look?: RingLook);
+    /** A ring at (x, z) reaching `radius` m. */
+    fire(x: number, z: number, radius: number, opts?: RingOptions): void;
+    update(timeSeconds: number): void;
+    dispose(): void;
+}