@blorkfield/overlay-core 0.7.0 → 0.8.0

package/dist/index.d.cts

@@ -196,6 +196,31 @@ interface DynamicObject {
     angle: number;
     tags: string[];
 }
+/**
+ * Extended object state for querying and manipulation.
+ * Includes velocity data not present in DynamicObject.
+ */
+interface ObjectState {
+    id: string;
+    x: number;
+    y: number;
+    velocity: {
+        x: number;
+        y: number;
+    };
+    angle: number;
+    tags: string[];
+}
+/**
+ * Lifecycle events that can be subscribed to.
+ */
+type LifecycleEvent = 'objectSpawned' | 'objectRemoved' | 'objectCollision';
+/**
+ * Callback type for lifecycle events.
+ * - objectSpawned/objectRemoved: receives the affected object
+ * - objectCollision: receives both colliding objects
+ */
+type LifecycleCallback<T extends LifecycleEvent> = T extends 'objectCollision' ? (a: ObjectState, b: ObjectState) => void : (object: ObjectState) => void;
 interface UpdateCallbackData {
     /** All dynamic objects (objects with 'falling' tag) */
     objects: DynamicObject[];
@@ -509,7 +534,6 @@ declare class OverlayScene {
     private objects;
     private boundaries;
     private updateCallbacks;
-    private mouseX;
     private config;
     private animationFrameId;
     private mouse;
@@ -525,6 +549,8 @@ declare class OverlayScene {
     private floorSegmentPressure;
     private collapsedSegments;
     private backgroundManager;
+    private lifecycleCallbacks;
+    private followTargets;
     static createContainer(parent: HTMLElement, options?: ContainerOptions): {
         canvas: HTMLCanvasElement;
         bounds: Bounds;
@@ -544,6 +570,11 @@ declare class OverlayScene {
      * Draws transparency/frosted glass layer after physics objects.
      */
     private handleAfterRender;
+    /**
+     * Handler for Matter.js collision events.
+     * Emits objectCollision lifecycle events.
+     */
+    private handleCollisionStart;
     /** Get a display name for an obstacle (letter char or short ID) */
     private getObstacleDisplayName;
     /** Update pressure tracking - check which dynamic objects rest on static obstacles */
@@ -638,7 +669,94 @@ declare class OverlayScene {
      * Get all unique tags currently in use by objects in the scene.
      */
     getAllTags(): string[];
-    setMousePosition(x: number, _y: number): void;
+    /**
+     * 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: number, y: number): void;
+    /**
+     * 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: string, x: number, y: number): void;
+    /**
+     * Remove a follow target. Objects with the corresponding tag will stop following.
+     * @param key - The target key to remove
+     */
+    removeFollowTarget(key: string): void;
+    /**
+     * Get all registered follow target keys.
+     * @returns Array of follow target keys
+     */
+    getFollowTargetKeys(): string[];
+    /**
+     * Apply a force to an object.
+     * @param objectId - The ID of the object
+     * @param force - The force vector to apply
+     */
+    applyForce(objectId: string, force: {
+        x: number;
+        y: number;
+    }): void;
+    /**
+     * 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: string, force: {
+        x: number;
+        y: number;
+    }): void;
+    /**
+     * Set the velocity of an object.
+     * @param objectId - The ID of the object
+     * @param velocity - The velocity vector to set
+     */
+    setVelocity(objectId: string, velocity: {
+        x: number;
+        y: number;
+    }): void;
+    /**
+     * Set the position of an object.
+     * @param objectId - The ID of the object
+     * @param position - The position to set
+     */
+    setPosition(objectId: string, position: {
+        x: number;
+        y: number;
+    }): void;
+    /**
+     * 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: string): ObjectState | null;
+    /**
+     * Get the current state of all objects with a specific tag.
+     * @param tag - The tag to match
+     * @returns Array of object states
+     */
+    getObjectsByTag(tag: string): ObjectState[];
+    /**
+     * Subscribe to a lifecycle event.
+     * @param event - The event type to subscribe to
+     * @param callback - The callback to invoke when the event occurs
+     */
+    on<T extends LifecycleEvent>(event: T, callback: LifecycleCallback<T>): void;
+    /**
+     * Unsubscribe from a lifecycle event.
+     * @param event - The event type to unsubscribe from
+     * @param callback - The callback to remove
+     */
+    off<T extends LifecycleEvent>(event: T, callback: LifecycleCallback<T>): void;
+    /** Create ObjectState from an ObjectEntry */
+    private toObjectState;
+    /** Emit a lifecycle event to all registered callbacks */
+    private emitLifecycleEvent;
     /**
      * Get the current pressure (number of objects resting) on an obstacle.
      * @param obstacleId - The ID of the obstacle
@@ -967,4 +1085,4 @@ declare class BackgroundManager {
     static clearCache(): void;
 }
 
-export { type BackgroundConfig, type BackgroundImageConfig, type BackgroundImageSizing, BackgroundManager, type BackgroundTransparencyConfig, type BaseEffectConfig, type Bounds, type BurstEffectConfig, type ClickToFallConfig, type ContainerOptions, type DespawnEffectConfig, type DynamicObject, type EffectConfig, type EffectObjectConfig, type EffectType, type FloorConfig, type FontInfo, type FontManifest, type GlyphData, type LoadedFont, type LogLevel, type ObjectConfig, OverlayScene, type OverlaySceneConfig, type PressureThresholdConfig, type RainEffectConfig, type ShadowConfig, type ShapeConfig, type ShapePreset, type StreamEffectConfig, type TTFTextObstacleConfig, type TextAlign, type TextBounds, type TextObstacleConfig, type TextObstacleResult, type UpdateCallback, type UpdateCallbackData, type WeightConfig, clearFontCache, getGlyphData, getKerning, getLogLevel, loadFont, logger, measureText, setLogLevel };
+export { type BackgroundConfig, type BackgroundImageConfig, type BackgroundImageSizing, BackgroundManager, type BackgroundTransparencyConfig, type BaseEffectConfig, type Bounds, type BurstEffectConfig, type ClickToFallConfig, type ContainerOptions, type DespawnEffectConfig, type DynamicObject, type EffectConfig, type EffectObjectConfig, type EffectType, type FloorConfig, type FontInfo, type FontManifest, type GlyphData, type LifecycleCallback, type LifecycleEvent, type LoadedFont, type LogLevel, type ObjectConfig, type ObjectState, OverlayScene, type OverlaySceneConfig, type PressureThresholdConfig, type RainEffectConfig, type ShadowConfig, type ShapeConfig, type ShapePreset, type StreamEffectConfig, type TTFTextObstacleConfig, type TextAlign, type TextBounds, type TextObstacleConfig, type TextObstacleResult, type UpdateCallback, type UpdateCallbackData, type WeightConfig, clearFontCache, getGlyphData, getKerning, getLogLevel, loadFont, logger, measureText, setLogLevel };

package/dist/index.d.ts

@@ -196,6 +196,31 @@ interface DynamicObject {
     angle: number;
     tags: string[];
 }
+/**
+ * Extended object state for querying and manipulation.
+ * Includes velocity data not present in DynamicObject.
+ */
+interface ObjectState {
+    id: string;
+    x: number;
+    y: number;
+    velocity: {
+        x: number;
+        y: number;
+    };
+    angle: number;
+    tags: string[];
+}
+/**
+ * Lifecycle events that can be subscribed to.
+ */
+type LifecycleEvent = 'objectSpawned' | 'objectRemoved' | 'objectCollision';
+/**
+ * Callback type for lifecycle events.
+ * - objectSpawned/objectRemoved: receives the affected object
+ * - objectCollision: receives both colliding objects
+ */
+type LifecycleCallback<T extends LifecycleEvent> = T extends 'objectCollision' ? (a: ObjectState, b: ObjectState) => void : (object: ObjectState) => void;
 interface UpdateCallbackData {
     /** All dynamic objects (objects with 'falling' tag) */
     objects: DynamicObject[];
@@ -509,7 +534,6 @@ declare class OverlayScene {
     private objects;
     private boundaries;
     private updateCallbacks;
-    private mouseX;
     private config;
     private animationFrameId;
     private mouse;
@@ -525,6 +549,8 @@ declare class OverlayScene {
     private floorSegmentPressure;
     private collapsedSegments;
     private backgroundManager;
+    private lifecycleCallbacks;
+    private followTargets;
     static createContainer(parent: HTMLElement, options?: ContainerOptions): {
         canvas: HTMLCanvasElement;
         bounds: Bounds;
@@ -544,6 +570,11 @@ declare class OverlayScene {
      * Draws transparency/frosted glass layer after physics objects.
      */
     private handleAfterRender;
+    /**
+     * Handler for Matter.js collision events.
+     * Emits objectCollision lifecycle events.
+     */
+    private handleCollisionStart;
     /** Get a display name for an obstacle (letter char or short ID) */
     private getObstacleDisplayName;
     /** Update pressure tracking - check which dynamic objects rest on static obstacles */
@@ -638,7 +669,94 @@ declare class OverlayScene {
      * Get all unique tags currently in use by objects in the scene.
      */
     getAllTags(): string[];
-    setMousePosition(x: number, _y: number): void;
+    /**
+     * 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: number, y: number): void;
+    /**
+     * 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: string, x: number, y: number): void;
+    /**
+     * Remove a follow target. Objects with the corresponding tag will stop following.
+     * @param key - The target key to remove
+     */
+    removeFollowTarget(key: string): void;
+    /**
+     * Get all registered follow target keys.
+     * @returns Array of follow target keys
+     */
+    getFollowTargetKeys(): string[];
+    /**
+     * Apply a force to an object.
+     * @param objectId - The ID of the object
+     * @param force - The force vector to apply
+     */
+    applyForce(objectId: string, force: {
+        x: number;
+        y: number;
+    }): void;
+    /**
+     * 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: string, force: {
+        x: number;
+        y: number;
+    }): void;
+    /**
+     * Set the velocity of an object.
+     * @param objectId - The ID of the object
+     * @param velocity - The velocity vector to set
+     */
+    setVelocity(objectId: string, velocity: {
+        x: number;
+        y: number;
+    }): void;
+    /**
+     * Set the position of an object.
+     * @param objectId - The ID of the object
+     * @param position - The position to set
+     */
+    setPosition(objectId: string, position: {
+        x: number;
+        y: number;
+    }): void;
+    /**
+     * 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: string): ObjectState | null;
+    /**
+     * Get the current state of all objects with a specific tag.
+     * @param tag - The tag to match
+     * @returns Array of object states
+     */
+    getObjectsByTag(tag: string): ObjectState[];
+    /**
+     * Subscribe to a lifecycle event.
+     * @param event - The event type to subscribe to
+     * @param callback - The callback to invoke when the event occurs
+     */
+    on<T extends LifecycleEvent>(event: T, callback: LifecycleCallback<T>): void;
+    /**
+     * Unsubscribe from a lifecycle event.
+     * @param event - The event type to unsubscribe from
+     * @param callback - The callback to remove
+     */
+    off<T extends LifecycleEvent>(event: T, callback: LifecycleCallback<T>): void;
+    /** Create ObjectState from an ObjectEntry */
+    private toObjectState;
+    /** Emit a lifecycle event to all registered callbacks */
+    private emitLifecycleEvent;
     /**
      * Get the current pressure (number of objects resting) on an obstacle.
      * @param obstacleId - The ID of the obstacle
@@ -967,4 +1085,4 @@ declare class BackgroundManager {
     static clearCache(): void;
 }
 
-export { type BackgroundConfig, type BackgroundImageConfig, type BackgroundImageSizing, BackgroundManager, type BackgroundTransparencyConfig, type BaseEffectConfig, type Bounds, type BurstEffectConfig, type ClickToFallConfig, type ContainerOptions, type DespawnEffectConfig, type DynamicObject, type EffectConfig, type EffectObjectConfig, type EffectType, type FloorConfig, type FontInfo, type FontManifest, type GlyphData, type LoadedFont, type LogLevel, type ObjectConfig, OverlayScene, type OverlaySceneConfig, type PressureThresholdConfig, type RainEffectConfig, type ShadowConfig, type ShapeConfig, type ShapePreset, type StreamEffectConfig, type TTFTextObstacleConfig, type TextAlign, type TextBounds, type TextObstacleConfig, type TextObstacleResult, type UpdateCallback, type UpdateCallbackData, type WeightConfig, clearFontCache, getGlyphData, getKerning, getLogLevel, loadFont, logger, measureText, setLogLevel };
+export { type BackgroundConfig, type BackgroundImageConfig, type BackgroundImageSizing, BackgroundManager, type BackgroundTransparencyConfig, type BaseEffectConfig, type Bounds, type BurstEffectConfig, type ClickToFallConfig, type ContainerOptions, type DespawnEffectConfig, type DynamicObject, type EffectConfig, type EffectObjectConfig, type EffectType, type FloorConfig, type FontInfo, type FontManifest, type GlyphData, type LifecycleCallback, type LifecycleEvent, type LoadedFont, type LogLevel, type ObjectConfig, type ObjectState, OverlayScene, type OverlaySceneConfig, type PressureThresholdConfig, type RainEffectConfig, type ShadowConfig, type ShapeConfig, type ShapePreset, type StreamEffectConfig, type TTFTextObstacleConfig, type TextAlign, type TextBounds, type TextObstacleConfig, type TextObstacleResult, type UpdateCallback, type UpdateCallbackData, type WeightConfig, clearFontCache, getGlyphData, getKerning, getLogLevel, loadFont, logger, measureText, setLogLevel };

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,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;
+    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 ====================
   /**