Explosion

Show Deprecated

An Explosion applies force to BaseParts|BasePart within the explosion's Explosion.BlastRadius. This force breaks JointInstances and WeldConstraints between parts and kills Humanoid characters not protected by a ForceField. Constraints will not be broken by an explosion.

If an explosion is instanced while the game is running, it will destroy itself shortly afterwards, so they do not need to be cleaned up using the Debris service.

Explosion effects

Humanoids are killed by explosions as they break the character Model's neck joint. Parenting a ForceField to a model will protect all of its children from Explosions. This means that their joints will not be broken and thus Humanoids will not be killed.

If a developer doesn't want joints between BaseParts to be broken or wants to implement their own formula for damaging Humanoids it is recommended they set Explosion.DestroyJointRadiusPercent to 0 and use the Explosion.Hit event to handle the result of the explosion.

Explosions can also be configured to damage Terrain, creating craters, this behavior is controlled by the ExplosionType property.

The effect of an Explosion is not disrupted by obstacles, this means parts shielded behind other parts will still be affected, even if the BasePart they are shielded behind is not anchored.

Code Samples

Explosion Instantiation

local explosion = Instance.new("Explosion")
explosion.BlastRadius = 60
explosion.ExplosionType = Enum.ExplosionType.Craters -- damages terrain
explosion.Position = Vector3.new(0, 10, 0)
explosion.Parent = workspace

Summary

Properties

Used to determine the amount of force applied to BaseParts caught in the Explosion.BlastRadius.

This property determines the radius of the Explosion, in studs. This radius determines the area of effect of the explosion, not the size of the explosion's visuals.

Used to set the proportion of the Explosion.BlastRadius, between 0 and 1, within which all joints will be destroyed. Anything outside of this range will only have the Explosion force applied to it.

This property determines how the Explosion will interact with Terrain. Used to set if explosions will cause damage to the terrain or not.

This property is the position of the center of the Explosion. It is defined in world-space and not influenced by the Explosion's parent.

Value between 0-1 that controls the speed of the particle effect.

This property determines whether or not the visual effect of an Explosion is shown or not.

Methods

Events

Hit(part: BasePart, distance: number): RBXScriptSignal  

Fires when the Explosion hits a BasePart within its Explosion.BlastRadius. Returns the part hit along with the distance of the part from Explosion.Position.

Properties

BlastPressure

Used to determine the amount of force applied to BaseParts caught in the Explosion.BlastRadius.

Currently this level of force applied does not vary based on distance from Explosion.Position. Unanchored BaseParts will accelerate equally away from the origin regardless of distance provided they are within the blast radius.

The blast pressure determines the acceleration of parts due to an explosion. It does not determine the degree to which joints are broken. When Explosion.DestroyJointRadiusPercent is equal to 1 all joints between parts in the Explosion.BlastRadius will be destroyed provided BlastPressure is greater than 0.

The BlastPressure also does not determine the amount of damage given to Terrain. Provided BlastPressure is greater than 0 and Explosion.ExplosionType isn't set to Enum.ExplosionType.NoCraters the size of the crater created is determined exclusively by the Explosion.BlastRadius.

Setting BlastPressure to 0 eliminates the effect of the explosion and is useful when developers want to program their own custom behavior for explosions using the Explosion.Hit event.

Code Samples

Custom Explosion

local function customExplosion(position, radius, maxDamage)
local explosion = Instance.new("Explosion")
explosion.BlastPressure = 0 -- this could be set higher to still apply velocity to parts
explosion.DestroyJointRadiusPercent = 0 -- joints are safe
explosion.BlastRadius = radius
explosion.Position = position
-- set up a table to track the models hit
local modelsHit = {}
-- listen for contact
explosion.Hit:Connect(function(part, distance)
local parentModel = part.Parent
if parentModel then
-- check to see if this model has already been hit
if modelsHit[parentModel] then
return
end
-- log this model as hit
modelsHit[parentModel] = true
-- look for a humanoid
local humanoid = parentModel:FindFirstChild("Humanoid")
if humanoid then
local distanceFactor = distance / explosion.BlastRadius -- get the distance as a value between 0 and 1
distanceFactor = 1 - distanceFactor -- flip the amount, so that lower == closer == more damage
humanoid:TakeDamage(maxDamage * distanceFactor) -- TakeDamage to respect ForceFields
end
end
end)
explosion.Parent = game.Workspace
end
customExplosion(Vector3.new(0, 10, 0), 12, 50)

