Explosions

Use the Explosion component to damage and push nearby objects from one point, such as when a grenade detonates or a destructible barrel reaches zero Health.

Create an explosion prefab

1. Open Tools > Opsive > Ultimate Character Controller > Object Manager.
2. Enter a Name, select Explosion for Object Type, and select Build Object. An Explosion does not require a source GameObject in the manager.
3. Save the generated prefab. The Object Manager adds Particle System and Explosion components.
4. Configure the Particle System’s material, duration, and playback so the visual starts when the prefab is activated. The Explosion component does not control particles directly.
5. In Explosion, set Radius to the gameplay reach and configure Impact Damage Data for the targets, damage, and force.
6. Review Impact Actions. The generated component starts with Simple Damage, Spawn Surface Effect, and Impact Event.
7. Enable Line Of Sight when solid cover should protect targets, then make sure the cover layers are also included in Impact Damage Data > Layer Mask.
8. Add clips to Explosion Audio Clip Set when the detonation needs sound. UCC’s shared audio system obtains the audio source at runtime.
9. Choose one owner for detonation: Explode On Enable, a grenade or projectile, a Health death object, or your own call to Explode. Do not enable two of these paths for the same spawn.

Before testing, the saved prefab should contain one Explosion component, its visual effect, an intentional detonation path, and a Lifespan long enough for the particles and audio to finish.

Choose how the explosion starts

Grenade or projectile

Assign the explosion prefab to the grenade or projectile’s Spawned Objects On Destruction list. Keep Explode On Enable disabled: the Version 3 projectile code spawns the prefab and then calls Explode with the projectile’s impact data and damage-source ownership. Enabling the option would detonate the same spawned object twice.

Use this path when the collision, timer, or trajectory object should decide when and where the explosion occurs. Follow Grenade for the trajectory setup.

Destructible barrel

Add Attribute Manager and Health to the barrel, then place the explosion prefab in Health > Death > Spawned Objects On Death. Keep Explode On Enable disabled here as well. Health explicitly calls Explode after it spawns a death object.

This path attributes the explosion to the barrel GameObject. If a chain reaction or score system must retain the original attacker as an IDamageSource, invoke the owner/source overload from the system that owns that attribution.

Direct or pooled effect

Enable Explode On Enable only when activating the explosion prefab is the complete trigger. Each enable performs the overlap query, runs the actions, plays audio, and schedules the object for pooled destruction after Lifespan. A script can instead leave the option disabled and call one of the public Explode overloads.

Tune reach, damage, and force

The outer Radius controls target detection and distance strength. Impact Damage Data > Impact Radius is separate data passed to damage and force processing; it does not expand the detection sphere.

Setting	Version 3 default	Use it for
Explode On Enable	Disabled	Detonate whenever this pooled object becomes active. Leave it disabled for projectile and Health death-object workflows.
Radius	5	Detect colliders and calculate a strength from the explosion center to each collider’s closest point.
Impact Damage Data > Damage Amount	10	Supply the base damage used by the default Simple Damage action.
Impact Damage Data > Impact Force	2	Supply the base force. Force is multiplied by distance strength.
Impact Damage Data > Impact Force Frames	1	Spread force handled by an IForceObject, such as a character, over this many frames.
Impact Damage Data > Impact Radius	0	Mark radius damage and select downstream radial-force behavior. This is not the Explosion detection radius.
Impact Damage Data > Layer Mask	All except Ignore Raycast, Water, SubCharacter, Overlay, and Visual Effect	Choose affected colliders and, when Line Of Sight is enabled, which colliders can block the test. Trigger colliders are always ignored.
Impact Damage Data > Damage Processor	None	Supply custom damage filtering or modification before a damage target receives it.
Line Of Sight	Disabled	Skip a target when an included-layer collider blocks the route from the explosion.
Lifespan	3 seconds	Return or destroy the explosion object after detonation.
Max Collision Count	100	Size the non-allocating collider buffer created in Awake. Multiple colliders can fill this buffer even though duplicate objects are filtered later.
Explosion Audio Clip Set	Empty	Play one configured explosion clip once per detonation.

Explosion always calculates a distance strength, which approaches one percent at the radius edge, and Simple Damage multiplies Impact Force by that strength before applying its direction. Damage does not fall off by default. To scale damage too, expand Impact Actions > Simple Damage and enable Scale Damage By Impact Strength.

Explosion Version 3.2.0 has no Upward Modifier field. The direction runs outward from the explosion center. Add a custom impact action or apply a separate force when an upward lift is part of the design.

The Impact State Name, Impact State Disable Timer, and Surface Impact values in Impact Damage Data are only consumed by actions that use them. The default group does not contain State Impact, so add that action if an explosion should activate a state. Configure and test Spawn Surface Effect when a per-target surface response is required; use the prefab’s Particle System for the main blast visual.

How it runs

When Explode runs, the component:

1. Searches Radius with a non-allocating overlap sphere using the Impact Damage Data layer mask and ignoring triggers.
2. Filters duplicate GameObjects and duplicate parent force objects so a multi-collider target is not processed repeatedly.
3. Applies the optional line-of-sight test.
4. Finds the collider’s closest point and calculates outward direction and distance strength.
5. Runs every enabled Impact Action for that target. By default, Simple Damage damages an IDamageTarget or pushes an IForceObject or non-kinematic Rigidbody, Spawn Surface Effect requests a Surface System response, and Impact Event notifies the source and target.
6. Plays Explosion Audio Clip Set once, then returns or destroys the explosion object through the object pool after Lifespan.

For objects with Health, damage consumes the configured Shield attribute before Health. That attribute shield is separate from an equipped item’s Shield Action: Absorb Explosions is disabled by default on Shield Action, so enable it when that item should intercept explosion damage.

