Class ScyllaLooseQuadtree

Managed wrapper around ScyllaLooseQuadtreeCore that owns native container lifetime, enforces parameter invariants, and provides a built-in query scratch stack for convenient use from managed C# code without needing to supply a traversal buffer.

Inheritance
object
ScyllaLooseQuadtree
Implements
Inherited Members
Namespace: Scylla.Core.Structures
Assembly: ScyllaCore.dll
Syntax
public sealed class ScyllaLooseQuadtree : IScyllaCollection, IDisposable
Remarks

Ownership and disposal: This class owns the underlying ScyllaLooseQuadtreeCore and the internal query scratch stack. Call Dispose() when the tree is no longer needed to release unmanaged memory. Failing to dispose will leak native allocations.

Thread-safety: Unsynchronized. All read and write operations on this instance must be externally coordinated when accessed from multiple threads. See Unsynchronized.

Job usage: Access the underlying Burst-compilable kernel via the Core property and pass it to Unity jobs by value. Do not dispose this wrapper while a job using the core is scheduled or running.

Typed payload variant: If you need to associate arbitrary data with each item ID, use ScyllaLooseQuadtree<T> instead, which adds a managed dictionary for payload storage. 

// Direct construction
var quadtree = new ScyllaLooseQuadtree(rootBounds, maxDepth: 8, maxItemsPerNode: 8,
    looseness: 1.2f, allocator: Allocator.Persistent);

// Using fluent builder for complex configuration
var quadtree = ScyllaLooseQuadtree.CreateBuilder()
.WithRootBounds(rootBounds)
.WithMaxDepth(8)
.WithMaxItemsPerNode(8)
.WithLooseness(1.2f)
.WithAllocator(Allocator.Persistent)
.Build();

Constructors

ScyllaLooseQuadtree(ScyllaAABB2, int, int, float, Allocator, int)

Creates a new managed loose quadtree, allocating the underlying native containers.

Declaration
public ScyllaLooseQuadtree(ScyllaAABB2 rootBounds, int maxDepth, int maxItemsPerNode, float looseness, Allocator allocator, int initialItemCapacity = 64)
Parameters
Type Name Description
ScyllaAABB2 rootBounds

Tight root bounds of the tree. Items are accepted only when fully contained by the root loose bounds (tight bounds scaled by looseness). Both size axes must be greater than zero.
int maxDepth

Maximum subdivision depth. Pass 0 to store all items in the root node with no subdivision.
int maxItemsPerNode

Number of items a node may hold before it is subdivided. Must be at least 1.
float looseness

Looseness expansion factor for node bounds. Must be a finite value of at least 1.0. Typical values are between 1.1 and 2.0.
Allocator allocator

Native memory allocator used for the internal node list and item map. Use Allocator.Persistent for trees that live across multiple frames.
int initialItemCapacity

Initial capacity hint for the item hash map. Defaults to 64.
Exceptions
Type Condition
ArgumentException

Thrown when rootBounds is invalid.
ArgumentOutOfRangeException

Thrown when any numeric parameter is outside its valid range.

Properties

Capabilities

Capability flags supported by this collection instance.

Declaration
public ScyllaCollectionCapabilities Capabilities { get; }
Property Value
Type Description
ScyllaCollectionCapabilities

Core

Provides access to the underlying ScyllaLooseQuadtreeCore struct for direct use in Burst-compiled jobs. The returned struct is a copy - modifications made inside a job do not affect this wrapper's core unless the modified struct is written back explicitly.

Declaration
public ScyllaLooseQuadtreeCore Core { get; }
Property Value
Type Description
ScyllaLooseQuadtreeCore
Remarks

Do not dispose this wrapper while a job that holds the core is executing. Native containers are owned by this wrapper and disposing it invalidates the core's internal arrays.

Exceptions
Type Condition
ObjectDisposedException

Thrown when the tree has been disposed.

Count

Number of items currently stored.

Declaration
public int Count { get; }
Property Value
Type Description
int

IsEmpty

Convenience property indicating whether the tree contains no items.

Declaration
public bool IsEmpty { get; }
Property Value
Type Description
bool

SyncRoot

Synchronization root for externally coordinating operations with this collection. For unsynchronized collections this is null.

Declaration
public object SyncRoot { get; }
Property Value
Type Description
object

ThreadSafety

Declares the thread-safety guarantees provided by this collection instance.

Declaration
public ScyllaCollectionThreadSafety ThreadSafety { get; }
Property Value
Type Description
ScyllaCollectionThreadSafety

Methods

Add(int, ScyllaAABB2)

Adds a new item to the tree with the given 2D bounding box.

Declaration
public void Add(int itemID, ScyllaAABB2 bounds)
Parameters
Type Name Description
int itemID

Unique integer ID for the item. Must not already be registered. Use any integer that is meaningful in the caller's domain (e.g. an entity ID or instance ID).
ScyllaAABB2 bounds

