Class ScyllaLooseOctree

Managed wrapper around ScyllaLooseOctreeCore. This wrapper owns the native containers and provides parameter validation and a convenience query scratch stack.

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

Thread-safety: unsynchronized by default (matches Scylla collection patterns). Use external synchronization if accessed concurrently.

// Direct construction
var octree = new ScyllaLooseOctree(rootBounds, maxDepth: 8, maxItemsPerNode: 8, looseness: 1.2f, allocator:
Allocator.Persistent);
// Using fluent builder for complex configuration
var octree = ScyllaLooseOctree.CreateBuilder()
.WithRootBounds(rootBounds)
.WithMaxDepth(8)
.WithMaxItemsPerNode(8)
.WithLooseness(1.2f)
.WithAllocator(Allocator.Persistent)
.Build();

Constructors

ScyllaLooseOctree(ScyllaAABB3, int, int, float, Allocator, int)

Creates a new loose octree.

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

Tight root bounds; all items must be contained by the root loose bounds
int maxDepth

Maximum subdivision depth (0 disables subdivision)
int maxItemsPerNode

Maximum items per node before subdivision
float looseness

Looseness factor (>= 1)
Allocator allocator

Allocator used for internal native containers
int initialItemCapacity

Initial capacity for item storage

Properties

Capabilities

Capability flags supported by this collection instance.

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

Core

Exposes the underlying Burst-friendly core for job usage.

Declaration
public ScyllaLooseOctreeCore Core { get; }
Property Value
Type Description
ScyllaLooseOctreeCore

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, ScyllaAABB3)

Inserts a new item into the octree with the given spatial bounds.

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

Unique identifier for the item. Must not already be present in the tree.
ScyllaAABB3 bounds

Spatial bounds of the item. Must be fully contained by the root loose bounds (RootLooseBounds).
Remarks

Unlike TryAdd(int, ScyllaAABB3), this method throws on failure rather than returning false, which is better suited to usage patterns where failed insertion represents a programming error.

Exceptions
Type Condition
ArgumentException

Thrown when bounds lie outside the root loose bounds.
InvalidOperationException

Thrown when an item with itemID already exists in the tree, or when underlying insertion fails for any other reason.
ObjectDisposedException

Thrown when this instance has been disposed.

Clear()

Removes all items from the tree and resets it to a single root node.

Declaration
public void Clear()
Remarks

Delegates to Clear(). The root node geometry (center, half-size, looseness) is preserved; only the item list and all subdivided child nodes are discarded.

Exceptions
Type Condition
ObjectDisposedException

Thrown when this instance has been disposed.

Contains(int)

Determines whether an item with the given ID is currently stored in the tree.

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

The item ID to look up.
Returns
Type Description
bool

true if the item exists; false otherwise.
Exceptions
Type Condition
ObjectDisposedException

Thrown when this instance has been disposed.

CreateBuilder()

Creates a new builder instance for configuring a ScyllaLooseOctree.

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

A new builder instance

Dispose()

Releases native resources owned by this octree: the query scratch stack and the underlying ScyllaLooseOctreeCore (nodes and item map).

Declaration
public void Dispose()
Remarks

This method is idempotent - calling it more than once is safe (the second call is a no-op). After disposal, any subsequent public method call will throw ObjectDisposedException.

QueryOverlap(ScyllaAABB3, NativeList<int>)

AABB overlap query: appends the IDs of all items whose stored bounds overlap query.

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

The axis-aligned bounding box to test against all stored items.
NativeList<int> results

Native list that receives matching item IDs. Existing entries are preserved; matches are appended to the end.
Remarks

Results are appended to results - the list is not cleared before the query. The managed query stack (_queryStack) is reused internally to avoid per-call allocation. Returns immediately without traversing if query is invalid (IsValid is false).

Exceptions
Type Condition
ObjectDisposedException

Thrown when this instance has been disposed.

QueryRadius(float3, float, NativeList<int>)

Sphere query: appends the IDs of all items whose stored bounds intersect the sphere defined by center and radius.

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

World-space center of the query sphere.
float radius

Radius of the query sphere in world units. Negative values produce no results.
NativeList<int> results

Native list that receives matching item IDs. Existing entries are preserved; matches are appended to the end.
Remarks

Results are appended to results - the list is not cleared before the query. The managed query stack (_queryStack) is reused internally to avoid per-call allocation. Returns immediately without traversing if radius is negative.

Exceptions
Type Condition
ObjectDisposedException

Thrown when this instance has been disposed.

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

Ray query: appends the IDs of all items whose stored bounds intersect the ray segment [tMin, tMax].

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

World-space origin of the ray.
float3 invDir

Component-wise reciprocal of the ray direction. Use RcpSafe(float3) when the direction may have zero components.
float tMin

Minimum ray parameter. Use 0 for a ray starting at the origin.
float tMax

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

Native list that receives matching item IDs. Existing entries are preserved; matches are appended to the end.
Remarks

Results are appended to results - the list is not cleared before the query. The managed query stack (_queryStack) is reused internally to avoid per-call allocation.

Pass invDir as the component-wise reciprocal of the ray direction (1/dir.x, 1/dir.y, 1/dir.z). Use RcpSafe(float3) to safely handle axis-aligned rays whose direction components may be zero.

This method returns candidates only - the caller should perform exact intersection tests on returned IDs for precise hit determination.

Exceptions
Type Condition
ObjectDisposedException

Thrown when this instance has been disposed.

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

Clears the octree and rebuilds it from scratch by inserting all items in the provided arrays.

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

Array of unique item IDs to insert. Must have the same length as bounds.
NativeArray<ScyllaAABB3> bounds

Array of spatial bounds parallel to itemIDs.
Remarks

Prefer this over many individual Update(int, ScyllaAABB3) calls when most or all items move each frame. Items whose bounds lie outside the root loose bounds are silently skipped.

Exceptions
Type Condition
ArgumentException

Thrown when itemIDs and bounds have different lengths.
ObjectDisposedException

Thrown when this instance has been disposed.

Remove(int)

Removes the item with the given ID from the octree.

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 existed and was removed; false if no item with itemID was found.
Exceptions
Type Condition
ObjectDisposedException

Thrown when this instance has been disposed.

Update(int, ScyllaAABB3)

Updates the spatial bounds of an existing item.

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

ID of the item whose bounds are being updated.
ScyllaAABB3 newBounds

New spatial bounds. Must be fully contained by the root loose bounds.
Returns
Type Description
bool

true if the item existed and was updated; false if no item with itemID exists or the new bounds lie outside the root loose bounds.
Remarks

Delegates to Update(int, ScyllaAABB3). When the new bounds still fit within the item's current node's loose bounds, this is O(1). Otherwise the item is reinserted from the root, which is O(depth) and may trigger subdivision.

Exceptions
Type Condition
ObjectDisposedException

Thrown when this instance has been disposed.

Implements

Extension Methods