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

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

/**
 * Health Plugin for ECSpresso
 *
 * Provides a standard health/damage/death lifecycle.
 * Entities with a `health` component can receive `damage` events.
 * When health reaches zero, an `entityDied` event is published.
 * The plugin does NOT remove dead entities — game-specific logic
 * decides when and how to handle death (animations, loot, etc).
 */
import { type BasePluginOptions } from 'ecspresso';
import type { ComponentsConfig, EventsConfig } from 'ecspresso';
/**
 * Health state for an entity.
 */
export interface Health {
    current: number;
    max: number;
}
/**
 * Component types provided by the health plugin.
 */
export interface HealthComponentTypes {
    health: Health;
}
/**
 * Event requesting damage to an entity.
 */
export interface DamageEvent {
    entityId: number;
    amount: number;
    sourceId?: number;
}
/**
 * Event fired when an entity's health reaches zero.
 */
export interface EntityDiedEvent {
    entityId: number;
    killerId?: number;
}
/**
 * Event types provided by the health plugin.
 */
export interface HealthEventTypes {
    damage: DamageEvent;
    entityDied: EntityDiedEvent;
}
/**
 * WorldConfig representing the health plugin's provided types.
 * Used as the `Requires` type parameter by plugins that depend on health.
 */
export type HealthWorldConfig = ComponentsConfig<HealthComponentTypes> & EventsConfig<HealthEventTypes>;
export interface HealthPluginOptions<G extends string = 'combat'> extends BasePluginOptions<G> {
}
/**
 * Create a health component at full HP.
 *
 * @param max Maximum (and initial) health
 * @returns Component object suitable for spreading into spawn()
 *
 * @example
 * ```typescript
 * ecs.spawn({
 *   ...createHealth(100),
 *   ...createLocalTransform(200, 300),
 * });
 * ```
 */
export declare function createHealth(max: number): Pick<HealthComponentTypes, 'health'>;
/**
 * Create a health component with a specific current value.
 *
 * @param current Current health
 * @param max Maximum health
 * @returns Component object suitable for spreading into spawn()
 */
export declare function createHealthWith(current: number, max: number): Pick<HealthComponentTypes, 'health'>;
/**
 * Create a health plugin for ECSpresso.
 *
 * Provides event-driven damage processing. Subscribe to `damage` events
 * to deal damage, and listen to `entityDied` events to react to deaths.
 *
 * @example
 * ```typescript
 * const ecs = ECSpresso.create()
 *   .withPlugin(createHealthPlugin())
 *   .build();
 *
 * // Deal damage:
 * ecs.eventBus.publish('damage', { entityId: targetId, amount: 25 });
 *
 * // React to death:
 * ecs.on('entityDied', ({ entityId }) => {
 *   ecs.commands.removeEntity(entityId);
 * });
 * ```
 */
export declare function createHealthPlugin<G extends string = 'combat'>(options?: HealthPluginOptions<G>): import("ecspresso").Plugin<import("ecspresso").WithEvents<import("ecspresso").WithComponents<import("ecspresso").EmptyConfig, HealthComponentTypes>, HealthEventTypes>, import("ecspresso").EmptyConfig, "health-damage", G, never, never>;