2D bounding box of the item. Must be fully contained by the root loose bounds (RootLooseBounds).
Exceptions
Type Condition
ArgumentException

Thrown when bounds is not fully contained by the root loose bounds.
InvalidOperationException

Thrown when itemID is already registered in the tree.
ObjectDisposedException

Thrown when the tree has been disposed.

Add(int, float3, float3, ScyllaQuadtreePlane)

Adds a new item whose 3D world-space AABB is projected onto the selected 2D plane before insertion.

Declaration
public void Add(int itemID, float3 min, float3 max, ScyllaQuadtreePlane plane = ScyllaQuadtreePlane.XZ)
Parameters
Type Name Description
int itemID

Unique integer ID for the item. Must not already be registered.
float3 min

Minimum corner of the 3D world-space AABB.
float3 max

Maximum corner of the 3D world-space AABB.
ScyllaQuadtreePlane plane

Projection plane used to reduce the 3D AABB to a ScyllaAABB2. Defaults to XZ (top-down/ground-plane projection).
Exceptions
Type Condition
ArgumentException

Thrown when the projected bounds are not contained by the root loose bounds.
InvalidOperationException

Thrown when itemID is already registered.
ObjectDisposedException

Thrown when the tree has been disposed.

Clear()

Removes all items and resets the tree to a single root node, discarding all subdivision.

Declaration
public void Clear()
Exceptions
Type Condition
ObjectDisposedException

Thrown when the tree has been disposed.

Contains(int)

Returns true if an item with the specified ID is currently registered in the tree.

Declaration
public bool Contains(int itemID)
Parameters
Type Name Description
int itemID

The integer ID to test for membership.
Returns
Type Description
bool

true if the ID was previously added and has not since been removed; false otherwise.
Exceptions
Type Condition
ObjectDisposedException

Thrown when the tree has been disposed.

CreateBuilder()

Creates a new ScyllaLooseQuadtree.Builder with default settings for constructing a ScyllaLooseQuadtree via a fluent API.

Declaration
public static ScyllaLooseQuadtree.Builder CreateBuilder()
Returns
Type Description
ScyllaLooseQuadtree.Builder

A new ScyllaLooseQuadtree.Builder instance pre-configured with: maxDepth = 8, maxItemsPerNode = 8, looseness = 1.2, itemCapacity = 64. Root bounds and allocator must be set via the builder before calling Build().

Dispose()

Disposes the tree's native containers (node list, item map, and query scratch stack) and marks the instance as disposed.

Declaration
public void Dispose()
Remarks

Safe to call multiple times; subsequent calls after the first are no-ops. After disposal, any attempt to use other methods on this instance will throw an ObjectDisposedException.

QueryOverlap(ScyllaAABB2, NativeList<int>)

Overlap query: appends the IDs of all items whose bounding boxes intersect query to results.

Declaration
public void QueryOverlap(ScyllaAABB2 query, NativeList<int> results)
Parameters
Type Name Description
ScyllaAABB2 query

The 2D query region. Items are returned when their stored bounds overlap this region. The list is not cleared before appending - clear it first if a fresh result set is needed.
NativeList<int> results

Output list to which matching IDs are appended.
Exceptions
Type Condition
ObjectDisposedException

Thrown when the tree has been disposed.

QueryOverlap(float3, float3, NativeList<int>, ScyllaQuadtreePlane)

Overlap query using a 3D world-space AABB projected onto the selected plane.

Declaration
public void QueryOverlap(float3 min, float3 max, NativeList<int> results, ScyllaQuadtreePlane plane = ScyllaQuadtreePlane.XZ)
Parameters
Type Name Description
float3 min

Minimum corner of the 3D query AABB.
float3 max

Maximum corner of the 3D query AABB.
NativeList<int> results

Output list to which matching IDs are appended. Not cleared before appending.
ScyllaQuadtreePlane plane

Projection plane. Defaults to XZ.
Exceptions
Type Condition
ObjectDisposedException

Thrown when the tree has been disposed.

QueryRadius(float2, float, NativeList<int>)

Radius query: appends the IDs of all items whose bounding boxes are within radius of center.

Declaration
public void QueryRadius(float2 center, float radius, NativeList<int> results)
Parameters
Type Name Description
float2 center

2D center of the search circle in the tree's coordinate space.
float radius

Search radius. An item is included when the closest point on its bounds is within this distance. Negative values cause the query to be skipped.
NativeList<int> results

Output list to which matching IDs are appended. Not cleared before appending.
Exceptions
Type Condition
ObjectDisposedException

Thrown when the tree has been disposed.

QueryRadius(float3, float, NativeList<int>, ScyllaQuadtreePlane)

Radius query using a 3D world-space center projected onto the selected plane.

