Broken props remembered
How SDF remembers broken props across reloads and resets them by zone - Persistence Lifetime, Remember Debris Layout, partly broken props, Start Broken ruins, your own save game and the cheat commands.
The player breaks the pots in a corridor, leaves, and comes back: the pots are still broken. They rest at a checkpoint, and the pots stand again. The barricade they broke to open a shortcut stays open for good.
USDFDestructionPersistenceSubsystem (SDF Destruction Persistence, on the game instance) remembers
which props are broken, so a reloaded level brings them back broken, with no sound, effect or debris
replay. It lives on the game instance so the record survives a level reload, and it keeps only
identifiers, so your game can round-trip it through its own save.
SDF owns no checkpoint or death logic: your game calls the subsystem from wherever those events already exist.
Zones and resets
Each placed destructible component has three settings under Persistence:
| Setting | Default | What it does |
|---|---|---|
| Destruction Zone Id | None | Props sharing a zone come back together when that zone is reset |
| Participates In Persistence | on | Off keeps the prop out of the records: a loaded save never breaks it |
| Persistent Id Override | None | A key of your own, required for props spawned while the game runs |
Your game resets zones with these calls on the subsystem. Each returns how many props it restored:
| Call | Wire it to |
|---|---|
NotifyRestAtCheckpoint(ZoneId) | Resting at a checkpoint |
NotifyPlayerDeath(ZoneId) | The player’s death |
ResetZone(ZoneId) | Any other reset of one zone |
ResetAllZones() | A reset of every zone |
Without a zone, NotifyRestAtCheckpoint and NotifyPlayerDeath restore every zone. A prop with no
Destruction Zone Id comes back only when every zone is reset. The records of the zone are cleared
even for props whose level is not loaded, so a streamed-out prop does not come back already broken.
OnZoneRestored(ZoneId) fires on the subsystem after each reset, with None when every zone was reset.
A reset puts a fallen prop back where it was placed. A locked prop comes back whole and still locked. The Integration Examples map shows it with its Rest at a Bonfire station; see Integration examples.
How long it stays broken
Persistence Lifetime, on the Behavior, or as the Override Persistence Lifetime exception on one setup or one placed copy:
| Value | What it does |
|---|---|
| Reset With Zone (the default, as in SDF 1.0) | The prop comes back whole when its zone is reset: the pots return when the player rests |
| Permanent | The prop stays broken through every zone reset, death, rest and reload: an opened shortcut, a breached barricade |
A Permanent prop’s record carries bPermanent, so it holds even while its level is not loaded. A
script’s ResetDestruction() still restores it and forgets the record. A record from a save written
before Permanent existed reads as Reset With Zone.
Its key
Each prop is remembered under a key made of its map and its actor’s name, and its component’s name
when the actor holds several destructibles. The key is the same in the Editor, in PIE and in a packaged
game, and two maps that reuse actor names keep separate records. GetPersistentDestructionId() returns
it.
- A prop spawned while the game runs has a generated name: give it a Persistent Id Override.
- Two props that end up with the same key are reported in the log as they register.
- In a World Partition cell, the key uses the world’s map rather than the cell’s level, so a prop keeps its state when its cell unloads and loads again.
- A record written by SDF 1.0, keyed without its map, moves to the new key when exactly one loaded prop matches it. When several do, it is ignored and the log says so.
ResetDestruction()makes a prop whole and erases its record, so the next save no longer lists it.
Where its debris lay
Remember Debris Layout, on the Behavior or as the Override Remember Debris Layout exception on one setup or one placed copy, is off by default: a prop loaded already broken shows no debris, as in SDF 1.0.
On, its pieces come back where they lay when the game saved (GetPersistedDestructions) or its level
unloaded, asleep: nothing falls or rolls on load, and a piece still moving at that moment finishes
settling. A prop whose level streams out takes its debris with it; they come back with it.
- The record’s
DebrisLayoutholds them: 5 bytes, plus 25 when the pieces are Chaos pieces, then 21 bytes per Chaos piece or 27 per Swap And Scatter piece. Positions are kept to the millimetre and rotations to well under 0.01 degree. - A record from an older save, a damaged one, or one whose Geometry Collection was re-fractured since brings the prop back broken without debris, as in SDF 1.0. A placed copy set not to remember sets down no debris, whatever the save holds.
- Restored Chaos pieces take a slot of the Chaos budget like fresh ones: past it, the prop comes back without debris. The debris lifetime and removal settings start again from the load.
- Glass shards are not remembered.
Partly broken props
A prop set to Partial Break that has lost
pieces but still stands is remembered by those pieces. FSDFPersistedDestruction::FallenPieces lists
them, by their index in the Geometry Collection; it is empty for a prop broken whole and in older saves.
- Loaded, those pieces have fallen again, where they lay with Remember Debris Layout and gone without it, and the others stand, held, with no sound or effect.
- A zone reset brings the prop back whole unless it is Permanent.
- Its collapse makes the record a whole break.
- Its health is not remembered: loaded, it has its full health again.
On the component, IsPartlyBroken() and GetFallenShare() (Blueprint) and GetFallenPieces() (C++)
read the state.
Ruins set in the editor: Start Broken
Start Broken, on a placed copy’s destructible component, is off by default. On, the prop begins play already broken, with no sound or effect, its debris asleep where Bake Broken Layout left them.
- Bake Broken Layout, a button under Start Broken, breaks a copy of the prop with Broken Layout Seed (1) in a private world holding a copy of the static meshes around it, 3 m around and 2 m above and below its bounds. It lets the pieces settle, eight seconds at most, and keeps where they lie on the component.
- The same seed and surroundings bake the same layout, byte for byte; another seed lays the pieces out otherwise. Bake again after moving the prop or what it stands on.
- Ground that is not a static mesh, such as a landscape, stands in as a flat slab where a trace under the prop meets it. Instanced meshes and foliage are not copied into the bake.
- A zone reset leaves a Start Broken prop broken, and no record is written for it: it was never broken
in play. A script’s
ResetDestruction()rebuilds it. - Its debris come back as baked on every load, wherever the player pushed them.
- Without a baked layout, it starts broken with no debris.
Your own save game
GetPersistedDestructions() returns every record, for writing into your save game.
ApplyPersistedDestructions(Records) replaces the record set when you load it: the live props are
brought in line, and the saved props break again with no sound or effect.
Each FSDFPersistedDestruction holds:
| Field | What it holds |
|---|---|
PersistentId | The prop’s key |
ZoneId | Its Destruction Zone Id |
bPermanent | It is Permanent. False in saves written before it existed |
DebrisLayout | Where its debris lay, packed, with Remember Debris Layout. Empty otherwise and in older saves |
FallenPieces | The pieces a partly broken prop had lost. Empty for a prop broken whole and in older saves |
BreakVariant | For an Animated Break, which of its Break Animations it played; it comes back at that animation’s end. -1 for any other prop and in older saves |
IsBroken(PersistentId) and GetBrokenCount() read the record set. The Integration Examples map’s
Save the Broken Props and Load the Broken Props stations round-trip the records through a save
game with one array variable.
Older saves
A record from a save written before 2.0 reads as Reset With Zone, brings the prop back broken without debris, and has no fallen pieces, as in SDF 1.0.
Hanging props and fire
- A level loaded with a hanging prop’s chain remembered broken leaves the prop lying on the ground below where it hung. See Hanging props.
- A prop consumed by fire is remembered broken like any break. A prop consumed standing (Burns Without Breaking) is not saved: it comes back unburnt on load. See Fire and burning props.
Cheat commands
Three console commands, not in Shipping builds, act on the world they are typed in:
| Command | Does |
|---|---|
SDF.ResetAll | Restores every zone, as a rest at a checkpoint would |
SDF.ResetZone <ZoneId> | Restores one zone |
SDF.ListBroken | Lists the props remembered broken, in the log |
In a networked game, type them on the server. See Diagnostics for the other development commands.
In a networked game
The persistence records and saves live on the server. A zone reset, a death or a rest at a checkpoint called on the server makes the props whole on every machine, and Permanent props stay broken everywhere. See Networked games.
What is not saved
Glass shards are not remembered. Restored Chaos pieces need a slot of the Chaos budget, and past it the prop comes back without debris. A prop consumed standing by fire comes back unburnt. A partly broken prop’s health, locks, the physics positions of intact props and embedded projectiles are not saved.
Last updated: 2026-10-27