OnItemRefill
OnItemRefill is called when a player runs the refill command on a repairable item that is damaged, has satisfied the player's craft level, and the player is not swimming, before the item's condition is restored.
object OnItemRefill(Item item, BasePlayer player)Parameters
| Parameter | Type | Description |
|---|---|---|
item | Item | The Item that received the refill command. Its conditionNormalized is below 1 when the hook fires, so it is a damaged repairable item such as a weapon or tool with durability. |
player | BasePlayer | The BasePlayer who issued the refill command. Use it for permission checks, feedback messages, or to read team/position state. |
Return value
Return null (or nothing) to let the vanilla refill continue and repair the item's condition. Return any non-null value to stop the original code path, so DoRepair and the follow-up effect/feedback code never run and the item keeps its current damage.
How it works
The hook fires from ItemModRepair.ServerCommand only after the game has already checked that the command is refill, the player is not swimming, the item's repair path requires the player to have a craft level (HasCraftLevel), and item.conditionNormalized is below 1. It runs immediately before the item's condition is repaired through DoRepair, so it is the last point where you can veto the refill. Both parameters are always non-null in practice: the item being refilled and the player running the command.
Because the call site declares a generic return check, declaring Item and BasePlayer is what you want; narrowing the player parameter to a subclass would cause Oxide to skip calls for other player types, which is rarely useful here. The most common design is a permission gate plus a message, and optionally a cooldown or a cost charged through another plugin.
Note that the hook does not fire when the item is already at full condition, when the player is swimming, or when the craft-level requirement is not met, because the game returns earlier in those cases. Cancelling the refill only stops the condition restore; the vanilla refill also runs effects and command feedback afterwards, which you bypass entirely.
Example plugin: Restrict item refill to a permission
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;
namespace Oxide.Plugins
{
[Info("Refill Permission", "RustPluginGenerator", "1.0.0")]
[Description("Restricts the vanilla item refill command to players with a permission")]
public class RefillPermission : RustPlugin
{
private const string PermUse = "refillpermission.use";
private PluginConfig config;
private class PluginConfig
{
[JsonProperty("Require permission to refill items")]
public bool RequirePermission { get; set; } = 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>
{
["NoPermission"] = "You do not have permission to refill items.",
["Refilled"] = "Your {0} has been refilled."
}, this);
}
private string Msg(string key, string userId = null, params object[] args) =>
string.Format(lang.GetMessage(key, this, userId), args);
private void Init()
{
permission.RegisterPermission(PermUse, this);
}
private object OnItemRefill(Item item, BasePlayer player)
{
if (item == null || player == null) return null;
if (!config.RequirePermission) return null;
if (!permission.UserHasPermission(player.UserIDString, PermUse))
{
player.ChatMessage(Msg("NoPermission", player.UserIDString));
return false;
}
string name = item.info != null ? item.info.displayName.english : "item";
player.ChatMessage(Msg("Refilled", player.UserIDString, name));
return null;
}
}
}The plugin registers a single permission, refillpermission.use, and checks it inside OnItemRefill. Players without the permission get a chat message through the language file and the hook returns false, which is non-null and therefore blocks the vanilla repair. Permitted players get null back and the refill proceeds normally, including the game's own effects. Returning false rather than true is a habit worth keeping: the value itself is not read by this call site, only whether it is non-null. The plugin keeps no state, so Unload has nothing to clean up beyond the registered permission.
Common use cases
Permission-gated repairs
Only allow the refill command for players holding a VIP or staff permission, cancelling the hook for everyone else with a clear chat reply.
Charge a price per refill
Call into an economy plugin inside the hook to take scrap or currency, and return non-null when the player cannot pay so the item stays damaged.
Refill cooldown
Store a per-player timestamp and reject refills inside a short window, which limits how quickly players can top up weapons during a fight.
Pitfalls
Hook skips several vanilla checks
The game has already validated command name, swimming state, craft level and damage before the hook runs, so do not re-check those on your side and assume the hook will also fire for full-condition items.
Return value must be non-null to cancel
Returning
falsecancels, but so does returningtrue,0or any object. Onlynullallows the repair, so avoid building the return from a ternary that can produce an unexpected non-null value.Client sees no message by default
When you cancel the refill the vanilla command feedback is bypassed, so send your own chat or console reply or the player gets silent failure.
Build a plugin with OnItemRefill
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 OnItemRefill
Generate