ecspresso 0.10.2 → 0.12.0

package/dist/type-utils.d.ts

@@ -2,6 +2,7 @@
  * Utility types for ECSpresso ECS framework
  * This file contains reusable type helpers used across the codebase
  */
+import type { ScreenDefinition } from './screen-types';
 /**
  * Check if two types are exactly the same for overlapping keys
  */
@@ -16,11 +17,89 @@ export type TypesAreCompatible<T extends Record<string, any>, U extends Record<s
     [K in keyof T & keyof U]: ExactlyCompatible<T[K], U[K]>;
 }[keyof T & keyof U] extends false ? false : true;
 /**
- * Bundle compatibility checker.
- * Returns true if bundles can be merged without type conflicts.
- * All overlapping keys across all type categories must have identical types.
+ * Single config object that bundles all 5 world type dimensions.
+ * Replaces the 5 positional type params (ComponentTypes, EventTypes,
+ * ResourceTypes, AssetTypes, ScreenStates) throughout the codebase.
  */
-export type BundlesAreCompatible<C1 extends Record<string, any>, C2 extends Record<string, any>, E1 extends Record<string, any>, E2 extends Record<string, any>, R1 extends Record<string, any>, R2 extends Record<string, any>, A1 extends Record<string, unknown> = {}, A2 extends Record<string, unknown> = {}, S1 extends Record<string, any> = {}, S2 extends Record<string, any> = {}> = TypesAreCompatible<C1, C2> extends true ? TypesAreCompatible<E1, E2> extends true ? TypesAreCompatible<R1, R2> extends true ? TypesAreCompatible<A1, A2> extends true ? TypesAreCompatible<S1, S2> : false : false : false : false;
+export interface WorldConfig {
+    readonly components: Record<string, any>;
+    readonly events: Record<string, any>;
+    readonly resources: Record<string, any>;
+    readonly assets: Record<string, unknown>;
+    readonly screens: Record<string, ScreenDefinition<any, any>>;
+}
+/**
+ * Construct a WorldConfig from individual type dimensions.
+ * All parameters default to empty records.
+ */
+export type WorldConfigFrom<C extends Record<string, any> = {}, E extends Record<string, any> = {}, R extends Record<string, any> = {}, A extends Record<string, unknown> = {}, S extends Record<string, ScreenDefinition<any, any>> = {}> = {
+    readonly components: C;
+    readonly events: E;
+    readonly resources: R;
+    readonly assets: A;
+    readonly screens: S;
+};
+/**
+ * Empty WorldConfig with all slots defaulting to {}.
+ */
+export type EmptyConfig = WorldConfigFrom;
+/**
+ * Merge two WorldConfig types by intersecting each slot.
+ */
+export type MergeConfigs<A extends WorldConfig, B extends WorldConfig> = {
+    readonly components: A['components'] & B['components'];
+    readonly events: A['events'] & B['events'];
+    readonly resources: A['resources'] & B['resources'];
+    readonly assets: A['assets'] & B['assets'];
+    readonly screens: A['screens'] & B['screens'];
+};
+export type WithComponents<Cfg extends WorldConfig, T> = {
+    readonly components: Cfg['components'] & T;
+    readonly events: Cfg['events'];
+    readonly resources: Cfg['resources'];
+    readonly assets: Cfg['assets'];
+    readonly screens: Cfg['screens'];
+};
+export type WithEvents<Cfg extends WorldConfig, T> = {
+    readonly components: Cfg['components'];
+    readonly events: Cfg['events'] & T;
+    readonly resources: Cfg['resources'];
+    readonly assets: Cfg['assets'];
+    readonly screens: Cfg['screens'];
+};
+export type WithResources<Cfg extends WorldConfig, T> = {
+    readonly components: Cfg['components'];
+    readonly events: Cfg['events'];
+    readonly resources: Cfg['resources'] & T;
+    readonly assets: Cfg['assets'];
+    readonly screens: Cfg['screens'];
+};
+export type WithAssets<Cfg extends WorldConfig, T> = {
+    readonly components: Cfg['components'];
+    readonly events: Cfg['events'];
+    readonly resources: Cfg['resources'];
+    readonly assets: Cfg['assets'] & T;
+    readonly screens: Cfg['screens'];
+};
+export type WithScreens<Cfg extends WorldConfig, T> = {
+    readonly components: Cfg['components'];
+    readonly events: Cfg['events'];
+    readonly resources: Cfg['resources'];
+    readonly assets: Cfg['assets'];
+    readonly screens: Cfg['screens'] & T;
+};
+/**
+ * Check if two WorldConfig types are compatible (no conflicting keys
+ * across any slot).
+ */
+export type ConfigsAreCompatible<A extends WorldConfig, B extends WorldConfig> = TypesAreCompatible<A['components'], B['components']> extends true ? TypesAreCompatible<A['events'], B['events']> extends true ? TypesAreCompatible<A['resources'], B['resources']> extends true ? TypesAreCompatible<A['assets'], B['assets']> extends true ? TypesAreCompatible<A['screens'], B['screens']> : false : false : false : false;
+/**
+ * Check if a Requires config is satisfied by an Accumulated config.
+ * Checks all five WorldConfig slots (components, events, resources, assets, screens).
+ * When Required is EmptyConfig, all slots have `keyof {} = never`,
+ * and `never extends X = true`, so empty requirements are always satisfied.
+ */
+export type RequirementsSatisfied<Accumulated extends WorldConfig, Required extends WorldConfig> = keyof Required['components'] extends keyof Accumulated['components'] ? keyof Required['events'] extends keyof Accumulated['events'] ? keyof Required['resources'] extends keyof Accumulated['resources'] ? keyof Required['assets'] extends keyof Accumulated['assets'] ? keyof Required['screens'] extends keyof Accumulated['screens'] ? true : false : false : false : false : false;
 /**
  * Utility type for merging two types
  */
