Debris: keep, remove, budget and rest
What happens to the pieces after a prop breaks — keep them or remove them after a delay, shrink before removal, the debris budget for scenes full of pieces, how pieces leave, land and come to rest, the physics prerequisites, pieces that pass through each other and anchored bases.
By default, a broken crate stays broken: its planks scatter, come to rest on the floor and stay there for as long as the level runs, as in a souls-like world. You can instead have a prop’s pieces removed after a delay, one by one, shrinking away. Either way, SDF keeps a scene full of debris affordable with a debris budget, and makes the pieces leave the blow, land and rest without sinking into the floor, hanging in the air or flying back at the player. No Blueprint timer or cleanup script is needed.
Keep or remove
Debris Behavior has two choices:
- Keep Debris in World (the default): the debris stays in the world after settling. Nothing removes it with the default settings.
- Remove Debris After Delay: starts removing this prop’s debris after Start Removing After (seconds), measured from its destruction. A new setup starts at 30 seconds; decimals are accepted. Keep hides the removal fields.
With Remove selected, two more settings shape the removal:
- Removal Spread (seconds) (advanced, 0 by default). 0 removes all the prop’s pieces together at the delay. A positive value spreads the individual removals over that extra time: with delay 30 and spread 5, every piece remains for 30 seconds, the first goes at 30 and the last by about 35, within normal frame and timer precision.
- Shrink Before Removal (seconds) (0 by default, as in SDF 1.0). When a piece’s removal comes, it shrinks to nothing over this time, then goes. It shrinks rather than fades, so it works with any material. With delay 30, spread 5 and shrink 1, the last piece is gone by about 36 seconds. 0 removes each piece at once.
While it shrinks, a Swap And Scatter piece or a glass shard stops where it lies, with no simulation and no collision. A Chaos piece keeps its collision until it goes, and is drawn smaller only when its Geometry Collection’s Scale On Removal is on (the engine’s default); with it off, the piece stays full size and goes at the end.
A delay of zero means the next safe processing opportunity, not an infinite lifetime. Negative or non-finite values are refused: a prop with invalid debris settings returns Invalid Debris Settings and the log names the field. The summary under the settings shows the effective choice.
Where to set it
- Before Generate: the Debris Behavior section of Create Destructible (and of Batch Generate). Generate records the choice on the setup and in its manifest, and Regenerate keeps it, even if the preset changes later. A choice that differs from the picked Behavior’s is written as the setup’s Debris Settings exception.
- On a shared Behavior: its Debris Behavior applies to every prop that uses it, unless the setup or the placed copy sets its own. A setup with no Behavior carries it on itself, as in SDF 1.0.
- For one placed copy: select it, then its Destructible Component, and turn on Customize Debris Settings. The first activation copies the effective settings and the summary changes from Profile to This Instance; the profile and other copies are not changed. Turn it off to use the profile again. Re-enabling it restores the copy’s saved custom values.
- As an exception, Debris Settings on a setup’s Overrides or a placed copy’s Instance Overrides. See Exceptions.
Keep describes presence in the current world. It does not save the pieces across game sessions: for that, see Remember Debris Layout in Broken props remembered.
Try it in the demo
The Debris Behavior stand on the south side of L_SDF_Showcase holds the same three wooden
crates and two ceramic pots on each half. The left five keep their debris; the right five remove
it, Start Removing After 8 seconds, Removal Spread 5 seconds, through instance settings.
Each prop’s clock starts when that prop breaks: about 13 seconds after the last break, the right
side is clear. See Playable demo.
Settling is separate from removal
Physics settling lets pieces come to rest; it never removes them. Its settings are under the Behavior’s advanced Debris Physics section:
| Setting | Default | Meaning |
|---|---|---|
| Start Checking for Rest (seconds) | 2 | When SDF starts checking whether the pieces have stopped |
| Wait for Debris to Settle | On | Wait until the pieces actually stop before freezing them, so none freezes in mid-air |
| Maximum Additional Settle Time (seconds) | 4 | The longest extra wait for that rest |
| Reduce Collision After Settling | On | Settled pieces stop answering pawns and gameplay traces, but keep resting on the world and on each other |
The first settling window ends at the break plus the rest-check delay plus the extra settle time. It is not a promise that every body is frozen by then: airborne pieces keep falling. A shared check twice a second keeps supervising persistent Chaos debris while it exists — sleeping pieces cost no solver writes, slow supported pieces may be put to sleep, fast or airborne ones keep moving, and contact can wake pieces again. There is no tick per piece. A long removal delay does not lengthen this physics window, and the removal clock starts at the break, independently of settling.
Settled-debris eviction is a third, separate mechanism, off by default. Allow Settled Debris Eviction, in the budget limits, caps the frozen debris kept in the world at Max Settled Debris Actors (60), oldest first. Turned on, it may remove even Keep debris, or timed debris earlier; the Debris Behavior summary warns about it. Leave it off unless your game deliberately trades persistence for a hard ceiling on very long sessions.
Each break starts its own schedule. A reset cancels that prop’s schedule, a partly completed spread
included; other props, and the other regions of a composite, keep their debris. Removal never
destroys the source actor, released arrows, loot or neighbouring props. SDF.Debug.ClearDebris
removes every piece of debris while you test; broken props stay broken.
Many pieces at once
Three project settings, under Project Settings > Plugins > Souls Destruction Framework > Performance Budget > Budget Limits, keep a scene full of debris affordable. None of them removes a piece.
- Debris Shadows Beyond (3000 cm by default). A piece farther than this from every player camera stops casting its shadow, and casts it again as soon as a camera comes nearer. The distance is measured from the edge of the piece’s bounds, four times a second, and only while such debris exists. The pieces of one Chaos break share one component: they lose their shadow together, once all of them are beyond the distance. 0 keeps every shadow, as in SDF 1.0.
- Hide Debris Beyond (0 by default: never). Above 0, it becomes each piece’s draw distance: the engine stops drawing the piece beyond it. The piece still exists, keeps its collision, and is drawn again when the camera comes back.
- Max Active Debris Pieces (200 by default). While more pieces than this are moving — the pieces of the breaks of the last 3 seconds — a new break keeps only one piece in two knocking against the other debris: level 1. Each time the count doubles, the level rises, up to level 4: one piece in sixteen. The other pieces still land on the floor and the walls, and characters and weapons still hit them; they only pass through other debris. The next break after the pieces have settled is level 0 again. 0 turns this off. Past level 4, SDF still removes no piece.
Debris Always Visible, on a setup or as an exception on one placed copy, keeps that prop’s debris out of the two distances: its pieces keep their shadows and are drawn at any distance. Use it for a centrepiece the player looks at from far away. It does not change the collision levels.
USDFDestructionSubsystem::GetBudgetStats() reports ActiveDebrisPieces,
LastDebrisCollisionLevel and TotalReducedDebrisPieces; SDF.Debug.Stats prints the moving
pieces against Max Active Debris Pieces and the last level. A game can change the limits at
runtime with ConfigureBudgetLimits.
Measured on the demo (UE 5.7, RTX 5080):
| Measure | Result |
|---|---|
| 16 barrels broken at once, physics time over the next 2 s, best of 3 | 853 ms with the levels off, 812 ms at 400, 650 ms at 200 (a quarter less), 505 ms at 100. The worst single step stays about 27 ms |
| The 54 props of the showcase broken, debris at rest, no shadow beyond 5 m | 27 % fewer primitives drawn (1.30 M to 0.94 M), 11 % fewer draw calls (377 to 336). The GPU frame, about 1.15 ms at 1280 x 720 on this card, does not change |
The drawing saving matters where drawing is the limit; it was not measured on smaller hardware. See Performance.
How pieces leave, land and rest
These rules apply to every SDF Geometry Collection debris, with no setting to author.
- Launch away from the impact point. Every piece is pushed away from the point that was hit,
from its own centre, so the pieces scatter to either side of the blow, never down into the ground
they stand on; a piece at the impact point itself follows the hit direction. Launch speed comes
from
GeometryCollectionBreakVelocity,GeometryCollectionDamageRadiusandGeometryCollectionDistantFragmentScale.GeometryCollectionRadialBiasis no longer used; it is kept only so existing profiles load unchanged. - No piece is thrown back at the attacker. No piece is launched toward whoever broke the prop: the hit’s Damage Causer, or else its Instigator’s pawn. A blow on the side of a crate sends the pieces in front of it sideways rather than at the player. Pieces whose collision starts inside each other — a barrel’s hoop is boxed across the whole barrel — are thrown about as Chaos parts them: for the first 0.3 s after the break, a piece goes toward that player at 30 cm/s, and faster only as fast as falling and tipping over take it (half of gravity at most). A headstone struck low still topples onto them; no piece is thrown at them. A hit with neither field set launches the pieces from the impact point alone.
- Stronger hits, if you want them. With Scale Launch By Hit Strength on (off by default), a stronger hit throws the pieces faster: the hit’s Impulse Strength divided by Reference Hit Impulse (750), kept within Launch Scale Range (0.6 to 1.8); spin follows up to Maximum Spin Scale (1.5).
- Load collapse. The pieces under a resting prop slide out of its way and let it through, so the prop falls into the wreck. See Intact physics and fall damage.
- Contact refinement. Chaos sometimes leaves the deepest point of a resting convex piece out of its contact. On the physics thread, SDF checks each contact between debris and the fixed world (floors, walls, static props) against the engine’s own depth for every volume of the piece and, when the contact misses a deeper penetration or pushes a sunk piece sideways, moves it onto the real deepest point. Overlap from the current step is solved at once; older overlap is resolved at no more than 20 cm/s, so a correction never launches a piece. Contacts with simulated bodies and between pieces are left to Chaos.
- Depenetration. SDF debris resolve late-detected overlap at 100 cm/s, where Unreal’s Geometry Collection component would otherwise keep it.
- Solver iterations. Islands that contain SDF debris are solved with 32 position and 8 velocity iterations, so a piece under other pieces is not pressed visibly into the floor. Islands without debris keep the project’s counts.
- Rest freeze. Shortly after the break, a piece whose speeds stay near zero for three consecutive checks is put to sleep where it lies. A piece sunk more than 0.5 cm into a floor, or more than 0.5 cm inside another piece, is never frozen until it is separated. A piece that stays within 1 cm of one spot for half a second, moving no faster than 3 cm/s, rests there even if it creeps or rocks; one that stays within 1 cm for two seconds rests however it turns, outside a partly broken prop. A piece that stays in place sunk no more than 1 cm is lifted straight out of the floor and put to sleep. Two pieces that fall side by side still overlapping are moved apart, half each, up to 2 cm. A piece that wakes again — knocked by a blow, a character or another piece — comes back to rest under the same rules.
- Resting with neighbours. Chaos puts a pile to sleep only all at once, so a still body of another prop lying in a pile of SDF debris — a loose prop, another break’s pieces — goes to sleep with the pile.
- Settled pieces keep resting on one another. Reduce Collision After Settling stops settled debris from blocking pawns and gameplay traces; the pieces of a wreck still collide with each other and with simulated props lying on them, so nothing sinks into its neighbours.
For comparison while testing, SDF.Debris.ContactRefinement 0, SDF.Debris.RestFreeze 0 and
SDF.Debris.RestWithNeighbours 0 turn the contact refinement, the rest freeze and the resting with
neighbours off.
Debris physics prerequisites
Thin debris needs both fitted collision and a small enough physics step. A small step cannot repair invalid mass or collision smaller than the visible piece, and fitted collision cannot make up for a step that is too large.
A project with default physics settings does not meet the strict demo contact guarantee. In a controlled UE 5.7 test with substepping off, as in a fresh project, two pieces’ mass centres crossed the floor during the fall at 30 FPS even though the final visible penetration was only 0.1012 cm; the 60 and 120 FPS cases passed. A small final penetration alone does not prove correct contact throughout the fall.
The demo’s validated configuration uses synchronous physics substepping, in Project Settings > Physics > Framerate:
| Setting | Value |
|---|---|
| Substepping | On |
| Max Substep Delta Time | 0.008333333 s |
| Max Substeps | 4 |
| Max Physics Delta Time | 0.033333333 s |
This allows up to four physics steps per 30 FPS frame; frames slower than 30 FPS can exceed that
capacity, so validate your own frame-rate range and CPU budget. The exact section is in
Config/SDFDemoPhysics.ini: copy it into your project’s Config/DefaultEngine.ini, or enter the
values in Project Settings. The plugin does not load that file and never changes your project’s
physics settings. Validation warns when the prerequisite is missing or has too little step capacity
(SDF-PHYS-001); the warning only informs. Asynchronous fixed-step physics needs its own validation.
Collision Shape: Precise Convex is the default for new setups of every preset that produces a Geometry Collection: up to four convex volumes per piece that cover every visible vertex, so debris rests on the floor instead of sinking at its corners or hanging on empty space. It adds collision complexity and does not remove the physics-step prerequisite. Setups made before 2.0 keep their Preset Recipe. See Authoring presets.
The demo contact test checks every demo collection at 30, 60 and 120 FPS: at rest no piece sinks more than 0.5 cm into the floor, no piece goes through the floor or is lost, and a brief dip below the floor surface during an impact is tolerated.
Pieces Pass Through Each Other
Pieces Pass Through Each Other, on the setup (Debris section) or as an exception on one setup or one placed copy, is off by default: the broken pieces collide with each other, as in SDF 1.0. On, they collide with the world and never with each other.
It is meant for props whose parts are modelled through each other: a chain’s links hang through one another, a cage’s bars are riveted through its hoops. Colliding, such pieces would start inside each other and throw each other apart. The Metal (Assembled Parts) and Chain presets turn it on.
Since nothing can hold it up, a piece left standing on its end — a bar of a cage that landed upright — tips over on its foot, away from the middle of the prop: its foot stays where it stands while its top falls, each such piece its own way, up to 30 degrees either side of straight out, and at its own pace. One that falls against a wall or another prop may stay leaning there. Chaos props only.
Anchored Base Height
Anchored Base Height (cm) keeps the bottom of a Chaos prop where it stood when it breaks: the floor of a crate, the foot of a barrel, the plinth of a statue. Every piece lying wholly below that height, measured from the bottom of the pieces, stays still — within a millimetre — while the rest goes. 0, the default, frees every piece, as in SDF 1.0: the whole object breaks at once.
- Release Base On Hit (on by default): a later hit on a piece of the base frees that piece alone, if the hit is as strong as the prop’s Minimum Destruction Power. Off, the base stays whatever hits it.
- Set it in section 2. How Does It React? of Create Destructible, in Modify Destructible…, on the setup’s Geometry Collection section, or as the Anchored Base exception on one setup or one placed copy. The setup records it, so Regenerate and Modify keep it.
- Preview shows the anchored pieces in grey and counts them. Pieces cut across the whole height of the prop — the cells of a fractured pot — reach above a low base: Preview then says that no piece stays, and a greater height is needed.
- Swap And Scatter debris and glass have no fixed pieces: the base applies to Chaos props only.
Related
- Debris Pushed By Characters: characters nudging the pieces at their feet.
- Audio: the sound of pieces landing, and Surface Responses.
- Niagara and VFX: cosmetic splinters and dust have their own lifetimes; Debris Behavior does not retime them.
- Partial break: the debris settings apply from the collapse.
Last updated: 2026-10-29