@woosh/meep-engine 2.44.8 → 2.45.1

package/core/collection/HashMap.d.ts

@@ -29,7 +29,7 @@ export class HashMap<K, V> implements Iterable<[V, K]> {
 
     forEach(callback: (value: V, key: K, map: this) => any, thisArg?: any): void
 
-    [Symbol.iterator](): IterableIterator<[V, K]>
+    [Symbol.iterator](): IterableIterator<[K, V]>
 
     values(): IterableIterator<V>
 

package/core/collection/HashMap.js

@@ -40,6 +40,7 @@ const DEFAULT_LOAD_FACTOR = 0.75;
 
 /**
  * Implements part of {@link Map} interface
+ * @copyright Alex Goldring (c) 2023
  * @template K,V
  * @extends Map<K,V>
  */
@@ -519,7 +520,7 @@ export class HashMap {
                  */
                 const entry = bucket[i];
 
-                yield  [entry.value, entry.key];
+                yield  [entry.key, entry.value];
             }
         }
 

package/core/localization/LanguageMetadata.js

@@ -1,7 +1,7 @@
 import { assert } from "../assert.js";
 
 /**
- *
+ * Represents information about a language
  */
 export class LanguageMetadata {
     /**
@@ -10,12 +10,32 @@ export class LanguageMetadata {
      */
     reading_speed = 10
 
-    fromJSON({ reading_speed = 10 }) {
+    /**
+     * Ordered list of fallback languages, if no value is found for a key in this language, other languages will be attempted in order
+     * Identified by localization key
+     * @see {@link #locale}
+     * @type {string[]}
+     */
+    fallback_languages = []
+
+    /**
+     * Localization key,
+     * @see ISO 639
+     * @type {string}
+     */
+    locale = "";
+
+    fromJSON({
+                 reading_speed = 10,
+                 fallback_languages = []
+             }) {
 
         assert.isNumber(reading_speed, 'reading_speed');
         assert.greaterThan(reading_speed, 0, 'reading_speed');
 
         this.reading_speed = reading_speed;
+
+        this.fallback_languages = fallback_languages;
     }
 
     static fromJSON(j) {

package/core/localization/LocaleDataset.js

@@ -0,0 +1,37 @@
+//
+
+import { assert } from "../assert.js";
+
+/**
+ * Represents data for a single localization
+ */
+export class LocaleDataset {
+    /**
+     * Localized strings, identified by localization key
+     * @type {Object<string>}
+     * @private
+     */
+    __strings = {}
+
+    /**
+     *
+     * Does a given key exist?
+     * @param {string} key
+     * @return {boolean}
+     */
+    hasString(key) {
+        assert.isString(key, 'key');
+
+        return this.__strings[key] !== undefined;
+    }
+
+    /**
+     *
+     * @param {string} key
+     * @returns {string|undefined}
+     */
+    getString(key) {
+        return this.__strings[key];
+    }
+
+}

package/core/localization/Localization.js

@@ -25,7 +25,7 @@ function validationMockSeed(template) {
 
 const EMPTY_SEED = Object.freeze({});
 
-const DEFAULT_LANGUAGE_METADATA = new LanguageMetadata();
+const DEFAULT_LANGUAGE_METADATA = Object.freeze(new LanguageMetadata());
 
 export class Localization {
     constructor() {
@@ -117,7 +117,8 @@ export class Localization {
     }
 
     /**
-     *
+     * Request locale switch
+     * Assumes a specific folder structure, each different locale is stored with its locale code as name, and there's also "languages.json" file expected to be in the folder
      * @param {string} locale
      * @param {string} path where to look for localization data
      * @returns {Promise}
@@ -132,7 +133,14 @@ export class Localization {
             throw new Error('AssetManager is not set');
         }
 
-        const pLoadData = am.promise(`${path}/${locale}.json`, "json")
+        let _path = path.trim();
+
+        while (_path.endsWith('/') || _path.endsWith('\\')) {
+            // remove trailing slash if present
+            _path.slice(0, _path.length - 1);
+        }
+
+        const pLoadData = am.promise(`${_path}/${locale}.json`, "json")
             .then(asset => {
                 const json = asset.create();
 
@@ -148,7 +156,7 @@ export class Localization {
 
             });
 
-        const pLoadMetadata = am.promise(`${path}/languages.json`, "json")
+        const pLoadMetadata = am.promise(`${_path}/languages.json`, "json")
             .then(asset => {
                 const languages_metadata = asset.create();
 
@@ -162,14 +170,6 @@ export class Localization {
         return Promise.all([pLoadData, pLoadMetadata]);
     }
 
-    /**
-     *
-     * @param {String} id
-     * @return {boolean}
-     */
-    hasString(id) {
-        return this.json[id] !== undefined;
-    }
 
     /**
      *
@@ -216,29 +216,38 @@ export class Localization {
     }
 
     /**
-     *
-     * @param {string} id
+     * Get a localized string by a key
+     * @param {string} key
      * @param {object} [seed]
      *
      * @returns {string}
      */
-    getString(id, seed = EMPTY_SEED) {
-        assert.isString(id, 'id');
+    getString(key, seed = EMPTY_SEED) {
+        assert.isString(key, 'id');
 
-        const value = this.json[id];
+        const value = this.json[key];
 
         if (value === undefined) {
 
             if (this.debug) {
-                this.__debugMissingKey(id, seed)
+                this.__debugMissingKey(key, seed)
             }
 
             //no value, provide substitute
-            return `@${id}`;
+            return `@${key}`;
 
         }
 
         //value needs to be seeded
         return seedVariablesIntoTemplateString(value, seed);
     }
+
+    /**
+     * Does a given key exist?
+     * @param {string} key
+     * @return {boolean}
+     */
+    hasString(key) {
+        return this.json[key] !== undefined;
+    }
 }

package/core/process/task/Task.js

@@ -5,7 +5,7 @@
 
 import { assert } from "../../assert.js";
 import Signal from "../../events/signal/Signal.js";
-import { noop, returnZero } from "../../function/Functions.js";
+import { noop } from "../../function/Functions.js";
 import ObservedInteger from "../../model/ObservedInteger.js";
 import { TaskSignal } from "./TaskSignal.js";
 import TaskState from "./TaskState.js";
@@ -27,14 +27,14 @@ class Task {
             name,
             initializer = noop,
             cycleFunction,
-            computeProgress = returnZero,
+            computeProgress,
             dependencies = [],
             estimatedDuration = 1
         }
     ) {
 
-        assert.typeOf(cycleFunction, "function", 'cycleFunction');
-        assert.typeOf(estimatedDuration, 'number', 'estimatedDuration');
+        assert.isFunction(cycleFunction, 'cycleFunction');
+        assert.isNumber(estimatedDuration, 'estimatedDuration');
 
 
         this.dependencies = dependencies;
@@ -59,7 +59,12 @@ class Task {
          */
         this.initialize = initializer;
 
-        this.computeProgress = computeProgress;
+        if (computeProgress !== undefined) {
+
+            // override progress function
+            this.computeProgress = computeProgress;
+
+        }
 
         this.on = {
             started: new Signal(),
@@ -87,6 +92,18 @@ class Task {
         this.__executedCycleCount = 0;
     }
 
+    computeProgress() {
+
+        const cycles = this.__executedCycleCount;
+
+        if (cycles === 0) {
+            return 0;
+        }
+
+        // inverse logarithmic progression, never reaches 1
+        return 1 - (1 / cycles);
+    }
+
     /**
      * Time in milliseconds that the task has been executing for, suspended time does not count
      * @returns {number}

package/core/process/task/util/iteratorTask.js

@@ -0,0 +1,29 @@
+import Task from "../Task.js";
+import { TaskSignal } from "../TaskSignal.js";
+import { assert } from "../../../assert.js";
+
+/**
+ *
+ * @param {string} name
+ * @param {Iterator} iterator
+ * @param {TaskSignal.Continue|TaskSignal.Yield} [cycle_signal] what to signal at the end of each iteration, Continue will provide better throughput, whereas Yield will produce very low load on the CPU
+ * @returns {Task}
+ */
+export function iteratorTask(name, iterator, cycle_signal = TaskSignal.Continue) {
+    assert.defined(iterator, 'iterator');
+    assert.notNull(iterator, 'iterator');
+    assert.isFunction(iterator.next, 'iterator.next');
+
+    return new Task({
+        name,
+        cycleFunction() {
+            const next = iterator.next();
+
+            if (next.done) {
+                return TaskSignal.EndSuccess
+            } else {
+                return cycle_signal;
+            }
+        }
+    })
+}

package/engine/ecs/foliage/ViewState.js

@@ -1,6 +1,8 @@
 import { BitSet } from "../../../core/binary/BitSet.js";
 import { InstancedMeshGroup } from "../../graphics/geometry/instancing/InstancedMeshGroup.js";
-import { queryBinaryNode_FrustumIntersections_Data } from "../../../core/bvh2/traversal/queryBinaryNode_FrustumIntersections.js";
+import {
+    queryBinaryNode_FrustumIntersections_Data
+} from "../../../core/bvh2/traversal/queryBinaryNode_FrustumIntersections.js";
 import Quaternion from "../../../core/geom/Quaternion.js";
 import Vector3 from "../../../core/geom/Vector3.js";
 import { compose_matrix4_array } from "../../../core/geom/3d/compose_matrix4_array.js";
@@ -30,6 +32,10 @@ export class ViewState {
          * @type {InstancedMeshGroup}
          */
         this.instances = new InstancedMeshGroup();
+        
+        // make shrinking unlikely to prevent thrashing
+        this.instances.shrinkFactor = 0.4;
+        this.instances.shrinkConstant = 1024;
 
         /**
          *

package/engine/graphics/ecs/mesh-v2/ShadedGeometrySystem.js

@@ -20,6 +20,7 @@ import TaskState from "../../../../core/process/task/TaskState.js";
 import {
     bvh_query_user_data_overlaps_frustum
 } from "../../../../core/bvh2/bvh3/query/bvh_query_user_data_overlaps_frustum.js";
+import { iteratorTask } from "../../../../core/process/task/util/iteratorTask.js";
 
 
 /**
@@ -34,6 +35,31 @@ const scratch_point = new SurfacePoint3();
  */
 const scratch_ray_0 = new Float32Array(6);
 
+/**
+ *
+ * @param {ShadedGeometrySystem} system
+ * @return {Generator}
+ */
+function* maintenance_generator(system) {
+    while (true) { //infinite loop
+
+        const contexts = system.__view_contexts;
+
+        for (const [key, value] of contexts) {
+
+            if (value === undefined) {
+                continue;
+            }
+
+            yield* value.maintain();
+
+        }
+
+        // a small break between re-runs
+        yield;
+    }
+}
+
 export class ShadedGeometrySystem extends System {
     /**
      *
@@ -100,8 +126,15 @@ export class ShadedGeometrySystem extends System {
                 }
             }
         });
+
+        this.__maintenance_task = iteratorTask(
+            'Maintenance',
+            maintenance_generator(this),
+            TaskSignal.Yield
+        );
     }
 
+
     /**
      *
      * @returns {ExplicitBinaryBoundingVolumeHierarchy}
@@ -222,6 +255,9 @@ export class ShadedGeometrySystem extends System {
         this.__optimization_task.state.set(TaskState.INITIAL);
         engine.executor.run(this.__optimization_task);
 
+        this.__maintenance_task.state.set(TaskState.INITIAL);
+        engine.executor.run(this.__maintenance_task);
+
         readyCallback();
     }
 
@@ -233,6 +269,7 @@ export class ShadedGeometrySystem extends System {
         const view_list = graphics.views.elements;
 
         engine.executor.removeTask(this.__optimization_task);
+        engine.executor.removeTask(this.__maintenance_task);
 
         view_list.forEach(this.__handle_view_removed, this);
         view_list.on.added.remove(this.__handle_view_added, this);

package/engine/graphics/ecs/mesh-v2/render/ShadedGeometryRendererContext.js

@@ -30,6 +30,25 @@ export class ShadedGeometryRendererContext {
         ];
     }
 
+    /**
+     * Performs maintenance on the context, mainly to check the hash tables for changes
+     * @return {Generator}
+     */
+    * maintain() {
+        const adapters = this.adapters;
+        for (let i = 0; i < adapters.length; i++) {
+            const adapter = adapters[i];
+
+            if (adapter === undefined) {
+                // adapter may disappear between invocations, since this is a continuation-type function
+                continue;
+            }
+
+            // delegate to adapter's maintenance
+            yield* adapter.maintain();
+        }
+    }
+
     /**
      *
      * @param {number} index

package/engine/graphics/ecs/mesh-v2/render/adapters/AbstractRenderAdapter.js

@@ -2,8 +2,8 @@ import { array_quick_sort_by_comparator } from "../../../../../../core/collectio
 
 /**
  *
- * @param {THREE.Object3D} a
- * @param {THREE.Object3D} b
+ * @param {THREE.Object3D|{material?:Material}} a
+ * @param {THREE.Object3D|{material?:Material}} b
  * @returns {number}
  */
 function compare_by_material(a, b) {
@@ -96,6 +96,15 @@ export class AbstractRenderAdapter {
         this.__object_count = 0;
     }
 
+    /**
+     * Used to perform infrequent housekeeping on the adapter's internal data structures
+     * Returns a maintenance sequence
+     * @return {Generator}
+     */
+    * maintain() {
+        // override as necessary
+    }
+
     /**
      * @returns {THREE.Object3D[]}
      */

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

@@ -1076,12 +1076,24 @@ export class LightManager {
     }
 
     /**
-     *
+     * Set resolution of the cluster texture, higher resolution will result in less load on the GPU, but will take up more RAM to represent and more time to build the clusters each frame
      * @param {number} x
      * @param {number} y
      * @param {number} z
      */
     setTileMapResolution(x, y, z) {
+        assert.isNumber(x,'x');
+        assert.isNonNegativeInteger(x,'x');
+        assert.isFiniteNumber(x,'x');
+
+        assert.isNumber(y,'y');
+        assert.isNonNegativeInteger(y,'y');
+        assert.isFiniteNumber(y,'y');
+
+        assert.isNumber(z,'z');
+        assert.isNonNegativeInteger(z,'z');
+        assert.isFiniteNumber(z,'z');
+
         const r = this.__tiles_resolution;
 
         if (x === r.x && y === r.y && z === r.z) {

package/engine/graphics/render/forward_plus/plugin/ForwardPlusRenderingPlugin.d.ts

@@ -0,0 +1,5 @@
+import {EnginePlugin} from "../../../../plugin/EnginePlugin";
+
+export class ForwardPlusRenderingPlugin extends EnginePlugin {
+    setClusterResolution(x: number, y: number, z: number): void
+}

package/engine/graphics/render/forward_plus/plugin/ForwardPlusRenderingPlugin.js

@@ -9,6 +9,7 @@ export class ForwardPlusRenderingPlugin extends EnginePlugin {
         super();
 
         this.__light_manager = new LightManager();
+        lm.setTileMapResolution(16, 8, 8);
 
         this.__resolution = new ThreeVector2();
 
@@ -19,6 +20,16 @@ export class ForwardPlusRenderingPlugin extends EnginePlugin {
         });
     }
 
+    /**
+     * Set resolution of the cluster texture, higher resolution will result in less load on the GPU, but will take up more RAM to represent and more time to build the clusters each frame
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     */
+    setClusterResolution(x, y, z) {
+        this.__light_manager.setTileMapResolution(x, y, z);
+    }
+
     /**
      *
      * @param {CameraView} view
@@ -37,10 +48,6 @@ export class ForwardPlusRenderingPlugin extends EnginePlugin {
     }
 
     async startup() {
-        const lm = this.__light_manager;
-
-        lm.setTileMapResolution(16, 8, 8);
-
         const graphics = this.engine.graphics;
 
         graphics.getMaterialManager().addCompileStep(this.__material_transformer);

package/engine/input/devices/InputDeviceButton.d.ts

@@ -0,0 +1,7 @@
+import Signal from "../../../core/events/signal/Signal";
+
+export class InputDeviceButton{
+    readonly up: Signal
+    readonly down: Signal
+    readonly is_down: boolean
+}

package/engine/input/devices/InputDeviceButton.js

@@ -0,0 +1,22 @@
+import Signal from "../../../core/events/signal/Signal.js";
+
+/**
+ * Representation of an input device key
+ */
+export class InputDeviceButton {
+    /**
+     * Button press
+     * @type {Signal}
+     */
+    down = new Signal()
+    /**
+     * Button release
+     * @type {Signal}
+     */
+    up = new Signal()
+    /**
+     * is button currently being pressed?
+     * @type {boolean}
+     */
+    is_down = false
+}

package/engine/input/devices/KeyboardDevice.d.ts

@@ -1,3 +1,14 @@
+import {InputDeviceButton} from "./InputDeviceButton";
+import Signal from "../../../core/events/signal/Signal";
+
 export default class KeyboardDevice {
+    constructor(domElement:EventTarget|Element)
+
+    readonly on: {up:Signal,down:Signal}
+
+    readonly keys:{[key:string]:InputDeviceButton}
+
+    start():void
 
+    stop():void
 }

package/engine/input/devices/KeyboardDevice.js

@@ -5,6 +5,7 @@
 import Signal from "../../../core/events/signal/Signal.js";
 import { KeyCodes } from './KeyCodes.js';
 import { KeyboardEvents } from "./events/KeyboardEvents.js";
+import { InputDeviceButton } from "./InputDeviceButton.js";
 
 /**
  *
@@ -66,21 +67,23 @@ class KeyboardDevice {
             up: new Signal()
         };
 
-        //initialize separate events for each key
+
+        /**
+         *
+         * @type {Object<InputDeviceButton>}
+         */
         const keys = this.keys = {};
 
         const codeToKeyNameMap = [];
 
+        //initialize separate events for each key
         for (let keyName in KeyCodes) {
 
             const keyCode = KeyCodes[keyName];
 
             codeToKeyNameMap[keyCode] = keyName;
 
-            keys[keyName] = {
-                down: new Signal(),
-                up: new Signal()
-            };
+            keys[keyName] = new InputDeviceButton();
         }
 
         this.__handlerKeyDown = (event) => {
@@ -91,7 +94,11 @@ class KeyboardDevice {
             const keyName = codeToKeyNameMap[keyCode];
 
             if (keyName !== undefined) {
-                keys[keyName].down.send1(event);
+                const button = keys[keyName];
+
+                button.is_down = true;
+                button.down.send1(event);
+
             }
         }
 
@@ -104,7 +111,10 @@ class KeyboardDevice {
             const keyName = codeToKeyNameMap[keyCode];
 
             if (keyName !== undefined) {
-                keys[keyName].up.send1(event);
+                const button = keys[keyName];
+
+                button.is_down = false;
+                button.up.send1(event);
             }
         }
     }

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.8",
+  "version": "2.45.1",
   "dependencies": {
     "gl-matrix": "3.4.3",
     "fast-levenshtein": "2.0.6",