Class SharedHullCache

Namespace

Stride.CommunityToolkit.Bepu

Assembly

Stride.CommunityToolkit.Bepu.dll

Keeps one DecomposedHulls per distinct shape and size, so many bodies of the same shape share a single Bepu hull.

public static class SharedHullCache

Inheritance

object

SharedHullCache

Remarks

Stride caches the built Bepu ConvexHull against the DecomposedHulls instance it came from. A fresh instance per body therefore means a fresh hull per body: a thousand identical prisms build, store and eventually free a thousand identical hulls.

That is expensive, and worse than expensive. The hulls hold unmanaged buffers taken from a static pool that Stride returns them to from a finalizer, so the garbage collector can hand memory back while the simulation is allocating from the same pool on its worker threads. Sharing one instance keeps the entry alive for the process, which removes the churn and the finalizer entirely.

Entries are never evicted. One hull per distinct shape and size is a small, bounded cost, and releasing them is what causes the problem in the first place.

Methods

CreateCollider(string, float, float, float, Func<DecomposedHulls>)

Returns a new ConvexHullCollider backed by shared hull data.

public static ConvexHullCollider CreateCollider(string shape, float a, float b, float c, Func<DecomposedHulls> factory)

Parameters

shape string

Identifier for the shape family, distinguishing hulls of equal dimensions.

a float

First dimension of the shape.

b float

Second dimension, or zero when unused.

c float

Third dimension, or zero when unused.

factory Func<DecomposedHulls>

Builds the hull data when the shape and size have not been seen before.

Returns

ConvexHullCollider

A collider that shares its hull with every other collider of the same shape and size.

Remarks

The collider itself is new each time - a collidable owns its collider - but the hull behind it is shared, which is where the cost lives.

GetOrAdd(string, float, float, float, Func<DecomposedHulls>)

Returns the shared hull data for a shape and size, building it on first use.

public static DecomposedHulls GetOrAdd(string shape, float a, float b, float c, Func<DecomposedHulls> factory)

Parameters

shape string

Identifier for the shape family, distinguishing hulls of equal dimensions.

a float

First dimension of the shape.

b float

Second dimension, or zero when unused.

c float

Third dimension, or zero when unused.

factory Func<DecomposedHulls>

Builds the hull data when the shape and size have not been seen before.

Returns

DecomposedHulls

Hull data shared by every caller using the same shape and dimensions.