@netforge/engine 0.0.0-stage → 0.1.0

package/dist/runtime/render/post.js

@@ -0,0 +1,191 @@
+import { ACESFilmicToneMapping, AgXToneMapping, Color, NeutralToneMapping, RenderPipeline, Vector2, Vector3, } from "three/webgpu";
+import { abs, dot, float, length, max, mix, perspectiveDepthToViewZ, pass, pow, renderOutput, screenUV, smoothstep, uniform, vec2, vec3, vec4, } from "three/tsl";
+import { bloom } from "three/addons/tsl/display/BloomNode.js";
+import { fxaa } from "three/addons/tsl/display/FXAANode.js";
+import { resolveLook } from "./presets.js";
+function toneMappingOf(name) {
+    return name === "agx" ? AgXToneMapping : name === "neutral" ? NeutralToneMapping : ACESFilmicToneMapping;
+}
+/**
+ * The post stack: scene pass (HDR) -> bloom -> optional depth outline ->
+ * color grade (exposure, contrast, saturation, split tone, vignette, hurt
+ * pulse) -> tone mapping and sRGB (once, via renderOutput) -> FXAA.
+ *
+ * Tone mapping is the renderer's (`renderer.toneMapping`), so the same
+ * curve applies whether post is on (here, in renderOutput) or off
+ * (renderer.render to the canvas). Every knob is a uniform.
+ */
+export class PostFX {
+    renderer;
+    scene;
+    camera;
+    pipeline;
+    /** Extra exposure multiplier inside the grade (the preset's exposure is renderer.toneMappingExposure). */
+    exposure = uniform(1);
+    contrast = uniform(1);
+    saturation = uniform(1);
+    shadowTint = uniform(new Vector3(1, 1, 1));
+    highlightTint = uniform(new Vector3(1, 1, 1));
+    vignette = uniform(0.3);
+    /** 0..1: the game drives this when the player is hurt (red edge pulse). */
+    hurt = uniform(0);
+    outlineColor = uniform(new Color(0x06080c));
+    /** Outline thickness in pixels. */
+    outlineThickness = uniform(1.25);
+    /** Relative depth jump that counts as an edge. */
+    outlineThreshold = uniform(0.012);
+    outlineStrength = uniform(0.85);
+    texel = uniform(new Vector2(1 / 1280, 1 / 720));
+    near = uniform(0.1);
+    far = uniform(500);
+    bloomNode = null;
+    bloomOn;
+    outlineOn;
+    fxaaOn;
+    bloomScale;
+    grade;
+    style;
+    enabled;
+    constructor(renderer, scene, camera, opts = {}) {
+        this.renderer = renderer;
+        this.scene = scene;
+        this.camera = camera;
+        this.pipeline = new RenderPipeline(renderer);
+        this.pipeline.outputColorTransform = false;
+        this.bloomOn = opts.bloom ?? true;
+        this.outlineOn = opts.outline ?? false;
+        this.fxaaOn = opts.fxaa ?? true;
+        this.enabled = opts.enabled ?? true;
+        this.bloomScale = opts.bloomScale ?? 0.5;
+        this.style = opts.style ?? null;
+        this.grade = { ...resolveLook(opts.preset).grade, ...opts.overrides };
+        this.applyGrade();
+        this.build();
+    }
+    /** Bloom strength, radius and threshold uniforms (null while bloom is off). */
+    get bloom() {
+        return this.bloomNode;
+    }
+    setPreset(preset, overrides = {}) {
+        this.grade = { ...resolveLook(preset).grade, ...overrides };
+        this.applyGrade();
+    }
+    applyGrade() {
+        const g = this.grade;
+        this.renderer.toneMapping = toneMappingOf(g.toneMapping);
+        // Exposure lives on the renderer so it applies with post on or off.
+        this.renderer.toneMappingExposure = g.exposure;
+        this.exposure.value = 1;
+        this.contrast.value = g.contrast;
+        this.saturation.value = g.saturation;
+        this.shadowTint.value.set(...g.shadowTint);
+        this.highlightTint.value.set(...g.highlightTint);
+        this.vignette.value = g.vignette;
+        if (this.bloomNode) {
+            this.bloomNode.strength.value = g.bloomStrength;
+            this.bloomNode.radius.value = g.bloomRadius;
+            this.bloomNode.threshold.value = g.bloomThreshold;
+        }
+    }
+    /** Toggle stages; rebuilds the node graph only when something changed. */
+    configure(o) {
+        const next = {
+            bloom: o.bloom ?? this.bloomOn,
+            outline: o.outline ?? this.outlineOn,
+            fxaa: o.fxaa ?? this.fxaaOn,
+            bloomScale: o.bloomScale ?? this.bloomScale,
+        };
+        if (o.enabled !== undefined)
+            this.enabled = o.enabled;
+        const changed = next.bloom !== this.bloomOn || next.outline !== this.outlineOn || next.fxaa !== this.fxaaOn;
+        this.bloomOn = next.bloom;
+        this.outlineOn = next.outline;
+        this.fxaaOn = next.fxaa;
+        if (next.bloomScale !== this.bloomScale) {
+            this.bloomScale = next.bloomScale;
+            this.bloomNode?.setResolutionScale(this.bloomScale);
+        }
+        if (changed)
+            this.build();
+    }
+    /** Apply a quality tier: low turns post off; medium drops bloom resolution; outline needs medium+. */
+    setQuality(tier, outlineWanted = this.outlineOn) {
+        if (tier === "low")
+            this.configure({ enabled: false });
+        else
+            this.configure({ enabled: true, bloomScale: tier === "high" ? 0.5 : 0.33, outline: outlineWanted });
+    }
+    get stages() {
+        return { enabled: this.enabled, bloom: this.bloomOn, outline: this.outlineOn, fxaa: this.fxaaOn };
+    }
+    /** Swap the art style's post stages (runtime/styles) and rebuild the graph. */
+    setStyle(style) {
+        this.style = style;
+        this.build();
+    }
+    build() {
+        const scenePass = pass(this.scene, this.camera);
+        this.style?.scenePass?.(scenePass);
+        const sceneColor = scenePass.getTextureNode("output");
+        const styleInput = { color: sceneColor, depth: scenePass.getTextureNode("depth"), texel: this.texel, near: this.near, far: this.far };
+        const color = this.style?.scene ? this.style.scene(styleInput) : sceneColor;
+        let hdr = color;
+        this.bloomNode = null;
+        if (this.bloomOn) {
+            const g = this.grade;
+            const b = bloom(color, g.bloomStrength, g.bloomRadius, g.bloomThreshold);
+            b.setResolutionScale(this.bloomScale);
+            this.bloomNode = b;
+            hdr = color.add(b);
+        }
+        let rgb = vec4(hdr).rgb;
+        if (this.outlineOn) {
+            const depth = scenePass.getTextureNode("depth");
+            const viewZ = (dx, dy) => perspectiveDepthToViewZ(depth.sample(screenUV.add(this.texel.mul(vec2(dx, dy)).mul(this.outlineThickness))).x, this.near, this.far);
+            const c = viewZ(0, 0);
+            const diff = abs(viewZ(1, 0).sub(c)).add(abs(viewZ(-1, 0).sub(c))).add(abs(viewZ(0, 1).sub(c))).add(abs(viewZ(0, -1).sub(c)));
+            const rel = diff.div(max(abs(c), float(0.001)));
+            const edge = smoothstep(this.outlineThreshold, this.outlineThreshold.mul(2.5), rel).mul(this.outlineStrength);
+            rgb = mix(rgb, vec3(this.outlineColor), edge);
+        }
+        if (this.style?.color)
+            rgb = this.style.color(rgb, scenePass);
+        // Grade in linear HDR, before tone mapping.
+        let c = rgb.mul(this.exposure);
+        const luma = dot(c, vec3(0.2126, 0.7152, 0.0722));
+        c = mix(vec3(luma), c, this.saturation);
+        c = pow(max(c, vec3(1e-5)).div(0.18), vec3(this.contrast)).mul(0.18);
+        const tone = smoothstep(0.0, 1.0, luma);
+        c = c.mul(mix(this.shadowTint, this.highlightTint, tone));
+        const d = length(screenUV.sub(0.5)).mul(1.414);
+        const v = smoothstep(0.35, 1.05, d);
+        c = c.mul(float(1).sub(v.mul(this.vignette)));
+        const hurtEdge = smoothstep(0.45, 1.15, d).mul(this.hurt).mul(0.85);
+        c = mix(c, c.mul(vec3(1.25, 0.35, 0.3)).add(vec3(0.22, 0.0, 0.0)), hurtEdge);
+        let out = renderOutput(vec4(c, 1));
+        if (this.style?.display)
+            out = this.style.display(out, styleInput);
+        this.pipeline.outputNode = this.fxaaOn ? fxaa(out) : out;
+        this.pipeline.needsUpdate = true;
+    }
+    /** Call when the canvas size changes (CSS pixels times pixel ratio handled inside). */
+    setSize(width, height) {
+        const pr = this.renderer.getPixelRatio();
+        this.texel.value.set(1 / Math.max(1, width * pr), 1 / Math.max(1, height * pr));
+    }
+    /** Draw the frame: through the stack, or straight to the canvas when disabled. */
+    render() {
+        const cam = this.camera;
+        if (cam.near !== undefined)
+            this.near.value = cam.near;
+        if (cam.far !== undefined)
+            this.far.value = cam.far;
+        if (this.enabled)
+            this.pipeline.render();
+        else
+            this.renderer.render(this.scene, this.camera);
+    }
+    dispose() {
+        this.pipeline.dispose();
+    }
+}

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

