@woosh/meep-engine 2.128.1 → 2.128.3

package/README.md

@@ -13,11 +13,33 @@ To help get you started, various samples are provided under `/samples` folder. F
 
 ## Quality
 
-Meep is covered by 2,790 handwritten unit tests
+### Testing
+Meep is covered by 2,801 handwritten unit tests, reaching 90%+ coverage in `core` and 40%+ coverage total.
 
 The aim is to [ensure quality](https://about.codecov.io/blog/the-case-against-100-code-coverage/). As a result, the tests are written to cover complex code first and to exhaustively validate critical algorithms.
 Most of the test code is significantly larger than the code that is being tested.
 
+### Assertions
+Meep is covered by 3,162 asserts. [Assertions](https://en.wikipedia.org/wiki/Assertion_(software_development)) provide very extensive pre- and post-condition checks throughout the engine.
+Asserts are intended primarily for development builds.
+To remove asserts in Vite builds, you can use `@rollup/plugin-strip` package like so:
+
+```js
+import strip from '@rollup/plugin-strip';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+    plugins: [{
+        // this will remove all assert statements from the production build
+        ...strip(),
+        apply: 'build'
+    }],
+    // ... the rest of the config ...
+});
+```
+
+Assertion package can be found under `/src/core/assert.js`.
+
 ## Package Size
 
 Meep is infinitely tree-shakable, you only package what you use.

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.1",
+  "version": "2.128.3",
   "main": "build/meep.module.js",
   "module": "build/meep.module.js",
   "exports": {

package/src/core/assert.d.ts

@@ -120,8 +120,8 @@ export namespace assert {
      */
     export function notNaN(value: number, name?: string): void;
     /**
-     * Is given number finite?
-     * Will trigger if number is infinite, i.e. fails the `Number.isFinite` test
+     * Is the given number finite?
+     * Will trigger if the number is infinite, i.e. fails the `Number.isFinite` test
      * @param {number} value
      * @param {string} [name] optional name for the value being checked
      */

package/src/core/assert.js

@@ -447,8 +447,8 @@ assert.notNaN = function (value, name = "value") {
 };
 
 /**
- * Is given number finite?
- * Will trigger if number is infinite, i.e. fails the `Number.isFinite` test
+ * Is the given number finite?
+ * Will trigger if the number is infinite, i.e. fails the `Number.isFinite` test
  * @param {number} value
  * @param {string} [name] optional name for the value being checked
  */

package/src/core/binary/allocator/OffsetAllocator.d.ts

@@ -81,8 +81,17 @@ export class OffsetAllocator {
      */
     allocate(size: number): Allocation;
     /**
+     * Direct method of releasing an allocation.
+     * Allows the user to skip holding an object reference in memory.
+     * {@link node_index} can be read from {@link Allocation.metadata}
      *
+     * @param {number} node_index
+     * @see free
+     */
+    free_node(node_index: number): void;
+    /**
      * @param {Allocation} allocation
+     * @see free_node
      */
     free(allocation: Allocation): void;
     /**

package/src/core/binary/allocator/OffsetAllocator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OffsetAllocator.d.ts","sourceRoot":"","sources":["../../../../../src/core/binary/allocator/OffsetAllocator.js"],"names":[],"mappings":"AAaA,4CAA6C;AAmF7C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAwDI;;;;OAIG;IACH,kBAHW,MAAM,cACN,MAAM,EAYhB;IAtED;;;;OAIG;IACH,MAFU,MAAM,CAEP;IAET;;;;OAIG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,UAFU,UAAU,CAEoB;IAExC;;;OAGG;IACH,YAFU,WAAW,CAEuB;IAE5C;;;OAGG;IACH,OAFU,aAAa,CAEmB;IAE1C;;OAEG;IACH,WAFU,WAAW,CAEX;IAEV;;;OAGG;IACH,YAFU,MAAM,CAED;IAmBf;;;;OAIG;IACH,eAHW,MAAM,GACJ,UAAU,CAkGtB;IAED;;;OAGG;IACH,iBAFW,UAAU,QAsFpB;IAqID;;OAEG;IACH,cA4BC;IAED;;;OAGG;IACH,iBAFY,aAAa,CA2BxB;;CACJ;8BAjkB6B,yCAAyC;AAgDvE;IAII;;;;;OAKG;IACH,oBAJW,MAAM,YACN,MAAM,GACL,UAAU,CASrB;IAhBD,eAA4B;IAC5B,iBAA8B;CAgBjC;AAoBD;IACI,uBAAkB;IAClB,0BAAqB;CACxB"}
+{"version":3,"file":"OffsetAllocator.d.ts","sourceRoot":"","sources":["../../../../../src/core/binary/allocator/OffsetAllocator.js"],"names":[],"mappings":"AAaA,4CAA6C;AAmF7C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAwDI;;;;OAIG;IACH,kBAHW,MAAM,cACN,MAAM,EAYhB;IAtED;;;;OAIG;IACH,MAFU,MAAM,CAEP;IAET;;;;OAIG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,UAFU,UAAU,CAEoB;IAExC;;;OAGG;IACH,YAFU,WAAW,CAEuB;IAE5C;;;OAGG;IACH,OAFU,aAAa,CAEmB;IAE1C;;OAEG;IACH,WAFU,WAAW,CAEX;IAEV;;;OAGG;IACH,YAFU,MAAM,CAED;IAmBf;;;;OAIG;IACH,eAHW,MAAM,GACJ,UAAU,CAkGtB;IAED;;;;;;;OAOG;IACH,sBAHW,MAAM,QAqFhB;IAED;;;OAGG;IACH,iBAHW,UAAU,QAUpB;IAqID;;OAEG;IACH,cA4BC;IAED;;;OAGG;IACH,iBAFY,aAAa,CA2BxB;;CACJ;8BAhlB6B,yCAAyC;AAgDvE;IAII;;;;;OAKG;IACH,oBAJW,MAAM,YACN,MAAM,GACL,UAAU,CASrB;IAhBD,eAA4B;IAC5B,iBAA8B;CAgBjC;AAoBD;IACI,uBAAkB;IAClB,0BAAqB;CACxB"}

package/src/core/binary/allocator/OffsetAllocator.js

@@ -293,14 +293,16 @@ export class OffsetAllocator {
     }
 
     /**
+     * Direct method of releasing an allocation.
+     * Allows the user to skip holding an object reference in memory.
+     * {@link node_index} can be read from {@link Allocation.metadata}
      *
-     * @param {Allocation} allocation
+     * @param {number} node_index
+     * @see free
      */
-    free(allocation) {
-        assert.notEqual(allocation.metadata, ALLOCATOR_NO_SPACE, 'Invalid allocation');
-        // if (!m_nodes) return;
-
-        const node_index = allocation.metadata;
+    free_node(node_index) {
+        assert.isNonNegativeInteger(node_index, 'node_index');
+        assert.notEqual(node_index, ALLOCATOR_NO_SPACE, 'Invalid allocation');
 
         const nodes = this.nodes;
         const node_flags = nodes.readCellValue(node_index, NODE_FIELD_FLAGS);
@@ -382,6 +384,19 @@ export class OffsetAllocator {
         }
     }
 
+    /**
+     * @param {Allocation} allocation
+     * @see free_node
+     */
+    free(allocation) {
+        assert.notEqual(allocation.metadata, ALLOCATOR_NO_SPACE, 'Invalid allocation');
+        // if (!m_nodes) return;
+
+        const node_index = allocation.metadata;
+
+        this.free_node(node_index);
+    }
+
     /**
      *
      * @param {number} size

package/src/core/bvh2/bvh3/query/BVHQueryIntersectsSphere.d.ts

@@ -1,12 +1,12 @@
 export class BVHQueryIntersectsSphere extends BVHQuery {
     /**
      *
-     * @param {number[]|ArrayLike<number>} sphere
+     * @param {number[]|ArrayLike<number>} sphere (x,y,z,radius)
      * @returns {BVHQueryIntersectsRay}
      */
     static from(sphere: number[] | ArrayLike<number>): BVHQueryIntersectsRay;
     /**
-     *
+     * [x,y,z,radius]
      * @type {number[]}
      */
     sphere: number[];

package/src/core/bvh2/bvh3/query/BVHQueryIntersectsSphere.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BVHQueryIntersectsSphere.d.ts","sourceRoot":"","sources":["../../../../../../src/core/bvh2/bvh3/query/BVHQueryIntersectsSphere.js"],"names":[],"mappings":"AAKA;IAQI;;;;OAIG;IACH,oBAHW,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,yBASpC;IAjBD;;;OAGG;IACH,QAFU,MAAM,EAAE,CAEN;IAeZ,wCASC;CACJ;yBAnCwB,eAAe"}
+{"version":3,"file":"BVHQueryIntersectsSphere.d.ts","sourceRoot":"","sources":["../../../../../../src/core/bvh2/bvh3/query/BVHQueryIntersectsSphere.js"],"names":[],"mappings":"AAUA;IAQI;;;;OAIG;IACH,oBAHW,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,yBAWpC;IAnBD;;;OAGG;IACH,QAFU,MAAM,EAAE,CAEC;IAiBnB,wCASC;CACJ;yBAzCwB,eAAe"}

package/src/core/bvh2/bvh3/query/BVHQueryIntersectsSphere.js

@@ -1,22 +1,29 @@
+import { assert } from "../../../assert.js";
 import { aabb3_array_intersects_sphere_array } from "../../../geom/3d/aabb/aabb3_array_intersects_sphere_array.js";
 import { BVHQuery } from "./BVHQuery.js";
 
-const scratch_aabb = [];
+/**
+ * We read node bounds here
+ * @type {Float32Array}
+ */
+const scratch_aabb = new Float32Array(6);
 
 export class BVHQueryIntersectsSphere extends BVHQuery {
 
     /**
-     *
+     * [x,y,z,radius]
      * @type {number[]}
      */
-    sphere = [];
+    sphere = [0,0,0,0];
 
     /**
      *
-     * @param {number[]|ArrayLike<number>} sphere
+     * @param {number[]|ArrayLike<number>} sphere (x,y,z,radius)
      * @returns {BVHQueryIntersectsRay}
      */
     static from(sphere) {
+        assert.isArrayLike(sphere, 'sphere');
+
         const r = new BVHQueryIntersectsSphere();
 
         r.sphere = sphere;

package/src/engine/ecs/EntityManager.d.ts

@@ -9,7 +9,29 @@ export namespace EntityManagerState {
 }
 /**
  * Brings together {@link System}s and an {@link EntityComponentDataset}
- * Main entry point into the simulation process
+ * Main entry point into the simulation process.
+ *
+ * @example
+ *      const em = new EntityManager()
+ *
+ *      em.addSystem(new MySystem())
+ *      em.addSystem(new MyOtherSystem())
+ *
+ *      em.attachDataset(new EntityComponentDataset())
+ *
+ *      em.startup();
+ *
+ *      // ..
+ *
+ *      em.simulate(0.016); // advance simulation forward by 16ms
+ *
+ *      // ..
+ *
+ *      em.shutdown();
+ *
+ *      // ..
+ *
+ *      em.detachDataset();
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2025
@@ -179,11 +201,11 @@ export class EntityManager {
      */
     promiseSystem(systemClass: Class): Promise<System<any, any, any, any, any>>;
     /**
-     * @param {Class} systemClass
+     * @param {Class} SystemClass
      * @param {SystemState} state
      * @returns {Promise.<System>}
      */
-    promiseSystemInState(systemClass: Class, state: SystemState): Promise<System<any, any, any, any, any>>;
+    promiseSystemInState(SystemClass: Class, state: SystemState): Promise<System<any, any, any, any, any>>;
     /**
      * This method is asynchronous by nature, it will not be done until each system has finished its shutdown
      * Make sure to use callback to be notified when the shutdown has completed

package/src/engine/ecs/EntityManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EntityManager.d.ts","sourceRoot":"","sources":["../../../../src/engine/ecs/EntityManager.js"],"names":[],"mappings":"iCAgBU,MAAM;;;;;;;;;AAiBhB;;;;;;GAMG;AACH;IAEI;;;;OAIG;IACH,kBAFU,iCAAQ,CAEL;IAEb;;;;;;OAMG;IACH,uCAA2B;IAE3B;;;;;OAKG;IACH,iCAA4B;IAE5B;;OAEG;IACH;;;QAGI;;WAEG;qBADO,uCAAc;;MAI1B;IAEF;;;OAGG;IACH,OAFU,kBAAkB,CAEO;IAEnC;;;;;;OAMG;IACH,gDAA2C;IAE3C;;;;;;;;;OASG;IACH,qBAFU,MAAM,CAEqB;IAErC;;;;;OAKG;IACH,wCAFU,MAAM,CAE4B;IAE5C;;;;OAIG;IACH,SAFU,sBAAsB,CAEjB;IAEf;;;;;OAKG;IACH,uCAAsC;IAEtC;;;OAGG;IACH,6BAmFC;IAED;;;OAGG;IACH,uBAFa,OAAO,CAuBnB;IAED;;;;;OAKG;IACH,uBAJW,sBAAsB,QA4ChC;IAGD;;;OAGG;IACH,sBA2BC;IAED;;;;OAIG;IACH,qCAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,6CAgBC;IAED;;;;;OAKG;IACH,wCAHW,MAAM,GACJ,IAAI,aAAS,CAiBzB;IAGD;;;OAGG;IACH,oBAFW,MAAM,QAoEhB;IAED;;;;;OAKG;IACH,iEA6DC;IAED;;;;OAIG;IACH,uDAFa,QAAQ,OAAO,CAAC,CA2C5B;IAED;;;;;OAKG;IACH,mBAmCC;IAED;;;;;OAKG;IACH,oBAqFC;IAED;;;;;OAKG;IACH,kEAyEC;IAED;;;;OAIG;IACH,mCAFa,wCAAgB,CA0B5B;IAED;;;;OAIG;IACH,8DAFa,wCAAgB,CAsB5B;IAED;;;;;OAKG;IACH,mEAoFC;IAGL;;OAEG;IACH,yBAxrBe,sBAAsB,UAwrBA;IACrC;;OAEG;IACH,0BAAqC;CATpC;uBAh6BmC,aAAa;mBAR9B,oCAAoC;uCAMhB,6BAA6B"}
+{"version":3,"file":"EntityManager.d.ts","sourceRoot":"","sources":["../../../../src/engine/ecs/EntityManager.js"],"names":[],"mappings":"iCAgBU,MAAM;;;;;;;;;AAiBhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;IAEI;;;;OAIG;IACH,kBAFU,iCAAQ,CAEL;IAEb;;;;;;OAMG;IACH,uCAA2B;IAE3B;;;;;OAKG;IACH,iCAA4B;IAE5B;;OAEG;IACH;;;QAGI;;WAEG;qBADO,uCAAc;;MAI1B;IAEF;;;OAGG;IACH,OAFU,kBAAkB,CAEO;IAEnC;;;;;;OAMG;IACH,gDAA2C;IAE3C;;;;;;;;;OASG;IACH,qBAFU,MAAM,CAEqB;IAErC;;;;;OAKG;IACH,wCAFU,MAAM,CAE4B;IAE5C;;;;OAIG;IACH,SAFU,sBAAsB,CAEjB;IAEf;;;;;OAKG;IACH,uCAAsC;IAEtC;;;OAGG;IACH,6BAmFC;IAED;;;OAGG;IACH,uBAFa,OAAO,CAuBnB;IAED;;;;;OAKG;IACH,uBAJW,sBAAsB,QA4ChC;IAGD;;;OAGG;IACH,sBA2BC;IAED;;;;OAIG;IACH,qCAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,6CAgBC;IAED;;;;;OAKG;IACH,wCAHW,MAAM,GACJ,IAAI,aAAS,CAiBzB;IAGD;;;OAGG;IACH,oBAFW,MAAM,QAoEhB;IAED;;;;;OAKG;IACH,iEA6DC;IAED;;;;OAIG;IACH,uDAFa,QAAQ,OAAO,CAAC,CA2C5B;IAED;;;;;OAKG;IACH,mBAmCC;IAED;;;;;OAKG;IACH,oBAqFC;IAED;;;;;OAKG;IACH,kEAyEC;IAED;;;;OAIG;IACH,mCAFa,wCAAgB,CA0B5B;IAED;;;;OAIG;IACH,8DAFa,wCAAgB,CA0B5B;IAED;;;;;OAKG;IACH,mEAoFC;IAGL;;OAEG;IACH,yBA5rBe,sBAAsB,UA4rBA;IACrC;;OAEG;IACH,0BAAqC;CATpC;uBA17BmC,aAAa;mBAR9B,oCAAoC;uCAMhB,6BAA6B"}

package/src/engine/ecs/EntityManager.js

@@ -33,7 +33,29 @@ const DEFAULT_SYSTEM_STARTUP_TIMEOUT_CHECK = 5;
 
 /**
  * Brings together {@link System}s and an {@link EntityComponentDataset}
- * Main entry point into the simulation process
+ * Main entry point into the simulation process.
+ *
+ * @example
+ *      const em = new EntityManager()
+ *
+ *      em.addSystem(new MySystem())
+ *      em.addSystem(new MyOtherSystem())
+ *
+ *      em.attachDataset(new EntityComponentDataset())
+ *
+ *      em.startup();
+ *
+ *      // ..
+ *
+ *      em.simulate(0.016); // advance simulation forward by 16ms
+ *
+ *      // ..
+ *
+ *      em.shutdown();
+ *
+ *      // ..
+ *
+ *      em.detachDataset();
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2025
@@ -819,16 +841,20 @@ export class EntityManager {
     }
 
     /**
-     * @param {Class} systemClass
+     * @param {Class} SystemClass
      * @param {SystemState} state
      * @returns {Promise.<System>}
      */
-    promiseSystemInState(systemClass, state) {
+    promiseSystemInState(SystemClass, state) {
+
+        assert.defined(SystemClass, 'SystemClass');
+        assert.enum(state, SystemState, 'state');
+
         const em = this;
 
         return new Promise(function (resolve, reject) {
 
-            const pSystem = em.promiseSystem(systemClass);
+            const pSystem = em.promiseSystem(SystemClass);
 
             pSystem.then(function (system) {
                 function tryProcessSystem() {