Playmaker.Spatial 0.1.1

Playmaker.Spatial

A tiny, fast 3D spatial partition for .NET using dynamic AABB tree (Also known as BVH) that you can trust to handle thousands of objects.

Quick example

Define your game object with a way to get a tight bounding box enclosing it. The library doesn't care about any other details.

using System;
using System.Numerics;
using Playmaker.Spatial;

public sealed class Asteroid : ISpatialObject
{
    public int Id { get; }
    public AABB Bounds { get; set; }

    public Asteroid(int id, Vector3 center)
    {
        Id = id;
        Bounds = AABB.FromCenterAndSize(center, new Vector3(1, 1, 1));
    }
}

var space = new SpatialPartition<Asteroid>();

var a = new Asteroid(1, new Vector3( 0, 0, 0));
var b = new Asteroid(2, new Vector3(10, 0, 0));

space.Insert(a);
space.Insert(b);

// AABB query
var nearOrigin = space.Query(AABB.FromCenterAndSize(Vector3.Zero, new Vector3(5, 5, 5))); // Or new AABB(min, max)

// First-hit raycast
var hitSomething = space.Raycast(new Ray(new Vector3(-5, 0, 0), Vector3.UnitX), out var hit);
if (hitSomething)
{
    // hit.Object is your Asteroid, hit.Distance is distance along the ray
}

// "Penetrating" raycast means keep going through volumes and collect every hit along the ray,
// sorted by entry distance. Like Unity's Physics.RaycastAll.
var allHits = space.RaycastPenetrating(new Ray(new Vector3(-5, 0, 0), Vector3.UnitX));
// Each hit has Object, Distance, and even EntryPoint/ExitPoint for effects like bullet holes.

// Move an object: you must call Update when the objects bounds change.
a.Bounds = AABB.FromCenterAndSize(new Vector3(2, 0, 0), new Vector3(1, 1, 1));
space.Update(a);

// snapshot the whole tree for debugging; you could hook this up to a UI or something.
var tree = space.GetTreeInfo();
if (tree is not null)
{
    Console.WriteLine(tree);
}

// Remove when gone
space.Remove(b);

A few details that matter

This class is not thread-safe. It’s fast enough to live on your main thread, but if you want to update/query from multiple threads, you're responsible to guard access.

There’s a small test project (Playmaker.Spatial.Tests) that exercises the real-world bits you’ll care about. Run them from the repo root:

dotnet test

License

This project is licensed under Mozilla Public License 2.0. See LICENSE

Attribution & thanks

This project stands on the shoulders of giants. The core idea is heavily inspired by the dynamic AABB tree in Box2D. We also learned significantly from Emmet O’Toole’s excellent Unity port, go read it:

https://github.com/EmmetOT/BoundingVolumeHierarchy/

Thank you for the groundwork and clarity. Any mistakes here are mine.