---
title: "Fracture a rigid body in C#"
url: https://recursiveai.org/onephysics/cookbook/fracture-rigid-body/
description: "Fracture splits a solid body into independently moving pieces. This example breaks a sharp convex box, not an arbitrary triangle mesh."
version: "1.0.0"
---

# Fracture a rigid body in C#

**OnePhysics** is a free, open-source physics library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

[NuGet](https://www.nuget.org/packages/RecursiveAI.OnePhysics) · [GitHub](https://github.com/recursive-ai-oss/onephysics-csharp) · [Docs](https://recursiveai.org/onephysics/docs/) · [Download example (.zip)](https://recursiveai.org/onephysics/cookbook/fracture-rigid-body/fracture-rigid-body.zip)

Fracture splits a solid body into independently moving pieces. This example breaks a sharp convex box, not an arbitrary triangle mesh.

```shell
dotnet add package RecursiveAI.OnePhysics
```

Requires [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) (net10.0); .NET 9 and earlier aren’t supported.

```csharp
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}");
```

```text
Fragments: 8
```

Unzip [the example](https://recursiveai.org/onephysics/cookbook/fracture-rigid-body/fracture-rigid-body.zip), 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.

```csharp
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:

```text
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:

```csharp
Console.WriteLine($"Velocity x: {pieces[0].LinearVelocity.X:F1}");
```

The additional line is:

```text
Velocity x: 0.0
```

## Related recipes

- [Carve destructible 2D terrain in C#](https://recursiveai.org/onephysics/cookbook/carve-destructible-2d-terrain/)
- [Edit 3D voxel terrain in C#](https://recursiveai.org/onephysics/cookbook/edit-3d-voxel-terrain/)

---

## 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](https://recursiveai.org/onephysics/docs/destruction/).

## 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.
