@woosh/meep-engine 2.44.7 → 2.44.8

package/core/cache/Cache.js

@@ -395,7 +395,7 @@ export class Cache {
     }
 
     /**
-     *
+     * Please note that the key will be stored inside the cache, so it must be treated as immutable
      * @param {Key} key
      * @param {function(Key):Value} compute
      * @param {*} [compute_context]

package/core/localization/LanguageMetadata.js

@@ -0,0 +1,28 @@
+import { assert } from "../assert.js";
+
+/**
+ *
+ */
+export class LanguageMetadata {
+    /**
+     * Measured in characters per second
+     * @type {number}
+     */
+    reading_speed = 10
+
+    fromJSON({ reading_speed = 10 }) {
+
+        assert.isNumber(reading_speed, 'reading_speed');
+        assert.greaterThan(reading_speed, 0, 'reading_speed');
+
+        this.reading_speed = reading_speed;
+    }
+
+    static fromJSON(j) {
+        const r = new LanguageMetadata();
+
+        r.fromJSON(j);
+
+        return r;
+    }
+}

package/core/localization/Localization.js

@@ -0,0 +1,244 @@
+import levenshtein from "fast-levenshtein";
+import { parseTooltipString } from "../../view/tooltip/gml/parser/parseTooltipString.js";
+import { assert } from "../assert.js";
+import ObservedString from "../model/ObservedString.js";
+import { seedVariablesIntoTemplateString } from "../parser/seedVariablesIntoTemplateString.js";
+import { STRING_TEMPLATE_VARIABLE_REGEX } from "../parser/STRING_TEMPLATE_VARIABLE_REGEX.js";
+import { Cache } from "../cache/Cache.js";
+import { computeStringHash } from "../primitives/strings/computeStringHash.js";
+import { computeHashArray } from "../collection/array/computeHashArray.js";
+import { LanguageMetadata } from "./LanguageMetadata.js";
+
+/**
+ * Validation utility method
+ * @param {string} template
+ * @return {string}
+ */
+function validationMockSeed(template) {
+
+    const result = template.replace(STRING_TEMPLATE_VARIABLE_REGEX, function (match, varName) {
+        return "0";
+    });
+
+    return result;
+}
+
+const EMPTY_SEED = Object.freeze({});
+
+const DEFAULT_LANGUAGE_METADATA = new LanguageMetadata();
+
+export class Localization {
+    constructor() {
+        /**
+         *
+         * @type {AssetManager|null}
+         */
+        this.assetManager = null;
+
+        this.json = {};
+
+        /**
+         * @protected
+         * @type {LanguageMetadata}
+         */
+        this.language_metadata = DEFAULT_LANGUAGE_METADATA;
+
+        /**
+         *
+         * @type {ObservedString}
+         */
+        this.locale = new ObservedString('');
+
+        /**
+         * In debug mode error messages are a lot more verbose and helpful
+         * @type {boolean}
+         */
+        this.debug = true;
+
+        /**
+         * @type {Cache<string[], string>}
+         * @private
+         */
+        this.__failure_cache = new Cache({
+            maxWeight: 1024,
+            keyHashFunction: (key) => computeHashArray(key, computeStringHash)
+        });
+    }
+
+    /**
+     * Measured in characters per second
+     * @deprecated use 'language_metadata' directly instead
+     * @return {number}
+     */
+    get reading_speed() {
+        return this.language_metadata.reading_speed;
+    }
+
+    /**
+     * Time required to read a piece of text, in seconds
+     * @param {string} text
+     * @returns {number} time in seconds
+     */
+    estimateReadingTime(text) {
+        assert.isString(text, 'text');
+
+        return text.length / this.reading_speed;
+    }
+
+    /**
+     *
+     * @param {AssetManager} am
+     */
+    setAssetManager(am) {
+        this.assetManager = am;
+    }
+
+    /**
+     * @returns {boolean}
+     * @param {function(key:string, error:*, original: string)} errorConsumer
+     */
+    validate(errorConsumer) {
+        let result = true;
+
+        for (let key in this.json) {
+            const value = this.json[key];
+
+            const seededValue = validationMockSeed(value);
+
+            try {
+                parseTooltipString(seededValue);
+            } catch (e) {
+                result = false;
+                errorConsumer(key, e, value);
+            }
+        }
+
+        return result;
+    }
+
+    /**
+     *
+     * @param {string} locale
+     * @param {string} path where to look for localization data
+     * @returns {Promise}
+     */
+    loadLocale(locale, path = 'data/database/text') {
+        assert.isString(locale, 'locale');
+        assert.isString(path, 'path');
+
+        const am = this.assetManager;
+
+        if (am === null) {
+            throw new Error('AssetManager is not set');
+        }
+
+        const pLoadData = am.promise(`${path}/${locale}.json`, "json")
+            .then(asset => {
+                const json = asset.create();
+
+                this.json = json;
+
+                this.locale.set(locale);
+            }, reason => {
+
+                console.error(`Failed to load locale data for locale '${locale}' : ${reason}`);
+
+                // reset data
+                this.json = {};
+
+            });
+
+        const pLoadMetadata = am.promise(`${path}/languages.json`, "json")
+            .then(asset => {
+                const languages_metadata = asset.create();
+
+                this.language_metadata = LanguageMetadata.fromJSON(languages_metadata[locale]);
+            }, reason => {
+                console.error(`Failed to load language metadata: ${reason}`);
+
+                this.language_metadata = DEFAULT_LANGUAGE_METADATA;
+            });
+
+        return Promise.all([pLoadData, pLoadMetadata]);
+    }
+
+    /**
+     *
+     * @param {String} id
+     * @return {boolean}
+     */
+    hasString(id) {
+        return this.json[id] !== undefined;
+    }
+
+    /**
+     *
+     * @param {number} value
+     */
+    formatIntegerByThousands(value) {
+        const formatter = new Intl.NumberFormat(this.locale.getValue(), { useGrouping: true });
+
+        return formatter.format(value);
+    }
+
+    /**
+     *
+     * @param {string} id
+     * @param {Object} seed
+     * @private
+     */
+    __debugMissingKey(id, seed) {
+        const locale = this.locale.getValue();
+
+        const seed_string = JSON.stringify(seed);
+
+        const message = this.__failure_cache.getOrCompute([locale, id, seed_string], () => {
+
+            //try to find similar keys
+            const similarities = Object.keys(this.json).map(function (key) {
+                const distance = levenshtein.get(key, id);
+                return {
+                    key,
+                    distance
+                };
+            });
+
+            similarities.sort(function (a, b) {
+                return a.distance - b.distance;
+            });
+
+            const suggestions = similarities.slice(0, 3).map(p => p.key);
+
+            return `No localization value for id='${id}', seed=${seed_string}, approximate matches: ${suggestions.join(', ')}`;
+        });
+
+        console.warn(message);
+    }
+
+    /**
+     *
+     * @param {string} id
+     * @param {object} [seed]
+     *
+     * @returns {string}
+     */
+    getString(id, seed = EMPTY_SEED) {
+        assert.isString(id, 'id');
+
+        const value = this.json[id];
+
+        if (value === undefined) {
+
+            if (this.debug) {
+                this.__debugMissingKey(id, seed)
+            }
+
+            //no value, provide substitute
+            return `@${id}`;
+
+        }
+
+        //value needs to be seeded
+        return seedVariablesIntoTemplateString(value, seed);
+    }
+}

