open-index/open-npm huggingface dataset:
npm package: @spatial-engine/core
Description: High-performance spatial partitioning and query library using Data-Oriented Design
Author: Francisco Rueda Esquivel
Latest version: 0.0.4

# @spatial-engine/core

The foundation layer for `spatial-engine`, a high-performance spatial partitioning and query library using a Data-Oriented Design (DOD) approach. It provides cache-friendly, zero-GC spatial data structures backed by flat `Float32Array` pools.

Everything lives in contiguous memory: no per-object heap allocations, no mid-frame GC pauses.

## Installation

```bash
npm install @spatial-engine/core
# or
pnpm add @spatial-engine/core
```

## Features
- **Octree with automatic subdivision** — insert, update, and remove axis-aligned bounding boxes.
- **Branchless slab-method raycast** — fast `rayIntersectsAABB` implementation.
- **Box query** — `octree.queryBox()` returns all objects whose AABB overlaps a query region natively (iterative DFS, no recursion).
- **Zero GC Pools** — `AABBPool`, `RayPool`, and `OctreeNodePool` allocate once and reuse. Call `.reset()` each frame.
- **LiDAR Web Worker** — run a full multi-ray sweep entirely off the main thread using shared memory.
- **`SharedArrayBuffer` support** — pools can be shared with Web Workers without copying data.

## Basic Usage

```ts
import { AABBPool, RayPool, OctreeNodePool, Octree } from '@spatial-engine/core';

// --- 1. Allocate pools once (e.g. on startup) ---
const nodePool  = new OctreeNodePool(512);
const aabbPool  = new AABBPool(512);
const rayPool   = new RayPool(64);
const octree    = new Octree(nodePool, aabbPool);

octree.setBounds(-100, -100, -100, 100, 100, 100);

// --- 2. Each frame: reset pools and re-insert objects ---
nodePool.reset();
aabbPool.reset();

const idx = aabbPool.allocate();
aabbPool.set(idx, -1, -1, -1, 1, 1, 1); // minX,minY,minZ,maxX,maxY,maxZ
octree.insert(idx);

// --- 3. Raycast ---
const rayIdx = rayPool.allocate();
rayPool.set(rayIdx, 0, 0, -10, 0, 0, 1); // origin (0,0,-10), direction +Z

const rayBuf = (rayPool as any).buffer as Float32Array;
const hit = octree.raycast(rayBuf, rayIdx * 6);
// hit: { objectIndex: 0, t: 9 } | null

// --- 4. Box query ---
const hits = octree.queryBox(-2, -2, -2, 2, 2, 2);
// hits: [0]  (array of aabbPool indices)
```

## LiDAR Web Worker
For scenes with many rays (e.g. simulated sensors), you can use the built-in worker implementation to run sweeps off the main thread using `SharedArrayBuffer` exports natively provided.

```ts
import { AABBPool, RayPool, OctreeNodePool } from '@spatial-engine/core';
import type { LidarInitMessage, LidarSweepMessage } from '@spatial-engine/core';
// Import the robust built in web worker
const worker = new Worker(new URL('@spatial-engine/core/lidar-worker', import.meta.url), { type: 'module' });
```
(See root monorepo README for full worker example code).

## Use Cases
- **Game collision broad-phase**: `queryBox` for candidate pairs
- **Frustum culling**: `raycast` or `queryBox` to cull objects 
- **LiDAR sensor simulation**: `createLidarProcessor` off thread
- **Physics broad-phase**: Find overlap candidates before narrow-phase
npm package: @spatial-engine/react
Description: React Three Fiber adapter for @spatial-engine/core
Author: Francisco Rueda Esquivel
Latest version: 0.0.4

# @spatial-engine/react