@@ -29,7 +108,168 @@ export type Merge<T1, T2> = T1 & T2;
  * Utility type for merging an array of types
  */
 export type MergeAll<T extends any[]> = T extends [infer First, ...infer Rest] ? Rest extends [] ? First : Merge<First, MergeAll<Rest>> : {};
-export {};
 /**
- * Basic utility types that can be used independently
- */ 
+ * Wildcard ECSpresso type that any concrete instance is assignable to.
+ * Use as a generic constraint for functions that accept any ECSpresso world.
+ * Matches the phantom _cfg property declared on the ECSpresso class.
+ */
+export type AnyECSpresso = {
+    readonly _cfg: WorldConfig;
+};
+/**
+ * Wildcard Plugin type that any concrete plugin is assignable to.
+ * Matches the phantom _cfg and _requires properties declared on the Plugin interface.
+ */
+export type AnyPlugin = {
+    readonly _cfg?: WorldConfig;
+    readonly _requires?: WorldConfig;
+};
+/**
+ * Extract the full WorldConfig from a Plugin or ECSpresso instance
+ */
+export type ConfigOf<B> = B extends {
+    readonly _cfg: infer Cfg extends WorldConfig;
+} ? Cfg : never;
+/**
+ * Extract the ComponentTypes from a Plugin or ECSpresso instance
+ */
+export type ComponentsOf<B> = B extends {
+    readonly _cfg: {
+        components: infer C extends Record<string, any>;
+    };
+} ? C : B extends {
+    readonly _cfg?: {
+        components: infer C extends Record<string, any>;
+    };
+} ? C : never;
+/**
+ * Extract the EventTypes from a Plugin or ECSpresso instance
+ */
+export type EventsOf<B> = B extends {
+    readonly _cfg: {
+        events: infer E extends Record<string, any>;
+    };
+} ? E : B extends {
+    readonly _cfg?: {
+        events: infer E extends Record<string, any>;
+    };
+} ? E : never;
+/**
+ * Extract the ResourceTypes from a Plugin or ECSpresso instance
+ */
+export type ResourcesOf<B> = B extends {
+    readonly _cfg: {
+        resources: infer R extends Record<string, any>;
+    };
+} ? R : B extends {
+    readonly _cfg?: {
+        resources: infer R extends Record<string, any>;
+    };
+} ? R : never;
+/**
+ * Extract AssetTypes from a Plugin or ECSpresso instance
+ */
+export type AssetTypesOf<B> = B extends {
+    readonly _cfg: {
+        assets: infer A extends Record<string, unknown>;
+    };
+} ? A : B extends {
+    readonly _cfg?: {
+        assets: infer A extends Record<string, unknown>;
+    };
+} ? A : never;
+/**
+ * Extract ScreenStates from a Plugin or ECSpresso instance
+ */
+export type ScreenStatesOf<B> = B extends {
+    readonly _cfg: {
+        screens: infer S extends Record<string, ScreenDefinition<any, any>>;
+    };
+} ? S : B extends {
+    readonly _cfg?: {
+        screens: infer S extends Record<string, ScreenDefinition<any, any>>;
+    };
+} ? S : never;
+/**
+ * Extract the system Labels from a Plugin instance
+ */
+export type LabelsOf<B> = B extends {
+    readonly _labels?: infer L;
+} ? L extends string ? L : never : never;
+/**
+ * Extract the system Groups from a Plugin instance
+ */
+export type GroupsOf<B> = B extends {
+    readonly _groups?: infer G;
+} ? G extends string ? G : never : never;
+/**
+ * Extract the AssetGroupNames from a Plugin instance
+ */
+export type AssetGroupNamesOf<B> = B extends {
+    readonly _assetGroupNames?: infer AG;
+} ? AG extends string ? AG : never : never;
+/**
+ * Extract the ReactiveQueryNames from a Plugin instance
+ */
+export type ReactiveQueryNamesOf<B> = B extends {
+    readonly _reactiveQueryNames?: infer RQ;
+} ? RQ extends string ? RQ : never : never;
+/**
+ * Extract ComponentTypes from an ECSpresso world instance type.
+ */
+export type ComponentsOfWorld<W> = W extends {
+    readonly _cfg: {
+        components: infer C extends Record<string, any>;
+    };
+} ? C : never;
+/**
+ * Extract EventTypes from an ECSpresso world instance type.
+ */
+export type EventsOfWorld<W> = W extends {
+    readonly _cfg: {
+        events: infer E extends Record<string, any>;
+    };
+} ? E : never;
+/**
+ * Extract AssetTypes from an ECSpresso world instance type.
+ */
+export type AssetsOfWorld<W> = W extends {
+    readonly _cfg: {
+        assets: infer A extends Record<string, unknown>;
+    };
+} ? A : never;
+/**
+ * Extract ScreenStates from an ECSpresso world instance type
+ */
+export type ScreenStatesOfWorld<W> = W extends {
+    readonly _cfg: {
+        screens: infer S extends Record<string, ScreenDefinition<any, any>>;
+    };
+} ? S : never;
+/**
+ * Extract event names from an EventTypes record whose payload extends the given shape.
+ * Eliminates the need for each plugin to define its own mapped filter type.
+ *
+ * @example
+ * ```typescript
+ * interface MyEventData { entityId: number }
+ * type MyEventName<ET> = EventNameMatching<ET, MyEventData>;
+ * ```
+ */
+export type EventNameMatching<ET extends Record<string, any>, Payload> = {
+    [K in keyof ET & string]: ET[K] extends Payload ? K : never;
+}[keyof ET & string];
+/**
+ * Extract the channel type from a world's AudioSource component.
+ * Falls back to `string` if the world has no audioSource component.
+ */
+export type ChannelOfWorld<W> = W extends {
+    readonly _cfg: {
+        components: {
+            audioSource: {
+                channel: infer Ch extends string;
+            };
+        };
+    };
+} ? Ch : string;
+export {};

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import ECSpresso from "./ecspresso";
+import type { WorldConfig, EmptyConfig, WorldConfigFrom } from "./type-utils";
 /**
  * Execution phase for systems. Systems are grouped by phase and executed
  * in this fixed order: preUpdate -> fixedUpdate -> update -> postUpdate -> render.
@@ -18,17 +19,6 @@ export interface RemoveEntityOptions {
      */
     cascade?: boolean;
 }