package/core/model/node-graph/DataType.js

@@ -16,7 +16,7 @@ export class DataType {
     }
 
     toString() {
-        return `{DataType: id=${this.id}, name='${this.name}' }`;
+        return `DataType{ id=${this.id}, name='${this.name}' }`;
     }
 
     /**

package/core/model/node-graph/node/Port.js

@@ -57,6 +57,10 @@ export class Port {
             ;
 
     }
+
+    toString() {
+        return `Port{ id=${this.id}, direction=${this.direction}, name=${this.name}, type=${this.dataType} }`;
+    }
 }
 
 /**

package/editor/view/ecs/components/items/ItemContainerController.stories.js

@@ -1,5 +1,5 @@
 import { storiesOf } from "@storybook/html/dist/client/preview";
-import { Localization } from "../../../../../core/Localization.js";
+import { Localization } from "../../../../../core/localization/Localization.js";
 import { ItemContainerController } from "./ItemContainerController.js";
 import ItemContainer from "../../../../../../model/game/ecs/component/item_container/ItemContainer.js";
 import Item from "../../../../../../model/game/ecs/component/Item.js";

package/engine/Engine.js

@@ -23,7 +23,7 @@ import EmptyView from "../view/elements/EmptyView.js";
 import { assert } from "../core/assert.js";
 import { StaticKnowledgeDatabase } from "./knowledge/database/StaticKnowledgeDatabase.js";
 import Ticker from "./simulation/Ticker.js";
-import { Localization } from "../core/Localization.js";
+import { Localization } from "../core/localization/Localization.js";
 import { ModuleRegistry } from "../core/model/ModuleRegistry.js";
 import { BinarySerializationRegistry } from "./ecs/storage/binary/BinarySerializationRegistry.js";
 import { EnginePluginManager } from "./plugin/EnginePluginManager.js";

package/engine/asset/AssetManager.js

@@ -326,6 +326,10 @@ export class AssetManager {
             throw new Error("Path must be string. Path = " + JSON.stringify(path));
         }
 
+        if(typeof type !== "string"){
+            throw new TypeError(`type must be a string, instead was '${typeof type}'`);
+        }
+
         const assetDescription = new AssetDescription(path, type);
 
         const asset = this.assets.get(assetDescription);

package/engine/ecs/speaker/VoiceSystem.js

@@ -373,7 +373,7 @@ export class VoiceSystem extends AbstractContextSystem {
         // localized line may contain reference tags, the user will not see/read those, so we also compile line as pure text for estimating reading time
         const line_pure_text = gml.compileAsText(localized_line);
 
-        const display_time_raw = localiation.computeReadingTime(line_pure_text);
+        const display_time_raw = localiation.estimateReadingTime(line_pure_text);
 
         const display_time = max2(TIMING_MINIMUM_READ_TIME, display_time_raw * line.displayDuration) + TIMING_NOTICE_DELAY;
 

package/engine/graphics/ecs/decal/v2/prototypeDecalSystem.js

@@ -15,7 +15,7 @@ import { GameAssetType } from "../../../../asset/GameAssetType.js";
 import { GLTFAssetLoader } from "../../../../asset/loaders/GLTFAssetLoader.js";
 import '../../../../../../../../css/game.scss';
 import { countTask } from "../../../../../core/process/task/util/countTask.js";
-import Vector2 from "../../../../../core/geom/Vector2.js";
+import Vector2, { v2_distance } from "../../../../../core/geom/Vector2.js";
 import { RotationBehavior } from "../../../../intelligence/behavior/util/RotationBehavior.js";
 import { BehaviorComponent } from "../../../../intelligence/behavior/ecs/BehaviorComponent.js";
 import Vector3 from "../../../../../core/geom/Vector3.js";
@@ -270,14 +270,17 @@ function grid(ecd, offset_x, offset_y, x, y, size_x, size_y, spacing, textures)
 function makeNormalTestGridDecal(ecd, root_transform = new Transform()) {
     const uv = new OctahedralUvEncoder();
 
-    const GRID_SIZE = 9;
+    const GRID_SIZE = 16;
 
     const CELL_SIZE = 1;
 
-    const SPACING = CELL_SIZE*1.2;
+    const SPACING = CELL_SIZE * 1.2;
+    // const SPACING = CELL_SIZE * 0.6;
 
     const DEBUG_BOX = makeHelperBoxGeometry();
 
+    const random = seededRandom(7);
+
     for (let i = 0; i < GRID_SIZE; i++) {
         for (let j = 0; j < GRID_SIZE; j++) {
 
@@ -290,7 +293,7 @@ function makeNormalTestGridDecal(ecd, root_transform = new Transform()) {
             const decal = new Decal();
 
             // decal.uri = decal_urls[1];
-            decal.uri ='moicon/ISO 7010 - Safety Signs (3)/ISO 7010 - Safety Signs/Emergency/400px/E001 – Emergency exit (left hand).png';
+            decal.uri = 'moicon/ISO 7010 - Safety Signs (3)/ISO 7010 - Safety Signs/Emergency/400px/E001 – Emergency exit (left hand).png';
 
             const entity = new EntityBuilder();
 
@@ -303,7 +306,7 @@ function makeNormalTestGridDecal(ecd, root_transform = new Transform()) {
                 0,
             );
             transform.scale.setScalar(CELL_SIZE);
-            transform.rotation._lookRotation(direction[0],direction[2], direction[1] , 0, 1, 0);
+            transform.rotation._lookRotation(direction[0], direction[2], direction[1], 0, 1, 0);
 
             transform.multiplyTransforms(root_transform, transform);
 
@@ -314,9 +317,12 @@ function makeNormalTestGridDecal(ecd, root_transform = new Transform()) {
                 .add(decal)
                 .build(ecd);
 
-            setInterval(()=>{
-                decal.priority = Math.random();
-            },7000);
+            // setInterval(()=>{
+            //     decal.priority = Math.random();
+            // },7000);
+
+            // decal.priority = randomIntegerBetween(random,0,4096);
+            decal.priority = v2_distance(i, j, GRID_SIZE * 0.5, GRID_SIZE * 0.5);
 
 
             // make an arrow helper
@@ -330,7 +336,7 @@ function makeNormalTestGridDecal(ecd, root_transform = new Transform()) {
                     side: DoubleSide
                 }), DrawMode.Triangles))
                 .add(arrow_transform)
-                .build(ecd);
+            .build(ecd);
         }
     }
 }
@@ -448,9 +454,9 @@ async function main(engine) {
     new EntityBuilder()
         .add(SGMesh.fromURL('data/models/snaps/cube_white.gltf'))
         .add(Transform.fromJSON({
-        position:new Vector3(14,1,4.8),
+            position: new Vector3(14, 1, 4.8),
             rotation: t_forward_grid.rotation,
-            scale: new Vector3(25,25,0.1)
+            scale: new Vector3(25, 25, 0.1)
         }))
         .build(ecd);
 

package/engine/graphics/render/forward_plus/LightManager.js

@@ -17,7 +17,6 @@ import Vector3 from "../../../../core/geom/Vector3.js";
 import { query_bvh_frustum_from_objects } from "./query/query_bvh_frustum_from_objects.js";
 import { IncrementalDeltaSet } from "../visibility/IncrementalDeltaSet.js";
 import { computeFrustumCorners } from "./computeFrustumCorners.js";
-import { compute_light_data_hash_0 } from "./cluster/compute_light_data_hash_0.js";
 import { read_plane_pair } from "./cluster/read_plane_pair.js";
 import { read_frustum_planes_to_array } from "../../../../core/geom/3d/frustum/read_frustum_planes_to_array.js";
 import { compute_cluster_planes_from_points } from "./cluster/compute_cluster_planes_from_points.js";
@@ -30,9 +29,7 @@ import { NumericType } from "./data/NumericType.js";
 import { computeDataType } from "./data/computeDataType.js";
 import { computeThreeTextureTypeFromDataType } from "./data/computeThreeTextureTypeFromDataType.js";
 import { computeThreeTextureInternalFormatFromDataType } from "./data/computeThreeTextureInternalFormatFromDataType.js";
-import { testClusterEquality } from "./testClusterEquality.js";
 import { BinaryUint32BVH } from "../../../../core/bvh2/binary/2/BinaryUint32BVH.js";
-import { query_bvh_frustum_from_texture } from "./query/query_bvh_frustum_from_texture.js";
 import { mat4 } from "gl-matrix";
 import { TextureAtlas } from "../../texture/atlas/TextureAtlas.js";
 import { CachingTextureAtlas } from "../../texture/atlas/CachingTextureAtlas.js";
@@ -48,46 +45,8 @@ import { arraySwapElements } from "../../../../core/collection/array/arraySwapEl
 import { compareObjectsByNumericId } from "../../../../core/model/object/compareObjectsByNumericId.js";
 import { slice_frustum_linear_to_points } from "../../../../core/geom/3d/frustum/slice_frustum_linear_to_points.js";
 import { read_cluster_frustum_corners } from "../../../../core/geom/3d/frustum/read_cluster_frustum_corners.js";
+import { assign_cluster, LOOKUP_CACHE, scratch_corners, scratch_frustum_planes } from "./assign_cluster.js";
 
-const LOOKUP_CACHE_SIZE = 1024; // must be power of two
-
-/**
- * Using continuous buffer for related attributes to get better cache utilization
- * @type {ArrayBuffer}
- * @private
- */
-const _scratch_array_buffer = new ArrayBuffer(
-    24 * 4
-    + 24 * 4
-    + LOOKUP_CACHE_SIZE * 4
-);
-
-/**
- *
- * @type {number[]|Float32Array|Float64Array}
- */
-const scratch_corners = new Float32Array(_scratch_array_buffer, 0, 24);
-
-
-/**
- * Linear access data structure with parameters of each plane of the frustum
- * 6 planes, 4 values per plane
- * Layout: [normal.x, normal.y, normal.z, constant]
- * @type {number[]|Float32Array|Float64Array}
- */
-const scratch_frustum_planes = new Float32Array(_scratch_array_buffer, 24 * 4, 24);
-
-/**
- * Cache used to identify duplicate cells. Helps reduce memory usage and just point to equivalent existing cells instead of allocating new ones.
- * @type {Uint16Array|Uint32Array}
- */
-const LOOKUP_CACHE = new Uint32Array(_scratch_array_buffer, (24 + 24) * 4, LOOKUP_CACHE_SIZE);
-
-/**
- *
- * @type {number[]}
- */
-const scratch_light_nodes = [];
 
 /**
  * How many bits are used to encode light type
@@ -121,84 +80,6 @@ function encode_light_descriptor(address, light) {
     return light_type | (address << 2);
 }
 
-function assign_cluster(
-    tile_texture_data_offset,
-    light_bvh,
-    lookup_address_offset,
-    light_lookup_texture_data,
-    tile_texture_data,
-    light_source_data
-) {
-
-    // at this point we have a fully constructed cluster, we can query lights within the cluster
-    const match_count = query_bvh_frustum_from_texture(
-        scratch_light_nodes,
-        0,
-        light_bvh,
-        light_source_data,
-        scratch_frustum_planes,
-        scratch_corners
-    );
-
-    // construct tile data
-
-    // write number of light entries
-    tile_texture_data[tile_texture_data_offset + 1] = match_count;
-
-    if (match_count === 0) {
-        // don't waste time on assignment, there are no lights in the cluster
-        return 0;
-    }
-
-    /*
-     We can sort lights by index to get higher cache utilization, but it turns out quite costly.
-     Through experimentation, sorting was taking around 20% of the whole assignment time
-     while improving number of cache hits by around 40% (8000 without sorting -> 11000 with sorting)
-     */
-    const cluster_data_hash = compute_light_data_hash_0(scratch_light_nodes, match_count) & (LOOKUP_CACHE_SIZE - 1);
-
-    const existing_lookup_address = LOOKUP_CACHE[cluster_data_hash];
-
-    if (existing_lookup_address !== 0xFFFFFFFF) {
-        // found a hash match, validate equality
-        const existing_lookup_entry_match = testClusterEquality(
-            scratch_light_nodes,
-            match_count,
-            light_lookup_texture_data,
-            existing_lookup_address
-        );
-
-        if (existing_lookup_entry_match) {
-            tile_texture_data[tile_texture_data_offset] = existing_lookup_address;
-
-            //hash_reuse_count++;
-
-            return 0;
-        }
-    } else {
-        // no hash entry exists, create one
-        LOOKUP_CACHE[cluster_data_hash] = lookup_address_offset;
-    }
-
-    // if we get to this point, that means no hash match was found, or equality check was failed
-
-    // write address of the lookup table
-    tile_texture_data[tile_texture_data_offset] = lookup_address_offset;
-
-    for (let i = 0; i < match_count; i++) {
-        /**
-         *
-         * @type {number}
-         */
-        const light_descriptor = scratch_light_nodes[i];
-
-        // construct lookup table
-        light_lookup_texture_data[lookup_address_offset + i] = light_descriptor;
-    }
-
-    return match_count;
-}
-
 /**
  *
  * @param {IncrementalDeltaSet<PointLightData>} data_set
@@ -968,7 +849,7 @@ export class LightManager {
 
         /**
          *
-         * @type {number[]|Uint8ClampedArray}
+         * @type {number[]|Float32Array}
          */
         const light_source_data = this.__light_data.getTexture().image.data;
 
