@dill-pixel/plugin-crunch-physics/lib/Entity.d.ts

Crunch Physics

import { AppTypeOverrides, defaultFactoryMethods, PointLike, SignalConnection, SignalConnections } from 'dill-pixel';
import { default as CrunchPhysicsPlugin } from './CrunchPhysicsPlugin';
import { Group } from './Group';
import { System } from './System';
import { EntityData, PhysicsEntityConfig, PhysicsEntityType, PhysicsEntityView, Rectangle } from './types';
/**
 * Base class for all physics entities in the Crunch physics system.
 * Provides common functionality for position, size, view management, and lifecycle.
 *
 * Entity is the foundation for:
 * - Actors (dynamic objects)
 * - Solids (static objects)
 * - Sensors (trigger zones)
 *
 * It handles:
 * - Position and size management
 * - View (sprite) management and updates
 * - Group membership and relative positioning
 * - Culling and lifecycle states
 * - Signal connections for event handling
 *
 * @typeParam A - Application type, defaults to base Application
 * @typeParam D - Entity data type, defaults to base EntityData
 *
 * @example
 * ```typescript
 * // Create a custom entity
 * class CustomEntity extends Entity {
 *   constructor() {
 *     super({
 *       type: 'Custom',
 *       position: [100, 100],
 *       size: [32, 32],
 *       view: sprite
 *     });
 *   }
 *
 *   // Override update for custom behavior
 *   update(dt: number) {
 *     super.update(dt);
 *     // Custom update logic
 *   }
 * }
 * ```
 */
