@woosh/meep-engine 3.38.0 → 3.39.0

package/src/engine/ecs/transform/Transform64.d.ts

@@ -313,8 +313,10 @@ export class Transform64 extends Float64Array {
      * Nothing calls this for you, and until you do, the rotation and scale part of the matrix is whatever
      * it was before. The translation column needs no help - it is the translation, see {@link matrix}.
      *
-     * The translation is passed in as three scalars, read before the first store, so writing it back
-     * over its own column is safe.
+     * The compose reads the operands from the transform's own lanes, every one before its first store, so
+     * writing the translation back over its own column is safe. They go by offset rather than as ten
+     * numbers: wherever V8 inlines this method but not the compose, ten numbers would each be boxed into a
+     * new heap object on the way in, once per call.
      */
     updateMatrix(): void;
     /**

package/src/engine/ecs/transform/Transform64.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Transform64.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/transform/Transform64.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"Transform64.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/transform/Transform64.js"],"names":[],"mappings":"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"}

package/src/engine/ecs/transform/Transform64.js

@@ -2,7 +2,7 @@ import { assert } from "../../../core/assert.js";
 import { array_copy } from "../../../core/collection/array/array_copy.js";
 import { array_range_equal_strict } from "../../../core/collection/array/array_range_equal_strict.js";
 import { m4_decompose_array } from "../../../core/geom/3d/mat4/m4_decompose_array.js";
-import { m4_from_rotation_translation_scale_scalar } from "../../../core/geom/3d/mat4/m4_from_rotation_translation_scale_scalar.js";
+import { m4_from_rotation_translation_scale_array } from "../../../core/geom/3d/mat4/m4_from_rotation_translation_scale_array.js";
 import { m4_multiply } from "../../../core/geom/3d/mat4/m4_multiply.js";
 import { quat3_multiply } from "../../../core/geom/3d/quaternion/quat3_multiply.js";
 import { v3_quaternion_apply } from "../../../core/geom/vec3/v3_quaternion_apply.js";
@@ -518,24 +518,18 @@ export class Transform64 extends Float64Array {
      * Nothing calls this for you, and until you do, the rotation and scale part of the matrix is whatever
      * it was before. The translation column needs no help - it is the translation, see {@link matrix}.
      *
-     * The translation is passed in as three scalars, read before the first store, so writing it back
-     * over its own column is safe.
+     * The compose reads the operands from the transform's own lanes, every one before its first store, so
+     * writing the translation back over its own column is safe. They go by offset rather than as ten
+     * numbers: wherever V8 inlines this method but not the compose, ten numbers would each be boxed into a
+     * new heap object on the way in, once per call.
      */
     updateMatrix() {
-        m4_from_rotation_translation_scale_scalar(
+        // the matrix starts at element 0 (TRANSFORM64_MATRIX_OFFSET), where a mat4 function writes it
+        m4_from_rotation_translation_scale_array(
             this,
-            this[TRANSFORM64_ROTATION_OFFSET],
-            this[TRANSFORM64_ROTATION_OFFSET + 1],
-            this[TRANSFORM64_ROTATION_OFFSET + 2],
-            this[TRANSFORM64_ROTATION_OFFSET + 3],
-
-            this[TRANSFORM64_TRANSLATION_OFFSET],
-            this[TRANSFORM64_TRANSLATION_OFFSET + 1],
-            this[TRANSFORM64_TRANSLATION_OFFSET + 2],
-
-            this[TRANSFORM64_SCALE_OFFSET],
-            this[TRANSFORM64_SCALE_OFFSET + 1],
-            this[TRANSFORM64_SCALE_OFFSET + 2]
+            this, TRANSFORM64_ROTATION_OFFSET,
+            this, TRANSFORM64_TRANSLATION_OFFSET,
+            this, TRANSFORM64_SCALE_OFFSET
         );
     }
 

package/src/engine/graphics/ecs/water/Water.d.ts

@@ -2,95 +2,57 @@ export default Water;
 /**
  * A body of water flooding the level, as authored data and nothing else.
  *
+ * Everything optical here is physical and in SI units (WATER_OPTICS_PLAN_2026_10_02.md §7.1): the
+ * index of refraction, the micro-roughness of the surface, and what fills the body — a
+ * {@link ParticipatingMedium}, the same description the path tracer, fog and glass read. Presets
+ * and the constituent and appearance tools in `shade/renderer/medium/water/` build that medium;
+ * the component stores only the result.
+ *
+ * How the surface moves is not here: the surface producer and its own component (`WaterWaves`)
+ * own that.
+ *
  * The component holds no renderer state: `WaterSystem` reads these values every frame onto the
- * surface its pass draws, which is why an edit needs no notification to be picked up.
+ * surface its passes draw, which is why an edit needs no notification to be picked up.
  */
 declare class Water {
     constructor(options: any);
-    level: Vector1;
-    /**
-     *
-     * @type {Color}
-     */
-    color: Color;
-    /**
-     * Defines what is considered as shore as well as how long is the transition between shore and deep water
-     * @type {NumericInterval}
-     */
-    shoreDepthTransition: NumericInterval;
     /**
-     * Color of the water at the shore
-     * @type {Color}
-     */
-    shoreColor: Color;
-    /**
-     *
+     * Rest height of the surface, m.
      * @type {Vector1}
      */
-    waveSpeed: Vector1;
+    level: Vector1;
     /**
-     *
+     * Index of refraction of the water relative to the air above it.
      * @type {Vector1}
      */
-    waveAmplitude: Vector1;
+    ior: Vector1;
     /**
-     *
+     * Perceptual roughness of the surface for the waves too small for the surface's mesh, before
+     * the slope variance the surface producer reports is added.
      * @type {Vector1}
      */
-    waveFrequency: Vector1;
+    roughness: Vector1;
     /**
-     * Scattering of light, the higher this value is - the more opaque water will become
-     * @type {Vector1}
+     * What fills the body: absorption and scattering lobes, RGB in 1/m. Clear open ocean
+     * (chlorophyll 0.3 mg/m³, the `open_ocean` preset) unless told otherwise. After editing its fields in place, set
+     * `medium.needsUpdate = true`.
+     * @type {ParticipatingMedium}
      */
-    scattering: Vector1;
-    /** Air-to-water optical properties; scattering scales the authored RGB extinction. */
-    ior: Vector1;
-    opticalNormalStrength: Vector1;
-    opticalNormalScale: Vector1;
-    extinction: Vector3;
-    reflectionRoughness: Vector1;
+    medium: ParticipatingMedium;
     bvh: BvhClient;
     updateBounds(): void;
     fromJSON(json: any): void;
     toJSON(): {
         level: number;
-        color: {
-            r: number;
-            g: number;
-            b: number;
-            a: number;
-        };
-        shoreColor: {
-            r: number;
-            g: number;
-            b: number;
-            a: number;
-        };
-        shoreDepthTransition: {
-            min: number;
-            max: number;
-        };
-        waveSpeed: number;
-        waveAmplitude: number;
-        waveFrequency: number;
-        scattering: number;
         ior: number;
-        opticalNormalStrength: number;
-        opticalNormalScale: number;
-        extinction: {
-            x: number;
-            y: number;
-            z: number;
-        };
-        reflectionRoughness: number;
+        roughness: number;
+        medium: any;
     };
 }
 declare namespace Water {
     let typeName: string;
 }
 import Vector1 from "../../../../core/geom/Vector1.js";
-import { Color } from "../../../../core/color/Color.js";
-import { NumericInterval } from "../../../../core/math/interval/NumericInterval.js";
-import Vector3 from "../../../../core/geom/Vector3.js";
+import { ParticipatingMedium } from "../../../../shade/renderer/medium/ParticipatingMedium.js";
 import { BvhClient } from "../../../../core/bvh2/bvh3/BvhClient.js";
 //# sourceMappingURL=Water.d.ts.map

package/src/engine/graphics/ecs/water/Water.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Water.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/water/Water.js"],"names":[],"mappings":";AAOA;;;;;GAKG;AACH;IAuDI,0BAMC;IA5DD,eAAuB;IACvB;;;OAGG;IACH,OAFU,KAAK,CAEgB;IAG/B;;;OAGG;IACH,sBAFU,eAAe,CAE0B;IAGnD;;;OAGG;IACH,YAFU,KAAK,CAE6B;IAE5C;;;OAGG;IACH,WAFU,OAAO,CAEY;IAE7B;;;OAGG;IACH,eAFU,OAAO,CAEgB;IAEjC;;;OAGG;IACH,eAFU,OAAO,CAEc;IAE/B;;;OAGG;IACH,YAFU,OAAO,CAEa;IAE9B,sFAAsF;IACtF,aAAwB;IACxB,+BAA0C;IAC1C,4BAAoC;IACpC,oBAA4C;IAC5C,6BAAwC;IAExC,eAAsB;IAUtB,qBAcC;IAED,0BAcC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAWC;CACJ;;;;oBAtHmB,kCAAkC;sBADhC,iCAAiC;gCAGvB,mDAAmD;oBAD/D,kCAAkC;0BAH5B,yCAAyC"}
+{"version":3,"file":"Water.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/water/Water.js"],"names":[],"mappings":";AAUA;;;;;;;;;;;;;;GAcG;AACH;IA8BI,0BAMC;IAnCD;;;OAGG;IACH,OAFU,OAAO,CAEM;IAEvB;;;OAGG;IACH,KAFU,OAAO,CAEQ;IAEzB;;;;OAIG;IACH,WAFU,OAAO,CAEa;IAE9B;;;;;OAKG;IACH,QAFU,mBAAmB,CAEG;IAEhC,eAAsB;IAUtB,qBAcC;IAED,0BAgBC;IAED;;;;;MAOC;CACJ;;;;oBAxGmB,kCAAkC;oCAClB,0DAA0D;0BAFpE,yCAAyC"}

package/src/engine/graphics/ecs/water/Water.js

@@ -1,125 +1,110 @@
-import { BvhClient } from "../../../../core/bvh2/bvh3/BvhClient.js";
-import { Color } from "../../../../core/color/Color.js";
-import Vector1 from "../../../../core/geom/Vector1.js";
-import Vector3 from "../../../../core/geom/Vector3.js";
-import { NumericInterval } from "../../../../core/math/interval/NumericInterval.js";
-import { WATER_SIZE } from "./WATER_SIZE.js";
-
-/**
- * A body of water flooding the level, as authored data and nothing else.
- *
- * The component holds no renderer state: `WaterSystem` reads these values every frame onto the
- * surface its pass draws, which is why an edit needs no notification to be picked up.
- */
-class Water {
-    level = new Vector1(0);
-    /**
-     *
-     * @type {Color}
-     */
-    color = new Color(0, 0.3, 0.5);
-
-
-    /**
-     * Defines what is considered as shore as well as how long is the transition between shore and deep water
-     * @type {NumericInterval}
-     */
-    shoreDepthTransition = new NumericInterval(0.7, 2);
-
-
-    /**
-     * Color of the water at the shore
-     * @type {Color}
-     */
-    shoreColor = new Color(0.584, 0.792, 0.850);
-
-    /**
-     *
-     * @type {Vector1}
-     */
-    waveSpeed = new Vector1(1.8);
-
-    /**
-     *
-     * @type {Vector1}
-     */
-    waveAmplitude = new Vector1(0.3);
-
-    /**
-     *
-     * @type {Vector1}
-     */
-    waveFrequency = new Vector1(1);
-
-    /**
-     * Scattering of light, the higher this value is - the more opaque water will become
-     * @type {Vector1}
-     */
-    scattering = new Vector1(1.2);
-
-    /** Air-to-water optical properties; scattering scales the authored RGB extinction. */
-    ior = new Vector1(1.33);
-    opticalNormalStrength = new Vector1(0.08);
-    opticalNormalScale = new Vector1(3);
-    extinction = new Vector3(0.12, 0.035, 0.02);
-    reflectionRoughness = new Vector1(0.08);
-
-    bvh = new BvhClient();
-
-    constructor(options) {
-
-        if (options !== undefined) {
-            console.error('Constructor options are deprecated');
-            this.fromJSON(options);
-        }
-    }
-
-    updateBounds() {
-        const width = WATER_SIZE;
-        const height = WATER_SIZE;
-
-        const level = this.level.getValue();
-
-        this.bvh.resize(
-            -width / 4,
-            level,
-            -height / 4,
-            width * (3 / 4),
-            level,
-            height * (3 / 4)
-        );
-    }
-
-    fromJSON(json) {
-        if (typeof json.level === 'number') {
-            this.level.fromJSON(json.level);
-        }
-        if (typeof json.color === 'object') {
-            this.color.fromJSON(json.color);
-        }
-        for (const key of ['waveSpeed', 'waveAmplitude', 'waveFrequency', 'scattering', 'ior',
-            'opticalNormalStrength', 'opticalNormalScale', 'reflectionRoughness']) {
-            if (typeof json[key] === 'number') { this[key].fromJSON(json[key]); }
-        }
-        for (const key of ['shoreColor', 'shoreDepthTransition', 'extinction']) {
-            if (json[key] !== null && typeof json[key] === 'object') { this[key].fromJSON(json[key]); }
-        }
-    }
-
-    toJSON() {
-        return {
-            level: this.level.toJSON(),
-            color: this.color.toJSON(),
-            shoreColor: this.shoreColor.toJSON(), shoreDepthTransition: this.shoreDepthTransition.toJSON(),
-            waveSpeed: this.waveSpeed.toJSON(), waveAmplitude: this.waveAmplitude.toJSON(),
-            waveFrequency: this.waveFrequency.toJSON(), scattering: this.scattering.toJSON(),
-            ior: this.ior.toJSON(), opticalNormalStrength: this.opticalNormalStrength.toJSON(),
-            opticalNormalScale: this.opticalNormalScale.toJSON(), extinction: this.extinction.toJSON(),
-            reflectionRoughness: this.reflectionRoughness.toJSON(),
-        };
-    }
-}
-
-Water.typeName = "Water";
-
-export default Water;
+import { BvhClient } from "../../../../core/bvh2/bvh3/BvhClient.js";
+import Vector1 from "../../../../core/geom/Vector1.js";
+import { ParticipatingMedium } from "../../../../shade/renderer/medium/ParticipatingMedium.js";
+import {
+    participating_medium_from_json,
+    participating_medium_to_json
+} from "../../../../shade/renderer/medium/participating_medium_serialization.js";
+import { water_medium_default } from "../../../../shade/renderer/medium/water/water_presets.js";
+import { WATER_SIZE } from "./WATER_SIZE.js";
+
+/**
+ * A body of water flooding the level, as authored data and nothing else.
+ *
+ * Everything optical here is physical and in SI units (WATER_OPTICS_PLAN_2026_10_02.md §7.1): the
+ * index of refraction, the micro-roughness of the surface, and what fills the body — a
+ * {@link ParticipatingMedium}, the same description the path tracer, fog and glass read. Presets
+ * and the constituent and appearance tools in `shade/renderer/medium/water/` build that medium;
+ * the component stores only the result.
+ *
+ * How the surface moves is not here: the surface producer and its own component (`WaterWaves`)
+ * own that.
+ *
+ * The component holds no renderer state: `WaterSystem` reads these values every frame onto the
+ * surface its passes draw, which is why an edit needs no notification to be picked up.
+ */
+class Water {
+    /**
+     * Rest height of the surface, m.
+     * @type {Vector1}
+     */
+    level = new Vector1(0);
+
+    /**
+     * Index of refraction of the water relative to the air above it.
+     * @type {Vector1}
+     */
+    ior = new Vector1(1.333);
+
+    /**
+     * Perceptual roughness of the surface for the waves too small for the surface's mesh, before
+     * the slope variance the surface producer reports is added.
+     * @type {Vector1}
+     */
+    roughness = new Vector1(0.02);
+
+    /**
+     * What fills the body: absorption and scattering lobes, RGB in 1/m. Clear open ocean
+     * (chlorophyll 0.3 mg/m³, the `open_ocean` preset) unless told otherwise. After editing its fields in place, set
+     * `medium.needsUpdate = true`.
+     * @type {ParticipatingMedium}
+     */
+    medium = water_medium_default();
+
+    bvh = new BvhClient();
+
+    constructor(options) {
+
+        if (options !== undefined) {
+            console.error('Constructor options are deprecated');
+            this.fromJSON(options);
+        }
+    }
+
+    updateBounds() {
+        const width = WATER_SIZE;
+        const height = WATER_SIZE;
+
+        const level = this.level.getValue();
+
+        this.bvh.resize(
+            -width / 4,
+            level,
+            -height / 4,
+            width * (3 / 4),
+            level,
+            height * (3 / 4)
+        );
+    }
+
+    fromJSON(json) {
+        if (typeof json.level === 'number') {
+            this.level.fromJSON(json.level);
+        }
+
+        if (typeof json.ior === 'number') {
+            this.ior.fromJSON(json.ior);
+        }
+
+        if (typeof json.roughness === 'number') {
+            this.roughness.fromJSON(json.roughness);
+        }
+
+        if (json.medium !== null && typeof json.medium === 'object') {
+            participating_medium_from_json(this.medium, json.medium);
+        }
+    }
+
+    toJSON() {
+        return {
+            level: this.level.toJSON(),
+            ior: this.ior.toJSON(),
+            roughness: this.roughness.toJSON(),
+            medium: participating_medium_to_json(this.medium),
+        };
+    }
+}
+
+Water.typeName = "Water";
+
+export default Water;

package/src/engine/graphics/ecs/water/WaterSerializationAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WaterSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/water/WaterSerializationAdapter.js"],"names":[],"mappings":"AAGA;;IAEI,oBAAc;IAGd;;;;OAIG;IACH,uCAFW,KAAK,QA0Bf;IAED;;;;OAIG;IACH,yCAFW,KAAK,QA8Bf;CACJ;gDAzE+C,gEAAgE;kBAC9F,YAAY"}
+{"version":3,"file":"WaterSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/water/WaterSerializationAdapter.js"],"names":[],"mappings":"AAOA;;IAEI,oBAAc;IAGd;;;;OAIG;IACH,uCAFW,KAAK,QAQf;IAED;;;;OAIG;IACH,yCAFW,KAAK,QAQf;CACJ;gDArC+C,gEAAgE;kBAK9F,YAAY"}

