@woosh/meep-engine 2.47.23 → 2.47.26

package/src/engine/ecs/systems/TimerSystem.js

@@ -8,61 +8,81 @@ import Timer from '../components/Timer.js';
 
 
 class TimerSystem extends System {
-    constructor() {
-        super();
-
-        this.dependencies = [Timer];
-    }
-
-    update(timeDelta) {
-        const entityManager = this.entityManager;
-        const dataset = entityManager.dataset;
-
-        if (dataset === null) {
+    /**
+     *
+     * @type {number}
+     */
+    #timeDelta = 0;
+    /**
+     *
+     * @type {EntityComponentDataset|null}
+     */
+    #dataset = null;
+
+    dependencies = [Timer];
+
+
+    /**
+     *
+     * @param {Timer} timer
+     * @param {number} entity
+     */
+    #visit(timer, entity) {
+        if (!timer.active) {
             return;
         }
 
-        dataset.traverseComponents(Timer, function (timer, entity) {
-            if (!timer.active) {
-                return;
-            }
-
-            let budget = timer.counter + timeDelta;
-            const timeout = timer.timeout;
+        const timeDelta = this.#timeDelta;
+        const dataset = this.#dataset;
 
-            while (budget > timeout) {
-                budget -= timeout;
+        let budget = timer.counter + timeDelta;
+        const timeout = timer.timeout;
 
-                const functions = timer.actions;
+        while (budget > timeout) {
+            budget -= timeout;
 
-                const n = functions.length;
+            const functions = timer.actions;
 
-                for (let i = 0; i < n; i++) {
-                    const action = functions[i];
+            const n = functions.length;
 
-                    try {
-                        action();
-                    } catch (e) {
-                        console.error(`entity '${entity}' Timer action[${i}] exception:`, e);
-                    }
+            for (let i = 0; i < n; i++) {
+                const action = functions[i];
 
+                try {
+                    action();
+                } catch (e) {
+                    console.error(`entity '${entity}' Timer action[${i}] exception:`, e);
                 }
 
-                entityManager.sendEvent(entity, "timer-timeout", timer);
-                if (++timer.ticks > timer.repeat) {
-                    //already performed too many cycles
-                    timer.active = false;
-                    return; //bail out
-                }
+            }
 
-                if (timeout === 0) {
-                    // prevent infinite loop
-                    break;
-                }
+            dataset.sendEvent(entity, "timer-timeout", timer);
+            if (++timer.ticks > timer.repeat) {
+                //already performed too many cycles
+                timer.active = false;
+                return; //bail out
             }
-            timer.counter = budget;
 
-        });
+            if (timeout === 0) {
+                // prevent infinite loop
+                break;
+            }
+        }
+        timer.counter = budget;
+    }
+
+    update(timeDelta) {
+        const entityManager = this.entityManager;
+        const dataset = entityManager.dataset;
+
+        if (dataset === null) {
+            return;
+        }
+
+        this.#dataset = dataset;
+        this.#timeDelta = timeDelta;
+
+        dataset.traverseComponents(Timer, this.#visit, this);
 
     }
 }

package/src/engine/ecs/terrain/util/obtainTerrain.js

@@ -1,5 +1,6 @@
 import { assert } from "../../../../core/assert.js";
 import Terrain from "../ecs/Terrain.js";
+import { noop } from "../../../../core/function/Functions.js";
 
 /**
  *
@@ -7,7 +8,7 @@ import Terrain from "../ecs/Terrain.js";
  * @param {function(terrain:Terrain,entity:number)} [callback]
  * @returns {Terrain|null}
  */
-export function obtainTerrain(ecd, callback) {
+export function obtainTerrain(ecd, callback=noop) {
     assert.notEqual(ecd, null, 'ecd is null');
     assert.notEqual(ecd, undefined, 'ecd is undefined');
 
@@ -15,9 +16,7 @@ export function obtainTerrain(ecd, callback) {
 
     const terrain = object.component;
 
-    if (terrain !== null && typeof callback === "function") {
         callback(terrain, object.entity);
-    }
 
     return terrain;
 }

package/src/engine/graphics/GraphicsEngine.js

@@ -359,7 +359,7 @@ GraphicsEngine.prototype.start = function () {
         /**
          * @see https://registry.khronos.org/webgl/specs/latest/1.0/#5.2
          */
-        powerPreference:"high-performance"
+        powerPreference: "high-performance"
     };
 
     const webGLRenderer = this.renderer = new WebGLRenderer(rendererParameters);
@@ -490,8 +490,9 @@ GraphicsEngine.prototype.normalizeViewportPoint = function (input, result) {
 
     const viewportSize = this.viewport.size;
 
-    const _x = input.x;
-    const _y = input.y;
+    // shift by pixel center
+    const _x = input.x + 0.5;
+    const _y = input.y + 0.5;
 
     result.x = (_x / viewportSize.x) * 2 - 1;
     result.y = -(_y / viewportSize.y) * 2 + 1;

package/src/engine/graphics/ecs/camera/Camera.js

@@ -14,6 +14,7 @@ import { frustum_from_camera } from "./frustum_from_camera.js";
 import { invertQuaternionOrientation } from "./InvertQuaternionOrientation.js";
 import { v3_distance_above_plane } from "../../../../core/geom/v3_distance_above_plane.js";
 import { ProjectionType } from "./ProjectionType.js";
+import { computePlaneRayIntersection } from "../../../../core/geom/Plane.js";
 
 /**
  * @class
@@ -222,6 +223,42 @@ export class Camera {
         return true;
     }
 
+    /**
+     *
+     * @param {Vector3} out
+     * @param {number} origin_x
+     * @param {number} origin_y
+     * @param {number} origin_z
+     * @param {number} direction_x
+     * @param {number} direction_y
+     * @param {number} direction_z
+     * @param {number} plane_index
+     */
+    rayPlaneIntersection(
+        out,
+        origin_x, origin_y, origin_z,
+        direction_x, direction_y, direction_z,
+        plane_index
+    ) {
+
+        assert.isNonNegativeInteger(plane_index, 'plane_index');
+        assert.lessThanOrEqual(plane_index, 5, `plane_index must be <= 5, was ${plane_index}`)
+
+        frustum_from_camera(this.object, scratch_frustum);
+
+        const plane = scratch_frustum.planes[plane_index];
+
+        assert.defined(plane, 'plane');
+
+        computePlaneRayIntersection(
+            out,
+            origin_x, origin_y, origin_z,
+            direction_x, direction_y, direction_z,
+            plane.normal.x, plane.normal.y, plane.normal.z,
+            plane.constant
+        );
+    }
+
     /**
      *
      * @param {number} x

package/src/engine/graphics/ecs/camera/filter/setup_filtered_camera_controller.js

@@ -0,0 +1,78 @@
+import { assert } from "../../../../../core/assert.js";
+import TopDownCameraController from "../topdown/TopDownCameraController.js";
+import EntityBuilder from "../../../../ecs/EntityBuilder.js";
+import { BehaviorComponent } from "../../../../intelligence/behavior/ecs/BehaviorComponent.js";
+import { RepeatBehavior } from "../../../../intelligence/behavior/decorator/RepeatBehavior.js";
+import { ActionBehavior } from "../../../../intelligence/behavior/primitive/ActionBehavior.js";
+import { SerializationMetadata } from "../../../../ecs/components/SerializationMetadata.js";
+import { clamp01 } from "../../../../../core/math/clamp01.js";
+import { lerp } from "../../../../../core/math/lerp.js";
+
+/**
+ *
+ * @param {TopDownCameraController} target
+ * @param {EntityComponentDataset} ecd
+ * @param {number} [responsiveness] higher value results in sharper movement when following
+ * @param {number} [inertia]
+ * @returns {{controller:TopDownCameraController, entity:EntityBuilder}}
+ */
+export function setup_filtered_camera_controller({
+                                                     target,
+                                                     ecd,
+                                                     responsiveness = 10,
+                                                     inertia = 0.1
+                                                 }) {
+
+    assert.defined(target, 'target');
+    assert.defined(ecd, 'ecd');
+    assert.isNumber(responsiveness, 'responsiveness');
+
+    const result = new TopDownCameraController();
+    result.copy(target);
+
+    const remembered_value = new TopDownCameraController();
+    remembered_value.copy(result);
+
+    const entityBuilder = new EntityBuilder();
+
+    entityBuilder
+        .add(BehaviorComponent.fromOne(
+            RepeatBehavior.from(
+                new ActionBehavior(time_delta => {
+                    if (!remembered_value.equals(target)) {
+
+                        // external change detected, override filtered result
+                        result.copy(target);
+
+
+                    } else {
+
+                        const d = clamp01(1 - Math.exp(-responsiveness * time_delta));
+
+                        target.distance = lerp(target.distance, result.distance, d);
+
+                        target.pitch = result.pitch;
+                        target.yaw = result.yaw;
+                        target.roll = result.roll;
+
+                        target.distanceMin = lerp(target.distanceMin, result.distanceMin, d);
+                        target.distanceMax = lerp(target.distanceMax, result.distanceMax, d);
+
+                        target.target.copy(result.target);
+                    }
+
+
+                    // remember current value
+                    remembered_value.copy(target);
+                })
+            )
+        ))
+        .add(SerializationMetadata.Transient)
+        .build(ecd);
+
+
+    return {
+        controller: result,
+        entity: entityBuilder
+    };
+}

package/src/engine/graphics/ecs/camera/pp/NOTES.md

@@ -0,0 +1,48 @@
+Perfect panning implementation, based on [this](https://prideout.net/blog/perfect_panning/). Below is a copy of the original article
+
+---
+
+Perfect Panning
+===============
+
+This is a quick note about _through the lens_ camera control. The user drags the mouse around in their viewport, which causes the camera to slide around within the plane that is parallel to the near and far clipping planes.
+
+This is super easy to implement, but it’s somewhat tricky if you want the user to feel like they’re grabbing something in the scene – especially if you consider the distortion caused by perspective projection.
+
+For example, the following screenshots show a terrain that has been dragged towards the southwest. Since the mountain top appears to move faster than the coastline, how do you make the 3D scene “stick” to the mouse cursor?
+
+![](pan_a.png)
+
+![](pan_b.png)
+
+To solve this problem the right way, it helps to leverage a raycaster, even if your actual rendering is done with OpenGL. I also find it helpful to pretend that the mouse cursor lives within the near or far planes of the viewing frustum.
+
+So, if you cast a ray from the camera’s position to the cursor’s position, you’ll hit the point in the scene that needs to be stable during the pan. In the following diagram, we’ve panned the camera from **A** to **B** such that point **C** has remained stable. The cursor at the start of the pan was projected onto the far plane at **E**, and the cursor’s current position corresponds to point **D**.
+
+![](Perfect_Panning.png)
+
+We wish to solve for **B**, given that **A**, **C**, and **E** are known quantities, assuming that your game engine can perform basic raycasts.
+
+What’s less obvious is that **D** is also a known quantity (sort of). At any point in time during the drag, you can project the current mouse position onto the current far plane and get **D**. If you stash **A**, **C**, **E** at the start of the pan and never forget them, then you won’t accumulate error while the user pans.
+
+The next thing to notice is that **ΔCAB** is similar to **ΔCED**. Applying the law of similar triangles yields:
+
+    |A-B| / |A-C| == |E-D| / |E-C|
+
+This allows you to solve for **|A-B|**:
+
+    |A-B| = |A-C| * |E-D| / |E-C|
+
+Thus, we have a “perfect panning” algorithm:
+
+After every mouse-move event, translate the mouse-down camera position **A** in the direction of **(E-D)** by the distance **|A-B|**, as computed above.
+
+It’s even easier to implement perfect zooming, when you wish to zoom in at the mouse cursor while keeping the scene’s geometry stable at the point. Simply move the camera along the ray that goes from the camera’s position to the cursor’s position. It might also be desirable to adjust the speed of the zoom according to the distance between the camera and the nearest point in the scene that the ray hits. Here’s a diagram just for completeness:
+
+![](Zooming.png)
+
+* * *
+
+For complete C code implementing the techniques described in this post, look for “map mode” in [par\_camera\_control.h](https://github.com/prideout/par/blob/master/par_camera_control.h), one of my single-file libraries on GitHub.
+
+[![](https://prideout.net/assets/PublishedLogo.svg)](https://prideout.net)

package/src/engine/graphics/ecs/camera/pp/PerfectPanner.js

@@ -0,0 +1,164 @@
+import Vector3 from "../../../../../core/geom/Vector3.js";
+import { obtainTerrain } from "../../../../ecs/terrain/util/obtainTerrain.js";
+import { SurfacePoint3 } from "../../../../../core/geom/3d/SurfacePoint3.js";
+import { make_ray_from_viewport_position } from "../../../make_ray_from_viewport_position.js";
+import { CameraSystem } from "../CameraSystem.js";
+import Vector2 from "../../../../../core/geom/Vector2.js";
+import { Transform } from "../../../../ecs/transform/Transform.js";
+
+const NEAR_PLANE_INDEX = 5;
+const FAR_PLANE_INDEX = 4;
+
+export class PerfectPanner {
+
+    /**
+     * Point in world space that was under our cursor when we started panning
+     * @type {Vector3}
+     */
+    #grab_world_reference = new Vector3();
+    #grab_near_projection = new Vector3();
+    #grab_far_projection = new Vector3();
+    /**
+     * Camera position at the start
+     * @type {Vector3}
+     */
+    #grab_eye_position = new Vector3();
+
+    /**
+     *
+     * @type {Engine|null}
+     */
+    #engine = null;
+
+
+    /**
+     *
+     * @type {Camera|null}
+     */
+    #camera = null;
+    /**
+     *
+     * @type {Transform|null}
+     */
+    #camera_transform = null;
+
+    /**
+     *
+     * Translation relative to starting point
+     * @type {Vector3}
+     */
+    #translation = new Vector3();
+
+    get engine() {
+        return this.#engine;
+    }
+
+    /**
+     *
+     * @param {Engine} v
+     */
+    set engine(v) {
+        this.#engine = v;
+    }
+
+    /**
+     * @returns {Vector3}
+     */
+    get translation() {
+        return this.#translation;
+    }
+
+    /**
+     *
+     * @param {Vector3} out
+     * @param {number} viewport_x
+     * @param {number} viewport_y
+     * @param {number} plane
+     */
+    #projection_viewport_onto_plane(out, viewport_x, viewport_y, plane) {
+        const engine = this.#engine;
+
+        const ray = make_ray_from_viewport_position(engine, new Vector2(viewport_x, viewport_y));
+
+        this.#camera.rayPlaneIntersection(
+            out,
+            ray.origin.x, ray.origin.y, ray.origin.z,
+            ray.direction.x, ray.direction.y, ray.direction.z,
+            plane
+        );
+    }
+
+    /**
+     *
+     * @param {Vector2} screen_position
+     */
+    update(screen_position) {
+
+        const C = this.#grab_world_reference;
+        const A = this.#grab_eye_position;
+        const E = this.#grab_far_projection;
+
+        //
+        const AC = new Vector3();
+        AC.subVectors(A, C);
+
+        const EC = new Vector3();
+        EC.subVectors(E, C);
+
+
+        const D = new Vector3();
+
+        this.#projection_viewport_onto_plane(D, screen_position.x, screen_position.y, FAR_PLANE_INDEX);
+
+        const translation = new Vector3();
+        translation.subVectors(E, D);
+        translation.multiplyScalar(AC.length() / EC.length());
+
+        this.#translation.copy(translation);
+    }
+
+    start(screen_position) {
+
+        // obtain reference point
+
+        const engine = this.#engine;
+
+        const ecd = engine.entityManager.dataset;
+
+        if (ecd === null) {
+            throw new Error('No dataset');
+        }
+
+        // bind camera
+        const camera = CameraSystem.getFirstActiveCamera(ecd);
+        this.#camera = camera.component;
+        this.#camera_transform = ecd.getComponent(camera.entity, Transform);
+
+
+        this.#projection_viewport_onto_plane(this.#grab_near_projection, screen_position.x, screen_position.y, NEAR_PLANE_INDEX);
+        this.#projection_viewport_onto_plane(this.#grab_far_projection, screen_position.x, screen_position.y, FAR_PLANE_INDEX);
+
+        const ray = make_ray_from_viewport_position(engine, screen_position);
+
+        const terrain = obtainTerrain(ecd);
+
+        const hit = new SurfacePoint3();
+
+        if (terrain.raycastFirstSync(hit,
+            ray.origin.x, ray.origin.y, ray.origin.z,
+            ray.direction.x, ray.direction.y, ray.direction.z
+        )) {
+            // got terrain hit
+            this.#grab_world_reference.copy(hit.position);
+        }
+
+        this.#grab_eye_position.copy(this.#camera_transform.position);
+
+        this.#translation.set(0, 0, 0);
+    }
+
+    end() {
+
+    }
+
+}

package/src/engine/graphics/ecs/mesh/MeshSystem.js

@@ -424,7 +424,7 @@ export class MeshSystem extends System {
             }
         }
 
-        em.getComponentAsync(entity, Transform, component.internalApplyTransform, component);
+        dataset.getComponentAsync(entity, Transform, component.internalApplyTransform, component);
     }
 
     update(timeDelta) {

package/src/engine/graphics/make_ray_from_viewport_position.js

@@ -0,0 +1,28 @@
+import Vector2 from "../../core/geom/Vector2.js";
+import Vector3 from "../../core/geom/Vector3.js";
+
+/**
+ *
+ * @param {Engine} engine
+ * @param {Vector2} [position] if not specified, current pointer position will be used
+ * @returns {{origin:Vector3, direction:Vector3}}
+ */
+export function make_ray_from_viewport_position(engine, position) {
+
+    let _p = position;
+
+    if (position === undefined) {
+        _p = engine.devices.pointer.position;
+    }
+
+    const ndc = new Vector2();
+
+    engine.graphics.normalizeViewportPoint(_p, ndc);
+
+    const origin = new Vector3();
+    const direction = new Vector3();
+
+    engine.graphics.viewportProjectionRay(ndc.x, ndc.y, origin, direction);
+
+    return { origin, direction };
+}

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

@@ -8,6 +8,7 @@ import { assert } from "../../../core/assert.js";
 import { MouseEvents } from "./events/MouseEvents.js";
 import { TouchEvents } from "./events/TouchEvents.js";
 import { sign } from "../../../core/math/sign.js";
+import { InputDeviceSwitch } from "./InputDeviceSwitch.js";
 
 /**
  * @see https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/buttons
@@ -371,6 +372,13 @@ export class PointerDevice {
      */
     isRunning = false;
 
+    /**
+     * The MouseEvent.buttons is a 32bit field, which means we can encode up to 32 buttons
+     * @readonly
+     * @type {InputDeviceSwitch[]}
+     */
+    buttons = new Array(32);
+
     /**
      *
      * @param {EventTarget} domElement html element
@@ -379,6 +387,10 @@ export class PointerDevice {
     constructor(domElement) {
         assert.defined(domElement, "domElement");
 
+        // initialize buttons
+        for (let i = 0; i < this.buttons.length; i++) {
+            this.buttons[i] = new InputDeviceSwitch();
+        }
 
         /**
          *
@@ -420,6 +432,16 @@ export class PointerDevice {
     #eventHandlerMouseDown = (event) => {
         this.readPointerPositionFromEvent(this.position, event);
         this.on.down.send2(this.position, event);
+
+        // update button state and dispatch specific signal
+        const button_index = event.button;
+
+        const button = this.buttons[button_index];
+
+        if (button !== undefined) {
+            button.is_down = true;
+            button.down.send0();
+        }
     }
 
     /**
@@ -447,6 +469,16 @@ export class PointerDevice {
     #eventHandlerGlobalMouseUp = (event) => {
         this.readPointerPositionFromEvent(this.position, event);
         this.#globalUp.send2(this.position, event);
+
+        // update button state and dispatch specific signal
+        const button_index = event.button;
+
+        const button = this.buttons[button_index];
+
+        if (button !== undefined) {
+            button.is_down = false;
+            button.up.send0();
+        }
     }
 
     /**