@woosh/meep-engine 3.53.0 → 3.55.0

package/src/engine/graphics3/DecalSystem.js

@@ -1,450 +1,447 @@
-import { assert } from "../../core/assert.js";
-import { LoadingCache } from "../../core/cache/LoadingCache.js";
-import { strictEquals } from "../../core/function/strictEquals.js";
-import { computeStringHash } from "../../core/primitives/strings/computeStringHash.js";
-import { FramePhase } from "../../shade/renderer/extension/FramePhase.js";
-import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
-import { GameAssetType } from "../asset/GameAssetType.js";
-import { ImageRGBADataLoader } from "../asset/loaders/image/ImageRGBADataLoader.js";
-import { System } from "../ecs/System.js";
-import { Transform64 } from "../ecs/transform/Transform64.js";
-import { Decal } from "../graphics/ecs/decal/v2/Decal.js";
-import { ReferencedTextureAtlas } from "../graphics/texture/atlas/ReferencedTextureAtlas.js";
-import { sampler2d_ensure_uint8_RGBA } from "../graphics/texture/sampler/sampler2d_ensure_uint8_RGBA.js";
-import { DecalAtlas } from "./decal/DecalAtlas.js";
-import { DecalAtlasFill } from "./decal/DecalAtlasFill.js";
-import { decal_atlas_max_lod } from "./decal/decal_atlas_border.js";
-import {
-    decal_identity_normal,
-    decal_identity_orm,
-    decal_pack_orm
-} from "./decal/decal_material_samplers.js";
-import { DECAL_RECORD_WORD_COUNT } from "./decal/DECAL_GPU_RECORD.js";
-import { sort_decals_by_priority, write_decal_record } from "./decal/decal_gpu_records.js";
-import { GPUDecalRenderer } from "./decal/GPUDecalRenderer.js";
-
-/**
- * Paints the game's decals into the G-buffer under Shade.
- *
- * **A decal is a surface override, not a tint** (D22): it carries albedo, a tangent-space normal,
- * roughness, metalness and emission, and it writes them into the G-buffer before anything is lit —
- * so ambient occlusion, screen-space reflection and shading all see a decal exactly as they see the
- * surface it is painted on. The renderer this replaces could only lerp diffuse colour inside a
- * forward shader.
- *
- * **Decals reach opaque surfaces only, by construction.** The G-buffer is all they touch and
- * transparency composites later, so a decal will never appear on water.
- *
- * The records are rebuilt every frame. That sounds wasteful and is the cheaper arrangement: the
- * froxel binning depends on the camera and so has to run every frame regardless, and rebuilding the
- * records alongside it means nothing has to watch a decal's colour for changes — which matters,
- * because the signal that would be watched does not fire for alpha-only edits.
- */
-export class DecalSystem extends System {
-    dependencies = [Decal, Transform64];
-
-    /**
-     * @type {GraphicsEngine}
-     */
-    #graphics;
-
-    /**
-     * @type {AssetManager}
-     */
-    #assets;
-
-    /**
-     * @type {GPUDecalRenderer}
-     */
-    #renderer = new GPUDecalRenderer();
-
-    /**
-     * Three atlases, because their contents want different mip filters and different border fills —
-     * and because albedo is sRGB while the other two are not.
-     *
-     * @type {DecalAtlas}
-     */
-    #atlas_albedo = new DecalAtlas(DecalAtlasFill.PremultipliedCoverage);
-
-    /**
-     * @type {DecalAtlas}
-     */
-    #atlas_normal = new DecalAtlas(DecalAtlasFill.EdgeExtend);
-
-    /**
-     * @type {DecalAtlas}
-     */
-    #atlas_orm = new DecalAtlas(DecalAtlasFill.EdgeExtend);
-
-    /**
-     * @type {ReferencedTextureAtlas}
-     */
-    #referenced_albedo = new ReferencedTextureAtlas(this.#atlas_albedo);
-
-    /**
-     * @type {ReferencedTextureAtlas}
-     */
-    #referenced_normal = new ReferencedTextureAtlas(this.#atlas_normal);
-
-    /**
-     * @type {ReferencedTextureAtlas}
-     */
-    #referenced_orm = new ReferencedTextureAtlas(this.#atlas_orm);
-
-    /**
-     * What every decal authoring no maps of its own shares. One patch each, packed once.
-     *
-     * @type {Sampler2D}
-     */
-    #identity_normal = decal_identity_normal();
-
-    /**
-     * @type {Sampler2D}
-     */
-    #identity_orm = decal_identity_orm();
-
-    /**
-     * @type {LoadingCache<string, Sampler2D>}
-     */
-    #textures;
-
-    /**
-     * The decals to draw, in link order until {@link update} sorts them into draw order.
-     *
-     * @type {Array<{entity: number, decal: Decal, transform: Transform, patches: object, listener: Function}>}
-     */
-    #entries = [];
-
-    /**
-     * @type {Map<number, object>}
-     */
-    #by_entity = new Map();
-
-    /**
-     * @type {Float32Array}
-     */
-    #records = new Float32Array(0);
-
-    /**
-     * @type {number}
-     */
-    #record_count = 0;
-
-    /**
-     * @type {RenderExtension|null}
-     */
-    #extension = null;
-
-    /**
-     * What the pass draws. Read-only — the decals follow the entities.
-     *
-     * @returns {Array}
-     */
-    get decals() {
-        return this.#entries;
-    }
-
-    /**
-     * @returns {number} decals packed for the GPU by the last update
-     */
-    get record_count() {
-        return this.#record_count;
-    }
-
-    /**
-     * What was packed, for a gate that wants to see it. Read-only.
-     *
-     * @returns {Float32Array}
-     */
-    get records() {
-        return this.#records;
-    }
-
-    /**
-     * @param {GraphicsEngine} graphics
-     * @param {AssetManager} assets
-     */
-    constructor(graphics, assets) {
-        super();
-
-        assert.defined(graphics, 'graphics');
-        assert.defined(assets, 'assets');
-
-        this.#graphics = graphics;
-        this.#assets = assets;
-
-        this.#textures = new LoadingCache({
-            load: key => this.#assets.promise(key, GameAssetType.Image)
-                .then(asset => sampler2d_ensure_uint8_RGBA(asset.create())),
-            keyHashFunction: computeStringHash,
-            keyEqualityFunction: strictEquals
-        });
-    }
-
-    async startup(entityManager) {
-        this.entityManager = entityManager;
-
-        const assets = this.#assets;
-
-        if (!assets.hasLoaderForType(GameAssetType.Image)) {
-            await assets.registerLoader(GameAssetType.Image, new ImageRGBADataLoader());
-        }
-
-        this.#extension = this.#graphics.add_extension(new DecalExtension(this));
-    }
-
-    async shutdown(entityManager) {
-        if (this.#extension !== null) {
-            this.#graphics.remove_extension(this.#extension);
-
-            this.#extension = null;
-        }
-
-        this.#renderer.destroy();
-
-        this.#entries.length = 0;
-        this.#by_entity.clear();
-        this.#record_count = 0;
-    }
-
-    /**
-     * The `transform` IS the projection volume, and it projects along its local **+Z** — so the
-     * surface being painted faces the other way. Get the sign backwards and every pixel of the
-     * decal is rejected by the coverage fade, silently, with every CPU-side observable here
-     * reporting success.
-     *
-     * @see Decal
-     * @see chunk_decal_surface_frame
-     *
-     * @param {Decal} decal
-     * @param {Transform64} transform
-     * @param {number} entity
-     */
-    link(decal, transform, entity) {
-        const entry = {
-            entity,
-            decal,
-            transform,
-            /**
-             * Atlas patches, acquired as the textures arrive. A decal whose albedo has not loaded
-             * yet is not packed at all — there is nothing to draw with, and drawing it with the
-             * identity patch would put a white square on the ground until the image landed.
-             */
-            patches: { albedo: null, normal: null, orm: null }
-        };
-
-        this.#entries.push(entry);
-        this.#by_entity.set(entity, entry);
-
-        this.#acquire(entry);
-    }
-
-    /**
-     * @param {Decal} decal
-     * @param {Transform64} transform
-     * @param {number} entity
-     */
-    unlink(decal, transform, entity) {
-        const entry = this.#by_entity.get(entity);
-
-        if (entry === undefined) {
-            return;
-        }
-
-        this.#release(entry);
-
-        const index = this.#entries.indexOf(entry);
-
-        if (index !== -1) {
-            this.#entries.splice(index, 1);
-        }
-
-        this.#by_entity.delete(entity);
-    }
-
-    /**
-     * @param {object} entry
-     */
-    #release(entry) {
-        const patches = entry.patches;
-
-        if (patches.albedo !== null) {
-            patches.albedo.release();
-            patches.albedo = null;
-        }
-
-        if (patches.normal !== null) {
-            patches.normal.release();
-            patches.normal = null;
-        }
-
-        if (patches.orm !== null) {
-            patches.orm.release();
-            patches.orm = null;
-        }
-    }
-
-    /**
-     * Fetch this decal's textures and take a reference on the atlas patch each lands in.
-     *
-     * Reference counted, because combat spawns a footprint decal per step and every one of them
-     * names the same file: packing a patch per footprint would repack three atlases and regenerate
-     * their mip chains several times a second.
-     *
-     * @param {object} entry
-     */
-    #acquire(entry) {
-        const decal = entry.decal;
-
-        const albedo_uri = decal.albedo_uri;
-
-        if (albedo_uri === "") {
-            return;
-        }
-
-        this.#textures.get(albedo_uri).then(sampler => {
-            if (this.#by_entity.get(entry.entity) !== entry) {
-                // unlinked while the image was in flight
-                return;
-            }
-
-            entry.patches.albedo = this.#referenced_albedo.acquire(sampler);
-        });
-
-        if (decal.uri_normal === "") {
-            entry.patches.normal = this.#referenced_normal.acquire(this.#identity_normal);
-        } else {
-            this.#textures.get(decal.uri_normal).then(sampler => {
-                if (this.#by_entity.get(entry.entity) !== entry) {
-                    return;
-                }
-
-                entry.patches.normal = this.#referenced_normal.acquire(sampler);
-            });
-        }
-
-        if (decal.uri_orm === "" && decal.uri_emissive === "") {
-            entry.patches.orm = this.#referenced_orm.acquire(this.#identity_orm);
-
-            return;
-        }
-
-        Promise.all([
-            decal.uri_orm === "" ? null : this.#textures.get(decal.uri_orm),
-            decal.uri_emissive === "" ? null : this.#textures.get(decal.uri_emissive)
-        ]).then(([orm, emissive]) => {
-            if (this.#by_entity.get(entry.entity) !== entry) {
-                return;
-            }
-
-            entry.patches.orm = this.#referenced_orm.acquire(decal_pack_orm(orm, emissive));
-        });
-    }
-
-    update(timeDelta) {
-        const entries = this.#entries;
-
-        sort_decals_by_priority(entries);
-
-        this.#atlas_albedo.update();
-        this.#atlas_normal.update();
-        this.#atlas_orm.update();
-
-        const required = entries.length * DECAL_RECORD_WORD_COUNT;
-
-        if (this.#records.length < required) {
-            this.#records = new Float32Array(required);
-        }
-
-        const records = this.#records;
-
-        let count = 0;
-
-        for (let i = 0; i < entries.length; i++) {
-            const entry = entries[i];
-            const patches = entry.patches;
-
-            if (patches.albedo === null || patches.normal === null || patches.orm === null) {
-                // still waiting on an image; a decal is packed once it can be drawn properly
-                continue;
-            }
-
-            const albedo = patches.albedo.getValue();
-            const normal = patches.normal.getValue();
-            const orm = patches.orm.getValue();
-
-            write_decal_record(
-                records,
-                count * DECAL_RECORD_WORD_COUNT,
-                entry.decal,
-                entry.transform.matrix,
-                { albedo: albedo.uv, normal: normal.uv, orm: orm.uv },
-                {
-                    albedo: decal_atlas_max_lod(albedo.padding),
-                    normal: decal_atlas_max_lod(normal.padding),
-                    orm: decal_atlas_max_lod(orm.padding)
-                }
-            );
-
-            count++;
-        }
-
-        this.#record_count = count;
-    }
-
-    /**
-     * @param {FrameContext} frame
-     */
-    record(frame) {
-        if (this.#record_count === 0) {
-            /*
-             Nothing to paint, so the frame keeps the G-buffer it already had. Skipping is what makes
-             the replacement design free when no decal is on screen — the pass reads and rewrites
-             every pixel when it runs.
-            */
-            return;
-        }
-
-        this.#renderer.graph_draw({
-            frame,
-            records: this.#records,
-            record_count: this.#record_count,
-            atlas_albedo: this.#atlas_albedo.sampler,
-            atlas_normal: this.#atlas_normal.sampler,
-            atlas_orm: this.#atlas_orm.sampler
-        });
-    }
-}
-
-/**
- * **Late on the phase**, because a decal composites over surfaces that are already written rather
- * than preceding them — anything another extension writes into the G-buffer at this phase. That
- * requirement used to be met by putting a registration call above an `await` and writing a comment
- * about it; here it is the declaration below. The textured ground no longer depends on it: terrain is
- * shaded in the G-buffer pass itself, before any extension runs.
- */
-export class DecalExtension extends RenderExtension {
-    name = "decals";
-
-    phase = FramePhase.AfterGBuffer;
-
-    relative_order = 1;
-
-    /**
-     * @type {DecalSystem}
-     */
-    #system;
-
-    /**
-     * @param {DecalSystem} system
-     */
-    constructor(system) {
-        super();
-
-        this.#system = system;
-    }
-
-    record(frame) {
-        this.#system.record(frame);
-    }
-}
+import { assert } from "../../core/assert.js";
+import { FramePhase } from "../../shade/renderer/extension/FramePhase.js";
+import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
+import { GameAssetType } from "../asset/GameAssetType.js";
+import { ImageRGBADataLoader } from "../asset/loaders/image/ImageRGBADataLoader.js";
+import { System } from "../ecs/System.js";
+import { Transform64 } from "../ecs/transform/Transform64.js";
+import { Decal } from "../graphics/ecs/decal/v2/Decal.js";
+import { ManagedAtlas } from "../graphics/texture/atlas/ManagedTextureAtlas.js";
+import { SpriteAtlas } from "../graphics/texture/atlas/SpriteAtlas.js";
+import { SpriteAtlasFill } from "../graphics/texture/atlas/SpriteAtlasFill.js";
+import { sprite_atlas_max_lod } from "../graphics/texture/atlas/sprite_atlas_border.js";
+import { sampler2d_ensure_uint8_RGBA } from "../graphics/texture/sampler/sampler2d_ensure_uint8_RGBA.js";
+import {
+    decal_identity_normal,
+    decal_identity_orm,
+    decal_pack_orm
+} from "./decal/decal_material_samplers.js";
+import { DECAL_RECORD_WORD_COUNT } from "./decal/DECAL_GPU_RECORD.js";
+import { sort_decals_by_priority, write_decal_record } from "./decal/decal_gpu_records.js";
+import { GPUDecalRenderer } from "./decal/GPUDecalRenderer.js";
+
+/**
+ * Paints the game's decals into the G-buffer under Shade.
+ *
+ * **A decal is a surface override, not a tint** (D22): it carries albedo, a tangent-space normal,
+ * roughness, metalness and emission, and it writes them into the G-buffer before anything is lit —
+ * so ambient occlusion, screen-space reflection and shading all see a decal exactly as they see the
+ * surface it is painted on. The renderer this replaces could only lerp diffuse colour inside a
+ * forward shader.
+ *
+ * **Decals reach opaque surfaces only, by construction.** The G-buffer is all they touch and
+ * transparency composites later, so a decal will never appear on water.
+ *
+ * The records are rebuilt every frame. That sounds wasteful and is the cheaper arrangement: the
+ * froxel binning depends on the camera and so has to run every frame regardless, and rebuilding the
+ * records alongside it means nothing has to watch a decal's colour for changes — which matters,
+ * because the signal that would be watched does not fire for alpha-only edits.
+ */
+export class DecalSystem extends System {
+    dependencies = [Decal, Transform64];
+
+    /**
+     * @type {GraphicsEngine}
+     */
+    #graphics;
+
+    /**
+     * @type {AssetManager}
+     */
+    #assets;
+
+    /**
+     * @type {GPUDecalRenderer}
+     */
+    #renderer = new GPUDecalRenderer();
+
+    /**
+     * Three atlases, because their contents want different mip filters and different border fills —
+     * and because albedo is sRGB while the other two are not.
+     *
+     * @type {SpriteAtlas}
+     */
+    #atlas_albedo = new SpriteAtlas(SpriteAtlasFill.PremultipliedCoverage);
+
+    /**
+     * @type {SpriteAtlas}
+     */
+    #atlas_normal = new SpriteAtlas(SpriteAtlasFill.EdgeExtend);
+
+    /**
+     * @type {SpriteAtlas}
+     */
+    #atlas_orm = new SpriteAtlas(SpriteAtlasFill.EdgeExtend);
+
+    /**
+     * @type {ManagedAtlas}
+     */
+    #managed_albedo;
+
+    /**
+     * @type {ManagedAtlas}
+     */
+    #managed_normal;
+
+    /**
+     * @type {ManagedAtlas}
+     */
+    #managed_orm;
+
+    /**
+     * What every decal authoring no maps of its own shares. One patch each, packed once.
+     *
+     * @type {Sampler2D}
+     */
+    #identity_normal = decal_identity_normal();
+
+    /**
+     * @type {Sampler2D}
+     */
+    #identity_orm = decal_identity_orm();
+
+    /**
+     * The decals to draw, in link order until {@link update} sorts them into draw order.
+     *
+     * @type {Array<{entity: number, decal: Decal, transform: Transform, patches: object, listener: Function}>}
+     */
+    #entries = [];
+
+    /**
+     * @type {Map<number, object>}
+     */
+    #by_entity = new Map();
+
+    /**
+     * @type {Float32Array}
+     */
+    #records = new Float32Array(0);
+
+    /**
+     * @type {number}
+     */
+    #record_count = 0;
+
+    /**
+     * @type {RenderExtension|null}
+     */
+    #extension = null;
+
+    /**
+     * What the pass draws. Read-only — the decals follow the entities.
+     *
+     * @returns {Array}
+     */
+    get decals() {
+        return this.#entries;
+    }
+
+    /**
+     * @returns {number} decals packed for the GPU by the last update
+     */
+    get record_count() {
+        return this.#record_count;
+    }
+
+    /**
+     * What was packed, for a gate that wants to see it. Read-only.
+     *
+     * @returns {Float32Array}
+     */
+    get records() {
+        return this.#records;
+    }
+
+    /**
+     * @param {GraphicsEngine} graphics
+     * @param {AssetManager} assets
+     */
+    constructor(graphics, assets) {
+        super();
+
+        assert.defined(graphics, 'graphics');
+        assert.defined(assets, 'assets');
+
+        this.#graphics = graphics;
+        this.#assets = assets;
+
+        this.#managed_albedo = new ManagedAtlas({
+            assetManager: this.#assets,
+            atlas: this.#atlas_albedo
+        });
+
+        this.#managed_normal = new ManagedAtlas({
+            assetManager: this.#assets,
+            atlas: this.#atlas_normal
+        });
+
+        this.#managed_orm = new ManagedAtlas({
+            atlas: this.#atlas_orm,
+            load: async (key) => {
+                const separator = key.indexOf("\0");
+                const uri_orm = key.slice(0, separator);
+                const uri_emissive = key.slice(separator + 1);
+
+                const [orm, emissive] = await Promise.all([
+                    uri_orm === "" ? null : this.#load_sampler(uri_orm),
+                    uri_emissive === "" ? null : this.#load_sampler(uri_emissive)
+                ]);
+
+                return decal_pack_orm(orm, emissive);
+            }
+        });
+    }
+
+    /**
+     * @param {string} uri
+     * @returns {Promise<import("../graphics/texture/sampler/Sampler2D.js").Sampler2D>}
+     */
+    async #load_sampler(uri) {
+        const asset = await this.#assets.promise(uri, GameAssetType.Image);
+
+        return sampler2d_ensure_uint8_RGBA(asset.create());
+    }
+
+    async startup(entityManager) {
+        this.entityManager = entityManager;
+
+        const assets = this.#assets;
+
+        if (!assets.hasLoaderForType(GameAssetType.Image)) {
+            await assets.registerLoader(GameAssetType.Image, new ImageRGBADataLoader());
+        }
+
+        this.#extension = this.#graphics.add_extension(new DecalExtension(this));
+    }
+
+    async shutdown(entityManager) {
+        if (this.#extension !== null) {
+            this.#graphics.remove_extension(this.#extension);
+
+            this.#extension = null;
+        }
+
+        for (let i = 0; i < this.#entries.length; i++) {
+            this.#release(this.#entries[i]);
+        }
+
+        this.#renderer.destroy();
+
+        this.#entries.length = 0;
+        this.#by_entity.clear();
+        this.#record_count = 0;
+    }
+
+    /**
+     * The `transform` IS the projection volume, and it projects along its local **+Z** — so the
+     * surface being painted faces the other way. Get the sign backwards and every pixel of the
+     * decal is rejected by the coverage fade, silently, with every CPU-side observable here
+     * reporting success.
+     *
+     * @see Decal
+     * @see chunk_decal_surface_frame
+     *
+     * @param {Decal} decal
+     * @param {Transform64} transform
+     * @param {number} entity
+     */
+    link(decal, transform, entity) {
+        const entry = {
+            entity,
+            decal,
+            transform,
+            /**
+             * Atlas patches, acquired as the textures arrive. A decal whose albedo has not loaded
+             * yet is not packed at all — there is nothing to draw with, and drawing it with the
+             * identity patch would put a white square on the ground until the image landed.
+             */
+            patches: { albedo: null, normal: null, orm: null }
+        };
+
+        this.#entries.push(entry);
+        this.#by_entity.set(entity, entry);
+
+        this.#acquire(entry);
+    }
+
+    /**
+     * @param {Decal} decal
+     * @param {Transform64} transform
+     * @param {number} entity
+     */
+    unlink(decal, transform, entity) {
+        const entry = this.#by_entity.get(entity);
+
+        if (entry === undefined) {
+            return;
+        }
+
+        this.#release(entry);
+
+        const index = this.#entries.indexOf(entry);
+
+        if (index !== -1) {
+            this.#entries.splice(index, 1);
+        }
+
+        this.#by_entity.delete(entity);
+    }
+
+    /**
+     * @param {object} entry
+     */
+    #release(entry) {
+        const patches = entry.patches;
+
+        if (patches.albedo !== null) {
+            patches.albedo.release();
+            patches.albedo = null;
+        }
+
+        if (patches.normal !== null) {
+            patches.normal.release();
+            patches.normal = null;
+        }
+
+        if (patches.orm !== null) {
+            patches.orm.release();
+            patches.orm = null;
+        }
+    }
+
+    /**
+     * Fetch this decal's textures and take a reference on the atlas patch each lands in.
+     *
+     * Reference counted and graveyard cached through {@link ManagedAtlas}, because combat spawns a
+     * footprint decal per step and every one of them names the same file: packing or erasing a patch
+     * per footprint would repack three atlases and regenerate their mip chains several times a second.
+     *
+     * @param {object} entry
+     */
+    #acquire(entry) {
+        const decal = entry.decal;
+
+        const albedo_uri = decal.albedo_uri;
+
+        if (albedo_uri === "") {
+            return;
+        }
+
+        entry.patches.albedo = this.#managed_albedo.acquire(albedo_uri);
+
+        entry.patches.normal = decal.uri_normal === ""
+            ? this.#managed_normal.acquire_sampler(this.#identity_normal)
+            : this.#managed_normal.acquire(decal.uri_normal);
+
+        entry.patches.orm = (decal.uri_orm === "" && decal.uri_emissive === "")
+            ? this.#managed_orm.acquire_sampler(this.#identity_orm)
+            : this.#managed_orm.acquire(`${decal.uri_orm}\0${decal.uri_emissive}`);
+    }
+
+    update(timeDelta) {
+        const entries = this.#entries;
+
+        sort_decals_by_priority(entries);
+
+        this.#managed_albedo.update();
+        this.#managed_normal.update();
+        this.#managed_orm.update();
+
+        const required = entries.length * DECAL_RECORD_WORD_COUNT;
+
+        if (this.#records.length < required) {
+            this.#records = new Float32Array(required);
+        }
+
+        const records = this.#records;
+
+        let count = 0;
+
+        for (let i = 0; i < entries.length; i++) {
+            const entry = entries[i];
+            const patches = entry.patches;
+
+            const albedo = patches.albedo?.getValue() ?? null;
+            const normal = patches.normal?.getValue() ?? null;
+            const orm = patches.orm?.getValue() ?? null;
+
+            if (albedo === null || normal === null || orm === null) {
+                // still waiting on an image; a decal is packed once it can be drawn properly
+                continue;
+            }
+
+            write_decal_record(
+                records,
+                count * DECAL_RECORD_WORD_COUNT,
+                entry.decal,
+                entry.transform.matrix,
+                { albedo: albedo.uv, normal: normal.uv, orm: orm.uv },
+                {
+                    albedo: sprite_atlas_max_lod(albedo.padding),
+                    normal: sprite_atlas_max_lod(normal.padding),
+                    orm: sprite_atlas_max_lod(orm.padding)
+                }
+            );
+
+            count++;
+        }
+
+        this.#record_count = count;
+    }
+
+    /**
+     * @param {FrameContext} frame
+     */
+    record(frame) {
+        if (this.#record_count === 0) {
+            /*
+             Nothing to paint, so the frame keeps the G-buffer it already had. Skipping is what makes
+             the replacement design free when no decal is on screen — the pass reads and rewrites
+             every pixel when it runs.
+            */
+            return;
+        }
+
+        this.#renderer.graph_draw({
+            frame,
+            records: this.#records,
+            record_count: this.#record_count,
+            atlas_albedo: this.#atlas_albedo.sampler,
+            atlas_normal: this.#atlas_normal.sampler,
+            atlas_orm: this.#atlas_orm.sampler
+        });
+    }
+}
+
+/**
+ * **Late on the phase**, because a decal composites over surfaces that are already written rather
+ * than preceding them — anything another extension writes into the G-buffer at this phase. That
+ * requirement used to be met by putting a registration call above an `await` and writing a comment
+ * about it; here it is the declaration below. The textured ground no longer depends on it: terrain is
+ * shaded in the G-buffer pass itself, before any extension runs.
+ */
+export class DecalExtension extends RenderExtension {
+    name = "decals";
+
+    phase = FramePhase.AfterGBuffer;
+
+    relative_order = 1;
+
+    /**
+     * @type {DecalSystem}
+     */
+    #system;
+
+    /**
+     * @param {DecalSystem} system
+     */
+    constructor(system) {
+        super();
+
+        this.#system = system;
+    }
+
+    record(frame) {
+        this.#system.record(frame);
+    }
+}