Skip to content
RustPluginGenerator
Weapon hookOxide + CarbonCompiled against Rust 2635.289.1 / Oxide 2.0.7839 ยท checked Oct 26, 2026

OnExplosiveDud

OnExplosiveDud is called when a timed explosive fail-rolls and the server is about to turn it into a dud instead of detonating it. Returning a non-null value cancels that conversion so the explosive goes through its normal detonation path.

Signature
object OnExplosiveDud(DudTimedExplosive dudTimedExplosive)

Parameters

Hook parameters
ParameterTypeDescription
dudTimedExplosiveDudTimedExplosiveThe DudTimedExplosive entity (timed explosive such as an F1 grenade or similar throwable) that the game has rolled as a dud and is about to convert into a non-exploding dud. Check its position, owner (OwnerID), skinID, or parent entity to decide what to do.

Return value

Return null to allow the game to convert the explosive into a dud (BecomeDud() runs). Return any non-null object to skip that conversion, so the explosive continues into its normal explode path and detonates.

How it works

The hook fires inside DudTimedExplosive.Explode, after the game has already passed the NPC-creator check and after UnityEngine.Random.Range(0f, 1f) has landed below the entity's dudChance. That means it only runs on the failure branch: the explosive was rolled to dud, and the call happens right before BecomeDud() would replace the live entity with a dud version. Non-NPC creators are the normal case; explosives spawned by scientists bypass the roll entirely and never reach this hook.

Use the dudTimedExplosive parameter to inspect what is about to dud: transform.position, OwnerID, skinID, GetParentEntity(), or ShortPrefabName all work and let you apply rules such as 'admins' grenades never dud' or 'no duds inside a raid base zone'. You cannot inspect the roll value itself; by the time you are called the decision is already made.

Returning a non-null object (any value, even true or 0) short-circuits the dud branch and falls through to the detonation path, so the explosive behaves as if the dud roll had passed. Returning null leaves the default: BecomeDud() runs. Because the hook fires at most once per explosive detonation, it is safe to do per-entity work here, but keep it cheap since explosives can fire in bursts.

Example plugin: Disable duds inside raid zones with a permission bypass

NoDudInRaidZone.cs
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;
using UnityEngine;

namespace Oxide.Plugins
{
    [Info("No Dud In Raid Zone", "RustPluginGenerator", "1.0.0")]
    [Description("Prevents timed explosives from becoming duds inside a configured zone for permitted players")]
    public class NoDudInRaidZone : RustPlugin
    {
        private const string PermBypass = "nodudinraidzone.bypass";

        private class PluginConfig
        {
            [JsonProperty("Zone center X")]
            public float CenterX = 0f;

            [JsonProperty("Zone center Z")]
            public float CenterZ = 0f;

            [JsonProperty("Zone radius (meters)")]
            public float Radius = 200f;

            [JsonProperty("Notify owner when a dud is suppressed")]
            public bool Notify = true;
        }

        private PluginConfig config;

        protected override void LoadDefaultConfig() => config = new PluginConfig();

        protected override void LoadConfig()
        {
            base.LoadConfig();
            try
            {
                config = Config.ReadObject<PluginConfig>();
                if (config == null) throw new Exception();
            }
            catch
            {
                PrintWarning("Configuration file is invalid, using defaults");
                LoadDefaultConfig();
            }
            SaveConfig();
        }

        protected override void SaveConfig() => Config.WriteObject(config);

        protected override void LoadDefaultMessages()
        {
            lang.RegisterMessages(new Dictionary<string, string>
            {
                ["DudSuppressed"] = "Your timed explosive was not dudded because you are inside the raid zone."
            }, this);
        }

        private string Msg(string key, string userId = null, params object[] args) =>
            string.Format(lang.GetMessage(key, this, userId), args);

        private void Init()
        {
            permission.RegisterPermission(PermBypass, this);
        }

        private object OnExplosiveDud(DudTimedExplosive dudTimedExplosive)
        {
            if (dudTimedExplosive == null) return null;

            Vector3 position = dudTimedExplosive.transform.position;
            float dx = position.x - config.CenterX;
            float dz = position.z - config.CenterZ;
            if ((dx * dx + dz * dz) > config.Radius * config.Radius) return null;

            ulong ownerId = dudTimedExplosive.OwnerID;
            if (ownerId == 0) return null;

            string ownerString = ownerId.ToString();
            BasePlayer owner = BasePlayer.FindByID(ownerId);
            if (!permission.UserHasPermission(ownerString, PermBypass) && (owner == null || !owner.IsAdmin))
                return null;

            if (config.Notify && owner != null)
                owner.ChatMessage(Msg("DudSuppressed", ownerString));

            return true;
        }
    }
}

The plugin keeps a configurable world radius (default centered near the map centre, but you can set any X/Z and range) inside which timed explosives never dud. On OnExplosiveDud it checks squared distance between the explosive's X/Z position and the configured centre; if the explosive is inside the zone and the owner has the nodudinraidzone.bypass permission (or is an admin), it returns true, which cancels the dud conversion. It also optionally sends the owner a language message so they know the dud was suppressed. Everything else falls through to null, preserving vanilla behaviour outside the zone.

Common use cases

  • Guarantee detonations during scheduled raid events

    Return non-null for explosives inside a configured zone or owner list so event raids or training exercises are not interrupted by a random dud.

  • Per-permission dud bypass

    Let VIPs or admins keep duds disabled entirely by checking OwnerID against a permission before returning a non-null value.

  • Debug or warn on dud

    Capture the position and prefab name of the explosive that dudded and send it to the owner as a chat message, then still allow the dud by returning null.

Pitfalls

  • NPC explosives skip the hook

    The dud roll is only reached for non-NPC creators; explosives created by scientists always call the base explode and never trigger OnExplosiveDud.

  • Any non-null return cancels the dud

    Returning false or 0 still counts as non-null and stops the dud conversion. Only return null if you want the vanilla dud to happen.

  • The roll is already decided

    You cannot inspect or influence the random roll itself; the hook is only the decision point, so a null return always means the vanilla dud occurs.

Build a plugin with OnExplosiveDud

Describe what should happen and get a compiled plugin that uses this hook.

Prompt: Guarantee detonations during scheduled raid events using the OnExplosiveDud hook, with a config file and a permission
Generate this plugin

Edit the prompt on the next screen. 2 free plugins a month, no card.

Last updated Oct 26, 2026. Found a mistake? Email support@rustplugingenerator.com.

Build a plugin with OnExplosiveDud

Generate