@blorkfield/overlay-core 0.8.11 → 0.9.0

package/README.md

@@ -40,6 +40,7 @@ scene.spawnObject({ tags: [FALLING, GRABABLE], ... });
 | `TAG_FALLING` / `TAGS.FALLING` | `'falling'` | Object is dynamic and affected by gravity |
 | `TAG_FOLLOW_WINDOW` / `TAGS.FOLLOW_WINDOW` | `'follow_window'` | Object follows mouse position when grounded |
 | `TAG_GRABABLE` / `TAGS.GRABABLE` | `'grabable'` | Object can be grabbed and moved with mouse |
+| `TAG_GRAVITY_OVERRIDE` / `TAGS.GRAVITY_OVERRIDE` | `'gravity_override'` | Object uses its own gravity (set via `gravityOverride` in config) |
 
 Without the `falling` tag, objects are static and won't move.
 
@@ -82,7 +83,7 @@ const { canvas, bounds } = OverlayScene.createContainer(container, {
 // Create scene
 const scene = new OverlayScene(canvas, {
   bounds,
-  gravity: 1,
+  gravity: { x: 0, y: 1 },
   wrapHorizontal: true,
   background: 'transparent'
 });
@@ -426,7 +427,7 @@ const currentGrab = scene.getGrabbedObject(); // Returns ID or null
 ```typescript
 const scene = new OverlayScene(canvas, {
   bounds: { top: 0, bottom: 600, left: 0, right: 800 },
-  gravity: 1,
+  gravity: { x: 0, y: 1 },
   wrapHorizontal: true,
   debug: false,
   background: '#16213e',
@@ -443,7 +444,7 @@ const scene = new OverlayScene(canvas, {
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `gravity` | 1 | Gravity strength |
+| `gravity` | `{ x: 0, y: 1 }` | Gravity vector. Both axes support negative values |
 | `wrapHorizontal` | true | Objects wrap around screen edges |
 | `debug` | false | Show collision wireframes |
 | `background` | transparent | Canvas background color |
@@ -641,13 +642,53 @@ setLogLevel('debug');  // Options: debug, info, warn, error
 ## Lifecycle
 
 ```typescript
-scene.start();           // Start simulation
-scene.stop();            // Pause simulation
-scene.resize(w, h);      // Resize canvas and bounds
-scene.setDebug(true);    // Toggle wireframe mode
-scene.destroy();         // Clean up resources
+scene.start();                          // Start simulation
+scene.stop();                           // Pause simulation
+scene.resize(w, h);                     // Resize canvas and bounds
+scene.setDebug(true);                   // Toggle wireframe mode
+scene.setGravity({ x: 0, y: -1 });     // Set gravity (negative y = upward)
+scene.setGravity({ x: 0, y: 0 });      // Zero gravity
+scene.setGravity({ x: 1, y: 0 });      // Sideways gravity
+scene.destroy();                        // Clean up resources
 ```
 
+### Per-Object Gravity Override
+
+Individual dynamic objects can have their own gravity vector, independent of the scene gravity. This is done via the `gravityOverride` field in `ObjectConfig`, which automatically adds the `gravity_override` tag to the object.
+
+```typescript
+// Spawn a floaty object that drifts upward
+scene.spawnObject({
+  x: 200, y: 300,
+  radius: 20,
+  fillStyle: '#4a90d9',
+  tags: ['falling', 'grabable'],
+  gravityOverride: { x: 0, y: -0.3 }  // floats upward
+});
+
+// Zero gravity — hovers in place
+scene.spawnObject({
+  x: 400, y: 200,
+  radius: 15,
+  fillStyle: '#e94560',
+  tags: ['falling'],
+  gravityOverride: { x: 0, y: 0 }
+});
+
+// Change or clear a gravity override at runtime
+scene.setObjectGravityOverride(id, { x: 0.5, y: 0 }); // drift sideways
+scene.setObjectGravityOverride(id, null);               // restore scene gravity
+```
+
+Tags are either boolean (presence = true) or carry a value. `gravity_override` is a value tag — its Vector2 value is set via `gravityOverride` in the config. Boolean tags (`falling`, `grabable`, `follow_window`) need no value.
+
+| Tag | Type | Behavior |
+|-----|------|----------|
+| `falling` | boolean | Dynamic body affected by gravity |
+| `grabable` | boolean | Can be grabbed with mouse |
+| `follow_window` | boolean | Walks toward mouse when grounded |
+| `gravity_override` | Vector2 | Uses own gravity instead of scene gravity |
+
 ## Examples
 
 Working examples are provided in the `/examples` directory:
@@ -673,6 +714,7 @@ import type {
   // Scene configuration
   OverlaySceneConfig,
   Bounds,
+  Vector2,
   ContainerOptions,
   FloorConfig,
 
@@ -732,5 +774,5 @@ import type {
 } from '@blorkfield/overlay-core';
 
 // Tag constants (values, not types)
-import { TAGS, TAG_FALLING, TAG_GRABABLE, TAG_FOLLOW_WINDOW } from '@blorkfield/overlay-core';
+import { TAGS, TAG_FALLING, TAG_GRABABLE, TAG_FOLLOW_WINDOW, TAG_GRAVITY_OVERRIDE } from '@blorkfield/overlay-core';
 ```

package/dist/index.cjs

@@ -36,6 +36,7 @@ __export(index_exports, {
   TAG_FALLING: () => TAG_FALLING,
   TAG_FOLLOW_WINDOW: () => TAG_FOLLOW_WINDOW,
   TAG_GRABABLE: () => TAG_GRABABLE,
+  TAG_GRAVITY_OVERRIDE: () => TAG_GRAVITY_OVERRIDE,
   clearFontCache: () => clearFontCache,
   getGlyphData: () => getGlyphData,
   getKerning: () => getKerning,
@@ -54,7 +55,8 @@ var import_matter_js5 = __toESM(require("matter-js"), 1);
 var import_matter_js = __toESM(require("matter-js"), 1);
 function createEngine(gravity) {
   const engine = import_matter_js.default.Engine.create();
-  engine.gravity.y = gravity;
+  engine.gravity.x = gravity.x;
+  engine.gravity.y = gravity.y;
   return engine;
 }
 function createRender(engine, canvas, config) {
@@ -1456,6 +1458,8 @@ 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();
     /** Handle mouse down - start grab via programmatic API */
     this.handleMouseDown = (event) => {
       const rect = this.canvas.getBoundingClientRect();
@@ -1533,7 +1537,16 @@ 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;
+          import_matter_js5.default.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
+          });
+        }
         import_matter_js5.default.Engine.update(this.engine, substepDelta);
       }
       this.effectManager.update();
@@ -1596,7 +1609,7 @@ var OverlayScene = class {
     };
     this.canvas = canvas;
     this.config = {
-      gravity: 1,
+      gravity: { x: 0, y: 1 },
       wrapHorizontal: true,
       debug: false,
       ...config
@@ -2062,6 +2075,39 @@ var OverlayScene = class {
       }
     }
   }
+  /**
+   * Set gravity at runtime. Supports any direction including negative values.
+   * @example
+   * scene.setGravity({ x: 0, y: 1 });   // Normal downward gravity
+   * scene.setGravity({ x: 0, y: -1 });  // Upward gravity
+   * scene.setGravity({ x: 1, y: 0 });   // Sideways 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) {
+      entry.gravityOverride = void 0;
+      this.gravityOverrideEntries.delete(entry);
+      const idx = entry.tags.indexOf("gravity_override");
+      if (idx !== -1) entry.tags.splice(idx, 1);
+    } else {
+      entry.gravityOverride = gravity;
+      this.gravityOverrideEntries.add(entry);
+      if (!entry.tags.includes("gravity_override")) {
+        entry.tags.push("gravity_override");
+      }
+    }
+  }
   /**
    * Update the background configuration at runtime.
    */
@@ -2119,7 +2165,10 @@ var OverlayScene = class {
       return result.id;
     }
     const id = crypto.randomUUID();
-    const tags = config.tags ?? [];
+    const tags = [...config.tags ?? []];
+    if (config.gravityOverride && !tags.includes("gravity_override")) {
+      tags.push("gravity_override");
+    }
     const isStatic = !tags.includes("falling");
     logger.debug("OverlayScene", `Spawning object`, {
       id,
@@ -2159,9 +2208,11 @@ var OverlayScene = class {
       pressureThreshold,
       shadow,
       originalPosition: shadow || clicksRemaining !== void 0 ? { x: config.x, y: config.y } : void 0,
-      clicksRemaining
+      clicksRemaining,
+      gravityOverride: config.gravityOverride
     };
     this.objects.set(id, entry);
+    if (config.gravityOverride) this.gravityOverrideEntries.add(entry);
     import_matter_js5.default.Composite.add(this.engine.world, body);
     if (isStatic && pressureThreshold !== void 0) {
       this.obstaclePressure.set(id, /* @__PURE__ */ new Set());
@@ -2175,7 +2226,10 @@ var OverlayScene = class {
    */
   async spawnObjectAsync(config) {
     const id = crypto.randomUUID();
-    const tags = config.tags ?? [];
+    const tags = [...config.tags ?? []];
+    if (config.gravityOverride && !tags.includes("gravity_override")) {
+      tags.push("gravity_override");
+    }
     const isStatic = !tags.includes("falling");
     logger.debug("OverlayScene", `Spawning object async`, {
       id,
@@ -2215,9 +2269,11 @@ var OverlayScene = class {
       pressureThreshold,
       shadow,
       originalPosition: shadow || clicksRemaining !== void 0 ? { x: config.x, y: config.y } : void 0,
-      clicksRemaining
+      clicksRemaining,
+      gravityOverride: config.gravityOverride
     };
     this.objects.set(id, entry);
+    if (config.gravityOverride) this.gravityOverrideEntries.add(entry);
     import_matter_js5.default.Composite.add(this.engine.world, body);
     if (isStatic && pressureThreshold !== void 0) {
       this.obstaclePressure.set(id, /* @__PURE__ */ new Set());
@@ -2306,6 +2362,7 @@ var OverlayScene = class {
     if (!entry) return;
     this.emitLifecycleEvent("objectRemoved", this.toObjectState(entry));
     import_matter_js5.default.Composite.remove(this.engine.world, entry.body);
+    this.gravityOverrideEntries.delete(entry);
     this.objects.delete(id);
   }
   removeObjects(ids) {
@@ -2318,6 +2375,7 @@ var OverlayScene = class {
       import_matter_js5.default.Composite.remove(this.engine.world, entry.body);
     }
     this.objects.clear();
+    this.gravityOverrideEntries.clear();
   }
   removeObjectsByTag(tag) {
     const toRemove = [];
@@ -3434,10 +3492,12 @@ var OverlayScene = class {
 var TAG_FALLING = "falling";
 var TAG_FOLLOW_WINDOW = "follow_window";
 var TAG_GRABABLE = "grabable";
+var TAG_GRAVITY_OVERRIDE = "gravity_override";
 var TAGS = {
   FALLING: TAG_FALLING,
   FOLLOW_WINDOW: TAG_FOLLOW_WINDOW,
-  GRABABLE: TAG_GRABABLE
+  GRABABLE: TAG_GRABABLE,
+  GRAVITY_OVERRIDE: TAG_GRAVITY_OVERRIDE
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -3447,6 +3507,7 @@ var TAGS = {
   TAG_FALLING,
   TAG_FOLLOW_WINDOW,
   TAG_GRABABLE,
+  TAG_GRAVITY_OVERRIDE,
   clearFontCache,
   getGlyphData,
   getKerning,