package/src/engine/graphics/ecs/water/WaterSerializationAdapter.js

@@ -1,74 +1,38 @@
-import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
-import Water from "./Water.js";
-
-export class WaterSerializationAdapter extends BinaryClassSerializationAdapter {
-
-    klass = Water;
-    version = 2;
-
-    /**
-     *
-     * @param {BinaryBuffer} buffer
-     * @param {Water} value
-     */
-    serialize(buffer, value) {
-        buffer.writeFloat64(value.level.getValue());
-
-        buffer.writeUint24(value.color.toUint());
-
-        buffer.writeFloat32(value.shoreDepthTransition.min);
-        buffer.writeFloat32(value.shoreDepthTransition.max);
-
-        buffer.writeUint24(value.shoreColor.toUint());
-
-        buffer.writeFloat32(value.waveSpeed.getValue());
-
-        buffer.writeFloat32(value.waveAmplitude.getValue());
-
-        buffer.writeFloat32(value.waveFrequency.getValue());
-
-        buffer.writeFloat32(value.scattering.getValue());
-        buffer.writeFloat32(value.ior.getValue());
-        buffer.writeFloat32(value.opticalNormalStrength.getValue());
-        buffer.writeFloat32(value.opticalNormalScale.getValue());
-        buffer.writeFloat32(value.reflectionRoughness.getValue());
-        buffer.writeFloat32(value.extinction.x);
-        buffer.writeFloat32(value.extinction.y);
-        buffer.writeFloat32(value.extinction.z);
-    }
-
-    /**
-     *
-     * @param {BinaryBuffer} buffer
-     * @param {Water} value
-     */
-    deserialize(buffer, value) {
-
-        const level = buffer.readFloat64();
-        const color = buffer.readUint24();
-
-        const shoreDepthTransition_min = buffer.readFloat32();
-        const shoreDepthTransition_max = buffer.readFloat32();
-
-        const shoreColor = buffer.readUint24();
-
-        const waveSpeed = buffer.readFloat32();
-        const waveAmplitude = buffer.readFloat32();
-        const waveFrequency = buffer.readFloat32();
-        const scattering = buffer.readFloat32();
-
-        value.level.set(level);
-        value.color.fromUint(color);
-        value.shoreDepthTransition.set(shoreDepthTransition_min, shoreDepthTransition_max);
-        value.shoreColor.fromUint(shoreColor);
-        value.waveSpeed.set(waveSpeed);
-        value.waveAmplitude.set(waveAmplitude);
-        value.waveFrequency.set(waveFrequency);
-        value.scattering.set(scattering);
-        value.ior.set(buffer.readFloat32());
-        value.opticalNormalStrength.set(buffer.readFloat32());
-        value.opticalNormalScale.set(buffer.readFloat32());
-        value.reflectionRoughness.set(buffer.readFloat32());
-        value.extinction.set(buffer.readFloat32(), buffer.readFloat32(), buffer.readFloat32());
-    }
-}
+import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import {
+    deserialize_participating_medium,
+    serialize_participating_medium
+} from "../../../../shade/renderer/medium/participating_medium_serialization.js";
+import Water from "./Water.js";
+
+export class WaterSerializationAdapter extends BinaryClassSerializationAdapter {
+
+    klass = Water;
+    version = 3;
+
+    /**
+     *
+     * @param {BinaryBuffer} buffer
+     * @param {Water} value
+     */
+    serialize(buffer, value) {
+        buffer.writeFloat64(value.level.getValue());
+        buffer.writeFloat32(value.ior.getValue());
+        buffer.writeFloat32(value.roughness.getValue());
+
+        serialize_participating_medium(buffer, value.medium);
+    }
+
+    /**
+     *
+     * @param {BinaryBuffer} buffer
+     * @param {Water} value
+     */
+    deserialize(buffer, value) {
+        value.level.set(buffer.readFloat64());
+        value.ior.set(buffer.readFloat32());
+        value.roughness.set(buffer.readFloat32());
+
+        deserialize_participating_medium(buffer, value.medium);
+    }
+}

