@woosh/meep-engine 3.30.0 → 3.31.0

package/src/engine/graphics3/Trail3DSystem.d.ts

@@ -1,9 +1,19 @@
 /**
- * Draws {@link Trail3D}'s tubes under Shade, on the dynamic-geometry path.
+ * Draws {@link Trail3D}'s tubes under Shade, as dynamic geometry inside the transparency pipeline.
  *
  * **A trail is dynamic content by definition** — every knot of it is rewritten as the entity moves
- * and every knot's opacity as it ages — so it goes down S4's dedicated non-meshlet path (D5/I-10),
- * the same one particles, paths and debug shapes take.
+ * and every knot's opacity as it ages — so its geometry is a {@link DynamicMesh} (D5/I-10), not a
+ * meshlet build, the same as paths and debug shapes.
+ *
+ * **It is drawn through AVBOIT, not over it.** The batch is a transparency channel
+ * ({@link DynamicMeshAVBOITChannel}, registered with the facade): its fragments go into the same
+ * extinction volume and accumulators as the transparent meshes and the GPU particles, so a trail
+ * behind glass is seen through the glass, a trail inside smoke is hidden by the smoke in front of it
+ * and hides the smoke behind it, and two trails crossing composite by depth, not by the order they
+ * were linked in. Fog of war still covers trails: it runs at `AfterTransparency`, after the
+ * transparency resolve they are part of — and so does everything else drawn there, so path display
+ * and the selection highlight land over a trail now rather than under it. Under MBOIT, the legacy
+ * transparency mode, trails are not drawn — as the particles are not.
  *
  * **The simulation is not this system's, and that is deliberate.** {@link seed_trail_tube} and
  * {@link advance_trail} are what the legacy `Trail3DSystem` runs too: the knots a trail lays down
@@ -15,11 +25,12 @@
  * every knot on every tick and the age is what the vertex opacity carries. There is no quiet trail
  * — a trail that has stopped is a trail fading out.
  *
- * **What the tube material had and this does not**: a texture, and per-trail depth writing. The
- * dynamic path has one pipeline, one vertex layout — position and colour — and one blend mode
- * (straight alpha over the finished scene, depth tested, never written), which is what a trail
- * wants and what the game's trails are authored as. `Trail3D.textureURL` therefore draws untinted
- * here; nothing in the game's own effects sets it to anything a flat colour does not carry.
+ * **What the tube material had and this does not**: a texture, lighting, and per-trail depth
+ * writing. The dynamic path has one vertex layout — position and colour — and a trail is drawn as
+ * unlit straight alpha, depth tested against the opaque scene and never written, which is what a
+ * trail wants and what the game's trails are authored as. `Trail3D.textureURL` therefore draws
+ * untinted here; nothing in the game's own effects sets it to anything a flat colour does not
+ * carry.
  */
 export class Trail3DSystem extends System<any> {
     /**
@@ -28,7 +39,7 @@ export class Trail3DSystem extends System<any> {
     constructor(graphics: GraphicsEngine);
     dependencies: (typeof Transform64 | typeof Trail3D)[];
     /**
-     * What the pass draws. Read-only — the meshes follow the entities.
+     * What the transparency channel draws. Read-only — the meshes follow the entities.
      *
      * @returns {DynamicMeshBatch}
      */
@@ -48,22 +59,20 @@ export class Trail3DSystem extends System<any> {
      */
     unlink(trail: Trail3D, transform: Transform64, entity: number): void;
     update(timeDelta: any): void;
-    /**
-     * @param {FrameContext} frame
-     */
-    record(frame: FrameContext): void;
     #private;
 }
 /**
- * A trail is drawn into the scene and is concealed by the fog of war like anything else in it.
+ * @deprecated Trails are not drawn by an extension any more. {@link Trail3DSystem} registers a
+ * transparency channel instead, so a trail is drawn inside the transparency pipeline rather than over
+ * it — see the class's own doc. This is the extension the system used to register at
+ * `AfterTransparency`; it records nothing now, and registering it draws nothing.
+ *
+ * Kept rather than removed for the reason `Trail3DSystem3` is: this is a library, and an import that
+ * stops linking stops the whole application loading, not just its trails. It warns once, when first
+ * constructed, and is the removal candidate for the next major.
  */
 export class TrailExtension extends RenderExtension {
-    /**
-     * @param {Trail3DSystem} system
-     */
-    constructor(system: Trail3DSystem);
     record(frame: any): void;
-    #private;
 }
 import { System } from "../ecs/System.js";
 import { Transform64 } from "../ecs/transform/Transform64.js";

package/src/engine/graphics3/Trail3DSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Trail3DSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/Trail3DSystem.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IA0CI;;OAEG;IACH,sCAMC;IAlDD,sDAAsC;IAgCtC;;;;OAIG;IACH,8BAEC;IAaD,2CAIC;IAED,4CAWC;IAED;;;;OAIG;IACH,YAJW,OAAO,aACP,WAAW,UACX,MAAM,QAgBhB;IAED;;;;OAIG;IACH,cAJW,OAAO,aACP,WAAW,UACX,MAAM,QAiBhB;IAED,6BAYC;IAED;;OAEG;IACH,kCAeC;;CACJ;AAED;;GAEG;AACH;IAUI;;OAEG;IACH,oBAFW,aAAa,EAMvB;IAED,yBAEC;;CACJ;uBAjNsB,kBAAkB;4BACb,iCAAiC;oBAGzC,oCAAoC;iCALvB,gDAAgD;gCAJjD,mDAAmD"}
+{"version":3,"file":"Trail3DSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/Trail3DSystem.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH;IAuCI;;OAEG;IACH,sCAMC;IA/CD,sDAAsC;IA6BtC;;;;OAIG;IACH,8BAEC;IAaD,2CAIC;IAED,4CAQC;IAED;;;;OAIG;IACH,YAJW,OAAO,aACP,WAAW,UACX,MAAM,QAgBhB;IAED;;;;OAIG;IACH,cAJW,OAAO,aACP,WAAW,UACX,MAAM,QAiBhB;IAED,6BAaC;;CACJ;AAQD;;;;;;;;;GASG;AACH;IAeI,yBAEC;CACJ;uBA5MsB,kBAAkB;4BACb,iCAAiC;oBAGzC,oCAAoC;iCALvB,gDAAgD;gCAHjD,mDAAmD"}

package/src/engine/graphics3/Trail3DSystem.js

@@ -1,10 +1,8 @@
 import { assert } from "../../core/assert.js";
-import { GPUDynamicMeshRenderer } from "../../shade/renderer/dynamic/GPUDynamicMeshRenderer.js";
-import { Geometry } from "../../shade/renderer/geometry/Geometry.js";
+import { DynamicMeshAVBOITChannel } from "../../shade/renderer/dynamic/DynamicMeshAVBOITChannel.js";
 import { FramePhase } from "../../shade/renderer/extension/FramePhase.js";
 import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
-import { SceneColor } from "../../shade/renderer/extension/SceneColor.js";
-import { ViewTextures } from "../../shade/renderer/extension/ViewTextures.js";
+import { Geometry } from "../../shade/renderer/geometry/Geometry.js";
 import { DynamicMesh } from "../../shade/renderer/scene/DynamicMesh.js";
 import { DynamicMeshBatch } from "../../shade/renderer/scene/DynamicMeshBatch.js";
 import { System } from "../ecs/System.js";
@@ -19,11 +17,21 @@ import {
 import { trail_tube_write_geometry } from "./trail/trail_tube_write_geometry.js";
 
 /**
- * Draws {@link Trail3D}'s tubes under Shade, on the dynamic-geometry path.
+ * Draws {@link Trail3D}'s tubes under Shade, as dynamic geometry inside the transparency pipeline.
  *
  * **A trail is dynamic content by definition** — every knot of it is rewritten as the entity moves
- * and every knot's opacity as it ages — so it goes down S4's dedicated non-meshlet path (D5/I-10),
- * the same one particles, paths and debug shapes take.
+ * and every knot's opacity as it ages — so its geometry is a {@link DynamicMesh} (D5/I-10), not a
+ * meshlet build, the same as paths and debug shapes.
+ *
+ * **It is drawn through AVBOIT, not over it.** The batch is a transparency channel
+ * ({@link DynamicMeshAVBOITChannel}, registered with the facade): its fragments go into the same
+ * extinction volume and accumulators as the transparent meshes and the GPU particles, so a trail
+ * behind glass is seen through the glass, a trail inside smoke is hidden by the smoke in front of it
+ * and hides the smoke behind it, and two trails crossing composite by depth, not by the order they
+ * were linked in. Fog of war still covers trails: it runs at `AfterTransparency`, after the
+ * transparency resolve they are part of — and so does everything else drawn there, so path display
+ * and the selection highlight land over a trail now rather than under it. Under MBOIT, the legacy
+ * transparency mode, trails are not drawn — as the particles are not.
  *
  * **The simulation is not this system's, and that is deliberate.** {@link seed_trail_tube} and
  * {@link advance_trail} are what the legacy `Trail3DSystem` runs too: the knots a trail lays down
@@ -35,11 +43,12 @@ import { trail_tube_write_geometry } from "./trail/trail_tube_write_geometry.js"
  * every knot on every tick and the age is what the vertex opacity carries. There is no quiet trail
  * — a trail that has stopped is a trail fading out.
  *
- * **What the tube material had and this does not**: a texture, and per-trail depth writing. The
- * dynamic path has one pipeline, one vertex layout — position and colour — and one blend mode
- * (straight alpha over the finished scene, depth tested, never written), which is what a trail
- * wants and what the game's trails are authored as. `Trail3D.textureURL` therefore draws untinted
- * here; nothing in the game's own effects sets it to anything a flat colour does not carry.
+ * **What the tube material had and this does not**: a texture, lighting, and per-trail depth
+ * writing. The dynamic path has one vertex layout — position and colour — and a trail is drawn as
+ * unlit straight alpha, depth tested against the opaque scene and never written, which is what a
+ * trail wants and what the game's trails are authored as. `Trail3D.textureURL` therefore draws
+ * untinted here; nothing in the game's own effects sets it to anything a flat colour does not
+ * carry.
  */
 export class Trail3DSystem extends System {
     dependencies = [Trail3D, Transform64];
@@ -50,14 +59,16 @@ export class Trail3DSystem extends System {
     #graphics;
 
     /**
-     * @type {GPUDynamicMeshRenderer}
+     * @type {DynamicMeshBatch}
      */
-    #renderer = new GPUDynamicMeshRenderer();
+    #batch = new DynamicMeshBatch();
 
     /**
-     * @type {DynamicMeshBatch}
+     * The batch as the transparency pipeline sees it, and the owner of its GPU buffers.
+     *
+     * @type {DynamicMeshAVBOITChannel}
      */
-    #batch = new DynamicMeshBatch();
+    #channel = new DynamicMeshAVBOITChannel(this.#batch);
 
     /**
      * @type {Map<number, {trail: Trail3D, transform: Transform, mesh: DynamicMesh}>}
@@ -70,12 +81,7 @@ export class Trail3DSystem extends System {
     #simulator = new TubeXFixedPhysicsSimulator();
 
     /**
-     * @type {RenderExtension|null}
-     */
-    #extension = null;
-
-    /**
-     * What the pass draws. Read-only — the meshes follow the entities.
+     * What the transparency channel draws. Read-only — the meshes follow the entities.
      *
      * @returns {DynamicMeshBatch}
      */
@@ -97,17 +103,14 @@ export class Trail3DSystem extends System {
     async startup(entityManager) {
         this.entityManager = entityManager;
 
-        this.#extension = this.#graphics.add_extension(new TrailExtension(this));
+        this.#graphics.add_transparency_channel(this.#channel);
     }
 
     async shutdown(entityManager) {
-        if (this.#extension !== null) {
-            this.#graphics.remove_extension(this.#extension);
-
-            this.#extension = null;
-        }
+        // says whether it was there, so a shutdown after a startup that never ran is harmless
+        this.#graphics.remove_transparency_channel(this.#channel);
 
-        this.#renderer.destroy();
+        this.#channel.destroy();
 
         this.#batch.clear();
         this.#entries.clear();
@@ -149,7 +152,7 @@ export class Trail3DSystem extends System {
         this.#batch.remove(entry.mesh);
 
         // residency deliberately survives leaving the batch, so nothing else would free it
-        this.#renderer.release(entry.mesh.geometry);
+        this.#channel.release(entry.mesh.geometry);
 
         this.#entries.delete(entity);
 
@@ -162,58 +165,48 @@ export class Trail3DSystem extends System {
 
             advance_trail(trail, entry.transform, timeDelta, this.#simulator);
 
-            // bounds are the GPU's business on this path (§4.5), so the flag the head raises has
-            // nobody else to answer it
+            // The component's own bounds serve CPU culling, which this path does not do (§4.5), and
+            // the depth range the transparency pipeline needs the channel reads off the written
+            // geometry — so the flag the head raises has nobody else to answer it.
             trail.clearFlag(Trail3DFlags.BoundsNeedUpdate);
 
             trail_tube_write_geometry(entry.mesh.geometry, trail.tube);
         }
     }
-
-    /**
-     * @param {FrameContext} frame
-     */
-    record(frame) {
-        if (this.#batch.count === 0) {
-            // nothing to draw, and the frame's colour is left exactly as it was
-            return;
-        }
-
-        const scene = frame.get(SceneColor);
-
-        scene.color = this.#renderer.graph_draw({
-            graph: frame.graph,
-            batch: this.#batch,
-            color: scene.color,
-            depth: frame.get(ViewTextures).depth,
-            camera: frame.view.camera.buffer
-        });
-    }
 }
 
 /**
- * A trail is drawn into the scene and is concealed by the fog of war like anything else in it.
+ * {@link TrailExtension} warns once per process.
+ * @type {boolean}
+ */
+let trail_extension_deprecation_warned = false;
+
+/**
+ * @deprecated Trails are not drawn by an extension any more. {@link Trail3DSystem} registers a
+ * transparency channel instead, so a trail is drawn inside the transparency pipeline rather than over
+ * it — see the class's own doc. This is the extension the system used to register at
+ * `AfterTransparency`; it records nothing now, and registering it draws nothing.
+ *
+ * Kept rather than removed for the reason `Trail3DSystem3` is: this is a library, and an import that
+ * stops linking stops the whole application loading, not just its trails. It warns once, when first
+ * constructed, and is the removal candidate for the next major.
  */
 export class TrailExtension extends RenderExtension {
     name = "trails";
 
     phase = FramePhase.AfterTransparency;
 
-    /**
-     * @type {Trail3DSystem}
-     */
-    #system;
-
-    /**
-     * @param {Trail3DSystem} system
-     */
-    constructor(system) {
+    constructor() {
         super();
 
-        this.#system = system;
+        if (!trail_extension_deprecation_warned) {
+            trail_extension_deprecation_warned = true;
+
+            console.warn('TrailExtension is deprecated and draws nothing: Trail3DSystem draws trails inside the transparency pipeline now. Remove the registration.');
+        }
     }
 
     record(frame) {
-        this.#system.record(frame);
+        // nothing: the trails are the transparency pipeline's
     }
 }

package/src/engine/graphics3/debug/gizmo_write_geometry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gizmo_write_geometry.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/debug/gizmo_write_geometry.js"],"names":[],"mappings":"AA0eA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;;;GAcG;AACH,oGAFW,SAAS,QAoCnB;;eA7gBa,YAAY;kBACZ,MAAM;aACN,WAAW;iBACX,MAAM;;;;;;;;;;SAgdN,MAAM,EAAE,GAAC,YAAY;;;;aACrB,MAAM,EAAE,GAAC,YAAY;;;;;sBACrB,MAAM;;;;;qBAEN,MAAM;;;;gBAEN,MAAM"}
+{"version":3,"file":"gizmo_write_geometry.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/debug/gizmo_write_geometry.js"],"names":[],"mappings":"AAsbA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;;;GAcG;AACH,oGAFW,SAAS,QAoCnB;;eAtda,YAAY;kBACZ,MAAM;aACN,WAAW;iBACX,MAAM;;;;;;;;;;SAyZN,MAAM,EAAE,GAAC,YAAY;;;;aACrB,MAAM,EAAE,GAAC,YAAY;;;;;sBACrB,MAAM;;;;;qBAEN,MAAM;;;;gBAEN,MAAM"}

package/src/engine/graphics3/debug/gizmo_write_geometry.js

@@ -1,6 +1,9 @@
 import { assert } from "../../../core/assert.js";
 import { max2 } from "../../../core/math/max2.js";
-import { Attribute } from "../../../shade/renderer/geometry/Attribute.js";
+import {
+    geometry_obtain_attribute,
+    geometry_obtain_index
+} from "../../../shade/renderer/geometry/geometry_obtain_attribute.js";
 import { StandardAttributes } from "../../../shade/renderer/geometry/StandardAttributes.js";
 import { make_box_geometry } from "../../../shade/renderer/geometry/primitives/make_box_geometry.js";
 import {
@@ -433,61 +436,6 @@ function expand_segments(positions, colors, indices, vertex_offset, index_offset
         index += 6;
     }
 }
-
-/**
- * @param {Geometry} geometry
- * @param {string} name
- * @param {number} item_size
- * @param {number} count
- * @returns {Float32Array}
- */
-function obtain_attribute(geometry, name, item_size, count) {
-    const existing = geometry.getAttribute(name);
-
-    if (existing === undefined) {
-        const attribute = Attribute.from(new Float32Array(count * item_size), item_size, name);
-
-        geometry.addAttribute(attribute);
-
-        return attribute.data;
-    }
-
-    if (existing.count !== count) {
-        existing.data = new Float32Array(count * item_size);
-        existing.count = count;
-    }
-
-    existing.needsUpdate = true;
-
-    return existing.data;
-}
-
-/**
- * @param {Geometry} geometry
- * @param {number} count
- * @returns {Uint32Array}
- */
-function obtain_index(geometry, count) {
-    const existing = geometry.index;
-
-    if (existing === null) {
-        const attribute = Attribute.from(new Uint32Array(count), 1, StandardAttributes.Index);
-
-        geometry.index = attribute;
-
-        return attribute.data;
-    }
-
-    if (existing.count !== count) {
-        existing.data = new Uint32Array(count);
-        existing.count = count;
-    }
-
-    existing.needsUpdate = true;
-
-    return existing.data;
-}
-
 /**
  * How the frame is being looked at, which is what turns a recorded line into a quad of a given
  * width in pixels.
@@ -540,9 +488,9 @@ export function gizmo_write_geometry(geometry, gizmo, view) {
     const vertex_count = solid_vertex_count + segments.count * 4;
     const index_count = solid_index_count + segments.count * 6;
 
-    const positions = obtain_attribute(geometry, StandardAttributes.Position, 3, vertex_count);
-    const colors = obtain_attribute(geometry, StandardAttributes.Color, 4, vertex_count);
-    const indices = obtain_index(geometry, index_count);
+    const positions = geometry_obtain_attribute(geometry, StandardAttributes.Position, 3, vertex_count);
+    const colors = geometry_obtain_attribute(geometry, StandardAttributes.Color, 4, vertex_count);
+    const indices = geometry_obtain_index(geometry, index_count);
 
     let [vertex, index] = write_solid(positions, colors, indices, 0, 0, BOX_SOLID, gizmo.boxes_solid);
 

package/src/engine/graphics3/decal/GPUDecalRenderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUDecalRenderer.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/decal/GPUDecalRenderer.js"],"names":[],"mappings":"AA4CA;;;;;;;GAOG;AACH;IA6BI;;;;;;;;;;;OAWG;IACH;QAP8B,KAAK;QACL,OAAO,EAA1B,YAAY;QACC,YAAY,EAAzB,MAAM;QACU,YAAY;QACZ,YAAY;QACZ,SAAS;aAuBnC;IAuOD,gBAaC;;CACJ"}
+{"version":3,"file":"GPUDecalRenderer.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/decal/GPUDecalRenderer.js"],"names":[],"mappings":"AA4CA;;;;;;;GAOG;AACH;IA6BI;;;;;;;;;;;OAWG;IACH;QAP8B,KAAK;QACL,OAAO,EAA1B,YAAY;QACC,YAAY,EAAzB,MAAM;QACU,YAAY;QACZ,YAAY;QACZ,SAAS;aAuBnC;IAgPD,gBAoBC;;CACJ"}

package/src/engine/graphics3/decal/GPUDecalRenderer.js

@@ -283,7 +283,8 @@ export class GPUDecalRenderer {
      *
      * The chain is the point: the borders and the per-patch LOD bound exist so that these levels can
      * be sampled without a decal reading its neighbour. Albedo is uploaded as **sRGB** so the
-     * reduction averages in the space the colours were authored in; normals get the filter that
+     * reduction averages linear light — the generator reads each level through an sRGB view, which
+     * decodes, and writes the next through one, which encodes; normals get the filter that
      * renormalizes as it goes.
      *
      * @param {GraphicsContext} graphics
@@ -299,6 +300,15 @@ export class GPUDecalRenderer {
         const existing = residency.texture;
 
         if (existing === null || existing.descriptor.size[0] !== width || existing.descriptor.size[1] !== height) {
+            // The old one goes back before the new one is taken, as every
+            // sibling does — nothing in the frame graph owns these, so nothing
+            // else reclaims them. The atlas grows several times as a level's
+            // decals load, and at 2048x2048 rgba8 with mips that is about
+            // 5.6 MB per texture left resident for the life of the device.
+            if (existing !== null) {
+                existing.destroy();
+            }
+
             const mip_levels = 1 + Math.floor(Math.log2(Math.max(width, height)));
 
             residency.texture = graphics.textures.contextFromDescriptor(TextureDescriptor.from({
@@ -306,15 +316,14 @@ export class GPUDecalRenderer {
                 format,
                 mipLevelCount: mip_levels,
                 /*
-                 `COPY_SRC` is what the mip generator needs, not what this pass does with the
-                 texture: an sRGB source has to be decoded before its levels can be averaged, and
-                 with no linear view format declared the generator does that by copying the whole
-                 texture into a linear one. Without it the copy fails validation, no mip chain is
-                 ever built, and the frame it was encoded into is dropped whole.
+                 `RENDER_ATTACHMENT` is the mip generator's, not this pass's: with it, each level is
+                 rendered straight into the atlas rather than into a scratch texture that is then
+                 copied home. There is no `COPY_SRC`, because nothing is copied out of the atlas —
+                 it carried one for a copy into a linear twin that was meant to decode the sRGB
+                 albedo and, a texture copy being byte-exact, never did.
                 */
                 usage: GPUTextureUsage.TEXTURE_BINDING
                     | GPUTextureUsage.COPY_DST
-                    | GPUTextureUsage.COPY_SRC
                     | GPUTextureUsage.RENDER_ATTACHMENT,
                 label: `decals/atlas/${format}`
             }));
@@ -352,6 +361,13 @@ export class GPUDecalRenderer {
         this.#records_capacity = 0;
 
         for (const residency of [this.#albedo, this.#normal, this.#orm]) {
+            if (residency.texture !== null) {
+                // dropping the reference is not giving the memory back —
+                // `DecalSystem.shutdown` comes through here, so a stop/start of
+                // the renderer leaked all three atlases every time
+                residency.texture.destroy();
+            }
+
             residency.texture = null;
             residency.version = -1;
             residency.source = null;

package/src/engine/graphics3/decal/shader_cluster_assign_decals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_cluster_assign_decals.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/decal/shader_cluster_assign_decals.js"],"names":[],"mappings":"AAuCA,6DAMG;AAiBH,sDAAoF;AAmIpF;;;;;;;;GAQG;AACH,2CAFU,aAAa,CAMpB;6BAjL0B,qDAAqD;4BADtD,oDAAoD;8BALlD,iDAAiD"}
+{"version":3,"file":"shader_cluster_assign_decals.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/decal/shader_cluster_assign_decals.js"],"names":[],"mappings":"AAuCA,6DAMG;AAiBH,sDAAoF;AA0JpF;;;;;;;;GAQG;AACH,2CAFU,aAAa,CAMpB;6BAxM0B,qDAAqD;4BADtD,oDAAoD;8BALlD,iDAAiD"}

package/src/engine/graphics3/decal/shader_cluster_assign_decals.js

@@ -135,18 +135,41 @@ fn main(
             continue;
         }
 
-        if (local_count >= ${DECAL_CLUSTER_LOCAL_LIMIT}u) {
-            // a froxel this crowded is a pile of surface overrides where all but the last few are
-            // invisible; dropping the tail costs nothing that can be seen
-            continue;
-        }
-
         /*
          Inserted in order, not appended. The cull list arrives scrambled by its atomic, and the
          records are laid down in priority order — so keeping this sorted by record index is what
          makes the composite walk decals in the order they are meant to be drawn. Lights can append
          because they commute; decals overwrite each other.
         */
+        if (local_count >= ${DECAL_CLUSTER_LOCAL_LIMIT}u) {
+            /*
+             Full, so something has to go — and what goes is the LOWEST priority held, not whatever
+             arrives next. Testing the count before the comparison dropped every later candidate
+             whatever its record index, and the list being walked is the cull pass's atomic-appended
+             output: the survivors were simply the first 32 the atomic happened to emit, so the same
+             frame composited a different 32 each time it ran. The priority order the records are
+             laid down in is void above the limit exactly where it matters most.
+
+             The array is sorted ascending, so slot 0 is the one to drop.
+            */
+            if (decal_index <= local_decals[0]) {
+                continue;
+            }
+
+            // walk the new index down into place, shifting the entries it passes over slot 0
+            var slot = 0u;
+
+            while (slot + 1u < ${DECAL_CLUSTER_LOCAL_LIMIT}u && local_decals[slot + 1u] < decal_index) {
+                local_decals[slot] = local_decals[slot + 1u];
+
+                slot += 1u;
+            }
+
+            local_decals[slot] = decal_index;
+
+            continue;
+        }
+
         var slot = local_count;
 
         while (slot > 0u && local_decals[slot - 1u] > decal_index) {

package/src/engine/graphics3/path/tube_stream_write_geometry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tube_stream_write_geometry.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/path/tube_stream_write_geometry.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AACH,6FAkBC"}
+{"version":3,"file":"tube_stream_write_geometry.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/path/tube_stream_write_geometry.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;GAcG;AACH,6FAkBC"}

package/src/engine/graphics3/path/tube_stream_write_geometry.js

@@ -1,5 +1,8 @@
 import { assert } from "../../../core/assert.js";
-import { Attribute } from "../../../shade/renderer/geometry/Attribute.js";
+import {
+    geometry_obtain_attribute,
+    geometry_obtain_index
+} from "../../../shade/renderer/geometry/geometry_obtain_attribute.js";
 import { StandardAttributes } from "../../../shade/renderer/geometry/StandardAttributes.js";
 
 /**
@@ -24,67 +27,15 @@ export function tube_stream_write_geometry(geometry, stream) {
     const vertex_count = stream.vertex_count;
     const index_count = stream.index_count;
 
-    const positions = obtain_positions(geometry, vertex_count);
+    const positions = geometry_obtain_attribute(geometry, StandardAttributes.Position, 3, vertex_count);
 
     positions.set(stream.positions.subarray(0, vertex_count * 3));
 
     // the shader indexes `array<u32>` and the residency uploads four bytes per index, whatever the
     // stream sized its own index array as
-    const indices = obtain_indices(geometry, index_count);
+    const indices = geometry_obtain_index(geometry, index_count);
 
     indices.set(stream.indices.subarray(0, index_count));
 
     geometry.needsUpdate = true;
-}
-
-/**
- * @param {Geometry} geometry
- * @param {number} vertex_count
- * @returns {Float32Array}
- */
-function obtain_positions(geometry, vertex_count) {
-    const existing = geometry.getAttribute(StandardAttributes.Position);
-
-    if (existing === undefined) {
-        const attribute = Attribute.from(new Float32Array(vertex_count * 3), 3, StandardAttributes.Position);
-
-        geometry.addAttribute(attribute);
-
-        return attribute.data;
-    }
-
-    if (existing.count !== vertex_count) {
-        existing.data = new Float32Array(vertex_count * 3);
-        existing.count = vertex_count;
-    }
-
-    existing.needsUpdate = true;
-
-    return existing.data;
-}
-
-/**
- * @param {Geometry} geometry
- * @param {number} index_count
- * @returns {Uint32Array}
- */
-function obtain_indices(geometry, index_count) {
-    const existing = geometry.index;
-
-    if (existing === null) {
-        const attribute = Attribute.from(new Uint32Array(index_count), 1, StandardAttributes.Index);
-
-        geometry.index = attribute;
-
-        return attribute.data;
-    }
-
-    if (existing.count !== index_count) {
-        existing.data = new Uint32Array(index_count);
-        existing.count = index_count;
-    }
-
-    existing.needsUpdate = true;
-
-    return existing.data;
-}
+}

package/src/engine/graphics3/register_instance_animation.d.ts

@@ -3,9 +3,9 @@
  *
  * **Registration is eventually consistent by design**, which is what makes this callable the moment
  * an instance exists rather than at some later moment when the scene is known to be built. An id is
- * allocated and returned synchronously, while the chain that drives deformation is queued until
- * every joint has a row in the scene. Until then the skin is inert rather than wrong: no
- * deformation runs.
+ * allocated and returned synchronously, while the skin's meshes are bound to it only once every
+ * joint has a row in the scene. Until then the skin is inert rather than wrong: its meshes draw
+ * undeformed.
  *
  * The instance's entities therefore do **not** have to hold their rows yet.
  *

package/src/engine/graphics3/register_instance_animation.js

@@ -38,9 +38,9 @@ export class InstanceAnimationRegistration {
  *
  * **Registration is eventually consistent by design**, which is what makes this callable the moment
  * an instance exists rather than at some later moment when the scene is known to be built. An id is
- * allocated and returned synchronously, while the chain that drives deformation is queued until
- * every joint has a row in the scene. Until then the skin is inert rather than wrong: no
- * deformation runs.
+ * allocated and returned synchronously, while the skin's meshes are bound to it only once every
+ * joint has a row in the scene. Until then the skin is inert rather than wrong: its meshes draw
+ * undeformed.
  *
  * The instance's entities therefore do **not** have to hold their rows yet.
  *

package/src/engine/graphics3/terrain/GPUTerrainSplatRenderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUTerrainSplatRenderer.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/terrain/GPUTerrainSplatRenderer.js"],"names":[],"mappings":"AA6EA;;;;;;;GAOG;AACH;IAyCI;;;;;;;;;;;;;;;;;;OAkBG;IACH;QAd8B,KAAK;QACN,IAAI,EAAtB,WAAW;QACE,SAAS,EAAtB,MAAM;QACa,MAAM,EAAzB,YAAY;QACC,WAAW,EAAxB,MAAM;QACa,gBAAgB,EAAnC,YAAY;QACG,cAAc,EAA7B,MAAM,EAAE;QACO,cAAc,EAA7B,MAAM,EAAE;QACO,eAAe,EAA9B,MAAM,EAAE;QACgF,OAAO,EAA/F;YAAC,IAAI,EAAE,UAAU,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAC;QACO,WAAW,EAAnG;YAAC,IAAI,EAAE,UAAU,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAC;QACjE,OAAO;QACP,MAAM;aAgEhC;IAkND,gBAwBC;;CACJ"}
+{"version":3,"file":"GPUTerrainSplatRenderer.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/terrain/GPUTerrainSplatRenderer.js"],"names":[],"mappings":"AA6EA;;;;;;;GAOG;AACH;IAyCI;;;;;;;;;;;;;;;;;;OAkBG;IACH;QAd8B,KAAK;QACN,IAAI,EAAtB,WAAW;QACE,SAAS,EAAtB,MAAM;QACa,MAAM,EAAzB,YAAY;QACC,WAAW,EAAxB,MAAM;QACa,gBAAgB,EAAnC,YAAY;QACG,cAAc,EAA7B,MAAM,EAAE;QACO,cAAc,EAA7B,MAAM,EAAE;QACO,eAAe,EAA9B,MAAM,EAAE;QACgF,OAAO,EAA/F;YAAC,IAAI,EAAE,UAAU,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAC;QACO,WAAW,EAAnG;YAAC,IAAI,EAAE,UAAU,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAC;QACjE,OAAO;QACP,MAAM;aAgEhC;IAyND,gBAwBC;;CACJ"}