Fracture splits a solid body into independently moving pieces. This example breaks a sharp convex box, not an arbitrary triangle mesh.
dotnet add package RecursiveAI.OnePhysicsRequires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.
using RecursiveAI.OnePhysics.Physics3D; using RecursiveAI.OnePhysics.Destruction; var world = new PhysicsWorld3D(); var box = world.AddBox(new(2, 2, 2)); var pieces = box.Fracture(new FractureDef { CellCount = 8, Seed = 42 }); Console.WriteLine( $"Fragments: {pieces.Length}");
Fragments: 8Unzip the example, then dotnet run.
The full program
The program fractures an in-memory box, reads its event before the next step, then applies a four-fragment debris budget. It restores a snapshot and repeats the operation.
using RecursiveAI.OneMath; using RecursiveAI.OnePhysics; using RecursiveAI.OnePhysics.Physics3D; using RecursiveAI.OnePhysics.Destruction; var world = new PhysicsWorld3D(); world.Debris = new DebrisOptions { MaxFragments = 4, LifetimeSteps = 120 }; var box = world.AddBox(new(2, 2, 2), at: new(0, 4, 0)); box.SetLinearVelocity(new(2, 0, 0)); byte[] before = world.Snapshot(); ulong BreakAndStep() { var pieces = box.Fracture(new FractureDef { CellCount = 8, Seed = 42 }); Console.WriteLine($"Fragments created: {pieces.Length}"); Console.WriteLine($"Fracture events: {world.FractureEvents.Length}"); world.Step(1f / 60); Console.WriteLine($"Fragments kept: {world.DestructionCounters.FragmentsAlive}"); return world.ComputeHash(); } ulong first = BreakAndStep(); world.Restore(before); Console.WriteLine("Restored fracture:"); ulong second = BreakAndStep(); Console.WriteLine($"Repeated hash matches: {first == second}"); try { world.AddSphere(1).Fracture(); } catch (FractureException) { Console.WriteLine("Sphere refused: FractureException"); }
dotnet run prints:
Fragments created: 8 Fracture events: 1 Fragments kept: 4 Restored fracture: Fragments created: 8 Fracture events: 1 Fragments kept: 4 Repeated hash matches: True Sphere refused: FractureException
Unsupported shapes throw FractureException, as the sphere in this program shows.
Variations
Read a fragment’s velocity. Append this to the snippet at the top:
Console.WriteLine($"Velocity x: {pieces[0].LinearVelocity.X:F1}");The additional line is:
Velocity x: 0.0Related recipes
The short answer
Call body.Fracture(new FractureDef { CellCount = 8, Seed = 42 }) on a supported convex body. It replaces the original with dynamic Voronoi cells and returns their new body handles. Use world.Debris to limit how many fragments remain after stepping. The original handle is stale once fracture succeeds.
This is sharp convex fracture: boxes and sharp convex hulls in 3D, and polygons in 2D. It is not arbitrary mesh fracture. Spheres, capsules, meshes and rounded shapes are refused, as are bodies belonging to a joint, vehicle, character or ragdoll. Manual fracture throws FractureException; a body configured to fracture automatically is left whole when its shape is unsupported.
How does rigid body fracture work?
OnePhysics places seeds and clips the original convex geometry into Voronoi cells. CellCount requests a seed count, not an unconditional output count: cells that clip away or merge can leave fewer fragments. Seed controls the deterministic generator. The example requests eight cells with seed 42 and gets eight fragments from its box.
Pattern selects uniform seeds, seeds clustered around an impact point, or explicit points. For a manual clustered fracture, ImpactPoint is a world position; explicit Points are in the body’s own frame. Do not interchange those coordinate systems when using a collision point to direct the fracture. The same seed gives the same cells across platforms, according to the destruction guide.
How do you get the velocity of a rigid body?
Read LinearVelocity from a returned fragment, as the variation above does.
The fragments inherit the original body’s velocity field rather than receiving an automatic explosion impulse. The public API describes mass, linear momentum and angular momentum as conserved “to rounding,” except when small cells are deleted with MergeSmall = false. If a scene needs pieces thrown outward, fracture alone is not that effect. The velocity-reading variation prints zero because its source box begins at rest; the full program gives its source box a nonzero linear velocity before breaking it.
Manual fracture happens between steps. Its event is available immediately in world.FractureEvents; the full program reads it before calling Step. The event identifies the destroyed source and refers to the fragments in world.FractureFragments. Events describe what broke, not a permanent registry of every fragment still alive. Retain the returned handles only as long as those bodies exist.
For contact-driven destruction, configure SetFracturable with an ImpulseThreshold. That threshold measures contact impulse in kg m/s, not force in newtons. A qualifying contact makes the body break at the end of the step. Depth allows subsequent generations to break, while ChildThresholdScale raises their threshold. This is a different trigger from calling Fracture yourself, not a requirement for the manual example.
Set a debris policy when repeated destruction should not keep adding bodies indefinitely. MaxFragments removes the smallest pieces first, then the oldest, at the end of a step. The full program creates eight and keeps four after stepping. LifetimeSteps removes fragments by age in simulation steps. SleepToStaticSteps can replace settled fragments with static bodies, changing their handles. All three rules default to off. A cached handle can therefore stop being valid because of debris management as well as another fracture.
Fracture settings, debris state and the resulting bodies are part of snapshots and world hashes. The full program restores the intact box and repeats the fracture and step; the hashes match. Keep the seed, geometry, input state and step sequence the same when reproducing a result. Subscriptions attached to the destroyed body do not move onto its fragments, so register any per-fragment handlers against the new bodies rather than continuing to use the old source.