ecspresso/dist/plugins/spatial/bounds.d.ts

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

/**
 * Bounds Plugin for ECSpresso
 *
 * Provides screen bounds enforcement for entities with transforms.
 * Reads worldTransform for position checking; modifies localTransform for corrections.
 * Supports destroy, clamp, and wrap behaviors.
 */
import { type BasePluginOptions } from 'ecspresso';
import type { TransformWorldConfig } from './transform';
/**
 * Component that marks an entity for destruction when outside bounds.
 */
export interface DestroyOutOfBounds {
    /** Extra padding beyond bounds before destruction (default: 0) */
    padding?: number;
}
/**
 * Component that clamps an entity's position to stay within bounds.
 */
export interface ClampToBounds {
    /** Margin to shrink the valid area (default: 0) */
    margin?: number;
}
/**
 * Component that wraps an entity's position to the opposite edge.
 */
export interface WrapAtBounds {
    /** Padding beyond bounds before wrapping (default: 0) */
    padding?: number;
}
/**
 * Component types provided by the bounds plugin.
 * Included automatically via `.withPlugin(createBoundsPlugin())`.
 *
 * @example
 * ```typescript
 * const ecs = ECSpresso.create()
 *   .withPlugin(createTransformPlugin())
 *   .withPlugin(createBoundsPlugin({ width: 800, height: 600 }))
 *   .withComponentTypes<{ sprite: Sprite }>()
 *   .build();
 * ```
 */
export interface BoundsComponentTypes {
    destroyOutOfBounds: DestroyOutOfBounds;
    clampToBounds: ClampToBounds;
    wrapAtBounds: WrapAtBounds;
}
/**
 * Bounds rectangle definition.
 */
export interface BoundsRect {
    /** Left edge x coordinate (default: 0) */
    x?: number;
    /** Top edge y coordinate (default: 0) */
    y?: number;
    /** Width of the bounds area */
    width: number;
    /** Height of the bounds area */
    height: number;
}
/**
 * Resource types provided by the bounds plugin.
 */
export interface BoundsResourceTypes {
    bounds: BoundsRect;
}
/**
 * Event fired when an entity exits bounds.
 */
export interface EntityOutOfBoundsEvent {
    /** The entity that exited bounds */
    entityId: number;
    /** The edge the entity exited through */
    exitEdge: 'top' | 'bottom' | 'left' | 'right';
}
/**
 * Event types provided by the bounds plugin.
 */
export interface BoundsEventTypes {
    entityOutOfBounds: EntityOutOfBoundsEvent;
}
/**
 * Configuration options for the bounds plugin.
 */
export interface BoundsPluginOptions<G extends string = 'physics'> extends BasePluginOptions<G> {
    /** Resource key for bounds rectangle (default: 'bounds') */
    boundsResourceKey?: string;
    /** Whether to auto-remove entities when out of bounds (default: true) */
    autoRemove?: boolean;
}
/**
 * Create a bounds rectangle resource.
 *
 * @param width The width of the bounds area
 * @param height The height of the bounds area
 * @param x The left edge x coordinate (default: 0)
 * @param y The top edge y coordinate (default: 0)
 * @returns Bounds rectangle suitable for use as a resource
 *
 * @example
 * ```typescript
 * ECSpresso.create()
 *   .withResource('bounds', createBounds(800, 600))
 *   .build();
 * ```
 */
export declare function createBounds(width: number, height: number, x?: number, y?: number): BoundsRect;
/**
 * Create a destroyOutOfBounds component.
 *
 * @param padding Extra padding beyond bounds before destruction
 * @returns Component object suitable for spreading into spawn()
 *
 * @example
 * ```typescript
 * ecs.spawn({
 *   ...createTransform(100, 200),
 *   ...createDestroyOutOfBounds(20),
 * });
 * ```
 */
export declare function createDestroyOutOfBounds(padding?: number): Pick<BoundsComponentTypes, 'destroyOutOfBounds'>;
/**
 * Create a clampToBounds component.
 *
 * @param margin Margin to shrink the valid area
 * @returns Component object suitable for spreading into spawn()
 *
 * @example
 * ```typescript
 * ecs.spawn({
 *   ...createTransform(100, 200),
 *   ...createClampToBounds(30),
 * });
 * ```
 */
export declare function createClampToBounds(margin?: number): Pick<BoundsComponentTypes, 'clampToBounds'>;
/**
 * Create a wrapAtBounds component.
 *
 * @param padding Padding beyond bounds before wrapping
 * @returns Component object suitable for spreading into spawn()
 *
 * @example
 * ```typescript
 * ecs.spawn({
 *   ...createTransform(100, 200),
 *   ...createWrapAtBounds(10),
 * });
 * ```
 */
export declare function createWrapAtBounds(padding?: number): Pick<BoundsComponentTypes, 'wrapAtBounds'>;
/**
 * Create a bounds plugin for ECSpresso.
 *
 * This plugin provides:
 * - Destroy out of bounds system - removes entities that exit bounds
 * - Clamp to bounds system - constrains entities within bounds
 * - Wrap at bounds system - wraps entities to opposite edge
 *
 * Uses worldTransform for position checking (world-space) and modifies
 * localTransform for corrections. Works best with entities that don't
 * have parent transforms (orphan entities).
 *
 * @example
 * ```typescript
 * const ecs = ECSpresso
 *   .create<Components, Events, Resources>()
 *   .withResource('bounds', createBounds(800, 600))
 *   .withPlugin(createTransformPlugin())
 *   .withPlugin(createBoundsPlugin())
 *   .build();
 *
 * // Entity that gets destroyed when leaving screen
 * ecs.spawn({
 *   ...createTransform(100, 200),
 *   ...createDestroyOutOfBounds(),
 * });
 * ```
 */
export declare function createBoundsPlugin<ResourceTypes extends BoundsResourceTypes = BoundsResourceTypes, G extends string = 'physics'>(options?: BoundsPluginOptions<G>): import("ecspresso").Plugin<import("ecspresso").WithResources<import("ecspresso").WithEvents<import("ecspresso").WithComponents<import("ecspresso").EmptyConfig, BoundsComponentTypes>, BoundsEventTypes>, ResourceTypes>, TransformWorldConfig, "bounds-destroy" | "bounds-clamp" | "bounds-wrap", G, never, never>;