@blorkfield/overlay-core 0.8.11 → 0.10.0

package/dist/index.js

@@ -5,7 +5,8 @@ import Matter5 from "matter-js";
 import Matter from "matter-js";
 function createEngine(gravity) {
   const engine = Matter.Engine.create();
-  engine.gravity.y = gravity;
+  engine.gravity.x = gravity.x;
+  engine.gravity.y = -gravity.y;
   return engine;
 }
 function createRender(engine, canvas, config) {
@@ -455,6 +456,7 @@ function createBodyFromVertices(id, x, y, vertices, renderOptions) {
     restitution: 0.3,
     friction: 0.1,
     frictionAir: 0.01,
+    density: 5e-3,
     label: `entity:${id}`,
     render: renderOptions
   });
@@ -547,6 +549,7 @@ function createCircleEntity(id, config) {
     restitution: 0.3,
     friction: 0.1,
     frictionAir: 0.01,
+    density: 5e-3,
     label: `entity:${id}`,
     render: createFillRenderOptions(config)
   });
@@ -558,6 +561,7 @@ function createCircleEntityWithSprite(id, config, imageWidth, imageHeight) {
     restitution: 0.3,
     friction: 0.1,
     frictionAir: 0.01,
+    density: 5e-3,
     label: `entity:${id}`,
     render: createSpriteRenderOptions(config, imageWidth, imageHeight)
   });