@@ -0,0 +1,57 @@
+/**
+ * Look presets: one name picks the lighting, the atmosphere and the color
+ * grade together, so a template (or a generated game) says `preset: "dusk"`
+ * and gets a coherent picture. Plain data, node-testable.
+ */
+export type LookPreset = "night" | "dusk" | "day" | "studio";
+export declare const LOOK_PRESETS: readonly LookPreset[];
+export interface LightingPreset {
+    /** Hemisphere sky and ground colors, intensity. */
+    readonly sky: number;
+    readonly ground: number;
+    readonly hemi: number;
+    /** Directional sun (or moon) color and intensity. */
+    readonly sun: number;
+    readonly sunIntensity: number;
+    /** Direction the light travels FROM, normalized at use (x, y, z). */
+    readonly sunDir: readonly [number, number, number];
+    /** Flat ambient fill (0 = none). */
+    readonly ambient: number;
+    readonly ambientColor: number;
+    /** Shadow darkness 0..1 (1 = full black shadows). */
+    readonly shadowStrength: number;
+}
+export interface AtmospherePreset {
+    /** Fog and horizon color. */
+    readonly fog: number;
+    /** Sky gradient: color at the top of the screen. */
+    readonly skyTop: number;
+    readonly mode: "linear" | "exp2";
+    /** Linear fog near and far (m), or exp2 density. */
+    readonly near: number;
+    readonly far: number;
+    readonly density: number;
+    /** Height fog density (0 = off) below `heightFogTop` m. */
+    readonly heightFog: number;
+    readonly heightFogTop: number;
+}
+export interface GradePreset {
+    readonly exposure: number;
+    readonly contrast: number;
+    readonly saturation: number;
+    /** Multiplier tints for shadows and highlights (split toning). */
+    readonly shadowTint: readonly [number, number, number];
+    readonly highlightTint: readonly [number, number, number];
+    readonly vignette: number;
+    readonly bloomStrength: number;
+    readonly bloomRadius: number;
+    readonly bloomThreshold: number;
+    readonly toneMapping: "aces" | "agx" | "neutral";
+}
+export interface Look {
+    readonly lighting: LightingPreset;
+    readonly atmosphere: AtmospherePreset;
+    readonly grade: GradePreset;
+}
+/** A preset by name; unknown names fall back to "studio" (never throws at runtime). */
+export declare function resolveLook(name: string | undefined): Look;

