//! `SpatialQuery` — handler-side access to the engine's spatial
//! index, distance metrics, and area lookups.
//!
//! Replaces the default-empty-impl `entities_at` method on the old
//! `GameContext`. That method lied about its shape — the SDK
//! couldn't model the engine impl, so plugins got `Vec::new()`
//! unless the engine override fired. With `SpatialQuery`, the
//! provider is opt-in: tests / SDK-only contexts simply don't
//! install one, and handlers that need spatial queries detect the
//! absence via `Option<Arc<dyn SpatialQuery>>`.

use crate::predicate::MetricKind;
use crate::trait_data::AreaShape;
use crate::types::{EntityId, Position};

pub trait SpatialQuery {
    /// Entities currently occupying `pos`. Empty vec if none.
    fn entities_at(&self, pos: &Position) -> Vec<EntityId>;

    /// Distance from `from` to `to` under `kind`. Returns `None`
    /// when either endpoint is dead, off-board, or unreachable
    /// under the named metric (e.g., `VisionLimited` distance is
    /// `None` if the line of sight is blocked).
    fn distance(&self, from: EntityId, to: EntityId, kind: MetricKind) -> Option<u32>;

    /// Entities within `shape` centered on `center`. Used by area-
    /// of-effect spell handlers, broadcast-style cascades, etc.
    fn entities_in_area(&self, center: &Position, shape: &AreaShape) -> Vec<EntityId>;
}
