OnInventoryAmmoItemFind
OnInventoryAmmoItemFind is called when a weapon asks the player's inventory for an ammo or fuel item, before the default lookup runs. Returning an Item replaces the result; returning null lets vanilla search run.
object OnInventoryAmmoItemFind(PlayerInventory inventory, ItemDefinition fuelType)Parameters
| Parameter | Type | Description |
|---|---|---|
inventory | PlayerInventory | The PlayerInventory that ammo is being searched in. Null-check it; its containerMain and containerBelt are the usual places ammo lives. |
fuelType | ItemDefinition | The ItemDefinition being searched for. From Chainsaw.GetAmmo and FlameThrower.GetAmmo this is the weapon's fuel/ammo definition (low grade fuel); from PlayerInventory.FindAmmo it can be that definition or an AmmoTypes instance depending on the overload that fired. |
Return value
Return an Item to make that item the result of the lookup, skipping the weapon's or inventory's own FindItemByItemName / FindAmmo call. Return null (or any non-Item value) to let vanilla search the player's main container as usual.
How it works
The hook fires from three patched locations. Chainsaw.GetAmmo and FlameThrower.GetAmmo call it when the held tool needs its next unit of fuel, passing the owner's PlayerInventory and the fuel ItemDefinition. PlayerInventory.FindAmmo(AmmoTypes) calls it whenever vanilla code looks up ammo by category, which covers most firearms and turrets that draw from a player inventory.
Use inventory to inspect what the player actually carries (containerMain, containerBelt, itemList) and fuelType to know what is being requested. You can return any Item you like, including one from another container, from storage you track yourself, or a freshly created item. If you only want to observe or veto, return null.
The two GetAmmo sites pass an ItemDefinition, while FindAmmo passes Rust.AmmoTypes. Because Oxide matches parameters by type, declare ItemDefinition and you receive only the Chainsaw and FlameThrower calls; declare AmmoTypes and you receive only the FindAmmo calls. This is why the same hook name has two documented signatures.
TheGetAmmo paths are reached from the tool's tick and firing logic, so this hook can run very often while a flamethrower or chainsaw is in use. Keep the body cheap and never log inside it.
Other signatures
Oxide also calls OnInventoryAmmoItemFind from other places in the game with these parameter types. Declare the overload you need, or several:
object OnInventoryAmmoItemFind(PlayerInventory playerInventory, Rust.AmmoTypes ammoType)
Example plugin: Make flamethrowers and chainsaws draw fuel from nearby configured containers
using System.Linq;
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;
using UnityEngine;
namespace Oxide.Plugins
{
[Info("Fuel Can Ammo Source", "RustPluginGenerator", "1.0.0")]
[Description("Lets chainsaws and flamethrowers draw fuel from nearby configured storage containers.")]
public class FuelCanAmmoSource : RustPlugin
{
private const string PermUse = "fuelcanammosource.use";
private class PluginConfig
{
[JsonProperty("Search radius (metres)")]
public float SearchRadius = 5f;
[JsonProperty("Container short prefabs")]
public List<string> ContainerPrefabs = new List<string>
{
"box.wooden.large",
"woodbox_deployed",
"fuelstorage"
};
}
private PluginConfig config;
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(PermUse, this);
}
private object OnInventoryAmmoItemFind(PlayerInventory inventory, ItemDefinition fuelType)
{
if (inventory == null || fuelType == null) return null;
BasePlayer owner = inventory.containerMain != null ? inventory.containerMain.playerOwner : null;
if (owner == null || !permission.UserHasPermission(owner.UserIDString, PermUse)) return null;
List<BaseEntity> found = new List<BaseEntity>();
Vis.Entities(owner.transform.position, config.SearchRadius, found);
foreach (BaseEntity entity in found)
{
StorageContainer container = entity as StorageContainer;
if (container == null || container.inventory == null) continue;
if (!config.ContainerPrefabs.Contains(container.ShortPrefabName)) continue;
foreach (Item item in container.inventory.itemList)
{
if (item == null || item.info == null) continue;
if (item.info.itemid != fuelType.itemid) continue;
return item;
}
}
return null;
}
}
}The plugin keeps a configurable list of container short prefabs that count as a fuel source. When a tool asks for fuel, the OnInventoryAmmoItemFind hook fires with the owner's PlayerInventory and the requested ItemDefinition. The plugin resolves the player from inventory.containerMain.playerOwner and checks the fuelcanammosource.use permission. It then scans entities within the configured radius and returns the first item in a matching container whose item id equals the requested fuel type. Returning null when nothing is found leaves vanilla behaviour intact.
Common use cases
Fuel from external storage
Let flamethrowers and chainsaws pull low grade fuel from a nearby box, locker or fuel tank instead of the player's inventory, which is handy for base maintenance roles.
Restricted fuel types
Return only items that pass a whitelist check so players cannot feed a tool from a stack you consider off-limits, or swap in a custom skin-tagged fuel item.
Track consumption
Record which item and amount is returned so you can bill players, award points, or log fuel usage without patching the weapon itself.
Pitfalls
Two different parameter types
GetAmmopasses anItemDefinitionandFindAmmopassesRust.AmmoTypes. If you declareItemDefinition, firearm ammo lookups never reach your method; if you need both, write two separate hook methods.Very hot call path
The Chainsaw and FlameThrower call this from their attack/tick logic, so it can fire many times per second while a player holds the trigger. Avoid LINQ, entity queries per call, or any logging.
Returning a removed or foreign item
The returned
Itemis consumed by the weapon. Do not return an item that belongs to a destroyed container or is already being removed, or the weapon may fail to consume fuel.
Build a plugin with OnInventoryAmmoItemFind
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 OnInventoryAmmoItemFind
Generate