reze-engine 0.61.7 → 0.62.1

package/dist/shaders/passes/grid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grid.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/grid.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AAoC7C,eAAO,MAAM,QAAQ,OAAO,CAAA;AAC5B,uEAAuE;AACvE,eAAO,MAAM,UAAU,EAAE,gBAAgC,CAAA;AAEzD,gDAAgD;AAChD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CA6B1F;AAgBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,SAAK,GAAG,MAAM,CAsFpG"}
+{"version":3,"file":"grid.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/grid.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AAqC7C,eAAO,MAAM,QAAQ,OAAO,CAAA;AAC5B,uEAAuE;AACvE,eAAO,MAAM,UAAU,EAAE,gBAAgC,CAAA;AAEzD,gDAAgD;AAChD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CA6B1F;AAgBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,SAAK,GAAG,MAAM,CAuFpG"}

package/dist/shaders/passes/grid.js

@@ -9,6 +9,7 @@ import { clockApi, trailSlotsApi, viewportApi } from "./hosted-api";
 import { idApi } from "../id-api";
 import { sceneLightApi } from "../scene-light-api";
 import { pointsApi } from "../points-api";
+import { textureApi } from "../texture-api";
 // A persistent grid an effect can step and read: the one thing an effect could
 // not have before, which is MEMORY.
 //
@@ -164,6 +165,7 @@ fn rzGrid(uv: vec2f) -> vec4f { return rzGridPrev(uv); }
         idApi(false, 0, 0) +
         sceneLightApi(false, 0, 0) +
         pointsApi(false) +
+        textureApi(0) +
         // Inlined rather than imported from cast-distance, and NOT for tidiness.
         //
         // This module and composite.ts import each other — grid takes

package/dist/shaders/passes/particles.d.ts

@@ -50,6 +50,9 @@ type ParticleSource = {
      *  bending where a foot pressed is the whole case: the bend has to persist and
      *  recover, which is memory, and memory is what the grid is for. */
     gridSize: number;
+    /** `#textures N`: pictures the shading samples (rzTexture), bound only when
+     *  N > 0 — see texture-api.ts. Omitted = 0. */
+    textures?: number;
 };
 /** Where the shading stage's five scene-light bindings start — see scene-light-api.ts. */
 export declare const PARTICLE_LIGHT_BINDING = 10;
@@ -60,6 +63,10 @@ export declare const PARTICLE_POINTS_BINDING = 15;
  *  (6, count, 0, 0), so the draw reads at byte 16. */
 export declare const PARTICLE_INDIRECT_BINDING = 16;
 export declare const PARTICLE_INDIRECT_BYTES = 32;
+/** `#textures`: the pictures at 17..20 and their one sampler at 21, render
+ *  stage only — see texture-api.ts. */
+export declare const PARTICLE_TEXTURE_BINDING = 17;
+export declare const PARTICLE_TEXTURE_SAMPLER_BINDING = 21;
 export declare const PARTICLE_INDIRECT_DRAW_OFFSET = 16;
 /** Bytes per particle. Explicitly padded — see the struct below. */
 export declare const PARTICLE_STRIDE = 48;

package/dist/shaders/passes/particles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"particles.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/particles.ts"],"names":[],"mappings":"AA+BA,sEAAsE;AACtE,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAA;IACb;;mFAE+E;IAC/E,UAAU,EAAE,MAAM,CAAA;IAClB,+EAA+E;IAC/E,KAAK,EAAE,MAAM,EAAE,CAAA;CAChB,CAAA;AAkCD,qDAAqD;AACrD;0EAC0E;AAC1E,KAAK,aAAa,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,CAAA;AAEpD,KAAK,cAAc,GAAG;IACpB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,qFAAqF;IACrF,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,aAAa,CAAA;IACpB,qEAAqE;IACrE,KAAK,EAAE,OAAO,CAAA;IACd;;+BAE2B;IAC3B,UAAU,EAAE,MAAM,CAAA;IAClB;;;;;iEAK6D;IAC7D,KAAK,EAAE,OAAO,CAAA;IACd;;;;;;;kFAO8E;IAC9E,IAAI,EAAE,OAAO,CAAA;IACb;;;wEAGoE;IACpE,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,0FAA0F;AAC1F,eAAO,MAAM,sBAAsB,KAAK,CAAA;AACxC,iFAAiF;AACjF,eAAO,MAAM,uBAAuB,KAAK,CAAA;AACzC;;sDAEsD;AACtD,eAAO,MAAM,yBAAyB,KAAK,CAAA;AAC3C,eAAO,MAAM,uBAAuB,KAAK,CAAA;AACzC,eAAO,MAAM,6BAA6B,KAAK,CAAA;AAE/C,oEAAoE;AACpE,eAAO,MAAM,eAAe,KAAK,CAAA;AAwDjC;;2EAE2E;AAC3E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAQlI;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CA0ExF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CA2LvF"}
+{"version":3,"file":"particles.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/particles.ts"],"names":[],"mappings":"AAgCA,sEAAsE;AACtE,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAA;IACb;;mFAE+E;IAC/E,UAAU,EAAE,MAAM,CAAA;IAClB,+EAA+E;IAC/E,KAAK,EAAE,MAAM,EAAE,CAAA;CAChB,CAAA;AAkCD,qDAAqD;AACrD;0EAC0E;AAC1E,KAAK,aAAa,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,CAAA;AAEpD,KAAK,cAAc,GAAG;IACpB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,qFAAqF;IACrF,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,aAAa,CAAA;IACpB,qEAAqE;IACrE,KAAK,EAAE,OAAO,CAAA;IACd;;+BAE2B;IAC3B,UAAU,EAAE,MAAM,CAAA;IAClB;;;;;iEAK6D;IAC7D,KAAK,EAAE,OAAO,CAAA;IACd;;;;;;;kFAO8E;IAC9E,IAAI,EAAE,OAAO,CAAA;IACb;;;wEAGoE;IACpE,QAAQ,EAAE,MAAM,CAAA;IAChB;mDAC+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,0FAA0F;AAC1F,eAAO,MAAM,sBAAsB,KAAK,CAAA;AACxC,iFAAiF;AACjF,eAAO,MAAM,uBAAuB,KAAK,CAAA;AACzC;;sDAEsD;AACtD,eAAO,MAAM,yBAAyB,KAAK,CAAA;AAC3C,eAAO,MAAM,uBAAuB,KAAK,CAAA;AACzC;uCACuC;AACvC,eAAO,MAAM,wBAAwB,KAAK,CAAA;AAC1C,eAAO,MAAM,gCAAgC,KAAK,CAAA;AAClD,eAAO,MAAM,6BAA6B,KAAK,CAAA;AAE/C,oEAAoE;AACpE,eAAO,MAAM,eAAe,KAAK,CAAA;AAwDjC;;2EAE2E;AAC3E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAQlI;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CA6ExF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CA6LvF"}