Verify in Play Mode

1. Place one target close to the explosion, one near the radius edge, one outside it, and one behind included-layer cover.
2. Give damage targets Attribute Manager and Health, and give physics-only targets a non-kinematic Rigidbody.
3. Detonate once. Confirm the visual and audio play once and the explosion object leaves the scene after Lifespan.
4. Confirm the two in-range targets receive outward force and the outside target is unchanged.
5. With Scale Damage By Impact Strength disabled, confirm both damage targets receive the base damage. Enable it and confirm the edge target then receives less damage.
6. Enable Line Of Sight and confirm the covered target is protected. Check that both the target and cover layers are in Layer Mask.
7. Test a target with several colliders and a crowded scene. Each logical object should react once, and the Console should not report that Max Collision Count was reached.
8. Test the actual trigger path: grenade collision or timer, barrel death, direct activation, or script call. Confirm only one detonation occurs.
9. If the project uses multiplayer or saving, test through that integration’s authority and restoration flow rather than assuming the Explosion component synchronizes itself.

Troubleshooting

Symptom	Check	Fix
Nothing is damaged or pushed.	The target may be outside Radius, excluded by Layer Mask, represented only by a trigger, blocked by Line Of Sight, or missing Health/Rigidbody/IForceObject.	Include a non-trigger collider on an affected layer and add the receiver required for damage or force.
Edge targets take the same damage as close targets.	Simple Damage > Scale Damage By Impact Strength is disabled by default.	Enable it when damage, rather than only force, should fall off with distance.
A barrel or grenade detonates twice.	Explode On Enable may be enabled while Health or ProjectileBase also calls Explode.	Disable Explode On Enable and let the owning gameplay system make the call.
Cover does not block the explosion.	Line Of Sight may be disabled, or the cover layer may be absent from the same Impact Damage Data layer mask used by the test.	Enable the option and include both blockers and targets in Layer Mask.
Only some crowded targets react.	The overlap query may have filled Max Collision Count; the value counts colliders before duplicate targets are removed.	Increase it on the prefab before runtime and test again. Changing it after Awake does not resize the current buffer.
A Rigidbody receives no useful force.	It may be kinematic, use an excluded layer, or have zero Impact Force. Impact Radius may also be confused with the outer Radius.	Use a non-kinematic Rigidbody or IForceObject, set Impact Force, and use the outer Radius for detection.
An equipped shield does not block the blast.	Shield Action > Absorb Explosions defaults to disabled.	Enable it and verify the shield collider is the collider found by the explosion.
Particles or audio are cut off.	Lifespan may be shorter than the configured effect.	Increase Lifespan or shorten the Particle System and Audio Clip Set playback.
A surface effect appears at the wrong place or cannot identify the surface.	Version 3.2.0 builds explosion targets from an overlap collider, not a full raycast hit.	Keep the main blast on the prefab and use a tested custom impact action when exact per-surface placement is required.
Multiplayer clients produce duplicate or different explosions.	Explosion has no built-in network spawn, authority, or replication logic.	Let the multiplayer integration’s authority spawn and detonate the effect, then replicate the resulting gameplay state as required.

Related pages

• Object Manager creates the starting explosion prefab.
• Grenade configures a throwable object that spawns an explosion on destruction.
• Trajectory Object explains collision, timing, and spawned destruction objects shared by projectiles.
• Health configures damage, Shield attributes, death objects, and barrel-style destruction.
• Damage Processor customizes how structured damage reaches a target.
• Surface System maps impacts to effects.
• Audio explains Audio Clip Sets and shared audio playback.
• Events explains how to register and unregister UCC event listeners.

Developer reference

Detonation API and ownership

Explosion implements IDamageSource. Use an owner when damage attribution matters, and forward an existing IDamageSource when the explosion belongs to another attack:

using UnityEngine;
using Opsive.UltimateCharacterController.Objects;
using Opsive.UltimateCharacterController.Traits.Damage;

public class ExplosionTrigger : MonoBehaviour
{
    [SerializeField] private Explosion m_Explosion;

    public void Detonate(GameObject owner, IDamageSource ownerSource)
    {
        m_Explosion.Explode(m_Explosion.ImpactDamageData, owner, ownerSource);
    }
}

The public overloads are Explode(), Explode(GameObject owner), Explode(float damageAmount, float impactForce, int impactForceFrames, GameObject owner, IDamageSource ownerSource = null), and the virtual Explode(IImpactDamageData impactDamageData, GameObject owner, IDamageSource ownerSource = null). Useful public properties include ExplodeOnEnable, Radius, ImpactDamageData, ImpactActionGroup, LineOfSight, Lifespan, and ExplosionAudioClipSet. Max Collision Count is serialized but has no public property in the inspected Version 3.2.0 source.

The default Impact Event action sends OnObjectImpact with an ImpactCallbackContext to the explosion source and the impacted target. Damage applied through Health then produces the normal Health damage and death events.

Version 3.2.0 source boundaries

The inspected Version 3.2.0 implementation uses the LayerMask from an impactDamageData argument for target detection, but assigns the component’s serialized Impact Damage Data to the default action context. A projectile-supplied or temporary data object therefore does not necessarily replace the damage and force read by context-driven default actions. Keep the explosion prefab’s data aligned with the caller and recheck this behavior after upgrading.

The default Spawn Surface Effect receives overlap-derived collision data without a populated RaycastHit. Surface selection and placement that require raycast details need a custom action or an explicitly tested fallback.

Explosion contains no save serialization or multiplayer replication. Its scheduled pooled destruction is local runtime state. Persist the source object’s durable state, such as barrel Health, and let the chosen multiplayer integration own network spawning, authority, damage, and despawning.