@woosh/meep-engine 3.11.3 → 3.12.0

package/src/engine/graphics3/DecalSystem3.js

@@ -1,441 +1,10 @@
-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 { TerrainExtension } from "./TerrainSystem3.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 { Transform } from "../ecs/transform/Transform.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";
+import { DecalSystem } from "./DecalSystem.js";
 
 /**
- * Paints the game's decals into the G-buffer under Shade.
+ * @deprecated Renamed to {@link DecalSystem}. The trailing `3` marked the 2.x → 3.x renderer transition;
+ * the 2.x name it disambiguated against is gone, so the suffix no longer distinguishes anything.
  *
- * **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 DecalSystem3 extends System {
-    dependencies = [Decal, Transform];
-
-    /**
-     * @type {GraphicsEngine3}
-     */
-    #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 {GraphicsEngine3} 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;
-    }
-
-    /**
-     * @param {Decal} decal
-     * @param {Transform} 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 {Transform} 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
-        });
-    }
-}
-
-/**
- * **After the terrain**, because the decal composite has to see the textured ground rather than
- * precede it. 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.
+ * Kept as a re-export rather than removed: this is a library, and an import path is as much a
+ * published interface as a class name.
  */
-export class DecalExtension extends RenderExtension {
-    name = "decals";
-
-    phase = FramePhase.AfterGBuffer;
-
-    after = [TerrainExtension];
-
-    /**
-     * @type {DecalSystem3}
-     */
-    #system;
-
-    /**
-     * @param {DecalSystem3} system
-     */
-    constructor(system) {
-        super();
-
-        this.#system = system;
-    }
-
-    record(frame) {
-        this.#system.record(frame);
-    }
-}
+export const DecalSystem3 = DecalSystem;

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

@@ -0,0 +1,74 @@
+/**
+ * Draws the level's fog of war under Shade.
+ *
+ * **The mask stays where it was.** `FogOfWar` owns a CPU `Sampler2D` and a distance field, and every
+ * gameplay query — what a unit can see, what the AI may know, whether an entity is drawn at all —
+ * reads them. None of that moves to the GPU; the renderer is handed the same array, as a texture.
+ *
+ * **The composite is a pass at {@link FramePhase.AfterTransparency}.** That is the last phase where
+ * the frame's colour and its depth are the same size — after it the image is upscaled to the output
+ * resolution while the depth buffer stays at the internal one — and the fog is a screen-space read
+ * of depth, so the two have to agree texel for texel. It also puts the fog inside the tonemapper
+ * rather than over it, which is what the phase is for.
+ */
+export class FogOfWarSystem extends System<any> {
+    /**
+     * @param {GraphicsEngine} graphics
+     */
+    constructor(graphics: GraphicsEngine);
+    dependencies: (typeof Terrain | typeof FogOfWar)[];
+    /**
+     * What the pass draws. Read-only — the fields follow the entities.
+     *
+     * @returns {FogField[]}
+     */
+    get fields(): FogField[];
+    startup(entityManager: any): Promise<void>;
+    shutdown(entityManager: any): Promise<void>;
+    /**
+     * @param {FrameContext} frame
+     */
+    record(frame: FrameContext): void;
+    /**
+     * @param {FogOfWar} fow
+     * @param {Terrain} terrain
+     * @param {number} entity
+     */
+    link(fow: FogOfWar, terrain: Terrain, entity: number): void;
+    /**
+     * @param {FogOfWar} fow
+     * @param {Terrain} terrain
+     * @param {number} entity
+     */
+    unlink(fow: FogOfWar, terrain: Terrain, entity: number): void;
+    update(timeDelta: any): void;
+    #private;
+}
+/**
+ * **Last among the content extensions**, because the fog conceals and therefore belongs over
+ * everything it is meant to conceal — particles, trails, the path display and the selection
+ * highlight all draw before it and are all subject to it. Written down here rather than being a
+ * property of where a registration call happened to sit, which is how it came to be wrong.
+ *
+ * The declaration is stated from this side, over the content extensions, so that adding another one
+ * is a change to that extension and not to this list. {@link DebugDrawExtension} is the one thing
+ * that goes after the fog, and it says so itself.
+ */
+export class FogOfWarExtension extends RenderExtension {
+    /**
+     * @param {FogOfWarSystem} system
+     */
+    constructor(system: FogOfWarSystem);
+    after: (typeof HighlightExtension | typeof ParticleExtension | typeof PathDisplayExtension | typeof TrailExtension)[];
+    record(frame: any): void;
+    #private;
+}
+import { System } from "../ecs/System.js";
+import Terrain from "../ecs/terrain/ecs/Terrain.js";
+import { FogOfWar } from "../ecs/fow/FogOfWar.js";
+import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
+import { HighlightExtension } from "./HighlightSystem.js";
+import { ParticleExtension } from "./ParticleEmitterSystem.js";
+import { PathDisplayExtension } from "./PathDisplaySystem.js";
+import { TrailExtension } from "./Trail3DSystem.js";
+//# sourceMappingURL=FogOfWarSystem.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FogOfWarSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/FogOfWarSystem.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;GAYG;AACH;IAwCI;;OAEG;IACH,sCAMC;IAhDD,mDAAmC;IA8BnC;;;;OAIG;IACH,yBAEC;IAaD,2CAIC;IAED,4CAeC;IAED;;OAEG;IACH,kCAwBC;IAED;;;;OAIG;IACH,UAJW,QAAQ,WACR,OAAO,UACP,MAAM,QA8BhB;IAED;;;;OAIG;IACH,YAJW,QAAQ,WACR,OAAO,UACP,MAAM,QAkBhB;IAED,6BASC;;CA4BJ;AAED;;;;;;;;;GASG;AACH;IAYI;;OAEG;IACH,oBAFW,cAAc,EAMxB;IAdD,sHAAsF;IAgBtF,yBAEC;;CACJ;uBAzPsB,kBAAkB;oBADrB,+BAA+B;yBAH1B,wBAAwB;gCAHjB,mDAAmD;mCALhD,sBAAsB;kCACvB,4BAA4B;qCACzB,wBAAwB;+BAC9B,oBAAoB"}