Skip to content
RustPluginGenerator

OnFuelAmountCheck

OnFuelAmountCheck is called when EntityFuelSystem.GetFuelAmount is invoked, before the game returns the stored fuel count. It lets you substitute a different fuel amount or short-circuit the lookup entirely.

Signature
object OnFuelAmountCheck(EntityFuelSystem entityFuelSystem, Item fuelItem)

Parameters

Hook parameters
ParameterTypeDescription
entityFuelSystemEntityFuelSystemThe EntityFuelSystem component whose fuel level is being queried. Use it to reach the owning entity (entityFuelSystem.owner), its net ID and ShortPrefabName, or to compare it against a cached reference.
fuelItemItemThe Item the fuel system currently uses as its fuel source, or null when no fuel item is present. Read fuelItem.amount to see the stored units and fuelItem.info.shortname to identify the fuel type.

Return value

Return an int to replace the value GetFuelAmount reports, skipping the default fuel item check. Returning null, or any non-int object, makes the game fall through to its normal fuelItem == null || fuelItem.amount < 1 logic.

How it works

The hook fires inside EntityFuelSystem.GetFuelAmount, the method generators and vehicles use to decide whether they have fuel. It runs after the system has looked up its current fuel item and before the default amount < 1 check, so both active consumption (a running generator) and passive UI or IsOn queries can trigger it. entityFuelSystem identifies the caller — entityFuelSystem.owner is the entity holding the component, useful for allow lists, ownership checks or type filtering. fuelItem is the resolved Item and is frequently null on empty generators; treat it as optional and never assume fuelItem.info is available. Because every call runs your hook, keep the body cheap: no chat output, no entity scans and no data writes. If you need per-entity state, store it in a dictionary keyed by entityFuelSystem.owner.net.ID.Value and clean it up on entity removal. This is one of the few hooks where an int return changes behavior, so always return null when you have no opinion so the vanilla calculation continues.

Example plugin: Give whitelisted generators a virtual fuel reserve

FuelAmountOverride.cs
using System.Linq;
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;
using UnityEngine;

namespace Oxide.Plugins
{
    [Info("Fuel Amount Override", "RustPluginGenerator", "1.0.0")]
    [Description("Reports a virtual fuel amount for whitelisted fuel systems so they keep running.")]
    public class FuelAmountOverride : RustPlugin
    {
        private const string PermAdmin = "fuelamountoverride.admin";

        private PluginConfig config;

        private class PluginConfig
        {
            [JsonProperty("Enable virtual fuel")]
            public bool Enabled = true;

            [JsonProperty("Virtual fuel amount")]
            public int VirtualAmount = 100;

            [JsonProperty("Only matching prefabs")]
            public List<string> Prefabs = new List<string> { "fuelgenerator.static" };
        }

        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>
            {
                ["ToggleOn"] = "Virtual fuel is now enabled.",
                ["ToggleOff"] = "Virtual fuel is now disabled."
            }, this);
        }

        private string Msg(string key, string userId = null) => lang.GetMessage(key, this, userId);

        private void Init()
        {
            permission.RegisterPermission(PermAdmin, this);
        }

        [ChatCommand("fueltoggle")]
        private void CmdFuelToggle(BasePlayer player, string command, string[] args)
        {
            if (player == null || !permission.UserHasPermission(player.UserIDString, PermAdmin)) return;

            config.Enabled = !config.Enabled;
            SaveConfig();
            player.ChatMessage(Msg(config.Enabled ? "ToggleOn" : "ToggleOff", player.UserIDString));
        }

        private object OnFuelAmountCheck(EntityFuelSystem entityFuelSystem, Item fuelItem)
        {
            if (!config.Enabled || entityFuelSystem == null) return null;
            if (fuelItem == null || fuelItem.parent == null) return null;

            BaseEntity owner = fuelItem.parent.entityOwner;
            if (owner == null || owner.IsDestroyed) return null;

            string prefab = owner.ShortPrefabName;
            if (string.IsNullOrEmpty(prefab) || !config.Prefabs.Contains(prefab)) return null;

            int stored = Mathf.Max(fuelItem.amount, 0);
            return stored + config.VirtualAmount;
        }
    }
}

The plugin answers fuel amount queries in OnFuelAmountCheck(EntityFuelSystem, Item), resolves the owning entity through fuelItem.parent.entityOwner, and only acts when the owner's ShortPrefabName is in the configured prefab list (default fuelgenerator.static). For a whitelisted owner it returns the configured VirtualAmount plus the fuel item's current amount, so the system keeps running without depleting its tank. All other owners and the disabled feature return null and fall through to vanilla behavior. Admins with fuelamountoverride.admin can toggle Enabled with /fueltoggle, which persists to the config and does not modify stored fuel.

Common use cases

  • Free fuel for admin or event generators

    Return a fixed amount for entities in an allow list so event areas keep power without a fuel economy. Combine with CanUseFuel if you also want to block manual fuel insertion.

  • Diagnostics for empty fuel systems

    Track which entity IDs keep querying with a null fuel item to find broken or starved generators during a wipe, then act on the collected set from a timer instead of inside the hook.

  • Custom fuel accounting

    Read a per-entity charge counter from your own data files and return it here, letting a modified generator run on a currency rather than low grade fuel.

Pitfalls

  • fuelItem can be null

    Empty generators and vehicles return null for the fuel item, so touching fuelItem.amount or fuelItem.info without a null check throws inside the hook and can break the generator's tick.

  • Fires very often

    Every GetFuelAmount call runs the hook, including repeated UI and IsOn queries. Keep the body to dictionary lookups and never chat, log or iterate players.

  • Returning an int bypasses stock behavior

    A non-null int replaces the result entirely, so returning 0 for one fuel system disables it and returning a positive value keeps it running even with an empty tank. Return null for anything you do not intend to override.

Build a plugin with OnFuelAmountCheck

Describe what should happen and get a compiled plugin that uses this hook.

Prompt: Free fuel for admin or event generators using the OnFuelAmountCheck hook, with a config file and a permission
Generate this plugin

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 OnFuelAmountCheck

Generate