package/dist/shaders/passes/particles.js

@@ -12,6 +12,7 @@ import { sceneIdFieldWgsl, sceneIdPadWgsl } from "./scene-contract";
 import { idApi } from "../id-api";
 import { sceneLightApi } from "../scene-light-api";
 import { pointsApi } from "../points-api";
+import { textureApi } from "../texture-api";
 /**
  * The trail accessors, in the PARTICLE module.
  *
@@ -51,6 +52,10 @@ export const PARTICLE_POINTS_BINDING = 15;
  *  (6, count, 0, 0), so the draw reads at byte 16. */
 export const PARTICLE_INDIRECT_BINDING = 16;
 export const PARTICLE_INDIRECT_BYTES = 32;
+/** `#textures`: the pictures at 17..20 and their one sampler at 21, render
+ *  stage only — see texture-api.ts. */
+export const PARTICLE_TEXTURE_BINDING = 17;
+export const PARTICLE_TEXTURE_SAMPLER_BINDING = 21;
 export const PARTICLE_INDIRECT_DRAW_OFFSET = 16;
 /** Bytes per particle. Explicitly padded — see the struct below. */
 export const PARTICLE_STRIDE = 48;
@@ -151,6 +156,9 @@ ${src.paramsDecl}
         idApi(false, 0, 0) + castDistanceStub() + sceneLightApi(false, 0, 0) +
         // The named points, for real: particleInit is where a flame is put on a wick.
         pointsApi(true, 0, PARTICLE_POINTS_BINDING) +
+        // Stubs: textureSample is fragment-only, and a spawn rule has no use for a
+        // picture. The names resolve so the file compiles here.
+        textureApi(0) +
         (src.live
             ? `@group(0) @binding(${PARTICLE_INDIRECT_BINDING}) var<storage, read_write> _rzIndirect: array<u32, 8>;\n`
             : "") +
@@ -247,6 +255,8 @@ ${src.paramsDecl}
         // run by the time this draws, inside the scene pass. See scene-light-api.ts.
         sceneLightApi(true, 0, PARTICLE_LIGHT_BINDING) +
         pointsApi(true, 0, PARTICLE_POINTS_BINDING) +