package/src/engine/graphics/ecs/water/WaterSerializationUpgrader_1_2.d.ts

@@ -1,4 +1,4 @@
-/** Preserve the version-1 appearance record and append the new component defaults. */
+/** Preserve the version-1 appearance record and append the version-2 defaults. */
 export class WaterSerializationUpgrader_1_2 extends BinaryClassUpgrader {
     upgrade(source: any, target: any): void;
 }

package/src/engine/graphics/ecs/water/WaterSerializationUpgrader_1_2.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WaterSerializationUpgrader_1_2.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/water/WaterSerializationUpgrader_1_2.js"],"names":[],"mappings":"AAGA,sFAAsF;AACtF;IAII,wCAQC;CACJ;oCAjBmC,oDAAoD"}
+{"version":3,"file":"WaterSerializationUpgrader_1_2.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/water/WaterSerializationUpgrader_1_2.js"],"names":[],"mappings":"AAeA,kFAAkF;AAClF;IAII,wCAKC;CACJ;oCA1BmC,oDAAoD"}

package/src/engine/graphics/ecs/water/WaterSerializationUpgrader_1_2.js

@@ -1,18 +1,27 @@
-import { BinaryClassUpgrader } from "../../../ecs/storage/binary/BinaryClassUpgrader.js";
-import Water from "./Water.js";
-
-/** Preserve the version-1 appearance record and append the new component defaults. */
-export class WaterSerializationUpgrader_1_2 extends BinaryClassUpgrader {
-    __startVersion = 1;
-    __targetVersion = 2;
-
-    upgrade(source, target) {
-        const old = new Uint8Array(38);
-        source.readBytes(old, 0, old.length);
-        target.writeBytes(old, 0, old.length);
-        const defaults = new Water();
-        for (const value of [defaults.ior.getValue(), defaults.opticalNormalStrength.getValue(),
-            defaults.opticalNormalScale.getValue(), defaults.reflectionRoughness.getValue(),
-            defaults.extinction.x, defaults.extinction.y, defaults.extinction.z]) { target.writeFloat32(value); }
-    }
-}
+import { BinaryClassUpgrader } from "../../../ecs/storage/binary/BinaryClassUpgrader.js";
+
+/**
+ * The fields version 2 appended, with the defaults they had at that version. Constants, not read off
+ * the current `Water`: an upgrader writes the format of its target version, and the component has
+ * moved on since (version 3 removed most of these fields).
+ */
+const VERSION_2_DEFAULTS = [
+    1.33, // ior
+    0.08, // optical normal strength
+    3, // optical normal scale
+    0.08, // reflection roughness
+    0.12, 0.035, 0.02, // extinction
+];
+
+/** Preserve the version-1 appearance record and append the version-2 defaults. */
+export class WaterSerializationUpgrader_1_2 extends BinaryClassUpgrader {
+    __startVersion = 1;
+    __targetVersion = 2;
+
+    upgrade(source, target) {
+        const old = new Uint8Array(38);
+        source.readBytes(old, 0, old.length);
+        target.writeBytes(old, 0, old.length);
+        for (const value of VERSION_2_DEFAULTS) { target.writeFloat32(value); }
+    }
+}

package/src/engine/graphics/ecs/water/WaterSerializationUpgrader_2_3.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Version 2 described water by an authored body colour, shore colours, an RGB "extinction" times a
+ * scattering scale, and shore-wave and optical-normal controls. None of it was calibrated, so none
+ * of it maps onto a physical medium: mapping it would preserve a look nobody chose. Level, index
+ * of refraction and the reflection roughness carry over; the medium becomes the default physical
+ * preset (WATER_OPTICS_PLAN_2026_10_02.md §7.5, F1).
+ */
+export class WaterSerializationUpgrader_2_3 extends BinaryClassUpgrader {
+    upgrade(source: any, target: any): void;
+}
+import { BinaryClassUpgrader } from "../../../ecs/storage/binary/BinaryClassUpgrader.js";
+//# sourceMappingURL=WaterSerializationUpgrader_2_3.d.ts.map

package/src/engine/graphics/ecs/water/WaterSerializationUpgrader_2_3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WaterSerializationUpgrader_2_3.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/water/WaterSerializationUpgrader_2_3.js"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH;IAII,wCA4BC;CACJ;oCA5CmC,oDAAoD"}