React hooks specifically designed for [React Three Fiber](https://docs.pmnd.rs/react-three-fiber) scenes that interface with [`@spatial-engine/core`](https://www.npmjs.com/package/@spatial-engine/core) and [`@spatial-engine/three`](https://www.npmjs.com/package/@spatial-engine/three).

The hooks safely setup and manage pool lifecycles across React renders natively ensuring the core Data-Oriented arrays remain stable and don't leak memory.

## Installation

```bash
npm install @spatial-engine/react @spatial-engine/core @spatial-engine/three @react-three/fiber three react
# or
pnpm add @spatial-engine/react @spatial-engine/core @spatial-engine/three @react-three/fiber three react
```

## Features
- Provides React-safe lifecycles for complex DOD memory pools.
- Automatically initializes and clears arrays safely mapped exactly within the `useFrame` game loop.
- Simple, un-intimidating hooks (`useSpatialEngine`, `useOctree`) making extreme performance approachable in R3F.

## Usage

### Using `useSpatialEngine`
Manages a paired `AABBPool` and `RayPool` across renders.

```tsx
import { useSpatialEngine } from '@spatial-engine/react';
import { useFrame } from '@react-three/fiber';

function Scene() {
  const engine = useSpatialEngine({ aabbCapacity: 1024, rayCapacity: 64 });

  useFrame(() => {
    engine.reset(); // free all allocations safely each frame (zero GC impact)
    
    // dynamically re-populate your aabbPool and rayPool for this tick...
  });
}
```

### Using `useOctree`
Manages an entire `Octree`, alongside an `OctreeNodePool`, and `AABBPool` tied safely within a lifecycle context.

```tsx
import { useOctree } from '@spatial-engine/react';
import { useFrame, useThree } from '@react-three/fiber';

function Scene() {
  const { octree, aabbPool, reset } = useOctree({ 
    nodeCapacity: 1024, 
    objectCapacity: 1024 
  });

  useFrame(() => {
    reset(); // reset DOD pools each frame
    
    // insert/update objects into the octree here natively mapping external models ...
    
    // Native query without memory allocations
    const hits = octree.queryBox(-5, -5, -5, 5, 5, 5);
  });
}
```

## Use Cases
- Building interactive pointer/ray mechanics across thousands of objects smoothly.
- Connecting external R3F `useFrame` mechanics perfectly safely over the Spatial Engine lifecycle context.
- Frustum culling heavy geometries smoothly out of view in React Three scenarios.
npm package: @spatial-engine/three
Description: Three.js adapter for @spatial-engine/core
Author: Francisco Rueda Esquivel
Latest version: 0.0.4

# @spatial-engine/three

Bridges [`@spatial-engine/core`](https://www.npmjs.com/package/@spatial-engine/core) with [Three.js](https://threejs.org/). 

Provides `ThreeSynchronizer`, which automatically computes a `THREE.Mesh` or `THREE.Group`'s world-space bounding box and keeps the corresponding AABB exactly synchronized in the core DOD spatial octree without GC memory leaks.

## Installation

```bash
npm install @spatial-engine/three @spatial-engine/core three
# or
pnpm add @spatial-engine/three @spatial-engine/core three
```

## Features
- **Zero GC Sync** — computes world-space bounding boxes directly into the pre-allocated Data-Oriented Design (DOD) cache-friendly arrays.
- **Compatible with all Three.js Objects** — Works effortlessly with single `Mesh` components or deep `Group` tree hierarchies.

## Usage

```ts
import { AABBPool, OctreeNodePool, Octree } from '@spatial-engine/core';
import { ThreeSynchronizer } from '@spatial-engine/three';
import { Mesh, BoxGeometry, MeshBasicMaterial } from 'three';

// 1. Setup Data-Oriented core pools
const nodePool = new OctreeNodePool(512);
const aabbPool = new AABBPool(512);
const octree   = new Octree(nodePool, aabbPool);
octree.setBounds(-100, -100, -100, 100, 100, 100);

// 2. Setup Three.js Meshes
const mesh = new Mesh(new BoxGeometry(2, 2, 2), new MeshBasicMaterial());

// 3. Connect them via synchronizer
const sync = new ThreeSynchronizer(mesh, octree, aabbPool);

function animate() {
  // Update your Three.js objects
  mesh.position.x += 0.1;
  mesh.updateMatrixWorld();
  
  // Call sync() each frame after updating position/scale
  // This computes world AABB and repositions it instantly in the octree
  sync.sync(); 
}
```

## Use Cases
- High performance custom raycasting bypassing Three.js's standard `Raycaster` allocations.
- Culling thousands of Three.js objects outside a specific region or box.
- Simulating robotic sensors or environment scans over complex Three.js loaded geometries safely synchronized onto the `Octree`.