+        // The host's pictures, for real — see texture-api.ts.
+        textureApi(src.textures ?? 0, 0, PARTICLE_TEXTURE_BINDING, PARTICLE_TEXTURE_SAMPLER_BINDING) +
         "\n// ── user effect ──\n" +
         src.wgsl +
         /* wgsl */ `

package/dist/shaders/passes/scene-contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scene-contract.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/scene-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;uDAEuD;AACvD,MAAM,MAAM,YAAY,GAAG;IACzB,+CAA+C;IAC/C,GAAG,EAAE,gBAAgB,CAAA;IACrB,iEAAiE;IACjE,GAAG,EAAE,gBAAgB,CAAA;CACtB,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,gBAA6B,CAAA;AAkB3D,8DAA8D;AAC9D,wBAAgB,SAAS,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAE3C;AAED,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED;;;;;;GAMG;AACH,KAAK,gBAAgB;AACnB,2DAA2D;AACzD,UAAU;AACZ;;+CAE+C;GAC7C,QAAQ;AACV,uEAAuE;GACrE,SAAS;AACX;;;;6EAI6E;GAC3E,QAAQ;AACV;;;;;;yEAMyE;GACvE,mBAAmB;AACrB,iEAAiE;GAC/D,UAAU;AACZ;;;mDAGmD;GACjD,mBAAmB;AACrB;;;oCAGoC;GAClC,OAAO;AACT;;;kDAGkD;GAChD,eAAe,CAAA;AAqFnB;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,EAAE,OAAO,EAAE,YAAY,GAAG,mBAAmB,EAAE,CAoBhG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,GAAG,gBAAgB,EAAE,CAE3E;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAAC,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAmB7E;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEtF;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAElD"}
+{"version":3,"file":"scene-contract.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/scene-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;uDAEuD;AACvD,MAAM,MAAM,YAAY,GAAG;IACzB,+CAA+C;IAC/C,GAAG,EAAE,gBAAgB,CAAA;IACrB,iEAAiE;IACjE,GAAG,EAAE,gBAAgB,CAAA;CACtB,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,gBAA6B,CAAA;AAkB3D,8DAA8D;AAC9D,wBAAgB,SAAS,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAE3C;AAED,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED;;;;;;GAMG;AACH,KAAK,gBAAgB;AACnB,2DAA2D;AACzD,UAAU;AACZ;;+CAE+C;GAC7C,QAAQ;AACV,uEAAuE;GACrE,SAAS;AACX;;;;6EAI6E;GAC3E,QAAQ;AACV;;;;;;yEAMyE;GACvE,mBAAmB;AACrB,iEAAiE;GAC/D,UAAU;AACZ;;;mDAGmD;GACjD,mBAAmB;AACrB;;;oCAGoC;GAClC,OAAO;AACT;;;kDAGkD;GAChD,eAAe,CAAA;AAyFnB;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,EAAE,OAAO,EAAE,YAAY,GAAG,mBAAmB,EAAE,CAoBhG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,GAAG,gBAAgB,EAAE,CAE3E;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAAC,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAmB7E;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEtF;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAElD"}

package/dist/shaders/passes/scene-contract.js

@@ -72,7 +72,7 @@ const ADD_BOTH = {
  * OVER for something that arrives ALREADY premultiplied: take the source whole
  * and let it displace the destination by its own coverage.
  *
- * The ground needs this and nothing else does. Every other class writes a
+ * The ground, the mirror and particles need it. The other classes write a
  * straight colour and an alpha, and the src-alpha factor premultiplies it once
  * on the way in. The ground cannot: its coverage is the SUM of a lit surface
  * and a colourless shadow-catcher layer, so it has to weight its own colour by
@@ -125,7 +125,11 @@ const BLENDS = {
     // everything else, and coverage is what the blend applies.
     ground: [PREMULTIPLIED_OVER, ALPHA_OVER],
     outline: [ALPHA_OVER, ALPHA_OVER],
-    particle: [ALPHA_OVER, ALPHA_OVER],
+    // PREMULTIPLIED colour: the particle fragment weights its colour by its own
+    // alpha before it writes (passes/particles.ts), so the src-alpha blend would
+    // weight it a second time — a splash at alpha 0.1 arrived at a hundredth of
+    // its colour instead of a tenth. The aux mask is written straight, as ever.
+    particle: [PREMULTIPLIED_OVER, ALPHA_OVER],
     "particle-additive": [ADD_KEEP_ALPHA, ADD_BOTH],
     trail: [ADD_PREMULTIPLIED, ALPHA_OVER],
 };

package/dist/shaders/passes/trails.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trails.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/trails.ts"],"names":[],"mappings":"AA+BA,KAAK,WAAW,GAAG;IACjB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAA;IACb;oEACgE;IAChE,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAA;IAClB,8DAA8D;IAC9D,KAAK,EAAE,OAAO,GAAG,UAAU,CAAA;IAC3B,KAAK,EAAE,OAAO,CAAA;IACd;sFACkF;IAClF,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAA;AAEnC,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAKjF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE;IACJ,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,EAAE,CAAA;IACf;;;;kFAI8E;IAC9E,SAAS,EAAE,OAAO,CAAA;CACnB,GACA,MAAM,CA6ZR"}
+{"version":3,"file":"trails.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/trails.ts"],"names":[],"mappings":"AAgCA,KAAK,WAAW,GAAG;IACjB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAA;IACb;oEACgE;IAChE,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAA;IAClB,8DAA8D;IAC9D,KAAK,EAAE,OAAO,GAAG,UAAU,CAAA;IAC3B,KAAK,EAAE,OAAO,CAAA;IACd;sFACkF;IAClF,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAA;AAEnC,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAKjF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE;IACJ,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,EAAE,CAAA;IACf;;;;kFAI8E;IAC9E,SAAS,EAAE,OAAO,CAAA;CACnB,GACA,MAAM,CA6ZR"}

package/dist/shaders/passes/trails.js

@@ -12,6 +12,7 @@ import { sceneIdFieldWgsl, sceneIdPadWgsl } from "./scene-contract";
 import { idApi } from "../id-api";
 import { sceneLightApi } from "../scene-light-api";
 import { pointsApi } from "../points-api";
+import { textureApi } from "../texture-api";
 /**
  * Sub-segments drawn between each pair of recorded samples.
  *
@@ -249,7 +250,7 @@ fn rzTurnRadius(a: vec3f, b: vec3f, c: vec3f) -> f32 {
         gridReadApi(0, 8, 9, src.gridSize) +
         // Stubbed: this module cannot read an attachment the scene pass writes — see
         // id-api.ts. The author's whole file compiles here, so the names must exist.
-        idApi(false, 0, 0) + castDistanceStub() + sceneLightApi(false, 0, 0) + pointsApi(false) +
+        idApi(false, 0, 0) + castDistanceStub() + sceneLightApi(false, 0, 0) + pointsApi(false) + textureApi(0) +
         "\n// ── user effect ──\n" +
         src.wgsl +
         /* wgsl */ `

