@woosh/meep-engine 2.120.2 → 2.120.3

package/src/engine/ecs/EntityComponentDataset.js

@@ -9,7 +9,8 @@ import {
 import Signal from "../../core/events/signal/Signal.js";
 import { SignalHandler } from "../../core/events/signal/SignalHandler.js";
 import { max3 } from "../../core/math/max3.js";
-import { EventType } from "./EntityManager.js";
+
+import { EventType } from "./EventType.js";
 
 /**
  *
@@ -110,6 +111,18 @@ const scratch_array_1 = [];
  * 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
+ * Typically you would use {@link Entity} helper class instead of working directly with the dataset as it offers a higher-level API
+ *
+ * @example
+ *   const ecd = new EntityComponentDataset();
+ *   // create an entity
+ *   const entityId = ecd.createEntity();
+ *
+ *   // add a component to your entity
+ *   ecd.addComponentToEntity(entityId, myComponentInstance);
+ *
+ *   // destroy the entity
+ *   ecd.removeEntity(entityId);
  */
 export class EntityComponentDataset {
 
@@ -769,6 +782,8 @@ export class EntityComponentDataset {
      * @returns {number}
      */
     getEntityGeneration(entity_id) {
+        assert.isNonNegativeInteger(entity_id, 'entity_id');
+
         return this.entityGeneration[entity_id];
     }
 
@@ -843,9 +858,9 @@ export class EntityComponentDataset {
     }
 
     /**
-     *
+     * Remove entity from the dataset, effectively destroying it from the world
      * @param {number} entity_id
-     * @returns {boolean}
+     * @returns {boolean} true if entity was removed, false if it doesn't exist
      */
     removeEntity(entity_id) {
         if (!this.entityExists(entity_id)) {
@@ -1166,7 +1181,13 @@ export class EntityComponentDataset {
 
     /**
      * Performs traversal on a subset of entities which have specified components.
-     * @example traverseEntities([Transform,Renderable,Tag],function(transform, renderable, tag, entity){ ... }, this);
+     * @example
+     *  ecd.traverseEntities(
+     *      [Transform, Renderable, Tag], // Component classes to match
+     *      (transform, renderable, tag, entity ) => {  // actual component instances along with entity ID
+     *          // do something
+     *      }
+     *  );
      * @param {Array} classes
      * @param {function(...args):boolean} visitor Visitor can return optional "false" to terminate traversal earlier
      * @param {object} [thisArg] specifies context object on which callbacks are to be called, optional

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":";;;wBAcU,MAAM;;;;;;iCAWN,MAAM;;;;;;;;;AAWhB;;;GAGG;AACH;IAEI;;;OAGG;IACH,kBAFU,iCAAQ,CAEL;IAEb;;;;OAIG;IACH,uCAA2B;IAE3B;;;;OAIG;IACH,iCAAqB;IAErB;;OAEG;IACH;;;QAGI;;WAEG;qBADO,MAAM,iCAAQ;;MAI1B;IAEF;;;OAGG;IACH,OAFU,kBAAkB,CAEO;IAEnC;;;;;;OAMG;IACH,gDAA2C;IAE3C;;;;OAIG;IACH,qBAFU,MAAM,CAEY;IAE5B;;;;;OAKG;IACH,wCAFU,MAAM,CAE4B;IAE5C;;;OAGG;IACH,SAFU,sBAAsB,CAEjB;IAEf;;;;;OAKG;IACH,uCAAsC;IAEtC;;;OAGG;IACH,6BA8EC;IAED,sBAcC;IAED;;;OAGG;IACH,uBAFa,KAAK,EAAE,CAuBnB;IAED;;;;;OAKG;IACH,uBAJW,sBAAsB,QA0BhC;IAED;;;;OAIG;IACH,UAJa,CAAC,eACH,KAAK,CAAC,CAAC,CAAC,GACN,OAAO,CAInB;IAED;;;;OAIG;IACH,UAJa,CAAC,eACH,KAAK,CAAC,CAAC,CAAC,GACN,CAAC,GAAC,IAAI,CAgBlB;IAED;;;;;OAKG;IACH,wBAJa,CAAC,aACH,MAAM,GACJ,IAAI,GAAC,KAAK,CAAC,CAAC,CAAC,CAezB;IAGD;;;OAGG;IACH,oBAFW,MAAM,QAkEhB;IAED;;;;;OAKG;IACH,iEA0EC;IAED;;;;OAIG;IACH,uDAFa,OAAO,CAAC,OAAO,CAAC,CAyC5B;IAED;;;;;OAKG;IACH,mBA6BC;IAED;;;;;OAKG;IACH,oBAwCC;IAED;;;;OAIG;IACH,gEAwEC;IAED;;;;OAIG;IACH,2BAHW,KAAK,GACH,OAAO,iCAAS,CA0B5B;IAED;;;;;OAKG;IACH,kCAJW,KAAK,SACL,WAAW,GACT,OAAO,iCAAS,CAsB5B;IAED;;;;OAIG;IACH,iEAkEC;CACJ;uBA7yBsD,aAAa;mBANjD,oCAAoC"}
+{"version":3,"file":"EntityManager.d.ts","sourceRoot":"","sources":["../../../../src/engine/ecs/EntityManager.js"],"names":[],"mappings":"iCAeU,MAAM;;;;;;;;;AAWhB;;;GAGG;AACH;IAEI;;;OAGG;IACH,kBAFU,iCAAQ,CAEL;IAEb;;;;OAIG;IACH,uCAA2B;IAE3B;;;;OAIG;IACH,iCAAqB;IAErB;;OAEG;IACH;;;QAGI;;WAEG;qBADO,MAAM,iCAAQ;;MAI1B;IAEF;;;OAGG;IACH,OAFU,kBAAkB,CAEO;IAEnC;;;;;;OAMG;IACH,gDAA2C;IAE3C;;;;OAIG;IACH,qBAFU,MAAM,CAEY;IAE5B;;;;;OAKG;IACH,wCAFU,MAAM,CAE4B;IAE5C;;;OAGG;IACH,SAFU,sBAAsB,CAEjB;IAEf;;;;;OAKG;IACH,uCAAsC;IAEtC;;;OAGG;IACH,6BA8EC;IAED,sBAcC;IAED;;;OAGG;IACH,uBAFa,KAAK,EAAE,CAuBnB;IAED;;;;;OAKG;IACH,uBAJW,sBAAsB,QA0BhC;IAED;;;;OAIG;IACH,UAJa,CAAC,eACH,KAAK,CAAC,CAAC,CAAC,GACN,OAAO,CAInB;IAED;;;;OAIG;IACH,UAJa,CAAC,eACH,KAAK,CAAC,CAAC,CAAC,GACN,CAAC,GAAC,IAAI,CAgBlB;IAED;;;;;OAKG;IACH,wBAJa,CAAC,aACH,MAAM,GACJ,IAAI,GAAC,KAAK,CAAC,CAAC,CAAC,CAezB;IAGD;;;OAGG;IACH,oBAFW,MAAM,QAkEhB;IAED;;;;;OAKG;IACH,iEA0EC;IAED;;;;OAIG;IACH,uDAFa,OAAO,CAAC,OAAO,CAAC,CAyC5B;IAED;;;;;OAKG;IACH,mBA6BC;IAED;;;;;OAKG;IACH,oBAwCC;IAED;;;;OAIG;IACH,gEAwEC;IAED;;;;OAIG;IACH,2BAHW,KAAK,GACH,OAAO,iCAAS,CA0B5B;IAED;;;;;OAKG;IACH,kCAJW,KAAK,SACL,WAAW,GACT,OAAO,iCAAS,CAsB5B;IAED;;;;OAIG;IACH,iEAsEC;CACJ;uBAtyBmC,aAAa;mBAP9B,oCAAoC"}

package/src/engine/ecs/EntityManager.js

@@ -5,22 +5,12 @@ import { IllegalStateException } from "../../core/fsm/exceptions/IllegalStateExc
 
 import { noop } from "../../core/function/noop.js";
 import { ResourceAccessKind } from "../../core/model/ResourceAccessKind.js";
+import { computeSystemName } from "./computeSystemName.js";
 import { EntityObserver } from "./EntityObserver.js";
-import { computeSystemName, System, SystemState } from "./System.js";
+import { System, SystemState } from "./System.js";
 import { computeSystemComponentDependencyGraph } from "./system/computeSystemComponentDependencyGraph.js";
 import { validateSystem } from "./validateSystem.js";
 
-/**
- *
- * @enum {string}
- * @readonly
- */
-export const EventType = {
-    EntityRemoved: "entityRemoved",
-    ComponentAdded: "componentAdded",
-    ComponentRemoved: "componentRemoved"
-};
-
 /**
  * @readonly
  * @enum {number}
@@ -753,6 +743,10 @@ export class EntityManager {
      * @param {function} errorCallback
      */
     shutdown(readyCallback, errorCallback) {
+        if(this.state !== EntityManagerState.Running){
+            throw new IllegalStateException(`System is wrong state, expected '${EntityManagerState.Running}'`);
+        }
+
         this.state = EntityManagerState.Stopping;
 
         if (this.dataset !== null) {

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

@@ -1,6 +1,20 @@
 /**
  * Uniquely identifies an entity by both its ID and generation.
  * Lets us distinguish between two entities with the same ID that were created at different times
+ *
+ * @example
+ * // 1. Get your EntityComponentDataset to where you manager entities.
+ * const ecd = ... ; //EntityComponentDataset
+ *
+ * // 2. Create an entity (we'll get an ID). Or use an existing one.
+ * const entityId = ecd.createEntity(); // Let's say this returns ID 1, generation 0
+ *
+ * // 3. Create an EntityReference and bind it to the entity.
+ * const entityRef = EntityReference.bind(ecd, entityId);
+ *
+ * // 4. After you no longer need the entity - destroy the entity via reference.
+ * entityRef.destroy(ecd);
+ *
  */
 export class EntityReference {
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"EntityReference.d.ts","sourceRoot":"","sources":["../../../../src/engine/ecs/EntityReference.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH;IAiHI;;;;;OAKG;IACH,gBAJW,MAAM,cACN,MAAM,GACL,eAAe,CAQ1B;IAED;;;;;OAKG;IACH,iBAJW,sBAAsB,MACtB,MAAM,GACJ,eAAe,CAQ3B;IAzID;;;;OAIG;IACH,IAFU,MAAM,CAET;IAEP;;;;OAIG;IACH,YAFU,MAAM,CAED;IAEf;;;OAGG;IACH,YAFW,eAAe,QAKzB;IAED;;;OAGG;IACH,SAFa,eAAe,CAQ3B;IAED;;;OAGG;IACH,QAFY,MAAM,CAIjB;IAED;;;;OAIG;IACH,cAHW,eAAe,GACd,OAAO,CAMlB;IAED;;;;OAIG;IACH,YAHW,sBAAsB,GACpB,OAAO,CAQnB;IAED;;;;;OAKG;IACH,aAHW,sBAAsB,GACpB,OAAO,CASnB;IAED;;;;OAIG;IACH,UAHW,sBAAsB,UACtB,MAAM,QAShB;IAED;;;;OAIG;IACH,SAHW,MAAM,cACN,MAAM,QAUhB;IA+BL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;CAN1C;;cAWS,eAAe"}
+{"version":3,"file":"EntityReference.d.ts","sourceRoot":"","sources":["../../../../src/engine/ecs/EntityReference.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH;IAqHI;;;;;OAKG;IACH,gBAJW,MAAM,cACN,MAAM,GACL,eAAe,CAQ1B;IAED;;;;;OAKG;IACH,iBAJW,sBAAsB,MACtB,MAAM,GACJ,eAAe,CAQ3B;IA7ID;;;;OAIG;IACH,IAFU,MAAM,CAET;IAEP;;;;OAIG;IACH,YAFU,MAAM,CAED;IAEf;;;OAGG;IACH,YAFW,eAAe,QAKzB;IAED;;;OAGG;IACH,SAFa,eAAe,CAQ3B;IAED;;;OAGG;IACH,QAFY,MAAM,CAIjB;IAED;;;;OAIG;IACH,cAHW,eAAe,GACd,OAAO,CAMlB;IAED;;;;OAIG;IACH,YAHW,sBAAsB,GACpB,OAAO,CAYnB;IAED;;;;;OAKG;IACH,aAHW,sBAAsB,GACpB,OAAO,CASnB;IAED;;;;OAIG;IACH,UAHW,sBAAsB,UACtB,MAAM,QAShB;IAED;;;;OAIG;IACH,SAHW,MAAM,cACN,MAAM,QAUhB;IA+BL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;CAN1C;;cAWS,eAAe"}

package/src/engine/ecs/EntityReference.js

@@ -3,6 +3,20 @@ import { assert } from "../../core/assert.js";
 /**
  * Uniquely identifies an entity by both its ID and generation.
  * Lets us distinguish between two entities with the same ID that were created at different times
+ *
+ * @example
+ * // 1. Get your EntityComponentDataset to where you manager entities.
+ * const ecd = ... ; //EntityComponentDataset
+ *
+ * // 2. Create an entity (we'll get an ID). Or use an existing one.
+ * const entityId = ecd.createEntity(); // Let's say this returns ID 1, generation 0
+ *
+ * // 3. Create an EntityReference and bind it to the entity.
+ * const entityRef = EntityReference.bind(ecd, entityId);
+ *
+ * // 4. After you no longer need the entity - destroy the entity via reference.
+ * entityRef.destroy(ecd);
+ *
  */
 export class EntityReference {
 
@@ -66,6 +80,10 @@ export class EntityReference {
      * @returns {boolean}
      */
     verify(ecd) {
+        if (this.id < 0) {
+            // special case
+            return false;
+        }
 
         return ecd.entityExists(this.id)
             && this.generation === ecd.getEntityGeneration(this.id)

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

@@ -0,0 +1,10 @@
+/**
+ * *
+ */
+export type EventType = string;
+export namespace EventType {
+    let EntityRemoved: string;
+    let ComponentAdded: string;
+    let ComponentRemoved: string;
+}
+//# sourceMappingURL=EventType.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EventType.d.ts","sourceRoot":"","sources":["../../../../src/engine/ecs/EventType.js"],"names":[],"mappings":";;;wBAEU,MAAM"}

package/src/engine/ecs/EventType.js

@@ -0,0 +1,10 @@
+/**
+ * Special set of ECD events
+ * @enum {string}
+ * @readonly
+ */
+export const EventType = {
+    EntityRemoved: "entityRemoved",
+    ComponentAdded: "componentAdded",
+    ComponentRemoved: "componentRemoved"
+};

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

@@ -1 +1 @@
-{"version":3,"file":"System.d.ts","sourceRoot":"","sources":["../../../../src/engine/ecs/System.js"],"names":[],"mappings":"0BA4JU,MAAM;;;;;;;;AAtJhB;;;GAGG;AACH,oBAFa,CAAC;IAIV;;;OAGG;IACH,yBAFU,aAAa,CAEF;IAErB;;;OAGG;IACH,gBAFU,aAAa,CAAE,WAAW,CAAC,CAEU;IAE/C;;;OAGG;IACH,oBAAkB;IAElB;;;;;;;;OAQG;IACH,iBAFU,2BAA2B,EAAE,CAElB;IAGrB;;OAEG;IACH,mCAcC;IAED;;;;OAIG;IACH,sBAJa,CAAC,SACH,CAAC,GACA,MAAM,CA8BjB;IAED,0EAGC;IAED,2EAEC;IAED,wCAEC;IAED,0CAEC;IAIL;;;OAGG;IACH,mBAFU,OAAO,CAEQ;IAEzB;;;;OAIG;IACH,yBAA4B;IAG5B;;;OAGG;IACH,oBAAuB;CApBtB;;;;AA2DD;;;;GAIG;AACH,wDAFa,MAAM,CAKlB;0BAjLyB,mCAAmC;qBADxC,6BAA6B"}
+{"version":3,"file":"System.d.ts","sourceRoot":"","sources":["../../../../src/engine/ecs/System.js"],"names":[],"mappings":"AAMA;;;GAGG;AACH,oBAFa,CAAC;IAIV;;;OAGG;IACH,yBAFU,aAAa,CAEF;IAErB;;;OAGG;IACH,gBAFU,aAAa,CAAE,WAAW,CAAC,CAEU;IAE/C;;;OAGG;IACH,oBAAkB;IAElB;;;;;;;;OAQG;IACH,iBAFU,2BAA2B,EAAE,CAElB;IAGrB;;OAEG;IACH,mCAcC;IAED;;;;OAIG;IACH,sBAJa,CAAC,SACH,CAAC,GACA,MAAM,CA8BjB;IAED,0EAGC;IAED,2EAEC;IAED,wCAEC;IAED,0CAEC;IAIL;;;OAGG;IACH,mBAFU,OAAO,CAEQ;IAEzB;;;;OAIG;IACH,yBAA4B;IAG5B;;;OAGG;IACH,oBAAuB;CApBtB;;;;0BA2CS,MAAM;;;;;;;;0BAzJU,mCAAmC;qBADxC,6BAA6B"}

package/src/engine/ecs/System.js

@@ -8,7 +8,7 @@ import { ResourceAccessKind } from "../../core/model/ResourceAccessKind.js";
  *
  * @template C
  */
-class System {
+export class System {
 
     /**
      * @protected
@@ -170,14 +170,3 @@ export const SystemState = {
  */
 System.State = SystemState;
 
-/**
- *
- * @param {System} system
- * @returns {string}
- */
-function computeSystemName(system) {
-
-    return system.constructor.name;
-}
-
-export { System, computeSystemName };

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

@@ -0,0 +1,8 @@
+/**
+ * Compute name of a system.
+ * Mostly used for UI and debug
+ * @param {System} system
+ * @returns {string}
+ */
+export function computeSystemName(system: System): string;
+//# sourceMappingURL=computeSystemName.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"computeSystemName.d.ts","sourceRoot":"","sources":["../../../../src/engine/ecs/computeSystemName.js"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,0CAHW,MAAM,GACJ,MAAM,CAKlB"}

package/src/engine/ecs/computeSystemName.js

@@ -0,0 +1,10 @@
+/**
+ * Compute name of a system.
+ * Mostly used for UI and debug
+ * @param {System} system
+ * @returns {string}
+ */
+export function computeSystemName(system) {
+
+    return system.constructor.name;
+}

package/src/engine/ecs/parent/ParentEntitySystem.js

@@ -1,4 +1,4 @@
-import { EventType } from "../EntityManager.js";
+import { EventType } from "../EventType.js";
 import { AbstractContextSystem } from "../system/AbstractContextSystem.js";
 import { SystemEntityContext } from "../system/SystemEntityContext.js";
 import { ParentEntity } from "./ParentEntity.js";

package/src/engine/ecs/terrain/TerrainClouds.d.ts

@@ -27,21 +27,54 @@ declare class Clouds {
      * @returns {boolean}
      */
     get enabled(): boolean;
-    setSpeed(x: any, y: any): void;
-    writeOneCloudSpeed(mat: any): void;
-    writeOneEnabled(mat: any): void;
-    writeOneTime(mat: any): void;
+    /**
+     *
+     * @param {number} x
+     * @param {number} y
+     */
+    setSpeed(x: number, y: number): void;
+    /**
+     *
+     * @param {THREE.Material} mat
+     */
+    writeOneCloudSpeed(mat: THREE.Material): void;
+    /**
+     *
+     * @param {THREE.Material} mat
+     */
+    writeOneEnabled(mat: THREE.Material): void;
+    /**
+     *
+     * @param {THREE.Material} mat
+     */
+    writeOneTime(mat: THREE.Material): void;
     writeAllTime(): void;
-    update(timeDelta: any): void;
-    writeOneCloudTextures(mat: any): void;
-    writeOneCloudUniforms(mat: any): void;
     /**
      *
-     * @param {Material} material
+     * @param {number} timeDelta
+     */
+    update(timeDelta: number): void;
+    /**
+     *
+     * @param {THREE.Material} mat
+     */
+    writeOneCloudTextures(mat: THREE.Material): void;
+    /**
+     *
+     * @param {THREE.Material} mat
+     */
+    writeOneCloudUniforms(mat: THREE.Material): void;
+    /**
+     *
+     * @param {THREE.Material} material
      * @returns {boolean}
      */
-    removeMaterial(material: Material): boolean;
-    addMaterial(material: any): void;
+    removeMaterial(material: THREE.Material): boolean;
+    /**
+     *
+     * @param {THREE.Material} material
+     */
+    addMaterial(material: THREE.Material): void;
 }
 import Vector2 from '../../../core/geom/Vector2.js';
 //# sourceMappingURL=TerrainClouds.d.ts.map

package/src/engine/ecs/terrain/TerrainClouds.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TerrainClouds.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/terrain/TerrainClouds.js"],"names":[],"mappings":";AA6BA;IACI;;;;OAIG;IACH,kBAAkB;IAClB;;;;OAIG;IACH,kBAAe;IACf,aAAS;IAGT,kBAAyB;IACzB,kBAAyB;IACzB,kBAAyB;IAGzB,oBAAmB;IAMnB;;;OAGG;IACH,iBAFW,OAAO,EASjB;IAED;;;OAGG;IACH,eAFa,OAAO,CAInB;IAED,+BAMC;IAED,mCAMC;IAED,gCAGC;IAED,6BAGC;IAGD,qBAQC;IAED,6BAGC;IAED,sCAKC;IAED,sCAWC;IAED;;;;OAIG;IACH,yBAHW,QAAQ,GACN,OAAO,CAWnB;IAED,iCAWC;CACJ;oBAtKmB,+BAA+B"}
+{"version":3,"file":"TerrainClouds.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/terrain/TerrainClouds.js"],"names":[],"mappings":";AA6BA;IACI;;;;OAIG;IACH,kBAAkB;IAClB;;;;OAIG;IACH,kBAAe;IACf,aAAS;IAGT,kBAAyB;IACzB,kBAAyB;IACzB,kBAAyB;IAGzB,oBAAmB;IAMnB;;;OAGG;IACH,iBAFW,OAAO,EASjB;IAED;;;OAGG;IACH,eAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,YAHW,MAAM,KACN,MAAM,QAQhB;IAED;;;OAGG;IACH,wBAFW,KAAK,CAAC,QAAQ,QAQxB;IAED;;;OAGG;IACH,qBAFW,KAAK,CAAC,QAAQ,QAKxB;IAED;;;OAGG;IACH,kBAFW,KAAK,CAAC,QAAQ,QAKxB;IAGD,qBAQC;IAED;;;OAGG;IACH,kBAFW,MAAM,QAKhB;IAED;;;OAGG;IACH,2BAFW,KAAK,CAAC,QAAQ,QAOxB;IAED;;;OAGG;IACH,2BAFW,KAAK,CAAC,QAAQ,QAaxB;IAED;;;;OAIG;IACH,yBAHW,KAAK,CAAC,QAAQ,GACZ,OAAO,CAWnB;IAED;;;OAGG;IACH,sBAFW,KAAK,CAAC,QAAQ,QAgBxB;CACJ;oBA1MmB,+BAA+B"}

package/src/engine/ecs/terrain/TerrainClouds.js

@@ -75,6 +75,11 @@ class Clouds {
         return this.__enabled;
     }
 
+    /**
+     *
+     * @param {number} x
+     * @param {number} y
+     */
     setSpeed(x, y) {
         const variability = this.variability;
 
@@ -83,6 +88,10 @@ class Clouds {
         this.__speed2.set(x * (1 + variability), y * (1 - variability));
     }
 
+    /**
+     *
+     * @param {THREE.Material} mat
+     */
     writeOneCloudSpeed(mat) {
         const uniforms = mat.uniforms;
 
@@ -91,11 +100,19 @@ class Clouds {
         uniforms.v_CloudsSpeed_2.value.copy(this.__speed2);
     }
 
+    /**
+     *
+     * @param {THREE.Material} mat
+     */
     writeOneEnabled(mat) {
         mat.defines.SHADOWMAP_CLOUDS = this.__enabled;
         mat.needsUpdate = true;
     }
 
+    /**
+     *
+     * @param {THREE.Material} mat
+     */
     writeOneTime(mat) {
         const uniforms = mat.uniforms;
         uniforms.f_CloudsTime.value = this.time;
@@ -112,11 +129,19 @@ class Clouds {
         }
     }
 
+    /**
+     *
+     * @param {number} timeDelta
+     */
     update(timeDelta) {
         this.time += timeDelta;
         this.writeAllTime();
     }
 
+    /**
+     *
+     * @param {THREE.Material} mat
+     */
     writeOneCloudTextures(mat) {
         const uniforms = mat.uniforms;
         uniforms.t_Clouds_0.value = loadCloudTexture("data/textures/noise/tile_256.png");
@@ -124,6 +149,10 @@ class Clouds {
         uniforms.t_Clouds_2.value = loadCloudTexture("data/textures/noise/tile_256.png");
     }
 
+    /**
+     *
+     * @param {THREE.Material} mat
+     */
     writeOneCloudUniforms(mat) {
 
         const uniforms = mat.uniforms;
@@ -139,7 +168,7 @@ class Clouds {
 
     /**
      *
-     * @param {Material} material
+     * @param {THREE.Material} material
      * @returns {boolean}
      */
     removeMaterial(material) {
@@ -153,8 +182,15 @@ class Clouds {
         return true;
     }
 
+    /**
+     *
+     * @param {THREE.Material} material
+     */
     addMaterial(material) {
-        if (typeof material.defines === "object" && material.defines.hasOwnProperty("SHADOWMAP_CLOUDS")) {
+        if (
+            typeof material.defines === "object"
+            && material.defines.hasOwnProperty("SHADOWMAP_CLOUDS")
+        ) {
             this.writeOneTime(material);
             this.writeOneEnabled(material);
             this.writeOneCloudTextures(material);

package/src/engine/ecs/terrain/ecs/Terrain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Terrain.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/ecs/terrain/ecs/Terrain.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"Terrain.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/ecs/terrain/ecs/Terrain.js"],"names":[],"mappings":"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"}

package/src/engine/ecs/terrain/ecs/Terrain.js

@@ -34,6 +34,12 @@ import { TerrainFlags } from "./TerrainFlags.js";
 
 let idCounter = 0;
 
+/**
+ * Terrain is split into equal sized square patches
+ * Dimensions of single patch in width and height
+ * NOTE: edges of the terrain will typically result in patches smaller than this, so this is upper bound
+ * @type {number}
+ */
 const TILE_SIZE = 7;
 
 class Terrain {

package/src/engine/ecs/terrain/ecs/makeTerrainWorkerProxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"makeTerrainWorkerProxy.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/ecs/terrain/ecs/makeTerrainWorkerProxy.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH,0CAFY,WAAW,CAgFtB"}
+{"version":3,"file":"makeTerrainWorkerProxy.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/ecs/terrain/ecs/makeTerrainWorkerProxy.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH,0CAFY,WAAW,CAkFtB"}

package/src/engine/ecs/terrain/ecs/makeTerrainWorkerProxy.js

@@ -8,7 +8,9 @@ export function makeTerrainWorkerProxy() {
     const workerBuilder = new WorkerBuilder();
     workerBuilder.importScript('bundle-worker-terrain.js');
 
-    workerBuilder.addCode(`
+    workerBuilder.addCode(
+        //language=JavaScript
+        `
         function useSampler(callback) {
             if (globalScope.samplerHeight !== undefined) {
                 callback(globalScope.samplerHeight);

package/src/engine/graphics/ecs/path/ribbon/RibbonPathBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RibbonPathBuilder.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/ecs/path/ribbon/RibbonPathBuilder.js"],"names":[],"mappings":"AAaA;IAEQ;;;OAGG;IACH,OAFU,eAAe,GAAC,IAAI,CAEb;IAEjB;;;OAGG;IACH,MAFU,IAAI,GAAC,IAAI,CAEH;IAEhB;;;OAGG;IACH,QAFU,aAAa,GAAC,IAAI,CAEV;IAGtB;;;OAGG;IACH,gBAFW,eAAe,QAIzB;IAED;;;OAGG;IACH,cAFW,IAAI,QAId;IAED;;;OAGG;IACH,kBAFW,aAAa,QAIvB;IAED;;;OAGG;IACH,mBAFW,MAAM,EAAE,QAsFlB;CAEJ;mBA3IkB,2BAA2B"}
+{"version":3,"file":"RibbonPathBuilder.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/ecs/path/ribbon/RibbonPathBuilder.js"],"names":[],"mappings":"AAaA;IAEQ;;;OAGG;IACH,OAFU,eAAe,GAAC,IAAI,CAEb;IAEjB;;;OAGG;IACH,MAFU,IAAI,GAAC,IAAI,CAEH;IAEhB;;;OAGG;IACH,QAFU,aAAa,GAAC,IAAI,CAEV;IAGtB;;;OAGG;IACH,gBAFW,eAAe,QAIzB;IAED;;;OAGG;IACH,cAFW,IAAI,QAId;IAED;;;OAGG;IACH,kBAFW,aAAa,QAIvB;IAED;;;OAGG;IACH,mBAFW,MAAM,EAAE,QAsFlB;CAEJ;mBAnJkB,2BAA2B"}

package/src/engine/graphics/ecs/path/ribbon/RibbonPathBuilder.js

@@ -1,15 +1,15 @@
-import { RibbonX } from "../../../trail/x/RibbonX.js";
-import {
-    RIBBON_ATTRIBUTE_ADDRESS_AGE,
-    RIBBON_ATTRIBUTE_ADDRESS_UV_OFFSET
-} from "../../../trail/x/ribbon_attributes_spec.js";
 import Vector3 from "../../../../../core/geom/Vector3.js";
+import Entity from "../../../../ecs/Entity.js";
+import { EventType } from "../../../../ecs/EventType.js";
 import Renderable from "../../../../ecs/renderable/Renderable.js";
 import { RenderableFlags } from "../../../../ecs/renderable/RenderableFlags.js";
 import { Transform } from "../../../../ecs/transform/Transform.js";
-import Entity from "../../../../ecs/Entity.js";
 import ThreeFactory from "../../../three/ThreeFactory.js";
-import { EventType } from "../../../../ecs/EntityManager.js";
+import {
+    RIBBON_ATTRIBUTE_ADDRESS_AGE,
+    RIBBON_ATTRIBUTE_ADDRESS_UV_OFFSET
+} from "../../../trail/x/ribbon_attributes_spec.js";
+import { RibbonX } from "../../../trail/x/RibbonX.js";
 
 export class RibbonPathBuilder {
     constructor() {

package/src/engine/input/devices/InputDeviceSwitch.d.ts

@@ -4,4 +4,8 @@ export class InputDeviceSwitch {
     readonly up: Signal
     readonly down: Signal
     readonly is_down: boolean
+    readonly is_up: boolean
+
+    press():void
+    release():void
 }

package/src/engine/input/devices/InputDeviceSwitch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"InputDeviceSwitch.d.ts","sourceRoot":"","sources":["../../../../../src/engine/input/devices/InputDeviceSwitch.js"],"names":[],"mappings":"AAEA;;GAEG;AACH;IAEI;;;;OAIG;IACH,eAFU,MAAM,CAEG;IAEnB;;;;OAIG;IACH,aAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,SAFU,OAAO,CAEF;IAEf;;;OAGG;IACH,aAFa,OAAO,CAInB;IAED;;;OAGG;IACH,cAOC;IAED;;;OAGG;IACH,gBAOC;CACJ;mBA5DkB,uCAAuC"}
+{"version":3,"file":"InputDeviceSwitch.d.ts","sourceRoot":"","sources":["../../../../../src/engine/input/devices/InputDeviceSwitch.js"],"names":[],"mappings":"AAEA;;GAEG;AACH;IAEI;;;;OAIG;IACH,eAFU,MAAQ,CAEC;IAEnB;;;;OAIG;IACH,aAFU,MAAQ,CAED;IAEjB;;;OAGG;IACH,SAFU,OAAO,CAEF;IAEf;;;OAGG;IACH,aAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,cAOC;IAED;;;;OAIG;IACH,gBAOC;CACJ;mBA9DkB,uCAAuC"}

package/src/engine/input/devices/InputDeviceSwitch.js

@@ -8,14 +8,14 @@ export class InputDeviceSwitch {
     /**
      * Switch press
      * @readonly
-     * @type {Signal}
+     * @type {Signal<>}
      */
     down = new Signal()
 
     /**
      * Switch release
      * @readonly
-     * @type {Signal}
+     * @type {Signal<>}
      */
     up = new Signal()
 
@@ -36,6 +36,7 @@ export class InputDeviceSwitch {
     /**
      * Execute press, will trigger {@link down} signal if previous state was up
      * Idempotent
+     * NOTE: make sure you understand the implications of using this
      */
     press() {
         if (this.is_down) {
@@ -49,6 +50,7 @@ export class InputDeviceSwitch {
     /**
      * Execute release, will trigger {@link up} signal if previous state was down
      * Idempotent
+     * NOTE: make sure you understand the implications of using this
      */
     release() {
         if (!this.is_down) {

package/src/engine/input/devices/KeyCodes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"KeyCodes.d.ts","sourceRoot":"","sources":["../../../../../src/engine/input/devices/KeyCodes.js"],"names":[],"mappings":"uBAEU,MAAM;AAFhB;;;GAGG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqGE"}
+{"version":3,"file":"KeyCodes.d.ts","sourceRoot":"","sources":["../../../../../src/engine/input/devices/KeyCodes.js"],"names":[],"mappings":";;;uBAGU,MAAM;AAHhB;;;;GAIG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqGE"}

package/src/engine/input/devices/KeyCodes.js

@@ -1,4 +1,5 @@
 /**
+ * Valid keyboard keys
  * @readonly
  * @enum {number}
  */

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

@@ -1 +1 @@
-{"version":3,"file":"KeyboardDevice.d.ts","sourceRoot":"","sources":["../../../../../src/engine/input/devices/KeyboardDevice.js"],"names":[],"mappings":";AAYA;IAgBI;;;OAGG;IACH,wBAFW,WAAW,GAAC,OAAO,EA+B7B;IA/CD;;OAEG;IACH;;;MAGE;IAEF;;;OAGG;IACH,mBAAU;IAkBN;;;OAGG;IACH,YAFU,WAAW,CAEO;IAkFhC,cAGC;IAED,aAGC;;CACJ;mBA3IkB,uCAAuC"}
+{"version":3,"file":"KeyboardDevice.d.ts","sourceRoot":"","sources":["../../../../../src/engine/input/devices/KeyboardDevice.js"],"names":[],"mappings":";AAYA;;;GAGG;AACH;IA4BI;;;OAGG;IACH,wBAHW,WAAW,GAAC,OAAO,EAgC7B;IA3DD;;OAEG;IACH;QACI;;;WAGG;cADO,MAAM,CAAC,aAAa,CAAC;QAG/B;;;WAGG;YADO,MAAM,CAAC,aAAa,CAAC;MAGjC;IAEF;;;;;;;OAOG;IACH,mBAAU;IAkBN;;;OAGG;IACH,YAFU,WAAW,CAEO;IAkFhC;;;OAGG;IACH,SAFa,IAAI,CAKhB;IAED;;;OAGG;IACH,QAFa,IAAI,CAKhB;;CAEJ;mBApKkB,uCAAuC"}

package/src/engine/input/devices/KeyboardDevice.js

@@ -10,25 +10,41 @@ import { KeyCodes } from './KeyCodes.js';
  */
 const codeToKeyNameMap = [];
 
+/**
+ * Provides keyboard input.
+ * Listens for key events on a DOM element and provides signals and state for key presses.
+ */
 class KeyboardDevice {
 
     /**
      * @readonly
      */
     on = {
+        /**
+         * Fires when any key is pressed
+         * @type {Signal<KeyboardEvent>}
+         */
         down: new Signal(),
+        /**
+         * Fires when any key is released
+         * @type {Signal<KeyboardEvent>}
+         */
         up: new Signal()
     };
 
     /**
+     * See {@link KeyCodes} for valid IDs
      * @readonly
      * @type {Object<InputDeviceSwitch>}
+     *
+     * @example
+     *   const is_enter_pressed = keyboard.keys[KeyCodes.enter].is_down;
      */
     keys = {};
 
     /**
-     *
-     * @param {EventTarget|Element} domElement
+     * @param {EventTarget|Element} domElement The DOM element to listen for keyboard events on.  This element *must* be focusable (e.g., have a `tabindex` attribute).
+     * @throws {TypeError} If the provided `domElement` is not focusable and doesn't have a `tabindex` attribute.
      */
     constructor(domElement) {
 
@@ -43,7 +59,7 @@ class KeyboardDevice {
         }
 
         /**
-         *
+         * The DOM element being listened to.
          * @type {EventTarget}
          */
         this.domElement = domElement;
@@ -128,15 +144,24 @@ class KeyboardDevice {
 
     }
 
+    /**
+     * Starts listening for keyboard events on the associated DOM element.
+     * @returns {void}
+     */
     start() {
         this.domElement.addEventListener(KeyboardEvents.KeyDown, this.#handlerKeyDown);
         this.domElement.addEventListener(KeyboardEvents.KeyUp, this.#handlerKeyUp);
     }
 
+    /**
+     * Stops listening for keyboard events.
+     * @returns {void}
+     */
     stop() {
         this.domElement.removeEventListener(KeyboardEvents.KeyDown, this.#handlerKeyDown);
         this.domElement.removeEventListener(KeyboardEvents.KeyUp, this.#handlerKeyUp);
     }
+
 }
 
 export default KeyboardDevice;