BlastRadius

This property determines the radius of the Explosion, in studs. This property accepts any value between 0 and 100.

This radius determines the area of effect of the Explosion, not the size of the Explosion's visuals. The size of the Explosion's visual effect is the same regardless of BlastRadius (even if BlastRadius is 0).

BaseParts within the BlastRadius will be affected by the explosion. Meaning, if Explosion.BlastPressure is greater than 0, force will be applied to parts. The degree to which joints are broken within the BlastRadius depends on Explosion.DestroyJointRadiusPercent. Explosion.Hit will fire for any every BasePart within the radius.

BaseParts are considered within an Explosion's BlastRadius even if they are only partially in range.

Code Samples

Explosion Instantiation

local explosion = Instance.new("Explosion")
explosion.BlastRadius = 60
explosion.ExplosionType = Enum.ExplosionType.Craters -- damages terrain
explosion.Position = Vector3.new(0, 10, 0)
explosion.Parent = workspace

DestroyJointRadiusPercent

Used to set the proportion of the Explosion.BlastRadius, between 0 and 1, within which all joints will be destroyed. Anything outside of this range will only have the Explosion force applied to it.

For example, if Explosion.BlastRadius is set to 100 and DestroyJointRadiusPercent is set to 0.5, any joints within a radius of 50 studs would be broken. Any joints between the ranges of 50 and 100 studs wouldn't be destroyed, but the Explosion's force would still be applied to the BaseParts.

This property allows developers to make Explosions 'non-lethal' to Humanoids by setting DestroyJointRadiusPercent to 0. This means the neck joint will not be broken when characters come into contact with the Explosion.

Code Samples

Custom Explosion

local function customExplosion(position, radius, maxDamage)
local explosion = Instance.new("Explosion")
explosion.BlastPressure = 0 -- this could be set higher to still apply velocity to parts
explosion.DestroyJointRadiusPercent = 0 -- joints are safe
explosion.BlastRadius = radius
explosion.Position = position
-- set up a table to track the models hit
local modelsHit = {}
-- listen for contact
explosion.Hit:Connect(function(part, distance)
local parentModel = part.Parent
if parentModel then
-- check to see if this model has already been hit
if modelsHit[parentModel] then
return
end
-- log this model as hit
modelsHit[parentModel] = true
-- look for a humanoid
local humanoid = parentModel:FindFirstChild("Humanoid")
if humanoid then
local distanceFactor = distance / explosion.BlastRadius -- get the distance as a value between 0 and 1
distanceFactor = 1 - distanceFactor -- flip the amount, so that lower == closer == more damage
humanoid:TakeDamage(maxDamage * distanceFactor) -- TakeDamage to respect ForceFields
end
end
end)
explosion.Parent = game.Workspace
end
customExplosion(Vector3.new(0, 10, 0), 12, 50)
Non lethal explosions

local function onDescendantAdded(instance)
if instance:IsA("Explosion") then
local explosion = instance
explosion.DestroyJointRadiusPercent = 0
local destroyJointRadiusPercent = 1
explosion.Hit:Connect(function(part, distance)
-- check the part is in range to break joints
if distance <= destroyJointRadiusPercent * explosion.BlastRadius then
-- make sure the part does not belong to a character
if not game.Players:GetPlayerFromCharacter(part.Parent) then
part:BreakJoints()
end
end
end)
end
end
workspace.DescendantAdded:Connect(onDescendantAdded)

ExplosionType

This property determines how the Explosion will interact with Terrain. It is an Enum.ExplosionType value and can be set to one of three options.

  • NoCraters - Explosions will not damage Terrain
  • Craters - Explosions will create craters in Terrain
  • CratersAndDebris - Redundant, behaves the same as Craters

If ExplosionType is set to create craters in Terrain, the radius of the crater will be roughly equal to the Explosion.BlastRadius. Craters are created in all Terrain materials other than water. The size of the crater is not influenced by the material, although some materials create rougher edges than others.

Code Samples

Stop Explosions from Damaging Terrain

local function onDescendantAdded(instance)
if instance:IsA("Explosion") then
instance.ExplosionType = Enum.ExplosionType.NoCraters
instance:GetPropertyChangedSignal("ExplosionType"):Connect(function()
instance.ExplosionType = Enum.ExplosionType.NoCraters
end)
end
end
workspace.DescendantAdded:Connect(onDescendantAdded)

