reze-engine 0.50.11 → 0.51.0

package/dist/engine.js

@@ -2,7 +2,7 @@ import { Camera } from "./camera";
 import { decodeDds, isDds } from "./dds-loader";
 import { Mat4, Quat, Vec3 } from "./math";
 import { decodePsd, isPsd } from "./psd-loader";
-import { MATERIAL_MORPH_MULTIPLY } from "./model";
+import { Model, MATERIAL_MORPH_MULTIPLY } from "./model";
 import { MORPH_COMPUTE_WGSL } from "./shaders/passes/morph";
 import { CULL_COMPUTE_WGSL } from "./shaders/passes/cull";
 import { buildAnchorTable, anchorAliasWgsl, EMPTY_ANCHOR_TABLE } from "./shaders/anchor-table";
@@ -41,6 +41,7 @@ import { PICK_SHADER_WGSL } from "./shaders/passes/pick";
 import { MIPMAP_BLIT_SHADER_WGSL } from "./shaders/passes/mipmap";
 import { compileGraph } from "./graph/compile";
 import { DEFAULT_GRAPH } from "./graph/presets/default";
+import { UNLIT_GRAPH } from "./graph/presets/unlit";
 import { FACE_GRAPH } from "./graph/presets/face";
 import { HAIR_GRAPH } from "./graph/presets/hair";
 import { BODY_GRAPH } from "./graph/presets/body";
@@ -983,6 +984,8 @@ export class Engine {
         this.framePhysicsMsRaw = 0;
         /** Every shadow caster in one sphere: (x, y, z, radius). radius 0 = nothing
          *  casts, -1 = do not use (a rigid caster has no sphere). See updateCasterSphere. */
+        /** A card's own texture, by model key — see setPlaneFrame. */
+        this.planeTextures = new Map();
         this.casterSphere = new Float32Array(4);
         /** The ground's uniform block, kept so the caster sphere can be refreshed in
          *  it every frame rather than rebuilding the buffer (addGround allocates). */
@@ -2040,41 +2043,6 @@ export class Engine {
             primitive: { topology: "triangle-list" },
         });
     }