export declare class Entity<D extends EntityData = EntityData> {
    readonly entityType: PhysicsEntityType;
    protected _id: string;
    /** Unique type identifier for this entity */
    type: string;
    /** Color to use when rendering debug visuals */
    debugColor: number;
    /** Whether the entity should be removed when culled (out of bounds) */
    shouldRemoveOnCull: boolean;
    /** Entity width in pixels */
    width: number;
    /** Entity height in pixels */
    height: number;
    /** Visual representation (sprite/graphics) of this entity */
    view: PhysicsEntityView;
    /** Whether this entity is active and should be updated */
    /** Collision layer this entity belongs to (bitwise) */
    collisionLayer: number;
    /** Collision mask defining which layers this entity collides with (bitwise) */
    collisionMask: number;
    protected _data: Partial<D>;
    protected _group: Group | null;
    protected _groupOffset: {
        x: number;
        y: number;
    };
    protected _isCulled: boolean;
    protected _isDestroyed: boolean;
    protected _isInitialized: boolean;
    protected _xRemainder: number;
    protected _yRemainder: number;
    protected _x: number;
    protected _y: number;
    protected signalConnections: SignalConnections;
    protected _following: Entity | null;
    protected _followOffset: {
        x: number;
        y: number;
    };
    protected _config: PhysicsEntityConfig<D> | undefined;
    protected _active: boolean;
    updatedFollowPosition: boolean;
    updatedGroupPosition: boolean;
    set active(value: boolean);
    get active(): boolean;
    set id(value: string);
    get id(): string;
    get make(): typeof defaultFactoryMethods;
    /**
     * Custom data associated with this entity
     */
    set data(value: Partial<D>);
    get data(): Partial<D>;
    setFollowing(entityToFollow: Entity | null, offset?: PointLike): void;
    get followOffset(): {
        x: number;
        y: number;
    };
    get following(): Entity | null;
    get followers(): Entity[];
    /**
     * The group this entity belongs to, if any.
     * Groups allow for collective movement and management of entities.
     */
    get group(): Group | null;
    set groupOffset(value: {
        x: number;
        y: number;
    });
    get groupOffset(): {
        x: number;
        y: number;
    };
    setGroup(group: Group | null, offset?: PointLike): void;
    set position(value: PointLike);
    get position(): PointLike;
    /**
     * Entity's X position in world space.
     * If the entity belongs to a group, returns position relative to group.
     */
    set x(value: number);
    get x(): number;
    /**
     * Entity's Y position in world space.
     * If the entity belongs to a group, returns position relative to group.
     */
    set y(value: number);
    get y(): number;
    /** Whether this entity is currently culled (out of bounds) */
    get isCulled(): boolean;
    /** Whether this entity has been destroyed */
    get isDestroyed(): boolean;
    /** Reference to the main application instance */
    get app(): AppTypeOverrides['App'];
    /** Reference to the physics plugin */
    get physics(): CrunchPhysicsPlugin;
    /**
     * Creates a new Entity instance.
     *
     * @param config - Optional configuration for the entity
     */
    constructor(config?: PhysicsEntityConfig<D>);
    /**
     * Called after construction to perform additional initialization.
     * Override this in subclasses to add custom initialization logic.
     */
    protected initialize(): void;
    /**
     * Called before update to prepare for the next frame.
     * Override this in subclasses to add pre-update logic.
     */
    preUpdate(): void;
    /**
     * Called every frame to update the entity's state.
     * Override this in subclasses to add update logic.
     *
     * @param dt - Delta time in seconds since last update
     */
    update(dt: number): void;
    /**
     * Called after update to finalize the frame.
     * Override this in subclasses to add post-update logic.
     */
    postUpdate(): void;
    /**
     * Excludes collision types for this entity
     * @deprecated Use setCollisionMask instead
     */
    excludeCollisionType(): void;
    /**
     * Includes collision types for this entity
     * @deprecated Use setCollisionMask instead
     */
    includeCollisionType(): void;
    /**
     * Removes collision types for this entity
     * @deprecated Use removeCollisionMask instead
     */
    removeCollisionType(): void;
    /**
     * Adds collision types for this entity
     * @deprecated Use addCollisionMask instead
     */
    addCollisionType(): void;
    /**
     * Checks if this entity can collide with a specific type
     */
    canCollideWith(): boolean;
    /**
     * Adds the entity's view to the physics container and updates its position.
     */
    protected addView(): void;
    /**
     * Initializes or reinitializes the entity with new configuration.
     * Used by object pools when recycling entities.
     *
     * @param config - New configuration to apply
     */
    init(config: PhysicsEntityConfig<D>): void;
    /**
     * Resets the entity to its initial state for reuse in object pools.
     * Override this to handle custom reset logic.
     */
    reset(): void;
    /** Reference to the physics system */
    get system(): System;
    /**
     * Called when the entity is added to a group.
     * Override this to handle custom group addition logic.
     */
    onAddedToGroup(): void;
    /**
     * Called when the entity is removed from a group.
     * Override this to handle custom group removal logic.
     */
    onRemovedFromGroup(): void;
    /**
     * Updates the entity's position and view.
     */
    updatePosition(): void;
    /**
     * Called when the entity is culled (goes out of bounds).
     * Override this to handle culling differently.
     */
    onCull(): void;
    /**
     * Called when the entity is brought back after being culled.
     * Override this to handle unculling differently.
     */
    onUncull(): void;
    /**
     * Prepares the entity for removal/recycling.
     * Override this to handle custom cleanup.
     */
    destroy(): void;
    /**
     * Called when the entity is removed from the physics system.
     * Override this to handle custom removal logic.
     */
    onRemoved(): void;
    /**
     * Sets a new view for the entity and updates its position.
     *
     * @param view - The new view to use
     */
    setView(view: PhysicsEntityView): void;
    /**
     * Updates the view's position to match the entity's position.
     */
    updateView(): void;
    /**
     * Gets the entity's bounding rectangle.
     *
     * @returns Rectangle representing the entity's bounds
     */
    getBounds(): Rectangle;
    /**
     * Sets the entity's position, resetting any movement remainders.
     *
     * @param x - New X position
     * @param y - New Y position
     */
    setPosition(x: number, y: number): void;
    /**
     * Alias for setPosition.
     *
     * @param x - New X position
     * @param y - New Y position
     */
    moveTo(x: number, y: number): void;
    /**
     * Adds signal connections to the entity.
     *
     * @param args - Signal connections to add
     */
    addSignalConnection(...args: SignalConnection[]): void;
    /**
     * Alias for addSignalConnection.
     *
     * @param args - Signal connections to add
     */
    connectSignal(...args: SignalConnection[]): void;
    /**
     * Alias for addSignalConnection, specifically for action signals.
     *
     * @param args - Action signal connections to add
     */
    connectAction(...args: SignalConnection[]): void;
    /**
     * Checks if this entity can collide with another entity
     */
    canCollideWithEntity(entity: Entity): boolean;
    /**
     * Sets the collision layer for this entity
     *
     * @param layer The collision layer or layers (can be combined with bitwise OR)
     */
    setCollisionLayer(layer: number): void;
    /**
     * Adds the specified layers to this entity's collision layer
     *
     * @param layers The layers to add (can be combined with bitwise OR)
     */
    addCollisionLayer(layers: number): void;
    /**
     * Removes the specified layers from this entity's collision layer
     *
     * @param layers The layers to remove (can be combined with bitwise OR)
     */
    removeCollisionLayer(layers: number): void;
    /**
     * Sets the collision mask for this entity
     *
     * @param mask The collision mask (can be combined with bitwise OR)
     */
    setCollisionMask(...mask: number[]): void;
    /**
     * Adds the specified layers to this entity's collision mask
     *
     * @param layers The layers to add to the mask (can be combined with bitwise OR)
     */
    addCollisionMask(layers: number): void;
    /**
     * Removes the specified layers from this entity's collision mask
     *
     * @param layers The layers to remove from the mask (can be combined with bitwise OR)
     */
    removeCollisionMask(layers: number): void;
    /**
     * Checks if this entity belongs to a specific collision layer
     *
     * @param layer The layer to check
     * @returns True if the entity belongs to the specified layer
     *
     * @example
     * ```typescript
     * // Check if entity is on the PLAYER layer
     * if (entity.hasCollisionLayer(CollisionLayer.PLAYER)) {
     *   console.log('Entity is a player');
     * }
     *
     * // Check if entity is on a custom layer
     * const WATER_LAYER = CollisionLayers.createLayer(0);
     * if (entity.hasCollisionLayer(WATER_LAYER)) {
     *   console.log('Entity is water');
     * }
     * ```
     */
    hasCollisionLayer(layer: number): boolean;
    /**
     * Checks if this entity can collide with a specific collision layer
     *
     * @param layer The layer to check
     * @returns True if the entity can collide with the specified layer
     *
     * @example
     * ```typescript
     * // Check if entity can collide with players
     * if (entity.canCollideWithLayer(CollisionLayer.PLAYER)) {
     *   console.log('Entity can collide with players');
     * }
     *
     * // Check if entity can collide with a custom layer
     * const WATER_LAYER = CollisionLayers.createLayer(0);
     * if (entity.canCollideWithLayer(WATER_LAYER)) {
     *   console.log('Entity can collide with water');
     * }
     * ```
     */
    canCollideWithLayer(layer: number): boolean;
}
//# sourceMappingURL=Entity.d.ts.map