Position

This property is the position of the center of the Explosion. It is defined in world-space and not influenced by the Explosion's parent.

BaseParts will be influenced by the Explosion if they are within Explosion.BlastRadius studs of the explosion's position.

The effect of an explosion is instantaneous. This means that although the position of an explosion can be changed after it has been set it cannot affect two different areas. Once an explosion has been 'detonated', shortly after parenting it to a descendant of the Workspace, it will not do so again. In some cases the visual effect of the explosion will move but it will have no effect.

For this reason a new Explosion should be created if the developer wants an explosion to appear at a different position.

Code Samples

Explosion Instantiation

local explosion = Instance.new("Explosion")
explosion.BlastRadius = 60
explosion.ExplosionType = Enum.ExplosionType.Craters -- damages terrain
explosion.Position = Vector3.new(0, 10, 0)
explosion.Parent = workspace

TimeScale

A value between 0-1 than controls the speed of the particle effect. At 1 it runs at normal speed, at 0.5 it runs at half speed, and at 0 it freezes time.

Visible

This property determines whether or not the visual effect of an Explosion is shown or not.

When Visible is set to false, the explosion will still affect BaseParts in its Explosion.BlastRadius, the only difference is it will not be seen.

One use for this property would be for a developer to make their own custom explosion effects using a ParticleEmitter, while retaining the default Explosion functionality.

Code Samples

Explosion Custom Visuals

local function customExplosion(position)
local explosion = Instance.new("Explosion")
explosion.Position = position
explosion.Visible = false
local attachment = Instance.new("Attachment")
attachment.Position = position
attachment.Parent = workspace.Terrain
local particleEmitter = Instance.new("ParticleEmitter")
particleEmitter.Enabled = false
particleEmitter.Parent = attachment
particleEmitter.Speed = NumberRange.new(5, 30)
particleEmitter.SpreadAngle = Vector2.new(-90, 90)
explosion.Parent = workspace
particleEmitter:Emit(20)
task.delay(5, function()
if attachment then
attachment:Destroy()
end
end)
end
customExplosion(Vector3.new(0, 10, 0))

Methods

Events

Hit

Fires when the Explosion hits a BasePart within its Explosion.BlastRadius. Returns the part hit along with the distance of the part from Explosion.Position.

Note that the effect of an Explosion is not disrupted by obstacles, this means parts shielded behind other parts will still be hit, even if the BasePart they are shielded behind is anchored.

This event will also fire when Explosion.BlastPressure is equal to zero. This means developers can program their own custom behavior for explosions by eliminating the explosion's influence on BaseParts and Terrain.

Note that this event will fire for every BasePart hit. This means it can fire multiple times for the same player character (as the character Model is made up of multiple parts). For this reason when dealing custom damage using the Explosion.Hit event it's recommended to implement a check to see if the character has already been hit by the Explosion.

Parameters

part: BasePart

The BasePart hit by the Explosion.

distance: number

The distance of the hit from Explosion.Position.


Code Samples

Custom Explosion

local function customExplosion(position, radius, maxDamage)
local explosion = Instance.new("Explosion")
explosion.BlastPressure = 0 -- this could be set higher to still apply velocity to parts
explosion.DestroyJointRadiusPercent = 0 -- joints are safe
explosion.BlastRadius = radius
explosion.Position = position
-- set up a table to track the models hit
local modelsHit = {}
-- listen for contact
explosion.Hit:Connect(function(part, distance)
local parentModel = part.Parent
if parentModel then
-- check to see if this model has already been hit
if modelsHit[parentModel] then
return
end
-- log this model as hit
modelsHit[parentModel] = true
-- look for a humanoid
local humanoid = parentModel:FindFirstChild("Humanoid")
if humanoid then
local distanceFactor = distance / explosion.BlastRadius -- get the distance as a value between 0 and 1
distanceFactor = 1 - distanceFactor -- flip the amount, so that lower == closer == more damage
humanoid:TakeDamage(maxDamage * distanceFactor) -- TakeDamage to respect ForceFields
end
end
end)
explosion.Parent = game.Workspace
end
customExplosion(Vector3.new(0, 10, 0), 12, 50)