ecspresso/dist/plugins/combat/projectile.d.ts

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

/**
 * Projectile Plugin for ECSpresso
 *
 * Provides projectile movement (homing and linear) and collision integration.
 * Homing projectiles track a target entity's position each frame.
 * Linear projectiles move in a fixed direction.
 * When a collision involves a projectile, a `projectileHit` event is published
 * and a `damage` event is forwarded to the target (if the health plugin is present).
 */
import { type BasePluginOptions } from 'ecspresso';
import type { ComponentsConfig, EventsConfig } from 'ecspresso';
import type { TransformWorldConfig } from '../spatial/transform';
import type { CollisionEventTypes } from '../physics/collision';
import type { DamageEvent } from './health';
/**
 * Core projectile data.
 */
export interface Projectile {
    damage: number;
    speed: number;
    /** Entity that fired this projectile */
    sourceId: number;
}
/**
 * Homing target — projectile tracks this entity's position each frame.
 */
export interface ProjectileTarget {
    entityId: number;
}
/**
 * Fixed direction for non-homing projectiles (normalized).
 */
export interface ProjectileDirection {
    x: number;
    y: number;
}
/**
 * Component types provided by the projectile plugin.
 */
export interface ProjectileComponentTypes {
    projectile: Projectile;
    projectileTarget: ProjectileTarget;
    projectileDirection: ProjectileDirection;
}
/**
 * Event fired when a projectile hits a target via collision.
 */
export interface ProjectileHitEvent {
    projectileId: number;
    targetId: number;
    damage: number;
}
/**
 * Event types provided by the projectile plugin.
 */
export interface ProjectileEventTypes {
    projectileHit: ProjectileHitEvent;
    damage: DamageEvent;
}
/**
 * WorldConfig representing the projectile plugin's provided types.
 */
export type ProjectileWorldConfig = ComponentsConfig<ProjectileComponentTypes> & EventsConfig<ProjectileEventTypes>;
export interface ProjectilePluginOptions<G extends string = 'combat'> extends BasePluginOptions<G> {
    /**
     * Whether to auto-publish `damage` events on hit.
     * Requires the health plugin to be installed. (default: true)
     */
    publishDamage?: boolean;
}
/**
 * Create a projectile component.
 *
 * @param damage Damage dealt on hit
 * @param speed Movement speed in pixels per second
 * @param sourceId Entity that fired this projectile
 * @returns Component object suitable for spreading into spawn()
 */
export declare function createProjectile(damage: number, speed: number, sourceId: number): Pick<ProjectileComponentTypes, 'projectile'>;
/**
 * Create a homing projectile target component.
 *
 * @param entityId Target entity to track
 * @returns Component object suitable for spreading into spawn()
 */
export declare function createProjectileTarget(entityId: number): Pick<ProjectileComponentTypes, 'projectileTarget'>;
/**
 * Create a fixed-direction projectile component (auto-normalizes).
 *
 * @param x Direction x
 * @param y Direction y
 * @returns Component object suitable for spreading into spawn()
 */
export declare function createProjectileDirection(x: number, y: number): Pick<ProjectileComponentTypes, 'projectileDirection'>;
/**
 * Create a projectile plugin for ECSpresso.
 *
 * Provides homing and linear projectile movement systems, plus
 * automatic collision-to-damage integration.
 *
 * @example
 * ```typescript
 * // Spawn a homing projectile:
 * ecs.spawn({
 *   ...createProjectile(10, 400, turretId),
 *   ...createProjectileTarget(enemyId),
 *   ...createLocalTransform(x, y),
 *   ...createCircleCollider(4),
 *   ...collisionLayers.turretProjectile(),
 *   sprite: bulletSprite,
 *   renderLayer: 'projectiles',
 * });
 * ```
 */
export declare function createProjectilePlugin<G extends string = 'combat'>(options?: ProjectilePluginOptions<G>): import("ecspresso").Plugin<import("ecspresso").WithEvents<import("ecspresso").WithComponents<import("ecspresso").EmptyConfig, ProjectileComponentTypes>, ProjectileEventTypes>, TransformWorldConfig & EventsConfig<CollisionEventTypes<string>>, "projectile-homing" | "projectile-linear" | "projectile-collision", G, never, never>;