OnLootItem
OnLootItem is called when a player starts looting an item that has its own container, such as a backpack, dropped bag or source item with contents, right as the game prepares the loot panel.
void OnLootItem(BasePlayer player, Item item)Parameters
| Parameter | Type | Description |
|---|---|---|
player | BasePlayer | The BasePlayer who is opening the loot panel. Read it for permissions, identity, position or team checks before allowing the item to be looted. |
item | Item | The Item that will be placed into the player's loot panel. Its info, amount, skin and contents describe what is about to be opened. |
Return value
The hook's return value is ignored by the patched method. The loot panel opens regardless of what you return, so this hook cannot block looting.
How it works
The hook fires inside PlayerLoot.StartLootingItem, the method the server calls when a player opens the loot panel for an item that carries its own ItemContainer contents. It runs after the game has attached the dirty callback and set the internal itemSource/entitySource, and before the panel is marked dirty and networked to the client. Typical triggers are opening a dropped loot bag, a backpack item, or any other container item the player owns or is allowed to access.
player is the looter; use it for permission checks, distance, team or building-authority rules. item is the item whose contents are about to be shown, so item.info.shortname, item.skin, and item.contents are the useful fields. Because the panel setup has already started when the hook runs, this hook is not a clean place to cancel the open — use CanLootEntity for that. It is a good place to observe, log or react to the moment of looting (for example first-loot rewards or statistics). You do not need a more specific parameter type since both arguments already arrive as BasePlayer and Item.
Example plugin: First-loot reward for backpacks
using System.Linq;
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;
using UnityEngine;
namespace Oxide.Plugins
{
[Info("First Loot Reward", "RustPluginGenerator", "1.0.0")]
[Description("Grants a one-time scrap reward the first time a player loots a configured container item.")]
public class FirstLootReward : RustPlugin
{
private const string PermUse = "firstlootreward.use";
private PluginConfig config;
private StoredData data;
private class PluginConfig
{
[JsonProperty("Reward amount")]
public int RewardAmount = 50;
[JsonProperty("Reward item shortname")]
public string RewardShortname = "scrap";
[JsonProperty("Tracked container shortnames")]
public List<string> TrackedShortnames = new List<string> { "backpack" };
}
private class StoredData
{
public HashSet<string> Rewarded = new HashSet<string>();
}
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>
{
["Reward"] = "First loot bonus: you received {0}x {1}.",
["NoPermission"] = "You do not have permission to receive loot bonuses."
}, this);
}
private void Init()
{
permission.RegisterPermission(PermUse, this);
data = Interface.Oxide.DataFileSystem.ReadObject<StoredData>("FirstLootReward") ?? new StoredData();
}
private void OnLootItem(BasePlayer player, Item item)
{
if (player == null || item == null || item.info == null) return;
if (!permission.UserHasPermission(player.UserIDString, PermUse)) return;
if (!config.TrackedShortnames.Contains(item.info.shortname)) return;
string key = player.UserIDString + ":" + item.info.shortname;
if (data.Rewarded.Contains(key)) return;
data.Rewarded.Add(key);
Interface.Oxide.DataFileSystem.WriteObject("FirstLootReward", data);
Item reward = ItemManager.CreateByName(config.RewardShortname, config.RewardAmount);
if (reward == null) return;
player.GiveItem(reward);
player.ChatMessage(string.Format(lang.GetMessage("Reward", this, player.UserIDString), config.RewardAmount, item.info.displayName.english));
}
private void Unload()
{
if (data != null)
Interface.Oxide.DataFileSystem.WriteObject("FirstLootReward", data);
}
}
}The plugin listens for OnLootItem and checks which item the player just opened using item.info.shortname. It stores per-player loot counts in an Oxide data file under oxide/data and only fires a reward the first time a player opens a container item of a configured shortname. On that first open it grants a configurable scrap amount with ItemManager.CreateByName and GiveItem, and sends a localized chat notice back through the language system. A short cooldown-style guard prevents duplicate rewards from the same panel session, and the data file is written on unload.
Common use cases
One-time reward for opening a loot bag
Grant scrap or another item the first time a player loots a specific container shortname, using persisted data so it does not repeat.
Loot statistics tracking
Increment a per-player counter every time they open a container item and later expose it with a chat command or leaderboard.
Anti-abuse alerts for admins
Note which players are opening containers at suspicious rates or in disallowed areas and notify online admins through chat instead of blocking the loot.
Pitfalls
This hook cannot block looting
The return value is discarded and the panel has already been prepared, so use
CanLootEntityif you need to prevent opening the container.Fires for every container item open
A player opening several items triggers the hook each time, so always key your reward logic on persisted identifiers rather than assuming a single fire per session.
Null item contents
Not every item you see will have meaningful contents; treat
item.contentsas possibly null and checkitem.infobefore reading shortnames.
Build a plugin with OnLootItem
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 OnLootItem
Generate