-/**
- * Event data emitted when an entity's parent changes
- */
-export interface HierarchyChangedEvent {
-    /** The entity whose parent changed */
-    entityId: number;
-    /** The previous parent, or null if entity had no parent */
-    oldParent: number | null;
-    /** The new parent, or null if entity was orphaned */
-    newParent: number | null;
-}
 /**
  * Options for hierarchy traversal methods
  */
@@ -47,10 +37,6 @@ export interface HierarchyEntry {
     /** Depth in the hierarchy (0 for roots) */
     depth: number;
 }
-export interface EventHandler<T> {
-    callback: (data: T) => void;
-    once: boolean;
-}
 export interface FilteredEntity<ComponentTypes, WithComponents extends keyof ComponentTypes = never, WithoutComponents extends keyof ComponentTypes = never, OptionalComponents extends keyof ComponentTypes = never> {
     id: number;
     components: Omit<Partial<ComponentTypes>, WithoutComponents | OptionalComponents> & {
@@ -124,7 +110,7 @@ export type QueryDefinition<ComponentTypes extends Record<string, any>, WithComp
  *
  * world.addSystem('movement')
  *   .addQuery('entities', movingEntitiesQuery)
- *   .setProcess((queries) => {
+ *   .setProcess(({ queries }) => {
  *     for (const entity of queries.entities) {
  *       updatePosition(entity);
  *     }
@@ -138,7 +124,7 @@ export declare function createQueryDefinition<ComponentTypes extends Record<stri
     optional?: ReadonlyArray<keyof ComponentTypes>;
     parentHas?: ReadonlyArray<keyof ComponentTypes>;
 }>(queryDef: QueryDef): QueryDef;
-export interface System<ComponentTypes extends Record<string, any> = {}, WithComponents extends keyof ComponentTypes = never, WithoutComponents extends keyof ComponentTypes = never, EventTypes extends Record<string, any> = {}, ResourceTypes extends Record<string, any> = {}, AssetTypes extends Record<string, unknown> = {}, ScreenStates extends Record<string, any> = {}> {
+export interface System<Cfg extends WorldConfig = EmptyConfig, WithComponents extends keyof Cfg['components'] = never, WithoutComponents extends keyof Cfg['components'] = never> {
     label: string;
     /**
      * System priority - higher values execute first (default: 0)
@@ -159,53 +145,86 @@ export interface System<ComponentTypes extends Record<string, any> = {}, WithCom
      * Screens where this system should run. If specified, system only runs
      * when current screen is in this list.
      */
-    inScreens?: string[];
+    inScreens?: ReadonlyArray<keyof Cfg['screens'] & string>;
     /**
      * Screens where this system should NOT run. If specified, system skips
      * when current screen is in this list.
      */
-    excludeScreens?: string[];
+    excludeScreens?: ReadonlyArray<keyof Cfg['screens'] & string>;
     /**
      * Assets that must be loaded for this system to run.
      * System will be skipped if any required asset is not loaded.
      */
-    requiredAssets?: string[];
+    requiredAssets?: ReadonlyArray<keyof Cfg['assets'] & string>;
+    /**
+     * When true, the system's process function runs even when all queries
+     * return zero entities. Default is false (system is skipped when all
+     * queries are empty).
+     */
+    runWhenEmpty?: boolean;
     entityQueries?: {
-        [queryName: string]: QueryConfig<ComponentTypes, WithComponents, WithoutComponents>;
+        [queryName: string]: QueryConfig<Cfg['components'], WithComponents, WithoutComponents>;
     };
     /**
-     * Process method that runs during each update cycle
-     * @param queries The entity queries results based on system's entityQueries definition
-     * @param deltaTime Time elapsed since the last update in seconds
-     * @param ecs The ECSpresso instance providing access to all ECS functionality
+     * Process method that runs during each update cycle.
+     * Receives a single context object with queries, dt, and ecs.
      */
-    process?(queries: {
-        [queryName: string]: Array<FilteredEntity<ComponentTypes, WithComponents, WithoutComponents>>;
-    } | Array<FilteredEntity<ComponentTypes, WithComponents, WithoutComponents>>, deltaTime: number, ecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>): void;
+    process?(ctx: {
+        queries: {
+            [queryName: string]: Array<FilteredEntity<Cfg['components'], WithComponents, WithoutComponents>>;
+        };
+        dt: number;
+        ecs: ECSpresso<Cfg>;
+    }): void;
     /**
      * Lifecycle hook called when the system is initialized
      * This is called when ECSpresso.initialize() is invoked, after resources are initialized
      * Use this for one-time initialization that depends on resources
      * @param ecs The ECSpresso instance providing access to all ECS functionality
      */
-    onInitialize?(ecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>): void | Promise<void>;
+    onInitialize?(ecs: ECSpresso<Cfg>): void | Promise<void>;
     /**
      * Lifecycle hook called when the system is detached from the ECS
      * @param ecs The ECSpresso instance providing access to all ECS functionality
      */
-    onDetach?(ecs: import("./ecspresso").default<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>): void;
+    onDetach?(ecs: import("./ecspresso").default<Cfg>): void;
+    /**
+     * Per-query callbacks that fire once per entity the first time it appears
+     * in a query's results. Fires before process. Automatic cleanup when
+     * entity leaves query (component removed, entity destroyed) so re-entry
+     * fires the callback again.
+     */
+    onEntityEnter?: Record<string, (ctx: {
+        entity: FilteredEntity<Cfg['components'], WithComponents, WithoutComponents>;
+        ecs: ECSpresso<Cfg>;
+    }) => void>;
     /**
      * Event handlers for specific event types
      */
     eventHandlers?: {
-        [EventName in keyof EventTypes]?: {
-            /**
-             * Event handler function
-             * @param data The event data specific to this event type
-             * @param ecs The ECSpresso instance providing access to all ECS functionality
-             */
-            handler(data: EventTypes[EventName], ecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>): void;
-        };
+        [EventName in keyof Cfg['events']]?: (ctx: {
+            data: Cfg['events'][EventName];
+            ecs: ECSpresso<Cfg>;
+        }) => void;
     };
 }
-export type { Merge, MergeAll } from './type-utils';
+/**
+ * Typed world interface for plugin helpers and structural typing.
+ *
+ * Generic over component types `C`:
+ * - `BaseWorld` (no param): defaults to `{}`, meaning component-accessing methods
+ *   cannot be called (keys resolve to `never`). Use for functions that only need
+ *   `removeEntity`, `getResource`, etc.
+ * - `BaseWorld<MyComponents>`: narrows `getComponent`, `hasComponent`, `markChanged`,
+ *   `spawn`, and command buffer methods to the declared component map.
+ *
+ * Structural typing ensures any `ECSpresso<Cfg>` where `Cfg['components']` is a
+ * superset of `C` satisfies `BaseWorld<C>`.
+ */
+type _BaseWorldCfg<C extends Record<string, any>> = WorldConfigFrom<C, Record<string, any>, Record<string, any>, Record<string, unknown>, Record<string, any>>;
+type _EventBus = import("./event-bus").default<Record<string, any>>;
+export type BaseWorld<C extends Record<string, any> = {}> = Pick<ECSpresso<_BaseWorldCfg<C>>, 'getComponent' | 'hasComponent' | 'removeEntity' | 'spawn' | 'markChanged' | 'getResource' | 'hasResource'> & {
+    eventBus: Pick<_EventBus, 'publish'>;
+    commands: Pick<import("./command-buffer").default<_BaseWorldCfg<C>>, 'spawn' | 'removeEntity' | 'addComponent' | 'removeComponent'>;
+};
+export type { Merge, MergeAll, TypesAreCompatible, ComponentsOf, EventsOf, ResourcesOf, LabelsOf, GroupsOf, AssetGroupNamesOf, ReactiveQueryNamesOf, AssetTypesOf, ScreenStatesOf, ComponentsOfWorld, EventsOfWorld, AssetsOfWorld, ScreenStatesOfWorld, AnyECSpresso, AnyPlugin, EventNameMatching, ChannelOfWorld, WorldConfig, EmptyConfig, WorldConfigFrom, MergeConfigs, ConfigsAreCompatible, ConfigOf, WithComponents, WithEvents, WithResources, WithAssets, WithScreens } from './type-utils';

package/dist/utils/check-required-cycle.d.ts

@@ -0,0 +1,12 @@
+/**
+ * BFS cycle detection for required component graphs.
+ * Shared by ECSpresso and Plugin.
+ *
+ * @param trigger     The component that triggers the requirement
+ * @param newRequired The component about to be added as required
+ * @param getRequirements Callback returning the existing requirements for a component
+ * @throws Error if adding trigger→newRequired would create a cycle
+ */
+export declare function checkRequiredCycle<K>(trigger: K, newRequired: K, getRequirements: (component: K) => Iterable<{
+    component: K;
+}> | undefined): void;

package/dist/utils/easing.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Easing Functions
+ *
+ * 31 standard easing functions for animation. Pure math, no dependencies.
+ */
+export type EasingFn = (t: number) => number;
+export declare function linear(t: number): number;
+export declare function easeInQuad(t: number): number;
+export declare function easeOutQuad(t: number): number;
+export declare function easeInOutQuad(t: number): number;
+export declare function easeInCubic(t: number): number;
+export declare function easeOutCubic(t: number): number;
+export declare function easeInOutCubic(t: number): number;
+export declare function easeInQuart(t: number): number;
+export declare function easeOutQuart(t: number): number;
+export declare function easeInOutQuart(t: number): number;
+export declare function easeInQuint(t: number): number;
+export declare function easeOutQuint(t: number): number;
+export declare function easeInOutQuint(t: number): number;
+export declare function easeInSine(t: number): number;
+export declare function easeOutSine(t: number): number;
+export declare function easeInOutSine(t: number): number;
+export declare function easeInExpo(t: number): number;
+export declare function easeOutExpo(t: number): number;
+export declare function easeInOutExpo(t: number): number;
+export declare function easeInCirc(t: number): number;
+export declare function easeOutCirc(t: number): number;
+export declare function easeInOutCirc(t: number): number;
+export declare function easeInBack(t: number): number;
+export declare function easeOutBack(t: number): number;
+export declare function easeInOutBack(t: number): number;
+export declare function easeInElastic(t: number): number;
+export declare function easeOutElastic(t: number): number;
+export declare function easeInOutElastic(t: number): number;
+export declare function easeOutBounce(t: number): number;
+export declare function easeInBounce(t: number): number;
+export declare function easeInOutBounce(t: number): number;
+/** Runtime lookup of all easing functions by name */
+export declare const easings: {
+    readonly linear: typeof linear;
+    readonly easeInQuad: typeof easeInQuad;
+    readonly easeOutQuad: typeof easeOutQuad;
+    readonly easeInOutQuad: typeof easeInOutQuad;
+    readonly easeInCubic: typeof easeInCubic;
+    readonly easeOutCubic: typeof easeOutCubic;
+    readonly easeInOutCubic: typeof easeInOutCubic;
+    readonly easeInQuart: typeof easeInQuart;
+    readonly easeOutQuart: typeof easeOutQuart;
+    readonly easeInOutQuart: typeof easeInOutQuart;
+    readonly easeInQuint: typeof easeInQuint;
+    readonly easeOutQuint: typeof easeOutQuint;
+    readonly easeInOutQuint: typeof easeInOutQuint;
+    readonly easeInSine: typeof easeInSine;
+    readonly easeOutSine: typeof easeOutSine;
+    readonly easeInOutSine: typeof easeInOutSine;
+    readonly easeInExpo: typeof easeInExpo;
+    readonly easeOutExpo: typeof easeOutExpo;
+    readonly easeInOutExpo: typeof easeInOutExpo;
+    readonly easeInCirc: typeof easeInCirc;
+    readonly easeOutCirc: typeof easeOutCirc;
+    readonly easeInOutCirc: typeof easeInOutCirc;
+    readonly easeInBack: typeof easeInBack;
+    readonly easeOutBack: typeof easeOutBack;
+    readonly easeInOutBack: typeof easeInOutBack;
+    readonly easeInElastic: typeof easeInElastic;
+    readonly easeOutElastic: typeof easeOutElastic;
+    readonly easeInOutElastic: typeof easeInOutElastic;
+    readonly easeInBounce: typeof easeInBounce;
+    readonly easeOutBounce: typeof easeOutBounce;
+    readonly easeInOutBounce: typeof easeInOutBounce;
+};

package/dist/utils/math.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Shared 2D vector math utilities for ECSpresso bundles.
+ * All functions are pure — they return new vectors, never mutate inputs.
+ */
+/**
+ * A 2D vector with x and y components.
+ */
+export interface Vector2D {
+    x: number;
+    y: number;
+}
+/**
+ * Create a Vector2D from x and y components.
+ */
+export declare function vec2(x: number, y: number): Vector2D;
+/**
+ * Return a zero vector {x: 0, y: 0}.
+ */
+export declare function vec2Zero(): Vector2D;
+/**
+ * Add two vectors component-wise.
+ */
+export declare function vec2Add(a: Vector2D, b: Vector2D): Vector2D;
+/**
+ * Subtract b from a component-wise.
+ */
+export declare function vec2Sub(a: Vector2D, b: Vector2D): Vector2D;
+/**
+ * Scale a vector by a scalar.
+ */
+export declare function vec2Scale(v: Vector2D, scalar: number): Vector2D;
+/**
+ * Negate a vector (flip both components).
+ */
+export declare function vec2Negate(v: Vector2D): Vector2D;
+/**
+ * Compute the dot product of two vectors.
+ */
+export declare function vec2Dot(a: Vector2D, b: Vector2D): number;
+/**
+ * Compute the 2D cross product (scalar z-component of the 3D cross product).
+ */
+export declare function vec2Cross(a: Vector2D, b: Vector2D): number;
+/**
+ * Compute the squared length of a vector. Avoids sqrt when only comparing magnitudes.
+ */
+export declare function vec2LengthSq(v: Vector2D): number;
+/**
+ * Compute the length (magnitude) of a vector.
+ */
+export declare function vec2Length(v: Vector2D): number;
+/**
+ * Return a unit vector in the same direction. Returns zero vector if input is zero-length.
+ */
+export declare function vec2Normalize(v: Vector2D): Vector2D;
+/**
+ * Compute the squared distance between two points. Avoids sqrt when only comparing.
+ */
+export declare function vec2DistanceSq(a: Vector2D, b: Vector2D): number;
+/**
+ * Compute the distance between two points.
+ */
+export declare function vec2Distance(a: Vector2D, b: Vector2D): number;
+/**
+ * Check if two vectors are approximately equal within an epsilon tolerance.
+ */
+export declare function vec2Equals(a: Vector2D, b: Vector2D, epsilon?: number): boolean;

package/dist/utils/narrowphase.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Shared Narrowphase Module
+ *
+ * Provides contact-computing narrowphase tests and a generic collision
+ * iteration pipeline used by both the collision plugin (event-only) and
+ * the physics2D plugin (impulse response).
+ */
+import type { SpatialIndex } from './spatial-hash';
+/** Contact result from a narrowphase test. Normal points from A toward B. */
+export interface Contact {
+    normalX: number;
+    normalY: number;
+    /** Penetration depth (positive = overlapping) */
+    depth: number;
+}
+/** Minimum collider data shared by collision and physics bundles. */
+export interface BaseColliderInfo<L extends string = string> {
+    entityId: number;
+    x: number;
+    y: number;
+    layer: L;
+    collidesWith: readonly L[];
+    aabb?: {
+        halfWidth: number;
+        halfHeight: number;
+    };
+    circle?: {
+        radius: number;
+    };
+}
+/**
+ * Build a BaseColliderInfo from raw entity/collider component data.
+ * Returns null if the entity has neither an AABB nor circle collider.
+ * Shared by collision plugin (event-only) and physics2D plugin (impulse response).
+ */
+export declare function buildBaseColliderInfo<L extends string>(entityId: number, x: number, y: number, layer: L, collidesWith: readonly L[], aabb: {
+    width: number;
+    height: number;
+    offsetX?: number;
+    offsetY?: number;
+} | undefined, circle: {
+    radius: number;
+    offsetX?: number;
+    offsetY?: number;
+} | undefined): BaseColliderInfo<L> | null;
+/**
+ * Retrieve the optional spatialIndex resource, returning undefined when absent.
+ * Centralizes the cross-plugin typed lookup so individual plugins don't each
+ * need to import SpatialIndex or repeat the tryGetResource pattern.
+ */
+export declare function tryGetSpatialIndex(tryGetResource: <T>(key: string) => T | undefined): SpatialIndex | undefined;
+export declare function computeAABBvsAABB(ax: number, ay: number, ahw: number, ahh: number, bx: number, by: number, bhw: number, bhh: number): Contact | null;
+export declare function computeCircleVsCircle(ax: number, ay: number, ar: number, bx: number, by: number, br: number): Contact | null;
+export declare function computeAABBvsCircle(aabbX: number, aabbY: number, ahw: number, ahh: number, circleX: number, circleY: number, radius: number): Contact | null;
+export declare function computeContact(a: BaseColliderInfo, b: BaseColliderInfo): Contact | null;
+/**
+ * Generic collision detection pipeline: brute-force or broadphase,
+ * with layer filtering and contact computation.
+ *
+ * Uses a context parameter forwarded to the callback to avoid
+ * per-frame closure allocation.
+ */
+export declare function detectCollisions<I extends BaseColliderInfo, C>(colliders: I[], spatialIndex: SpatialIndex | undefined, onContact: (a: I, b: I, contact: Contact, context: C) => void, context: C): void;