reze-engine 0.64.0 → 0.66.0

package/dist/engine.d.ts

@@ -51,9 +51,9 @@ export type LoadModelFromFilesOptions = {
     pmxFile?: File;
 };
 type WorldOptions = {
-    /** Linear scene-referred color of the World Background (Blender: World > Surface > Color). */
+    /** Linear colour of the ambient when the World is a flat colour (Unity: Environment Lighting > Source Color). */
     color?: Vec3;
-    /** Multiplier on world color (Blender: World > Surface > Strength). */
+    /** Multiplier on the ambient and the sky's reflection (Unity: the Environment Lighting intensity multiplier). */
     strength?: number;
     /**
      * A sky that changes with the direction you look: one colour overhead, one at
@@ -128,14 +128,14 @@ type ParentTrack = {
     seat: [number, number, number];
 };
 type SunOptions = {
-    /** Linear color of the sun lamp (Blender: Light > Color). */
+    /** Linear colour of the main light (Unity: Light > Color). */
     color?: Vec3;
     /** The rendering layers it keys, as bits; every layer by default. A
      *  directional light from setLights takes the layers the sun leaves. */
     layers?: number;
-    /** Lamp power in Blender units (Blender: Light > Strength). */
+    /** Unity's light intensity: a white sun of 1 lights albedo 1:1 at N·L = 1. */
     strength?: number;
-    /** Direction sunlight travels (points FROM sun TO scene, Blender: -light.rotation.Z). */
+    /** Direction sunlight travels (points FROM the sun TO the scene, Unity: the light's forward). */
     direction?: Vec3;
     /**
      * How much shadow the sun casts: 1 full, 0 none, and anything between.
@@ -222,15 +222,22 @@ type CameraOptions = {
     /** Vertical field of view in radians. */
     fov?: number;
 };
-/** EEVEE Bloom panel (3D Viewport > Render > Bloom). Fields map 1:1 to Blender's UI. */
+/** Bloom — Aether Gazer's own (shaders/passes/bloom.ts): a soft-knee prefilter,
+ *  a Gaussian chain down to a few pixels, and a scatter blend back up, added to
+ *  the scene before the view transform. The defaults ARE the game. */
 export type BloomOptions = {
     enabled: boolean;
+    /** Brightest-channel level where the glow starts (the game's per-scene
+     *  threshold). The soft knee is always half of it. */
     threshold: number;
-    knee: number;
-    radius: number;
+    /** 0..1, URP's Scatter: how far each level leans toward the wider one on the
+     *  way up, as lerp(0.05, 0.95, scatter) — low is a tight halo, high a wide
+     *  haze, and the top still keeps the finest level. 0.8 is the game's 0.77. */
+    scatter: number;
+    /** Tint on the glow; white is the game. */
     color: Vec3;
+    /** Multiplier on the glow added in the composite; 1 is the game. */
     intensity: number;
-    clamp: number;
 };
 export declare const DEFAULT_BLOOM_OPTIONS: BloomOptions;
 /** Camera depth of field — a bokeh gather in the composite pass. Costs nothing
@@ -258,27 +265,27 @@ export type DepthOfFieldOptions = {
     quality: "performance" | "balanced" | "cinematic";
 };
 export declare const DEFAULT_DEPTH_OF_FIELD_OPTIONS: DepthOfFieldOptions;
-/** Blender Color Management / View (rendering.txt: Filmic, exposure, gamma). `look` is reserved for future curve tweaks. */
+/** How the scene-linear frame becomes a display image: exposure, then a tone
+ *  transform, then display gamma. */
 export type ViewTransformOptions = {
-    /** Stops applied before Filmic: `linear *= 2^exposure`. */
+    /** Stops applied before the transform: `linear *= 2^exposure`. */
     exposure: number;
-    /** After Filmic, display gamma (`pow(rgb, 1/gamma)`). */
+    /** After the transform, display gamma (`pow(rgb, 1/gamma)`). */
     gamma: number;
     /**
-     * Which display transform the frame is formed with.
+     * Which display transform the frame is formed with (composite.ts, viewTransform).
      *
-     * "standard" is Blender's Standard: the sRGB encoding and nothing else, which
-     * is what NPR and anime work uses — the colours the graph computes are the
-     * colours that land, with no film curve reinterpreting them. Both of the
-     * reference Wuthering Waves projects render this way.
+     * "soft" — Aether Gazer's own final curve, (1 - e^(-2.5x))^1.4. The default.
+     * "neutral" — Unity URP's Neutral, the Khronos PBR Neutral operator: colour
+     *   passes through until the top fifth, which rolls off.
+     * "aces" — Unity URP's ACES (RRT + ODT approximation from the Core RP).
+     * "none" — the sRGB encoding and nothing else.
      *
-     * "filmic" is Blender 3.6's Filmic, Medium High Contrast, baked as a LUT.
-     *
-     * "aether-gazer" is that game's own final curve, (1 - e^(-2.5x))^1.4 — what
-     * its scenes are graded through (composite.ts, agTransform).
+     * All four end in the sRGB encoding.
      */
-    transform: "agx" | "filmic" | "standard" | "aether-gazer";
+    transform: ViewTransformName;
 };