package/dist/shaders/texture-api.d.ts

@@ -0,0 +1,9 @@
+/** How many pictures one effect can read. */
+export declare const MAX_EFFECT_TEXTURES = 4;
+/**
+ * rzTexture / rzTextureLod. `count` is the effect's `#textures` (0 = stubs);
+ * the textures take bindings first..first+count-1 in `group` and the one
+ * sampler `sampler`.
+ */
+export declare function textureApi(count: number, group?: number, first?: number, sampler?: number): string;
+//# sourceMappingURL=texture-api.d.ts.map

package/dist/shaders/texture-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"texture-api.d.ts","sourceRoot":"","sources":["../../src/shaders/texture-api.ts"],"names":[],"mappings":"AAkBA,6CAA6C;AAC7C,eAAO,MAAM,mBAAmB,IAAI,CAAA;AAEpC;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAI,EAAE,KAAK,SAAI,EAAE,OAAO,SAAI,GAAG,MAAM,CA6BnF"}

package/dist/shaders/texture-api.js

@@ -0,0 +1,54 @@
+// Pictures an effect is handed by its host — `#textures N`.
+//
+//     #textures 2
+//
+// gives the PARTICLE SHADING rzTexture(i, uv) and rzTextureLod(i, uv, lod) over
+// N images the host passes with the install (setEffects' `textures`, slot i =
+// picture i). uv (0,0) is the image's top-left row, the style graph's
+// tex_image convention, and it repeats. A slot the host left empty reads white.
+//
+// WHY: a game's splash is a picture on a card, and an effect that may only draw
+// procedurally can only ever guess at it — shape, coverage, veins, each a guess
+// to be corrected. A converted stage carries the game's own textures, and this
+// is how its particles draw them.
+//
+// Fragment-only, because textureSample is: the compute stage and every other
+// module the author's file is spliced into get STUBS returning zero, so one
+// effect file compiles in every mount it has.
+/** How many pictures one effect can read. */
+export const MAX_EFFECT_TEXTURES = 4;
+/**
+ * rzTexture / rzTextureLod. `count` is the effect's `#textures` (0 = stubs);
+ * the textures take bindings first..first+count-1 in `group` and the one
+ * sampler `sampler`.
+ */
+export function textureApi(count, group = 0, first = 0, sampler = 0) {
+    if (count <= 0) {
+        return /* wgsl */ `
+fn rzTexture(i: u32, uv: vec2f) -> vec4f { return vec4f(0.0); }
+fn rzTextureLod(i: u32, uv: vec2f, lod: f32) -> vec4f { return vec4f(0.0); }
+`;
+    }
+    const n = Math.min(count, MAX_EFFECT_TEXTURES);
+    let decl = `@group(${group}) @binding(${sampler}) var _rzTexSampler: sampler;\n`;
+    for (let k = 0; k < n; k++)
+        decl += `@group(${group}) @binding(${first + k}) var _rzTex${k}: texture_2d<f32>;\n`;
+    // Every slot is sampled unconditionally and the one asked for is selected:
+    // textureSample must be reached in uniform control flow, and a switch on a
+    // per-fragment index is not.
+    const pick = (call) => {
+        let body = "  var c = vec4f(0.0);\n";
+        for (let k = 0; k < n; k++)
+            body += `  let s${k} = ${call(k)};\n  if (i == ${k}u) { c = s${k}; }\n`;
+        return body + "  return c;\n";
+    };
+    return (decl +
+        /* wgsl */ `
+/** Picture i of the effect's #textures, at uv ((0,0) top-left, repeating). */
+fn rzTexture(i: u32, uv: vec2f) -> vec4f {
+${pick((k) => `textureSample(_rzTex${k}, _rzTexSampler, uv)`)}}
+/** The same at an explicit mip level — usable where derivatives are not. */
+fn rzTextureLod(i: u32, uv: vec2f, lod: f32) -> vec4f {
+${pick((k) => `textureSampleLevel(_rzTex${k}, _rzTexSampler, uv, lod)`)}}
+`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reze-engine",
-  "version": "0.61.7",
+  "version": "0.62.1",
   "description": "A lightweight WebGPU engine for real-time 3D MMD/PMX model rendering",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/engine.ts

@@ -118,6 +118,8 @@ import {
   buildParticleRenderShader,
   PARTICLE_LIGHT_BINDING,
   PARTICLE_POINTS_BINDING,
+  PARTICLE_TEXTURE_BINDING,
+  PARTICLE_TEXTURE_SAMPLER_BINDING,
   particleEntryPoints,
   PARTICLE_INDIRECT_BINDING,
   PARTICLE_INDIRECT_BYTES,
@@ -488,6 +490,17 @@ export type EffectParamValue = number | { x: number; y: number; z: number }
 /** A vector by shape rather than by class — Vec3 satisfies it, and so does a
  *  JSON object out of a scene document or a literal typed into a console. */
 export type XYZ = { x: number; y: number; z: number }
+/**
+ * One picture an effect's `#textures` reads, as the host holds it — slot i of
+ * the install's `textures` is rzTexture(i, uv). `srgb` for a colour picture
+ * (decoded to linear on sample), false for data. Null, or a slot past the end,
+ * reads white. The engine never fetches: images arrive decoded, as models do.
+ */
+export type EffectTextureInput = {
+  source: ImageBitmap | HTMLImageElement | HTMLCanvasElement | OffscreenCanvas | ImageData
+  srgb: boolean
+} | null
+
 export type EffectResult = {
   ok: boolean
   /** Compile/validation errors, line:col relative to the USER's WGSL. Also
@@ -1513,6 +1526,9 @@ interface EffectParticles {
    *  indirect arguments it writes them to. Null when the effect declared none —
    *  the whole pool is then stepped and drawn. */
   live: { pipeline: GPUComputePipeline; indirect: GPUBuffer; binds: [GPUBindGroup, GPUBindGroup] } | null
+  /** `#textures`: the pictures the host handed over, uploaded for this effect
+   *  alone and destroyed with it. Empty when it declared none. */
+  textures: GPUTexture[]
 }
 
 /**
@@ -4780,6 +4796,8 @@ export class Engine {
     anchors: { bone: string; trail: boolean }[],
     /** Its row of that table: local slot → scene slot. */
     alias: number[],
+    /** The pictures for `#textures`, as the host passed them. */
+    textures?: EffectTextureInput[],
   ): Promise<{ ok: true; instance: EffectInstance; warnings: string[] } | EffectResult> {
     const noMounts = { background: false, foreground: false }
     if (!this.device) return { ok: false, diagnostics: ["setEffect requires init() to have run"], mounts: noMounts, params: [], duration: 0, readsCast: false }
@@ -5100,6 +5118,7 @@ export class Engine {
       particles?.uniform.destroy()
       particles?.points?.buffer.destroy()
       particles?.live?.indirect.destroy()
+      for (const t of particles?.textures ?? []) t.destroy()
       grid?.textures[0].destroy()
       grid?.textures[1].destroy()
       grid?.uniform.destroy()
@@ -5115,7 +5134,7 @@ export class Engine {
       grid = built.state
     }
     if (wantsParticles) {
-      const built = await this.buildParticles(wgsl, d, anchors, alias, paramsFor, grid)
+      const built = await this.buildParticles(wgsl, d, anchors, alias, paramsFor, grid, textures)
       if (!built.ok) return abandon(built.diagnostics)
       particles = built.state
     }
@@ -5276,6 +5295,9 @@ export class Engine {
            *  aimed at one dancer should not spend its first frame on all four,
            *  which on a ribbon or a sigil reads as a flash. */
           subjects?: readonly string[] | null
+          /** `#textures`: slot i is the effect's rzTexture(i, uv). See
+           *  EffectTextureInput. Ignored by an effect that declares none. */
+          textures?: EffectTextureInput[]
         }[]
       | null,
   ): Promise<EffectResult[]> {
@@ -5329,6 +5351,7 @@ export class Engine {
         requested[i].params,
         perEffectAnchors[i],
         table.alias[i],
+        requested[i].textures,
       )
       if (!("instance" in built)) {
         // Contained: this one is out, the others carry on.
@@ -5444,13 +5467,13 @@ export class Engine {
    * Install ONE effect — the singleton API, kept because most scenes are one
    * effect and every existing caller uses it. A one-element setEffects.
    */
-  async setEffect(wgsl: string | null, params?: Record<string, EffectParamValue>): Promise<EffectResult> {
+  async setEffect(wgsl: string | null, params?: Record<string, EffectParamValue>, textures?: EffectTextureInput[]): Promise<EffectResult> {
     const noMounts = { background: false, foreground: false }
     if (wgsl === null) {
       await this.setEffects(null)
       return { ok: true, diagnostics: [], mounts: noMounts, params: [], duration: 0, readsCast: false }
     }
-    const [result] = await this.setEffects([{ wgsl, params }])
+    const [result] = await this.setEffects([{ wgsl, params, textures }])
     return result ?? { ok: false, diagnostics: ["effect failed to install"], mounts: noMounts, params: [], duration: 0, readsCast: false }
   }
 
@@ -5471,6 +5494,8 @@ export class Engine {
     /** This effect's own grid, already built, or null when it declared none.
      *  Read-only here: the pool samples it, the grid pass owns it. */
     grid: EffectGrid | null,
+    /** `#textures`: the host's pictures, slot for slot. */
+    textureInputs?: EffectTextureInput[],
   ): Promise<{ ok: true; state: EffectParticles } | { ok: false; diagnostics: string[] }> {
     // No pragma means "some": an author who wrote the trio clearly wants
     // particles, and failing over a missing comment would be pedantry.
@@ -5484,8 +5509,15 @@ export class Engine {
       gridSize: grid?.size ?? 0,
       cover: particleEntryPoints(wgsl).cover,
       live: particleEntryPoints(wgsl).count,
+      textures: d.textures,
     }
     const prepass = src.blend === "cutout" && src.cover
+    // `#textures`: uploaded now, each with its mips, for this effect alone. A
+    // slot the host left empty is null here and binds the white fallback.
+    const textures = this.uploadEffectTextures(textureInputs, d.textures)
+    const dropTextures = () => {
+      for (const t of textures) t?.destroy()
+    }
     const points = d.points
       ? {
           prefix: d.points,
@@ -5525,11 +5557,13 @@ export class Engine {
     const computeModule = await compile(buildParticleComputeShader(src, cast), "particle compute")
     if (Array.isArray(computeModule)) {
       points?.buffer.destroy()
+      dropTextures()
       return { ok: false, diagnostics: computeModule }
     }
     const renderModule = await compile(buildParticleRenderShader(src, cast), "particle render")
     if (Array.isArray(renderModule)) {
       points?.buffer.destroy()
+      dropTextures()
       return { ok: false, diagnostics: renderModule }
     }
 
@@ -5609,6 +5643,18 @@ export class Engine {
           ...(withIndirect
             ? [{ binding: PARTICLE_INDIRECT_BINDING, visibility: GPUShaderStage.COMPUTE, buffer: { type: "storage" as const } }]
             : []),
+          // `#textures`, the shading stage only and only when declared — an
+          // effect without them keeps exactly the layout it always had.
+          ...(shadow && textures.length
+            ? [
+                ...textures.map((_, k) => ({
+                  binding: PARTICLE_TEXTURE_BINDING + k,
+                  visibility: GPUShaderStage.FRAGMENT,
+                  texture: { sampleType: "float" as const },
+                })),
+                { binding: PARTICLE_TEXTURE_SAMPLER_BINDING, visibility: GPUShaderStage.FRAGMENT, sampler: { type: "filtering" as const } },
+              ]
+            : []),
         ],
       })
     /** One per GRID PARITY, for the reason rebuildFieldBindGroup gives: the grid
@@ -5641,6 +5687,15 @@ export class Engine {
                 ]
               : []),
             ...(withIndirect && indirect ? [{ binding: PARTICLE_INDIRECT_BINDING, resource: { buffer: indirect } }] : []),
+            ...(shadow && textures.length
+              ? [
+                  ...textures.map((t, k) => ({
+                    binding: PARTICLE_TEXTURE_BINDING + k,
+                    resource: (t ?? this.fallbackMaterialTexture).createView(),
+                  })),
+                  { binding: PARTICLE_TEXTURE_SAMPLER_BINDING, resource: this.effectTextureSampler() },
+                ]
+              : []),
           ],
         }),
       ) as [GPUBindGroup, GPUBindGroup]
@@ -5723,6 +5778,7 @@ export class Engine {
         uniform.destroy()
         points?.buffer.destroy()
         indirect?.destroy()
+        dropTextures()
         return { ok: false, diagnostics: [scoped.message] }
       }
       return {
@@ -5752,6 +5808,7 @@ export class Engine {
           }),
           points,
           live,
+          textures: textures.filter((t): t is GPUTexture => t !== null),
         },
       }
     } catch (e) {
@@ -5760,6 +5817,7 @@ export class Engine {
       uniform.destroy()
       points?.buffer.destroy()
       indirect?.destroy()
+      dropTextures()
       return { ok: false, diagnostics: [e instanceof Error ? e.message : String(e)] }
     }
   }
@@ -6528,6 +6586,7 @@ export class Engine {
       e.particles?.uniform.destroy()
       e.particles?.points?.buffer.destroy()
       e.particles?.live?.indirect.destroy()
+      for (const t of e.particles?.textures ?? []) t.destroy()
       e.particles = null
     }
   }
@@ -12396,6 +12455,54 @@ export class Engine {
     for (const set of Object.values(install.imagesByMaterial ?? {})) for (const tex of set) tex?.destroy()
   }
 
+  /**
+   * An effect's `#textures`, uploaded: `count` slots, each with a full mip chain
+   * (a splash card seen from across a stage is a few pixels, and unmipped it
+   * sparkles). Slot k is null where the host gave nothing — the bind group then
+   * reads the white fallback.
+   */
+  private uploadEffectTextures(inputs: EffectTextureInput[] | undefined, count: number): (GPUTexture | null)[] {
+    const out: (GPUTexture | null)[] = []
+    for (let k = 0; k < count; k++) {
+      const entry = inputs?.[k]
+      if (!entry) {
+        out.push(null)
+        continue
+      }
+      const src = entry.source
+      const width = Math.max(1, "naturalWidth" in src ? src.naturalWidth : src.width)
+      const height = Math.max(1, "naturalHeight" in src ? src.naturalHeight : src.height)
+      const mipLevelCount = Math.floor(Math.log2(Math.max(width, height))) + 1
+      const tex = this.device.createTexture({
+        label: `effect texture ${k}`,
+        size: [width, height],
+        mipLevelCount,
+        format: entry.srgb ? "rgba8unorm-srgb" : "rgba8unorm",
+        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT,
+      })
+      this.device.queue.copyExternalImageToTexture({ source: src }, { texture: tex }, [width, height])
+      if (mipLevelCount > 1) this.generateMipmaps(tex, mipLevelCount)
+      out.push(tex)
+    }
+    return out
+  }
+
+  private effectTextureSamplerCache: GPUSampler | null = null
+  /** Linear, mipmapped, repeating — one for every effect's pictures. */
+  private effectTextureSampler(): GPUSampler {
+    if (!this.effectTextureSamplerCache) {
+      this.effectTextureSamplerCache = this.device.createSampler({
+        label: "effect texture sampler",
+        magFilter: "linear",
+        minFilter: "linear",
+        mipmapFilter: "linear",
+        addressModeU: "repeat",
+        addressModeV: "repeat",
+      })
+    }
+    return this.effectTextureSamplerCache
+  }
+
   /** Upload a group's image maps. Sources are decoded images the host already
    *  holds; the engine never fetches, matching how models and motions arrive. */
   private uploadGroupImages(group: StyleGroup, slots = group.images): (GPUTexture | null)[] | undefined {

package/src/shaders/directives.ts

@@ -60,6 +60,16 @@ export type EffectDirectives = {
   /** `#points <prefix>`: every bone on every model whose name starts with it,
    *  as rzPoint(i) in the particle stages. Null when the file declares none. */
   points: string | null
+  /**
+   * `#textures N` (1-4): the particle shading reads N pictures the HOST hands
+   * over with the install (setEffects' `textures`), as rzTexture(i, uv) — uv
+   * (0,0) at the image's top-left, repeating. A game's own splash or spray is a
+   * picture on a card, and drawn procedurally it can only ever be a guess at
+   * it; this is how a converted stage's particles carry the real one. The
+   * other modules an effect is spliced into get the names as stubs returning
+   * zero. 0 when undeclared.
+   */
+  textures: number
   bloom: boolean
   /** This effect takes the cast apart — the host reads the timing. */
   dissolve: boolean
@@ -124,6 +134,7 @@ const SPEC = {
   lights: 1,
   grid: 1,
   points: 1,
+  textures: 1,
   bloom: 0,
   dissolve: 0,
   mirror: 0,
@@ -183,6 +194,7 @@ export function parseDirectives(wgsl: string): DirectiveResult {
     lights: 0,
     grid: 0,
     points: null,
+    textures: 0,
     bloom: false,
     dissolve: false,
     ground: null,
@@ -304,6 +316,15 @@ export function parseDirectives(wgsl: string): DirectiveResult {
       case "points":
         d.points = args[0]
         return
+      case "textures": {
+        const n = num(args[0])
+        if (n === null || !Number.isInteger(n) || n < 1 || n > 4) {
+          errors.push(`${at}: #textures takes a count from 1 to 4`)
+          return
+        }
+        d.textures = n
+        return
+      }
       case "mirror":
         d.mirror = true
         return

package/src/shaders/lights.ts

@@ -49,6 +49,7 @@ import { clockApi, trailSlotsApi, viewportApi } from "./passes/hosted-api"
 import { idApi } from "./id-api"
 import { sceneLightApi, worldAmbientWgsl } from "./scene-light-api"
 import { pointsApi } from "./points-api"
+import { textureApi } from "./texture-api"
 
 /** Words before the first record: the counts, the grid's placement and the
  *  outside mask, four vec4s — see the layout above. */
@@ -179,7 +180,7 @@ ${viewportApi("viewU[6].w")}
 ${trailSlotsApi(cast.trailCount)}
 // The id accessors, stubbed: this module cannot read an attachment the
 // scene pass writes. See id-api.ts — the author's whole file compiles here.
-${idApi(false, 0, 0) + castDistanceStub() + sceneLightApi(false, 0, 0) + pointsApi(false)}
+${idApi(false, 0, 0) + castDistanceStub() + sceneLightApi(false, 0, 0) + pointsApi(false) + textureApi(0)}
 // The dials the author declared, if any. A lamp is exactly the thing someone
 // retunes — its colour and its reach — so an emitter reads params like every
 // other mount rather than being the one place a #param resolves to nothing.

package/src/shaders/passes/composite.ts

@@ -8,6 +8,7 @@ import { audioApi } from "../audio-api"
 import { idApi } from "../id-api"
 import { sceneLightApi } from "../scene-light-api"
 import { pointsApi } from "../points-api"
+import { textureApi } from "../texture-api"
 import { castDistanceApi, CAST_FIELD_DIV } from "./cast-distance"
 import { lyricsApi, lyricsTextApi } from "../lyrics-api"
 import { midiApi } from "../midi-api"
@@ -758,6 +759,7 @@ export function buildFieldShader(effect: CompositeEffectSource): string {
     idApi(effect.ids === true, 0, 23) +
     sceneLightApi(false, 0, 0) +
     pointsApi(false) +
+    textureApi(0) +
     // Distance to the cast, in SCREEN pixels: the field is half-res, so a field
     // texel is CAST_FIELD_DIV of them and the accessor scales on the way out.
     // An author writes the width they mean and never learns how it is built.

package/src/shaders/passes/grid.ts

@@ -10,6 +10,7 @@ import { clockApi, trailSlotsApi, viewportApi } from "./hosted-api"
 import { idApi } from "../id-api"
 import { sceneLightApi } from "../scene-light-api"
 import { pointsApi } from "../points-api"
+import { textureApi } from "../texture-api"
 
 // A persistent grid an effect can step and read: the one thing an effect could
 // not have before, which is MEMORY.
@@ -172,6 +173,7 @@ fn rzGrid(uv: vec2f) -> vec4f { return rzGridPrev(uv); }
     idApi(false, 0, 0) +
     sceneLightApi(false, 0, 0) +
     pointsApi(false) +
+    textureApi(0) +
     // Inlined rather than imported from cast-distance, and NOT for tidiness.
     //
     // This module and composite.ts import each other — grid takes

package/src/shaders/passes/particles.ts

@@ -12,6 +12,7 @@ import { sceneIdFieldWgsl, sceneIdPadWgsl } from "./scene-contract"
 import { idApi } from "../id-api"
 import { sceneLightApi } from "../scene-light-api"
 import { pointsApi } from "../points-api"
+import { textureApi } from "../texture-api"
 // GPU particles for user effects: a compute step and an instanced quad draw.
 //
 // Its own shader MODULE rather than more source spliced into composite.ts, for
@@ -115,6 +116,9 @@ type ParticleSource = {
    *  bending where a foot pressed is the whole case: the bend has to persist and
    *  recover, which is memory, and memory is what the grid is for. */
   gridSize: number
+  /** `#textures N`: pictures the shading samples (rzTexture), bound only when
+   *  N > 0 — see texture-api.ts. Omitted = 0. */
+  textures?: number
 }
 
 /** Where the shading stage's five scene-light bindings start — see scene-light-api.ts. */
@@ -126,6 +130,10 @@ export const PARTICLE_POINTS_BINDING = 15
  *  (6, count, 0, 0), so the draw reads at byte 16. */
 export const PARTICLE_INDIRECT_BINDING = 16
 export const PARTICLE_INDIRECT_BYTES = 32
+/** `#textures`: the pictures at 17..20 and their one sampler at 21, render
+ *  stage only — see texture-api.ts. */
+export const PARTICLE_TEXTURE_BINDING = 17
+export const PARTICLE_TEXTURE_SAMPLER_BINDING = 21
 export const PARTICLE_INDIRECT_DRAW_OFFSET = 16
 
 /** Bytes per particle. Explicitly padded — see the struct below. */
@@ -234,6 +242,9 @@ ${src.paramsDecl}
     idApi(false, 0, 0) + castDistanceStub() + sceneLightApi(false, 0, 0) +
     // The named points, for real: particleInit is where a flame is put on a wick.
     pointsApi(true, 0, PARTICLE_POINTS_BINDING) +
+    // Stubs: textureSample is fragment-only, and a spawn rule has no use for a
+    // picture. The names resolve so the file compiles here.
+    textureApi(0) +
     (src.live
       ? `@group(0) @binding(${PARTICLE_INDIRECT_BINDING}) var<storage, read_write> _rzIndirect: array<u32, 8>;\n`
       : "") +
@@ -333,6 +344,8 @@ ${src.paramsDecl}
     // run by the time this draws, inside the scene pass. See scene-light-api.ts.
     sceneLightApi(true, 0, PARTICLE_LIGHT_BINDING) +
     pointsApi(true, 0, PARTICLE_POINTS_BINDING) +
+    // The host's pictures, for real — see texture-api.ts.
+    textureApi(src.textures ?? 0, 0, PARTICLE_TEXTURE_BINDING, PARTICLE_TEXTURE_SAMPLER_BINDING) +
     "\n// ── user effect ──\n" +
     src.wgsl +
     /* wgsl */ `

package/src/shaders/passes/scene-contract.ts

@@ -138,7 +138,7 @@ const ADD_BOTH: GPUBlendState = {
  * OVER for something that arrives ALREADY premultiplied: take the source whole
  * and let it displace the destination by its own coverage.
  *
- * The ground needs this and nothing else does. Every other class writes a
+ * The ground, the mirror and particles need it. The other classes write a
  * straight colour and an alpha, and the src-alpha factor premultiplies it once
  * on the way in. The ground cannot: its coverage is the SUM of a lit surface
  * and a colourless shadow-catcher layer, so it has to weight its own colour by
@@ -194,7 +194,11 @@ const BLENDS: Record<Exclude<SceneRenderClass, "depth-prepass">, [GPUBlendState,
   // everything else, and coverage is what the blend applies.
   ground: [PREMULTIPLIED_OVER, ALPHA_OVER],
   outline: [ALPHA_OVER, ALPHA_OVER],
-  particle: [ALPHA_OVER, ALPHA_OVER],
+  // PREMULTIPLIED colour: the particle fragment weights its colour by its own
+  // alpha before it writes (passes/particles.ts), so the src-alpha blend would
+  // weight it a second time — a splash at alpha 0.1 arrived at a hundredth of
+  // its colour instead of a tenth. The aux mask is written straight, as ever.
+  particle: [PREMULTIPLIED_OVER, ALPHA_OVER],
   "particle-additive": [ADD_KEEP_ALPHA, ADD_BOTH],
   trail: [ADD_PREMULTIPLIED, ALPHA_OVER],
 }