esengine/docs/en/modules/spatial/index.md

Spatial Index System

@esengine/spatial provides efficient spatial querying and indexing, including range queries, nearest neighbor queries, raycasting, and AOI (Area of Interest) management.

Installation

npm install @esengine/spatial

Quick Start

Spatial Index

import { createGridSpatialIndex } from '@esengine/spatial';

// Create spatial index (cell size 100)
const spatialIndex = createGridSpatialIndex<Entity>(100);

// Insert objects
spatialIndex.insert(player, { x: 100, y: 200 });
spatialIndex.insert(enemy1, { x: 150, y: 250 });
spatialIndex.insert(enemy2, { x: 500, y: 600 });

// Find objects within radius
const nearby = spatialIndex.findInRadius({ x: 100, y: 200 }, 100);
console.log(nearby); // [player, enemy1]

// Find nearest object
const nearest = spatialIndex.findNearest({ x: 100, y: 200 });
console.log(nearest); // enemy1

// Update position
spatialIndex.update(player, { x: 120, y: 220 });

AOI (Area of Interest)

import { createGridAOI } from '@esengine/spatial';

// Create AOI manager
const aoi = createGridAOI<Entity>(100);

// Add observers
aoi.addObserver(player, { x: 100, y: 100 }, { viewRange: 200 });
aoi.addObserver(npc, { x: 150, y: 150 }, { viewRange: 150 });

// Listen to enter/exit events
aoi.addListener((event) => {
    if (event.type === 'enter') {
        console.log(`${event.observer} saw ${event.target}`);
    } else if (event.type === 'exit') {
        console.log(`${event.target} left ${event.observer}'s view`);
    }
});

// Update position (triggers enter/exit events)
aoi.updatePosition(player, { x: 200, y: 200 });

// Get visible entities
const visible = aoi.getEntitiesInView(player);

Core Concepts

Spatial Index vs AOI

Feature	SpatialIndex	AOI
Purpose	General spatial queries	Entity visibility tracking
Events	No event notification	Enter/exit events
Direction	One-way query	Two-way tracking
Use Cases	Collision, range attacks	MMO sync, NPC AI perception

IBounds

interface IBounds {
    readonly minX: number;
    readonly minY: number;
    readonly maxX: number;
    readonly maxY: number;
}

IRaycastHit

interface IRaycastHit<T> {
    readonly target: T;       // Hit object
    readonly point: IVector2; // Hit point
    readonly normal: IVector2;// Hit normal
    readonly distance: number;// Distance from origin
}

Spatial Index API

createGridSpatialIndex

function createGridSpatialIndex<T>(cellSize?: number): GridSpatialIndex<T>

Choosing cellSize:

• Too small: High memory, reduced query efficiency
• Too large: Many objects per cell, slow iteration
• Recommended: 1-2x average object spacing

Management Methods

spatialIndex.insert(entity, position);
spatialIndex.remove(entity);
spatialIndex.update(entity, newPosition);
spatialIndex.clear();

Query Methods

findInRadius

const enemies = spatialIndex.findInRadius(
    { x: 100, y: 200 },
    50,
    (entity) => entity.type === 'enemy' // Optional filter
);

findInRect

import { createBounds } from '@esengine/spatial';

const bounds = createBounds(0, 0, 200, 200);
const entities = spatialIndex.findInRect(bounds);

findNearest

const nearest = spatialIndex.findNearest(
    playerPosition,
    500, // maxDistance
    (entity) => entity.type === 'enemy'
);

findKNearest

const nearestEnemies = spatialIndex.findKNearest(
    playerPosition,
    5,    // k
    500,  // maxDistance
    (entity) => entity.type === 'enemy'
);

raycast / raycastFirst

const hits = spatialIndex.raycast(origin, direction, maxDistance);
const firstHit = spatialIndex.raycastFirst(origin, direction, maxDistance);

AOI API

createGridAOI

function createGridAOI<T>(cellSize?: number): GridAOI<T>

Observer Management

// Add observer
aoi.addObserver(player, position, {
    viewRange: 200,
    observable: true  // Can be seen by others
});

// Remove observer
aoi.removeObserver(player);

// Update position
aoi.updatePosition(player, newPosition);

// Update view range
aoi.updateViewRange(player, 300);

Query Methods

// Get entities in observer's view
const visible = aoi.getEntitiesInView(player);

// Get observers who can see entity
const observers = aoi.getObserversOf(monster);

// Check visibility
if (aoi.canSee(player, enemy)) { ... }

Event System

// Global event listener
aoi.addListener((event) => {
    switch (event.type) {
        case 'enter': /* entered view */ break;
        case 'exit': /* left view */ break;
    }
});

// Entity-specific listener
aoi.addEntityListener(player, (event) => {
    if (event.type === 'enter') {
        sendToClient(player, 'entity_enter', event.target);
    }
});

Utility Functions

Bounds Creation

import {
    createBounds,
    createBoundsFromCenter,
    createBoundsFromCircle
} from '@esengine/spatial';

const bounds1 = createBounds(0, 0, 100, 100);
const bounds2 = createBoundsFromCenter({ x: 50, y: 50 }, 100, 100);
const bounds3 = createBoundsFromCircle({ x: 50, y: 50 }, 50);

Geometry Checks

import {
    isPointInBounds,
    boundsIntersect,
    boundsIntersectsCircle,
    distance,
    distanceSquared
} from '@esengine/spatial';

if (isPointInBounds(point, bounds)) { ... }
if (boundsIntersect(boundsA, boundsB)) { ... }
if (boundsIntersectsCircle(bounds, center, radius)) { ... }
const dist = distance(pointA, pointB);
const distSq = distanceSquared(pointA, pointB); // Faster

Practical Examples

Range Attack Detection

class CombatSystem {
    private spatialIndex: ISpatialIndex<Entity>;

    dealAreaDamage(center: IVector2, radius: number, damage: number): void {
        const targets = this.spatialIndex.findInRadius(
            center, radius,
            (entity) => entity.hasComponent(HealthComponent)
        );

        for (const target of targets) {
            target.getComponent(HealthComponent).takeDamage(damage);
        }
    }
}

MMO Sync System

class SyncSystem {
    private aoi: IAOIManager<Player>;

    constructor() {
        this.aoi = createGridAOI<Player>(100);

        this.aoi.addListener((event) => {
            const packet = this.createSyncPacket(event);
            this.sendToPlayer(event.observer, packet);
        });
    }

    onPlayerMove(player: Player, newPosition: IVector2): void {
        this.aoi.updatePosition(player, newPosition);
    }
}

Blueprint Nodes

Spatial Query Nodes

• FindInRadius, FindInRect, FindNearest, FindKNearest
• Raycast, RaycastFirst

AOI Nodes

• GetEntitiesInView, GetObserversOf, CanSee
• OnEntityEnterView, OnEntityExitView

Service Tokens

import { SpatialIndexToken, AOIManagerToken } from '@esengine/spatial';

services.register(SpatialIndexToken, createGridSpatialIndex(100));
services.register(AOIManagerToken, createGridAOI(100));