@woosh/meep-engine 2.50.2 → 2.51.0

package/README.md

@@ -13,7 +13,8 @@ To help get you started, various samples are provided under `/samples` folder. F
 
 [Engine Documentation](http://meep-engine.company-named.com:8080/docs/api/)
 
-## Features, for more information, please refer to the documentation
+## Features
+
 * Automatic instancing. This will minimize the number of draw calls and improve performance.
 * Decals. Decals in meep are done on the GPU, and as a result you can have a lot of them in your scene. The most I tested in a single scene is 1,000,000 which works quite well. Decals are useful for bullet holes, blood splatter and various scene decorations such as signs and scuff marks.
 * Deferred lights. Meep implements clustered lighting technique which allows you to have a pretty much an unlimited number of point lights in your scene. All the other light types are supported as well, but only point lights are clustered for now. Point lights are useful for various effects, like muzzle flashes, grenade explosions, torches, etc.
@@ -35,5 +36,7 @@ To help get you started, various samples are provided under `/samples` folder. F
 * UI system. You're free to use it or not, the engine works just fine without it. The system is written for speed, and it offers a few commonly used tools, such as popup windows, notifications and pages. The UI system is optimized for speed, so it generates no garbage, but again - if you want to use, say React - you can ignore this system or integrate it with the system.
 * Trails. Meep implements a fairly complex trail system, where a trail can be attached to an entity, and it will create a trail behind.
 
+For more information, please refer to the documentation
+
 ---
 Copyright © 2023 Company Named Limited, All Rights Reserved

package/editor/actions/concrete/WriteGridValueAction.js

@@ -1,4 +1,3 @@
-import GridField from "../../../src/engine/navigation/grid/GridField.js";
 import GridObstacle from "../../../src/engine/grid/components/GridObstacle.js";
 import { Action } from "../../../src/core/process/undo/Action.js";
 
@@ -16,31 +15,27 @@ class WriteGridValueAction extends Action {
     }
 
     async apply(editor) {
-        const obstacle = editor.engine.entityManager.getComponent(this.entity, GridObstacle);
+        /**
+         * @type {Engine}
+         */
+        const engine = editor.engine;
+
+        /**
+         *
+         * @type {GridObstacle}
+         */
+        const obstacle = engine.entityManager.dataset.getComponent(this.entity, GridObstacle);
         this.obstacle = obstacle;
 
 
-        const gridField = obstacle2grid(obstacle);
-
-        this.oldValue = gridField.read(this.x, this.y);
-        gridField.pointSet(this.x, this.y, this.value);
+        this.oldValue = obstacle.readPoint(this.x, this.y);
+        obstacle.writePoint(this.x, this.y, this.value);
     }
 
     async revert(editor) {
-        const gridField = obstacle2grid(this.obstacle);
 
-        gridField.pointSet(this.x, this.y, this.oldValue);
+        this.obstacle.writePoint(this.x, this.y, this.oldValue);
     }
 }
 
-function obstacle2grid(obstacle) {
-    const gridField = new GridField();
-
-    gridField.width = obstacle.size.x;
-    gridField.height = obstacle.size.y;
-    gridField.data = obstacle.data;
-
-    return gridField;
-}
-
 export default WriteGridValueAction;

package/editor/ecs/component/editors/Sampler2DEditor.js

@@ -1,7 +1,7 @@
 import { TypeEditor } from "../TypeEditor.js";
 import { CanvasView } from "../../../../src/view/elements/CanvasView.js";
 import sampler2D2Canvas from "../../../../src/engine/graphics/texture/sampler/Sampler2D2Canvas.js";
