OnItemFilter
OnItemFilter is called when a StorageContainer checks whether it will accept an item into its inventory, letting you approve or reject the move before the container's own rules are applied.
object OnItemFilter(Item item, StorageContainer storageContainer, int targetSlot, BasePlayer player)Parameters
| Parameter | Type | Description |
|---|---|---|
item | Item | The Item instance the container is deciding whether to accept. Check item.info.shortname, item.skin or item.info.itemid to decide. |
storageContainer | StorageContainer | The StorageContainer (box, locker, oven, turret, etc.) receiving the item. Use it to scope rules to a specific entity via net.ID or ShortPrefabName. |
targetSlot | int | The inventory slot index the item would land in, or -1 when the game has not picked a slot yet. |
player | BasePlayer | The BasePlayer who triggered the filter, usually the one moving or looting. May be null for non-player driven transfers. |
Return value
Return true to force acceptance or false to reject the item; the game converts a returned bool and skips its own filter check. Return null (or any non-bool) to let StorageContainer.ItemFilter continue with the container's normal category and slot logic.
How it works
This hook fires from StorageContainer.ItemFilter, the virtual method the game runs each time it evaluates whether an item may enter a container's inventory. Vanilla containers use it to enforce things like category restrictions (an oven only taking cooking items) or slot rules. Because the hook is invoked at the top of that method, your code runs before those built-in checks. Return a bool to decide the outcome outright; return null to fall through to the stock filtering logic.
The item tells you what is being moved, storageContainer which entity is receiving it, targetSlot the intended slot (-1 if unassigned) and player who is moving it. Declaring player as BasePlayer is correct and also lets Oxide skip the call when the argument is not a player instance, which happens on some automated transfers.
Typical uses: whitelisting items per container type, blocking specific skins (event items) from storage, or preventing a player from dropping items into a box they are not authorised on. The hook is cheap but fires on every container insert, so keep handlers free of Puts or heavy iteration.
Example plugin: Restrict certain containers to admin-only items
using System.Linq;
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;
namespace Oxide.Plugins
{
[Info("Slot Filtered Storage", "RustPluginGenerator", "1.0.0")]
[Description("Blocks configured item shortnames from being inserted into configured storage containers.")]
public class SlotFilteredStorage : RustPlugin
{
private PluginConfig config;
private class PluginConfig
{
[JsonProperty("Only apply to these container prefabs (empty = all)")]
public List<string> ContainerPrefabs = new List<string> { "box.wooden.large", "small_stash" };
[JsonProperty("Blocked item shortnames")]
public List<string> BlockedItems = new List<string> { "rocket.launcher", "explosive.satchel" };
[JsonProperty("Notify player when blocked")]
public bool NotifyPlayer = 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>
{
["Blocked"] = "You cannot store {0} in this container.",
["BlockedSkin"] = "That item is not allowed in this container."
}, this);
}
private string Msg(string key, string userId = null, params object[] args)
=> string.Format(lang.GetMessage(key, this, userId), args);
private object OnItemFilter(Item item, StorageContainer storageContainer, int targetSlot, BasePlayer player)
{
if (item?.info == null || storageContainer == null) return null;
if (config.ContainerPrefabs != null && config.ContainerPrefabs.Count > 0)
{
string prefab = storageContainer.ShortPrefabName;
if (string.IsNullOrEmpty(prefab) || !config.ContainerPrefabs.Contains(prefab))
return null;
}
if (config.BlockedItems == null || !config.BlockedItems.Contains(item.info.shortname))
return null;
if (config.NotifyPlayer && player != null && player.IsConnected)
player.ChatMessage(Msg("Blocked", player.UserIDString, item.info.displayName.english));
return false;
}
}
}The plugin defines a config list of container short prefabs and the item shortnames they should refuse. OnItemFilter looks up the container's ShortPrefabName, and when it is in the configured list it scans the blocked shortnames against item.info.shortname. A match returns false so the game treats the item as rejected; otherwise it returns null and the container's own category rules still apply. Player-facing feedback is sent via the lang message only when a connected player is present, so server-side transfers stay silent.
Common use cases
Item-specific storage lockdowns
Refuse rocket launchers or explosives in small boxes on PvE or raiding-restricted servers by returning false for those shortnames.
Event skin blocking
Reject items whose skin ID belongs to a limited event drop so they cannot be hoarded in ordinary storage containers.
Permission-gated containers
Return false when the moving player lacks a permission node for a special box, keeping restricted loot out of unauthorised hands.
Pitfalls
Null player on automated transfers
The
playerargument is not always set. Always guardplayerbefore callingUserIDStringor sending chat, otherwise you will throw on non-player inserts.Fires on every container insert
This hook runs frequently, including from items auto-moving after loot despawn. Keep the handler branch-light and never print debug output inside it.
Do not confuse with CanAcceptItem
CanAcceptItem covers a broader set of transfer paths with more context. OnItemFilter is scoped to StorageContainer.ItemFilter specifically, so a rule here only applies to containers that use that method.
Build a plugin with OnItemFilter
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 OnItemFilter
Generate