Upgrading from SDF 1.0

What happens to SDF 1.0 setups, manifests and saves when a project moves to SDF 2.0 — the automatic conversion at Editor start, its backups and rollback, what keeps its 1.0 behaviour, and the changes that apply without a setting.

Open a project made with SDF 1.0 in an Editor that runs SDF 2.0 and your setups are converted as the Editor starts. A notification reports the result. A converted setup plays exactly as it did: new options arrive off by default, and every value a 1.0 setup played with is kept. A few changes apply without a setting; they are listed under Changes that apply without a setting.

Before you upgrade

Install the 2.0 package that matches your engine (UE 5.7.4 or 5.8.4) in place of the 1.0 plugin folder — see Installation. The conversion backs up everything it touches, but commit or back up your project first, as before any plugin update.

What changes in a setup

An SDF 1.0 setup carries its own copy of every reaction and material value. In 2.0, a setup references a shared Behavior (health, the hit power needed, the single-hit rule, intact physics, debris timing and optional modules) and a shared Material (break and hit sounds, break and hit effects, impact decals and the response to projectiles). Edit a shared asset and every prop that uses it follows. See Behaviors and Materials.

Automatic conversion at Editor start

When the Editor starts, SDF converts the 1.0 setups of your project content (/Game):

  • each setup’s reaction and material values move into shared assets under /Game/SDF_Shared/Behaviors and /Game/SDF_Shared/Materials; setups with identical values share one asset;
  • the setup and its manifest reference them;
  • every value each setup uses is compared with what it used before, and nothing is saved unless all of them match, so a converted setup plays exactly as it did.

Preset Runtime templates are never converted.

Backups and the ConversionJournal

Before anything changes, every setup and manifest is backed up, with a ConversionJournal.txt that lists each change, under:

Saved/SoulsDestructionFramework/ConversionBackups/

A notification reports the result of the conversion. The journal is the record of each change the run made, next to the backups it made them from.

Rollback

If anything fails during the conversion, the backups are copied back and the shared assets created by that run are removed. Your 1.0 setups are then as they were before the Editor started.

Content outside /Game

Content outside /Game, such as your own plugins, is converted only on request, with the console command:

SDF.ConvertSetups [Preview] [Root=/Path] [Exit]
ArgumentEffect
PreviewLists what would be converted and writes nothing.
RootThe folder to convert. Defaults to /Game.
ExitCloses the Editor when the command finishes (exit code 0 on success), for command-line runs.

Run it with Preview first, read the list, then run it again without Preview.

What keeps its 1.0 behaviour

  • A setup without Behavior, Material or exception is used as it is, and a Behavior without modules reacts as a plain SDF 1.0 profile does.
  • Collision. Setups made before 2.0 read Collision Shape: Preset Recipe, exactly the collision they were published with. New objects use Precise Convex. Modify Destructible… can switch an old setup to Precise Convex, for example when its debris sinks or hangs above the floor. See Modify Destructible.
  • Break By Pawn Collision, the SDF 1.0 body contact with its speed floor and its power, keeps exactly its 1.0 behaviour. The new body contacts of 2.0 are separate options, off by default. See Bodies against props.
  • GeometryCollectionRadialBias is no longer used; it is kept only so existing profiles load unchanged.
  • Health settings — Max Health, Damage Multiplier, Impact Damage Multiplier and Allow Power Override — are greyed out unless Use Health is on and Destroy On Single Valid Hit is off, because they do nothing otherwise. Nothing saved changed: every setting keeps its name and its default value.
  • New choices default to the 1.0 behaviour: Allowed Breakers is Everyone, Navigation On Break is Follow NavMesh, Debris Affects Navigation, Intact Blocks Camera and Intact Blocks Characters are on, Persistence Lifetime is Reset With Zone, Anchored Base Height is 0 and Push When Hit is off.
  • The authoring manifest schema is still version 4. A setup whose manifest was written by an earlier schema is reported as LegacyManifest drift and must be adopted once with Regenerate Destructible… before it can be regenerated or modified. See Validation and regeneration.
  • Setups made before intact physics keep their physics (Keep Existing). Switching them to Simulated is an explicit step with SDF.MigrateToSimulatedPhysics. See Intact physics and fall damage.

