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

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

/**
 * Steering Plugin for ECSpresso
 *
 * Provides simple move-to-target behavior with arrival detection.
 * Entities with a `moveTarget` component move toward the target position
 * at their configured `moveSpeed`. The `moveTarget` component is removed
 * on arrival and an `arriveAtTarget` event is published.
 */
import { type BasePluginOptions } from 'ecspresso';
import type { ComponentsConfig, EventsConfig } from 'ecspresso';
import type { TransformWorldConfig } from '../spatial/transform';
/**
 * Target position for an entity to move toward.
 * Removed automatically when the entity arrives.
 */
export interface MoveTarget {
    x: number;
    y: number;
}
/**
 * Component types provided by the steering plugin.
 */
export interface SteeringComponentTypes {
    moveTarget: MoveTarget;
    moveSpeed: number;
}
/**
 * Event fired when an entity arrives at its move target.
 */
export interface ArriveAtTargetEvent {
    entityId: number;
}
/**
 * Event types provided by the steering plugin.
 */
export interface SteeringEventTypes {
    arriveAtTarget: ArriveAtTargetEvent;
}
/**
 * WorldConfig representing the steering plugin's provided types.
 * Used as the `Requires` type parameter by plugins that depend on steering.
 */
export type SteeringWorldConfig = ComponentsConfig<SteeringComponentTypes> & EventsConfig<SteeringEventTypes>;
/**
 * Configuration options for the steering plugin.
 */
export interface SteeringPluginOptions<G extends string = 'steering'> extends BasePluginOptions<G> {
    /** Distance threshold to consider arrival (default: 2) */
    arrivalThreshold?: number;
}
/**
 * Create a moveTarget component.
 *
 * @param x Target x position
 * @param y Target y position
 * @returns Component object suitable for spreading into spawn()
 *
 * @example
 * ```typescript
 * ecs.addComponent(entityId, 'moveTarget', createMoveTarget(200, 300).moveTarget);
 * ```
 */
export declare function createMoveTarget(x: number, y: number): Pick<SteeringComponentTypes, 'moveTarget'>;
/**
 * Create a moveSpeed component.
 *
 * @param speed Movement speed in pixels per second
 * @returns Component object suitable for spreading into spawn()
 *
 * @example
 * ```typescript
 * ecs.spawn({
 *   ...createTransform(100, 200),
 *   ...createMoveSpeed(150),
 * });
 * ```
 */
export declare function createMoveSpeed(speed: number): Pick<SteeringComponentTypes, 'moveSpeed'>;
/**
 * Create a steering plugin for ECSpresso.
 *
 * Provides a `move-to-target` system that moves entities with `moveTarget`
 * and `moveSpeed` components toward their target position. On arrival,
 * the `moveTarget` component is removed and an `arriveAtTarget` event is published.
 *
 * @example
 * ```typescript
 * const ecs = ECSpresso.create()
 *   .withPlugin(createTransformPlugin())
 *   .withPlugin(createSteeringPlugin())
 *   .build();
 *
 * await ecs.initialize();
 *
 * ecs.spawn({
 *   ...createTransform(0, 0),
 *   ...createMoveSpeed(100),
 *   ...createMoveTarget(200, 200),
 * });
 * ```
 */
export declare function createSteeringPlugin<G extends string = 'steering'>(options?: SteeringPluginOptions<G>): import("ecspresso").Plugin<import("ecspresso").WithEvents<import("ecspresso").WithComponents<import("ecspresso").EmptyConfig, SteeringComponentTypes>, SteeringEventTypes>, TransformWorldConfig, "move-to-target", G, never, never>;