@@ -1033,7 +914,7 @@ export class LightManager {
                         light_source_data
                     );
 
-                    lookup_address_offset += assign_cluster(
+                    const decal_count = assign_cluster(
                         tile_data_offset + 2,
                         bvh_decals,
                         lookup_address_offset,
@@ -1041,6 +922,23 @@ export class LightManager {
                         tile_texture_data,
                         light_source_data
                     );
+
+                    /*
+                    TODO fix decal sorting artifacts
+
+                    if (decal_count > 1) { // only sort when there are 2 or more, sorting 1 object is pointless
+                        // decals need to be sorted for correct blending result
+                        sort_decal_data(
+                            light_lookup_texture_data,
+                            light_source_data,
+                            lookup_address_offset,
+                            decal_count
+                        );
+                    }
+
+                     */
+
+                    lookup_address_offset += decal_count;
                 }
             }
         }

package/engine/graphics/render/forward_plus/SPECIFICATION.md

@@ -0,0 +1,155 @@
+# Clustered Lighting Specification
+
+## 1. GPU Data structures
+
+Data is organized into 3 main textures:
+
+ - Clusters. `type: UINT, format: RGBA, dimension: 3D, filtering: nearest(none)`
+   - R - Offset into lookup texture for lights
+   - G - number of lights
+   - B - Offset into lookup texture for decals
+   - A - number of decals
+ - Lookup. `type: UINT, format: R, dimensions: 2D, filtering: nearest(none)`
+   - R - encoded reference into data texture, where actual lighting information is stored
+ - Data. `type: FLOAT, format: RGBA, dimensions: 2D, filtering: nearest(none)`
+   - RGBA - single `word` of data, you can think of it as a collection of `VEC4`s
+
+Below is a glsl snippet with initialization of uniforms for these textures:
+```glsl
+uniform usampler3D fp_t_light_clusters;
+uniform usampler2D fp_t_light_lookup;
+uniform sampler2D fp_t_light_data;
+```
+
+## 2. Light Data Format
+
+Each light is represented as a collection of `VEC4`s inside the `Data` texture. 
+
+ - Point Light:
+   - `[ position.x, position.y, position.z, radius ]`
+   - `[ color.r, color.g, color.b, intensity ]`
+ - Directional Light:
+   - `[ direction.x, direction.y, direction.z, UNUSED ]`
+   - `[ color.r, color.g, color.b, intensity ]`
+
+## 3. Light reference encoding
+
+Lookup texture contains integers that encode both the address of light data, and the type of light found at that address, this is done by encoding light type into lower 2 bits of a UINT32 
+
+Light type codes:
+ - 0 - PointLight
+ - 1 - Directional Light
+ - 2 - Spotlight
+
+Encoding snippet in JavaScript:
+```js
+/**
+ *
+ * @param {number} address
+ * @param {AbstractLight} light
+ * @returns {number}
+ */
+function encode_light_descriptor(address, light) {
+    const light_type = encode_light_type(light);
+    return light_type | (address << 2);
+}
+```
+
+Decoding snippet in GLSL
+```glsl
+ivec2 address_to_data_texture_coordinates(uint address){
+    // Lookup texture has 128 width
+    uint lookup_index_x = address % 128u;
+    uint lookup_index_y = address >> 7;
+
+    return ivec2(int(lookup_index_x),int(lookup_index_y));
+}
+
+// ...
+uint light_descriptor = texelFetch(fp_t_light_lookup, address_to_data_texture_coordinates(lookup_index), 0 ).r;
+
+uint type = (light_descriptor) & 0x3u;
+uint light_address = light_descriptor >> 2;
+```
+
+## 4. Auxiliary material
+
+Convert projection-space depth to linear space
+```glsl
+float convert_depth_to_linear(in float d){
+    float d_n = 2.0*d - 1.0;
+
+    float f = fp_f_camera_far;
+    float n = fp_f_camera_near;
+
+    float fn = f*n;
+    
+    float z_diff = f - n;
+    
+    float denominator = (f + n - d_n * z_diff );
+
+    float z_view = (2.0*fn) / denominator;
+
+    return (z_view - n) / z_diff;
+}
+```
+
+Fetching cluster information from fragment shader inside a forward pass
+```glsl
+    // v3_cluster_resolution is resolution of our cluster 3d texture
+    ivec3 v3_cluster_resolution = textureSize(fp_t_light_tiles, 0);
+    ivec3 v3_cluster_position = ivec3(  clip_v.x * float(v3_cluster_resolution.x), clip_v.y*float(v3_cluster_resolution.y),  (clip_v.z)*float(v3_cluster_resolution.z) );
+
+    uvec4 fp_cluster_metadata = texelFetch( fp_t_light_tiles, v3_cluster_position, 0 ).rgba;
+```
+
+Perform lighting (point-light only)
+```glsl
+// read light data
+for(uint i=0u; i < fp_cluster_metadata.y; i++){
+    uint lookup_index = fp_cluster_metadata.x + i;
+
+    uint light_descriptor = texelFetch(fp_t_light_lookup, address_to_data_texture_coordinates(lookup_index), 0 ).r;
+
+    uint type = (light_descriptor) & 0x3u;
+    uint light_address = light_descriptor >> 2;
+    
+
+    if(type == 0u){
+        // point light
+        
+        vec4 light_data_0 = texelFetch(fp_t_light_data, address_to_data_texture_coordinates(light_address), 0);
+        vec4 light_data_1 = texelFetch(fp_t_light_data, address_to_data_texture_coordinates(light_address+1u), 0);
+        
+        vec3 light_position = light_data_0.xyz;
+        float light_radius = light_data_0.w;
+        
+        vec3 light_color = light_data_1.xyz;
+        float light_intensity = light_data_1.w;
+        
+        PointLight pointlight;
+        
+        pointlight.position = light_position;
+        pointlight.distance = light_radius;
+        pointlight.color = light_color*light_intensity;
+        pointlight.decay = 1.0;
+        
+        fp_getPointDirectLightIrradiance( pointlight, directLight, vViewPosition );
+        RE_Direct( directLight, geometry, material, reflectedLight );
+    
+    } else if(type == 1u){
+        // directional light
+        
+        // ...
+    }
+}
+```
+
+## References:
+- [Dr.Strangelight or: How I learned to Stop Worrying and Love the Cluster](https://discourse.threejs.org/t/dr-strangelight-or-how-i-learned-to-stop-worrying-and-love-the-cluster/23104)
+- [Practical Clustered Shading by Emil Persson](http://www.humus.name/Articles/PracticalClusteredShading.pdf)
+
+---
+Author: Alexander Goldring, Company Named Limited
+
+Private and confidential, copyright (c) Company Named Limited, 2022

package/engine/graphics/render/forward_plus/assign_cluster.js

@@ -0,0 +1,125 @@
+import { query_bvh_frustum_from_texture } from "./query/query_bvh_frustum_from_texture.js";
+import { compute_light_data_hash_0 } from "./cluster/compute_light_data_hash_0.js";
+import { testClusterEquality } from "./testClusterEquality.js";
+
+const LOOKUP_CACHE_SIZE = 1024; // must be power of two
+/**
+ * Using continuous buffer for related attributes to get better cache utilization
+ * @type {ArrayBuffer}
+ * @private
+ */
+const _scratch_array_buffer = new ArrayBuffer(
+    24 * 4
+    + 24 * 4
+    + LOOKUP_CACHE_SIZE * 4
+);
+/**
+ *
+ * @type {number[]|Float32Array|Float64Array}
+ */
+export const scratch_corners = new Float32Array(_scratch_array_buffer, 0, 24);
+/**
+ * Linear access data structure with parameters of each plane of the frustum
+ * 6 planes, 4 values per plane
+ * Layout: [normal.x, normal.y, normal.z, constant]
+ * @type {number[]|Float32Array|Float64Array}
+ */
+export const scratch_frustum_planes = new Float32Array(_scratch_array_buffer, 24 * 4, 24);
+/**
+ * Cache used to identify duplicate cells. Helps reduce memory usage and just point to equivalent existing cells instead of allocating new ones.
+ * @type {Uint16Array|Uint32Array}
+ */
+export const LOOKUP_CACHE = new Uint32Array(_scratch_array_buffer, (24 + 24) * 4, LOOKUP_CACHE_SIZE);
+/**
+ *
+ * @type {number[]}
+ */
+const scratch_light_nodes = [];
+
+/**
+ *
+ * @param {number} tile_texture_data_offset
+ * @param {BinaryUint32BVH} bvh
+ * @param {number} lookup_address_offset
+ * @param {number[]|ArrayLike<number>|Uint8ClampedArray|Uint8Array|Uint16Array|Uint32Array} lookup_data
+ * @param {number[]|ArrayLike<number>|Uint8Array|Uint8ClampedArray|Uint16Array|Uint32Array} cluster_data
+ * @param {number[]|ArrayLike<number>|Float32Array} source_data Light/Decal source information is stored in here, such as position, color etc.
+ * @return {number}
+ */
+export function assign_cluster(
+    tile_texture_data_offset,
+    bvh,
+    lookup_address_offset,
+    lookup_data,
+    cluster_data,
+    source_data
+) {
+
+    // at this point we have a fully constructed cluster, we can query lights within the cluster
+    const match_count = query_bvh_frustum_from_texture(
+        scratch_light_nodes,
+        0,
+        bvh,
+        source_data,
+        scratch_frustum_planes,
+        scratch_corners
+    );
+
+    // construct tile data
+
+    // write number of light entries
+    cluster_data[tile_texture_data_offset + 1] = match_count;
+
+    if (match_count === 0) {
+        // don't waste time on assignment, there are no lights in the cluster
+        return 0;
+    }
+
+    /*
+     We can sort lights by index to get higher cache utilization, but it turns out quite costly.
+     Through experimentation, sorting was taking around 20% of the whole assignment time
+     while improving number of cache hits by around 40% (8000 without sorting -> 11000 with sorting)
+     */
+    const cluster_data_hash = compute_light_data_hash_0(scratch_light_nodes, match_count) & (LOOKUP_CACHE_SIZE - 1);
+
+    const existing_lookup_address = LOOKUP_CACHE[cluster_data_hash];
+
+    if (existing_lookup_address !== 0xFFFFFFFF) {
+        // found a hash match, validate equality
+        const existing_lookup_entry_match = testClusterEquality(
+            scratch_light_nodes,
+            match_count,
+            lookup_data,
+            existing_lookup_address
+        );
+
+        if (existing_lookup_entry_match) {
+            cluster_data[tile_texture_data_offset] = existing_lookup_address;
+
+            //hash_reuse_count++;
+
+            return 0;
+        }
+    } else {
+        // no hash entry exists, create one
+        LOOKUP_CACHE[cluster_data_hash] = lookup_address_offset;
+    }
+
+    // if we get to this point, that means no hash match was found, or equality check was failed
+
+    // write address of the lookup table
+    cluster_data[tile_texture_data_offset] = lookup_address_offset;
+
+    for (let i = 0; i < match_count; i++) {
+        /**
+         *
+         * @type {number}
+         */
+        const light_descriptor = scratch_light_nodes[i];
+
+        // construct lookup table
+        lookup_data[lookup_address_offset + i] = light_descriptor;
+    }
+
+    return match_count;
+}

package/engine/graphics/render/forward_plus/model/Decal.js

@@ -100,7 +100,11 @@ export class Decal extends AbstractLight {
 
         array_copy(this.uv, 0, destination, address + 16, 4);
 
-        return 20;
+        // required for sorting
+        destination[address + 20] = this.draw_priority;
+        destination[address + 21] = this.id;
+
+        return 24;
     }
 }
 
@@ -110,4 +114,4 @@ export class Decal extends AbstractLight {
  */
 Decal.prototype.isDecal = true;
 
-Decal.prototype.ENCODED_SLOT_COUNT = 20;
+Decal.prototype.ENCODED_SLOT_COUNT = 24;

package/engine/graphics/render/forward_plus/prototype/prototypeLightManager.js

@@ -62,7 +62,7 @@ import { TooltipManager } from "../../../../../view/tooltip/TooltipManager.js";
 import { GMLEngine } from "../../../../../view/tooltip/gml/GMLEngine.js";
 import { PointerDevice } from "../../../../input/devices/PointerDevice.js";
 import { StaticKnowledgeDatabase } from "../../../../knowledge/database/StaticKnowledgeDatabase.js";
-import { Localization } from "../../../../../core/Localization.js";
+import { Localization } from "../../../../../core/localization/Localization.js";
 import '../../../../../../../../css/game.scss'
 import { randomFromArray } from "../../../../../core/math/random/randomFromArray.js";
 import { debugAtlas } from "../../../particles/particular/engine/shader/debugAtlas.js";
@@ -1558,8 +1558,8 @@ function draw_camera_view_planes() {
     });
 }
 
