OnInventoryAmmoFind
OnInventoryAmmoFind is called when a player inventory searches for ammo of a given Rust.AmmoTypes category, before the game scans the main and belt containers.
object OnInventoryAmmoFind(PlayerInventory playerInventory, List<Item> ammoList, Rust.AmmoTypes ammoType)Parameters
| Parameter | Type | Description |
|---|---|---|
playerInventory | PlayerInventory | The PlayerInventory instance whose ammo search is running. Use it to read containerMain, containerBelt, or playerOwner to identify the player. |
ammoList | List<Item> | The list the game is about to fill with matching ammo items. If you add items yourself and return non-null, the game skips its own search. |
ammoType | Rust.AmmoTypes | The Rust.AmmoTypes value the caller is looking for (e.g. Pistol, Rifle, Shotgun), so you can filter by weapon category. |
Return value
Return null to let the game run its normal containerMain and containerBelt searches. Return any non-null object to skip those searches entirely; the list then contains only what you added.
How it works
The hook fires inside PlayerInventory.FindAmmo(List<Item>, AmmoTypes), which the game calls when it needs a list of usable ammo for a weapon (for example when a held weapon reloads or picks its ammo type). The game then calls containerMain.FindAmmo and containerBelt.FindAmmo to populate the list.
Use playerInventory to identify the player via playerOwner and to inspect the containers yourself. ammoList is the collection the caller will read afterwards, so anything you add there becomes visible to the game. ammoType is the category being requested, matching values such as Rifle, Pistol, or Shotgun in Rust.AmmoTypes.
Returning null lets the normal scan run. Returning any non-null value stops the game from calling the container searches at all, so the list only contains what you put in it. This is useful for restricting which ammo a player may use (for example, disallowing certain ammo types for a weapon or enforcing a custom item).
Because the hook fires on reload and ammo lookup, keep your handler fast: no chat messages, no logging, no heavy LINQ over full inventories on every call.
Example plugin: Limit which ammo types a player can load
using System.Linq;
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;
namespace Oxide.Plugins
{
[Info("Ammo Type Restrictor", "RustPluginGenerator", "1.0.0")]
[Description("Blocks configured ammo shortnames from being found for a given ammo type category.")]
public class AmmoTypeRestrictor : RustPlugin
{
private const string PermBypass = "ammotyperestrictor.bypass";
private PluginConfig config;
private readonly Dictionary<Rust.AmmoTypes, HashSet<string>> blockedByType = new Dictionary<Rust.AmmoTypes, HashSet<string>>();
private class PluginConfig
{
[JsonProperty("Blocked ammo by type (Rust.AmmoTypes name -> shortnames)")]
public Dictionary<string, List<string>> Blocked = new Dictionary<string, List<string>>
{
["Rifle"] = new List<string> { "ammo.rifle.explosive" },
["Pistol"] = new List<string> { "ammo.pistol.fire" }
};
}
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 Init()
{
permission.RegisterPermission(PermBypass, this);
blockedByType.Clear();
foreach (var entry in config.Blocked)
{
Rust.AmmoTypes type;
if (!Enum.TryParse(entry.Key, true, out type)) continue;
var set = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
if (entry.Value != null)
{
foreach (var shortname in entry.Value)
{
if (!string.IsNullOrEmpty(shortname)) set.Add(shortname);
}
}
blockedByType[type] = set;
}
}
private object OnInventoryAmmoFind(PlayerInventory playerInventory, List<Item> ammoList, Rust.AmmoTypes ammoType)
{
if (playerInventory == null || ammoList == null) return null;
HashSet<string> blocked;
if (!blockedByType.TryGetValue(ammoType, out blocked) || blocked.Count == 0) return null;
var player = playerInventory.containerMain?.playerOwner
?? playerInventory.containerBelt?.playerOwner
?? playerInventory.containerWear?.playerOwner;
if (player != null && permission.UserHasPermission(player.UserIDString, PermBypass)) return null;
ammoList.RemoveAll(item => item?.info == null || blocked.Contains(item.info.shortname));
return null;
}
}
}The plugin keeps a config list of shortnames that are forbidden for each requested Rust.AmmoTypes category. When OnInventoryAmmoFind fires, it looks up the owning player through containerMain, containerBelt or containerWear, checks a permission grant, and removes forbidden items from the provided ammo list. Entries with a missing item or item info are removed as well. Returning null lets the normal container scan continue, so the player still gets their other ammo; the restricted shortnames are simply gone from the resulting list. If every eligible item is blocked, the weapon finds nothing and the player cannot reload that category. Admins skip the check when they have the bypass permission.
Common use cases
Ban specific ammo types per category
Block shortnames such as explosive or incendiary rounds from a given Rust.AmmoTypes category by removing them from the list the game builds.
Grant ammo via a custom container
Return a non-null value after adding items from a virtual inventory (e.g. a plugin-managed reserve) so the weapon reloads from your own source.
VIP-only ammo
Check a permission and strip premium ammo for players without the grant while leaving standard rounds intact.
Pitfalls
The list may already contain items
The hook fires before the container scan, so treat the list as possibly empty but never assume it is; filter with RemoveAll rather than Clear unless you intend to wipe everything the caller passed in.
Non-null return skips the game scan
Returning true or any object means the main and belt containers are never searched. Only return a value if you populated the list yourself, otherwise players will be unable to reload.
Hook fires frequently
FindAmmo is called on weapon reload and ammo lookups, so keep the handler free of chat output and logging; cache shortname sets at plugin load instead of building them per call.
Build a plugin with OnInventoryAmmoFind
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 OnInventoryAmmoFind
Generate