package/dist/runtime/render/presets.js

@@ -0,0 +1,116 @@
+/**
+ * Look presets: one name picks the lighting, the atmosphere and the color
+ * grade together, so a template (or a generated game) says `preset: "dusk"`
+ * and gets a coherent picture. Plain data, node-testable.
+ */
+export const LOOK_PRESETS = ["night", "dusk", "day", "studio"];
+const LOOKS = {
+    night: {
+        lighting: {
+            sky: 0x9fb0ff,
+            ground: 0x3a2c18,
+            hemi: 2.6,
+            sun: 0xc8d6ff,
+            sunIntensity: 3.4,
+            sunDir: [-0.45, 0.85, 0.3],
+            ambient: 0.35,
+            ambientColor: 0x8090c0,
+            shadowStrength: 0.75,
+        },
+        atmosphere: { fog: 0x121a2a, skyTop: 0x060912, mode: "linear", near: 32, far: 85, density: 0.018, heightFog: 0.06, heightFogTop: 1.2 },
+        grade: {
+            exposure: 1.5,
+            contrast: 1.08,
+            saturation: 1.12,
+            shadowTint: [0.86, 0.94, 1.15],
+            highlightTint: [1.08, 1.0, 0.9],
+            vignette: 0.42,
+            bloomStrength: 0.8,
+            bloomRadius: 0.45,
+            bloomThreshold: 0.82,
+            toneMapping: "aces",
+        },
+    },
+    dusk: {
+        lighting: {
+            sky: 0xffb38a,
+            ground: 0x3a2a3a,
+            hemi: 1.2,
+            sun: 0xffa060,
+            sunIntensity: 2.6,
+            sunDir: [0.7, 0.45, 0.35],
+            ambient: 0.1,
+            ambientColor: 0xffd0b0,
+            shadowStrength: 0.7,
+        },
+        atmosphere: { fog: 0x6a4a5c, skyTop: 0x2a2140, mode: "linear", near: 30, far: 110, density: 0.012, heightFog: 0.04, heightFogTop: 1.5 },
+        grade: {
+            exposure: 1.0,
+            contrast: 1.08,
+            saturation: 1.15,
+            shadowTint: [0.9, 0.88, 1.12],
+            highlightTint: [1.1, 1.0, 0.86],
+            vignette: 0.35,
+            bloomStrength: 0.65,
+            bloomRadius: 0.5,
+            bloomThreshold: 0.85,
+            toneMapping: "agx",
+        },
+    },
+    day: {
+        lighting: {
+            sky: 0xcfe6ff,
+            ground: 0x6b5a40,
+            hemi: 1.3,
+            sun: 0xfff2dc,
+            sunIntensity: 3.2,
+            sunDir: [0.4, 0.9, 0.25],
+            ambient: 0.15,
+            ambientColor: 0xffffff,
+            shadowStrength: 0.6,
+        },
+        atmosphere: { fog: 0xb8d4ee, skyTop: 0x6aa6e8, mode: "linear", near: 45, far: 160, density: 0.008, heightFog: 0, heightFogTop: 0 },
+        grade: {
+            exposure: 1.0,
+            contrast: 1.04,
+            saturation: 1.08,
+            shadowTint: [0.95, 0.98, 1.06],
+            highlightTint: [1.04, 1.01, 0.96],
+            vignette: 0.22,
+            bloomStrength: 0.35,
+            bloomRadius: 0.4,
+            bloomThreshold: 0.95,
+            toneMapping: "agx",
+        },
+    },
+    studio: {
+        lighting: {
+            sky: 0xffffff,
+            ground: 0x404040,
+            hemi: 1.4,
+            sun: 0xffffff,
+            sunIntensity: 2.4,
+            sunDir: [0.5, 1, 0.6],
+            ambient: 0.3,
+            ambientColor: 0xffffff,
+            shadowStrength: 0.5,
+        },
+        atmosphere: { fog: 0x22252c, skyTop: 0x101216, mode: "linear", near: 60, far: 200, density: 0.005, heightFog: 0, heightFogTop: 0 },
+        grade: {
+            exposure: 1.0,
+            contrast: 1.0,
+            saturation: 1.0,
+            shadowTint: [1, 1, 1],
+            highlightTint: [1, 1, 1],
+            vignette: 0.15,
+            bloomStrength: 0.3,
+            bloomRadius: 0.35,
+            bloomThreshold: 0.95,
+            toneMapping: "neutral",
+        },
+    },
+};
+/** A preset by name; unknown names fall back to "studio" (never throws at runtime). */
+export function resolveLook(name) {
+    return (name !== undefined && LOOKS[name]) || LOOKS.studio;
+}

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