-import { scaleSampler2D } from "../../../../src/engine/graphics/texture/sampler/scaleSampler2D.js";
+import { sampler2d_scale } from "../../../../src/engine/graphics/texture/sampler/resize/sampler2d_scale.js";
 import { Sampler2D } from "../../../../src/engine/graphics/texture/sampler/Sampler2D.js";
 import {
     typedArrayConstructorByInstance
@@ -38,7 +38,7 @@ function draw_sampler(sampler, domElement) {
     const res = 32;
     const result_sampler = new Sampler2D(new TypedArrayConstructor(sampler.itemSize * res * res), sampler.itemSize, res, res);
 
-    scaleSampler2D(sampler, result_sampler);
+    sampler2d_scale(sampler, result_sampler);
 
 
     const { scale, offset } = sampler2d_compute_texel_value_conversion_scale_to_uint8(result_sampler);

package/editor/process/SymbolicDisplayProcess.js

@@ -1,6 +1,6 @@
 import { EditorProcess } from "./EditorProcess.js";
 import { ParticleEmitter } from "../../src/engine/graphics/particles/particular/engine/emitter/ParticleEmitter.js";
-import RenderSystem from "../../src/engine/ecs/systems/RenderSystem.js";
+import RenderSystem from "../../src/engine/ecs/renderable/RenderSystem.js";
 import { Camera } from "../../src/engine/graphics/ecs/camera/Camera.js";
 import { Light } from "../../src/engine/graphics/ecs/light/Light.js";
 import { ComponentSymbolicDisplay } from "./symbolic/ComponentSymbolicDisplay.js";

package/editor/process/symbolic/buildThreeJSHelperEntity.js

@@ -1,5 +1,5 @@
 import EntityBuilder from "../../../src/engine/ecs/EntityBuilder.js";
-import Renderable from "../../../src/engine/ecs/components/Renderable.js";
+import Renderable from "../../../src/engine/ecs/renderable/Renderable.js";
 import { Transform } from "../../../src/engine/ecs/transform/Transform.js";
 import EditorEntity from "../../ecs/EditorEntity.js";
 import Script from "../../../src/engine/ecs/components/Script.js";

package/editor/process/symbolic/makeCameraSymbolicDisplay.js

@@ -1,7 +1,7 @@
 import { make3DSymbolicDisplay } from "./make3DSymbolicDisplay.js";
 import { CameraHelper } from "three";
 import { buildThreeJSHelperEntity } from "./buildThreeJSHelperEntity.js";
-import Renderable from "../../../src/engine/ecs/components/Renderable.js";
+import Renderable from "../../../src/engine/ecs/renderable/Renderable.js";
 import { Camera } from "../../../src/engine/graphics/ecs/camera/Camera.js";
 import { Transform } from "../../../src/engine/ecs/transform/Transform.js";
 

package/editor/process/symbolic/makeGridPositionSymbolDisplay.js

@@ -4,7 +4,7 @@ import Task from "../../../src/core/process/task/Task.js";
 import { TaskSignal } from "../../../src/core/process/task/TaskSignal.js";
 import EntityBuilder from "../../../src/engine/ecs/EntityBuilder.js";
 import { BufferGeometry, Float32BufferAttribute, Line, LineBasicMaterial } from "three";
-import Renderable from "../../../src/engine/ecs/components/Renderable.js";
+import Renderable from "../../../src/engine/ecs/renderable/Renderable.js";
 import { SurfacePoint3 } from "../../../src/core/geom/3d/SurfacePoint3.js";
 import Vector3 from "../../../src/core/geom/Vector3.js";
 import { Transform } from "../../../src/engine/ecs/transform/Transform.js";

package/editor/process/symbolic/makeLightSymbolicDisplay.js

@@ -2,7 +2,7 @@ import { Light } from "../../../src/engine/graphics/ecs/light/Light.js";
 import { DirectionalLightHelper, PointLightHelper, SpotLightHelper } from "three";
 import { make3DSymbolicDisplay } from "./make3DSymbolicDisplay.js";
 import { buildThreeJSHelperEntity } from "./buildThreeJSHelperEntity.js";
-import Renderable from "../../../src/engine/ecs/components/Renderable.js";
+import Renderable from "../../../src/engine/ecs/renderable/Renderable.js";
 import { Transform } from "../../../src/engine/ecs/transform/Transform.js";
 
 /**

package/editor/process/symbolic/makePathSymbolicDisplay.js

@@ -1,7 +1,7 @@
 import { BufferGeometry, Float32BufferAttribute, Group, Line, LineBasicMaterial } from "three";
 import Vector3 from "../../../src/core/geom/Vector3.js";
 import { min2 } from "../../../src/core/math/min2.js";
-import Renderable from "../../../src/engine/ecs/components/Renderable.js";
+import Renderable from "../../../src/engine/ecs/renderable/Renderable.js";
 import { buildThreeJSHelperEntity } from "./buildThreeJSHelperEntity.js";
 import { make3DSymbolicDisplay } from "./make3DSymbolicDisplay.js";
 import Path from "../../../src/engine/navigation/ecs/components/Path.js";

package/editor/process/symbolic/makePositionedIconDisplaySymbol.js

@@ -2,7 +2,7 @@ import { assert } from "../../../src/core/assert.js";
 import { Sprite, SpriteMaterial } from "three";
 import { make3DSymbolicDisplay } from "./make3DSymbolicDisplay.js";
 import EntityBuilder from "../../../src/engine/ecs/EntityBuilder.js";
-import Renderable from "../../../src/engine/ecs/components/Renderable.js";
+import Renderable from "../../../src/engine/ecs/renderable/Renderable.js";
 import { Transform } from "../../../src/engine/ecs/transform/Transform.js";
 import { synchronizeTransform } from "./synchronizeTransform.js";
 

package/editor/view/ecs/components/GridObstacleController.js

@@ -4,7 +4,7 @@ import { CanvasView } from "../../../../src/view/elements/CanvasView.js";
 import DatGuiController from "./DatGuiController.js";
 import convertSampler2D2Canvas from "../../../../src/engine/graphics/texture/sampler/Sampler2D2Canvas.js";
 import { Sampler2D } from "../../../../src/engine/graphics/texture/sampler/Sampler2D.js";
-import { scaleSampler2D } from "../../../../src/engine/graphics/texture/sampler/scaleSampler2D.js";
+import { sampler2d_scale } from "../../../../src/engine/graphics/texture/sampler/resize/sampler2d_scale.js";
 import Vector2 from "../../../../src/core/geom/Vector2.js";
 
 /**
@@ -17,7 +17,7 @@ export function buildGridObstaclePreview(grid, canvas) {
 
     const target = Sampler2D.uint8(1, canvas.width, canvas.height);
 
-    scaleSampler2D(source, target);
+    sampler2d_scale(source, target);
 
     convertSampler2D2Canvas(target, 255, 0, canvas);
 }

package/editor/view/ecs/components/TerrainController.js

@@ -7,7 +7,7 @@ import CheckersTextureURI from "../../../../src/engine/graphics/texture/Checkers
 import EmptyView from "../../../../src/view/elements/EmptyView.js";
 import convertSampler2D2Canvas from "../../../../src/engine/graphics/texture/sampler/Sampler2D2Canvas.js";
 import { CanvasView } from "../../../../src/view/elements/CanvasView.js";
-import { scaleSampler2D } from "../../../../src/engine/graphics/texture/sampler/scaleSampler2D.js";
+import { sampler2d_scale } from "../../../../src/engine/graphics/texture/sampler/resize/sampler2d_scale.js";
 import { Sampler2D } from "../../../../src/engine/graphics/texture/sampler/Sampler2D.js";
 import Signal from "../../../../src/core/events/signal/Signal.js";
 import Vector2Control from "../../../../src/view/controller/controls/Vector2Control.js";
@@ -93,7 +93,7 @@ class LayersController extends View {
 
                     function update() {
 
-                        scaleSampler2D(layer.diffuse, t);
+                        sampler2d_scale(layer.diffuse, t);
 
                         convertSampler2D2Canvas(t, 1, 0, vCanvas.el);
                     }

package/package.json

@@ -5,7 +5,7 @@
   "description": "Fully featured ECS game engine written in JavaScript",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "2.50.2",
+  "version": "2.51.0",
   "main": "build/meep.module.js",
   "module": "build/meep.module.js",
   "exports": {

package/samples/terrain/editor.js

@@ -11,7 +11,7 @@ import { obtainTerrain } from "../../src/engine/ecs/terrain/util/obtainTerrain.j
 import { Cache } from "../../src/core/cache/Cache.js";
 import { computeStringHash } from "../../src/core/primitives/strings/computeStringHash.js";
 import { noop, strictEquals } from "../../src/core/function/Functions.js";
-import { scaleSampler2D } from "../../src/engine/graphics/texture/sampler/scaleSampler2D.js";
+import { sampler2d_scale } from "../../src/engine/graphics/texture/sampler/resize/sampler2d_scale.js";
 import { Sampler2D } from "../../src/engine/graphics/texture/sampler/Sampler2D.js";
 import { BinaryDataType } from "../../src/core/binary/type/BinaryDataType.js";
 import {
@@ -205,7 +205,7 @@ function makeTerrainEditor(root, terrain, engine) {
 
         const preview = Sampler2D.uint8(4, PREVIEW_SIZE, PREVIEW_SIZE);
 
-        scaleSampler2D(source, preview);
+        sampler2d_scale(source, preview);
 
         PREVIEW_CACHE.put(url, preview);
 

package/src/core/UUID.spec.js

@@ -0,0 +1,8 @@
+import UUID from "./UUID.js";
+
+test("valid string is produced", () => {
+    const id = UUID.generate();
+
+    expect(typeof id).toBe("string");
+    expect(id.trim().length).toBeGreaterThan(0);
+});

package/src/core/bvh2/bvh3/ExplicitBinaryBoundingVolumeHierarchy.d.ts

@@ -11,6 +11,8 @@ export class ExplicitBinaryBoundingVolumeHierarchy {
 
     remove_leaf(node: number): void
 
+    node_is_leaf(node: number): boolean
+
     collect_nodes_all(destination: ArrayLike<number>, destination_offset: number): void
 
     node_set_aabb_primitive(node_id: number, x0: number, y0: number, z0: number, x1: number, y1: number, z1: number): void
@@ -39,6 +41,8 @@ export class ExplicitBinaryBoundingVolumeHierarchy {
 
     node_get_height(node: number): number
 
+    node_move_aabb(node: number, new_aabb: ArrayLike<number>): void
+
     swap_nodes(node_a_id: number, node_b_id: number): boolean
 
     release_all(): void

package/src/core/bvh2/bvh3/ExplicitBinaryBoundingVolumeHierarchy.js

@@ -54,65 +54,67 @@ const INITIAL_CAPACITY = 128;
 /**
  * Bounding Volume Hierarchy implementation. Stores unsigned integer values at leaves, these are typically IDs or Index values.
  * Highly optimized both in terms of memory usage and CPU. Most of the code inlined. No allocation are performed during usage (except for growing the tree capacity).
- * RAM usage: 40 bytes per node. Compared with V8s per-object allocation size of 80 bytes (see https://blog.dashlane.com/how-is-data-stored-in-v8-js-engine-memory)
+ * RAM usage: 40 bytes per node. Compared with V8s per-object allocation size of 80 bytes
+ * @see https://blog.dashlane.com/how-is-data-stored-in-v8-js-engine-memory
+ * @class
  */
 export class ExplicitBinaryBoundingVolumeHierarchy {
-    constructor() {
-        /**
-         *
-         * @type {ArrayBuffer}
-         * @private
-         */
-        this.__data_buffer = new ArrayBuffer(INITIAL_CAPACITY * ELEMENT_WORD_COUNT * 4);
-
-        /**
-         *
-         * @type {Float32Array}
-         * @private
-         */
-        this.__data_float32 = new Float32Array(this.__data_buffer);
-
-        /**
-         *
-         * @type {Uint32Array}
-         * @private
-         */
-        this.__data_uint32 = new Uint32Array(this.__data_buffer);
-
-        /**
-         * How many nodes are currently reserved, this will grow automatically through {@link #allocate_node} method usage
-         * @type {number}
-         * @private
-         */
-        this.__capacity = INITIAL_CAPACITY;
-
-        /**
-         * Number of used nodes. These are either live nodes, or node sitting in the {@link #__free} pool
-         * @type {number}
-         * @private
-         */
-        this.__size = 0;
 
-        /**
-         * Indices of released nodes. Nodes are pulled from here first if available, before the whole tree gets resized
-         * @type {number[]}
-         * @private
-         */
-        this.__free = [];
-        /**
-         * Pointer into __free array that's used as a stack, so this pointer represents top of the stack
-         * @type {number}
-         * @private
-         */
-        this.__free_pointer = 0;
+    /**
+     *
+     * @type {ArrayBuffer}
+     * @private
+     */
+    __data_buffer = new ArrayBuffer(INITIAL_CAPACITY * ELEMENT_WORD_COUNT * 4);
 
-        /**
-         * Root node of the hierarchy
-         * @type {number}
-         * @private
-         */
-        this.__root = NULL_NODE;
-    }
+    /**
+     *
+     * @type {Float32Array}
+     * @private
+     */
+    __data_float32 = new Float32Array(this.__data_buffer);
+
+    /**
+     *
+     * @type {Uint32Array}
+     * @private
+     */
+    __data_uint32 = new Uint32Array(this.__data_buffer);
+
+    /**
+     * How many nodes are currently reserved, this will grow automatically through {@link #allocate_node} method usage
+     * @type {number}
+     * @private
+     */
+    __capacity = INITIAL_CAPACITY;
+
+    /**
+     * Number of used nodes. These are either live nodes, or node sitting in the {@link #__free} pool
+     * @type {number}
+     * @private
+     */
+    __size = 0;
+
+    /**
+     * Indices of released nodes. Nodes are pulled from here first if available, before the whole tree gets resized
+     * @type {number[]}
+     * @private
+     */
+    __free = [];
+
+    /**
+     * Pointer into __free array that's used as a stack, so this pointer represents top of the stack
+     * @type {number}
+     * @private
+     */
+    __free_pointer = 0;
+
+    /**
+     * Root node of the hierarchy
+     * @type {number}
+     * @private
+     */
+    __root = NULL_NODE;
 
     /**
      *

package/src/core/bvh2/bvh3/ExplicitBinaryBoundingVolumeHierarchy.spec.js

@@ -248,3 +248,57 @@ test("swap two detached nodes", () => {
     expect(bvh.node_get_user_data(a)).toBe(11);
     expect(bvh.node_get_user_data(b)).toBe(7);
 });
+
+test("setting capacity", () => {
+    const bvh = new ExplicitBinaryBoundingVolumeHierarchy();
+
+    bvh.node_capacity = 3;
+
+    expect(bvh.node_capacity).toEqual(3);
+
+    bvh.node_capacity = 3;
+
+    expect(bvh.node_capacity).toEqual(3);
+
+    bvh.node_capacity = 0;
+
+    expect(bvh.node_capacity).toEqual(0);
+
+    bvh.allocate_node();
+
+    bvh.node_capacity = 3;
+
+    expect(bvh.node_capacity).toEqual(3);
+
+    bvh.node_capacity = 1;
+
+    expect(bvh.node_capacity).toEqual(1);
+
+    expect(() => bvh.node_capacity = 0).toThrow();
+});
+
+test("move leaf node", () => {
+    const bvh = new ExplicitBinaryBoundingVolumeHierarchy();
+
+    const a = bvh.allocate_node();
+    const b = bvh.allocate_node();
+
+    bvh.node_set_aabb(a, [-1.1, -1.2, -1.3, 2.1, 2.2, 2.3]);
+    bvh.node_set_aabb(b, [3.1, 3.2, 3.2, 5.1, 5.2, 5.2]);
+
+    bvh.insert_leaf(a);
+    bvh.insert_leaf(b);
+
+    // convert to float32 and back to account for rounding errors when checking results
+    const a_new_bounds = Array.from(new Float32Array([
+        7.1, 7.2, 7.3,
+        11.1, 11.2, 11.3
+    ]));
+
+    bvh.node_move_aabb(a, a_new_bounds);
+
+    const actual_bounds = [];
+    bvh.node_get_aabb(a, actual_bounds);
+
+    expect(actual_bounds).toEqual(a_new_bounds);
+});

package/src/core/bvh2/bvh3/ebvh_build_for_geometry_morton.js

@@ -1,4 +1,4 @@
-import { AABB3 } from "../aabb3/AABB3.js";
+import { AABB3 } from "../../geom/3d/aabb/AABB3.js";
 import { aabb3_from_v3_array } from "../../geom/3d/aabb/aabb3_from_v3_array.js";
 import morton from "../../geom/3d/morton/Morton.js";
 import { arrayQuickSort } from "../../collection/array/arrayQuickSort.js";
@@ -37,14 +37,14 @@ export function ebvh_build_for_geometry_morton(bvh, index_array, position_array)
     // allocate nodes
     const tri_count = index_array.length / 3;
     const node_leaf_count = tri_count;
-    const node_bin_count = Math.ceil(node_leaf_count / 2) * 2 - 1;
+    const node_bin_count = max2(0, node_leaf_count - 1);
 
     const node_total_count = node_leaf_count + node_bin_count;
 
     const nodes = new Uint32Array(node_total_count);
 
     // skip allocation calls, allocate exactly as many nodes as we need
-    bvh.__set_capacity(node_total_count);
+    bvh.node_capacity = node_total_count;
     bvh.__size = node_total_count;
 
     for (let i = 0; i < node_total_count; i++) {

package/src/core/bvh2/bvh3/ebvh_build_for_geometry_morton.spec.js

@@ -0,0 +1,60 @@
+import { ebvh_build_for_geometry_morton } from "./ebvh_build_for_geometry_morton.js";
+import { ExplicitBinaryBoundingVolumeHierarchy, NULL_NODE } from "./ExplicitBinaryBoundingVolumeHierarchy.js";
+
+test("sanity check with 1 triangle", () => {
+
+    const bvh = new ExplicitBinaryBoundingVolumeHierarchy();
+
+    ebvh_build_for_geometry_morton(bvh, [0, 1, 2], [
+        0, 1, 3,
+        13, 17, 19,
+        5, 7, 11
+    ]);
+
+    expect(bvh.root).not.toEqual(NULL_NODE);
+
+    const actual_bounds = [];
+    bvh.node_get_aabb(bvh.root, actual_bounds);
+
+    expect(actual_bounds).toEqual(
+        Array.from(new Float32Array([
+            0, 1, 3,
+            13, 17, 19
+        ]))
+    );
+
+    // check that first and only node has out triangle index stored
+    expect(bvh.node_is_leaf(bvh.root)).toEqual(true);
+    expect(bvh.node_get_user_data(bvh.root)).toEqual(0);
+});
+
+test("sanity check with 2 triangles", () => {
+    const bvh = new ExplicitBinaryBoundingVolumeHierarchy();
+
+    ebvh_build_for_geometry_morton(
+        bvh,
+        [
+            0, 0, 0,
+            1, 1, 1
+        ],
+        [
+            0, 1, 3,
+            5, 7, 11
+        ]
+    );
+
+    expect(bvh.root).not.toEqual(NULL_NODE);
+
+    const actual_bounds = [];
+    bvh.node_get_aabb(bvh.root, actual_bounds);
+
+    expect(actual_bounds).toEqual(
+        Array.from(new Float32Array([
+            0, 1, 3,
+            5, 7, 11
+        ]))
+    );
+
+    // check that first and only node has out triangle index stored
+    expect(bvh.node_is_leaf(bvh.root)).toEqual(false);
+});

package/src/core/bvh2/visual/convert_bvh_to_dot_format_string.js

@@ -1,4 +1,4 @@
-import { convertGraphToDotString } from "../../graph/convertGraphToDotString.js";
+import { convert_graph_to_dot_string } from "../../graph/convert_graph_to_dot_string.js";
 import { bvh_traverse_pre_order_using_stack } from "../traversal/bvh_traverse_pre_order_using_stack.js";
 import { Graph } from "../../graph/v2/Graph.js";
 import { Edge, EdgeDirectionType } from "../../graph/Edge.js";
@@ -46,5 +46,5 @@ export function bvh_to_graph(bvh) {
  */
 export function convert_bvh_to_dot_format_string(bvh) {
     const graph = bvh_to_graph(bvh);
-    return convertGraphToDotString({ graph: graph });
+    return convert_graph_to_dot_string({ graph: graph });
 }

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

@@ -33,6 +33,8 @@ export class Cache<K, V> {
 
     remove(k: K): boolean
 
+    silentRemove(k: K): boolean
+
     evictOne(): boolean
 
     clear(): void
@@ -40,4 +42,6 @@ export class Cache<K, V> {
     drop(): void
 
     getOrCompute(key: K, compute: (key: K) => V, compute_context?: any): V
+
+    recomputeWeight(): void
 }

package/src/core/cache/Cache.js

@@ -5,9 +5,10 @@ import { returnOne, returnZero, strictEquals } from "../function/Functions.js";
 import { CacheElement } from "./CacheElement.js";
 import { collectIteratorValueToArray } from "../collection/collectIteratorValueToArray.js";
 
+// TODO validate hashes of held elements to keep them up to date. Keys are assumed to be immutable, but this assumption may be broken by users
+
 /**
  * Hash-based cache, uses LRU (least-recently-used) eviction policy
- * TODO validate hashes of held elements to keep them up to date. Keys are assumed to be immutable, but this assumption may be broken by users
  * @template Key, Value
  * @extends Map<Key,Value>
  */
@@ -142,7 +143,7 @@ export class Cache {
     }
 
     /**
-     *
+     * Number of elements stored in cache
      * @returns {number}
      */
     size() {
@@ -150,7 +151,7 @@ export class Cache {
     }
 
     /**
-     *
+     * Will cause evictions if current weight is smaller than what we're setting
      * @param {number} value
      */
     setMaxWeight(value) {
@@ -163,6 +164,11 @@ export class Cache {
         this.evictUntilWeight(this.maxWeight);
     }
 
+    /**
+     * Forces weight to be recomputed for all elements stored in the cache
+     * Useful when values are mutated without re-insertion.
+     * In general - prefer to treat values as immutable
+     */
     recomputeWeight() {
         let result = 0;
 
@@ -175,18 +181,7 @@ export class Cache {
     }
 
     /**
-     *
-     * @param {function(Value):number} weigher
-     */
-    setValueWeigher(weigher) {
-        this.valueWeigher = weigher;
-        //recompute weight
-        this.recomputeWeight();
-        this.evictUntilWeight(this.maxWeight);
-    }
-
-    /**
-     *
+     * @private
      * @param {Key} key
      * @param {Value} value
      * @returns {number}
@@ -223,7 +218,14 @@ export class Cache {
         }
     }
 
+    /**
+     * Drop data until weight reduces lower or equal to requested weight
+     * @param {number} targetWeight
+     */
     evictUntilWeight(targetWeight) {
+        assert.isNumber(targetWeight, 'targetWeight');
+        assert.notNaN(targetWeight, 'targetWeight');
+
         const target = Math.max(targetWeight, 0);
 
         while (this.weight > target) {
@@ -402,7 +404,7 @@ export class Cache {
     }
 
     /**
-     * Remove without triggering {@link #removeListener}
+     * 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
@@ -466,7 +468,19 @@ export class Cache {
 }
 
 /**
- * Shortcut for "map" compliance
- * @type {Cache.put}
+ * Shortcut for "Map" class spec compliance
+ * @readonly
  */
 Cache.prototype.set = Cache.prototype.put;
+
+/**
+ * Shortcut for "Map" class spec compliance
+ * @readonly
+ */
+Cache.prototype.delete = Cache.prototype.remove;
+
+/**
+ * Shortcut for "Map" class spec compliance
+ * @readonly
+ */
+Cache.prototype.has = Cache.prototype.contains;