@@ -988,8 +992,7 @@ var EffectManager = class {
       const objectConfig = this.selectObjectConfig(config.objectConfigs);
       if (!objectConfig) continue;
       const radius = this.calculateRadius(objectConfig);
-      const tags = [...objectConfig.objectConfig.tags ?? []];
-      if (!tags.includes("falling")) tags.push("falling");
+      const tags = (objectConfig.objectConfig.tags ?? []).filter((t) => t !== "static");
       const fullConfig = {
         ...objectConfig.objectConfig,
         x: originX,
@@ -1028,8 +1031,7 @@ var EffectManager = class {
     const radius = this.calculateRadius(objectConfig);
     const x = this.randomInRange(spawnAreaStart + radius, spawnAreaStart + spawnAreaWidth - radius);
     const y = bounds.top - radius;
-    const tags = [...objectConfig.objectConfig.tags ?? []];
-    if (!tags.includes("falling")) tags.push("falling");
+    const tags = (objectConfig.objectConfig.tags ?? []).filter((t) => t !== "static");
     const fullConfig = {
       ...objectConfig.objectConfig,
       x,
@@ -1054,8 +1056,7 @@ var EffectManager = class {
     const objectConfig = this.selectObjectConfig(config.objectConfigs);
     if (!objectConfig) return;
     const radius = this.calculateRadius(objectConfig);
-    const tags = [...objectConfig.objectConfig.tags ?? []];
-    if (!tags.includes("falling")) tags.push("falling");
+    const tags = (objectConfig.objectConfig.tags ?? []).filter((t) => t !== "static");
     const fullConfig = {
       ...objectConfig.objectConfig,
       x: config.origin.x,
@@ -1407,6 +1408,12 @@ var OverlayScene = class {
     this.grabHistoryRadius = 20;
     // Number of physics substeps per frame — more substeps = better collision at high speeds, more CPU
     this.substeps = 2;
+    // Tracks only the bodies with a gravity override — engine gravity handles everyone else
+    this.gravityOverrideEntries = /* @__PURE__ */ new Set();
+    // Tracks only the bodies with follow_window tag — avoids scanning all objects each frame
+    this.followWindowEntries = /* @__PURE__ */ new Set();
+    // IDs of static objects that have pressure thresholds — empty = skip updatePressure entirely
+    this.pressureObstacleIds = /* @__PURE__ */ new Set();
     /** Handle mouse down - start grab via programmatic API */
     this.handleMouseDown = (event) => {
       const rect = this.canvas.getBoundingClientRect();
@@ -1438,7 +1445,7 @@ var OverlayScene = class {
       for (const body of bodies) {
         const entry = this.findObjectByBody(body);
         if (!entry) continue;
-        if (entry.tags.includes("falling")) continue;
+        if (!entry.tags.includes("static")) continue;
         if (entry.clicksRemaining === void 0) continue;
         entry.clicksRemaining--;
         const name = this.getObstacleDisplayName(entry);
@@ -1484,13 +1491,23 @@ var OverlayScene = class {
     // ==================== PRIVATE ====================
     this.loop = () => {
       const substepDelta = 1e3 / 60 / this.substeps;
+      const scale = this.engine.gravity.scale;
       for (let i = 0; i < this.substeps; i++) {
+        for (const entry of this.gravityOverrideEntries) {
+          if (entry.body.isStatic || entry.body.isSleeping) continue;
+          const g = entry.gravityOverride;
+          Matter5.Body.applyForce(entry.body, entry.body.position, {
+            x: entry.body.mass * (g.x - this.engine.gravity.x) * scale,
+            y: entry.body.mass * (g.y - this.engine.gravity.y) * scale
+          });
+        }
         Matter5.Engine.update(this.engine, substepDelta);
       }
       this.effectManager.update();
-      this.checkTTLExpiration();
-      this.checkDespawnBelowFloor();
-      this.updatePressure();
+      this.checkExpiration();
+      if (this.pressureObstacleIds.size > 0 || this.floorSegments.length > 0) {
+        this.updatePressure();
+      }
       if (this.grabbedObjectId && this.lastGrabMousePosition) {
         const entry = this.objects.get(this.grabbedObjectId);
         const mouseTarget = this.followTargets.get("mouse");
@@ -1504,27 +1521,39 @@ var OverlayScene = class {
           this.lastGrabMousePosition = { x: mouseTarget.x, y: mouseTarget.y };
         }
       }
-      for (const entry of this.objects.values()) {
-        const isDragging = this.grabbedObjectId === entry.id;
-        if (!isDragging) {
-          for (const tag of entry.tags) {
-            const key = tag === "follow_window" ? "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 });
-                }
-              }
+      for (const entry of this.followWindowEntries) {
+        if (this.grabbedObjectId === entry.id) continue;
+        const targetKey = entry.followTarget ?? "mouse";
+        let targetPos;
+        targetPos = this.followTargets.get(targetKey);
+        if (!targetPos) {
+          const targetEntry = this.objects.get(targetKey);
+          if (targetEntry) targetPos = targetEntry.body.position;
+        }
+        if (!targetPos) {
+          for (const e of this.objects.values()) {
+            if (e !== entry && e.tags.includes(targetKey)) {
+              targetPos = e.body.position;
+              break;
             }
           }
         }
-        if (this.config.wrapHorizontal && entry.tags.includes("falling")) {
+        if (targetPos) {
+          const dx = targetPos.x - entry.body.position.x;
+          const dy = targetPos.y - entry.body.position.y;
+          const dist = Math.sqrt(dx * dx + dy * dy);
+          if (dist > 0) {
+            const speedMult = entry.speedOverride ?? 1;
+            const mag = 1e-3 * speedMult / dist;
+            Matter5.Body.applyForce(entry.body, entry.body.position, { x: mag * dx, y: mag * dy });
+          }
+        }
+      }
+      for (const entry of this.objects.values()) {
+        if (this.config.wrapHorizontal && !entry.tags.includes("static")) {
           wrapHorizontal(entry.body, this.config.bounds);
         }
-        if (entry.domElement && entry.tags.includes("falling")) {
+        if (entry.domElement && !entry.tags.includes("static")) {
           this.updateDOMElementTransform(entry);
         }
         if (entry.tags.includes("grabable") && !entry.body.isStatic) {
@@ -1547,7 +1576,7 @@ var OverlayScene = class {
     };
     this.canvas = canvas;
     this.config = {
-      gravity: 1,
+      gravity: { x: 0, y: -1 },
       wrapHorizontal: true,
       debug: false,
       ...config
@@ -1621,7 +1650,7 @@ var OverlayScene = class {
     const obstacles = [];
     const dynamics = [];
     for (const entry of this.objects.values()) {
-      if (entry.tags.includes("falling")) {
+      if (!entry.tags.includes("static")) {
         if (Math.abs(entry.body.velocity.y) < 2) {
           dynamics.push(entry);
         }
@@ -1844,16 +1873,17 @@ var OverlayScene = class {
   }
   /** Convert a static obstacle to dynamic (make it fall) */
   collapseObstacle(entry) {
-    if (entry.tags.includes("falling")) return;
+    if (!entry.tags.includes("static")) return;
     const name = this.getObstacleDisplayName(entry);
     console.log(`[Pressure] Collapsed: ${name}`);
     if (entry.shadow && entry.originalPosition) {
       this.createShadow(entry);
     }
-    entry.tags.push("falling");
+    entry.tags = entry.tags.filter((t) => t !== "static");
     Matter5.Body.setStatic(entry.body, false);
     entry.pressureThreshold = void 0;
     entry.wordCollapseTag = void 0;
+    this.pressureObstacleIds.delete(entry.id);
   }
   /** Create a static shadow copy of an obstacle at its original position */
   async createShadow(entry) {
@@ -1898,6 +1928,7 @@ var OverlayScene = class {
         id: shadowId,
         body,
         tags: ["shadow"],
+        entityTag: shadowId,
         spawnTime: performance.now(),
         weight: 0,
         ttfGlyph: {
@@ -1925,6 +1956,7 @@ var OverlayScene = class {
       id: shadowId,
       body: result.body,
       tags: ["shadow"],
+      entityTag: shadowId,
       spawnTime: performance.now(),
       weight: 0
       // Shadows don't contribute to pressure
@@ -1966,10 +1998,6 @@ var OverlayScene = class {
     }
     return null;
   }
-  /** Check if a body is grounded (low vertical velocity indicates resting on something) */
-  isGrounded(body) {
-    return Math.abs(body.velocity.y) < 0.5;
-  }
   start() {
     Matter5.Render.run(this.render);
     this.loop();
@@ -1993,6 +2021,9 @@ var OverlayScene = class {
     Matter5.Events.off(this.engine, "collisionStart", this.handleCollisionStart);
     Matter5.Engine.clear(this.engine);
     this.objects.clear();
+    this.gravityOverrideEntries.clear();
+    this.followWindowEntries.clear();
+    this.pressureObstacleIds.clear();
     this.obstaclePressure.clear();
     this.previousPressure.clear();
     this.pressureLogTimer = 0;
@@ -2013,6 +2044,106 @@ var OverlayScene = class {
       }
     }
   }
+  /**
+   * Set gravity at runtime. Y axis uses physical convention: negative = down, positive = up.
+   * @example
+   * scene.setGravity({ x: 0, y: -1 });  // Normal downward gravity
+   * scene.setGravity({ x: 0, y: 1 });   // Upward gravity
+   * scene.setGravity({ x: 1, y: 0 });   // Rightward gravity
+   * scene.setGravity({ x: 0, y: 0 });   // Zero gravity
+   */
+  setGravity(gravity) {
+    this.config.gravity = gravity;
+    this.engine.gravity.x = gravity.x;
+    this.engine.gravity.y = -gravity.y;
+  }
+  /**
+   * Set or clear a per-object gravity override at runtime.
+   * Pass `null` to remove the override and restore scene gravity for that object.
+   */
+  setObjectGravityOverride(id, gravity) {
+    const entry = this.objects.get(id);
+    if (!entry) return;
+    if (gravity === null) {
+      this.removeTag(id, "gravity_override");
+    } else {
+      entry.gravityOverride = gravity;
+      this.addTag(id, "gravity_override");
+    }
+  }
+  /**
+   * Set or change the follow target for an object's 'follow_window' tag.
+   * Target can be 'mouse', an entity ID, or a tag string (follows first matching entity).
+   * Adds 'follow_window' tag if not already present.
+   */
+  setFollowWindowTarget(id, target) {
+    const entry = this.objects.get(id);
+    if (!entry) return;
+    entry.followTarget = target;
+    this.addTag(id, "follow_window");
+  }
+  /**
+   * Set or change the speed multiplier for an object's movement (follow_window and future
+   * movement behaviors). Pass null to remove the override and reset to default speed.
+   * Negative values cause the object to run away from its target.
+   * Adds 'speed_override' tag if not already present.
+   */
+  setObjectSpeedOverride(id, speed) {
+    const entry = this.objects.get(id);
+    if (!entry) return;
+    if (speed === null) {
+      this.removeTag(id, "speed_override");
+    } else {
+      entry.speedOverride = speed;
+      this.addTag(id, "speed_override");
+    }
+  }
+  /**
+   * Set or change the physics mass for an object. Pass null to remove the override and restore
+   * the original density-based mass. Adds 'mass_override' tag if not already present.
+   * Higher mass resists applied forces (including follow forces) more strongly.
+   */
+  setObjectMassOverride(id, mass) {
+    const entry = this.objects.get(id);
+    if (!entry) return;
+    if (mass === null) {
+      this.removeTag(id, "mass_override");
+    } else {
+      if (entry.originalMass === void 0) entry.originalMass = entry.body.mass;
+      entry.massOverride = mass;
+      Matter5.Body.setMass(entry.body, mass);
+      this.addTag(id, "mass_override");
+    }
+  }
+  /**
+   * Set the angular velocity (spin) of an object in radians per second.
+   * Positive = counter-clockwise, negative = clockwise.
+   */
+  setObjectAngularVelocity(id, omega) {
+    const entry = this.objects.get(id);
+    if (!entry) return;
+    Matter5.Body.setAngularVelocity(entry.body, omega);
+  }
+  /**
+   * Set the absolute scale of an object on each axis. Both physics collision shape and
+   * sprite rendering are updated together. Scaling changes the body's mass proportionally
+   * (area scales by x*y). Use setObjectMassOverride afterwards if you need a fixed mass.
+   * @param x - Scale factor on the X axis (1 = original size)
+   * @param y - Scale factor on the Y axis (1 = original size)
+   */
+  setObjectScale(id, x, y) {
+    const entry = this.objects.get(id);
+    if (!entry) return;
+    const currentX = entry.scaleX ?? 1;
+    const currentY = entry.scaleY ?? 1;
+    Matter5.Body.scale(entry.body, x / currentX, y / currentY);
+    if (entry.body.render.sprite && entry.baseSpriteSX !== void 0) {
+      entry.body.render.sprite.xScale = entry.baseSpriteSX * x;
+      entry.body.render.sprite.yScale = entry.baseSpriteSY * y;
+    }
+    entry.scaleX = x;
+    entry.scaleY = y;
+  }
   /**
    * Update the background configuration at runtime.
    */
@@ -2048,10 +2179,9 @@ var OverlayScene = class {
   /**
    * Spawn an object synchronously.
    * Object behavior is determined by tags:
-   * - 'falling': Object is dynamic (affected by gravity)
+   * - 'static': Object is not affected by gravity (obstacle). Without this tag, object is dynamic by default.
    * - 'follow_window': Object follows mouse when grounded (walks toward mouse)
    * - 'grabable': Object can be grabbed and moved with mouse
-   * Without 'falling' tag, object is static.
    */
   spawnObject(config) {
     if (config.element) {
@@ -2070,8 +2200,20 @@ var OverlayScene = class {
       return result.id;
     }
     const id = crypto.randomUUID();
-    const tags = config.tags ?? [];
-    const isStatic = !tags.includes("falling");
+    const entityDescriptor = config.imageUrl ? config.imageUrl.split("/").pop()?.replace(/\.[^.]+$/, "") ?? "image" : config.radius ? "circle" : config.shape?.type ?? "rect";
+    const entityTag = `${entityDescriptor.replace(/[^a-zA-Z0-9]/g, "-").toLowerCase().slice(0, 16)}-${id.slice(0, 4)}`;
+    const tags = [...config.tags ?? []];
+    tags.push(entityTag);
+    if (config.gravityOverride && !tags.includes("gravity_override")) {
+      tags.push("gravity_override");
+    }
+    if (config.speedOverride !== void 0 && !tags.includes("speed_override")) {
+      tags.push("speed_override");
+    }
+    if (config.massOverride !== void 0 && !tags.includes("mass_override")) {
+      tags.push("mass_override");
+    }
+    const isStatic = tags.includes("static");
     logger.debug("OverlayScene", `Spawning object`, {
       id,
       tags,
@@ -2088,6 +2230,10 @@ var OverlayScene = class {
     } else {
       body = createObstacle(id, config, isStatic);
     }
+    const naturalMass = body.mass;
+    if (config.massOverride !== void 0) {
+      Matter5.Body.setMass(body, config.massOverride);
+    }
     let pressureThreshold;
     if (config.pressureThreshold) {
       pressureThreshold = typeof config.pressureThreshold.value === "number" ? config.pressureThreshold.value : config.pressureThreshold.value[0];
@@ -2110,12 +2256,25 @@ var OverlayScene = class {
       pressureThreshold,
       shadow,
       originalPosition: shadow || clicksRemaining !== void 0 ? { x: config.x, y: config.y } : void 0,
-      clicksRemaining
+      clicksRemaining,
+      gravityOverride: config.gravityOverride,
+      followTarget: tags.includes("follow_window") ? config.followTarget ?? "mouse" : void 0,
+      speedOverride: tags.includes("speed_override") ? config.speedOverride ?? 1 : void 0,
+      massOverride: tags.includes("mass_override") ? config.massOverride : void 0,
+      originalMass: tags.includes("mass_override") ? naturalMass : void 0,
+      entityTag,
+      scaleX: 1,
+      scaleY: 1,
+      baseSpriteSX: body.render.sprite?.xScale,
+      baseSpriteSY: body.render.sprite?.yScale
     };
     this.objects.set(id, entry);
+    if (config.gravityOverride) this.gravityOverrideEntries.add(entry);
+    if (tags.includes("follow_window")) this.followWindowEntries.add(entry);
     Matter5.Composite.add(this.engine.world, body);
     if (isStatic && pressureThreshold !== void 0) {
       this.obstaclePressure.set(id, /* @__PURE__ */ new Set());
+      this.pressureObstacleIds.add(id);
     }
     this.emitLifecycleEvent("objectSpawned", this.toObjectState(entry));
     return id;
@@ -2126,8 +2285,20 @@ var OverlayScene = class {
    */
   async spawnObjectAsync(config) {
     const id = crypto.randomUUID();
-    const tags = config.tags ?? [];
-    const isStatic = !tags.includes("falling");
+    const entityDescriptor = config.imageUrl ? config.imageUrl.split("/").pop()?.replace(/\.[^.]+$/, "") ?? "image" : config.radius ? "circle" : config.shape?.type ?? "rect";
+    const entityTag = `${entityDescriptor.replace(/[^a-zA-Z0-9]/g, "-").toLowerCase().slice(0, 16)}-${id.slice(0, 4)}`;
+    const tags = [...config.tags ?? []];
+    tags.push(entityTag);
+    if (config.gravityOverride && !tags.includes("gravity_override")) {
+      tags.push("gravity_override");
+    }
+    if (config.speedOverride !== void 0 && !tags.includes("speed_override")) {
+      tags.push("speed_override");
+    }
+    if (config.massOverride !== void 0 && !tags.includes("mass_override")) {
+      tags.push("mass_override");
+    }
+    const isStatic = tags.includes("static");
     logger.debug("OverlayScene", `Spawning object async`, {
       id,
       tags,
@@ -2144,6 +2315,10 @@ var OverlayScene = class {
     } else {
       body = await createObstacleAsync(id, config, isStatic);
     }
+    const naturalMass = body.mass;
+    if (config.massOverride !== void 0) {
+      Matter5.Body.setMass(body, config.massOverride);
+    }
     let pressureThreshold;
     if (config.pressureThreshold) {
       pressureThreshold = typeof config.pressureThreshold.value === "number" ? config.pressureThreshold.value : config.pressureThreshold.value[0];
@@ -2166,26 +2341,39 @@ var OverlayScene = class {
       pressureThreshold,
       shadow,
       originalPosition: shadow || clicksRemaining !== void 0 ? { x: config.x, y: config.y } : void 0,
-      clicksRemaining
+      clicksRemaining,
+      gravityOverride: config.gravityOverride,
+      followTarget: tags.includes("follow_window") ? config.followTarget ?? "mouse" : void 0,
+      speedOverride: tags.includes("speed_override") ? config.speedOverride ?? 1 : void 0,
+      massOverride: tags.includes("mass_override") ? config.massOverride : void 0,
+      originalMass: tags.includes("mass_override") ? naturalMass : void 0,
+      entityTag,
+      scaleX: 1,
+      scaleY: 1,
+      baseSpriteSX: body.render.sprite?.xScale,
+      baseSpriteSY: body.render.sprite?.yScale
     };
     this.objects.set(id, entry);
+    if (config.gravityOverride) this.gravityOverrideEntries.add(entry);
+    if (tags.includes("follow_window")) this.followWindowEntries.add(entry);
     Matter5.Composite.add(this.engine.world, body);
     if (isStatic && pressureThreshold !== void 0) {
       this.obstaclePressure.set(id, /* @__PURE__ */ new Set());
+      this.pressureObstacleIds.add(id);
     }
     this.emitLifecycleEvent("objectSpawned", this.toObjectState(entry));
     return id;
   }
   /**
-   * Add 'falling' tag to an object, making it dynamic (affected by gravity).
+   * Make an object dynamic (remove 'static' tag, affected by gravity).
    * Also adds 'grabable' tag so released objects can be dragged.
    * This is the tag-based replacement for releaseObstacle().
    */
   addFallingTag(id) {
     const entry = this.objects.get(id);
     if (!entry) return;
-    if (!entry.tags.includes("falling")) {
-      entry.tags.push("falling");
+    if (entry.tags.includes("static")) {
+      entry.tags = entry.tags.filter((t) => t !== "static");
       Matter5.Body.setStatic(entry.body, false);
     }
     if (!entry.tags.includes("grabable")) {
@@ -2193,34 +2381,66 @@ var OverlayScene = class {
     }
   }
   /**
-   * Add a tag to an object.
+   * Add a tag to an object. Tags drive behavior — adding a tag activates the associated effect.
+   * For 'gravity_override', also pass a gravityOverride value via setObjectGravityOverride first,
+   * or the tag will default to {x:0, y:0} (hovering).
    */
   addTag(id, tag) {
     const entry = this.objects.get(id);
     if (!entry) return;
     if (!entry.tags.includes(tag)) {
       entry.tags.push(tag);
-      if (tag === "falling") {
-        Matter5.Body.setStatic(entry.body, false);
+      if (tag === "static") {
+        Matter5.Body.setStatic(entry.body, true);
+      } else if (tag === "gravity_override") {
+        if (!entry.gravityOverride) entry.gravityOverride = { x: 0, y: 0 };
+        this.gravityOverrideEntries.add(entry);
+      } else if (tag === "follow_window") {
+        if (!entry.followTarget) entry.followTarget = "mouse";
+        this.followWindowEntries.add(entry);
+      } else if (tag === "speed_override") {
+        if (entry.speedOverride === void 0) entry.speedOverride = 1;
+      } else if (tag === "mass_override") {
+        if (entry.originalMass === void 0) entry.originalMass = entry.body.mass;
+        if (entry.massOverride === void 0) entry.massOverride = Math.round(entry.body.mass);
+        Matter5.Body.setMass(entry.body, entry.massOverride);
       }
     }
   }
   /**
-   * Remove a tag from an object.
+   * Remove a tag from an object. Tags drive behavior — removing a tag deactivates the associated effect.
    */
   removeTag(id, tag) {
     const entry = this.objects.get(id);
     if (!entry) return;
+    if (tag === entry.entityTag) {
+      logger.warn("OverlayScene", `Cannot remove entity tag '${tag}' from '${id}' \u2014 entity tags are permanent identifiers and cannot be removed`);
+      return;
+    }
     const index = entry.tags.indexOf(tag);
     if (index !== -1) {
       entry.tags.splice(index, 1);
-      if (tag === "falling") {
-        Matter5.Body.setStatic(entry.body, true);
+      if (tag === "static") {
+        Matter5.Body.setStatic(entry.body, false);
+      } else if (tag === "gravity_override") {
+        this.gravityOverrideEntries.delete(entry);
+        entry.gravityOverride = void 0;
+      } else if (tag === "follow_window") {
+        entry.followTarget = void 0;
+        this.followWindowEntries.delete(entry);
+      } else if (tag === "speed_override") {
+        entry.speedOverride = void 0;
+      } else if (tag === "mass_override") {
+        if (entry.originalMass !== void 0) {
+          Matter5.Body.setMass(entry.body, entry.originalMass);
+        }
+        entry.massOverride = void 0;
+        entry.originalMass = void 0;
       }
     }
   }
   /**
-   * Release an object (add 'falling' tag to make it dynamic).
+   * Release an object (remove 'static' tag to make it dynamic).
    * Convenience method - equivalent to addFallingTag().
    */
   releaseObject(id) {
@@ -2235,7 +2455,7 @@ var OverlayScene = class {
     }
   }
   /**
-   * Release all static objects (add 'falling' and 'grabable' tags).
+   * Release all static objects (remove 'static' tag, add 'grabable' tag).
    */
   releaseAllObjects() {
     for (const [id] of this.objects) {
@@ -2243,7 +2463,7 @@ var OverlayScene = class {
     }
   }
   /**
-   * Release objects by tag (add 'falling' and 'grabable' tags to matching objects).
+   * Release objects by tag (remove 'static' tag, add 'grabable' tag to matching objects).
    */
   releaseObjectsByTag(tag) {
     for (const [id, entry] of this.objects) {
@@ -2257,6 +2477,9 @@ var OverlayScene = class {
     if (!entry) return;
     this.emitLifecycleEvent("objectRemoved", this.toObjectState(entry));
     Matter5.Composite.remove(this.engine.world, entry.body);
+    this.gravityOverrideEntries.delete(entry);
+    this.followWindowEntries.delete(entry);
+    this.pressureObstacleIds.delete(id);
     this.objects.delete(id);
   }
   removeObjects(ids) {
@@ -2269,6 +2492,9 @@ var OverlayScene = class {
       Matter5.Composite.remove(this.engine.world, entry.body);
     }
     this.objects.clear();
+    this.gravityOverrideEntries.clear();
+    this.followWindowEntries.clear();
+    this.pressureObstacleIds.clear();
   }
   removeObjectsByTag(tag) {
     const toRemove = [];
@@ -2426,14 +2652,14 @@ var OverlayScene = class {
     }
   }
   /**
-   * Set the velocity of an object.
+   * Set the velocity of an object. Y axis uses physical convention: negative = down, positive = up.
    * @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);
+    Matter5.Body.setVelocity(entry.body, { x: velocity.x, y: -velocity.y });
   }
   /**
    * Set the position of an object.
@@ -2656,7 +2882,7 @@ var OverlayScene = class {
     const width = config.width ?? element.offsetWidth;
     const height = config.height ?? element.offsetHeight;
     const tags = config.tags ?? [];
-    const isStatic = !tags.includes("falling");
+    const isStatic = tags.includes("static");
     const body = Matter5.Bodies.rectangle(x, y, width, height, {
       isStatic,
       label: `dom-${crypto.randomUUID().slice(0, 8)}`,
@@ -2664,6 +2890,8 @@ var OverlayScene = class {
       // Don't render the body, DOM element is the visual
     });
     const id = body.label;
+    const entityTag = `dom-${id.slice(4, 8)}`;
+    tags.push(entityTag);
     let pressureThreshold;
     if (config.pressureThreshold) {
       pressureThreshold = typeof config.pressureThreshold.value === "number" ? config.pressureThreshold.value : config.pressureThreshold.value[0];
@@ -2677,6 +2905,7 @@ var OverlayScene = class {
       id,
       body,
       tags,
+      entityTag,
       spawnTime: performance.now(),
       pressureThreshold,
       weight: config.weight ?? 1,
@@ -2691,12 +2920,13 @@ var OverlayScene = class {
     this.updateDOMElementTransform(entry);
     if (isStatic && pressureThreshold !== void 0) {
       this.obstaclePressure.set(id, /* @__PURE__ */ new Set());
+      this.pressureObstacleIds.add(id);
     }
     if (clicksRemaining !== void 0) {
       const clickHandler = () => {
         const currentEntry = this.objects.get(id);
         if (!currentEntry) return;
-        if (currentEntry.tags.includes("falling")) return;
+        if (!currentEntry.tags.includes("static")) return;
         if (currentEntry.clicksRemaining === void 0) return;
         currentEntry.clicksRemaining--;
         logger.debug("OverlayScene", `Click on DOM element: ${currentEntry.clicksRemaining} clicks remaining`);
@@ -2741,8 +2971,13 @@ var OverlayScene = class {
     const fontName = config.fontName ?? this.getDefaultFont()?.name ?? "handwritten";
     const basePath = `${fontsBasePath}${fontName}/`;
     const stringTag = config.stringTag ?? `str-${crypto.randomUUID().slice(0, 8)}`;
-    const baseTags = config.tags ?? [];
-    const isStatic = !baseTags.includes("falling");
+    const isStatic = config.isStatic !== false;
+    const baseTags = [...config.tags ?? []];
+    if (isStatic && !baseTags.includes("static")) baseTags.push("static");
+    else if (!isStatic) {
+      const i = baseTags.indexOf("static");
+      if (i !== -1) baseTags.splice(i, 1);
+    }
     const letterColor = config.letterColor;
     const letterIds = [];
     const letterMap = /* @__PURE__ */ new Map();
@@ -2884,8 +3119,10 @@ var OverlayScene = class {
         const resolvedChar = charFileNames.get(char) ?? char;
         const originalImageUrl = `${basePath}${resolvedChar}.png`;
         const imageUrl = letterColor ? await tintImage(originalImageUrl, letterColor) : originalImageUrl;
-        const tags = [...config.tags ?? [], stringTag, wordTag, `letter-${char}`, `letter-index-${globalCharIndex}`];
         const id = crypto.randomUUID();
+        const safeChar = char.match(/[a-zA-Z0-9]/) ? char.toLowerCase() : "sym";
+        const entityTag = `letter-${safeChar}-${id.slice(0, 4)}`;
+        const tags = [...baseTags, entityTag, stringTag, wordTag, `letter-${char}`, `letter-index-${globalCharIndex}`];
         const objectConfig = {
           x: centerX,
           y: centerY,
@@ -2931,10 +3168,12 @@ var OverlayScene = class {
           originalPosition: shadow || clicksRemaining !== void 0 ? { x: centerX, y: centerY } : void 0,
           imageUrl: shadow || clicksRemaining !== void 0 ? imageUrl : void 0,
           imageSize: shadow || clicksRemaining !== void 0 ? letterSize : void 0,
-          clicksRemaining
+          clicksRemaining,
+          entityTag
         };
         this.objects.set(id, entry);
         Matter5.Composite.add(this.engine.world, result.body);
+        if (pressureThreshold !== void 0) this.pressureObstacleIds.add(id);
         letterIds.push(id);
         letterMap.set(`${char}-${globalCharIndex}`, id);
         debugInfo.push({
@@ -2985,15 +3224,13 @@ var OverlayScene = class {
   }
   /**
    * Spawn falling text objects from a string.
-   * Same as addTextObstacles but with 'falling' tag (objects fall with gravity).
+   * Same as addTextObstacles but ensures objects are dynamic (removes 'static' tag if present).
    */
   async spawnFallingTextObstacles(config) {
-    const tags = [...config.tags ?? []];
-    if (!tags.includes("falling")) tags.push("falling");
-    return this.addTextObstacles({ ...config, tags });
+    return this.addTextObstacles({ ...config, isStatic: false });
   }
   /**
-   * Release all letters in a word (add 'falling' tag so they fall).
+   * Release all letters in a word (remove 'static' tag so they fall).
    * @param wordTag - The word tag returned from addTextObstacles
    */
   releaseTextObstacles(wordTag) {
@@ -3040,8 +3277,13 @@ var OverlayScene = class {
     const { x, y, fontSize, fontUrl } = config;
     const text = config.text.replace(/\\n/g, "\n");
     const stringTag = config.stringTag ?? `str-${crypto.randomUUID().slice(0, 8)}`;
-    const baseTags = config.tags ?? [];
-    const isStatic = !baseTags.includes("falling");
+    const isStatic = config.isStatic !== false;
+    const baseTags = [...config.tags ?? []];
+    if (isStatic && !baseTags.includes("static")) baseTags.push("static");
+    else if (!isStatic) {
+      const i = baseTags.indexOf("static");
+      if (i !== -1) baseTags.splice(i, 1);
+    }
     const fillColor = config.fillColor ?? "#ffffff";
     const fillColors = config.fillColors;
     const lineHeight = config.lineHeight ?? fontSize * 1.2;
@@ -3115,7 +3357,9 @@ var OverlayScene = class {
         const wordTag = `${stringTag}-word-${currentWordIndex}`;
         wordTagsSet.add(wordTag);
         const id = crypto.randomUUID();
-        const tags = [...config.tags ?? [], stringTag, wordTag, `letter-${char}`, `letter-index-${globalCharIndex}`];
+        const safeChar = char.match(/[a-zA-Z0-9]/) ? char.toLowerCase() : "sym";
+        const entityTag = `letter-${safeChar}-${id.slice(0, 4)}`;
+        const tags = [...baseTags, entityTag, stringTag, wordTag, `letter-${char}`, `letter-index-${globalCharIndex}`];
         const bbox = glyphData.boundingBox;
         const glyphWidth = bbox ? bbox.x2 - bbox.x1 : glyphData.advanceWidth;
         const glyphHeight = bbox ? bbox.y2 - bbox.y1 : fontSize;
@@ -3177,10 +3421,12 @@ var OverlayScene = class {
           weight,
           shadow,
           originalPosition: shadow || clicksRemaining !== void 0 ? { x: body.position.x, y: body.position.y } : void 0,
-          clicksRemaining
+          clicksRemaining,
+          entityTag
         };
         this.objects.set(id, entry);
         Matter5.Composite.add(this.engine.world, body);
+        if (pressureThreshold !== void 0) this.pressureObstacleIds.add(id);
         letterIds.push(id);
         letterMap.set(`${char}-${globalCharIndex}`, id);
         currentX += glyphData.advanceWidth;
@@ -3220,12 +3466,10 @@ var OverlayScene = class {
   }
   /**
    * Spawn falling TTF text objects.
-   * Same as addTTFTextObstacles but with 'falling' tag (objects fall with gravity).
+   * Same as addTTFTextObstacles but ensures objects are dynamic (removes 'static' tag if present).
    */
   async spawnFallingTTFTextObstacles(config) {
-    const tags = [...config.tags ?? []];
-    if (!tags.includes("falling")) tags.push("falling");
-    return this.addTTFTextObstacles({ ...config, tags });
+    return this.addTTFTextObstacles({ ...config, isStatic: false });
   }
   // ==================== COMBINED TAG METHODS ====================
   removeAllByTag(tag) {
@@ -3336,37 +3580,29 @@ var OverlayScene = class {
     entry.domElement.style.setProperty("top", `${y - height / 2}px`, "important");
     entry.domElement.style.setProperty("transform", `rotate(${angleDeg}deg)`, "important");
   }
-  checkTTLExpiration() {
+  /** TTL expiration + below-floor despawn in a single O(N) pass */
+  checkExpiration() {
     const now = performance.now();
-    const expiredObjects = [];
-    for (const [id, entry] of this.objects) {
-      if (entry.ttl !== void 0 && now - entry.spawnTime >= entry.ttl) {
-        expiredObjects.push(id);
-      }
-    }
-    for (const id of expiredObjects) {
-      this.removeObject(id);
-    }
-  }
-  /** Despawn objects that have fallen below the floor by the configured distance */
-  checkDespawnBelowFloor() {
     const despawnDistance = this.config.despawnBelowFloor ?? 1;
     const containerHeight = this.config.bounds.bottom - this.config.bounds.top;
     const despawnY = this.config.bounds.bottom + containerHeight * despawnDistance;
-    const toDespawn = [];
+    const toRemove = [];
     for (const [id, entry] of this.objects) {
-      if (entry.body.position.y > despawnY) {
-        toDespawn.push(id);
+      if (entry.ttl !== void 0 && now - entry.spawnTime >= entry.ttl) {
+        toRemove.push(id);
+      } else if (entry.body.position.y > despawnY) {
+        toRemove.push(id);
       }
     }
-    for (const id of toDespawn) {
+    for (const id of toRemove) {
       this.removeObject(id);
     }
   }
   fireUpdateCallbacks() {
+    if (this.updateCallbacks.length === 0) return;
     const objects = [];
-    this.objects.forEach((entry) => {
-      if (entry.tags.includes("falling")) {
+    for (const entry of this.objects.values()) {
+      if (!entry.tags.includes("static")) {
         objects.push({
           id: entry.id,
           x: entry.body.position.x,
@@ -3375,28 +3611,37 @@ var OverlayScene = class {
           tags: entry.tags
         });
       }
-    });
+    }
     const data = { objects };
-    this.updateCallbacks.forEach((cb) => cb(data));
+    for (const cb of this.updateCallbacks) cb(data);
   }
 };
 
 // src/tags.ts
-var TAG_FALLING = "falling";
+var TAG_STATIC = "static";
 var TAG_FOLLOW_WINDOW = "follow_window";
 var TAG_GRABABLE = "grabable";
+var TAG_GRAVITY_OVERRIDE = "gravity_override";
+var TAG_SPEED_OVERRIDE = "speed_override";
+var TAG_MASS_OVERRIDE = "mass_override";
 var TAGS = {
-  FALLING: TAG_FALLING,
+  STATIC: TAG_STATIC,
   FOLLOW_WINDOW: TAG_FOLLOW_WINDOW,
-  GRABABLE: TAG_GRABABLE
+  GRABABLE: TAG_GRABABLE,
+  GRAVITY_OVERRIDE: TAG_GRAVITY_OVERRIDE,
+  SPEED_OVERRIDE: TAG_SPEED_OVERRIDE,
+  MASS_OVERRIDE: TAG_MASS_OVERRIDE
 };
 export {
   BackgroundManager,
   OverlayScene,
   TAGS,
-  TAG_FALLING,
   TAG_FOLLOW_WINDOW,
   TAG_GRABABLE,
+  TAG_GRAVITY_OVERRIDE,
+  TAG_MASS_OVERRIDE,
+  TAG_SPEED_OVERRIDE,
+  TAG_STATIC,
   clearFontCache,
   getGlyphData,
   getKerning,