@rpgjs/physic/dist/collision/spatial-hash.d.ts

A deterministic 2D top-down physics library for RPG, sandbox and MMO games

import { Entity } from '../physics/Entity';
import { AABB } from '../core/math/AABB';
import { Ray, RaycastHit } from './Ray';
/**
 * Spatial hash grid for efficient collision detection
 *
 * Divides the world into a grid of cells and stores entities in cells
 * based on their position. This reduces collision checks from O(n²) to O(n).
 *
 * @example
 * ```typescript
 * const spatialHash = new SpatialHash(100, 10); // 100x100 cell size, 10x10 grid
 * spatialHash.insert(entity);
 * const nearby = spatialHash.query(entity);
 * ```
 */
export declare class SpatialHash {
    private cellSize;
    private gridWidth;
    private gridHeight;
    private cells;
    private entityCells;
    /**
     * Creates a new spatial hash
     *
     * @param cellSize - Size of each cell in world units
     * @param gridWidth - Number of cells horizontally
     * @param gridHeight - Number of cells vertically (default: same as width)
     */
    constructor(cellSize: number, gridWidth: number, gridHeight?: number);
    /**
     * Converts world coordinates to grid coordinates
     *
     * @param x - World X coordinate
     * @param y - World Y coordinate
     * @returns Grid coordinates
     */
    private worldToGrid;
    /**
     * Creates a cell key from grid coordinates
     *
     * @param gridX - Grid X coordinate
     * @param gridY - Grid Y coordinate
     * @returns Numeric cell key
     */
    private getKey;
    /**
     * Gets or creates a cell at grid coordinates
     *
     * @param key - Cell key
     * @returns Cell instance
     */
    private getCell;
    /**
     * Gets all cell keys that an entity's AABB overlaps
     *
     * @param entity - Entity to get cells for
     * @param outKeys - Array to store keys in (to avoid allocation)
     * @returns Number of keys added
     */
    private getEntityKeys;
    /**
     * Inserts an entity into the spatial hash
     *
     * @param entity - Entity to insert
     */
    insert(entity: Entity): void;
    /**
     * Removes an entity from the spatial hash
     *
     * @param entity - Entity to remove
     */
    remove(entity: Entity): void;
    /**
     * Updates an entity's position in the spatial hash
     *
     * Removes and re-inserts the entity if it moved to different cells.
     *
     * @param entity - Entity to update
     */
    update(entity: Entity): void;
    /**
     * Queries entities near a given entity
     *
     * @param entity - Entity to query around
     * @param results - Optional Set to store results in (avoids allocation)
     * @returns Set of nearby entities (excluding the query entity)
     */
    query(entity: Entity, results?: Set<Entity>): Set<Entity>;
    /**
     * Queries entities in an AABB region
     *
     * @param bounds - AABB to query
     * @returns Set of entities in the region
     */
    queryAABB(bounds: AABB): Set<Entity>;
    /**
     * Clears all entities from the spatial hash
     */
    clear(): void;
    /**
     * Gets statistics about the spatial hash
     *
     * @returns Statistics object
     */
    getStats(): {
        totalCells: number;
        usedCells: number;
        totalEntities: number;
        averageEntitiesPerCell: number;
    };
    /**
     * Casts a ray against entities in the spatial hash
     *
     * @param ray - Ray to cast
     * @param mask - Optional collision mask (layer)
     * @param filter - Optional filter function (return true to include entity)
     * @returns Raycast hit info if hit, null otherwise
     */
    raycast(ray: Ray, mask?: number, filter?: (entity: Entity) => boolean): RaycastHit | null;
}
//# sourceMappingURL=spatial-hash.d.ts.map