Saves

  • A persisted record from a save written before Persistence Lifetime existed reads as Reset With Zone, the SDF 1.0 behaviour.
  • A record from an older save brings the prop back broken without debris, as in SDF 1.0. Its list of fallen pieces (FallenPieces) is empty.
  • A record written by SDF 1.0 was keyed without its map. It moves to the new key, made of the map and the actor’s name, when exactly one loaded prop matches it; when several do, it is ignored and the log says so.

See Broken props remembered.

Changes that apply without a setting

These changes reach converted setups too.

  • No piece is launched back toward whoever broke the prop: the hit’s Damage Causer, or else its Instigator’s pawn. Pieces still leave the impact point, but a blow on the side of a crate sends the pieces in front of it sideways rather than at the player. For the first 0.3 s after the break, a piece may go their way at 30 cm/s, and faster only as fast as falling and tipping over take it. See Who may break a prop, and how hard.
  • Geometry Collection debris follow new launch and rest rules. Every piece leaves the impact point from its own centre; the pieces under a resting prop let it fall into the wreck; contacts with the fixed world are refined; still pieces are put to sleep where they lie, as is a piece that stays in one spot for two seconds however it turns. SDF.Debris.ContactRefinement 0 and SDF.Debris.RestFreeze 0 turn the contact refinement and the rest freeze off for comparison. See Debris.
  • Two debris budget settings are on by default: Debris Shadows Beyond (3000 cm) and Max Active Debris Pieces (200). Neither removes a piece. Set either to 0, in Project Settings > Plugins > Souls Destruction Framework, for the SDF 1.0 behaviour.
  • Broken glass panes report their shards landing on a floor, at most Maximum Shard Landing Sounds times per pane (once by default). Each landing plays the Material’s Debris Impact Sounds; 0 keeps them silent. See Audio.
  • Glass shards leave the pane. A broken pane’s shards are thrown out of its plane, away from the side struck, whichever way the blow travelled. In 1.0 a sword slashing across a window drove them along it, into the window’s own frame. See Runtime glass fracture.
  • Stone breaks raising its dust. The Stone material and the Stone template break with NS_SDF_Impact_Stone: chips, chunks and a grey-white dust rolling along the floor. In 1.0 they played NS_SDF_Dust_Stone alone. A stone setup generated before keeps the break effect it was given: select NS_SDF_Impact_Stone in its Break Effects, or regenerate it. See Niagara and VFX.
  • A projectile in flight shoves nothing. While USDFProjectileMovementComponent flies it, a projectile’s collision body collides by query only, and gets its own collision back when the flight ends. In 1.0 a precise arrow passing through a simulated prop’s collision box could throw the prop with it. See Projectile integration.
  • Props fall into a broken support. The pieces of a Geometry Collection that lie under a resting prop slide out of its way, so none can hold it up or throw it up, and the prop comes to rest on the wreck. See Intact physics and fall damage.

Documentation correction

The 1.0 runtime guide said a projectile could inflict damage without enough Destruction Power. That was wrong. The rule is: a hit below Minimum Destruction Power only reacts and does not reduce health, however large its Damage, and this applies to projectiles too. See Who may break a prop, and how hard.

After the upgrade

  1. Read the conversion notification, and the ConversionJournal.txt it wrote.
  2. Run SDF.Validate to check every SDF asset under /Game and /SoulsDestructionFramework, or SDF.Validate Root=/Game/YourFolder for one folder. Validation only reads. See Diagnostics.
  3. Play a level with a representative prop and open Diagnose this object on it: it shows the values the prop really plays, Behavior, Material and exceptions included.
  4. Convert content outside /Game with SDF.ConvertSetups, if you have any.
  5. Decide, setup by setup, whether to switch old collision to Precise Convex and old stone break effects to NS_SDF_Impact_Stone. Neither happens on its own.

Last updated: 2026-10-27

Type to search titles, sections and keywords.