@blorkfield/overlay-core 0.7.1 → 0.8.1

package/dist/index.js

@@ -854,12 +854,6 @@ function clearFontCache() {
 
 // src/entity.ts
 import Matter3 from "matter-js";
-var MOUSE_FORCE = 1e-3;
-function applyMouseForce(entity, mouseX, grounded) {
-  if (!grounded) return;
-  const direction = Math.sign(mouseX - entity.position.x);
-  Matter3.Body.applyForce(entity, entity.position, { x: MOUSE_FORCE * direction, y: 0 });
-}
 function wrapHorizontal(entity, bounds) {
   if (entity.position.x < bounds.left) {
     Matter3.Body.setPosition(entity, { x: bounds.right, y: entity.position.y });
@@ -1380,7 +1374,6 @@ var OverlayScene = class {
     this.objects = /* @__PURE__ */ new Map();
     this.boundaries = [];
     this.updateCallbacks = [];
-    this.mouseX = 0;
     this.animationFrameId = null;
     this.mouse = null;
     this.mouseConstraint = null;
@@ -1397,6 +1390,14 @@ var OverlayScene = class {
     this.floorSegmentPressure = /* @__PURE__ */ new Map();
     // segment index -> object IDs
     this.collapsedSegments = /* @__PURE__ */ new Set();
+    // Lifecycle event callbacks
+    this.lifecycleCallbacks = {
+      objectSpawned: [],
+      objectRemoved: [],
+      objectCollision: []
+    };
+    // Follow targets for follow-{key} tagged objects
+    this.followTargets = /* @__PURE__ */ new Map();
     /** Filter drag events - only allow grabbing objects with 'grabable' tag */
     this.handleStartDrag = (event) => {
       const body = event.body;
@@ -1446,17 +1447,48 @@ var OverlayScene = class {
     this.handleAfterRender = () => {
       this.backgroundManager.renderOverlay();
     };
+    /**
+     * Handler for Matter.js collision events.
+     * Emits objectCollision lifecycle events.
+     */
+    this.handleCollisionStart = (event) => {
+      for (const pair of event.pairs) {
+        const entryA = this.findObjectByBody(pair.bodyA);
+        const entryB = this.findObjectByBody(pair.bodyB);
+        if (entryA && entryB) {
+          this.emitLifecycleEvent(
+            "objectCollision",
+            this.toObjectState(entryA),
+            this.toObjectState(entryB)
+          );
+        }
+      }
+    };
     // ==================== PRIVATE ====================
     this.loop = () => {
       this.effectManager.update();
       this.checkTTLExpiration();
       this.checkDespawnBelowFloor();
       this.updatePressure();
-      const mouseX = this.mouse?.position.x ?? this.mouseX;
+      if (!this.followTargets.has("mouse") && this.mouse) {
+        this.followTargets.set("mouse", { x: this.mouse.position.x, y: this.mouse.position.y });
+      }
       for (const entry of this.objects.values()) {
         const isDragging = this.mouseConstraint?.body === entry.body;
-        if (!isDragging && entry.tags.includes("follow")) {
-          applyMouseForce(entry.body, mouseX, this.isGrounded(entry.body));
+        if (!isDragging) {
+          for (const tag of entry.tags) {
+            const key = tag === "follow" ? "mouse" : tag.startsWith("follow-") ? tag.slice(7) : null;
+            if (key) {
+              const target = this.followTargets.get(key);
+              if (target) {
+                const grounded = this.isGrounded(entry.body);
+                if (grounded) {
+                  const direction = Math.sign(target.x - entry.body.position.x);
+                  Matter5.Body.applyForce(entry.body, entry.body.position, { x: 1e-3 * direction, y: 0 });
+                }
+              }
+            }
+          }
         }
         if (this.config.wrapHorizontal && entry.tags.includes("falling")) {
           wrapHorizontal(entry.body, this.config.bounds);
@@ -1530,6 +1562,7 @@ var OverlayScene = class {
     }
     Matter5.Events.on(this.render, "beforeRender", this.handleBeforeRender);
     Matter5.Events.on(this.render, "afterRender", this.handleAfterRender);
+    Matter5.Events.on(this.engine, "collisionStart", this.handleCollisionStart);
   }
   static createContainer(parent, options = {}) {
     const canvas = document.createElement("canvas");
@@ -1934,6 +1967,7 @@ var OverlayScene = class {
     this.canvas.removeEventListener("click", this.handleCanvasClick);
     Matter5.Events.off(this.render, "beforeRender", this.handleBeforeRender);
     Matter5.Events.off(this.render, "afterRender", this.handleAfterRender);
+    Matter5.Events.off(this.engine, "collisionStart", this.handleCollisionStart);
     Matter5.Engine.clear(this.engine);
     this.objects.clear();
     this.obstaclePressure.clear();
@@ -1942,6 +1976,10 @@ var OverlayScene = class {
     this.floorSegmentPressure.clear();
     this.collapsedSegments.clear();
     this.updateCallbacks = [];
+    this.lifecycleCallbacks.objectSpawned = [];
+    this.lifecycleCallbacks.objectRemoved = [];
+    this.lifecycleCallbacks.objectCollision = [];
+    this.followTargets.clear();
   }
   setDebug(enabled) {
     this.config.debug = enabled;
@@ -2056,6 +2094,7 @@ var OverlayScene = class {
     if (isStatic && pressureThreshold !== void 0) {
       this.obstaclePressure.set(id, /* @__PURE__ */ new Set());
     }
+    this.emitLifecycleEvent("objectSpawned", this.toObjectState(entry));
     return id;
   }
   /**
@@ -2111,6 +2150,7 @@ var OverlayScene = class {
     if (isStatic && pressureThreshold !== void 0) {
       this.obstaclePressure.set(id, /* @__PURE__ */ new Set());
     }
+    this.emitLifecycleEvent("objectSpawned", this.toObjectState(entry));
     return id;
   }
   /**
@@ -2192,6 +2232,7 @@ var OverlayScene = class {
   removeObject(id) {
     const entry = this.objects.get(id);
     if (!entry) return;
+    this.emitLifecycleEvent("objectRemoved", this.toObjectState(entry));
     Matter5.Composite.remove(this.engine.world, entry.body);
     this.objects.delete(id);
   }
@@ -2241,8 +2282,208 @@ var OverlayScene = class {
     }
     return Array.from(tagsSet).sort();
   }
-  setMousePosition(x, _y) {
-    this.mouseX = x;
+  /**
+   * Set the mouse position for follow behavior.
+   * This overrides the browser mouse position for the 'follow' and 'follow-mouse' tags.
+   * @deprecated Use setFollowTarget('mouse', x, y) instead
+   */
+  setMousePosition(x, y) {
+    this.setFollowTarget("mouse", x, y);
+  }
+  /**
+   * Set a follow target position. Objects with 'follow-{key}' tag will
+   * automatically move toward this target each frame.
+   * @param key - The target key (e.g., 'absolute' for 'follow-absolute' tag)
+   * @param x - Target X position
+   * @param y - Target Y position
+   */
+  setFollowTarget(key, x, y) {
+    this.followTargets.set(key, { x, y });
+    if (key === "mouse" && this.mouse) {
+      this.mouse.position.x = x;
+      this.mouse.position.y = y;
+      this.mouse.absolute.x = x;
+      this.mouse.absolute.y = y;
+    }
+  }
+  /**
+   * Remove a follow target. Objects with the corresponding tag will stop following.
+   * @param key - The target key to remove
+   */
+  removeFollowTarget(key) {
+    this.followTargets.delete(key);
+  }
+  /**
+   * Get all registered follow target keys.
+   * @returns Array of follow target keys
+   */
+  getFollowTargetKeys() {
+    return Array.from(this.followTargets.keys());
+  }
+  // ==================== GRAB/DRAG METHODS ====================
+  /**
+   * Programmatically grab an object at the current mouse position.
+   * Uses the externally set mouse position (via setFollowTarget('mouse', x, y))
+   * or the native canvas mouse position if no external position is set.
+   * Only objects with the 'grabable' tag can be grabbed.
+   * @returns The ID of the grabbed object, or null if no grabable object at position
+   */
+  startGrab() {
+    if (!this.mouseConstraint || !this.mouse) return null;
+    const mouseTarget = this.followTargets.get("mouse");
+    const position = mouseTarget ?? { x: this.mouse.position.x, y: this.mouse.position.y };
+    const bodies = Matter5.Query.point(
+      Matter5.Composite.allBodies(this.engine.world),
+      position
+    );
+    for (const body of bodies) {
+      const entry = this.findObjectByBody(body);
+      if (entry && entry.tags.includes("grabable")) {
+        this.mouseConstraint.constraint.bodyB = entry.body;
+        this.mouseConstraint.constraint.pointB = {
+          x: position.x - entry.body.position.x,
+          y: position.y - entry.body.position.y
+        };
+        return entry.id;
+      }
+    }
+    return null;
+  }
+  /**
+   * Release any currently grabbed object.
+   */
+  endGrab() {
+    if (this.mouseConstraint) {
+      this.mouseConstraint.constraint.bodyB = null;
+    }
+  }
+  /**
+   * Get the ID of the currently grabbed object.
+   * @returns The ID of the grabbed object, or null if nothing is grabbed
+   */
+  getGrabbedObject() {
+    if (!this.mouseConstraint?.constraint.bodyB) return null;
+    const entry = this.findObjectByBody(this.mouseConstraint.constraint.bodyB);
+    return entry?.id ?? null;
+  }
+  // ==================== PHYSICS MANIPULATION METHODS ====================
+  /**
+   * Apply a force to an object.
+   * @param objectId - The ID of the object
+   * @param force - The force vector to apply
+   */
+  applyForce(objectId, force) {
+    const entry = this.objects.get(objectId);
+    if (!entry) return;
+    Matter5.Body.applyForce(entry.body, entry.body.position, force);
+  }
+  /**
+   * Apply a force to all objects with a specific tag.
+   * @param tag - The tag to match
+   * @param force - The force vector to apply
+   */
+  applyForceToTag(tag, force) {
+    for (const entry of this.objects.values()) {
+      if (entry.tags.includes(tag)) {
+        Matter5.Body.applyForce(entry.body, entry.body.position, force);
+      }
+    }
+  }
+  /**
+   * Set the velocity of an object.
+   * @param objectId - The ID of the object
+   * @param velocity - The velocity vector to set
+   */
+  setVelocity(objectId, velocity) {
+    const entry = this.objects.get(objectId);
+    if (!entry) return;
+    Matter5.Body.setVelocity(entry.body, velocity);
+  }
+  /**
+   * Set the position of an object.
+   * @param objectId - The ID of the object
+   * @param position - The position to set
+   */
+  setPosition(objectId, position) {
+    const entry = this.objects.get(objectId);
+    if (!entry) return;
+    Matter5.Body.setPosition(entry.body, position);
+  }
+  // ==================== OBJECT STATE METHODS ====================
+  /**
+   * Get the current state of an object.
+   * @param id - The ID of the object
+   * @returns The object state, or null if not found
+   */
+  getObject(id) {
+    const entry = this.objects.get(id);
+    if (!entry) return null;
+    return {
+      id: entry.id,
+      x: entry.body.position.x,
+      y: entry.body.position.y,
+      velocity: { x: entry.body.velocity.x, y: entry.body.velocity.y },
+      angle: entry.body.angle,
+      tags: [...entry.tags]
+    };
+  }
+  /**
+   * Get the current state of all objects with a specific tag.
+   * @param tag - The tag to match
+   * @returns Array of object states
+   */
+  getObjectsByTag(tag) {
+    const result = [];
+    for (const entry of this.objects.values()) {
+      if (entry.tags.includes(tag)) {
+        result.push({
+          id: entry.id,
+          x: entry.body.position.x,
+          y: entry.body.position.y,
+          velocity: { x: entry.body.velocity.x, y: entry.body.velocity.y },
+          angle: entry.body.angle,
+          tags: [...entry.tags]
+        });
+      }
+    }
+    return result;
+  }
+  // ==================== LIFECYCLE EVENTS ====================
+  /**
+   * Subscribe to a lifecycle event.
+   * @param event - The event type to subscribe to
+   * @param callback - The callback to invoke when the event occurs
+   */
+  on(event, callback) {
+    this.lifecycleCallbacks[event].push(callback);
+  }
+  /**
+   * Unsubscribe from a lifecycle event.
+   * @param event - The event type to unsubscribe from
+   * @param callback - The callback to remove
+   */
+  off(event, callback) {
+    const arr = this.lifecycleCallbacks[event];
+    const idx = arr.indexOf(callback);
+    if (idx !== -1) arr.splice(idx, 1);
+  }
+  /** Create ObjectState from an ObjectEntry */
+  toObjectState(entry) {
+    return {
+      id: entry.id,
+      x: entry.body.position.x,
+      y: entry.body.position.y,
+      velocity: { x: entry.body.velocity.x, y: entry.body.velocity.y },
+      angle: entry.body.angle,
+      tags: [...entry.tags]
+    };
+  }
+  /** Emit a lifecycle event to all registered callbacks */
+  emitLifecycleEvent(event, ...args) {
+    const callbacks = this.lifecycleCallbacks[event];
+    for (const cb of callbacks) {
+      cb(...args);
+    }
   }
   // ==================== PRESSURE TRACKING METHODS ====================
   /**