+export type ViewTransformName = "soft" | "neutral" | "aces" | "none";
 export declare const DEFAULT_VIEW_TRANSFORM: ViewTransformOptions;
 /** Color grading applied to the tonemapped scene (ASC CDL — see grade() in
  *  composite.ts). The three tonal controls are expressed as COLORS with
@@ -371,9 +378,9 @@ export type EngineOptions = {
     /** Canvas background (display-space sRGB 0–1), composited under the scene after
      *  tonemapping. Omit/null = transparent canvas (see setBackgroundColor). */
     background?: Vec3 | null;
-    /** Initial EEVEE-style bloom; tune at runtime with `setBloomOptions`. */
+    /** Initial bloom; tune at runtime with `setBloomOptions`. */
     bloom?: Partial<BloomOptions>;
-    /** View transform (exposure/gamma) applied in composite before/after Filmic. */
+    /** View transform (exposure, tone transform, gamma) applied in the composite. */
     view?: Partial<ViewTransformOptions>;
     onRaycast?: RaycastCallback;
     /** See {@link GizmoDragCallback}. */
@@ -545,12 +552,19 @@ interface ModelInstance {
     indexBuffer: GPUBuffer;
     jointsBuffer: GPUBuffer;
     weightsBuffer: GPUBuffer;
+    /** Vertex colour and second UV, per vertex — the material pipelines' slot 4.
+     *  See createAttributeBuffer. */
+    attributeBuffer: GPUBuffer;
+    /** The outline hull's own stream — smoothed normal + PMX edge scale per
+     *  vertex (outline-normals.ts). Made with the first edge-flagged material,
+     *  so a model with no outline never pays for it. */
+    outlineVertexBuffer?: GPUBuffer;
     skinMatrixBuffer: GPUBuffer;
     drawCalls: DrawCall[];
     shadowDrawCalls: DrawCall[];
     shadowBindGroups: GPUBindGroup[];
     mainPerInstanceBindGroup: GPUBindGroup;
-    /** Its ObjectLight — rendering layers, its own ambient — and the CPU copy it
+    /** Its ObjectLight — rendering layers, its own ambient, its fill — and the CPU copy it
      *  is written from. Every model has one: its layers decide its lights. */
     lightBuffer: GPUBuffer;
     objectLight: Float32Array<ArrayBuffer>;
@@ -703,6 +717,17 @@ export type SceneLight = {
      * cast's key on RENDERING_LAYER_CHARACTER is how a game lights the two apart.
      */
     layers?: number;
+    /**
+     * The bulb's radius in engine units: inside it the lamp stops getting
+     * brighter (intensity / max(d², near²)). Omitted keeps the default small
+     * bulb; a large soft lamp (a game rig light's shape radius) is wider.
+     */
+    near?: number;
+    /**
+     * A spot's cookie: the key of a picture given to loadLightCookie, projected
+     * along the cone the way a stage light throws a gobo. Ignored on a point.
+     */
+    cookie?: string;
 };
 /**
  * Rendering layers, as the game's pipeline (URP's rendering layers) uses them:
@@ -749,11 +774,19 @@ export declare class Engine {
     private mainPipelineLayout;
     private sceneTargets;
     private sceneTargetsAdditive;
+    /** A group blending "premultiplied" — see scene-contract's
+     *  material-premultiplied. */
+    private sceneTargetsPremultiplied;
     /** The scene pass's attachment formats, settled at init once the device has
      *  said which HDR format it will blend. Every scene-pass pipeline asks
      *  scene-contract for its targets against these. */
     private get sceneFormats();
     private fullVertexBufferLayouts;
+    /** What a MATERIAL pipeline reads: the full set, then (slot 4, past the
+     *  outline hull's slot 3) the model's attribute stream — vertex colour and a
+     *  second UV (see createAttributeBuffer). Only the material shaders declare
+     *  those inputs; every other pass keeps fullVertexBufferLayouts. */
+    private materialVertexBufferLayouts;
     private defaultToonRampTexture;
     private groundShadowPipeline;
     /** The soft-edge variant, built the first time a scene asks for one. Null while
@@ -865,6 +898,8 @@ export declare class Engine {
     private multisampleTexture;
     private hdrResolveTexture;
     private static readonly MULTISAMPLE_COUNT;
+    /** Floats per vertex in a model's attribute stream: colour RGBA, then UV2. */
+    private static readonly ATTRIBUTE_FLOATS;
     /**
      * Shadow map depth format — 16-bit, deliberately.
      *
@@ -1194,6 +1229,9 @@ export declare class Engine {
     /** Where addGround put the floor. The mirror reflects across it, so a raised
      *  floor that kept y = 0 would reflect the scene into the wrong plane. */
     private groundY;
+    /** The built-in floor's half size on x and z — what it covers, for the
+     *  shadow's reach (updateShadowSceneBounds). */
+    private groundHalf;
     private mirrorPlane;
     private mirrorCameraData;
     private mirrorCameraBuffer;
@@ -1219,6 +1257,7 @@ export declare class Engine {
      *  premultiplied quantity and a blur has to move them together. */
     private mirrorMaskMipViews;
     private mirrorMaskBlurBindGroups;
+    private mirrorDownsamplePipeline;
     private mirrorMaskDownsamplePipeline;
     /** Two blocks the ground reads its clip from: the camera's is inert, the
      *  mirror's carries the live plane. Which one a draw sees is decided by which
@@ -1312,6 +1351,38 @@ export declare class Engine {
     private worldAmbientSH;
     private fallbackEquirectTexture;
     private fallbackEquirectView;
+    /** The cube the materials read: 64² GGX-prefiltered down seven levels. */
+    private probeTexture;
+    private probeView;
+    /** 1×1 black cube, bound while a probe is being captured so no material
+     *  reads the cube it is drawing into. */
+    private probeFallbackView;
+    /** The spot lamps' cookies: one picture a layer of a 512² array, made on the
+     *  first cookie (a 1×1 white stand-in until then), and the layer each key holds. */
+    private cookieTexture;
+    private cookieView;
+    private cookieLayers;
+    /** What setLights was last given, rewritten when a cookie it names arrives. */
+    private sceneLights;
+    private static readonly COOKIE_SIZE;
+    private static readonly COOKIE_LAYERS;
+    /** ProbeUniforms for the scene (centre + strength, box min + on-flag, box
+     *  max), and a zeroed copy — the off flag — for the capture's own draws. */
+    private probeUniformBuffer;
+    private probeOffBuffer;
+    private probeData;
+    /** The capture camera: CameraUniforms for one cube face at a time. */
+    private probeCameraBuffer;
+    private probeCameraData;
+    private probeCaptureBindGroup;
+    /** Set when the stage or what it wears changes; the capture runs once the
+     *  scene has stayed put for PROBE_SETTLE_FRAMES (see maybeCaptureProbe). */
+    private probeDirty;
+    private probeDirtyFrame;
+    private probeFrame;
+    private probeCapture;
+    private static readonly PROBE_SETTLE_FRAMES;
+    private skyPrefilterPipeline;
     /**
      * The scene's effects, in document order — the order they layer in.
      *
@@ -1394,8 +1465,6 @@ export declare class Engine {
     /** Trail samples owed this frame, computed once so every trail on every
      *  character samples in lockstep and their paths stay comparable. */
     private trailDue;
-    private agxLutTexture;
-    private agxFallbackTexture;
     /** The scene's own grade (setStageGrade): the cube as handed over, kept so a
      *  call before init() still lands, and its texture once uploaded. */
     private stageGradeCube;
@@ -1420,29 +1489,44 @@ export declare class Engine {
     private readonly pipelineDescs;
     private readonly singleSided;
     private readonly singleSidedMirror;
+    /** Twins whose async build is in flight, so a draw asks for each once. */
+    private readonly sidedPending;
+    private readonly sidedPendingMirror;
+    private readonly shaderModuleCache;
+    private readonly pipelineCache;
+    private readonly bindGroupLayoutCache;
+    private readonly pipelineLayoutCache;
+    private readonly gpuObjectIds;
+    private gpuObjectNext;
+    /** Init's pipelines, built async and in parallel; init awaits them. Null
+     *  outside init, where a pipeline job builds the way it always did. */
+    private initPipelineJobs;
     private readonly steppedHeld;
     private readonly steppedTick;
     private steppedLastClock;
-    private bloomBlitUniformBuffer;
-    private bloomUpsampleUniformBuffer;
-    private readonly bloomBlitUniformData;
-    private readonly bloomUpsampleUniformData;
-    private bloomBlitPipeline;
-    private bloomDownsamplePipeline;
+    private bloomPrefilterBindGroupLayout;
+    private bloomBlurBindGroupLayout;
+    /** Single-attachment pass; colorAttachments[0].view set per bloom step. */
+    private bloomPassDescriptor;
+    private bloomPrefilterPipeline;
+    private bloomBlurHPipeline;
+    private bloomBlurVPipeline;
     private bloomUpsamplePipeline;
-    private bloomBlitBindGroupLayout;
-    private bloomDownsampleBindGroupLayout;
     private bloomUpsampleBindGroupLayout;
+    private bloomUniformBuffer;
+    private readonly bloomUniformData;
     private bloomDownTexture;
     private bloomUpTexture;
-    private bloomMipCount;
-    private bloomDownMipViews;
-    private bloomUpMipViews;
-    private bloomBlitBindGroup;
-    private bloomDownsampleBindGroups;
+    private bloomLevels;
+    private bloomDownViews;
+    private bloomUpViews;
+    private bloomPrefilterBindGroup;
+    private bloomBlurHBindGroups;
+    private bloomBlurVBindGroups;
     private bloomUpsampleBindGroups;
-    /** Single-attachment pass; colorAttachments[0].view set per bloom step. */
-    private bloomPassDescriptor;
+    /** The game's prefilter clamps at 6550.4 — a tenth of the half-float ceiling
+     *  (its BloomPass _Params.y of 100 never reaches the shader). */
+    private static readonly BLOOM_CLAMP;
     private static readonly BLOOM_MAX_LEVELS;
     private groundVertexBuffer?;
     private groundIndexBuffer?;
@@ -1453,11 +1537,6 @@ export declare class Engine {
     /** The sun's shadow atlas: every cascade in its own tile (shadow-cascades.ts). */
     private shadowAtlasTexture;
     private shadowAtlasView;
-    private brdfLutTexture;
-    private brdfLutView;
-    private filmicLutTexture;
-    private filmicLutView;
-    private static readonly FILMIC_LUT_WIDTH;
     private shadowDepthPipeline;
     private shadowLightVPBuffer;
     private shadowCascadeVPBuffers;
@@ -1521,10 +1600,10 @@ export declare class Engine {
     private bloomSettings;
     private viewTransform;
     constructor(canvas: HTMLCanvasElement, options?: EngineOptions);
-    /** Merge partial bloom with EEVEE defaults (same as constructor). */
+    /** Merge partial bloom with the defaults (same as constructor). */
     static mergeBloomDefaults(partial?: Partial<BloomOptions>): BloomOptions;
     static mergeViewTransformDefaults(partial?: Partial<ViewTransformOptions>): ViewTransformOptions;
-    /** Current bloom settings (Blender names; tint is a copied `Vec3`). */
+    /** Current bloom settings (tint is a copied `Vec3`). */
     getBloomOptions(): BloomOptions;
     getViewTransformOptions(): ViewTransformOptions;
     private colorGrading;
@@ -1550,7 +1629,7 @@ export declare class Engine {
     private uploadStageGrade;
     /** Current grade (for serialization into a scene descriptor). */
     getColorGrading(): ColorGradingOptions;
-    /** Sensor grain: how much, and whether it moves. */
+    /** Sensor grain: how much. */
     private grain;
     /**
      * Film grain over the rendered scene, 0–1.
@@ -1560,17 +1639,12 @@ export declare class Engine {
      * a background image or a backdrop video, which arrived with grain of their
      * own and would be graded rather than matched by a second helping.
      *
-     * `animated` false freezes it. A still photograph's grain does not move, and
-     * noise crawling over a frozen picture makes the rendering look more alive
-     * than the thing it is standing in.
-     *
      * Costs one hash per pixel in a pass that already runs, and nothing at all at
      * zero — the branch is on a uniform.
      */
-    setFilmGrain(amount: number, animated?: boolean): void;
+    setFilmGrain(amount: number): void;
     getFilmGrain(): Readonly<{
         amount: number;
-        animated: boolean;
     }>;
     setViewTransformOptions(patch: Partial<ViewTransformOptions>): void;
     /**
@@ -1590,6 +1664,8 @@ export declare class Engine {
      * it was written, expensive where it was reported.
      */
     private bloomContributes;
+    /** viewU[6].y per transform — see viewTransform in composite.ts. */
+    private static readonly VIEW_TRANSFORM_ID;
     private writeCompositeViewUniforms;
     /**
      * Set the canvas background color (display-space sRGB, 0–1 per channel — the
@@ -1767,7 +1843,7 @@ export declare class Engine {
      */
     private renderMirrorPass;
     /**
-     * Fill the mirror's mip levels — the bloom pyramid's own 13-tap downsample,
+     * Fill the mirror's mip levels — a 13-tap downsample (MIRROR_DOWNSAMPLE_WGSL),
      * one pass per level. Only when the blur dial is up: at zero the ground
      * samples level 0 exactly and the chain would be work nobody reads.
      */
@@ -1958,7 +2034,7 @@ export declare class Engine {
      * whether or not it is the thing you see — and it IS the thing you see until
      * a backdrop is set, which is what an HDRI on its own has always done.
      *
-     * `strength` is Blender's world-strength dial and is folded into the
+     * `strength` is the World's intensity and is folded into the
      * coefficients, so what lights her is what you see.
      */
     setWorldEquirect(source: HdrImage | null): void;
@@ -1975,7 +2051,13 @@ export declare class Engine {
      * lighting. Cleared, the world's own sky comes back.
      */
     setBackdropEquirect(source: ImageBitmap | HTMLImageElement | HTMLCanvasElement | null): void;
-    private makeCompositePipeline;
+    /**
+     * The scene composite's pair (gamma = 1, gamma ≠ 1), async and from the
+     * shader cache. Its source depends only on which field mounts the scene
+     * samples, so there are four at most, and an effect install that keeps the
+     * mounts it had gets the pair already built.
+     */
+    private compositePipelines;
     /**
      * Install the scene's WGSL effect (shadertoy-style), rendered per-pixel in the
      * composite pass. ONE effect per scene, and the code says where it mounts by
@@ -2285,7 +2367,13 @@ export declare class Engine {
     private getModelBodyFocus;
     private writeDepthOfFieldUniforms;
     setBloomOptions(patch: Partial<BloomOptions>): void;
+    private ensureBloomPipelines;
+    /** The game's chain at the current canvas size (AGSimPostFX.Bloom): half
+     *  size, then floor(log2(longest side)) - 1 levels, each half the last. */
+    private buildBloomTargets;
     private writeBloomUniforms;
+    /** The game's chain, pass for pass (AGSimPostFX.Bloom). */
+    private renderBloom;
     init(): Promise<void>;
     /** The frost tile the ground samples instead of evaluating fbm per pixel. */
     private groundNoiseTexture;
@@ -2300,18 +2388,8 @@ export declare class Engine {
      * per-pixel cost becomes a single level-0 texture read.
      */
     private bakeGroundNoise;
-    private bakeBrdfLut;
-    /**
-     * Decompress and upload Blender's AgX cube.
-     *
-     * Deliberately off the critical path: it is 723 KB once inflated, and a frame
-     * rendered before it lands should show the scene under whatever transform is
-     * already there rather than wait. Until then binding 10 holds a 1×1×1 stand-in,
-     * which is only ever sampled if someone selects AgX in that window.
-     */
-    private loadAgxLut;
-    private bakeFilmicLut;
     private createRenderPipeline;
+    private renderPipelineDesc;
     private createPipelines;
     private setupResize;
     /** When set, render resolution is pinned to this size instead of tracking the
@@ -2573,6 +2651,41 @@ export declare class Engine {
      *  resources are half-built, which is exactly the moment a host swaps a sky.
      *  Retried at the top of a frame until one of them takes. */
     private worldBindingsDirty;
+    /** Drop the capture's resources, so the next capture rebinds the sky. */
+    private dropProbeCapture;
+    /** Ask for a fresh capture of the stage's reflection probe. It runs at the
+     *  start of a frame once the scene has held still for a moment — asked for
+     *  by the engine itself whenever the stage or its looks change; a host may
+     *  call it after changing something the engine cannot see. */
+    captureReflectionProbe(): void;
+    /** The stage's world-space bounds: every stage model's material boxes
+     *  through its placement. Null without a stage. */
+    private stageBounds;
+    /** Run a pending capture once the scene has settled — see captureReflectionProbe. */
+    private maybeCaptureProbe;
+    private ensureProbeCapture;
+    /**
+     * Capture the probe: the stage drawn six times from one point into a 128²
+     * cube, the sky laid in behind it, a mip chain, and the GGX convolution
+     * into the 64² cube the materials read.
+     *
+     * WHERE: the middle of the stage's bounds across the floor, at about a
+     * character's chest height above the floor (y = 0 where the bounds span it,
+     * the MMD convention, else their bottom) — where a game puts the probe of a
+     * room the player stands in. The box it projects onto is the bounds.
+     *
+     * WHAT: the stage alone, in its own looks, lit by the scene's sun, lamps
+     * and sky as they stand. The cast is not in it (a baked probe never holds
+     * the characters), nor are effects.
+     */
+    private renderProbe;
+    /**
+     * The sky's mips, convolved with the GGX lobe each stands for — the box
+     * average the upload built is only the source. Level 0 is copied as it is
+     * (it is also what the backdrop draws); every level below it becomes the
+     * sky as a surface of that roughness reflects it (skyLevelRoughness).
+     */
+    private prefilterSky;
     /** Returns whether it actually rebuilt — see rebuildCompositeBindGroup. */
     private rebuildPerFrameBindGroups;
     /**
@@ -2583,7 +2696,6 @@ export declare class Engine {
     private writeWorld;
     /** Write sun lamp into light slot `index` (0..3). Layout mirrors the WGSL struct. */
     private writeSun;
-    /** Update the world environment (Blender: World Background). Ambient recomputes immediately. */
     /**
      * Distance fog on every lit surface, as a game on SimPipeline lays it: per
      * layer, t = saturate(f − (1 − f)·h) with f = saturate(depth·distance[0] +
@@ -2628,7 +2740,7 @@ export declare class Engine {
      */
     setWorldAmbient(sh: ArrayLike<number> | null): void;
     setWorld(options: WorldOptions): void;
-    /** Update the sun lamp (Blender: Light > Sun). Direction change marks shadow VP dirty. */
+    /** Update the main light (Unity's directional Sun). Direction change marks shadow VP dirty. */
     setSun(options: SunOptions): void;
     getWorld(): Readonly<{
         color: Vec3;
@@ -2703,6 +2815,16 @@ export declare class Engine {
      *  params make: a scene document's JSON passes straight in, and so does a
      *  literal typed into a console. Vec3 satisfies it either way. */
     lights: SceneLight[] | null): void;
+    /**
+     * A cookie, under `key`, for every spot lamp that names it (SceneLight.cookie):
+     * the picture a stage light throws through its gobo, projected along the
+     * cone — its RGB is the light let through, so black blocks, white passes and
+     * a colour tints. Square, stretched to 512². Up to 16 at once; loading a key
+     * again replaces its picture. False when every layer is taken.
+     */
+    loadLightCookie(key: string, source: Blob | ImageBitmap): Promise<boolean>;
+    /** Forget a cookie: lamps naming it light plainly again. */
+    removeLightCookie(key: string): void;
     /** How many positional lights the scene is carrying. */
     getLightCount(): number;
     /** Guarded, unlike most private writers here, because its callers are not:
@@ -2875,6 +2997,26 @@ export declare class Engine {
      * in here. Linear radiance, strength included.
      */
     setModelAmbient(name: string, sh: ArrayLike<number> | null): boolean;
+    /**
+     * Light one model with more than the world gives it: a FILL, linear RGB times
+     * its surface colour, added after its material graph. Null takes it away again.
+     *
+     * After the graph, not in its ambient: an NPR ramp reads an ambient fill as
+     * light, so sliding it moved her shadows and flipped whole regions across a
+     * hard step. Added after, it brightens her evenly and every shadow stays put.
+     *
+     * A game lights its stage and its characters apart. Aether Gazer's rooms are
+     * lit by their lamps and a near-black ambient, while its characters take a
+     * flat base light of their own — so a stage whose World is right for the room
+     * leaves a face turned from the lamps in the dark. This is that second light,
+     * for the models the host counts as cast. A model drawn by the game's own
+     * shaders (src/unity) lights itself and takes none of it.
+     */
+    setModelFill(name: string, fill: {
+        x: number;
+        y: number;
+        z: number;
+    } | null): boolean;
     /** The per-model group: its skinning matrices and its ObjectLight. */
     private perInstanceBindGroup;
     removeModel(name: string): void;
@@ -3399,6 +3541,8 @@ export declare class Engine {
      * geometry that vanishes. One of those is a bug report.
      */
     private noteSceneExtent;
+    /** Raise the scene's reach (never lower it) and hand it to the camera. */
+    private raiseSceneExtent;
     /**
      * One record per model: the rigid transform its per-material boxes live under,
      * or the world sphere that bounds it in any pose. Written every frame, because
@@ -3618,12 +3762,26 @@ export declare class Engine {
      *  diff them against the reference. */
     private readCullArgs;
     private setupModelInstance;
+    /**
+     * A model's attribute stream: vertex colour (RGBA) and a second UV set, six
+     * floats a vertex, read by the material pipelines at slot 4.
+     *
+     * PMX has no vertex colour and one UV, but it has four ADDITIONAL UV
+     * channels of four floats each, and that is where a model that needs more
+     * keeps it: the first additional UV is the vertex colour, the second's xy
+     * the second UV — the convention a converted game stage is written in (a
+     * plant's occlusion rides in its vertex alpha, a light card's mask in its
+     * second UV). A model without them reads white and its own UV, which is
+     * what every graph that reads neither already assumed.
+     */
+    private createAttributeBuffer;
     private createGpuMorph;
     private createGroundGeometry;
     /** Everything about the ground's pipeline except which shadow variant it
      *  compiles, so the two are built from one description and cannot drift. */
     private groundShadowPipelineDesc;
     private buildGroundPipeline;
+    private groundPipelineConfig;
     private groundMirrorPipeline;
     private groundMirrorSoftPipeline;
     /** The ground's pipeline for the mirror pass, built on the first frame a
@@ -3738,25 +3896,6 @@ export declare class Engine {
     private renderGizmoPass;
     private rotateVec3ByQuat;
     private unproject;
-    /**
-     * Where a point on the canvas lands on a horizontal plane.
-     *
-     * `px,py` are canvas-relative pixels, top-left origin — what a pointer event
-     * gives you after subtracting the element's rect. Returns null when the ray
-     * cannot reach the plane: parallel to it, or pointing the other way, which is
-     * what a click on the sky above the horizon is.
-     *
-     * The one primitive a placement UI needs. Dragging a thing across the floor is
-     * otherwise three sliders in world units, which asks someone to guess numbers
-     * that have no visible relation to the picture they are looking at — and it
-     * throws away the property that makes pointing work at all: under perspective,
-     * moving something further away makes it smaller by exactly the right amount,
-     * so position and size stop being two controls to tune against each other.
-     */
-    groundPointAt(px: number, py: number, planeY?: number): Vec3 | null;
-    /** Hand the pointer to something else — a placement drag, a gizmo, a host's own
-     *  overlay — so the orbit does not also act on it. */
-    setCameraInputLocked(locked: boolean): void;
     private buildMouseRay;
     private hitTestGizmo;
     private distSegmentRay;
@@ -3799,6 +3938,14 @@ export declare class Engine {
      * compile fails is not installed and its materials stay ungrouped (fallback-on-error).
      */
     applyStyleGroups(modelName: string, groups: StyleGroup[]): Promise<ApplyStyleGroupsResult>;
+    /**
+     * Compile style groups' pipelines before any model needs them — a scene's
+     * groups while its bundle is still downloading. Installs nothing: the
+     * pipelines land in the shader cache, and applyStyleGroups later finds them
+     * there (or still in flight). A group that does not compile is skipped
+     * silently; its real install reports it.
+     */
+    prewarmStyleGroups(groups: readonly StyleGroup[]): Promise<void>;
     /** Add or replace a single style group by id. `opts` may carry a `previewNode` for the
      *  editor's node-output preview workflow. */
     upsertStyleGroup(modelName: string, group: StyleGroup, opts?: CompileOptions): Promise<ApplyStyleGroupResult>;
@@ -3918,6 +4065,39 @@ export declare class Engine {
     /** A pipeline whose descriptor is kept, so a single-sided twin can be built
      *  from it on demand (see sidedPipeline). */
     private createModelPipeline;
+    private static readonly SHADER_CACHE_MAX;
+    private static readonly PIPELINE_CACHE_MAX;
+    private static trimCache;
+    /** A small stable id per GPU object, for cache keys. */
+    private gpuObjectId;
+    /** One module per WGSL source. */
+    private cachedShaderModule;
+    /** Drop a source whose module did not validate, so a retry reports afresh. */
+    private forgetShaderModule;
+    /** One bind group layout per entry list. */
+    private cachedBindGroupLayout;
+    /** One pipeline layout per bind group layout list. */
+    private cachedPipelineLayout;
+    private pipelineKey;
+    private cachedPipeline;
+    /** createRenderPipelineAsync, once per module + state. */
+    private cachedRenderPipeline;
+    /** createComputePipelineAsync, once per module + state. */
+    private cachedComputePipeline;
+    /**
+     * A pipeline init builds: async, in parallel with the rest, and in place by
+     * the time init returns (it awaits every job). Outside init — a pass built
+     * on first use — it is the synchronous build it always was.
+     */
+    private initRenderPipeline;
+    /** The compute twin of initRenderPipeline. */
+    private initComputePipeline;
+    /**
+     * Build a model pipeline's single-sided twin off the draw path (see
+     * sidedPipeline). Resolves once it is in place; never rejects — a twin that
+     * fails leaves the draw on its double-sided pipeline, as before it existed.
+     */
+    private buildSidedTwin;
     /**
      * The pipeline a draw should use once its double-sided flag is honoured.
      *
@@ -3940,6 +4120,17 @@ export declare class Engine {
      * makes outlines compose like MMD: every material drawn later in the author's
      * order covers earlier hulls, and each hull sits over everything drawn before it.
      */
+    /**
+     * A stage's draws, far to near from the eye: its transparent queue, in the
+     * order a game sorts one. Each draw's distance is its material box's centre,
+     * placed, against the camera — a pane or a water surface is one material,
+     * which is the unit a game sorts too. The array is kept per instance and
+     * re-sorted in place, so an unchanged order costs a comparison per draw.
+     */
+    private backToFront;
+    private sortedDraws;
+    private sortScratch;
+    private sortDistance;
     /** Is this draw's compiled class "hair"? Ungrouped draws never are — the
      *  neutral pipeline is the auto class. */
     private isHairDraw;
@@ -3947,9 +4138,9 @@ export declare class Engine {
     /**
      * Main-pass render sequence for one model instance — babylon-mmd parity:
      * opaque bucket, the hair-over-eyes stencil pass, then alpha-blend materials
-     * in PMX author order with depth write ON (forceDepthWrite). Outlines are not
-     * a separate phase: drawMaterials draws each edge-flagged material's hull
-     * right after the material itself, like MMD's per-mesh outline stage.
+     * in PMX author order with depth write ON (forceDepthWrite). Outlines close
+     * each drawMaterials call: the edge-flagged materials' hulls after all of its
+     * surfaces, as MMD draws a model's edges.
      */
     private setModelDrawState;
     /**
@@ -4115,6 +4306,21 @@ export declare class Engine {
      * every one still casts its shadow through the engine's pass.
      */
     setModelNativeLook(name: string, look: NativeLook | null): boolean;
+    /** Resolves once a model's native look can draw: every pass's pipeline is
+     *  compiled (async, at setModelNativeLook). Until then its dressed materials
+     *  sit out — a host reveals the model after this to avoid that gap. */
+    nativeLookReady(name: string): Promise<void>;
+    /**
+     * Set some of the values of one material a model's native look dresses —
+     * its Unity material properties by name, colours linear, as the look's
+     * `values` hold them — over the look's own, until set again. What a game
+     * animates on a material over a take (its timeline's material curves)
+     * reaches the shaders this way, one frame at a time: the caller samples its
+     * keys on its own clock and sets what it got. Only the names the material's
+     * look carries are taken, and a value equal to the one in place writes
+     * nothing. False when the model wears no look dressing that material.
+     */
+    setModelNativeUniforms(name: string, material: string, values: Record<string, number | ArrayLike<number>>): boolean;
     /** The hosts for the game's shaders: the scene pass's and the shadow atlas's,
      *  with the stand-ins an empty slot reads. Built on first use. */
     private ensureNativeHosts;