Grenade

Export

A Grenade gives a Throwable Action a timed, physical explosive that can begin cooking while it is still in the character’s hand. Use it when the object should follow a trajectory, bounce or settle, and spawn a separate Explosion when its fuse expires.

Before you begin

  • Prepare a visible grenade model and a separate Explosion prefab for the final area effect.
  • Configure a Throwable Action with an enabled Thrower, Ammo, Projectile, and Re-Equipper module.
  • Decide whether touching a target should also cause an immediate impact result, or whether all damage should come from the final Explosion.
  • Use a solid Sphere, Capsule, or Box Collider on the grenade root. The trajectory casts ignore trigger colliders.

Build the grenade prefab

  1. Open Tools > Opsive > Ultimate Character Controller > Object Manager.
  2. In Object Builder, enter a Name, set Object Type to Grenade, and assign the visible model to GameObject.
  3. Select Build Object, save the prefab under the project’s Assets folder, and open the generated prefab.
  4. Confirm the root has Rigidbody, Capsule Collider, and Grenade components. Object Manager disables Destroy On Collision for this object type so the generated grenade can keep moving after a hit.
  5. Resize the Capsule Collider to the model, or replace it with a solid Sphere Collider when that better matches a round grenade. The Grenade component makes the Rigidbody kinematic and disables Rigidbody gravity at runtime; Trajectory Object owns the arc.
  6. In the Grenade component’s trajectory settings, keep Initialize On Enable disabled when the Throwable Action will launch the object. Collision Mode starts as Reflect, so the generated object bounces.
  7. Under Destruction, keep Destroy On Collision disabled and Destruction Delay at 0 for a fuse-only result. Add the Explosion prefab to Spawned Objects On Destruction and leave its Probability at 1 when every cooked grenade should explode.
  8. Under the impact settings, configure Default Impact Damage Data even when the Explosion owns the visible damage result. Disable Internal Impact if a bounce should not run the Grenade’s own Impact Action Group.

Connect the Throwable Action

  1. On the Character Item’s Throwable Action, assign the prefab to Spawn Projectile > Thrown Object.
  2. Add Throwable Grenade to the action’s Extra module group. The released Version 3 Item Manager recipe does not add this module automatically.
  3. On the Grenade prefab, set Lifespan. Its released Version 3 default is 5 seconds.
  4. For a removable pin, make the pin a child Transform of the grenade and assign it to Pin. A root pin with no parent cannot be detached and restored by the built-in component.
  5. In Throwable Grenade, leave Animate Pin Removal enabled when the animation shows the pin being pulled. Assign Pin Attachment Location for each enabled perspective, then synchronize Remove Pin Event with OnAnimatorItemRemovePin. The trigger waits for that animation event by default; its stored Duration is 0.4 seconds when event waiting is disabled.
  6. Match the Throwable Action’s Use Event to the release frame. The fuse starts when item use starts, before this release event, so time spent holding the cooked grenade counts toward Lifespan.

The held object and the launched object are the same pooled Grenade instance. Do not add a separate timer to the Throwable Action unless it deliberately replaces the built-in cooking flow.

Key choices

Goal Configure Result
Bounce until the fuse expires Collision Mode Reflect, Destroy On Collision disabled, Destruction Delay 0 Contact changes the trajectory but does not schedule destruction.
Stop on the first surface, then wait for the fuse Collision Mode Collide, Destroy On Collision disabled, and include every intended stop surface in Sticky Layers The object stops and attaches at the hit while the cook event remains active. A uniform-scale target outside Sticky Layers forces destruction.
Explode immediately on contact Collision Mode Collide and Destroy On Collision enabled The first valid collision destroys the Grenade without waiting for the remaining fuse.
Damage only through the final blast Disable Internal Impact and configure the spawned Explosion Bounces provide trajectory and surface feedback without applying the Grenade’s collision Impact Action Group.
Damage on contact and at the final blast Keep Internal Impact enabled, configure its Impact Action Group, and configure the Explosion separately Each path owns an explicit result; test for unintended double damage near the final contact.
Keep collider-based interactions after a bounce Disable Disable Collider On Impact The physical Collider remains enabled after the first impact. The released Version 3 default disables it on impact even when the Grenade continues moving.

Impact Layers decides which colliders the trajectory can hit. Sticky Layers matters only in Collide mode. A positive Destruction Delay schedules destruction after the first collision even if Destroy On Collision is disabled, so it is not an extra fuse duration.

How it runs

  1. Spawn Projectile takes a Grenade from the pool, initializes its projectile data, attaches it to the held item, and keeps trajectory movement disabled.
  2. When the Use ability starts successfully, Throwable Grenade calls StartCooking. This records the character and Throwable Action as the damage-owner chain and schedules destruction after Lifespan.
  3. If pin removal is animated, the selected animation-event or duration mode moves the pin to Pin Attachment Location. Enabling a reused Grenade restores the pin to its original parent and local pose.
  4. At Use Event, the Projectile Thrower releases and initializes the trajectory. Hits run shared collision feedback and can run the Grenade’s own impact path, while the selected collision mode decides whether motion stops, reflects, or continues.
  5. When the cook event expires, the Grenade temporarily moves to Ignore Raycast so its own spawned Explosion does not detect it, then destructs at its current position.
  6. Destruction invokes the configured result, passes the Grenade’s impact and ownership data to a spawned Explosion, and returns the Grenade through the object or network pool.

