@woosh/meep-engine 2.48.1 → 2.48.5

package/src/core/model/ResourceAccessSpecification.js

@@ -0,0 +1,41 @@
+import { ResourceAccessKind } from "./ResourceAccessKind.js";
+
+const DEFAULT_ACCESS = ResourceAccessKind.Read | ResourceAccessKind.Write;
+
+/**
+ * @template R
+ */
+export class ResourceAccessSpecification {
+    /**
+     *
+     * @type {number|ResourceAccessKind}
+     */
+    access = DEFAULT_ACCESS
+
+    /**
+     *
+     * @type {R|null}
+     */
+    resource = null
+
+    /**
+     * @template R
+     * @param {R} resource
+     * @param {number|ResourceAccessKind} access
+     * @returns {ResourceAccessSpecification<R>}
+     */
+    static from(resource, access = DEFAULT_ACCESS){
+        const r = new ResourceAccessSpecification();
+
+        r.access = access;
+        r.resource = resource;
+
+        return r;
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+ResourceAccessSpecification.prototype.isResourceAccessSpecification = true;

package/src/engine/Engine.js

@@ -176,7 +176,7 @@ class Engine {
          *
          * @type {ModuleRegistry}
          */
-        this.classRegistry = new ModuleRegistry();
+        this.moduleRegistry = new ModuleRegistry();
 
         /**
          * @readonly

package/src/engine/ecs/EntityEventBinding.js

@@ -0,0 +1,74 @@
+import { assert } from "../../core/assert.js";
+
+export class EntityEventBinding {
+    entity = -1
+    event = ""
+    handler = null
+    context = null
+    /**
+     *
+     * @type {EntityComponentDataset|null}
+     */
+    ecd = null
+
+    #linked = false
+
+    /**
+     *
+     * @param {number} entity
+     * @param {string} event
+     * @param {function} handler
+     * @param {*} [context]
+     * @returns {EntityEventBinding}
+     */
+    static from(
+        entity, event, handler, context
+    ) {
+        assert.isNonNegativeInteger(entity, 'entity');
+        assert.isString(event, 'event');
+        assert.isFunction(handler, 'handler');
+
+        const r = new EntityEventBinding();
+
+        r.entity = entity;
+        r.event = event;
+        r.handler = handler;
+        r.context = context;
+
+        return r;
+    }
+
+    /**
+     *
+     * @param {EntityComponentDataset} ecd
+     */
+    link(ecd) {
+        if (this.#linked) {
+            if (this.ecd === ecd) {
+                return;
+            }
+
+            this.unlink();
+        }
+
+        this.#linked = true;
+        this.ecd = ecd;
+
+        ecd.addEntityEventListener(this.entity, this.event, this.handler, this.context);
+    }
+
+    unlink() {
+        if (!this.#linked) {
+            return;
+        }
+
+        const ecd = this.ecd;
+
+        if (ecd.entityExists(this.entity)) {
+            ecd.removeEntityEventListener(this.entity, this.event, this.handler, this.context);
+        }
+
+        this.#linked = false;
+        this.ecd = null;
+    }
+}

package/src/engine/ecs/EntityManager.js

@@ -9,6 +9,8 @@ import { assert } from "../../core/assert.js";
 import { EntityObserver } from "./EntityObserver.js";
 import { IllegalStateException } from "../../core/fsm/exceptions/IllegalStateException.js";
 import { noop } from "../../core/function/Functions.js";
+import { ResourceAccessKind } from "../../core/model/ResourceAccessKind.js";
+import { computeSystemComponentDependencyGraph } from "./system/computeSystemComponentDependencyGraph.js";
 
 /**
  *
@@ -45,6 +47,12 @@ function EntityManager() {
      */
     this.systems = [];
 
+    /**
+     * @readonly
+     * @type {System[]}
+     */
+    this.systemsExecutionOrder = [];
+
     /**
      * @readonly
      * @type {EntityObserver[]}
@@ -85,8 +93,98 @@ function EntityManager() {
      * @type {EntityComponentDataset}
      */
     this.dataset = null;
+
+    /**
+     *
+     * @type {boolean}
+     * @private
+     */
+    this.__execution_order_needs_update = true;
 }
 
+/**
+ * Rebuild execution order
+ */
+EntityManager.prototype.updateExecutionOrder = function () {
+    // console.time('updateExecutionOrder')
+
+    const order = this.systemsExecutionOrder;
+
+    order.splice(0, order.length);
+
+    const systems = this.systems;
+    const system_count = systems.length;
+
+    let executable_system_count = 0;
+
+    for (let i = 0; i < system_count; i++) {
+        const system = systems[i];
+
+        if (system.update === noop && system.fixedUpdate === noop) {
+            // not a simulation system
+            continue;
+        }
+
+        order[executable_system_count++] = system;
+    }
+
+    // build dependency graphs amongst components
+    const dependency_graph = computeSystemComponentDependencyGraph(executable_system_count, order);
+
+
+    /**
+     *
+     * @param {System} system
+     * @returns {number} higher values means it should be scheduled before others
+     */
+    function scoreSystem(system) {
+        let result = 0;
+
+        const components = system.referenced_components;
+        const component_count = components.length;
+
+        for (let i = 0; i < component_count; i++) {
+            const component = components[i];
+
+            result += 0.0001;
+
+
+            // count number of incoming edges
+            const attached_edge_count = dependency_graph.getNodeContainer(component).getIncomingEdgeCount();
+
+            const access = system.getAccessForComponent(component);
+
+            if ((access & ResourceAccessKind.Create) !== 0) {
+                result += attached_edge_count * 4
+            } else if ((access & ResourceAccessKind.Write) !== 0) {
+                result += attached_edge_count * 2
+            } else {
+                result += attached_edge_count;
+            }
+
+        }
+
+        return result;
+    }
+
+    // pre-score systems for faster sorting
+    const scores = new Map();
+
+    for (let i = 0; i < executable_system_count; i++) {
+        const system = order[i];
+
+        scores.set(system, scoreSystem(system));
+    }
+
+    order.sort((a, b) => {
+        return scores.get(b) - scores.get(a);
+    });
+
+    // clear update flag
+    this.__execution_order_needs_update = false;
+    // console.timeEnd('updateExecutionOrder')
+};
+
 EntityManager.prototype.detachDataSet = function () {
     const dataset = this.dataset;
 
@@ -215,6 +313,11 @@ EntityManager.prototype.simulate = function (timeDelta) {
     assert.notNaN(timeDelta, 'timeDelta');
     assert.greaterThanOrEqual(timeDelta, 0, 'timeDelta must be >= 0');
 
+    if (this.__execution_order_needs_update) {
+        this.updateExecutionOrder();
+    }
+
+
     /**
      *
      * @type {System[]}
@@ -263,6 +366,11 @@ EntityManager.prototype.simulate = function (timeDelta) {
     }
 };
 
+/**
+ *
+ * @param {System} system
+ * @throws if system fails validation
+ */
 function validateSystem(system) {
     if (system === undefined) {
         throw new Error("System is undefined");
@@ -284,6 +392,35 @@ function validateSystem(system) {
         throw new Error(`uses deprecated 'remove' method, should use 'unlink' instead`);
     }
 
+    // validate 'components_used' section
+    const components_used = system.components_used;
+    const components_used_count = components_used.length;
+
+    for (let i = 0; i < components_used_count; i++) {
+        const spec = components_used[i];
+
+        if (spec === undefined || spec === null || spec.isResourceAccessSpecification !== true) {
+            throw new Error(`Invalid access specification[${i}], expected an instance of ResourceAccessSpecification, but got something else`);
+        }
+
+        if (spec.resource === null) {
+            throw new Error(`No component specified for element [${i}]`);
+        }
+
+        if (spec.access === 0) {
+            throw new Error('No access modifiers specified, must have at least one (such as Read, Write, Create)');
+        }
+
+        // backtrace to make sure there are no duplicates
+        for (let j = 0; j < i - 1; j++) {
+            const spec_other = components_used[j];
+
+            if (spec_other.resource === spec.resource) {
+                throw new Error(`Duplicate specification of component [${j}] and [${i}]`);
+            }
+        }
+    }
+
     //validate dependencies
     const dependencies = system.dependencies;
 
@@ -305,6 +442,7 @@ function validateSystem(system) {
         }
     }
 
+
     const linkArgumentCount = numDependencies + 1;
 
     if (system.link !== System.prototype.link && system.link.length !== linkArgumentCount && system.__validation_ignore_link_argument_count !== true) {
@@ -359,6 +497,8 @@ EntityManager.prototype.addSystem = async function (system) {
 
     systems[systemIndex] = system;
 
+    // request exec order update
+    this.__execution_order_needs_update = true;
 
     //build observer
     const linkObserver = new EntityObserver(system.dependencies, system.link, system.unlink, system);
@@ -416,6 +556,9 @@ EntityManager.prototype.removeSystem = async function (system) {
     //shutdown system
     this.systems.splice(systemIndex, 1);
 
+    // request exec order update
+    this.__execution_order_needs_update = true;
+
     if (this.dataset !== null) {
         this.dataset.removeObserver(systemObserver);
     }

package/src/engine/ecs/System.js

@@ -6,6 +6,8 @@
 import { array_copy_unique } from "../../core/collection/array/array_copy_unique.js";
 import ObservedValue from "../../core/model/ObservedValue.js";
 import { noop } from "../../core/function/Functions.js";
+import { array_push_if_unique } from "../../core/collection/array/array_push_if_unique.js";
+import { ResourceAccessKind } from "../../core/model/ResourceAccessKind.js";
 
 /**
  *
@@ -32,21 +34,67 @@ class System {
     dependencies = [];
 
     /**
-     * Component types that are used internally by the system
-     * Declaring this helps EntityManager to ensure that all relevant component types are properly registered for the system
-     * @type {Array}
+     * Component types that are used internally by the system and how they are used
+     * Main benefit of doing so is twofold:
+     *      - Helps the engine figure out the best execution order for system to make sure that updates propagate as quickly as possible
+     *      - Declaring this helps EntityManager to ensure that all relevant component types are properly registered for the system
+     *
+     * NOTE: specifying this is optional. The engine will still work.
+     * @type {ResourceAccessSpecification[]}
      */
     components_used = [];
 
 
     /**
-     * @returns {[]}
+     * @returns {[]} Component classes
      */
     get referenced_components() {
         const result = [];
 
         array_copy_unique(this.dependencies, 0, result, result.length, this.dependencies.length);
-        array_copy_unique(this.components_used, 0, result, result.length, this.components_used.length);
+
+        const used = this.components_used;
+        const use_count = used.length;
+        for (let i = 0; i < use_count; i++) {
+            const ref = used[i];
+
+            array_push_if_unique(result, ref.resource);
+        }
+
+        return result;
+    }
+
+    /**
+     * @template T
+     * @param {T} Klass
+     * @return {number}
+     */
+    getAccessForComponent(Klass) {
+        let result = 0;
+
+        const used = this.components_used;
+        const use_count = used.length;
+        for (let i = 0; i < use_count; i++) {
+            const ref = used[i];
+
+            if (ref.resource === Klass) {
+                result |= ref.access;
+                break;
+            }
+        }
+
+        const dependencies = this.dependencies;
+        const dependency_count = dependencies.length;
+
+        for (let i = 0; i < dependency_count; i++) {
+            const dependency = dependencies[i];
+
+            if (dependency === Klass) {
+                // at the very least it's going to read
+                result |= ResourceAccessKind.Read;
+                break;
+            }
+        }
 
         return result;
     }

package/src/engine/ecs/animation/InverseKinematicsSystem.js

@@ -6,6 +6,8 @@ import { extractSkeletonFromMeshComponent } from "../../graphics/ecs/mesh/Skelet
 import { OneBoneSurfaceAlignmentSolver } from "./OneBoneSurfaceAlignmentSolver.js";
 import { IKProblem } from "./IKProblem.js";
 import { obtainTerrain } from "../terrain/util/obtainTerrain.js";
+import { ResourceAccessSpecification } from "../../../core/model/ResourceAccessSpecification.js";
+import { ResourceAccessKind } from "../../../core/model/ResourceAccessKind.js";
 
 
 export class InverseKinematicsSystem extends System {
@@ -14,6 +16,10 @@ export class InverseKinematicsSystem extends System {
 
         this.dependencies = [InverseKinematics, Mesh];
 
+        this.components_used = [
+            ResourceAccessSpecification.from(Mesh,ResourceAccessKind.Read|ResourceAccessSpecification.Write)
+        ];
+
         /**
          *
          * @type {{"2BIK": TwoBoneInverseKinematicsSolver}}

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

@@ -6,6 +6,8 @@ import { assert } from "../../../core/assert.js";
 import Mesh from "../../graphics/ecs/mesh/Mesh.js";
 import { BoneAttachmentBinding } from "./BoneAttachmentBinding.js";
 import { TransformAttachmentBinding } from "./TransformAttachmentBinding.js";
+import { ResourceAccessSpecification } from "../../../core/model/ResourceAccessSpecification.js";
+import { ResourceAccessKind } from "../../../core/model/ResourceAccessKind.js";
 
 export class AttachmentSystem extends System {
     constructor() {
@@ -13,6 +15,12 @@ export class AttachmentSystem extends System {
 
         this.dependencies = [Attachment, Transform];
 
+        this.components_used = [
+            ResourceAccessSpecification.from(AttachmentSockets, ResourceAccessKind.Read),
+            ResourceAccessSpecification.from(Mesh, ResourceAccessKind.Read),
+            ResourceAccessSpecification.from(Transform, ResourceAccessKind.Write)
+        ];
+
         /**
          *
          * @type {number[]}

package/src/engine/ecs/dynamic_actions/DynamicActorSystem.js

@@ -20,6 +20,8 @@ import { computeStringHash } from "../../../core/primitives/strings/computeStrin
 import { randomFromArray } from "../../../core/math/random/randomFromArray.js";
 import { randomFloatBetween } from "../../../core/math/random/randomFloatBetween.js";
 import { randomMultipleFromArray } from "../../../core/collection/array/randomMultipleFromArray.js";
+import { ResourceAccessSpecification } from "../../../core/model/ResourceAccessSpecification.js";
+import { ResourceAccessKind } from "../../../core/model/ResourceAccessKind.js";
 
 /**
  * In seconds
@@ -104,6 +106,9 @@ export class DynamicActorSystem extends AbstractContextSystem {
 
         this.dependencies = [DynamicActor];
 
+        this.components_used = [
+            ResourceAccessSpecification.from(Blackboard, ResourceAccessKind.Read)
+        ];
 
         /**
          *

package/src/engine/ecs/fow/FogOfWarRevealerSystem.js

@@ -6,6 +6,8 @@ import Team from "../team/Team.js";
 import { Transform } from "../transform/Transform.js";
 import Vector2 from "../../../core/geom/Vector2.js";
 import { obtainTerrain } from "../terrain/util/obtainTerrain.js";
+import { ResourceAccessSpecification } from "../../../core/model/ResourceAccessSpecification.js";
+import { ResourceAccessKind } from "../../../core/model/ResourceAccessKind.js";
 
 const v2 = new Vector2();
 
@@ -17,9 +19,11 @@ export class FogOfWarRevealerSystem extends System {
     constructor(team) {
         super();
 
-        this.dependencies.push(FogOfWarRevealer);
-        this.dependencies.push(Transform);
-        this.dependencies.push(Team);
+        this.dependencies = [FogOfWarRevealer, Transform, Team];
+
+        this.components_used = [
+            ResourceAccessSpecification.from(FogOfWar, ResourceAccessKind.Write)
+        ];
 
         this.data = [];
 

package/src/engine/ecs/fow/FogOfWarSystem.js

@@ -16,6 +16,8 @@ import {
     compute_perspective_camera_focal_position
 } from "../../graphics/ecs/camera/compute_perspective_camera_focal_position.js";
 import { frustum_from_camera } from "../../graphics/ecs/camera/frustum_from_camera.js";
+import { ResourceAccessSpecification } from "../../../core/model/ResourceAccessSpecification.js";
+import { ResourceAccessKind } from "../../../core/model/ResourceAccessKind.js";
 
 
 const frustum = new Frustum();
@@ -36,6 +38,10 @@ export class FogOfWarSystem extends System {
 
         this.dependencies = [FogOfWar, Terrain];
 
+        this.components_used = [
+            ResourceAccessSpecification.from(FogOfWar, ResourceAccessKind.Read | ResourceAccessKind.Write)
+        ];
+
         this.visibilityFilter = this.buildVisibilityFilter();
         //turn off by default
         this.visibilityFilter.enabled = false;

package/src/engine/ecs/gui/GUIElementSystem.js

@@ -85,7 +85,7 @@ class GUIElementSystem extends System {
         /**
          * @type {ModuleRegistry}
          */
-        this.classRegistry = engine.classRegistry;
+        this.classRegistry = engine.moduleRegistry;
 
         /**
          *

package/src/engine/ecs/gui/hud/HeadsUpDisplaySystem.js

@@ -12,6 +12,8 @@ import ViewportPosition from "../position/ViewportPosition.js";
 import GUIElement from "../GUIElement.js";
 import { HeadsUpDisplayFlag } from "./HeadsUpDisplayFlag.js";
 import { mat4 } from "gl-matrix";
+import { ResourceAccessSpecification } from "../../../../core/model/ResourceAccessSpecification.js";
+import { ResourceAccessKind } from "../../../../core/model/ResourceAccessKind.js";
 
 const projection = new Float32Array(16);
 
@@ -32,6 +34,12 @@ class HeadsUpDisplaySystem extends System {
 
         this.dependencies = [HeadsUpDisplay];
 
+
+        this.components_used = [
+            ResourceAccessSpecification.from(GUIElement, ResourceAccessKind.Read | ResourceAccessKind.Write),
+            ResourceAccessSpecification.from(ViewportPosition, ResourceAccessKind.Read | ResourceAccessKind.Write),
+        ];
+
         if (!(graphicsEngine instanceof GraphicsEngine)) {
             throw new TypeError(`graphicsEngine is not an instance of GraphicsEngine`);
         }

package/src/engine/ecs/gui/position/ViewportPositionSystem.js

@@ -9,6 +9,8 @@ import { SignalBinding } from "../../../../core/events/signal/SignalBinding.js";
 import AABB2 from "../../../../core/geom/AABB2.js";
 import { GUIElementEvent } from "../GUIElementEvent.js";
 import { EPSILON } from "../../../../core/math/EPSILON.js";
+import { ResourceAccessSpecification } from "../../../../core/model/ResourceAccessSpecification.js";
+import { ResourceAccessKind } from "../../../../core/model/ResourceAccessKind.js";
 
 const CSS_CLASS = 'ecs-viewport-position-component';
 
@@ -27,6 +29,10 @@ class ViewportPositionSystem extends System {
 
         this.dependencies = [ViewportPosition, GUIElement];
 
+        this.components_used = [
+            ResourceAccessSpecification.from(GUIElement, ResourceAccessKind.Read | ResourceAccessKind.Write),
+        ];
+
         this.viewportSize = viewportSize;
 
         this.viewportSizeChangeReactor = new SignalBinding(viewportSize.onChanged, () => {

package/src/engine/ecs/speaker/VoiceSystem.js

@@ -30,6 +30,8 @@ import TransitionFunctions from "../../animation/TransitionFunctions.js";
 import AnimationTrackPlayback from "../../animation/keyed2/AnimationTrackPlayback.js";
 import { globalMetrics } from "../../metrics/GlobalMetrics.js";
 import { MetricsCategory } from "../../metrics/MetricsCategory.js";
+import { ResourceAccessSpecification } from "../../../core/model/ResourceAccessSpecification.js";
+import { ResourceAccessKind } from "../../../core/model/ResourceAccessKind.js";
 
 /**
  * Delay before the user notices the text and begins to read
@@ -170,6 +172,17 @@ export class VoiceSystem extends AbstractContextSystem {
 
         this.dependencies = [Voice];
 
+        this.components_used = [
+            ResourceAccessSpecification.from(GUIElement, ResourceAccessKind.Create),
+            ResourceAccessSpecification.from(ViewportPosition, ResourceAccessKind.Create),
+            ResourceAccessSpecification.from(HeadsUpDisplay, ResourceAccessKind.Create),
+            ResourceAccessSpecification.from(Transform, ResourceAccessKind.Create),
+            ResourceAccessSpecification.from(Attachment, ResourceAccessKind.Create),
+            ResourceAccessSpecification.from(SerializationMetadata, ResourceAccessKind.Create),
+            ResourceAccessSpecification.from(BehaviorComponent, ResourceAccessKind.Create),
+        ];
+
+
         /**
          *
          * @type {Localization}