GizStack
View .mdOpen in ChatGPTOpen in Claude

gizgame/spatial

gizlang
import * as Spatial from "gizgame/spatial";

Types

Bounds

gizlang
type Bounds = { entity: Entity; low: Vec<f64>; high: Vec<f64>; }

A broad-phase AABB derived from a live entity's authoritative components.

  • entity: M186.Entity
  • low: Vec<f64>
  • high: Vec<f64>

Index

gizlang
class Index { private size: f64; private cells = new Map<string, Vec<i64>>(); private bounds: Vec<Bounds> = []; private world: World | undefined = undefined; private revision: i64 = -1; private epoch: i64 = -1; constructor(size: f64) { assert(Math.isFinite(size) && size> 0.0); this.size = size; } private keys(low: Vec<f64>, high: Vec<f64>): Vec<string> throws string { if (low.length <2 || low.length> 3 || high.length !== low.length) { throw "Spatial bounds need two or three dimensions"; } for (const at of range(0, low.length)) { if (!Math.isFinite(low[at]) || !Math.isFinite(high[at]) || low[at]> high[at] || Math.abs(low[at]/this.size)> 2147483647.0 || Math.abs(high[at]/this.size)> 2147483647.0) { throw "Invalid spatial bound"; } } const x0 = i64(Math.floor(low[0]/this.size)); const x1 = i64(Math.floor(high[0]/this.size)); const y0 = i64(Math.floor(low[1]/this.size)); const y1 = i64(Math.floor(high[1]/this.size)); const z0 = low.length === 3 ? i64(Math.floor(low[2]/this.size)): 0; const z1 = low.length === 3 ? i64(Math.floor(high[2]/this.size)): 0; const nx = x1-x0+1; const ny = y1-y0+1; const nz = z1-z0+1; if (nx> 65536 || ny> 65536/nx || nz> 65536/(nx*ny)) { throw "Spatial bound spans too many cells"; } let out: Vec<string> = []; for (const z of range(z0, z1+1)) { for (const y of range(y0, y1+1)) { for (const x of range(x0, x1+1)) { out.push(`${x }, ${ y }, ${ z }`); } } } return out; } rebuild(world: World, bounds: Vec<Bounds>): void throws string { let cells = new Map<string, Vec<i64>>(); for (const at of range(0, bounds.length)) { const bound = bounds[at]; if (!world.alive(bound.entity)) { throw "Spatial bound belongs to a stale entity"; } for (const key of this.keys(bound.low, bound.high)) { let list = cells.get(key) ?? []; list.push(at); cells.set(key, list); } } this.cells = cells; this.bounds = bounds; this.world = world; this.revision = world.revision(); this.epoch = world.epoch(); } query(world: World, low: Vec<f64>, high: Vec<f64>): Vec<Entity> throws string { if (this.world === undefined || this.world! !== world || this.revision !== world.revision() || this.epoch !== world.epoch()) { throw "Spatial index is stale or belongs to another World"; } let seen = new Set<i64>(); let out: Vec<Entity> = []; for (const key of this.keys(low, high)) { for (const at of this.cells.get(key) ?? []) { if (seen.has(at)) { continue; } seen.add(at); const bound = this.bounds[at]; if (bound.low.length !== low.length) { continue; } let hit = true; for (const axis of range(0, low.length)) { if (bound.high[axis] <low[axis] || bound.low[axis]> high[axis]) { hit = false; break; } } if (hit) { out.push(bound.entity); } } } return out.toSorted((a, b) => a.index <b.index); } }

A world-space uniform grid. It retains only derived bounds and identity, never simulation state.

  • size: f64
  • cells: _gizlang_sdk_collections.Map<string, Vec<i64>>
  • bounds: Vec<M185.Bounds>
  • world: _gizlang_sdk_core.Option<Ref<M186.World>>
  • revision: i64
  • epoch: i64

Functions

constructor

gizlang
constructor(size: f64)

Positive cell width shared by the two or three spatial axes.

Effects: fail, read, write, alloc.

Methods

Index.rebuild

gizlang
rebuild(world: World, bounds: Vec<Bounds>): void throws string

Replaces the derived index atomically from the current world.

Effects: fail, read, write, alloc.

Index.query

gizlang
query(world: World, low: Vec<f64>, high: Vec<f64>): Vec<Entity> throws string

Exact overlap candidates in entity order. Changes or replacement of the source World require a rebuild.

Effects: fail, read, alloc.