@woosh/meep-engine 2.59.0 → 2.59.2

package/src/core/geom/Vector3.spec.js

@@ -1,34 +1,34 @@
+import {MATRIX_4_IDENTITY} from "./3d/matrix/MATRIX_4_IDENTITY.js";
+import {v3_slerp} from "./vec3/v3_slerp.js";
 import Vector3 from "./Vector3.js";
-import { v3_slerp } from "./vec3/v3_slerp.js";
-import { MATRIX_4_IDENTITY } from "./3d/matrix/MATRIX_4_IDENTITY.js";
 
 test('slerp', () => {
 
     const v = new Vector3();
 
     v3_slerp(v, 0, 0, 0, 0, 0, 0, 0);
-    expect(v.toJSON()).toEqual({ x: 0, y: 0, z: 0 });
+    expect(v.toJSON()).toEqual({x: 0, y: 0, z: 0});
 
     v3_slerp(v, 0, 0, 0, 0, 0, 0, 1);
-    expect(v.toJSON()).toEqual({ x: 0, y: 0, z: 0 });
+    expect(v.toJSON()).toEqual({x: 0, y: 0, z: 0});
 
     v3_slerp(v, 1, 1, 1, 1, 1, 1, 0);
-    expect(v.toJSON()).toEqual({ x: 1, y: 1, z: 1 });
+    expect(v.toJSON()).toEqual({x: 1, y: 1, z: 1});
 
     v3_slerp(v, 1, 1, 1, 1, 1, 1, 1);
-    expect(v.toJSON()).toEqual({ x: 1, y: 1, z: 1 });
+    expect(v.toJSON()).toEqual({x: 1, y: 1, z: 1});
 
     v3_slerp(v, -1, -1, -1, -1, -1, -1, 0);
-    expect(v.toJSON()).toEqual({ x: -1, y: -1, z: -1 });
+    expect(v.toJSON()).toEqual({x: -1, y: -1, z: -1});
 
     v3_slerp(v, -1, -1, -1, -1, -1, -1, 1);
-    expect(v.toJSON()).toEqual({ x: -1, y: -1, z: -1 });
+    expect(v.toJSON()).toEqual({x: -1, y: -1, z: -1});
 
     v3_slerp(v, 1, 1, 1, -1, -1, -1, 0);
-    expect(v.toJSON()).toEqual({ x: 1, y: 1, z: 1 });
+    expect(v.toJSON()).toEqual({x: 1, y: 1, z: 1});
 
     v3_slerp(v, 1, 1, 1, -1, -1, -1, 1);
-    expect(v.toJSON()).toEqual({ x: -1, y: -1, z: -1 });
+    expect(v.toJSON()).toEqual({x: -1, y: -1, z: -1});
 
 
     v3_slerp(v, 1, 0, 0, 0, 1, 0, 0.5);
@@ -123,10 +123,10 @@ test("iterator symbol", () => {
 
     const iterator = v[Symbol.iterator]();
 
-    expect(iterator.next()).toEqual({ value: 5, done: false })
-    expect(iterator.next()).toEqual({ value: 7, done: false })
-    expect(iterator.next()).toEqual({ value: 11, done: false })
-    expect(iterator.next()).toEqual({ done: true })
+    expect(iterator.next()).toEqual({value: 5, done: false})
+    expect(iterator.next()).toEqual({value: 7, done: false})
+    expect(iterator.next()).toEqual({value: 11, done: false})
+    expect(iterator.next()).toEqual({done: true})
 
 });
 
@@ -172,3 +172,13 @@ test("applyMatrix with identity", () => {
     expect(v.z).toEqual(11);
 
 });
+
+test("setFromSphericalCoords", () => {
+    const v3 = new Vector3();
+
+    v3.setFromSphericalCoords(0, 0, 0);
+
+    expect(v3.x).not.toBeNaN();
+    expect(v3.y).not.toBeNaN();
+    expect(v3.z).not.toBeNaN();
+});

package/src/engine/EngineHarness.js

@@ -288,7 +288,7 @@ export class EngineHarness {
             autoClip: cameraAutoClip
         });
 
-        const cameraEntity = camera.entity;
+        const cameraEntity = camera.id;
 
         if (enableTerrain) {
             await EngineHarness.buildTerrain({

package/src/engine/control/ControlContext.js

@@ -125,7 +125,7 @@ export class ControlContext {
 
         for (const e of this.entities) {
             if (e.getFlag(EntityFlags.Built)) {
-                throw new IllegalStateException(`Entity ${e.entity} is already built, this violates pre-condition of control context`);
+                throw new IllegalStateException(`Entity ${e.id} is already built, this violates pre-condition of control context`);
             }
 
             e.build(this.ecd)

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

@@ -36,4 +36,6 @@ export default class Entity {
     getFlag(flag: number): boolean
 
     setFlag(flag: number, value: number): void
+
+    readonly isEntity:boolean
 }

package/src/engine/ecs/Entity.js

@@ -1,8 +1,8 @@
 import Signal from "../../core/events/signal/Signal.js";
-import { assert } from "../../core/assert.js";
-import { EventType } from "./EntityManager.js";
-import { isDefined } from "../../core/process/matcher/Matchers.js";
-import { EntityFlags } from "./EntityFlags.js";
+import {assert} from "../../core/assert.js";
+import {EventType} from "./EntityManager.js";
+import {isDefined} from "../../core/process/matcher/Matchers.js";
+import {EntityFlags} from "./EntityFlags.js";
 
 /**
  * Set of default flags
@@ -20,9 +20,10 @@ const DEFAULT_FLAGS =
 class Entity {
 
     /**
+     * When entity is live - this is the entity ID inside associated `EntityComponentDataset`, when the entity is not live - it's set to -1
      * @type {number}
      */
-    entity = void 0;
+    id = -1;
 
     /**
      * Generation is a unique identifier coming from the dataset
@@ -32,16 +33,17 @@ class Entity {
     generation = -1;
 
     /**
-     *
+     * Components associated with the entity
+     * @readonly
      * @type {Array}
      */
-    element = [];
+    components = [];
 
     /**
      *
      * @type {{name:string,listener:(function|Function), context:*}[]}
      */
-    deferredListeners = [];
+    #deferredListeners = [];
 
     /**
      *
@@ -56,7 +58,7 @@ class Entity {
     flags = DEFAULT_FLAGS;
 
     /**
-     *
+     * Arbitrary metadata, add anything you want here
      * @type {Object}
      */
     properties = {};
@@ -72,7 +74,7 @@ class Entity {
      * Handles event when entity is removed without invoking {@link #destroy} method
      * @private
      */
-    __handleEntityDestroyed() {
+    #handleEntityDestroyed() {
         this.clearFlag(EntityFlags.Built);
     }
 
@@ -115,7 +117,7 @@ class Entity {
      * Remove all components from the entity
      */
     removeAllComponents() {
-        const elements = this.element;
+        const elements = this.components;
         const n = elements.length;
         for (let i = n - 1; i >= 0; i--) {
             const component = elements[i];
@@ -129,7 +131,7 @@ class Entity {
      * @return {number}
      */
     get count() {
-        return this.element.length;
+        return this.components.length;
     }
 
     /**
@@ -139,16 +141,16 @@ class Entity {
      */
     add(componentInstance) {
         if (componentInstance === undefined) {
-            throw new Error(`Can not add ${componentInstance} to EntityBuilder`);
+            throw new Error(`Can not add ${componentInstance} to Entity`);
         }
 
         assert.notOk(this.hasComponent(Object.getPrototypeOf(componentInstance).constructor), 'Component of this type already exists');
 
-        this.element.push(componentInstance);
+        this.components.push(componentInstance);
 
         if (this.getFlag(EntityFlags.Built)) {
             //already built, add component to entity
-            this.dataset.addComponentToEntity(this.entity, componentInstance);
+            this.dataset.addComponentToEntity(this.id, componentInstance);
         }
 
         return this;
@@ -169,7 +171,7 @@ class Entity {
      * @returns {T|null} component of specified class
      */
     getComponent(klass) {
-        const elements = this.element;
+        const elements = this.components;
         const element_count = elements.length;
 
         for (let i = 0; i < element_count; i++) {
@@ -203,7 +205,7 @@ class Entity {
      * @returns {*|null}
      */
     removeComponent(klass) {
-        const elements = this.element;
+        const elements = this.components;
         const n = elements.length;
 
         for (let i = 0; i < n; i++) {
@@ -215,7 +217,7 @@ class Entity {
                 //see if entity is built
                 if (this.getFlag(EntityFlags.Built)) {
 
-                    this.dataset.removeComponentFromEntity(this.entity, klass);
+                    this.dataset.removeComponentFromEntity(this.id, klass);
 
                 }
 
@@ -233,7 +235,7 @@ class Entity {
      */
     sendEvent(eventName, event) {
         if (this.getFlag(EntityFlags.Built)) {
-            this.dataset.sendEvent(this.entity, eventName, event);
+            this.dataset.sendEvent(this.id, eventName, event);
         } else {
             console.warn("Entity doesn't exist. Event " + eventName + ":" + event + " was not sent.")
         }
@@ -269,9 +271,9 @@ class Entity {
      */
     addEventListener(eventName, listener, context) {
         if (this.getFlag(EntityFlags.Built)) {
-            this.dataset.addEntityEventListener(this.entity, eventName, listener, context);
+            this.dataset.addEntityEventListener(this.id, eventName, listener, context);
         } else {
-            this.deferredListeners.push({
+            this.#deferredListeners.push({
                 name: eventName,
                 listener: listener,
                 context
@@ -289,9 +291,9 @@ class Entity {
      */
     removeEventListener(eventName, listener, context) {
         if (this.getFlag(EntityFlags.Built)) {
-            this.dataset.removeEntityEventListener(this.entity, eventName, listener, context);
+            this.dataset.removeEntityEventListener(this.id, eventName, listener, context);
         } else {
-            const listeners = this.deferredListeners;
+            const listeners = this.#deferredListeners;
 
             for (let i = 0, numListeners = listeners.length; i < numListeners; i++) {
                 const deferredDescriptor = listeners[i];
@@ -320,16 +322,16 @@ class Entity {
         if (this.getFlag(EntityFlags.Built)) {
 
             const dataset = this.dataset;
-            const entity = this.entity;
+            const entity = this.id;
 
             //check that the entity is the same as what we have built
-            //assert.ok(checkExistingComponents(entity, this.element, dataset), `Signature of EntityBuilder does not match existing entity(id=${entity})`);
+            //assert.ok(checkExistingComponents(entity, this.element, dataset), `Signature of Entity does not match existing entity(id=${entity})`);
 
-            dataset.removeEntityEventListener(entity, EventType.EntityRemoved, this.__handleEntityDestroyed, this);
+            dataset.removeEntityEventListener(entity, EventType.EntityRemoved, this.#handleEntityDestroyed, this);
 
             dataset.removeEntity(entity);
 
-            this.entity = void 0;
+            this.id = -1;
 
             this.clearFlag(EntityFlags.Built);
 
@@ -350,18 +352,18 @@ class Entity {
 
         if (
             this.getFlag(EntityFlags.Built)
-            && checkExistingComponents(this.entity, this.element, dataset)
+            && checkExistingComponents(this.id, this.components, dataset)
         ) {
             //already built
-            return this.entity;
+            return this.id;
         }
 
-        const entity = this.entity = dataset.createEntity();
+        const entity = this.id = dataset.createEntity();
         this.dataset = dataset;
 
         let i;
 
-        const listeners = this.deferredListeners;
+        const listeners = this.#deferredListeners;
         const listeners_count = listeners.length;
 
         for (i = 0; i < listeners_count; i++) {
@@ -369,9 +371,9 @@ class Entity {
             dataset.addEntityEventListener(entity, subscription.name, subscription.listener, subscription.context);
         }
         // reset listeners
-        this.deferredListeners.splice(0, listeners_count);
+        this.#deferredListeners.splice(0, listeners_count);
 
-        const element = this.element;
+        const element = this.components;
         const element_count = element.length;
 
         if (this.getFlag(EntityFlags.RegisterComponents)) {
@@ -391,7 +393,7 @@ class Entity {
         this.setFlag(EntityFlags.Built);
 
         if (this.getFlag(EntityFlags.WatchDestruction)) {
-            dataset.addEntityEventListener(entity, EventType.EntityRemoved, this.__handleEntityDestroyed, this);
+            dataset.addEntityEventListener(entity, EventType.EntityRemoved, this.#handleEntityDestroyed, this);
         }
 
         this.on.built.send2(entity, dataset);
@@ -399,7 +401,7 @@ class Entity {
     }
 
     /**
-     *
+     * Extract data about an entity and its components from a dataset
      * @param {number} entity
      * @param {EntityComponentDataset} dataset
      * @returns {Entity}
@@ -412,7 +414,7 @@ class Entity {
             .forEach(r.add, r);
 
         r.setFlag(EntityFlags.Built);
-        r.entity = entity;
+        r.id = entity;
         r.dataset = dataset;
 
         return r;
@@ -420,10 +422,11 @@ class Entity {
 }
 
 /**
+ * Useful for faster alternative to `instanceof` checks
  * @readonly
  * @type {boolean}
  */
-Entity.prototype.isEntityBuilder = true;
+Entity.prototype.isEntity = true;
 
 
 /**

package/src/engine/ecs/Entity.spec.js

@@ -63,7 +63,7 @@ test("'Built' flag is reset when entity is removed without invoking 'destroy' me
     expect(b.getFlag(EntityFlags.Built)).toBe(true);
     expect(b.isBuilt).toBe(true);
 
-    dataset.removeEntity(b.entity);
+    dataset.removeEntity(b.id);
 
     expect(b.getFlag(EntityFlags.Built)).toBe(false);
     expect(b.isBuilt).toBe(false);
@@ -135,7 +135,7 @@ test("adding component to live entity results in component being added to the da
     const component = new DummyComponent();
     entity.add(component);
 
-    expect(ecd.getComponent(entity.entity, DummyComponent)).toBe(component);
+    expect(ecd.getComponent(entity.id, DummyComponent)).toBe(component);
 
 });
 

package/src/engine/ecs/EntityBuilderUtils.js

@@ -2,7 +2,7 @@ import { EventType } from "./EntityManager.js";
 
 /**
  *
- * @param {EntityBuilder[]} builders
+ * @param {Entity[]} builders
  * @returns {Promise}
  */
 export function whenAllEntitiesDestroyed(builders) {
@@ -11,7 +11,7 @@ export function whenAllEntitiesDestroyed(builders) {
 
 /**
  *
- * @param {EntityBuilder} builder
+ * @param {Entity} builder
  * @returns {Promise}
  */
 export function whenEntityDestroyed(builder) {

package/src/engine/ecs/EntityComponentDataset.js

@@ -1,17 +1,17 @@
-import { BitSet } from "../../core/binary/BitSet.js";
-import { assert } from "../../core/assert.js";
+import {BitSet} from "../../core/binary/BitSet.js";
+import {assert} from "../../core/assert.js";
 import Signal, {
     findSignalHandlerIndexByHandle,
     findSignalHandlerIndexByHandleAndContext
 } from "../../core/events/signal/Signal.js";
-import { EventType } from "./EntityManager.js";
-import { SignalHandler } from "../../core/events/signal/SignalHandler.js";
-import { arraySetDiff } from "../../core/collection/array/arraySetDiff.js";
-import { array_shrink_to_size } from "../../core/collection/array/array_shrink_to_size.js";
+import {EventType} from "./EntityManager.js";
+import {SignalHandler} from "../../core/events/signal/SignalHandler.js";
+import {arraySetDiff} from "../../core/collection/array/arraySetDiff.js";
+import {array_shrink_to_size} from "../../core/collection/array/array_shrink_to_size.js";
 
 /**
  *
- * @param {*} entityIndex
+ * @param {number} entityIndex
  * @returns {boolean}
  */
 function validateEntityIndex(entityIndex) {
@@ -20,7 +20,7 @@ function validateEntityIndex(entityIndex) {
 
 /**
  *
- * @param {*} componentIndex
+ * @param {number} componentIndex
  * @returns {boolean}
  */
 function validateComponentIndex(componentIndex) {
@@ -29,7 +29,7 @@ function validateComponentIndex(componentIndex) {
 
 /**
  *
- * @param index
+ * @param {number} index
  * @param {string} name
  * @returns {boolean}
  */
@@ -103,99 +103,101 @@ function buildObserverCallbackArgs(entityIndex, mask, componentIndexMap, compone
 const scratch_array_0 = [];
 const scratch_array_1 = [];
 
+/**
+ * Represents a storage for entities and their associated components
+ * Entities are just integer IDs and components are stored in a virtual table, where each component type has a separate column and each entity is a row in that table
+ * It is valid for entities to have no components or to have every possible component
+ * Generally the entity IDs are compacted, meaning that when an entity is removed - it's ID will be later reused
+ */
 export class EntityComponentDataset {
+
     /**
-     * @class
-     * @constructor
+     * @private
+     * @type {BitSet}
      */
-    constructor() {
-        /**
-         * @private
-         * @type {BitSet}
-         */
-        this.entityOccupancy = new BitSet();
-        /**
-         * @private
-         * @type {BitSet}
-         */
-        this.componentOccupancy = new BitSet();
+    entityOccupancy = new BitSet();
+    /**
+     * @private
+     * @type {BitSet}
+     */
+    componentOccupancy = new BitSet();
 
-        /**
-         * @private
-         * @type {Class[]}
-         */
-        this.componentTypeMap = [];
+    /**
+     * @private
+     * @type {Class[]}
+     */
+    componentTypeMap = [];
 
-        /**
-         * Fast index lookup from a component class
-         * @type {Map<Class, number>}
-         * @private
-         */
-        this.__type_to_index_map = new Map();
+    /**
+     * Fast index lookup from a component class
+     * @type {Map<Class, number>}
+     * @private
+     */
+    __type_to_index_map = new Map();
 
-        /**
-         * How many component types exist for this collection. This is the same as componentMap.length
-         * @private
-         * @type {number}
-         */
-        this.componentTypeCount = 0;
+    /**
+     * How many component types exist for this collection. This is the same as componentMap.length
+     * @private
+     * @type {number}
+     */
+    componentTypeCount = 0;
 
-        /**
-         * @private
-         * @type {Object[][]}
-         */
-        this.components = [];
+    /**
+     * @private
+     * @type {Object[][]}
+     */
+    components = [];
 
-        /**
-         * Current number of entities
-         * @private
-         * @type {number}
-         */
-        this.entityCount = 0;
+    /**
+     * Current number of entities
+     * @private
+     * @type {number}
+     */
+    entityCount = 0;
 
-        /**
-         * A counter that is incremented every time an entity is created
-         * Generation is used to provide an entity with a unique identity
-         * Entity IDs are re-used, but generation is always increasing
-         * Two entities with the same ID but different generation represent two distinct entities, one with "younger" generation (larger number) is the more recently created one
-         * @private
-         * @type {number}
-         */
-        this.generation = 0;
+    /**
+     * A counter that is incremented every time an entity is created
+     * Generation is used to provide an entity with a unique identity
+     * Entity IDs are re-used, but generation is always increasing
+     * Two entities with the same ID but different generation represent two distinct entities, one with "younger" generation (larger number) is the more recently created one
+     * @private
+     * @type {number}
+     */
+    generation = 0;
 
-        /**
-         * @readonly
-         * @type {Signal}
-         */
-        this.onEntityCreated = new Signal();
+    /**
+     * @readonly
+     * @type {Signal}
+     */
+    onEntityCreated = new Signal();
 
-        /**
-         * @readonly
-         * @type {Signal}
-         */
-        this.onEntityRemoved = new Signal();
+    /**
+     * @readonly
+     * @type {Signal}
+     */
+    onEntityRemoved = new Signal();
 
 
-        /**
-         *
-         * @type {Array<Object<SignalHandler[]>>}
-         * @private
-         */
-        this.__entityEventListeners = [];
+    /**
+     *
+     * @type {Array<Object<SignalHandler[]>>}
+     * @private
+     */
+    __entityEventListeners = [];
 
-        /**
-         *
-         * @type {SignalHandler[][]}
-         * @private
-         */
-        this.__entityAnyEventListeners = [];
+    /**
+     *
+     * @type {SignalHandler[][]}
+     * @private
+     */
+    __entityAnyEventListeners = [];
+
+    /**
+     * @private
+     * @type {Array<Array<EntityObserver>>}
+     */
+    observers = [];
 
-        /**
-         * @private
-         * @type {Array<Array<EntityObserver>>}
-         */
-        this.observers = [];
-    }
 
     /**
      * returns a promise of a component instance based on a given type
@@ -885,7 +887,7 @@ export class EntityComponentDataset {
         const componentClass = this.componentTypeMap[componentIndex];
 
         //dispatch event to components
-        this.sendEvent(entityIndex, EventType.ComponentRemoved, { klass: componentClass, instance: componentInstance });
+        this.sendEvent(entityIndex, EventType.ComponentRemoved, {klass: componentClass, instance: componentInstance});
     }
 
     /**
@@ -997,7 +999,7 @@ export class EntityComponentDataset {
         const componentClass = this.componentTypeMap[componentIndex];
 
         //dispatch event to components
-        this.sendEvent(entityIndex, EventType.ComponentAdded, { klass: componentClass, instance: componentInstance });
+        this.sendEvent(entityIndex, EventType.ComponentAdded, {klass: componentClass, instance: componentInstance});
     }
 
     /**

package/src/engine/ecs/EntityFlags.js

@@ -8,13 +8,13 @@ export const EntityFlags = {
      */
     Built: 1,
     /**
-     * If component type is not registered on the {@link EntityComponentDataset} when calling {@link EntityBuilder#build} - will register the component first
+     * If component type is not registered on the {@link EntityComponentDataset} when calling {@link Entity#build} - will register the component first
      */
     RegisterComponents: 2,
     /**
-     * Entity builder will watch destruction of the entity (subscribe to event), this will make the {@link EntityBuilder} automatically
-     * recognize when the corresponding entity is destroyed outside the EntityBuilder API
-     * NOTE: useful to turn off to save a bit of memory, as those event listeners take up a bit of space. Feel free to turn this flag off when you don't care to keep the reference to the EntityBuilder
+     * Entity builder will watch destruction of the entity (subscribe to event), this will make the {@link Entity} automatically
+     * recognize when the corresponding entity is destroyed outside the {@link Entity} API
+     * NOTE: useful to turn off to save a bit of memory, as those event listeners take up a bit of space. Feel free to turn this flag off when you don't care to keep the reference to the {@link Entity}
      */
     WatchDestruction: 4
 };

package/src/engine/ecs/attachment/Attachment.js

@@ -1,4 +1,5 @@
-import { Transform } from "../transform/Transform.js";
+import {Transform} from "../transform/Transform.js";
+import {assert} from "../../../core/assert.js";
 
 export class Attachment {
 
@@ -26,7 +27,9 @@ export class Attachment {
      */
     immediate = false;
 
-    fromJSON({ parent, socket, transform, immediate = false }) {
+    fromJSON({parent, socket, transform, immediate = false}) {
+        assert.isNonNegativeInteger(parent, 'parent');
+
         this.parent = parent;
         this.socket = socket;