@@ -0,0 +1,113 @@
+/**
+ * Quality tiers and dynamic resolution ("auto-detected
+ * low, medium or high (shadows, post-processing, resolution scale) with
+ * dynamic resolution to hold the frame rate"). The decision logic is pure
+ * so it is tested in node; `QualityManager` applies it to a renderer.
+ */
+export type QualityTier = "low" | "medium" | "high";
+export declare const QUALITY_TIERS: readonly QualityTier[];
+/** What a tier turns on. */
+export interface QualitySettings {
+    readonly tier: QualityTier;
+    /** Shadow map size in texels; 0 turns shadows off. */
+    readonly shadowMapSize: number;
+    /** Post-processing (bloom, grade, FXAA) on at all. */
+    readonly post: boolean;
+    /** Bloom render-target scale (fraction of the canvas). */
+    readonly bloomScale: number;
+    /** The toon outline pass may run (still opt-in per game). */
+    readonly outline: boolean;
+    /** Most device pixels per CSS pixel the tier renders. */
+    readonly maxPixelRatio: number;
+    /** Lowest pixel ratio dynamic resolution may drop to. */
+    readonly minPixelRatio: number;
+    /** GPU particle pool size. */
+    readonly particles: number;
+}
+export declare function qualitySettings(tier: QualityTier): QualitySettings;
+/** What the browser tells us about the device. Every field optional: missing reads as "unknown". */
+export interface DeviceHints {
+    readonly userAgent?: string;
+    /** `matchMedia("(pointer: coarse)").matches`. */
+    readonly coarsePointer?: boolean;
+    readonly hardwareConcurrency?: number;
+    /** `navigator.deviceMemory` (GB), Chrome only. */
+    readonly deviceMemory?: number;
+    readonly devicePixelRatio?: number;
+    readonly backend?: "webgpu" | "webgl2";
+    /** Screen width in CSS pixels. */
+    readonly screenWidth?: number;
+}
+/**
+ * Pick a tier from device hints. Phones and tablets start at medium (low on
+ * weak or WebGL-only ones); desktops start at high unless the CPU is small.
+ * Dynamic resolution then holds the frame rate within the tier.
+ */
+export declare function detectTier(h: DeviceHints): QualityTier;
+/** Read the hints from the running browser (safe in node: returns {}). */
+export declare function browserHints(backend?: "webgpu" | "webgl2"): DeviceHints;
+export interface DynamicResolutionOptions {
+    /** Frame budget, ms. Default 1000 / 60. */
+    readonly budgetMs?: number;
+    /** Step down when p95 exceeds budget x this. Default 1.26 (21 ms at 60 fps). */
+    readonly overFactor?: number;
+    /** Step up when p95 is under budget x this. Default 1.05 (17.5 ms at 60 fps). */
+    readonly underFactor?: number;
+    readonly step?: number;
+    readonly min?: number;
+    readonly max?: number;
+    /** Minimum ms between changes. Default 2000. */
+    readonly hysteresisMs?: number;
+    /** Frames needed in the window before deciding. Default 120. */
+    readonly minSamples?: number;
+    /** Rolling window size. Default 240 frames. */
+    readonly window?: number;
+}
+/**
+ * Pixel-ratio controller: trades pixels for frame time. Push every frame's
+ * interval; `update(now)` returns the new ratio when it changes, else null.
+ * After a change the window restarts so the next decision sees the new cost.
+ */
+export declare class DynamicResolution {
+    private readonly buf;
+    private i;
+    private n;
+    private lastChange;
+    ratio: number;
+    readonly o: Required<DynamicResolutionOptions>;
+    constructor(initial: number, opts?: DynamicResolutionOptions);
+    push(frameMs: number): void;
+    p95(): number;
+    /** Clamp the ratio range (a tier change). Returns the new ratio if it moved. */
+    setRange(min: number, max: number): number | null;
+    private lastCheck;
+    update(now: number): number | null;
+}
+export interface QualityTarget {
+    setPixelRatio(ratio: number): void;
+}
+/**
+ * Holds the tier and the dynamic resolution for one renderer. Listeners
+ * (lighting, post, particles) re-read `settings` on `onChange`.
+ */
+export declare class QualityManager {
+    private readonly target;
+    settings: QualitySettings;
+    readonly dynamic: DynamicResolution;
+    private readonly listeners;
+    private last;
+    constructor(target: QualityTarget, tier: QualityTier, opts?: {
+        devicePixelRatio?: number;
+        dynamic?: boolean;
+        budgetMs?: number;
+    });
+    /** Dynamic resolution on (default). */
+    enabled: boolean;
+    private readonly dpr;
+    get tier(): QualityTier;
+    get pixelRatio(): number;
+    onChange(fn: (s: QualitySettings) => void): void;
+    setTier(tier: QualityTier): void;
+    /** Call once per frame with the real time (ms). Returns true when the pixel ratio changed (resize needed). */
+    frame(now: number): boolean;
+}

