OnWeaponReload
OnWeaponReload is called when a player starts reloading a projectile weapon, just before BaseProjectile marks the reload as started. Returning a non-null value cancels the reload.
object OnWeaponReload(BaseProjectile projectile, BasePlayer player)Parameters
| Parameter | Type | Description |
|---|---|---|
projectile | BaseProjectile | The BaseProjectile component of the weapon being reloaded. Use it to read the held item, ammo type or owner. |
player | BasePlayer | The BasePlayer holding the weapon and starting the reload. Can be null if the reload is triggered without a player reference. |
Return value
Return null to let the reload proceed normally. Return any non-null object to stop the reload from starting: the game skips the code that sets reloadStarted and resets the insert counter, so the weapon stays in its pre-reload state. The returned value itself is ignored.
How it works
The hook fires inside BaseProjectile.StartReload, after the game has confirmed a reload is possible (a valid magazine-only weapon, matching ammo in the inventory, and no active reload already in progress). It fires before reloadStarted is set to true and before the fractional insert counter is reset, so you are running at the very start of the reload sequence.
The projectile parameter is the weapon component itself; player is whoever triggered the reload. This makes the hook convenient for checking the held item (projectile.GetItem()), the loaded ammo shortname, or the player's permissions before allowing the action. The return value is checked for null only, so any non-null object cancels the reload.
The hook is fired for every reload start that reaches this injected branch, including weapons held by NPCs if they have a valid owner. Because it fires only on reload start and not on every tick, it is safe to do lightweight checks and even print messages here, though you should still avoid Puts in high-frequency scenarios.
Example plugin: Block reloads above a magazine size limit for non-VIPs
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;
namespace Oxide.Plugins
{
[Info("Reload Size Limit", "RustPluginGenerator", "1.0.0")]
[Description("Blocks reloads that exceed a configured magazine size for players without permission.")]
public class ReloadSizeLimit : RustPlugin
{
private const string PermBypass = "reloadsizelimit.bypass";
private PluginConfig config;
public class PluginConfig
{
[JsonProperty("Maximum rounds per reload")]
public int MaxRounds { get; set; } = 30;
[JsonProperty("Warning cooldown in seconds")]
public float WarnCooldown { get; set; } = 5f;
}
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>
{
["ReloadBlocked"] = "You can only load {0} rounds per reload."
}, 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(PermBypass, this);
}
private object OnWeaponReload(BaseProjectile projectile, BasePlayer player)
{
if (projectile == null) return null;
if (config.MaxRounds <= 0) return null;
var item = projectile.GetItem();
if (item == null || item.info == null) return null;
if (player == null || player.IsNpc) return null;
var clip = projectile.primaryMagazine;
if (clip == null || clip.capacity <= config.MaxRounds) return null;
if (permission.UserHasPermission(player.UserIDString, PermBypass)) return null;
// Narrow the capacity cap and stop this reload
clip.capacity = config.MaxRounds;
player.ChatMessage(Msg("ReloadBlocked", player.UserIDString, config.MaxRounds));
return false;
}
}
}The plugin limits how many rounds a player can load in one reload when they lack a permission. On OnWeaponReload it reads the weapon's parent item, checks the current clip size against a configurable cap, and if the player is not in the allowed group it cancels the reload and sends a localized warning. Because the hook only returns non-null when the limit is exceeded, normal reloads proceed untouched. The check skips NPCs and players without a valid item, which keeps it safe with modded or fake weapons.
Common use cases
Enforce magazine size rules
Cap the number of rounds a non-VIP player can reload, or block oversized magazines on specific weapons to balance PvP.
Restrict reloads in zones
Cancel reloads when the player is inside a safe zone, spawn area, or other defined region where reloading should not be allowed.
Announce reloads for streamers
Detect the held weapon and broadcast a themed chat message or effect to spectators without affecting the actual reload.
Pitfalls
Player can be null
The player argument may be null when the reload is triggered without a connected owner, such as some NPC or tooling paths. Null-check
playerand itsUserIDStringbefore using permissions.Does not dispatch per weapon
You cannot declare a narrower weapon type in place of BaseProjectile; convert with
asinside the hook if you need to inspect a specific weapon subclass.Returning false is not a cancel
Only null allows the reload to continue. Returning
trueor any other object still cancels it, so use null for the pass case and a non-null sentinel for cancel.
Build a plugin with OnWeaponReload
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 OnWeaponReload
Generate