-prepare_scene_2();
-// prepare_scene_decal_0();
+// prepare_scene_2();
+prepare_scene_decal_0();
 // prepare_scene_decal_1();
 // prepare_scene_decal_2();
 // prepare_scene_9();

package/engine/graphics/render/forward_plus/query/query_bvh_frustum_from_texture.js

@@ -125,9 +125,9 @@ export function query_bvh_frustum_from_texture(
             const light_descriptor = data_view.getUint32(node_address + 24);
 
             const light_type = light_descriptor & 3;
-            const light_texel_index = light_descriptor >> 2;
 
-            const light_address = light_texel_index * 4;
+            // mask out type bits
+            const light_address = light_descriptor & 0xFFFFFFF8;
 
             if (light_type === 0) {
                 // Point light

package/engine/graphics/render/forward_plus/sort_decal_data.js

@@ -0,0 +1,102 @@
+const _scratch_array = [];
+
+/**
+ *
+ * @param {number} a
+ * @param {number} b
+ * @param {number[]} lookup
+ * @param {number[]} data
+ * @returns {number}
+ */
+function compare_decals(a, b, lookup, data) {
+    if (a === b) {
+        return 0;
+    }
+
+    const a_encoded = lookup[a];
+    const b_encoded = lookup[b];
+
+    // mask out bottom 2 type bits
+    const a_address = a_encoded & 0xFFFFFFF8;
+    const b_address = b_encoded & 0xFFFFFFF8;
+
+    const a_priority = data[a_address + 20];
+    const b_priority = data[b_address + 20];
+
+    let diff = b_priority - a_priority;
+
+    if (diff !== 0) {
+        return diff;
+    }
+
+
+    const a_id = data[a_address + 21];
+    const b_id = data[b_address + 21];
+
+    // data order is explicit and stable, we use that as a secondary comparison criteria
+    return b_id - a_id;
+}
+
+/**
+ * Decals need to be drawn in a specific order to achieve correct blending, for this they need to be sorted
+ * @param {number[]|Uint8ClampedArray|Uint8Array|Uint32Array} lookup
+ * @param {number[]|Float32Array} data
+ * @param {number} offset
+ * @param {number} count
+ */
+export function sort_decal_data(lookup, data, offset, count) {
+    const stack = _scratch_array;
+
+    stack[0] = offset;
+    stack[1] = offset + count - 1;
+
+    let stackPointer = 2;
+    let i, j;
+
+    while (stackPointer > 0) {
+        stackPointer -= 2;
+
+        const right = stack[stackPointer + 1];
+        const left = stack[stackPointer];
+
+        i = left;
+        j = right;
+
+        const pivotIndex = (left + right) >> 1;
+
+        /* partition */
+        while (i <= j) {
+
+            while (compare_decals(i, pivotIndex, lookup, data) > 0) {
+                i++;
+            }
+
+            while (compare_decals(j, pivotIndex, lookup, data) < 0) {
+                j--;
+            }
+
+            if (i <= j) {
+
+                if (i !== j) {
+                    //do swap
+                    const swap = lookup[i];
+                    lookup[i] = lookup[j]
+                    lookup[j] = swap;
+                }
+
+                i++;
+                j--;
+            }
+        }
+
+        /* recursion */
+        if (left < j) {
+            stack[stackPointer++] = left;
+            stack[stackPointer++] = j;
+        }
+        if (i < right) {
+            stack[stackPointer++] = i;
+            stack[stackPointer++] = right;
+        }
+    }
+}

package/engine/graphics/sh3/path_tracer/prototypePathTracer.js

@@ -27,7 +27,7 @@ import Task from "../../../../core/process/task/Task.js";
 import { TaskSignal } from "../../../../core/process/task/TaskSignal.js";
 import Quaternion from "../../../../core/geom/Quaternion.js";
 import TaskProgressView from "../../../../view/task/TaskProgressView.js";
-import { Localization } from "../../../../core/Localization.js";
+import { Localization } from "../../../../core/localization/Localization.js";
 
 import '../../../../../../../css/game.scss';
 import { MouseEvents } from "../../../input/devices/events/MouseEvents.js";

package/package.json

@@ -5,7 +5,7 @@
   "productName": "Meep",
   "description": "production-ready JavaScript game engine based on Entity Component System Architecture",
   "author": "Alexander Goldring",
-  "version": "2.44.7",
+  "version": "2.44.8",
   "dependencies": {
     "gl-matrix": "3.4.3",
     "fast-levenshtein": "2.0.6",

package/core/Localization.js

@@ -1,199 +0,0 @@
-import levenshtein from "fast-levenshtein";
-import { GameAssetType } from "../engine/asset/GameAssetType.js";
-import { parseTooltipString } from "../view/tooltip/gml/parser/parseTooltipString.js";
-import { assert } from "./assert.js";
-import ObservedString from "./model/ObservedString.js";
-import { seedVariablesIntoTemplateString } from "./parser/seedVariablesIntoTemplateString.js";
-import { STRING_TEMPLATE_VARIABLE_REGEX } from "./parser/STRING_TEMPLATE_VARIABLE_REGEX.js";
-
-/**
- * Validation utility method
- * @param {string} template
- * @return {string}
- */
-function validationMockSeed(template) {
-
-    const result = template.replace(STRING_TEMPLATE_VARIABLE_REGEX, function (match, varName) {
-        return "0";
-    });
-
-    return result;
-}
-
-const FAILURE_MESSAGE_CACHE = {};
-
-export class Localization {
-    constructor() {
-        /**
-         *
-         * @type {AssetManager|null}
-         */
-        this.assetManager = null;
-
-        this.json = {};
-
-        /**
-         * Measured in characters per second
-         * @type {number}
-         */
-        this.reading_speed = 10;
-
-        /**
-         *
-         * @type {ObservedString}
-         */
-        this.locale = new ObservedString('');
-    }
-
-    /**
-     *
-     * @param {string} text
-     * @returns {number}
-     */
-    computeReadingTime(text) {
-        assert.typeOf(text, 'string', 'text');
-
-        return text.length / this.reading_speed;
-    }
-
-    /**
-     *
-     * @param {AssetManager} am
-     */
-    setAssetManager(am) {
-        this.assetManager = am;
-    }
-
-    /**
-     * @returns {boolean}
-     * @param {function(key:string, error:*, original: string)} errorConsumer
-     */
-    validate(errorConsumer) {
-        let result = true;
-
-        for (let key in this.json) {
-            const value = this.json[key];
-
-            const seededValue = validationMockSeed(value);
-
-            try {
-                parseTooltipString(seededValue);
-            } catch (e) {
-                result = false;
-                errorConsumer(key, e, value);
-            }
-        }
-
-        return result;
-    }
-
-    /**
-     *
-     * @param {string} locale
-     * @returns {Promise}
-     */
-    loadLocale(locale) {
-        const am = this.assetManager;
-
-        const pLoadData = am.promise(`data/database/text/${locale}.json`, GameAssetType.JSON)
-            .then(asset => {
-                const json = asset.create();
-
-                this.json = json;
-
-                this.locale.set(locale);
-            });
-
-        const pLoadMetadata = am.promise(`data/database/text/languages.json`, GameAssetType.JSON)
-            .then(asset => {
-                const languages_metadata = asset.create();
-
-                const { reading_speed = 10 } = languages_metadata[locale];
-
-                assert.isNumber(reading_speed, 'reading_speed');
-                assert.greaterThan(reading_speed, 0, 'reading_speed');
-
-                this.reading_speed = reading_speed;
-            });
-
-        return Promise.all([pLoadData, pLoadMetadata]);
-    }
-
-    /**
-     *
-     * @param {String} id
-     * @return {boolean}
-     */
-    hasString(id) {
-        return this.json[id] !== undefined;
-    }
-
-    /**
-     *
-     * @param {number} value
-     */
-    formatIntegerByThousands(value) {
-        const formatter = new Intl.NumberFormat(this.locale.getValue(), { useGrouping: true });
-
-        return formatter.format(value);
-    }
-
-    /**
-     *
-     * @param {string} id
-     * @param {object} [seed]
-     *
-     * @returns {string}
-     */
-    getString(id, seed = {}) {
-        assert.typeOf(id, 'string', 'id');
-
-        const value = this.json[id];
-
-        if (value === undefined) {
-
-            if (!ENV_PRODUCTION) {
-                const locale = this.locale.getValue();
-
-                if (FAILURE_MESSAGE_CACHE[locale] === undefined) {
-                    FAILURE_MESSAGE_CACHE[locale] = {};
-                }
-
-                if (FAILURE_MESSAGE_CACHE[locale][id] === undefined) {
-
-                    //try to find similar keys
-                    const similarities = Object.keys(this.json).map(function (key) {
-                        const distance = levenshtein.get(key, id);
-                        return {
-                            key,
-                            distance
-                        };
-                    });
-
-                    similarities.sort(function (a, b) {
-                        return a.distance - b.distance;
-                    });
-
-                    const suggestions = similarities.slice(0, 3).map(p => p.key);
-
-                    const message = `No localization value for id='${id}', seed=${JSON.stringify(seed)}, approximate matches: ${suggestions.join(', ')}`;
-
-                    FAILURE_MESSAGE_CACHE[locale][id] = message;
-
-                }
-
-                console.warn(FAILURE_MESSAGE_CACHE[locale][id]);
-
-            }
-
-            //no value
-            return `@${id}`;
-
-        }
-
-        //value needs to be seeded
-        const seededValue = seedVariablesIntoTemplateString(value, seed);
-
-        return seededValue;
-    }
-}