Documentation
¶
Overview ¶
Package spatial provides spatial indexing primitives for 3D positions: a uniform hash grid (cheap, allocation-free queries), an octree (vertical relevance), and a static BVH (many-static + ray queries).
All three implement the generic Index[T] interface so consumers can pick by access pattern. Single-writer-per-index ownership is the expected concurrency model — pair with kit/actor for safe sharing.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Morton2D ¶
Morton2D interleaves the bits of x and y into a single uint64. Used to order items along a Z-order curve for cache-friendly spatial traversal (consumers building their own linear octrees / quadtrees over fixed dense grids can use this to sort items into Morton order so nearby indices map to nearby memory).
Types ¶
type Index ¶
type Index[T Locatable] interface { Insert(id uint64, item T) Remove(id uint64) Move(id uint64, item T) QueryAABB(box geometry.AABB, out *[]T) QueryRadius(center geometry.Vec3, r float32, out *[]T) QueryRay(r geometry.Ray, out *[]T) }
Index is the common shape of all spatial backends. Queries take an output slice so callers can reuse buffers (zero-allocation hot paths).
func NewBVH ¶
NewBVH builds a static bounding volume hierarchy using a Surface Area Heuristic (SAH) split: at each node we evaluate a small set of candidate split positions and pick the one minimising expected query cost (proportional to surface area × child count). SAH typically yields 20-30% faster queries than median splits on non-uniform inputs.
Items are placed by their Position() as point primitives. Read-only after construction — to mutate, rebuild.
func NewHashGrid ¶
NewHashGrid returns a 2D uniform hash grid indexed by XZ. Y is preserved on stored items but does not partition cells — suitable for ground-plane games. Use NewOctree if you need vertical partitioning.
Source Files