@blorkfield/overlay-core 0.10.0 → 0.11.0

package/README.md

@@ -381,6 +381,26 @@ scene.setEffect({
 });
 ```
 
+### Managing Effects
+
+```typescript
+// Pause/resume an effect without removing it
+scene.setEffectEnabled('my-rain', false);  // pause
+scene.setEffectEnabled('my-rain', true);   // resume
+
+// Check if an effect is enabled
+scene.isEffectEnabled('my-rain');  // → true/false
+
+// Get effect config
+const effect = scene.getEffect('my-rain');  // → EffectConfig | undefined
+
+// List all effect IDs
+const ids = scene.getEffectIds();  // → string[]
+
+// Remove an effect entirely
+scene.removeEffect('my-rain');
+```
+
 ## Managing Objects
 
 ```typescript
@@ -608,7 +628,7 @@ scene.on('objectRemoved', (obj) => {
   console.log(`Removed: ${obj.id}`);
 });
 
-// Objects collided
+// Objects collided (fires on collision start)
 scene.on('objectCollision', (a, b) => {
   console.log(`Collision: ${a.id} hit ${b.id}`);
 });
@@ -617,6 +637,23 @@ scene.on('objectCollision', (a, b) => {
 scene.off('objectSpawned', myCallback);
 ```
 
+### Querying Active Collisions
+
+The scene tracks which objects are currently in contact, so you can query collision state at any time without maintaining your own bookkeeping:
+
+```typescript
+// Get all object IDs currently touching a specific object
+const touching = scene.getCollidingWith('my-object-id'); // string[]
+
+// Get all active collision pairs
+const pairs = scene.getActiveCollisions(); // Array<{ a: string, b: string }>
+for (const { a, b } of pairs) {
+  console.log(`${a} is touching ${b}`);
+}
+```
+
+These reflect live physics state — pairs are added on `collisionStart` and removed on `collisionEnd`. Only tracked objects are included (floor, boundaries, and DOM obstacles are excluded).
+
 ## Font Setup
 
 ### Bundled Fonts
@@ -820,6 +857,23 @@ scene.setObjectMassOverride(id, 50);   // now heavy
 scene.setObjectMassOverride(id, null); // restore natural mass
 ```
 
+### Scale
+
+`setObjectScale(id, x, y)` resizes an object at runtime. Both the physics collision shape and sprite rendering are updated together. Scale is absolute — calling `setObjectScale(id, 2, 2)` always doubles the original size regardless of current scale. Scaling also changes body mass proportionally (area scales by x×y); use `setObjectMassOverride` after if you need a fixed mass.
+
+```typescript
+// Uniform scale
+scene.setObjectScale(id, 2, 2);    // double size
+scene.setObjectScale(id, 0.5, 0.5); // half size
+
+// Non-uniform scale (independent x and y)
+scene.setObjectScale(id, 3, 1);    // stretch wide, keep height
+scene.setObjectScale(id, 1, 0.5);  // squash vertically
+
+// Restore original size
+scene.setObjectScale(id, 1, 1);
+```
+
 ## Examples
 
 Working examples are provided in the `/examples` directory:
@@ -863,6 +917,11 @@ import type {
   TTFTextObstacleConfig,
   TextAlign,
   TextBounds,
+  LetterDebugInfo,
+
+  // DOM obstacle types
+  DOMObstacleConfig,
+  DOMObstacleResult,
 
   // Effect types
   EffectConfig,
@@ -905,5 +964,5 @@ import type {
 } from '@blorkfield/overlay-core';
 
 // Tag constants (values, not types)
-import { TAGS, TAG_FALLING, TAG_GRABABLE, TAG_FOLLOW_WINDOW, TAG_GRAVITY_OVERRIDE } from '@blorkfield/overlay-core';
+import { TAGS, TAG_STATIC, TAG_GRABABLE, TAG_FOLLOW_WINDOW, TAG_GRAVITY_OVERRIDE, TAG_SPEED_OVERRIDE, TAG_MASS_OVERRIDE } from '@blorkfield/overlay-core';
 ```

package/dist/index.cjs

@@ -1466,6 +1466,8 @@ var OverlayScene = class {
     this.followWindowEntries = /* @__PURE__ */ new Set();
     // IDs of static objects that have pressure thresholds — empty = skip updatePressure entirely
     this.pressureObstacleIds = /* @__PURE__ */ new Set();
+    // Active collision pairs: id -> Set of ids currently colliding with it
+    this.activeCollisions = /* @__PURE__ */ new Map();
     /** Handle mouse down - start grab via programmatic API */
     this.handleMouseDown = (event) => {
       const rect = this.canvas.getBoundingClientRect();
@@ -1532,6 +1534,10 @@ var OverlayScene = class {
         const entryA = this.findObjectByBody(pair.bodyA);
         const entryB = this.findObjectByBody(pair.bodyB);
         if (entryA && entryB) {
+          if (!this.activeCollisions.has(entryA.id)) this.activeCollisions.set(entryA.id, /* @__PURE__ */ new Set());
+          if (!this.activeCollisions.has(entryB.id)) this.activeCollisions.set(entryB.id, /* @__PURE__ */ new Set());
+          this.activeCollisions.get(entryA.id).add(entryB.id);
+          this.activeCollisions.get(entryB.id).add(entryA.id);
           this.emitLifecycleEvent(
             "objectCollision",
             this.toObjectState(entryA),
@@ -1540,6 +1546,16 @@ var OverlayScene = class {
         }
       }
     };
+    this.handleCollisionEnd = (event) => {
+      for (const pair of event.pairs) {
+        const entryA = this.findObjectByBody(pair.bodyA);
+        const entryB = this.findObjectByBody(pair.bodyB);
+        if (entryA && entryB) {
+          this.activeCollisions.get(entryA.id)?.delete(entryB.id);
+          this.activeCollisions.get(entryB.id)?.delete(entryA.id);
+        }
+      }
+    };
     // ==================== PRIVATE ====================
     this.loop = () => {
       const substepDelta = 1e3 / 60 / this.substeps;
@@ -1668,6 +1684,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);
+    import_matter_js5.default.Events.on(this.engine, "collisionEnd", this.handleCollisionEnd);
   }
   static createContainer(parent, options = {}) {
     const canvas = document.createElement("canvas");
@@ -2071,6 +2088,7 @@ var OverlayScene = class {
     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.Events.off(this.engine, "collisionEnd", this.handleCollisionEnd);
     import_matter_js5.default.Engine.clear(this.engine);
     this.objects.clear();
     this.gravityOverrideEntries.clear();
@@ -2081,6 +2099,7 @@ var OverlayScene = class {
     this.pressureLogTimer = 0;
     this.floorSegmentPressure.clear();
     this.collapsedSegments.clear();
+    this.activeCollisions.clear();
     this.updateCallbacks = [];
     this.lifecycleCallbacks.objectSpawned = [];
     this.lifecycleCallbacks.objectRemoved = [];
@@ -2532,6 +2551,13 @@ var OverlayScene = class {
     this.gravityOverrideEntries.delete(entry);
     this.followWindowEntries.delete(entry);
     this.pressureObstacleIds.delete(id);
+    const colliding = this.activeCollisions.get(id);
+    if (colliding) {
+      for (const otherId of colliding) {
+        this.activeCollisions.get(otherId)?.delete(id);
+      }
+      this.activeCollisions.delete(id);
+    }
     this.objects.delete(id);
   }
   removeObjects(ids) {
@@ -2781,6 +2807,32 @@ var OverlayScene = class {
     const idx = arr.indexOf(callback);
     if (idx !== -1) arr.splice(idx, 1);
   }
+  /**
+   * Get the IDs of all objects currently colliding with a given object.
+   * @param id - The ID of the object to query
+   * @returns Array of IDs of objects currently in contact with it
+   */
+  getCollidingWith(id) {
+    return Array.from(this.activeCollisions.get(id) ?? []);
+  }
+  /**
+   * Get all currently active collision pairs.
+   * @returns Array of `{ a, b }` pairs where `a` and `b` are colliding object IDs
+   */
+  getActiveCollisions() {
+    const pairs = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const [id, others] of this.activeCollisions) {
+      for (const otherId of others) {
+        const key = id < otherId ? `${id}:${otherId}` : `${otherId}:${id}`;
+        if (!seen.has(key)) {
+          seen.add(key);
+          pairs.push({ a: id, b: otherId });
+        }
+      }
+    }
+    return pairs;
+  }
   /** Create ObjectState from an ObjectEntry */
   toObjectState(entry) {
     return {