@woosh/meep-engine 2.166.0 → 2.167.0

package/package.json

@@ -6,7 +6,7 @@
   "description": "Pure JavaScript game engine. Fully featured and production ready.",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "2.166.0",
+  "version": "2.167.0",
   "main": "build/meep.module.js",
   "module": "build/meep.module.js",
   "exports": {

package/src/engine/ecs/fow/FogOfWar.d.ts

@@ -28,6 +28,18 @@ export class FogOfWar {
      */
     size: Vector2;
     color: Vector4;
+    /**
+     * What the fog does outside the fogged area — see {@link FogOfWarEdgeMode}.
+     *
+     * NOT serialized: it is configuration the owner sets when it builds the
+     * component, not accumulated reveal state, and adding it to the binary format
+     * would cost a version bump plus an updater for every existing save. A
+     * deserialized FogOfWar therefore comes back as Conceal; a consumer that
+     * wants Extend sets it after loading, in the same place it sets {@link color}.
+     *
+     * @type {FogOfWarEdgeMode}
+     */
+    edge_mode: FogOfWarEdgeMode;
     /**
      * Contains indices of pixes that are currently being updated
      * @type {RowFirstTable}
@@ -134,6 +146,7 @@ import { DataTexture } from "three";
 import Vector1 from "../../../core/geom/Vector1.js";
 import Vector2 from "../../../core/geom/Vector2.js";
 import Vector4 from "../../../core/geom/Vector4.js";
+import { FogOfWarEdgeMode } from "./FogOfWarEdgeMode.js";
 import { RowFirstTable } from "../../../core/collection/table/RowFirstTable.js";
 import Signal from "../../../core/events/signal/Signal.js";
 import { Sampler2D } from "../../graphics/texture/sampler/Sampler2D.js";

package/src/engine/ecs/fow/FogOfWar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FogOfWar.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/fow/FogOfWar.js"],"names":[],"mappings":"AA+CA;;GAEG;AACH;IAEI;;;OAGG;IACH,oBAFU,OAAO,CAES;IAC1B;;;OAGG;IACH,0BAFU,OAAO,CAEgB;IAEjC;;;OAGG;IACH,SAFU,WAAW,GAAC,IAAI,CAEX;IAEf;;;OAGG;IACH,OAFU,OAAO,CAEM;IAEvB;;;OAGG;IACH,MAFU,OAAO,CAEQ;IAEzB,eAAsC;IAEtC;;;OAGG;IACH,UAFU,aAAa,CAE2B;IAWlD;;MAEE;IAEF;;;OAGG;IACH,SAFU,SAAS,CAEgB;IAEnC;;;OAGG;IACH,iBAFU,SAAS,CAEwB;IAE3C;;;OAGG;IACH,sBAFW,MAAM,QA6EhB;IA4DD;;;;OAIG;IACH,eAHW,MAAM,KACN,MAAM,QAUhB;IAED,cAQC;IAED,kBAQC;IAED,mBAEC;IAED;;;;;OAKG;IACH,UAJW,MAAM,KACN,MAAM,UACN,MAAM,QAmChB;IAED;;;;;OAKG;IACH,WAJW,MAAM,KACN,MAAM,UACN,MAAM,QAmChB;IAED;;;;;;OAMG;IACH,yBAcC;IAED,gBAIC;IAED,sBAqCC;IAED;;;OAGG;IACH,kBAFW,MAAM,QAYhB;IAED;;;OAGG;IACH,0DA+BC;IAED;;;;;OAKG;IACH,yBAJW,MAAM,KACN,MAAM,UACN,MAAM,EAAE,QAelB;IAED;;;;;OAKG;IACH,yEAFW,MAAM,WA+EhB;IAED;;;;;OAKG;IACH,qBAJW,MAAM,KACN,MAAM,GACJ,MAAM,CASlB;IAED,6BAKC;IAED,+BASC;IAED,uBAyBC;IAGD;;;;;OAKG;IACH,UAJW,MAAM,KACN,MAAM,oBAahB;;CACJ;;;;4BAvqB2F,OAAO;oBAM/E,+BAA+B;oBAC/B,+BAA+B;oBAC/B,+BAA+B;8BALrB,iDAAiD;mBAE5D,uCAAuC;0BAQhC,6CAA6C"}
+{"version":3,"file":"FogOfWar.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/fow/FogOfWar.js"],"names":[],"mappings":"AAgDA;;GAEG;AACH;IAEI;;;OAGG;IACH,oBAFU,OAAO,CAES;IAC1B;;;OAGG;IACH,0BAFU,OAAO,CAEgB;IAEjC;;;OAGG;IACH,SAFU,WAAW,GAAC,IAAI,CAEX;IAEf;;;OAGG;IACH,OAFU,OAAO,CAEM;IAEvB;;;OAGG;IACH,MAFU,OAAO,CAEQ;IAEzB,eAAsC;IAEtC;;;;;;;;;;OAUG;IACH,WAFU,gBAAgB,CAEW;IAErC;;;OAGG;IACH,UAFU,aAAa,CAE2B;IAWlD;;MAEE;IAEF;;;OAGG;IACH,SAFU,SAAS,CAEgB;IAEnC;;;OAGG;IACH,iBAFU,SAAS,CAEwB;IAE3C;;;OAGG;IACH,sBAFW,MAAM,QA6EhB;IA4DD;;;;OAIG;IACH,eAHW,MAAM,KACN,MAAM,QAUhB;IAED,cAQC;IAED,kBAQC;IAED,mBAEC;IAED;;;;;OAKG;IACH,UAJW,MAAM,KACN,MAAM,UACN,MAAM,QAmChB;IAED;;;;;OAKG;IACH,WAJW,MAAM,KACN,MAAM,UACN,MAAM,QAmChB;IAED;;;;;;OAMG;IACH,yBAcC;IAED,gBAIC;IAmDD,sBA2CC;IAED;;;OAGG;IACH,kBAFW,MAAM,QAYhB;IAED;;;OAGG;IACH,0DA+BC;IAED;;;;;OAKG;IACH,yBAJW,MAAM,KACN,MAAM,UACN,MAAM,EAAE,QAelB;IAED;;;;;OAKG;IACH,yEAFW,MAAM,WA+EhB;IAED;;;;;OAKG;IACH,qBAJW,MAAM,KACN,MAAM,GACJ,MAAM,CASlB;IAED,6BAKC;IAED,+BASC;IAED,uBAyBC;IAGD;;;;;OAKG;IACH,UAJW,MAAM,KACN,MAAM,oBAahB;;CACJ;;;;4BA5uB2F,OAAO;oBAM/E,+BAA+B;oBAC/B,+BAA+B;oBAC/B,+BAA+B;iCAOlB,uBAAuB;8BAZ1B,iDAAiD;mBAE5D,uCAAuC;0BAQhC,6CAA6C"}

package/src/engine/ecs/fow/FogOfWar.js

@@ -13,6 +13,7 @@ import { min2 } from "../../../core/math/min2.js";
 import { computeUnsignedDistanceField } from "../../graphics/texture/sampler/distance/computeUnsignedDistanceField.js";
 import { Sampler2D } from "../../graphics/texture/sampler/Sampler2D.js";
 import { writeSample2DDataToDataTexture } from "../../graphics/texture/sampler/writeSampler2DDataToDataTexture.js";
+import { FogOfWarEdgeMode } from "./FogOfWarEdgeMode.js";
 
 const samplePosition = [];
 
@@ -81,6 +82,19 @@ export class FogOfWar {
 
     color = new Vector4(0.1, 0.1, 0.1, 1);
 
+    /**
+     * What the fog does outside the fogged area — see {@link FogOfWarEdgeMode}.
+     *
+     * NOT serialized: it is configuration the owner sets when it builds the
+     * component, not accumulated reveal state, and adding it to the binary format
+     * would cost a version bump plus an updater for every existing save. A
+     * deserialized FogOfWar therefore comes back as Conceal; a consumer that
+     * wants Extend sets it after loading, in the same place it sets {@link color}.
+     *
+     * @type {FogOfWarEdgeMode}
+     */
+    edge_mode = FogOfWarEdgeMode.Conceal;
+
     /**
      * Contains indices of pixes that are currently being updated
      * @type {RowFirstTable}
@@ -401,7 +415,62 @@ export class FogOfWar {
         }
     }
 
+    /**
+     * Copy the sampler's outermost REAL cells out into the 1-cell ring that
+     * {@link rebuildSampler} pads it with.
+     *
+     * That ring is padding — it exists so the shader's 5x5 blur and the distance
+     * field have something to read past the edge — and it is filled with full
+     * concealment. The blur then drags that concealment ~2 cells back INTO the
+     * fogged area, so the outermost cells of the world can never read as fully
+     * revealed however thoroughly they are explored; and every lookup from outside
+     * the area clamps onto it, which is what paints the void. Mirroring makes the
+     * padding agree with the edge it pads, on both counts.
+     *
+     * O(perimeter), and only on frames that upload a new texture.
+     *
+     * @private
+     */
+    #mirrorBorderRing() {
+        const s = this.sampler;
+
+        const w = s.width;
+        const h = s.height;
+
+        if (w < 3 || h < 3) {
+            // no interior to mirror from
+            return;
+        }
+
+        const data = s.data;
+
+        const last_row = (h - 1) * w;
+        const second_last_row = (h - 2) * w;
+
+        // top and bottom edges, corners excluded — those come from the sides below
+        for (let x = 1; x < w - 1; x++) {
+            data[x] = data[w + x];
+            data[last_row + x] = data[second_last_row + x];
+        }
+
+        // left and right edges, corners INCLUDED: the row above and below have
+        // already been mirrored, so a corner ends up with its diagonal neighbour's
+        // value rather than an arbitrary one
+        for (let y = 0; y < h; y++) {
+            const row = y * w;
+
+            data[row] = data[row + 1];
+            data[row + w - 1] = data[row + w - 2];
+        }
+    }
+
     updateTexture() {
+        if (this.edge_mode === FogOfWarEdgeMode.Extend) {
+            // do this HERE, at the single point every reveal path funnels through
+            // on its way to the GPU, rather than in each of them
+            this.#mirrorBorderRing();
+        }
+
         const s = this.sampler;
 
         /**

package/src/engine/ecs/fow/FogOfWarEdgeMode.d.ts

@@ -0,0 +1,16 @@
+/**
+ * What the fog of war does AT, and beyond, the edge of the fogged area.
+ *
+ * The fog is a screen-space effect (see screenSpaceFogOfWarShader): per pixel it
+ * reconstructs a world position from the depth buffer and reads that position out
+ * of the fog sampler. Neither end of that pipeline is defined outside the fogged
+ * rectangle — a pixel with no geometry has no world position to reconstruct, and
+ * a world position outside the sampler has no cell to read — so what happens
+ * there is a POLICY rather than a fact, and this is the knob for it.
+ */
+export type FogOfWarEdgeMode = number;
+export namespace FogOfWarEdgeMode {
+    let Conceal: number;
+    let Extend: number;
+}
+//# sourceMappingURL=FogOfWarEdgeMode.d.ts.map

package/src/engine/ecs/fow/FogOfWarEdgeMode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FogOfWarEdgeMode.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/fow/FogOfWarEdgeMode.js"],"names":[],"mappings":";;;;;;;;;;+BAUU,MAAM"}

package/src/engine/ecs/fow/FogOfWarEdgeMode.js

@@ -0,0 +1,39 @@
+/**
+ * What the fog of war does AT, and beyond, the edge of the fogged area.
+ *
+ * The fog is a screen-space effect (see screenSpaceFogOfWarShader): per pixel it
+ * reconstructs a world position from the depth buffer and reads that position out
+ * of the fog sampler. Neither end of that pipeline is defined outside the fogged
+ * rectangle — a pixel with no geometry has no world position to reconstruct, and
+ * a world position outside the sampler has no cell to read — so what happens
+ * there is a POLICY rather than a fact, and this is the knob for it.
+ *
+ * @enum {number}
+ */
+export const FogOfWarEdgeMode = {
+    /**
+     * Everything outside the fogged area is CONCEALED: the sampler's border ring
+     * is left at full concealment, and a pixel with no geometry takes whatever
+     * the clamped lookup returns — which is that same border.
+     *
+     * The default, and the behaviour of every release before this option existed.
+     * Right for a world that fills the screen, where "outside" is somewhere the
+     * player is never shown.
+     */
+    Conceal: 0,
+
+    /**
+     * The fog EXTENDS outward instead: the border ring mirrors the cells just
+     * inside it, and pixels with no geometry are left alone entirely.
+     *
+     * For a world with a VISIBLE boundary — a finite arena the camera can see
+     * past. Under {@link FogOfWarEdgeMode.Conceal} such a scene gets a hard black
+     * rectangle drawn exactly on its boundary (the concealed border ring, clamped
+     * across the whole void), which both advertises where the map stops and paints
+     * over anything drawn earlier to hide it — this layer composites last, over
+     * every other effect. Under Extend the fog agrees with the ground it borders:
+     * explored terrain stays clear right out past the boundary, unexplored terrain
+     * stays dark, and nothing marks where the geometry ends.
+     */
+    Extend: 1,
+};

package/src/engine/ecs/fow/FogOfWarSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FogOfWarSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/fow/FogOfWarSystem.js"],"names":[],"mappings":"AAwBA;IACI;;;OAGG;IACH,sCA0BC;IAvBG;;;OAGG;IACH,yBAAwB;IAExB,mDAAuC;IAEvC,gEAEC;IAED,mCAAoD;IAIpD;;;OAGG;IACH,eAFU,aAAa,CAEE;IAEzB,uBAAuB;IAG3B;;;OAGG;IACH,yBAFa,gBAAgB,CAuE5B;IAsBG,kBAAgC;IA+DpC,4CAEC;IAED;;;;;OAKG;IACH,UAJW,QAAQ,WACR,OAAO,UACP,MAAM,QAmBhB;IAED,kDAQC;IAED,6BAUC;CACJ;uBAzPsB,cAAc;oBACjB,2BAA2B;yBACtB,eAAe;4CAdI,oDAAoD;iCAS/D,sDAAsD;8BAPzD,0CAA0C"}
+{"version":3,"file":"FogOfWarSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/fow/FogOfWarSystem.js"],"names":[],"mappings":"AAwBA;IACI;;;OAGG;IACH,sCA0BC;IAvBG;;;OAGG;IACH,yBAAwB;IAExB,mDAAuC;IAEvC,gEAEC;IAED,mCAAoD;IAIpD;;;OAGG;IACH,eAFU,aAAa,CAEE;IAEzB,uBAAuB;IAG3B;;;OAGG;IACH,yBAFa,gBAAgB,CAuE5B;IAsBG,kBAAgC;IAgEpC,4CAEC;IAED;;;;;OAKG;IACH,UAJW,QAAQ,WACR,OAAO,UACP,MAAM,QAmBhB;IAED,kDAQC;IAED,6BAUC;CACJ;uBA1PsB,cAAc;oBACjB,2BAA2B;yBACtB,eAAe;4CAdI,oDAAoD;iCAS/D,sDAAsD;8BAPzD,0CAA0C"}

package/src/engine/ecs/fow/FogOfWarSystem.js

@@ -178,6 +178,7 @@ export class FogOfWarSystem extends System {
                 fogOfWarRenderer.setResolution(fow.size.x, fow.size.y);
                 fogOfWarRenderer.setUvTransformFromFog(fow);
                 fogOfWarRenderer.setFogColor(fow.color);
+                fogOfWarRenderer.setEdgeMode(fow.edge_mode);
 
 
                 //stop traversal

package/src/engine/ecs/fow/shader/FogOfWarRenderer.d.ts

@@ -47,6 +47,12 @@ export class FogOfWarRenderer {
      * @param {Vector4} color
      */
     setFogColor(color: Vector4): void;
+    /**
+     * What the fog does outside the fogged area. See {@link FogOfWarEdgeMode}.
+     *
+     * @param {FogOfWarEdgeMode} mode
+     */
+    setEdgeMode(mode: FogOfWarEdgeMode): void;
     /**
      *
      * @param {WebGLRenderer} renderer
@@ -59,4 +65,5 @@ export class FogOfWarRenderer {
 import { Mesh } from "three";
 import { OrthographicCamera } from "three";
 import { Scene } from "three";
+import { FogOfWarEdgeMode } from "../FogOfWarEdgeMode.js";
 //# sourceMappingURL=FogOfWarRenderer.d.ts.map

package/src/engine/ecs/fow/shader/FogOfWarRenderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FogOfWarRenderer.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/ecs/fow/shader/FogOfWarRenderer.js"],"names":[],"mappings":"AAMA;;;;GAIG;AACH,+EAFoB,MAAM,QAAE,MAAM,QAAE,MAAM,QAAE,MAAM,gBAiBjD;AAED;IAEQ;;;OAGG;IACH,yBAAgD;IAEhD,2DAAkE;IAElE,2BAAwD;IACxD,aAAwB;IAI5B;;;OAGG;IACH,2CAKC;IAED;;;;;;OAMG;IACH,wBALW,MAAM,WACN,MAAM,UACN,MAAM,UACN,MAAM,QAqBhB;IAED;;;OAGG;IACH,uCAIC;IAED;;;OAGG;IACH,oCAGC;IAED;;;;OAIG;IACH,iBAHW,MAAM,KACN,MAAM,QAIhB;IAED;;;OAGG;IACH,kCAEC;IAED;;;;;;OAMG;IACH,wCAJW,oBAAkB,kBAAkB,SACpC,KAAK,mCAqBf;CACJ;qBAhJ+C,OAAO;mCAAP,OAAO;sBAAP,OAAO"}
+{"version":3,"file":"FogOfWarRenderer.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/ecs/fow/shader/FogOfWarRenderer.js"],"names":[],"mappings":"AAOA;;;;GAIG;AACH,+EAFoB,MAAM,QAAE,MAAM,QAAE,MAAM,QAAE,MAAM,gBAiBjD;AAED;IAEQ;;;OAGG;IACH,yBAAgD;IAEhD,2DAAkE;IAElE,2BAAwD;IACxD,aAAwB;IAI5B;;;OAGG;IACH,2CAKC;IAED;;;;;;OAMG;IACH,wBALW,MAAM,WACN,MAAM,UACN,MAAM,UACN,MAAM,QAqBhB;IAED;;;OAGG;IACH,uCAIC;IAED;;;OAGG;IACH,oCAGC;IAED;;;;OAIG;IACH,iBAHW,MAAM,KACN,MAAM,QAIhB;IAED;;;OAGG;IACH,kCAEC;IAED;;;;OAIG;IACH,kBAFW,gBAAgB,QAI1B;IAED;;;;;;OAMG;IACH,wCAJW,oBAAkB,kBAAkB,SACpC,KAAK,mCAqBf;CACJ;qBA1J+C,OAAO;mCAAP,OAAO;sBAAP,OAAO;iCAItB,wBAAwB"}

package/src/engine/ecs/fow/shader/FogOfWarRenderer.js

@@ -1,145 +1,155 @@
-import { Mesh, OrthographicCamera, Scene } from "three";
-import { assert } from "../../../../core/assert.js";
-import { isValueBetweenInclusive } from "../../../../core/math/interval/isValueBetweenInclusive.js";
-import { FULL_SCREEN_TRIANGLE_GEOMETRY } from "../../../graphics/geometry/FULL_SCREEN_TRIANGLE_GEOMETRY.js";
-import { buildScreenSpaceFogOfWarShader } from "./screenSpaceFogOfWarShader.js";
-
-/**
- *
- * @param {FogOfWar} fow
- * @param {function(number, number, number, number)} callback
- */
-export function computeUvTransformFromFogOfWar(fow, callback) {
-
-    const sampler = fow.sampler;
-
-    const samplerWidth = sampler.width;
-    const samplerHeight = sampler.height;
-
-
-    const scaleX = (fow.scale * fow.size.x) * (samplerWidth / (samplerWidth - 3));
-    const scaleY = (fow.scale * fow.size.y) * (samplerHeight / (samplerHeight - 3));
-
-    const offsetX = 1.5 / samplerWidth;
-    const offsetY = 1.5 / samplerHeight;
-
-    callback(offsetX, offsetY, 1 / scaleX, 1 / scaleY);
-}
-
-export class FogOfWarRenderer {
-    constructor() {
-        /**
-         *
-         * @type {ShaderMaterial}
-         */
-        this.material = buildScreenSpaceFogOfWarShader();
-
-        this.quad = new Mesh(FULL_SCREEN_TRIANGLE_GEOMETRY, this.material);
-
-        this.camera = new OrthographicCamera(-1, 1, 1, -1, 0, 1);
-        this.scene = new Scene();
-        this.scene.add(this.quad);
-    }
-
-    /**
-     *
-     * @param {FogOfWar} fow
-     */
-    setUvTransformFromFog(fow) {
-        computeUvTransformFromFogOfWar(fow, (offsetX, offsetY, scaleX, scaleY) => {
-
-            this.setUvTransform(offsetX, offsetY, scaleX, scaleY);
-        });
-    }
-
-    /**
-     *
-     * @param {number} offsetX UV u offset, between 0 and 1
-     * @param {number} offsetY UV v offset, between 0 and 1
-     * @param {number} scaleX Transform scale from world coordinate position to UV u coordinate, minus offsetX
-     * @param {number} scaleY Transform scale from world coordinate position to UV v coordinate, minus offsetY
-     */
-    setUvTransform(offsetX, offsetY, scaleX, scaleY) {
-        assert.isNumber(offsetX, 'offsetX');
-        assert.notNaN(offsetX, 'offsetX');
-        assert.ok(isValueBetweenInclusive(offsetX, 0, 1), `expected offsetX to be between 0 and 1, instead was '${offsetX}'`);
-
-        assert.isNumber(offsetY,  'offsetY');
-        assert.notNaN(offsetY, 'offsetY');
-        assert.ok(isValueBetweenInclusive(offsetY, 0, 1), `expected offsetY to be between 0 and 1, instead was '${offsetY}'`);
-
-
-        assert.isNumber(scaleX,  'scaleX');
-        assert.notNaN(scaleX, 'scaleX');
-        assert.isFinite(scaleX, 'scaleX');
-
-        assert.isNumber(scaleY, 'scaleY');
-        assert.notNaN(scaleY, 'scaleY');
-        assert.isFinite(scaleY, 'scaleY');
-
-        this.material.uniforms.uFogUvTransform.value.set(offsetX, offsetY, scaleX, scaleY);
-    }
-
-    /**
-     *
-     * @param {Texture} texture
-     */
-    setDepthBuffer(texture) {
-        // assert.equal(texture.type, UnsignedShortType, `expected texture type to be UnsignedShort(=${UnsignedShortType}), instead got something else (=${texture.type})`)
-
-        this.material.uniforms.tDepth.value = texture;
-    }
-
-    /**
-     *
-     * @param {Texture} buffer
-     */
-    setFogBuffer(buffer) {
-        this.material.uniforms.tFog.value = buffer;
-
-    }
-
-    /**
-     * Resolution of the fog texture
-     * @param {number} x
-     * @param {number} y
-     */
-    setResolution(x, y) {
-        this.material.uniforms.uResolution.value.set(x, y);
-    }
-
-    /**
-     *
-     * @param {Vector4} color
-     */
-    setFogColor(color) {
-        this.material.uniforms.uColor.value.copy(color);
-    }
-
-    /**
-     *
-     * @param {WebGLRenderer} renderer
-     * @param {PerspectiveCamera|OrthographicCamera} camera
-     * @param {Scene} scene
-     * @param {WebGLRenderTarget} target
-     */
-    render(renderer, camera, scene, target) {
-        assert.ok(camera.isCamera, 'Not a camera');
-        assert.ok(camera.isPerspectiveCamera || camera.isOrthographicCamera, 'Unsupported Camera type. Expected PerspectiveCamera or OrthographicCamera');
-
-
-        //set up uniforms
-        const uniforms = this.material.uniforms;
-
-        uniforms.uProjectionInverse.value.copy(camera.projectionMatrixInverse);
-        uniforms.uViewInverse.value.copy(camera.matrixWorld);
-
-        renderer.setRenderTarget(target);
-        renderer.clearColor();
-
-        renderer.render(this.scene, this.camera);
-
-
-        renderer.setRenderTarget(null);
-    }
-}
+import { Mesh, OrthographicCamera, Scene } from "three";
+import { assert } from "../../../../core/assert.js";
+import { isValueBetweenInclusive } from "../../../../core/math/interval/isValueBetweenInclusive.js";
+import { FULL_SCREEN_TRIANGLE_GEOMETRY } from "../../../graphics/geometry/FULL_SCREEN_TRIANGLE_GEOMETRY.js";
+import { FogOfWarEdgeMode } from "../FogOfWarEdgeMode.js";
+import { buildScreenSpaceFogOfWarShader } from "./screenSpaceFogOfWarShader.js";
+
+/**
+ *
+ * @param {FogOfWar} fow
+ * @param {function(number, number, number, number)} callback
+ */
+export function computeUvTransformFromFogOfWar(fow, callback) {
+
+    const sampler = fow.sampler;
+
+    const samplerWidth = sampler.width;
+    const samplerHeight = sampler.height;
+
+
+    const scaleX = (fow.scale * fow.size.x) * (samplerWidth / (samplerWidth - 3));
+    const scaleY = (fow.scale * fow.size.y) * (samplerHeight / (samplerHeight - 3));
+
+    const offsetX = 1.5 / samplerWidth;
+    const offsetY = 1.5 / samplerHeight;
+
+    callback(offsetX, offsetY, 1 / scaleX, 1 / scaleY);
+}
+
+export class FogOfWarRenderer {
+    constructor() {
+        /**
+         *
+         * @type {ShaderMaterial}
+         */
+        this.material = buildScreenSpaceFogOfWarShader();
+
+        this.quad = new Mesh(FULL_SCREEN_TRIANGLE_GEOMETRY, this.material);
+
+        this.camera = new OrthographicCamera(-1, 1, 1, -1, 0, 1);
+        this.scene = new Scene();
+        this.scene.add(this.quad);
+    }
+
+    /**
+     *
+     * @param {FogOfWar} fow
+     */
+    setUvTransformFromFog(fow) {
+        computeUvTransformFromFogOfWar(fow, (offsetX, offsetY, scaleX, scaleY) => {
+
+            this.setUvTransform(offsetX, offsetY, scaleX, scaleY);
+        });
+    }
+
+    /**
+     *
+     * @param {number} offsetX UV u offset, between 0 and 1
+     * @param {number} offsetY UV v offset, between 0 and 1
+     * @param {number} scaleX Transform scale from world coordinate position to UV u coordinate, minus offsetX
+     * @param {number} scaleY Transform scale from world coordinate position to UV v coordinate, minus offsetY
+     */
+    setUvTransform(offsetX, offsetY, scaleX, scaleY) {
+        assert.isNumber(offsetX, 'offsetX');
+        assert.notNaN(offsetX, 'offsetX');
+        assert.ok(isValueBetweenInclusive(offsetX, 0, 1), `expected offsetX to be between 0 and 1, instead was '${offsetX}'`);
+
+        assert.isNumber(offsetY,  'offsetY');
+        assert.notNaN(offsetY, 'offsetY');
+        assert.ok(isValueBetweenInclusive(offsetY, 0, 1), `expected offsetY to be between 0 and 1, instead was '${offsetY}'`);
+
+
+        assert.isNumber(scaleX,  'scaleX');
+        assert.notNaN(scaleX, 'scaleX');
+        assert.isFinite(scaleX, 'scaleX');
+
+        assert.isNumber(scaleY, 'scaleY');
+        assert.notNaN(scaleY, 'scaleY');
+        assert.isFinite(scaleY, 'scaleY');
+
+        this.material.uniforms.uFogUvTransform.value.set(offsetX, offsetY, scaleX, scaleY);
+    }
+
+    /**
+     *
+     * @param {Texture} texture
+     */
+    setDepthBuffer(texture) {
+        // assert.equal(texture.type, UnsignedShortType, `expected texture type to be UnsignedShort(=${UnsignedShortType}), instead got something else (=${texture.type})`)
+
+        this.material.uniforms.tDepth.value = texture;
+    }
+
+    /**
+     *
+     * @param {Texture} buffer
+     */
+    setFogBuffer(buffer) {
+        this.material.uniforms.tFog.value = buffer;
+
+    }
+
+    /**
+     * Resolution of the fog texture
+     * @param {number} x
+     * @param {number} y
+     */
+    setResolution(x, y) {
+        this.material.uniforms.uResolution.value.set(x, y);
+    }
+
+    /**
+     *
+     * @param {Vector4} color
+     */
+    setFogColor(color) {
+        this.material.uniforms.uColor.value.copy(color);
+    }
+
+    /**
+     * What the fog does outside the fogged area. See {@link FogOfWarEdgeMode}.
+     *
+     * @param {FogOfWarEdgeMode} mode
+     */
+    setEdgeMode(mode) {
+        this.material.uniforms.uEdgeExtend.value = (mode === FogOfWarEdgeMode.Extend) ? 1 : 0;
+    }
+
+    /**
+     *
+     * @param {WebGLRenderer} renderer
+     * @param {PerspectiveCamera|OrthographicCamera} camera
+     * @param {Scene} scene
+     * @param {WebGLRenderTarget} target
+     */
+    render(renderer, camera, scene, target) {
+        assert.ok(camera.isCamera, 'Not a camera');
+        assert.ok(camera.isPerspectiveCamera || camera.isOrthographicCamera, 'Unsupported Camera type. Expected PerspectiveCamera or OrthographicCamera');
+
+
+        //set up uniforms
+        const uniforms = this.material.uniforms;
+
+        uniforms.uProjectionInverse.value.copy(camera.projectionMatrixInverse);
+        uniforms.uViewInverse.value.copy(camera.matrixWorld);
+
+        renderer.setRenderTarget(target);
+        renderer.clearColor();
+
+        renderer.render(this.scene, this.camera);
+
+
+        renderer.setRenderTarget(null);
+    }
+}

package/src/engine/ecs/fow/shader/screenSpaceFogOfWarShader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"screenSpaceFogOfWarShader.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/ecs/fow/shader/screenSpaceFogOfWarShader.js"],"names":[],"mappings":"AAGA;;;GAGG;AACH,kDAFW,cAAc,CAmKxB;+BAxKyE,OAAO"}
+{"version":3,"file":"screenSpaceFogOfWarShader.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/ecs/fow/shader/screenSpaceFogOfWarShader.js"],"names":[],"mappings":"AAGA;;;GAGG;AACH,kDAFW,cAAc,CA4LxB;+BAjMyE,OAAO"}