Editor checkpoint

Before Play Mode, confirm that:

  • the prefab root has Grenade, Rigidbody, and one supported solid Collider;
  • Initialize On Enable is disabled and Mass plus Start Velocity Multiplier are positive;
  • Impact Layers, Collision Mode, Destroy On Collision, and Destruction Delay describe one coherent contact result;
  • Default Impact Damage Data is populated and Internal Impact matches the intended collision damage;
  • Spawned Objects On Destruction contains the Explosion with Probability 1 for a guaranteed blast;
  • the Throwable Action’s Spawn Projectile > Thrown Object references this prefab;
  • Throwable Grenade is enabled in the Extra group; and
  • an assigned Pin has an original parent, a perspective-specific attachment location, and either a matching animation event or duration mode.

Verify in Play Mode

  1. Start using the grenade and keep holding it. Confirm the pin moves at the intended frame and the grenade destructs in the hand after Lifespan.
  2. Start again and release quickly. Confirm the object leaves the hand at Use Event, follows the expected arc, and keeps the remaining fuse time rather than restarting it.
  3. Throw against an included surface. Confirm Reflect bounces or Collide stops as configured, and confirm a fuse-only grenade does not destruct on first contact.
  4. Throw against an excluded layer. Confirm the trajectory does not report the contact or run the collision impact path.
  5. Let the fuse expire after a bounce. Confirm one Explosion appears at the Grenade’s current position, attributes damage to the character/item owner chain, and the Grenade returns to its pool.
  6. Reuse the prefab several times. Confirm the pin, collider, visible model, fuse, ownership, and destruction result reset on every throw.

Troubleshooting and released-Version-3 limitations

Symptom Check Fix
The Grenade flies forever Throwable Grenade is missing or no project code calls StartCooking. Enabling or launching a Grenade does not start its fuse. Add Throwable Grenade to the Extra group, or call StartCooking from the system that deliberately owns activation.
The use starts with a null-reference error Throwable Grenade is enabled but Thrown Object is not a Grenade prefab. Assign a prefab with the Grenade component, or remove the grenade-specific Extra module.
The Grenade explodes on its first bounce Destroy On Collision is enabled or Destruction Delay is greater than 0. Disable collision destruction and set the delay to 0 for a fuse-only grenade.
Reflect changes to Collide and a warning appears Destroy On Collision is enabled with a non-Collide mode. Disable collision destruction for a bouncing grenade. ProjectileBase forces Collide for that conflicting combination during Awake.
The pin never moves The Grenade’s Pin has no original parent, the attachment location is empty, or event waiting is enabled but OnAnimatorItemRemovePin never occurs. Keep the pin as a child, assign Pin Attachment Location, then supply the animation event or disable event waiting and use the configured Duration.
The first bounce stops later collider-based interactions Disable Collider On Impact remains at its enabled default. Disable that field when the Collider must remain active after contact, then retest the intended collision and pooling behavior.
Bounces deal damage when only the blast should Internal Impact and its Impact Action Group are enabled. Disable Internal Impact and keep damage on the spawned Explosion.
The Console reports missing impact damage data Default Impact Damage Data is not populated before the Throwable modules initialize the Grenade. Configure the Grenade’s default impact data, including its layers and damage ownership choices.
Canceling a cooked use leaves a live fuse Released Version 3 starts cooking at the beginning of use, but the built-in cancellation path does not cancel that scheduled Grenade event. Prevent interruption after cooking starts, or add project-owned cancellation that returns or safely destructs the pre-spawned object.
No Explosion appears at the end of the fuse Spawned Objects On Destruction has no valid object, its probability is below 1, or the Explosion prefab is misconfigured. Assign the tested Explosion prefab, use probability 1 for a guaranteed result, and verify that prefab separately.

Saving, pooling, and multiplayer

The prefab stores its trajectory, fuse, pin, impact, and destruction configuration. The remaining cook time, current flight, detached pin, contact state, and active owner are runtime state. Around a save/load boundary, preserve the gameplay consequence you need and deliberately respawn or discard an active Grenade rather than expecting its scheduled fuse and trajectory to resume.

Grenade destruction returns through ObjectPoolBase. With the supported multiplayer integration active, destruction and spawned results use the network path and only the server is allowed to explode the ProjectileBase. Configure and test the prefab through that integration; the base component does not by itself synchronize a custom save or networking policy.

  • Trajectory Object explains shared movement, collision, settling, and preview settings.
  • Throwable Action configures spawning, cooking, release timing, inventory use, and re-equipping.
  • Explosion configures the area damage and effects spawned at destruction.
  • Projectile is the corresponding one-hit or lifespan-based moving object.
  • Object Pool explains reusable object ownership.
  • Events explains project-level event listeners.

Developer reference

Grenade derives from ProjectileBase. Its public members are Lifespan, Pin, StartCooking(GameObject originator, IDamageSource ownerSource = null), and DetachAttachPin(Transform attachTransform). ProjectileBase exposes the C# OnImpact and OnDestruct events and notifies an IProjectileOwner through OnProjectileImpact and OnProjectileDestruct.

StartCooking schedules its fuse through the Opsive Scheduler; OnDisable cancels that event. DetachAttachPin(null) restores the cached original parent, position, and rotation. Subscribe and unsubscribe listeners with the pooled object’s enable/disable lifecycle, and use Events for project-level Event System callbacks.