Declaration
public void QueryRadius(float3 center, float radius, NativeList<int> results, ScyllaQuadtreePlane plane = ScyllaQuadtreePlane.XZ)
Parameters
Type Name Description
float3 center

3D world-space center to project and use as the query circle center.
float radius

Search radius. See the 2D overload for full semantics.
NativeList<int> results

Output list to which matching IDs are appended. Not cleared before appending.
ScyllaQuadtreePlane plane

Projection plane. Defaults to XZ.
Exceptions
Type Condition
ObjectDisposedException

Thrown when the tree has been disposed.

QueryRay(float2, float2, float, float, NativeList<int>)

Ray query: appends the IDs of all items whose bounding boxes intersect the ray segment within the parametric interval [tMin, tMax].

Declaration
public void QueryRay(float2 origin, float2 invDir, float tMin, float tMax, NativeList<int> results)
Parameters
Type Name Description
float2 origin

2D ray origin in the tree's coordinate space.
float2 invDir

Component-wise reciprocal of the 2D ray direction. Use RcpSafe(float2) when the direction may contain zero components to avoid producing NaN.
float tMin

Minimum ray parameter (typically 0f to start at the origin).
float tMax

Maximum ray parameter. Pass float.PositiveInfinity for an infinite ray.
NativeList<int> results

Output list to which matching IDs are appended. Not cleared before appending.
Exceptions
Type Condition
ObjectDisposedException

Thrown when the tree has been disposed.

QueryRay(float3, float3, float, float, NativeList<int>, ScyllaQuadtreePlane)

Ray query using 3D world-space origin and direction projected onto the selected plane. The direction's reciprocal is computed internally using RcpSafe(float2).

Declaration
public void QueryRay(float3 origin, float3 direction, float tMin, float tMax, NativeList<int> results, ScyllaQuadtreePlane plane = ScyllaQuadtreePlane.XZ)
Parameters
Type Name Description
float3 origin

3D world-space ray origin to project onto the selected plane.
float3 direction

3D world-space ray direction to project and invert for the AABB slab test.
float tMin

Minimum ray parameter.
float tMax

Maximum ray parameter.
NativeList<int> results

Output list to which matching IDs are appended. Not cleared before appending.
ScyllaQuadtreePlane plane

Projection plane. Defaults to XZ.
Exceptions
Type Condition
ObjectDisposedException

Thrown when the tree has been disposed.

Rebuild(NativeArray<int>, NativeArray<ScyllaAABB2>)

Performs a bulk rebuild by clearing the tree and reinserting every item from the parallel arrays. Prefer this over repeated Update(int, ScyllaAABB2) calls when most items move every tick.

Declaration
public void Rebuild(NativeArray<int> itemIDs, NativeArray<ScyllaAABB2> bounds)
Parameters
Type Name Description
NativeArray<int> itemIDs

Array of item IDs to reinsert. Must have the same length as bounds.
NativeArray<ScyllaAABB2> bounds

Array of 2D bounding boxes corresponding by index to itemIDs.
Exceptions
Type Condition
ArgumentException

Thrown when itemIDs and bounds have different lengths.
ObjectDisposedException

Thrown when the tree has been disposed.

Remove(int)

Removes the item with the specified ID from the tree.

Declaration
public bool Remove(int itemID)
Parameters
Type Name Description
int itemID

ID of the item to remove.
Returns
Type Description
bool

true if the item was found and removed; false if the ID was not registered.
Exceptions
Type Condition
ObjectDisposedException

Thrown when the tree has been disposed.

Update(int, ScyllaAABB2)

Updates the 2D bounding box of an existing item, reinserting it into a different node if it has moved outside its current node’s loose bounds.

Declaration
public bool Update(int itemID, ScyllaAABB2 newBounds)
Parameters
Type Name Description
int itemID

ID of the item to update. Must be currently registered.
ScyllaAABB2 newBounds

The item’s updated 2D bounding box. Must be within the root loose bounds.
Returns
Type Description
bool

true if the item was found and its bounds were updated; false if the ID was not registered or the new bounds exceed the root loose bounds.
Exceptions
Type Condition
ObjectDisposedException

Thrown when the tree has been disposed.

Update(int, float3, float3, ScyllaQuadtreePlane)

Updates an existing item’s bounds from a 3D world-space AABB projected onto the selected plane.

Declaration
public bool Update(int itemID, float3 min, float3 max, ScyllaQuadtreePlane plane = ScyllaQuadtreePlane.XZ)
Parameters
Type Name Description
int itemID

ID of the item to update. Must be currently registered.
float3 min

Minimum corner of the new 3D world-space AABB.
float3 max

Maximum corner of the new 3D world-space AABB.
ScyllaQuadtreePlane plane

Projection plane. Defaults to XZ.
Returns
Type Description
bool

true if the item was found and updated; false otherwise.
Exceptions
Type Condition
ObjectDisposedException

Thrown when the tree has been disposed.

Implements

Extension Methods

See Also