Class ScyllaBVH.Builder

Fluent builder for constructing ScyllaBVH instances with complex configurations. Supports allocator, multiple capacity parameters (item, node, query stack), and fattening margin.

Inheritance
object
ScyllaBVH.Builder
Inherited Members
Namespace: Scylla.Core.Structures
Assembly: ScyllaCore.dll
Syntax
public sealed class ScyllaBVH.Builder
Remarks

The builder provides a discoverable API for configuring BVH instances without relying on positional parameters. Use Build() to obtain a configured BVH instance. Use BuildConcrete() to obtain the concrete BVH type (same as Build() since there's no synchronized wrapper).

Required Configuration:

Optional Configuration: 

// Basic usage with required allocator
var bvh = ScyllaBVH.CreateBuilder()
.WithAllocator(Allocator.Persistent)
.Build();
// Configure all parameters
var bvh = ScyllaBVH.CreateBuilder()
.WithAllocator(Allocator.Persistent)
.WithItemCapacity(256)
.WithNodeCapacity(512)
.WithQueryStackCapacity(1024)
.WithFatteningMargin(0.2f)
.Build();
// BuildConcrete() returns same as Build() (no synchronized wrapper)
var bvh = ScyllaBVH.CreateBuilder()
.WithAllocator(Allocator.TempJob)
.WithItemCapacity(64)
.BuildConcrete();

Methods

Build()

Builds and returns the configured ScyllaBVH instance.

Declaration
public ScyllaBVH Build()
Returns
Type Description
ScyllaBVH

The configured ScyllaBVH instance
Remarks

Validates that WithAllocator(Allocator) has been called before constructing the BVH. Since ScyllaBVH doesn't have a synchronized wrapper, this method returns the concrete type directly.

Exceptions
Type Condition
InvalidOperationException

Thrown when allocator has not been set via WithAllocator()

BuildConcrete()

Builds and returns the concrete ScyllaBVH instance. This method is functionally identical to Build() since ScyllaBVH doesn't have a synchronized wrapper.

Declaration
public ScyllaBVH BuildConcrete()
Returns
Type Description
ScyllaBVH

The configured ScyllaBVH instance
Remarks

Validates that WithAllocator(Allocator) has been called before constructing the BVH. This method exists for API consistency with other collection builders, but returns the same type as Build().

Exceptions
Type Condition
InvalidOperationException

Thrown when allocator has not been set via WithAllocator()

WithAllocator(Allocator)

Sets the memory allocator for native containers. This method must be called before Build() or BuildConcrete().

Declaration
public ScyllaBVH.Builder WithAllocator(Allocator allocator)
Parameters
Type Name Description
Allocator allocator

Memory allocator for native containers (must not be Allocator.None)
Returns
Type Description
ScyllaBVH.Builder

This builder instance for method chaining
Remarks

Allocator Selection:

  • Allocator.Persistent: Long-lived BVH (recommended for most game scenarios)
  • Allocator.TempJob: BVH used within a single frame across jobs
  • Allocator.Temp: Short-lived BVH used within a single frame (avoid for BVH due to size)

Validation:

Allocator.None is not allowed and will throw an ArgumentException.

Exceptions
Type Condition
ArgumentException

Thrown when allocator is Allocator.None

WithFatteningMargin(float)

Sets the fattening margin used to expand leaf AABBs.

Declaration
public ScyllaBVH.Builder WithFatteningMargin(float margin)
Parameters
Type Name Description
float margin

The fattening margin. Must be >= 0 and finite (not NaN or Infinity).
Returns
Type Description
ScyllaBVH.Builder

This builder instance for method chaining
Remarks

Leaf AABBs are expanded by this margin to reduce update frequency for moving objects.

Trade-offs:

  • Larger values: Fewer updates but more false positives in queries
  • Smaller values: More updates but tighter query results
  • Typical range: 0.05 to 0.2 (5% to 20% expansion)
Exceptions
Type Condition
ArgumentOutOfRangeException

Thrown when margin is negative, NaN, or Infinity

WithItemCapacity(int)

Sets the initial capacity for item storage (IDs and bounds arrays).

Declaration
public ScyllaBVH.Builder WithItemCapacity(int capacity)
Parameters
Type Name Description
int capacity

The initial item capacity. Must be at least 0. If negative, will be clamped to 0 during construction.
Returns
Type Description
ScyllaBVH.Builder

This builder instance for method chaining
Remarks

This is a hint to reduce early allocations. The BVH will grow automatically if needed. Set this to the number of items you expect to store.

Exceptions
Type Condition
ArgumentOutOfRangeException

Thrown when capacity is negative

WithNodeCapacity(int)

Sets the initial capacity for BVH node storage.

Declaration
public ScyllaBVH.Builder WithNodeCapacity(int capacity)
Parameters
Type Name Description
int capacity

The initial node capacity. Must be at least 0. If negative, will be clamped to 0 during construction.
Returns
Type Description
ScyllaBVH.Builder

This builder instance for method chaining
Remarks

This is a hint to reduce early allocations. The BVH will grow automatically if needed. For a complete binary tree, node capacity should be approximately 2 * itemCapacity - 1.

Exceptions
Type Condition
ArgumentOutOfRangeException

Thrown when capacity is negative

WithQueryStackCapacity(int)

Sets the initial capacity for the query traversal stack.

Declaration
public ScyllaBVH.Builder WithQueryStackCapacity(int capacity)
Parameters
Type Name Description
int capacity

The initial query stack capacity. Must be at least 0. If negative, will be clamped to 0 during construction.
Returns
Type Description
ScyllaBVH.Builder

This builder instance for method chaining
Remarks

This is a hint to reduce early allocations during queries. The stack will grow automatically if needed. Capacity depends on tree depth; 256 is suitable for most cases.

Exceptions
Type Condition
ArgumentOutOfRangeException

Thrown when capacity is negative

Extension Methods