ecspresso/dist/plugins/physics/collision3D.d.ts

A minimal Entity-Component-System library for typescript and javascript.

/**
 * Collision 3D Plugin for ECSpresso
 *
 * Provides layer-based 3D collision detection with events.
 * Uses worldTransform3D for position (world-space collision).
 * Supports AABB3D and sphere colliders.
 */
import { type BasePluginOptions } from 'ecspresso';
import type { Transform3DWorldConfig } from '../spatial/transform3D';
import { defineCollisionLayers, createCollisionPairHandler, createCollisionLayer, type CollisionLayer, type LayerFactories, type LayersOf, type CollisionPairCallback } from './collision';
export { defineCollisionLayers, createCollisionPairHandler, createCollisionLayer };
export type { CollisionLayer, LayerFactories, LayersOf, CollisionPairCallback };
export type { AABB3DCollider, SphereCollider } from '../spatial/spatial-index3D';
import type { AABB3DCollider, SphereCollider } from '../spatial/spatial-index3D';
/**
 * Component types provided by the collision3D plugin.
 */
export interface Collision3DComponentTypes<L extends string = never> {
    aabb3DCollider: AABB3DCollider;
    sphereCollider: SphereCollider;
    collisionLayer: CollisionLayer<L>;
}
/**
 * Event fired when two 3D entities collide.
 *
 * Normal components are flattened to avoid per-event allocation in the hot path.
 */
export interface Collision3DEvent<L extends string = never> {
    entityA: number;
    entityB: number;
    layerA: L;
    layerB: L;
    /** Contact normal X, pointing from entityA toward entityB */
    normalX: number;
    /** Contact normal Y, pointing from entityA toward entityB */
    normalY: number;
    /** Contact normal Z, pointing from entityA toward entityB */
    normalZ: number;
    /** Penetration depth (positive = overlapping) */
    depth: number;
}
/**
 * Event types provided by the collision3D plugin.
 */
export interface Collision3DEventTypes<L extends string = never> {
    collision3D: Collision3DEvent<L>;
}
/**
 * Configuration options for the collision3D plugin.
 */
export interface Collision3DPluginOptions<G extends string = 'physics'> extends BasePluginOptions<G> {
}
export declare function createAABB3DCollider(width: number, height: number, depth: number, offsetX?: number, offsetY?: number, offsetZ?: number): {
    aabb3DCollider: AABB3DCollider;
};
export declare function createSphereCollider(radius: number, offsetX?: number, offsetY?: number, offsetZ?: number): {
    sphereCollider: SphereCollider;
};
/**
 * Create a 3D collision plugin for ECSpresso.
 *
 * Provides layer-based collision detection between entities with 3D colliders,
 * publishing `collision3D` events on contact. Supports AABB3D-AABB3D,
 * sphere-sphere, and AABB3D-sphere tests. Automatically uses the
 * `spatialIndex3D` resource for broadphase when present.
 *
 * @example
 * ```typescript
 * const layers = defineCollisionLayers({ player: ['enemy'], enemy: ['player'] });
 * const ecs = ECSpresso
 *   .create()
 *   .withPlugin(createTransform3DPlugin())
 *   .withPlugin(createCollision3DPlugin({ layers }))
 *   .build();
 *
 * ecs.eventBus.subscribe('collision3D', (data) => {
 *   console.log(data.entityA, data.entityB, data.normalZ);
 * });
 * ```
 */
export declare function createCollision3DPlugin<L extends string, G extends string = 'physics'>(options: Collision3DPluginOptions<G> & {
    layers: LayerFactories<Record<L, readonly string[]>>;
}): import("ecspresso").Plugin<import("ecspresso").WithEvents<import("ecspresso").WithComponents<import("ecspresso").EmptyConfig, Collision3DComponentTypes<L>>, Collision3DEventTypes<L>>, Transform3DWorldConfig, "collision3D-detection", G, never, never>;