package/src/engine/ecs/fow/shader/screenSpaceFogOfWarShader.js

@@ -22,9 +22,12 @@ export function buildScreenSpaceFogOfWarShader() {
         uniform vec2 uResolution;
                 
         uniform vec4 uColor;
-        
+
+        // FogOfWarEdgeMode as a float: 0 = Conceal (legacy), 1 = Extend
+        uniform float uEdgeExtend;
+
         varying vec2 vUv;
-        
+
         const float   c_samplesX    = 5.0;
         const float   c_samplesY    = 5.0;
 
@@ -43,11 +46,9 @@ export function buildScreenSpaceFogOfWarShader() {
         // per tap, so a 5-tap kernel reaches +/-2 texels either side of centre.
         const float texelSpacing = 1.0;
         
-	     vec3 computeWorldPosition(){
+	     vec3 computeWorldPosition(const in float normalizedDepth){
                 // Convert screen coordinates to normalized device coordinates (NDC)
-                
-                float normalizedDepth = texture2D( tDepth, vUv).x ; 
-                
+
                 vec4 ndc = vec4(
                     (vUv.x - 0.5) * 2.0,
                     (vUv.y - 0.5) * 2.0,
@@ -105,9 +106,28 @@ export function buildScreenSpaceFogOfWarShader() {
 	     }
 	     	        
         void main(){
+            float sceneDepth = texture2D( tDepth, vUv ).x;
+
+            // NOTHING WAS DRAWN HERE. The depth is the buffer's clear value, so
+            // the position reconstructed from it lands on the far plane: a point
+            // with no relationship to the scene, whose fog lookup is whatever the
+            // sampler's clamp happens to return. In a world with a visible
+            // boundary that is the concealed border ring, and it gets painted
+            // across the entire void as a hard rectangle on the world's edge.
+            // Under Extend, leave such a pixel alone rather than fog it on the
+            // strength of a reconstruction that means nothing.
+            //
+            // Under Conceal this branch never taken, so the legacy path is
+            // bit-identical — including the one case Extend gives up, a real
+            // surface sitting exactly on the far plane.
+            if (uEdgeExtend > 0.5 && sceneDepth >= 1.0) {
+                gl_FragColor = vec4(0.0);
+                return;
+            }
+
             //get world fragment position
-            vec3 worldPosition = computeWorldPosition();
-            
+            vec3 worldPosition = computeWorldPosition(sceneDepth);
+
             vec2 fogUv = worldPosition.xz * uFogUvTransform.zw + uFogUvTransform.xy;
             
             float fogValue = getFog( fogUv );
@@ -144,6 +164,11 @@ export function buildScreenSpaceFogOfWarShader() {
         uViewInverse: { type: 'm4', value: new Matrix4() },
         uProjectionInverse: { type: 'm4', value: new Matrix4() },
         uColor: { type: 'c', value: new Vector4(0, 0, 0, 1) },
+        /**
+         * {@link FogOfWarEdgeMode} as a float. Defaults to Conceal, so a consumer
+         * that never sets it keeps the pre-option behaviour.
+         */
+        uEdgeExtend: { type: 'f', value: 0 },
         uFogUvTransform: { type: 'v4', value: new Vector4(0, 0, 1, 1) },
         /**
          * Fog texture resolution