package/dist/runtime/render/quality.js

@@ -0,0 +1,180 @@
+/**
+ * Quality tiers and dynamic resolution ("auto-detected
+ * low, medium or high (shadows, post-processing, resolution scale) with
+ * dynamic resolution to hold the frame rate"). The decision logic is pure
+ * so it is tested in node; `QualityManager` applies it to a renderer.
+ */
+export const QUALITY_TIERS = ["low", "medium", "high"];
+const SETTINGS = {
+    low: { tier: "low", shadowMapSize: 0, post: false, bloomScale: 0.25, outline: false, maxPixelRatio: 1.25, minPixelRatio: 0.6, particles: 1024 },
+    medium: { tier: "medium", shadowMapSize: 1024, post: true, bloomScale: 0.33, outline: true, maxPixelRatio: 1.5, minPixelRatio: 0.75, particles: 2048 },
+    high: { tier: "high", shadowMapSize: 2048, post: true, bloomScale: 0.5, outline: true, maxPixelRatio: 2, minPixelRatio: 0.75, particles: 4096 },
+};
+export function qualitySettings(tier) {
+    return SETTINGS[tier];
+}
+const MOBILE_UA = /Android|iPhone|iPad|iPod|Mobile|Silk|Kindle|Opera Mini/i;
+/**
+ * Pick a tier from device hints. Phones and tablets start at medium (low on
+ * weak or WebGL-only ones); desktops start at high unless the CPU is small.
+ * Dynamic resolution then holds the frame rate within the tier.
+ */
+export function detectTier(h) {
+    const mobile = h.coarsePointer === true || MOBILE_UA.test(h.userAgent ?? "");
+    const cores = h.hardwareConcurrency ?? 4;
+    const mem = h.deviceMemory ?? 8;
+    if (mobile) {
+        if (cores <= 4 || mem <= 3 || h.backend === "webgl2")
+            return "low";
+        return "medium";
+    }
+    if (cores <= 2 || mem <= 2)
+        return "low";
+    if (cores <= 4 || h.backend === "webgl2")
+        return "medium";
+    return "high";
+}
+/** Read the hints from the running browser (safe in node: returns {}). */
+export function browserHints(backend) {
+    const g = globalThis;
+    return {
+        ...(g.navigator?.userAgent !== undefined ? { userAgent: g.navigator.userAgent } : {}),
+        ...(g.matchMedia ? { coarsePointer: g.matchMedia("(pointer: coarse)").matches } : {}),
+        ...(g.navigator?.hardwareConcurrency !== undefined ? { hardwareConcurrency: g.navigator.hardwareConcurrency } : {}),
+        ...(g.navigator?.deviceMemory !== undefined ? { deviceMemory: g.navigator.deviceMemory } : {}),
+        ...(g.devicePixelRatio !== undefined ? { devicePixelRatio: g.devicePixelRatio } : {}),
+        ...(g.screen?.width !== undefined ? { screenWidth: g.screen.width } : {}),
+        ...(backend ? { backend } : {}),
+    };
+}
+/**
+ * Pixel-ratio controller: trades pixels for frame time. Push every frame's
+ * interval; `update(now)` returns the new ratio when it changes, else null.
+ * After a change the window restarts so the next decision sees the new cost.
+ */
+export class DynamicResolution {
+    buf;
+    i = 0;
+    n = 0;
+    lastChange = -Infinity;
+    ratio;
+    o;
+    constructor(initial, opts = {}) {
+        this.o = {
+            budgetMs: 1000 / 60,
+            overFactor: 1.26,
+            underFactor: 1.05,
+            step: 0.25,
+            min: 0.75,
+            max: 2,
+            hysteresisMs: 2000,
+            minSamples: 120,
+            window: 240,
+            ...opts,
+        };
+        this.buf = new Float64Array(this.o.window);
+        this.ratio = Math.min(this.o.max, Math.max(this.o.min, initial));
+    }
+    push(frameMs) {
+        this.buf[this.i] = frameMs;
+        this.i = (this.i + 1) % this.buf.length;
+        this.n = Math.min(this.n + 1, this.buf.length);
+    }
+    p95() {
+        if (this.n === 0)
+            return 0;
+        const a = Array.from(this.buf.subarray(0, this.n)).sort((x, y) => x - y);
+        return a[Math.min(a.length - 1, Math.floor(0.95 * (a.length - 1)))] ?? 0;
+    }
+    /** Clamp the ratio range (a tier change). Returns the new ratio if it moved. */
+    setRange(min, max) {
+        this.o.min = min;
+        this.o.max = max;
+        const next = Math.min(max, Math.max(min, this.ratio));
+        if (next === this.ratio)
+            return null;
+        this.ratio = next;
+        return next;
+    }
+    lastCheck = -Infinity;
+    update(now) {
+        if (this.n < this.o.minSamples || now - this.lastChange < this.o.hysteresisMs)
+            return null;
+        // The p95 sorts the whole window: look at it at most twice a second, not every frame.
+        if (now - this.lastCheck < Math.min(500, this.o.hysteresisMs))
+            return null;
+        this.lastCheck = now;
+        const p95 = this.p95();
+        let next = this.ratio;
+        if (p95 > this.o.budgetMs * this.o.overFactor && this.ratio > this.o.min)
+            next = Math.max(this.o.min, this.ratio - this.o.step);
+        else if (p95 < this.o.budgetMs * this.o.underFactor && this.ratio < this.o.max)
+            next = Math.min(this.o.max, this.ratio + this.o.step);
+        if (next === this.ratio)
+            return null;
+        this.ratio = next;
+        this.lastChange = now;
+        this.n = 0;
+        this.i = 0;
+        return next;
+    }
+}
+/**
+ * Holds the tier and the dynamic resolution for one renderer. Listeners
+ * (lighting, post, particles) re-read `settings` on `onChange`.
+ */
+export class QualityManager {
+    target;
+    settings;
+    dynamic;
+    listeners = [];
+    last = 0;
+    constructor(target, tier, opts = {}) {
+        this.target = target;
+        this.settings = qualitySettings(tier);
+        const dpr = opts.devicePixelRatio ?? 1;
+        const max = Math.min(dpr, this.settings.maxPixelRatio);
+        this.dynamic = new DynamicResolution(max, {
+            min: Math.min(max, this.settings.minPixelRatio),
+            max,
+            ...(opts.budgetMs !== undefined ? { budgetMs: opts.budgetMs } : {}),
+        });
+        this.enabled = opts.dynamic ?? true;
+        this.dpr = dpr;
+        target.setPixelRatio(this.dynamic.ratio);
+    }
+    /** Dynamic resolution on (default). */
+    enabled;
+    dpr;
+    get tier() {
+        return this.settings.tier;
+    }
+    get pixelRatio() {
+        return this.dynamic.ratio;
+    }
+    onChange(fn) {
+        this.listeners.push(fn);
+    }
+    setTier(tier) {
+        this.settings = qualitySettings(tier);
+        const max = Math.min(this.dpr, this.settings.maxPixelRatio);
+        const moved = this.dynamic.setRange(Math.min(max, this.settings.minPixelRatio), max);
+        if (moved !== null)
+            this.target.setPixelRatio(moved);
+        for (const l of this.listeners)
+            l(this.settings);
+    }
+    /** Call once per frame with the real time (ms). Returns true when the pixel ratio changed (resize needed). */
+    frame(now) {
+        if (this.last !== 0)
+            this.dynamic.push(now - this.last);
+        this.last = now;
+        if (!this.enabled)
+            return false;
+        const next = this.dynamic.update(now);
+        if (next === null)
+            return false;
+        this.target.setPixelRatio(next);
+        return true;
+    }
+}

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

