@blorkfield/overlay-core 0.7.0 → 0.8.0

package/dist/index.cjs

@@ -899,12 +899,6 @@ function clearFontCache() {
 
 // src/entity.ts
 var import_matter_js3 = __toESM(require("matter-js"), 1);
-var MOUSE_FORCE = 1e-3;
-function applyMouseForce(entity, mouseX, grounded) {
-  if (!grounded) return;
-  const direction = Math.sign(mouseX - entity.position.x);
-  import_matter_js3.default.Body.applyForce(entity, entity.position, { x: MOUSE_FORCE * direction, y: 0 });
-}
 function wrapHorizontal(entity, bounds) {
   if (entity.position.x < bounds.left) {
     import_matter_js3.default.Body.setPosition(entity, { x: bounds.right, y: entity.position.y });
@@ -1425,7 +1419,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;
@@ -1442,6 +1435,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;
@@ -1491,17 +1492,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);
+                  import_matter_js5.default.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);
@@ -1575,6 +1607,7 @@ var OverlayScene = class {
     }
     import_matter_js5.default.Events.on(this.render, "beforeRender", this.handleBeforeRender);
     import_matter_js5.default.Events.on(this.render, "afterRender", this.handleAfterRender);
+    import_matter_js5.default.Events.on(this.engine, "collisionStart", this.handleCollisionStart);
   }
   static createContainer(parent, options = {}) {
     const canvas = document.createElement("canvas");
@@ -1979,6 +2012,7 @@ var OverlayScene = class {
     this.canvas.removeEventListener("click", this.handleCanvasClick);
     import_matter_js5.default.Events.off(this.render, "beforeRender", this.handleBeforeRender);
     import_matter_js5.default.Events.off(this.render, "afterRender", this.handleAfterRender);
+    import_matter_js5.default.Events.off(this.engine, "collisionStart", this.handleCollisionStart);
     import_matter_js5.default.Engine.clear(this.engine);
     this.objects.clear();
     this.obstaclePressure.clear();
@@ -1987,6 +2021,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;
@@ -2101,6 +2139,7 @@ var OverlayScene = class {
     if (isStatic && pressureThreshold !== void 0) {
       this.obstaclePressure.set(id, /* @__PURE__ */ new Set());
     }
+    this.emitLifecycleEvent("objectSpawned", this.toObjectState(entry));
     return id;
   }
   /**
@@ -2156,6 +2195,7 @@ var OverlayScene = class {
     if (isStatic && pressureThreshold !== void 0) {
       this.obstaclePressure.set(id, /* @__PURE__ */ new Set());
     }
+    this.emitLifecycleEvent("objectSpawned", this.toObjectState(entry));
     return id;
   }
   /**
@@ -2237,6 +2277,7 @@ var OverlayScene = class {
   removeObject(id) {
     const entry = this.objects.get(id);
     if (!entry) return;
+    this.emitLifecycleEvent("objectRemoved", this.toObjectState(entry));
     import_matter_js5.default.Composite.remove(this.engine.world, entry.body);
     this.objects.delete(id);
   }
@@ -2286,8 +2327,156 @@ 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 });
+  }
+  /**
+   * 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());
+  }
+  // ==================== 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;
+    import_matter_js5.default.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)) {
+        import_matter_js5.default.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;
+    import_matter_js5.default.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;
+    import_matter_js5.default.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 ====================
   /**