@blorkfield/overlay-core 0.7.1 → 0.8.1

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,111 @@ 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[];
+    /**
+     * Programmatically grab an object at the current mouse position.
+     * Uses the externally set mouse position (via setFollowTarget('mouse', x, y))
+     * or the native canvas mouse position if no external position is set.
+     * Only objects with the 'grabable' tag can be grabbed.
+     * @returns The ID of the grabbed object, or null if no grabable object at position
+     */
+    startGrab(): string | null;
+    /**
+     * Release any currently grabbed object.
+     */
+    endGrab(): void;
+    /**
+     * Get the ID of the currently grabbed object.
+     * @returns The ID of the grabbed object, or null if nothing is grabbed
+     */
+    getGrabbedObject(): string | null;
+    /**
+     * 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 +1102,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,111 @@ 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[];
+    /**
+     * Programmatically grab an object at the current mouse position.
+     * Uses the externally set mouse position (via setFollowTarget('mouse', x, y))
+     * or the native canvas mouse position if no external position is set.
+     * Only objects with the 'grabable' tag can be grabbed.
+     * @returns The ID of the grabbed object, or null if no grabable object at position
+     */
+    startGrab(): string | null;
+    /**
+     * Release any currently grabbed object.
+     */
+    endGrab(): void;
+    /**
+     * Get the ID of the currently grabbed object.
+     * @returns The ID of the grabbed object, or null if nothing is grabbed
+     */
+    getGrabbedObject(): string | null;
+    /**
+     * 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 +1102,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 };