-    /**
-     * 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
-     * which of these it defines — either, or both in one file:
-     *
-     *     fn background(ray: vec3f, uv: vec2f, time: f32) -> vec4f
-     *     fn foreground(ray: vec3f, uv: vec2f, time: f32, depth: f32) -> vec4f
-     *
-     * `background` is a LAYER between the base background and the scene,
-     * over-composited onto whichever base is active (solid color, 360 equirect, or
-     * transparency) — its alpha lets the base show through, so a starfield is
-     * stars over the user's background color. `foreground` composites over the
-     * finished frame instead, which is where rain, snow, petals and fog live, and
-     * is handed `depth`: the camera-space distance in metres of whatever the scene
-     * drew at that pixel (the far plane where it drew nothing). Compare a
-     * particle's own distance against it and the model occludes it; fog just reads
-     * it, since fog's alpha IS a function of distance.
-     *
-     * `ray` is the pixel's normalized world-space view direction (LH, +Z forward —
-     * what the skybox samples by), `uv` is 0..1 bottom-left origin, `time` is
-     * seconds since apply, and `bgResolution()` gives the canvas size. Return sRGB
-     * + alpha; alpha is the only "how much does this replace" control there is.
-     * Declared `params` arrive as `params.<name>` (number → f32, Vec3 → vec3f),
-     * shared by both mounts, and are later tweaked without recompiling via
-     * setEffectParam.
-     *
-     * Both mounts are display-space: neither affects lighting, bloom or
-     * tonemapping, and both are captured by offline export. A foreground makes the
-     * scene pass STORE its depth buffer (it otherwise discards it into tile
-     * memory) for as long as one is installed.
-     *
-     * Compiles off the hot path (async pipelines): on failure the previous effect
-     * is KEPT and diagnostics are returned with line numbers relative to the
-     * user's WGSL. Pass null to remove the effect.
-     */
     async compileEffect(wgsl, params, 
     /** This effect's own declarations, already parsed by the caller — which had
      *  to read them anyway to build the scene table. */
@@ -2170,6 +2138,28 @@ export class Engine {
         // pinning an effect that declares this has to keep installing; saying so is
         // all that was ever missing.
         const warnings = [];
+        // A DIRECTIVE THAT PARSED AS NOTHING.
+        //
+        // Every pragma is matched with `\s*$` after it, so a line that carries a
+        // note as well — `// @fullres — glyph edges are sub-pixel detail` — matches
+        // none of them and is read as an ordinary comment. Nothing failed, nothing
+        // said anything, and the effect simply ran without the property it asked
+        // for: three shipped effects were silently half-res and a fourth silently
+        // stopped being additive, each one's first line explaining why it needed
+        // the thing it was not getting.
+        //
+        // Every directive this engine knows, so an unrecognised one is named rather
+        // than ignored. Cheap: it runs once per install, over a file a human wrote.
+        for (const m of wgsl.matchAll(/^[ \t]*\/\/[ \t]*(@[a-zA-Z]+)(.*)$/gm)) {
+            const [, tag, rest] = m;
+            if (!Engine.KNOWN.has(tag)) {
+                warnings.push(`${tag} is not a directive this engine knows — it will be ignored.`);
+            }
+            else if (rest.trim() && !/^\s*[\w.\-+]+(\s+[\w.\-+]+)*\s*$/.test(rest)) {
+                warnings.push(`${tag} has a note on the same line, so it does not parse and is being IGNORED. ` +
+                    `A directive must be alone on its line — put the note on the next one.`);
+            }
+        }
         if (parseParticleBloom(wgsl) && !wantsParticles && !wantsTrails) {
             warnings.push("// @bloom does nothing here. A field effect (background/foreground) composites after tone " +
                 "mapping, past the bloom pyramid — the directive applies to particles and ribbons, which draw " +
@@ -2406,7 +2396,22 @@ export class Engine {
             epochScene: this.sceneClock,
             // Its OWN resolution, no longer the scene's: an effect that never asked
             // for full res is not promoted because a neighbour did.
-            fieldLayer: /^\s*\/\/\s*@fullres\s*$/m.test(wgsl) ? 0 : 1,
+            // FULL RESOLUTION UNLESS TOLD OTHERWISE.
+            //
+            // It was the other way round, and the default was the bug. An author
+            // who has never heard of the flag writes an effect with an edge in it
+            // and gets a soft one — nothing fails, nothing warns, because nothing
+            // was declared to fail. Three shipped effects DID declare it and were
+            // half-res anyway on a parsing technicality, which is the same bug
+            // wearing a different hat: the safe answer has to be the one you get
+            // for saying nothing.
+            //
+            // The cost is real and is why the half layer stays: `@halfres` is worth
+            // about 3.7x on a full-screen effect (Footprints, measured, 1.2ms
+            // against 4.5ms). It is the right call for a soft additive glow, which
+            // upsamples invisibly — and it is now a claim an author makes about
+            // their own effect rather than a fate that befalls one.
+            fieldLayer: /^\s*\/\/\s*@halfres\s*$/m.test(wgsl) ? 1 : 0,
             fieldPipeline,
             fieldClock,
             // Filled by rebuildFieldBindGroup below, which needs the instance to
@@ -3345,7 +3350,9 @@ export class Engine {
             return null;
         const view = this.camera.getViewMatrix().values;
         for (const inst of this.modelInstances.values()) {
-            if (!inst.model.visible || inst.isStage)
+            // Neither a stage nor a plane is a performer, so neither is a subject an
+            // effect can follow.
+            if (!inst.model.visible || inst.isStage || inst.isPlane)
                 continue;
             const model = inst.model;
             const matrices = model.getWorldMatrices();
@@ -4837,6 +4844,21 @@ export class Engine {
             // refresh on resize or effects aspect-correct against the stale size.
             if (this.compositeUniformBuffer)
                 this.writeCompositeViewUniforms();
+            // RELEASED BEFORE REPLACING. WebGPU does not free a texture when the last
+            // JS reference drops — it waits for GC, which has no idea a 130 MB MSAA
+            // target is riding on a small object. The id and mirror targets below
+            // already did this; the seven main scene targets did not, so every resize
+            // orphaned the whole set.
+            //
+            // A video export is what made it hurt: it resizes UP to the output size
+            // and back DOWN on the way out, so one 4K render orphaned roughly a third
+            // of a gigabyte, twice. A few exports in one session and the tab is
+            // starved — slow, then slow to reload.
+            //
+            // destroy() is safe against work already submitted: the implementation
+            // defers the free until the GPU is done. What it forbids is USING a
+            // destroyed texture in a new command, and every view is rebuilt below.
+            this.multisampleTexture?.destroy();
             this.multisampleTexture = this.device.createTexture({
                 label: "multisample HDR render target",
                 size: [width, height],
@@ -4844,6 +4866,7 @@ export class Engine {
                 format: this.hdrFormat,
                 usage: GPUTextureUsage.RENDER_ATTACHMENT,
             });
+            this.hdrResolveTexture?.destroy();
             this.hdrResolveTexture = this.device.createTexture({
                 label: "HDR resolve target",
                 size: [width, height],
@@ -4856,6 +4879,7 @@ export class Engine {
             this.createFieldTargets();
             // Bloom-mask MRT attachments — same dims + MSAA as HDR so they share the render pass.
             // MS buffer gets resolved into maskResolveTexture, which the bloom blit pass samples.
+            this.multisampleMaskTexture?.destroy();
             this.multisampleMaskTexture = this.device.createTexture({
                 label: "multisample bloom mask",
                 size: [width, height],
@@ -4863,6 +4887,7 @@ export class Engine {
                 format: Engine.BLOOM_MASK_FORMAT,
                 usage: GPUTextureUsage.RENDER_ATTACHMENT,
             });
+            this.maskResolveTexture?.destroy();
             this.maskResolveTexture = this.device.createTexture({
                 label: "bloom mask resolve",
                 size: [width, height],
@@ -5002,6 +5027,7 @@ export class Engine {
             const bh = Math.max(1, Math.floor(height / 2));
             const shortSide = Math.max(1, Math.min(bw, bh));
             this.bloomMipCount = Math.max(1, Math.min(Engine.BLOOM_MAX_LEVELS, Math.floor(Math.log2(shortSide)) - 1));
+            this.bloomDownTexture?.destroy();
             this.bloomDownTexture = this.device.createTexture({
                 label: "bloom down pyramid",
                 size: [bw, bh],
@@ -5009,6 +5035,7 @@ export class Engine {
                 format: this.hdrFormat,
                 usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
             });
+            this.bloomUpTexture?.destroy();
             this.bloomUpTexture = this.device.createTexture({
                 label: "bloom up pyramid",
                 size: [bw, bh],
@@ -5025,6 +5052,7 @@ export class Engine {
             for (let i = 0; i < upLevels; i++) {
                 this.bloomUpMipViews.push(this.bloomUpTexture.createView({ baseMipLevel: i, mipLevelCount: 1 }));
             }
+            this.depthTexture?.destroy();
             this.depthTexture = this.device.createTexture({
                 label: "depth texture",
                 size: [width, height],
@@ -5691,7 +5719,7 @@ export class Engine {
             // is first in insertion order and was seeding this clock with its own
             // permanent zero. In a scene with a stage, a camera VMD therefore sampled
             // frame 0 forever and the shot never moved.
-            if (inst.isStage)
+            if (inst.isStage || inst.isPlane)
                 continue;
             const p = inst.model.getAnimationProgress();
             if (p.playing || p.paused)
@@ -6033,7 +6061,7 @@ export class Engine {
         const reader = assetReader ?? createFetchAssetReader();
         const basePath = deriveBasePathFromPmxPath(pmxPath);
         model.setAssetContext(reader, basePath);
-        await this.setupModelInstance(key, model, basePath, reader, options?.stage ?? false);
+        await this.setupModelInstance(key, model, basePath, reader, options?.stage ?? false, options?.plane ?? false, options?.dynamic ?? false);
         return key;
     }
     /**
@@ -6061,6 +6089,163 @@ export class Engine {
             this.setModelTransform(key, options.transform);
         return key;
     }
+    /**
+     * Put a picture in the scene as a flat card.
+     *
+     * The thing compositors arrange in a post tool's fake 3D space — Nuke calls
+     * it a Card, After Effects a 3D layer, MMD 板ポリ — except the space here is
+     * the real one. A card is occluded by anything in front of it, occludes what
+     * is behind it, takes perspective when turned, and is caught by depth of
+     * field like everything else, because it is ordinary geometry rather than a
+     * layer composited afterwards.
+     *
+     * It is a MODEL, deliberately. Not a new kind of scene object with its own
+     * list, its own persistence and its own selection: a card wants a position,
+     * a rotation and a size, which is exactly what a model already has, and
+     * everything built around models — the transform, the shadow settings, the
+     * material editor, the asset bundle — works on it the day it exists. It is
+     * not a STAGE, though: it skips the same machinery for the same reasons, and
+     * leaves the floor alone. See ModelInstance.isPlane.
+     *
+     * @returns the model key, for setModelTransform and removeModel.
+     */
+    async addPlane(options) {
+        const { image, name, width, height } = options;
+        const hw = Math.max(width, 1e-4) / 2;
+        const hh = Math.max(height, 1e-4) / 2;
+        // A quad on the XY plane, facing +Z, centred on its own origin — so a
+        // rotation turns it about its middle and a position places its centre,
+        // which is what a handle in the viewport implies.
+        //
+        // V IS FLIPPED, and this is the whole of it: a picture's rows run downward
+        // from its top-left, a UV runs upward from the bottom-left, and a card that
+        // renders its image upside down looks like a bug in everything else.
+        // prettier-ignore
+        const vertexData = new Float32Array([
+            // x     y     z    nx   ny   nz   u    v
+            -hw, -hh, 0.0, 0.0, 0.0, 1.0, 0.0, 1.0,
+            hw, -hh, 0.0, 0.0, 0.0, 1.0, 1.0, 1.0,
+            hw, hh, 0.0, 0.0, 0.0, 1.0, 1.0, 0.0,
+            -hw, hh, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0,
+        ]);
+        // Two triangles, counter-clockwise seen from +Z. A second pair wound the
+        // other way is how "visible from behind" is done here, rather than a
+        // per-material cull flag the rest of the engine has no concept of.
+        const indices = options.doubleSided ? [0, 1, 2, 0, 2, 3, 0, 2, 1, 0, 3, 2] : [0, 1, 2, 0, 2, 3];
+        const indexData = new Uint32Array(indices);
+        // The texture table's one entry. The path is a key, not a location — the
+        // reader below answers it from memory, so nothing is fetched and nothing is
+        // written to disk.
+        //
+        // A PLAIN RELATIVE NAME under a plain directory, because the loader treats
+        // this exactly as it treats a PMX's: it takes the model path's directory
+        // and JOINS the texture entry onto it. A scheme-looking path went through
+        // that as `plane://` + `plane://name` and matched nothing, so every card
+        // came out with the untextured fallback. `plane/<name>` joins to
+        // `plane/<name>` and stays unique per card, which the engine-wide texture
+        // cache needs it to be.
+        const texturePath = `plane/${name}`;
+        const material = {
+            name,
+            diffuse: [1, 1, 1, 1],
+            specular: [0, 0, 0],
+            ambient: [0, 0, 0],
+            shininess: 0,
+            diffuseTextureIndex: 0,
+            normalTextureIndex: -1,
+            sphereTextureIndex: -1,
+            sphereMode: 0,
+            toonTextureIndex: -1,
+            sharedToon: false,
+            // 0 CARRIES TWO DECISIONS, both wanted, and both silent if changed.
+            //
+            // No inverted-hull outline (bit 0x10): a card is not a character, and a
+            // black rim around a light leak is the opposite of what it is for.
+            //
+            // AND NO SHADOW (bit 0x04, which is what castsShadow reads). A card is
+            // usually light or artwork rather than an object, and a rectangle of hard
+            // shadow thrown across the stage by a gradient reads as the renderer
+            // being broken. Set geometry that SHOULD cast one is the rarer case, and
+            // it can say so.
+            edgeFlag: 0,
+            edgeColor: [0, 0, 0, 1],
+            edgeSize: 0,
+            vertexCount: indices.length,
+        };
+        // ONE BONE, because Model requires one — it throws on an empty skeleton,
+        // every vertex has to be skinned to something, and a card has nothing to
+        // articulate. It is never posed; the model transform is what moves a card.
+        const skeleton = {
+            bones: [{ name: "全ての親", parentIndex: -1, bindTranslation: [0, 0, 0], children: [] }],
+            inverseBindMatrices: new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]),
+        };
+        const vertexCount = 4;
+        const joints = new Uint16Array(vertexCount * 4);
+        const weights = new Uint8Array(vertexCount * 4);
+        for (let i = 0; i < vertexCount; i++)
+            weights[i * 4] = 255;
+        const model = new Model(vertexData, indexData, [{ path: name, name }], [material], skeleton, { joints, weights }, { morphs: [] });
+        // ITS OWN PATH, not addStage's. A plane and a stage skip the same machinery
+        // and mean different things, and routing one through the other is how the
+        // ground came to be suppressed by adding a picture.
+        // The picture answers from memory, whatever it is asked for: a card has
+        // exactly ONE texture, so there is nothing to disambiguate and no way for a
+        // path to be wrong. Matching the string instead is what silently produced
+        // untextured cards, because the loader composes that string itself.
+        const reader = { readBinary: async () => image };
+        const key = await this.addModel(model, texturePath, name, reader, { plane: true, dynamic: options.dynamic });
+        // UNLIT, because a card is FOOTAGE and not a surface.
+        //
+        // Its pixels were finished somewhere else — a gradient painted in
+        // Photoshop, a title, a rendered element — so its brightness is the artwork
+        // rather than a response to anything. Shading it means the sun dimming one
+        // side of a thing that has no sides, and the world colour tinting a picture
+        // whose colour was the point. Left ungrouped it would take the neutral
+        // Principled base, which is exactly that mistake.
+        //
+        // A group, not a hard-coded pipeline: a card used as SET geometry — a photo
+        // of a wall, a poster standing in the room — genuinely does want the light,
+        // and this is the same control every other material is changed through, so
+        // that case is a graph swap rather than a feature request.
+        await this.applyStyleGroups(key, [
+            { id: "plane", label: "Plane", materials: [name], graph: UNLIT_GRAPH, alphaMode: "hashed" },
+        ]);
+        if (options.transform)
+            this.setModelTransform(key, options.transform);
+        // Kept so a moving card can push frames into it. The cache is keyed by the
+        // texture's logical path, which is derived rather than stored anywhere the
+        // caller can see — and deriving it twice is how the two would drift.
+        const tex = this.textureCache.get(texturePath);
+        if (tex)
+            this.planeTextures.set(key, tex);
+        return key;
+    }
+    /**
+     * Replace what a card is showing, in place.
+     *
+     * For a moving card: a video element, a decoded frame, a canvas — anything
+     * copyExternalImageToTexture accepts. Nothing is reallocated and no bind group
+     * is rebuilt, so this is a per-frame call rather than a per-clip one; the
+     * texture is written where it stands and the material keeps pointing at it.
+     *
+     * The frame must be the size the card was created at. A card is a fixed
+     * rectangle of texels and resizing one mid-clip would mean rebuilding the
+     * material behind it — so the caller allocates the card at its video's size
+     * and this refuses anything else rather than stretching it silently.
+     */
+    setPlaneFrame(id, source, width, height) {
+        const tex = this.planeTextures.get(id);
+        if (!tex || !this.device)
+            return false;
+        if (tex.width !== width || tex.height !== height)
+            return false;
+        this.device.queue.copyExternalImageToTexture({ source }, { texture: tex }, [width, height]);
+        // A moving card is allocated with one level precisely so this is never
+        // reached: rebuilding a mip pyramid per frame is a pass per level per card.
+        if (tex.mipLevelCount > 1)
+            this.generateMipmaps(tex, tex.mipLevelCount);
+        return true;
+    }
     /** True while a stage is in the scene. Two things turn on it: the built-in
      *  ground plane must not draw, and the far shadow cascade has nothing to
      *  cover without one (see the cascade loop). */
@@ -6079,6 +6264,9 @@ export class Engine {
         const inst = this.modelInstances.get(name);
         if (!inst)
             return;
+        // Before the texture cache below frees it: a stale entry here would hand a
+        // destroyed texture to the next setPlaneFrame.
+        this.planeTextures.delete(name);
         inst.model.stop();
         for (const path of inst.textureCacheKeys) {
             const tex = this.textureCache.get(path);
@@ -6331,10 +6519,10 @@ export class Engine {
             // A stage never solves IK — nothing drives its chains — and skips the pose
             // pass entirely while it is idle. Morph changes still come through, since
             // that is the one thing a stage's controls do move.
-            const stageIdle = inst.isStage && inst.model.isIdle();
+            const stageIdle = (inst.isStage || inst.isPlane) && inst.model.isIdle();
             let verticesChanged = false;
             if (!stageIdle) {
-                verticesChanged = inst.model.update(deltaTime, inst.isStage ? false : this.ikEnabled);
+                verticesChanged = inst.model.update(deltaTime, inst.isStage || inst.isPlane ? false : this.ikEnabled);
                 inst.skinMatricesDirty = true;
             }
             animMs += performance.now() - tAnim;
@@ -7284,7 +7472,7 @@ export class Engine {
                 });
         }
     }
-    async setupModelInstance(name, model, basePath, assetReader, isStage = false) {
+    async setupModelInstance(name, model, basePath, assetReader, isStage = false, isPlane = false, dynamicTexture = false) {
         const vertices = model.getVertices();
         const skinning = model.getSkinning();
         const skeleton = model.getSkeleton();
@@ -7327,7 +7515,7 @@ export class Engine {
         // A stage never simulates, so its bodies are never built — constructing the
         // solver for the heaviest mesh in the scene and dropping it afterwards was
         // both wasted work and an invariant maintained in the wrong place.
-        const physics = !isStage && rbs.length > 0 ? new RezePhysics(rbs, model.getJoints()) : null;
+        const physics = !isStage && !isPlane && rbs.length > 0 ? new RezePhysics(rbs, model.getJoints()) : null;
         // Which bones the simulation will overwrite, handed to the pose pipeline so
         // the append (付与) pass can consume the simulated result instead of the
         // animated one. Precomputed here, once, because the answer is topology —
@@ -7399,6 +7587,8 @@ export class Engine {
             pickPerInstanceBindGroup,
             pickDrawCalls: [],
             isStage,
+            isPlane,
+            dynamicTexture,
             // Seeded true: the bind pose has to reach the GPU once before any frame.
             skinMatricesDirty: true,
             hiddenMaterials: new Set(),
@@ -7820,7 +8010,21 @@ export class Engine {
             bounds[3] += grow;
             bounds[4] += grow;
             bounds[5] += grow;
-            const type = isTransparent ? "transparent" : "opaque";
+            // A CARD IS ALWAYS OPAQUE-PHASE, whatever its alpha says.
+            //
+            // The scene pass runs opaque -> ground -> transparent, and the ground
+            // writes depth at every opacity (effects locate the floor by it). Every
+            // card qualifies as transparent — a cutout has translucent texels, and a
+            // video card starts from a blank sheet that is nothing but — so cards
+            // drew after the ground and an INVISIBLE floor rejected them. Turning the
+            // ground down for the shadow catcher made pictures disappear into it.
+            //
+            // Not a workaround: alphaMode "hashed" is alpha-to-coverage, which is the
+            // transparency technique built for this phase, and addPlane already sets
+            // it. The cost is dithering on a large soft gradient, where MSAA has four
+            // coverage levels to spend — a cutout edge, which is what a card usually
+            // has, resolves exactly.
+            const type = inst.isPlane ? "opaque" : isTransparent ? "transparent" : "opaque";
             inst.drawCalls.push({
                 type,
                 count: indexCount,
@@ -8113,7 +8317,13 @@ export class Engine {
                 `so sheer fabric will not blend. The canvas 2D readback is what failed.`);
         }
         this.textureAlphaCache.set(cacheKey, alphaPlane);
-        const mipLevelCount = Math.floor(Math.log2(Math.max(width, height))) + 1;
+        // NO MIPS FOR A MOVING CARD. The chain would have to be rebuilt on every
+        // frame written into it — a full pyramid of render passes per video plane
+        // per frame, which is most of what a moving card was costing. Level 0 is
+        // the only level a card in frame reads anyway; the price is aliasing on one
+        // shrunk far into the distance, which is the case a video card is least
+        // often in.
+        const mipLevelCount = inst.dynamicTexture ? 1 : Math.floor(Math.log2(Math.max(width, height))) + 1;
         const texture = this.device.createTexture({
             label: `texture: ${cacheKey}`,
             size: [width, height],
@@ -10316,6 +10526,66 @@ Engine.FILMIC_LUT_WIDTH = 256;
 // (vsync-to-vsync), recomputed at STATS_REFRESH_MS so the readout doesn't flicker.
 Engine.STATS_WINDOW = 120;
 Engine.STATS_REFRESH_MS = 500;
+/**
+ * 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
+ * which of these it defines — either, or both in one file:
+ *
+ *     fn background(ray: vec3f, uv: vec2f, time: f32) -> vec4f
+ *     fn foreground(ray: vec3f, uv: vec2f, time: f32, depth: f32) -> vec4f
+ *
+ * `background` is a LAYER between the base background and the scene,
+ * over-composited onto whichever base is active (solid color, 360 equirect, or
+ * transparency) — its alpha lets the base show through, so a starfield is
+ * stars over the user's background color. `foreground` composites over the
+ * finished frame instead, which is where rain, snow, petals and fog live, and
+ * is handed `depth`: the camera-space distance in metres of whatever the scene
+ * drew at that pixel (the far plane where it drew nothing). Compare a
+ * particle's own distance against it and the model occludes it; fog just reads
+ * it, since fog's alpha IS a function of distance.
+ *
+ * `ray` is the pixel's normalized world-space view direction (LH, +Z forward —
+ * what the skybox samples by), `uv` is 0..1 bottom-left origin, `time` is
+ * seconds since apply, and `bgResolution()` gives the canvas size. Return sRGB
+ * + alpha; alpha is the only "how much does this replace" control there is.
+ * Declared `params` arrive as `params.<name>` (number → f32, Vec3 → vec3f),
+ * shared by both mounts, and are later tweaked without recompiling via
+ * setEffectParam.
+ *
+ * Both mounts are display-space: neither affects lighting, bloom or
+ * tonemapping, and both are captured by offline export. A foreground makes the
+ * scene pass STORE its depth buffer (it otherwise discards it into tile
+ * memory) for as long as one is installed.
+ *
+ * Compiles off the hot path (async pipelines): on failure the previous effect
+ * is KEPT and diagnostics are returned with line numbers relative to the
+ * user's WGSL. Pass null to remove the effect.
+ */
+/**
+ * Every directive an effect may declare — used ONLY to tell an author that
+ * the line they wrote is not doing what they think. See compileEffect.
+ *
+ * It has to be complete, including the ones this engine does not read itself:
+ * `@dissolve` is parsed by the host, and warning about it would be worse than
+ * the silence this replaced — a false alarm on a working line teaches authors
+ * to ignore the channel.
+ */
+Engine.KNOWN = new Set([
+    "@anchor",
+    "@layer",
+    "@blend",
+    "@bloom",
+    "@lights",
+    "@grid",
+    "@particles",
+    "@halfres",
+    // Accepted and inert: full resolution is the default now, and an effect
+    // that still says so is right about what it wants. Warning about it would
+    // be telling authors off for the thing that used to be necessary.
+    "@fullres",
+    // The HOST's, not this engine's — see the note above.
+    "@dissolve",
+]);
 // ── GPU frustum cull ────────────────────────────────────────────────────────
 //
 // Sizes, once, so the arithmetic below is readable: a DrawMeta is 32 bytes

package/dist/graph/presets/unlit.d.ts

@@ -0,0 +1,3 @@
+import type { ShaderGraph } from "../schema";
+export declare const UNLIT_GRAPH: ShaderGraph;
+//# sourceMappingURL=unlit.d.ts.map

package/dist/graph/presets/unlit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unlit.d.ts","sourceRoot":"","sources":["../../../src/graph/presets/unlit.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAE5C,eAAO,MAAM,WAAW,EAAE,WAmBzB,CAAA"}

package/dist/graph/presets/unlit.js

@@ -0,0 +1,34 @@
+// Unlit — the texture, at its own brightness, and nothing else.
+//
+// What FOOTAGE needs. A media plane carries pixels somebody already finished
+// somewhere else: a gradient painted in Photoshop, a title card, a rendered
+// element. Shading it is not a stylistic choice but a mistake — the scene's sun
+// would dim one side of a card that has no side, and the world colour would
+// tint artwork whose colour is the point. Blender's answer is the same one:
+// wire the image straight into an Emission shader and let it out at the value
+// it was authored at.
+//
+// Emission rather than Principled with roughness 1: emission is radiance, so it
+// leaves the light loop entirely instead of being an unusually flat surface
+// inside it. That is also what lets a card sit in front of a lamp without
+// picking up its highlight.
+export const UNLIT_GRAPH = {
+    version: 1,
+    name: "Unlit",
+    tags: ["unlit", "plane"],
+    nodes: [
+        { id: "tex", type: "texture" },
+        // The PMX material colour still multiplies in, so a plane can be tinted or
+        // faded through the same dial every other material uses rather than needing
+        // one of its own.
+        { id: "mat", type: "material_diffuse" },
+        { id: "base", type: "mix/multiply", inputs: { fac: 1.0 } },
+        { id: "emit", type: "emission", inputs: { strength: 1.0 } },
+    ],
+    links: [
+        { from: { node: "tex", socket: "color" }, to: { node: "base", socket: "a" } },
+        { from: { node: "mat", socket: "color" }, to: { node: "base", socket: "b" } },
+        { from: { node: "base", socket: "color" }, to: { node: "emit", socket: "color" } },
+    ],
+    output: { node: "emit", socket: "color" },
+};

package/dist/index.d.ts

@@ -18,6 +18,7 @@ export { BODY_GRAPH } from "./graph/presets/body";
 export { STOCKINGS_GRAPH } from "./graph/presets/stockings";
 export { EYE_GRAPH } from "./graph/presets/eye";
 export { FACE_GRAPH } from "./graph/presets/face";
+export { UNLIT_GRAPH } from "./graph/presets/unlit";
 export { Model, MATERIAL_MORPH_MULTIPLY, MATERIAL_MORPH_ADD, type ClipEventInfo, type RootMotionProfile, type Morph, type Morphing, type BoneMorphOffset, type MaterialMorphOffset, type UvMorphOffset, } from "./model";
 export { Vec3, Quat, Mat4, easeInOut, type EulerOrder } from "./math";
 export type { AnimationClip, AnimationPlayOptions, AnimationProgress, BlendEntry, BoneKeyframe, IkKeyframe, MorphKeyframe, BoneInterpolation, ControlPoint, } from "./animation";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,qBAAqB,EACrB,8BAA8B,EAC9B,sBAAsB,EACtB,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,QAAQ,GACd,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AACvG,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAGzC,OAAO,EAAE,QAAQ,EAAE,KAAK,QAAQ,EAAE,MAAM,OAAO,CAAA;AAE/C,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,QAAQ,EAAE,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAIrH,OAAO,EAAE,gBAAgB,EAAE,KAAK,QAAQ,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAA;AAChF,OAAO,EACL,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,SAAS,GACf,MAAM,iBAAiB,CAAA;AACxB,YAAY,EACV,WAAW,EACX,SAAS,EACT,SAAS,EACT,YAAY,EACZ,WAAW,EACX,UAAU,GACX,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,KAAK,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAC3E,OAAO,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC7G,YAAY,EACV,UAAU,EACV,UAAU,EACV,gBAAgB,EAChB,eAAe,EACf,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAA;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AAC/D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACnD,OAAO,EACL,KAAK,EACL,uBAAuB,EACvB,kBAAkB,EAClB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,KAAK,EACV,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,aAAa,GACnB,MAAM,SAAS,CAAA;AAChB,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,QAAQ,CAAA;AACrE,YAAY,EACV,aAAa,EACb,oBAAoB,EACpB,iBAAiB,EACjB,UAAU,EACV,YAAY,EACZ,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,YAAY,GACb,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,aAAa,GACnB,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,qBAAqB,EAAE,KAAK,YAAY,EAAE,KAAK,iBAAiB,EAAE,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAC5H,OAAO,EACL,GAAG,EACH,iBAAiB,EACjB,wBAAwB,EACxB,mCAAmC,GACpC,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,SAAS,EAAE,4BAA4B,EAAE,KAAK,cAAc,EAAE,KAAK,OAAO,EAAE,MAAM,cAAc,CAAA;AACzG,OAAO,EAAE,SAAS,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAChE,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,OAAO,EAAE,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAA;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AACvC,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/index.js

@@ -22,6 +22,7 @@ export { BODY_GRAPH } from "./graph/presets/body";
 export { STOCKINGS_GRAPH } from "./graph/presets/stockings";
 export { EYE_GRAPH } from "./graph/presets/eye";
 export { FACE_GRAPH } from "./graph/presets/face";
+export { UNLIT_GRAPH } from "./graph/presets/unlit";
 export { Model, MATERIAL_MORPH_MULTIPLY, MATERIAL_MORPH_ADD, } from "./model";
 export { Vec3, Quat, Mat4, easeInOut } from "./math";
 export { LocomotionController, } from "./locomotion";