@woosh/meep-engine 2.128.5 → 2.128.7

package/package.json

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

package/src/core/bvh2/binary/2/BinaryUint32BVH.d.ts

@@ -14,6 +14,14 @@ export const BVH_BINARY_NODE_SIZE: number;
  * @type {number}
  */
 export const BVH_LEAF_NODE_SIZE: number;
+/**
+ * Memory-efficient LBVH implementation.
+ * LBVH is fast to build, is quite fast to query and has good memory usage due to implicit addressing.
+ * LBVH is static, so it's not suitable for dynamic usecases, if your usecase requires updates to the BVH - use {@link BVH} instead, which is a fully dynamic BVH implementation.
+ *
+ * @see https://en.wikipedia.org/wiki/Bounding_volume_hierarchy
+ * @see BVH
+ */
 export class BinaryUint32BVH {
     /**
      *

package/src/core/bvh2/binary/2/BinaryUint32BVH.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BinaryUint32BVH.d.ts","sourceRoot":"","sources":["../../../../../../src/core/bvh2/binary/2/BinaryUint32BVH.js"],"names":[],"mappings":"AAUA;;;GAGG;AACH,gCAFU,MAAM,CAEmB;AAEnC;;;;GAIG;AACH,mCAFU,MAAM,CAEsB;AACtC;;;GAGG;AACH,iCAFU,MAAM,CAEoB;AAiDpC;IACI;;;;OAIG;IACH,sBAAc;IAEd;;;;OAIG;IACH,gCAAe;IAEf;;;;OAIG;IACH,+BAAc;IAEd;;;;OAIG;IACH,4BAAwB;IAExB;;;;OAIG;IACH,0BAAsB;IA0CtB;;;OAGG;IACH,2BAOC;IAED,wBAEC;IAnDD;;;OAGG;IACH,oBAFa,MAAM,CAIlB;IAED,2BAEC;IAED,gCAEC;IAED,8BAEC;IAED;;;OAGG;IACH,uBAFa,MAAM,CAIlB;IAED,4BAEC;IAED,0BAEC;IAmBD;;;;OAIG;IACH,2BAHW,MAAM,GACJ,MAAM,CAalB;IAED,6BASC;IAED;;;OAGG;IACH,oBAFW,MAAM,QAgBhB;IAED;;;;OAIG;IACH,sBAHW,MAAM,GACL,MAAM,CASjB;IAED;;;;;;;;;;OAUG;IACH,mBATW,MAAM,WACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAoChB;IAED;;;;;OAKG;IACH,oBAJW,MAAM,eACN,MAAM,EAAE,GAAC,YAAY,sBACrB,MAAM,QAIhB;IAED;;;;OAIG;IACH,4BAHW,MAAM,GACJ,MAAM,CAQlB;IAED,qCAoBC;IAED;;;OAGG;IACH,oBAFW,MAAM,EAAE,QAqElB;IAED;;;;;OAKG;IACH,sBAUC;IAED;;OAEG;IACH,cAsEC;CACJ"}
+{"version":3,"file":"BinaryUint32BVH.d.ts","sourceRoot":"","sources":["../../../../../../src/core/bvh2/binary/2/BinaryUint32BVH.js"],"names":[],"mappings":"AAUA;;;GAGG;AACH,gCAFU,MAAM,CAEmB;AAEnC;;;;GAIG;AACH,mCAFU,MAAM,CAEsB;AACtC;;;GAGG;AACH,iCAFU,MAAM,CAEoB;AAiDpC;;;;;;;GAOG;AACH;IACI;;;;OAIG;IACH,sBAAc;IAEd;;;;OAIG;IACH,gCAAe;IAEf;;;;OAIG;IACH,+BAAc;IAEd;;;;OAIG;IACH,4BAAwB;IAExB;;;;OAIG;IACH,0BAAsB;IA0CtB;;;OAGG;IACH,2BAOC;IAED,wBAEC;IAnDD;;;OAGG;IACH,oBAFa,MAAM,CAIlB;IAED,2BAEC;IAED,gCAEC;IAED,8BAEC;IAED;;;OAGG;IACH,uBAFa,MAAM,CAIlB;IAED,4BAEC;IAED,0BAEC;IAmBD;;;;OAIG;IACH,2BAHW,MAAM,GACJ,MAAM,CAalB;IAED,6BASC;IAED;;;OAGG;IACH,oBAFW,MAAM,QAgBhB;IAED;;;;OAIG;IACH,sBAHW,MAAM,GACL,MAAM,CASjB;IAED;;;;;;;;;;OAUG;IACH,mBATW,MAAM,WACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAoChB;IAED;;;;;OAKG;IACH,oBAJW,MAAM,eACN,MAAM,EAAE,GAAC,YAAY,sBACrB,MAAM,QAIhB;IAED;;;;OAIG;IACH,4BAHW,MAAM,GACJ,MAAM,CAQlB;IAED,qCAoBC;IAED;;;OAGG;IACH,oBAFW,MAAM,EAAE,QAqElB;IAED;;;;;OAKG;IACH,sBAUC;IAED;;OAEG;IACH,cAsEC;CACJ"}

package/src/core/bvh2/binary/2/BinaryUint32BVH.js

@@ -73,6 +73,14 @@ function build_morton(data, address, bounds) {
 
 const stack = SCRATCH_UINT32_TRAVERSAL_STACK;
 
+/**
+ * Memory-efficient LBVH implementation.
+ * LBVH is fast to build, is quite fast to query and has good memory usage due to implicit addressing.
+ * LBVH is static, so it's not suitable for dynamic usecases, if your usecase requires updates to the BVH - use {@link BVH} instead, which is a fully dynamic BVH implementation.
+ *
+ * @see https://en.wikipedia.org/wiki/Bounding_volume_hierarchy
+ * @see BVH
+ */
 export class BinaryUint32BVH {
     /**
      *
@@ -423,7 +431,7 @@ export class BinaryUint32BVH {
         let level = Math.floor(Math.log(binary_node_count) / Math.log(2));
 
         let i, offset, level_node_count;
-        //NOTE: building first level separately allows to avoid some switching logic needed to determine what is the type of lower level node
+        //NOTE: building the first level separately allows us to avoid some switching logic needed to determine what is the type of lower level node
         //build one level above leaf nodes
         level_node_count = Math.pow(2, level);
         offset = (level_node_count - 1) * BVH_BINARY_NODE_SIZE;

package/src/core/cache/Cache.d.ts

@@ -1,6 +1,11 @@
 import Signal from "../events/signal/Signal";
 
-export class Cache<K, V> extends Map<K,V>{
+interface Hashable {
+    hash(): number
+    equals(other: any): boolean
+}
+
+export class Cache<K extends Hashable, V> extends Map<K,V>{
     constructor({
                     maxWeight,
                     keyWeigher,
@@ -19,6 +24,7 @@ export class Cache<K, V> extends Map<K,V>{
 
     readonly onEvicted: Signal<K, V>
     readonly onRemoved: Signal<K, V>
+    readonly onSet: Signal<K, V>
 
     readonly weight: number
 

package/src/core/cache/Cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Cache.d.ts","sourceRoot":"","sources":["../../../../src/core/cache/Cache.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IASI;;;;;;;;OAQG;IACH,sGARW,MAAM,EA2FhB;IAzDG;;;;OAIG;IACH,mBAA4B;IAE5B;;;;OAIG;IACH,qBAAgC;IAEhC;;;;OAIG;IACH,gBAAmB;IACnB;;;;OAIG;IACH,eAAkB;IAGlB;;;;OAIG;IACH,aAIE;IAEF;;;;OAIG;IACH,WAFU,OAAO,GAAG,EAAC,KAAK,CAAC,CAEE;IAE7B;;;OAGG;IACH,WAFU,OAAO,GAAG,EAAC,KAAK,CAAC,CAEE;IAE7B;;;OAGG;IACH,OAFU,OAAO,GAAG,EAAC,KAAK,CAAC,CAEF;IAG7B;;;;;OAKG;IACH,kBAyBC;IAED;;;OAGG;IACH,QAFa,MAAM,CAIlB;IAED;;OAEG;IACH,+BAEC;IAED;;;OAGG;IACH,qBAEC;IAED;;;OAGG;IACH,2BAeC;IAED,wBAEC;IAED;;;;OAIG;IACH,wBAaC;IAED;;;;;;OAMG;IACH,yBAHW,GAAG,GACD,OAAO,CAgCnB;IAED;;;;;OAKG;IACH,6BAUC;IAED;;;OAGG;IACH,sBAFa,aAAa,GAAG,EAAC,KAAK,CAAC,GAAC,IAAI,CAIxC;IAED;;;OAGG;IACH,YAFa,OAAO,CAkBnB;IAED;;;OAGG;IACH,+BAFW,MAAM,QAWhB;IAED;;;;OAIG;IACH,SAHW,GAAG,SACH,KAAK,QAwEf;IAED;;;;OAIG;IACH,cAHW,GAAG,GACD,OAAO,CAInB;IAED;;;;OAIG;IACH,SAHW,GAAG,GACD,KAAK,GAAC,IAAI,CAYtB;IAGD;;;;;;OAMG;IACH,kBALW,GAAG,kBACM,GAAG,KAAE,KAAK,0BAElB,KAAK,CAchB;IAED;;;;OAIG;IACH,wBAqBC;IAED;;;;OAIG;IACH,YAHW,GAAG,GACD,OAAO,CAgBnB;IAED;;;;;OAKG;IACH,kBAHW,GAAG,GACD,OAAO,CAanB;IAED;;OAEG;IACH,cAcC;IAED;;;OAGG;IACH,aAOC;IAED;;;;;OAKG;IACH,wCAFa,OAAO,CAMnB;IAGL;;;OAGG;IACH,6CAAmB;IAEnB;;;OAGG;IACH,+BA5FiB,OAAO,CA4FF;IAEtB;;;OAGG;IACH,4BA9KiB,OAAO,CA8KL;;CAlBlB;mBAzjBkB,4BAA4B;6BAKlB,mBAAmB"}
+{"version":3,"file":"Cache.d.ts","sourceRoot":"","sources":["../../../../src/core/cache/Cache.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAgBI;;;;;;;;;;OAUG;IACH,sGARW,MAAM,EA2FhB;IAzDG;;;;OAIG;IACH,mBAA4B;IAE5B;;;;OAIG;IACH,qBAAgC;IAEhC;;;;OAIG;IACH,gBAAmB;IACnB;;;;OAIG;IACH,eAAkB;IAGlB;;;;OAIG;IACH,aAIE;IAEF;;;;OAIG;IACH,WAFU,OAAO,GAAG,EAAC,KAAK,CAAC,CAEE;IAE7B;;;OAGG;IACH,WAFU,OAAO,GAAG,EAAC,KAAK,CAAC,CAEE;IAE7B;;;OAGG;IACH,OAFU,OAAO,GAAG,EAAC,KAAK,CAAC,CAEF;IAG7B;;;;;OAKG;IACH,kBAyBC;IAED;;;OAGG;IACH,QAFa,MAAM,CAIlB;IAED;;OAEG;IACH,+BAEC;IAED;;;;;OAKG;IACH,qBAEC;IAED;;;OAGG;IACH,2BAeC;IAED,wBAEC;IAED;;;;OAIG;IACH,wBAaC;IAED;;;;;;OAMG;IACH,yBAHW,GAAG,GACD,OAAO,CAgCnB;IAED;;;;;OAKG;IACH,6BAUC;IAED;;;OAGG;IACH,sBAFa,aAAa,GAAG,EAAC,KAAK,CAAC,GAAC,IAAI,CAIxC;IAED;;;OAGG;IACH,YAFa,OAAO,CAkBnB;IAED;;;OAGG;IACH,gCAFW,MAAM,QAWhB;IAED;;;;OAIG;IACH,SAHW,GAAG,SACH,KAAK,QAwEf;IAED;;;;OAIG;IACH,cAHW,GAAG,GACD,OAAO,CAInB;IAED;;;;OAIG;IACH,SAHW,GAAG,GACD,KAAK,GAAC,IAAI,CAYtB;IAGD;;;;;;OAMG;IACH,kBALW,GAAG,kBACM,GAAG,KAAE,KAAK,0BAElB,KAAK,CAchB;IAED;;;;OAIG;IACH,wBAqBC;IAED;;;;OAIG;IACH,YAHW,GAAG,GACD,OAAO,CAgBnB;IAED;;;;;OAKG;IACH,kBAHW,GAAG,GACD,OAAO,CAanB;IAED;;;;OAIG;IACH,cAcC;IAED;;;OAGG;IACH,aAOC;IAED;;;;;OAKG;IACH,wCAFa,OAAO,CAMnB;IAGL;;;OAGG;IACH,6CAAmB;IAEnB;;;OAGG;IACH,+BA9FiB,OAAO,CA8FF;IAEtB;;;OAGG;IACH,4BAhLiB,OAAO,CAgLL;;CAlBlB;mBAtkBkB,4BAA4B;6BAKlB,mBAAmB"}

package/src/core/cache/Cache.js

@@ -29,7 +29,14 @@ import { CacheElement } from "./CacheElement.js";
  * @copyright Company Named Limited (c) 2025
  */
 export class Cache {
+
+    /**
+     * How much "weight" can the cache hold before it starts evicting elements
+     * @type {number}
+     * @private
+     */
     #maxWeight = Number.POSITIVE_INFINITY;
+
     /**
      *
      * @type {number}
@@ -38,6 +45,8 @@ export class Cache {
     #weight = 0;
 
     /**
+     * Note: setting {@link maxWeight} to 0 is pointless, as the cache will not be able to hold even a single element.
+     *
      * @param {number} [maxWeight=Number.POSITIVE_INFINITY] capacity of the cache, measure in "weight"; The weight is computed by summing key and value weights.
      * @param {function(key:Key):number} [keyWeigher= key=>0] function to compute weight of a key
      * @param {function(value:Value):number} [valueWeigher= value=>1] function to compute weight of a value
@@ -180,7 +189,9 @@ export class Cache {
     }
 
     /**
-     * Total weight of all elements currently in the cache
+     * Total weight of all elements currently in the cache.
+     * This is guaranteed to be less than or equal to {@link maxWeight}
+     *
      * @returns {number}
      */
     get weight() {
@@ -188,7 +199,7 @@ export class Cache {
     }
 
     /**
-     * Will cause evictions if current weight is smaller than what we're setting
+     * Will cause evictions if the current weight is greater than what we're setting
      * @param {number} weight
      */
     set maxWeight(weight) {
@@ -234,7 +245,7 @@ export class Cache {
 
     /**
      * Useful when working with wrapped value types, where contents can change and affect overall weight
-     * Instead of re-inserting element, we can just update weights
+     * Instead of re-inserting the element, we can just update weights
      * NOTE: this method may trigger eviction
      * @param {Key} key
      * @returns {boolean} true when weight successfully updated, false if element was not found in cache
@@ -299,7 +310,7 @@ export class Cache {
 
     /**
      * Evicts a single element from the cache
-     * @returns {boolean} true if element was evicted, false otherwise
+     * @returns {boolean} true if an element was evicted, false otherwise
      */
     evictOne() {
         //find a victim
@@ -320,14 +331,14 @@ export class Cache {
     }
 
     /**
-     * Drop data until weight reduces lower or equal to requested weight
-     * @param {number} targetWeight
+     * Drop data until the weight reduces to lower or equal to the requested weight
+     * @param {number} target_weight
      */
-    evictUntilWeight(targetWeight) {
-        assert.isNumber(targetWeight, 'targetWeight');
-        assert.notNaN(targetWeight, 'targetWeight');
+    evictUntilWeight(target_weight) {
+        assert.isNumber(target_weight, 'target_weight');
+        assert.notNaN(target_weight, 'target_weight');
 
-        const target = Math.max(targetWeight, 0);
+        const target = Math.max(target_weight, 0);
 
         while (this.#weight > target) {
             this.evictOne();
@@ -355,7 +366,7 @@ export class Cache {
 
             if (weightTarget < 0) {
                 // Special case
-                // element does not fit into cache, attempting to insert it forcibly would result in a full flush and overflow
+                // element does not fit into the cache, attempting to insert it forcibly would result in a full flush and overflow
                 return;
             }
 
@@ -512,7 +523,7 @@ export class Cache {
      * Remove without triggering {@link #onRemoved}
      * NOTE: please be sure you understand what you're doing when you use this method
      * @param {Key} key
-     * @returns {boolean} true if element was removed, false otherwise
+     * @returns {boolean} true if the element was removed, false otherwise
      */
     silentRemove(key) {
         const element = this.data.get(key);
@@ -528,7 +539,9 @@ export class Cache {
     }
 
     /**
-     * Remove all elements from the cache
+     * Remove all elements from the cache.
+     * Triggers {@link #onRemoved} for each removed element.
+     *
      */
     clear() {
         /**

package/src/core/collection/array/array_shuffle.d.ts

@@ -1,8 +1,8 @@
 /**
  * Randomly re-orders items in-place
  * @template T
- * @param {function} random
- * @param {T[]} array
+ * @param {function():number} random random number generator; can use Math.random. Must return a value between 0 and 1
+ * @param {T[]} array what to shuffle
  */
-export function array_shuffle<T>(random: Function, array: T[]): void;
+export function array_shuffle<T>(random: () => number, array: T[]): void;
 //# sourceMappingURL=array_shuffle.d.ts.map

package/src/core/collection/array/array_shuffle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"array_shuffle.d.ts","sourceRoot":"","sources":["../../../../../src/core/collection/array/array_shuffle.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,qEAYC"}
+{"version":3,"file":"array_shuffle.d.ts","sourceRoot":"","sources":["../../../../../src/core/collection/array/array_shuffle.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,+CAHsB,MAAM,oBAe3B"}

package/src/core/collection/array/array_shuffle.js

@@ -4,8 +4,8 @@ import { array_swap_one } from "./array_swap_one.js";
 /**
  * Randomly re-orders items in-place
  * @template T
- * @param {function} random
- * @param {T[]} array
+ * @param {function():number} random random number generator; can use Math.random. Must return a value between 0 and 1
+ * @param {T[]} array what to shuffle
  */
 export function array_shuffle(random, array) {
     const n = array.length;

package/src/core/collection/array/array_swap.d.ts

@@ -1,10 +1,23 @@
 /**
+ * Swap two sections between arrays, can be used to move elements in the same array
  * @template T
  * @param {T[]|ArrayLike<T>|TypedArray|Uint8ClampedArray|Uint8Array|Uint32Array|Float32Array} a
  * @param {number} a_offset
  * @param {T[]|ArrayLike<T>|TypedArray|Uint8ClampedArray|Uint8Array|Uint32Array|Float32Array} b
  * @param {number} b_offset
  * @param {number} length How many elements should be moved
+ * @returns {void}
+ *
+ * @example
+ *  const array = [1, 2, 3, 4, 5];
+ *  array_swap(array, 0, array, 2, 1); // array === [4, 2, 3, 1, 5]
+ * @example
+ *  const array_a = ["hello", "world"];
+ *  const array_b = ["foo", "bar"];
+ *  array_swap(array_a, 1, array_b, 0, 1); // array_a === ["hello", "foo"], array_b === ["world", "bar"]
+ * @example
+ *  const array = [1, 2, 3, 4, 5];
+ *  array_swap(array, 0, array, 2, 2); // array === [3, 4, 1, 2, 5]
  */
 export function array_swap<T>(a: any, a_offset: number, b: any, b_offset: number, length: number): void;
 //# sourceMappingURL=array_swap.d.ts.map

package/src/core/collection/array/array_swap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"array_swap.d.ts","sourceRoot":"","sources":["../../../../../src/core/collection/array/array_swap.js"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,gDALW,MAAM,oBAEN,MAAM,UACN,MAAM,QAkBhB"}
+{"version":3,"file":"array_swap.d.ts","sourceRoot":"","sources":["../../../../../src/core/collection/array/array_swap.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,gDAjBW,MAAM,oBAEN,MAAM,UACN,MAAM,GACJ,IAAI,CA+BhB"}

package/src/core/collection/array/array_swap.js

@@ -1,16 +1,33 @@
+import { assert } from "../../assert.js";
+
 /**
+ * Swap two sections between arrays, can be used to move elements in the same array
  * @template T
  * @param {T[]|ArrayLike<T>|TypedArray|Uint8ClampedArray|Uint8Array|Uint32Array|Float32Array} a
  * @param {number} a_offset
  * @param {T[]|ArrayLike<T>|TypedArray|Uint8ClampedArray|Uint8Array|Uint32Array|Float32Array} b
  * @param {number} b_offset
  * @param {number} length How many elements should be moved
+ * @returns {void}
+ *
+ * @example
+ *  const array = [1, 2, 3, 4, 5];
+ *  array_swap(array, 0, array, 2, 1); // array === [4, 2, 3, 1, 5]
+ * @example
+ *  const array_a = ["hello", "world"];
+ *  const array_b = ["foo", "bar"];
+ *  array_swap(array_a, 1, array_b, 0, 1); // array_a === ["hello", "foo"], array_b === ["world", "bar"]
+ * @example
+ *  const array = [1, 2, 3, 4, 5];
+ *  array_swap(array, 0, array, 2, 2); // array === [3, 4, 1, 2, 5]
  */
 export function array_swap(
     a, a_offset,
     b, b_offset,
     length
 ) {
+    assert.isNonNegativeInteger(a_offset, 'a_offset');
+    assert.isNonNegativeInteger(b_offset, 'b_offset');
 
     for (let k = 0; k < length; k++) {
         const i = a_offset + k;

package/src/core/collection/array/array_swap_one.d.ts

@@ -1,8 +1,11 @@
 /**
+ * Swaps two elements in the array
  * @template T
  * @param {T[]} array
  * @param {number} index0
  * @param {number} index1
+ * @returns {void}
+ * @see array_swap
  */
 export function array_swap_one<T>(array: T[], index0: number, index1: number): void;
 //# sourceMappingURL=array_swap_one.d.ts.map

package/src/core/collection/array/array_swap_one.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"array_swap_one.d.ts","sourceRoot":"","sources":["../../../../../src/core/collection/array/array_swap_one.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,sDAHW,MAAM,UACN,MAAM,QAWhB"}
+{"version":3,"file":"array_swap_one.d.ts","sourceRoot":"","sources":["../../../../../src/core/collection/array/array_swap_one.js"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,sDALW,MAAM,UACN,MAAM,GACJ,IAAI,CAYhB"}

package/src/core/collection/array/array_swap_one.js

@@ -1,10 +1,13 @@
 import { assert } from "../../assert.js";
 
 /**
+ * Swaps two elements in the array
  * @template T
  * @param {T[]} array
  * @param {number} index0
  * @param {number} index1
+ * @returns {void}
+ * @see array_swap
  */
 export function array_swap_one(array, index0, index1) {
     assert.isArrayLike(array, 'array');

package/src/engine/reference/v2/Reference.d.ts

@@ -1,7 +1,7 @@
 import Signal from "../../../core/events/signal/Signal";
 
 export class Reference<T> {
-    readonly onReleased: Signal<Reference<T>, T>
+    readonly onReleased: Signal<this, T>
 
     readonly bound: boolean
 
@@ -10,4 +10,8 @@ export class Reference<T> {
     release(): void
 
     bind(v: T): void
+
+    static from<X>(x: X): Reference<X>
+
+    static readonly NULL: Readonly<Reference<any>>
 }

package/src/engine/reference/v2/Reference.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Reference.d.ts","sourceRoot":"","sources":["../../../../../src/engine/reference/v2/Reference.js"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH;IAwBI,qBAEC;IAED;;;OAGG;IACH,gEAEC;IAED;;;OAGG;IACH,YAFW,CAAC,QAcX;IAED;;;OAGG;IACH,YAFa,CAAC,CAIb;IAED;;;OAGG;IACH,gBAcC;;CACJ;;cAKS,wBAAmB;;mBAlGV,uCAAuC"}
+{"version":3,"file":"Reference.d.ts","sourceRoot":"","sources":["../../../../../src/engine/reference/v2/Reference.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH;IAoCI;;;;;;;;OAQG;IACH,mCAMC;IA3BD,qBAEC;IAED;;;OAGG;IACH,gEAEC;IAmBD;;;OAGG;IACH,YAFW,CAAC,QAcX;IAED;;;OAGG;IACH,YAFa,CAAC,CAIb;IAED;;;OAGG;IACH,gBAcC;;CACJ;;cAKS,wBAAmB;;mBA1HV,uCAAuC"}

package/src/engine/reference/v2/Reference.js

@@ -8,6 +8,13 @@ import Signal from "../../../core/events/signal/Signal.js";
  *      // do work with texture
  *      ref.release(); // we're done with the resource, texture_system will be notified
  *      // now ref.getValue() === null, reference is no longer valid
+ * @example
+ *      const ref: Reference<Texture> = Reference.from(texture);
+ *      ref.onReleased.add((this_ref:Reference<Texture>, texture:Texture) => {
+ *          // cleanup memory when the reference is released
+ *          texture.dispose();
+ *      });
+ *      // pass the reference to some other system for use
  * @template T
  */
 export class Reference {
@@ -46,6 +53,23 @@ export class Reference {
         return this.#onReleased;
     }
 
+    /**
+     * Produces a new instance of a bound reference with a given value.
+     * Same as calling {@link bind} on a new instance.
+     *
+     * @template X
+     * @param {X} x
+     * @return {Reference<X>}
+     * @see bind
+     */
+    static from(x){
+        const r = new Reference();
+
+        r.bind(x);
+
+        return r;
+    }
+
     /**
      *
      * @param {T} value

package/src/view/common/VirtualListView.d.ts

@@ -48,7 +48,7 @@ declare class VirtualListView extends View<HTMLElement> {
      * @private
      */
     private __alignment_vertical;
-    __index_cache: Cache<any, any>;
+    __index_cache: Cache<import("../../core/cache/Cache.js").Hashable, any>;
     __throttledUpdate: Function;
     __handleElementAdded(el: any, index: any): void;
     __handleElementRemoved(el: any, index: any): void;

package/src/view/common/VirtualListView.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VirtualListView.d.ts","sourceRoot":"","sources":["../../../../src/view/common/VirtualListView.js"],"names":[],"mappings":";;;;;;AAgBA;IACI;;;;;;;;;;OAUG;IACH,gHARW,MAAM,EAoGhB;IA/EG,cAAgB;IAahB,YAAkB;IAclB,yBAA+B;IAE/B,mCAAkC;IAElC,6BAA8B;IAC9B,4BAA6B;IAE7B,iCAAoC;IAEpC;;;;OAIG;IACH,oBAA2B;IAE3B;;;;OAIG;IACH,uBAAiC;IAEjC;;;;OAIG;IACH,0BAAuC;IAEvC;;;;OAIG;IACH,6BAA6C;IAG7C,+BAIE;IAGF,4BAAyD;IAS7D,gDASC;IAED,kDAOC;IAGD,eA4EC;IAED,qCAmBC;IAED;;;;;OAKG;IACH,kCAIC;IAED,gCAKC;IAED,oBAMC;CAeJ;iBAlRgB,YAAY;iBAPZ,oCAAoC;sBAD/B,2BAA2B"}
+{"version":3,"file":"VirtualListView.d.ts","sourceRoot":"","sources":["../../../../src/view/common/VirtualListView.js"],"names":[],"mappings":";;;;;;AAgBA;IACI;;;;;;;;;;OAUG;IACH,gHARW,MAAM,EAoGhB;IA/EG,cAAgB;IAahB,YAAkB;IAclB,yBAA+B;IAE/B,mCAAkC;IAElC,6BAA8B;IAC9B,4BAA6B;IAE7B,iCAAoC;IAEpC;;;;OAIG;IACH,oBAA2B;IAE3B;;;;OAIG;IACH,uBAAiC;IAEjC;;;;OAIG;IACH,0BAAuC;IAEvC;;;;OAIG;IACH,6BAA6C;IAG7C,wEAIE;IAGF,4BAAyD;IAS7D,gDASC;IAED,kDAOC;IAGD,eA4EC;IAED,qCAmBC;IAED;;;;;OAKG;IACH,kCAIC;IAED,gCAKC;IAED,oBAMC;CAeJ;iBAlRgB,YAAY;iBAPZ,oCAAoC;sBAD/B,2BAA2B"}