@@ -0,0 +1,29 @@
+import { AnimationClip, Bone, SkinnedMesh } from "three/webgpu";
+import type { BufferGeometry, Material } from "three/webgpu";
+export interface SegmentRigOptions {
+    /** Total height, m. Default 1.2. */
+    readonly height?: number;
+    /** Radius at the base, m. Default 0.35. */
+    readonly radius?: number;
+    /** Radius at the top (a cone when 0). Default radius x 0.75. */
+    readonly topRadius?: number;
+    readonly radialSegments?: number;
+    readonly heightSegments?: number;
+    /** Use this geometry instead of a cylinder (it must stand on y = 0, up to `height`). */
+    readonly geometry?: BufferGeometry;
+}
+export interface SegmentRig {
+    readonly mesh: SkinnedMesh;
+    /** hip, spine, head. */
+    readonly bones: readonly [Bone, Bone, Bone];
+    /** "rest", "idle", "walk", "run", "hit", "attack", "die". */
+    readonly clips: readonly AnimationClip[];
+}
+/**
+ * A three-bone procedural character (hip, spine, head) skinned to a
+ * cylinder or any upright geometry, with a full animation set built in
+ * code: rest, idle, walk, run, hit, attack, die. Templates with procedural
+ * art get real skinned animation (and VAT crowds via bakeVertexAnimation)
+ * without any asset files.
+ */
+export declare function buildSegmentRig(material: Material, opts?: SegmentRigOptions): SegmentRig;