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

OnFireBallDamage

OnFireBallDamage is called by FireBall.DoRadialDamage right after the Heat damage is written into HitInfo and before the victim's OnAttacked receives it.

Signature
void OnFireBallDamage(FireBall fireBall, BaseCombatEntity item, HitInfo hitInfo)

Parameters

Hook parameters
ParameterTypeDescription
fireBallFireBallThe FireBall entity that is dealing the radial damage. Use it for its position and to identify which throwable caused the hit.
itemBaseCombatEntityThe BaseCombatEntity receiving the fire damage. Cast it to a more specific type such as BasePlayer or BuildingBlock when you need those members.
hitInfoHitInfoThe HitInfo built by the fireball. Its damageTypes are already set to Heat and its hit position is the victim's position, so you can read or change the damage before it is applied.

Return value

The return value is ignored. The hook cannot cancel item.OnAttacked(hitInfo), so return type must be void and the damage is applied unless you change hitInfo itself.

How it works

This hook fires inside FireBall.DoRadialDamage, once for each entity the fireball affects. The burst of damage types has already been scaled (including the siege weapon multiplier) and hitInfo.damageTypes is set to DamageType.Heat, with HitPositionWorld and PointEnd pointing at the victim. The method then calls item.OnAttacked(hitInfo), which is where armor, health and death handling happen.

Because the call happens before OnAttacked, mutating hitInfo here changes the damage. Use hitInfo.damageTypes.ScaleAll(multiplier), Scale(Rust.DamageType.Heat, x) or Set to zero it out. You can also set flags or tag the FireBall to track it.

The hook fires once per affected entity, so a single fireball hitting several players and blocks calls it multiple times. Declaring item as BasePlayer narrows the hook to player victims only, since Oxide skips calls where the argument is not an instance of the parameter type. Avoid heavy work or chat output here: on busy servers a fireball can trigger several calls in one frame.

Example plugin: Scale fireball damage against players

FireBallDamageScaler.cs
using System.Linq;
using System;
using Newtonsoft.Json;
using UnityEngine;

namespace Oxide.Plugins
{
    [Info("Fire Ball Damage Scaler", "RustPluginGenerator", "1.0.0")]
    [Description("Scales fireball heat damage against players using a configurable multiplier.")]
    public class FireBallDamageScaler : RustPlugin
    {
        private PluginConfig config;

        private class PluginConfig
        {
            [JsonProperty("Damage multiplier")]
            public float DamageMultiplier = 0.5f;
        }

        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);

        private void OnFireBallDamage(FireBall fireBall, BaseCombatEntity item, HitInfo hitInfo)
        {
            if (hitInfo == null || hitInfo.damageTypes == null) return;

            var player = item as BasePlayer;
            if (player == null || player.IsNpc) return;

            float multiplier = Mathf.Max(0f, config.DamageMultiplier);
            hitInfo.damageTypes.ScaleAll(multiplier);
        }
    }
}

The plugin reads a DamageMultiplier from its config and, for every player hit by a fireball, scales the Heat damage in hitInfo before OnAttacked runs. A value of 0.0 disables fireball damage to players entirely, 1.0 keeps vanilla behavior. Blocks and other entities are untouched because the code checks item as BasePlayer and returns early otherwise. The example registers no permissions or commands, keeps no timers and never logs inside the hook, so it is safe under load. Config reload creates a fresh multiplier on the next config load.

Common use cases

  • Reduce fireball damage against players

    Scale hitInfo.damageTypes down for BasePlayer victims to make thrown fireballs less lethal in PvP without removing them.

  • Protect building blocks from fireballs

    Check item as BuildingBlock and zero out the Heat damage for blocks you want to shield, for example around safe zones.

  • Log fireball hits for staff review

    Record the thrower and victim ids into a data file so admins can audit who is spamming fireballs at bases.

Pitfalls

  • Hook fires before OnAttacked

    Damage is only modified if you change hitInfo before returning; return values do nothing, so a full block requires scaling the damage list to zero.

  • Multiple calls per fireball

    DoRadialDamage loops over every affected entity, so one throw can call the hook several times. Do not increment counters or send messages without deduplication.

  • Narrowing to BasePlayer skips blocks

    If you declare the second parameter as BasePlayer, Oxide will not invoke the hook for blocks or other entities, which is fine for PvP tweaks but wrong if you also want to shield structures.

Build a plugin with OnFireBallDamage

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

Prompt: Reduce fireball damage against players using the OnFireBallDamage 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 OnFireBallDamage

Generate