vibe3_physics/source/boids_mgr/spatial_grid.hpp

#pragma once

#include <unordered_map>
#include <vector>

class Ball;  // Forward declaration

// ============================================================================
// SPATIAL HASH GRID - Sistema genérico de particionamiento espacial
// ============================================================================
//
// Divide el espacio 2D en celdas de tamaño fijo para acelerar búsquedas de vecinos.
// Reduce complejidad de O(n²) a O(n) para queries de proximidad.
//
// CASOS DE USO:
// - Boids: Buscar vecinos para reglas de Reynolds (separación/alineación/cohesión)
// - Física: Detección de colisiones ball-to-ball (futuro)
// - IA: Pathfinding con obstáculos dinámicos
//
// ALGORITMO:
// 1. Dividir pantalla en grid de celdas (ej: 100x100px cada una)
// 2. Insertar cada Ball en celda(s) correspondiente(s) según posición
// 3. Query: Solo revisar celdas adyacentes (9 celdas max) en lugar de TODOS los objetos
//
// MEJORA DE RENDIMIENTO:
// - Sin grid: 1000 boids = 1M comparaciones (1000²)
// - Con grid:  1000 boids ≈ 9K comparaciones (1000 * ~9 vecinos/celda promedio)
// - Speedup:  ~100x en casos típicos
//
// ============================================================================

class SpatialGrid {
public:
    // Constructor: especificar dimensiones del mundo y tamaño de celda
    SpatialGrid(int world_width, int world_height, float cell_size);

    // Limpiar todas las celdas (llamar al inicio de cada frame)
    void clear();

    // Insertar objeto en el grid según su posición (x, y)
    void insert(Ball* ball, float x, float y);

    // Buscar todos los objetos dentro del radio especificado desde (x, y)
    // Devuelve vector de punteros a Ball (puede contener duplicados si ball está en múltiples celdas)
    std::vector<Ball*> queryRadius(float x, float y, float radius);

    // Actualizar dimensiones del mundo (útil para cambios de resolución F4)
    void updateWorldSize(int world_width, int world_height);

private:
    // Convertir coordenadas (x, y) a índice de celda (cell_x, cell_y)
    void getCellCoords(float x, float y, int& cell_x, int& cell_y) const;

    // Convertir (cell_x, cell_y) a hash key único para el mapa
    int getCellKey(int cell_x, int cell_y) const;

    // Dimensiones del mundo (ancho/alto en píxeles)
    int world_width_;
    int world_height_;

    // Tamaño de cada celda (en píxeles)
    float cell_size_;

    // Número de celdas en cada dimensión
    int grid_cols_;
    int grid_rows_;

    // Estructura de datos: hash map de cell_key → vector de Ball*
    // Usamos unordered_map para O(1) lookup
    std::unordered_map<int, std::vector<Ball*>> cells_;
};