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

Crunch Physics

import { Entity } from './Entity';
import { Solid } from './Solid';
import { ActorCollisionResult, CollisionResult, EntityData, PhysicsEntityConfig, PhysicsEntityType, Vector2 } from './types';
/**
 * Dynamic physics entity that can move and collide with other entities.
 * Actors are typically used for players, enemies, projectiles, and other moving game objects.
 *
 * Features:
 * - Velocity-based movement with gravity
 * - Collision detection and response
 * - Solid surface detection (riding)
 * - Automatic culling when out of bounds
 * - Actor-to-actor collision detection
 *
 * @typeParam T - Application type, defaults to base Application
 *
 * @example
 * ```typescript
 * // Create a player actor
 * class Player extends Actor {
 *   constructor() {
 *     super({
 *       type: 'Player',
 *       position: [100, 100],
 *       size: [32, 64],
 *       view: playerSprite
 *     });
 *   }
 *
 *   // Handle collisions
 *   onCollide(result: CollisionResult) {
 *     if (result.solid.type === 'Spike') {
 *       this.die();
 *     }
 *   }
 *
 *   // Handle actor-to-actor collisions
 *   onActorCollide(result: ActorCollisionResult) {
 *     if (result.actor.type === 'Enemy') {
 *       this.takeDamage(10);
 *     }
 *   }
 *
 *   // Custom movement
 *   update(dt: number) {
 *     super.update(dt);
 *
 *     // Move left/right
 *     if (this.app.input.isKeyDown('ArrowLeft')) {
 *       this.velocity.x = -200;
 *     } else if (this.app.input.isKeyDown('ArrowRight')) {
 *       this.velocity.x = 200;
 *     }
 *
 *     // Jump when on ground
 *     if (this.app.input.isKeyPressed('Space') && this.isRidingSolid()) {
 *       this.velocity.y = -400;
 *     }
 *   }
 * }
 * ```
 */
export declare class Actor<D extends EntityData = EntityData> extends Entity<D> {
    readonly entityType: PhysicsEntityType;
    /** Current velocity in pixels per second */
    velocity: Vector2;
    /** Whether actor-to-actor collisions are disabled for this actor */
    disableActorCollisions: boolean;
    /** Whether the actor should be removed when culled (out of bounds) */
    shouldRemoveOnCull: boolean;
    /** List of current frame collisions */
    collisions: CollisionResult[];
    /** List of current frame actor-to-actor collisions */
    actorCollisions: ActorCollisionResult[];
    /** Cache for isRidingSolid check */
    private _isRidingSolidCache;
    /** Tracks which solid is currently carrying this actor in the current frame */
    private _carriedBy;
    private _carriedByOverlap;
    /** Tracks the grid cells this actor currently occupies */
    private _currentGridCells;
    /**
     * Initialize or reinitialize the actor with new configuration.
     *
     * @param config - Configuration for the actor
     */
    init(config: PhysicsEntityConfig<D>): void;
    /**
     * Called at the start of each update to prepare for collision checks.
     */
    preUpdate(): void;
    /**
     * Updates the actor's position based on velocity and handles collisions.
     *
     * @param dt - Delta time in seconds
     */
    update(dt: number): void;
    /**
     * Called after update to handle post-movement effects.
     */
    postUpdate(): void;
    /**
     * Resets the actor to its initial state.
     */
    reset(): void;
    /**
     * Called when the actor is culled (goes out of bounds).
     * Override this to handle culling differently.
     */
    onCull(): void;
    /**
     * Called when this actor collides with a solid.
     * Override this method to implement custom collision response.
     *
     * @param result - Information about the collision
     */
    onCollide(result: CollisionResult): void;
    /**
     * Called when this actor collides with another actor.
     * Override this method to implement custom actor-to-actor collision response.
     *
     * @param result - Information about the actor collision
     */
    onActorCollide(result: ActorCollisionResult): void;
    /**
     * Checks if this actor is riding the given solid.
     * An actor is riding if it's directly above the solid.
     *
     * @param solid - The solid to check against
     * @returns True if riding the solid
     */
    isRiding(solid: Solid): boolean;
    /**
     * Checks if this actor is riding any solid in the physics system.
     * Uses caching to optimize multiple checks per frame.
     *
     * @returns True if riding any solid
     */
    isRidingSolid(): boolean;
    /**
     * Called when the actor is squeezed between solids.
     * Override this to handle squishing differently.
     */
    squish(result: CollisionResult): void;
    /**
     * Updates the actor's grid cells in the spatial partitioning system.
     * This is called when the actor moves or when its size changes.
     */
    updateGridCells(): void;
    /**
     * Gets the current grid cells this actor occupies
     */
    get currentGridCells(): string[];
    /**
     * Sets the current grid cells this actor occupies
     */
    set currentGridCells(cells: string[]);
    /**
     * Moves the actor horizontally, checking for collisions with solids.
     *
     * @param amount - Distance to move in pixels
     * @param collisionHandler - Optional callback for handling collisions
     * @returns Array of collision results
     */
    moveX(amount: number, collisionHandler?: (result: CollisionResult) => void, pushingSolid?: Solid): CollisionResult[];
    /**
     * Moves the actor vertically, checking for collisions with solids.
     *
     * @param amount - Distance to move in pixels
     * @param collisionHandler - Optional callback for handling collisions
     * @returns Array of collision results
     */
    moveY(amount: number, collisionHandler?: (result: CollisionResult) => void, pushingSolid?: Solid): CollisionResult[];
    /**
     * Updates the actor's view position.
     */
    updateView(): void;
    /**
     * Gets all solids at the specified position that could collide with this actor.
     *
     * @param _x - X position to check
     * @param _y - Y position to check
     * @returns Array of solids at the position
     */
    protected getSolidsAt(_x: number, _y: number): Solid[];
    /**
     * Checks if this actor is colliding with another actor.
     * The collision will only occur if:
     * 1. Both actors are active
     * 2. Neither actor has disabled actor collisions
     * 3. The collision layers and masks match:
     *    - (this.collisionLayer & other.collisionMask) !== 0
     *    - (other.collisionLayer & this.collisionMask) !== 0
     *
     * @param actor - The actor to check collision with
     * @returns Collision result with information about the collision
     */
    checkActorCollision(actor: Actor): ActorCollisionResult;
    /**
     * Resolves a collision with another actor.
     *
     * @param result - The collision result to resolve
     * @param shouldMove - Whether this actor should move to resolve the collision
     * @returns The updated collision result
     */
    resolveActorCollision(result: ActorCollisionResult): ActorCollisionResult;
    /**
     * Sets the actor's size and updates grid cells if needed.
     *
     * @param width - New width in pixels
     * @param height - New height in pixels
     */
    setSize(width: number, height: number): void;
    /**
     * Sets the actor's width and updates grid cells if needed.
     *
     * @param value - New width in pixels
     */
    setWidth(value: number): void;
    /**
     * Sets the actor's height and updates grid cells if needed.
     *
     * @param value - New height in pixels
     */
    setHeight(value: number): void;
}
//# sourceMappingURL=Actor.d.ts.map