OnBonusItemDrop
OnBonusItemDrop is called when a looter's scrap-yield bonus creates bonus scrap from a loot container, before that scrap is dropped into the world.
object OnBonusItemDrop(Item item, BasePlayer player, ItemContainer container)Parameters
| Parameter | Type | Description |
|---|---|---|
item | Item | The bonus scrap item that LootContainer.DropBonusItems just created. It is not yet dropped or parented to anything when the hook fires. |
player | BasePlayer | The BasePlayer looting the container, used for the scrap yield modifier. Null-check it; the hook is normally reached from an active looter. |
container | ItemContainer | The ItemContainer of the lootable entity (for example a crate or corpse) that the player is looting. It is the source container, not the destination. |
Return value
Returning null (or nothing) lets the game drop the bonus scrap and fire OnBonusItemDropped. Returning any non-null object cancels the whole drop branch, so no scrap enters the world and OnBonusItemDropped is not called.
How it works
The hook fires inside LootContainer.DropBonusItems. Rust computes a scrap amount from the player's Scrap_Yield modifier, creates a scrap item with ItemManager.Create, and calls this hook before dropping it near the container. If the hook returns a non-null value, the drop is skipped entirely: the item is never placed in the world and the follow-up OnBonusItemDropped hook is not called.
The item parameter is the freshly created scrap stack, useful for changing its amount, skin or condition before it exists as a world object. player is the looter and lets you check permissions, teams or group membership. container identifies which crate or corpse produced the bonus.
Returning null keeps vanilla behavior. Since this is a void method patched with a non-null check, only null lets the original drop run; any object you return suppresses it. Declaring the parameters exactly as shown is the safe option. This hook only covers bonus scrap from loot containers, not scrap from recycling, quarry output or manual drops.
Example plugin: Scale bonus scrap by permission and drop a notice
using UnityEngine;
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;
namespace Oxide.Plugins
{
[Info("Bonus Scrap Control", "RustPluginGenerator", "1.0.0")]
[Description("Scales bonus scrap from loot containers for players with a VIP permission.")]
public class BonusScrapControl : RustPlugin
{
private const string PermVip = "bonusscrapcontrol.vip";
private PluginConfig config;
private class PluginConfig
{
[JsonProperty("VIP scrap multiplier")]
public float VipMultiplier { get; set; } = 2f;
[JsonProperty("Maximum scrap per bonus drop")]
public int MaxAmount { get; set; } = 500;
[JsonProperty("Notify player about bonus")]
public bool Notify { get; set; } = true;
}
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>
{
["BonusScrap"] = "Your loot bonus gave you {0} scrap.",
["BonusSuppressed"] = "Bonus scrap was suppressed for this container."
}, 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(PermVip, this);
}
private object OnBonusItemDrop(Item item, BasePlayer player, ItemContainer container)
{
if (item == null || player == null || container == null) return null;
if (player.IsNpc || !player.IsConnected) return null;
if (!permission.UserHasPermission(player.UserIDString, PermVip)) return null;
int scaled = UnityEngine.Mathf.RoundToInt(item.amount * config.VipMultiplier);
if (scaled > config.MaxAmount) scaled = config.MaxAmount;
if (scaled < 1) scaled = 1;
item.amount = scaled;
if (config.Notify)
{
player.ChatMessage(Msg("BonusScrap", player.UserIDString, scaled));
}
return null;
}
}
}The plugin reads a multiplier config and a permission for VIP players. Inside OnBonusItemDrop it multiplies the scrap amount and clamps it to a maximum, then allows the normal drop by returning null. For players below the multiplier or without permission it leaves the amount alone. The player receives a short chat message about the boosted scrap, sent through the language file so it can be translated. Because the hook fires only when a loot container grants bonus scrap, messages appear rarely and do not spam chat. Admins can reload the config without restarting the server.
Common use cases
Boost bonus scrap for donors
Multiply the scrap amount for players holding a VIP permission to reward them for looting crates.
Cap bonus scrap on high-rate servers
Clamp the amount to a configured maximum so stacked modifiers do not flood the economy.
Disable bonus scrap on selected containers
Return a non-null value when the source container belongs to a container type you do not want to reward.
Pitfalls
Any non-null return cancels the drop
The return value is only checked for null. Returning
true,falseor any object suppresses the scrap even though a boolean might look like a flag.Changing amount after the hook has no effect
Set
item.amountinside the hook; once the item is dropped as a DroppedItem the hook has already finished.Only loot-container scrap is covered
Scrap from recycling, quarries or other sources does not pass through this hook, so a multiplier here alone will not affect those paths.
Build a plugin with OnBonusItemDrop
Describe what should happen and get a compiled plugin that uses this hook.
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 OnBonusItemDrop
Generate