DestructionService

Getting it

local DestructionService = Engine:GetService("DestructionService")

Overview

DestructionService turns ordinary parts and models into destructibles. A destructible has health; when it runs out, the object is cut into real mesh shards (using GeometryService-style mesh generation) that fly apart with physics, settle, and are cleaned up after a while.

local DestructionService = Engine:GetService("DestructionService")

local wall = DestructionService:MakeDestructible(workspace.Wall, {
	health = 250,
	pieces = 24,
	effect = "WallCrumble", -- an EffectService effect, optional
	debris = { removal = "Fade", delay = { min = 8, max = 14 } },
})

wall.Damaged:Connect(function(amount, health)
	print("wall at", health)
end)

-- From a weapon
wall:Damage(40)

-- Or blow up everything nearby
DestructionService:Explode(position, { radius = 20, damage = 300 })

Fracturing live or ahead of time

Cutting a mesh into pieces takes time. For objects that must break instantly, pre-fracture them while the game loads: the pieces are computed once and kept hidden, and breaking only swaps them in.

DestructionService:PrefractureManyAsync(workspace.Breakables:GetChildren(), { pieces = 20 })
	:andThen(function()
		print("all breakables ready")
	end)

Where to call it

Destructibles work on both the server and the client.

• Server-side destructibles break for everyone and are the safe choice for gameplay objects.
• Client-side destructibles break only for that player, which is cheap and good for decoration. Make the same object destructible on the server too; see Client breaks and Server Authority for what the server does with it.
• With authoritative = true, a client's :Damage() and :BreakAsync() calls are sent to the server instead of applied locally.

Client breaks and Server Authority

When an object breaks on one client only, the client tells the server, and the server looks at who moves that player's character:

• The client moves its own character, as in classic games. The player walks through the gap on their own screen, and the object keeps colliding on the server, so server raycasts and NPCs still hit a wall that is broken on one screen only.
• The server moves the character, with Server Authority or in a game that keeps characters owned by the server. The server turns CanCollide, CanQuery and CanTouch off on its copy while a player has the object broken, so that player can walk through it, and turns them back on once no player has it broken any more (it was repaired, or the player left). This needs the object to be destructible on the server too; Engine warns you when it is not.

Making things destructible

MakeDestructible

DestructionService:MakeDestructible(target: Model | BasePart, config: MakeDestructibleConfig?): Destructible

Fracture patterns:

Shards smaller than minPieceSize (bounding-box diagonal in studs) are dropped. With useCompute and a piece count at or above the configured threshold, cutting runs in parallel through ComputeService. A seed makes the fracture repeatable.

GetDestructible

DestructionService:GetDestructible(target: Instance): Destructible?

Destructible

BreakConfig is { ImpulseOrigin: Vector3?, ImpulseMagnitude: number? }: where the blast comes from and how hard pieces are thrown.

Pieces are added to the world in small batches per frame (DefaultFinalizeBatchSize), so even a large break does not cause a hitch.

What the shards look like

Shards look like the part they came from:

• A MeshPart's SurfaceAppearance carries over: its color map with its Color tint and AlphaMode, and its normal, metalness, roughness and emissive maps through a SurfaceAppearance made with AssetService:CreateSurfaceAppearanceAsync. Engine uses the appearance whose SurfaceSlot is All, or the one for slot 0 on a mesh with a single material.
• Decals keep their Color3 and Transparency and stack by ZIndex. A transparent texture or decal shows the part's color underneath.
• A pixelated texture (ResampleMode = Pixelated on a Decal, Texture or SurfaceAppearance) stays pixelated, and a textured MeshPart keeps its Transparency.
• The cut faces show the texture of the part they were cut from.

All textures of one break share a single texture atlas of at most 1024 by 1024 pixels, and are scaled down when they do not fit. A texture the game may not load does not stop the break: those shards use the part's color, and one warning names the asset.

Explosions

Explode

DestructionService:Explode(position: Vector3, config: { radius: number, damage: number, impulse: number?, falloff: boolean?, losCheck: boolean? })

Damages every destructible within radius. With falloff (default on) damage and impulse shrink with distance. With losCheck an object behind cover is not hit. Only destructibles are affected; damage players yourself.

Pre-fracturing

Pre-fractured pieces are used automatically when the object is made destructible, before or after pre-fracturing.

Debris

There is a global cap on live debris pieces. When it is exceeded the oldest pieces are removed and DebrisBudgetExceeded fires with the number removed.

Structural collapse

BuildSupportGraph

DestructionService:BuildSupportGraph(model: Model, config: { supportTag: string?, autoCollapse: boolean? }?): SupportGraph

Works out which parts of a model touch each other. When a part is destroyed, any part that is no longer connected to the ground, directly or through other parts, falls: with autoCollapse (default on) it is unanchored and becomes debris, and SupportBroken fires.

A part counts as ground when it is Anchored or has the supportTag CollectionService tag. Parts that are neither are held up only through their connections, so leave the parts that should be able to fall unanchored (for example welded to the structure) and keep the foundation anchored or tagged.

Configuration

Types

export type Destructible
export type SupportGraph
export type MakeDestructibleConfig
export type FractureOverrides
export type DebrisConfig
export type ExplodeConfig
export type SupportGraphConfig
export type PrefractureConfig