OnFuelItemCheck
OnFuelItemCheck is called from EntityFuelSystem.GetFuelItem when the game is about to determine which item counts as the current fuel unit for a fuel-burning entity.
object OnFuelItemCheck(EntityFuelSystem entityFuelSystem, StorageContainer fuelContainer)Parameters
| Parameter | Type | Description |
|---|---|---|
entityFuelSystem | EntityFuelSystem | The EntityFuelSystem component whose fuel is being queried, typically attached to a vehicle, boat, helicopter or another entity that burns fuel. Use it to reach the owning entity via GetEntity() or the fuel container. |
fuelContainer | StorageContainer | The StorageContainer that holds the fuel items, as returned by the fuel system's GetFuelContainer(). It can be null when the entity has no container attached yet. |
Return value
Return null (or false, or any non-Item value) to let the original method pick the fuel item normally. Return an Item instance to short-circuit the method and make that item the result returned by GetFuelItem, bypassing the container-based selection.
How it works
The hook fires inside EntityFuelSystem.GetFuelItem, a method the game and plugins call to learn which fuel item a vehicle or other fuel system will burn next. The call happens before the method decides between using the fuel container contents and its fallback path, so it runs whenever something asks for the current fuel item - for example when a vehicle consumes fuel, checks whether it can start, or when another plugin queries GetFuelItem() directly.
The first argument is the EntityFuelSystem itself, so you can identify the owner with entityFuelSystem.GetEntity(), inspect its type, or tag specific vehicles by prefab. The second argument is the fuel StorageContainer, which may be null, so null-check it before touching inventory. Because Oxide skips overloads when an argument is not an instance of the declared parameter type, declaring StorageContainer as your second parameter is safe here: it either matches or the hook is skipped.
Use the return value to substitute a different Item as the fuel unit. This lets you accept non-standard fuel shortnames on a specific vehicle, or force a particular item. Do not delete items here; the method is a query, not a mutation point.
Example plugin: Allow wood as vehicle fuel by permission
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;
namespace Oxide.Plugins
{
[Info("Wood Fuel Vehicles", "RustPluginGenerator", "1.0.0")]
[Description("Lets players with permission use wood as vehicle fuel.")]
public class WoodFuelVehicles : RustPlugin
{
private const string PermUse = "woodfuelvehicles.use";
private PluginConfig config;
private class PluginConfig
{
[JsonProperty("Required permission")]
public string Permission = PermUse;
[JsonProperty("Fuel shortname")]
public string FuelShortname = "wood";
}
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>
{
["NoPermission"] = "You do not have permission to use {0} as fuel.",
["Hint"] = "You can load {0} into this vehicle as fuel."
}, this);
}
private string Msg(string key, string userId = null, params object[] args) =>
string.Format(lang.GetMessage(key, this, userId), args);
private void Init()
{
if (!string.IsNullOrEmpty(config.Permission))
permission.RegisterPermission(config.Permission, this);
}
private object OnFuelItemCheck(EntityFuelSystem entityFuelSystem, StorageContainer fuelContainer)
{
if (entityFuelSystem == null || fuelContainer == null) return null;
if (fuelContainer.inventory == null) return null;
if (string.IsNullOrEmpty(config.FuelShortname)) return null;
if (ItemManager.FindItemDefinition(config.FuelShortname) == null) return null;
var owner = fuelContainer.inventory.playerOwner;
if (owner == null)
{
var entity = fuelContainer.GetParentEntity();
if (entity != null && entity.OwnerID != 0)
{
BasePlayer player = BasePlayer.FindByID(entity.OwnerID);
if (player != null && player.IsConnected)
owner = player;
}
}
if (owner == null) return null;
string perm = string.IsNullOrEmpty(config.Permission) ? PermUse : config.Permission;
if (!permission.UserHasPermission(owner.UserIDString, perm)) return null;
foreach (Item item in fuelContainer.inventory.itemList)
{
if (item?.info == null) continue;
if (item.info.shortname != config.FuelShortname) continue;
return item;
}
return null;
}
}
}The plugin lets players with the configured permission load wood into vehicle fuel containers. In OnFuelItemCheck it finds the owner from fuelContainer.inventory.playerOwner, falling back to the parent entity's OwnerID, and checks that player for the permission (default woodfuelvehicles.use). If the player has it, the plugin scans fuelContainer.inventory.itemList for an item whose shortname matches FuelShortname (default wood) and returns the first match. If no owner is found, the player lacks permission, or no matching item exists, it returns null and normal fuel selection applies. Both the permission and fuel shortname are config values, so admins can retarget the plugin without recompiling.
Common use cases
Accept alternative fuel items on vehicles
Return a matching
Itemfrom the fuel container to let a vehicle burn wood, low grade scrap, or a custom resource on select entities. Scope it by the fuel system's owning entity type or a permission on its owner.Restrict fuel per vehicle prefab
Check
entityFuelSystem.GetEntity().ShortPrefabNameand return the normal selection only for approved prefabs, or force a specific item for vehicles you want to lock down.Debug which fuel the game will consume
Temporarily return null and inspect
fuelContainer.inventory.itemListin the hook to confirm what the game considers the active fuel unit before writing a balancing or economy feature.
Pitfalls
The fuel container can be null
GetFuelContainer()returns null on entities without an attached container or before it is created. Always null-checkfuelContainerand itsinventorybefore readingitemList.Do not remove items in this hook
This is a query path called whenever the game asks for the current fuel item, often many times per second. Removing or moving items here will corrupt fuel accounting and duplicate consumption.
Returning the wrong type is ignored
The game only uses a return value that is an
Item. Returningtrue, a string, or a non-Item object has no effect and the normal selection proceeds.
Build a plugin with OnFuelItemCheck
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 OnFuelItemCheck
Generate