OnNpcEquipWeapon
OnNpcEquipWeapon is called on an NPC before the server makes a weapon its active item, and returning a non-null value cancels that equip step.
object OnNpcEquipWeapon(NPCPlayer nPCPlayer, Item slot)Parameters
| Parameter | Type | Description |
|---|---|---|
nPCPlayer | NPCPlayer | The NPC that is about to equip a weapon. In the ScientistNPC overload it is still the same NPCPlayer instance, so you can cast it or declare ScientistNPC to narrow the call. |
slot | Item | The Item being considered for the active hand. It comes from the belt slot 0 in NPCPlayer.EquipWeapon; in the scientist path it is the item held by the entity. It can be null. |
Return value
Returning null lets the original code continue, so the NPC equips the item as usual. Returning any non-null object stops the original method before the active item is set (in the scientist path, before its follow-up weapon logic runs), so the NPC keeps its previous active item. The actual value is not used.
How it works
The hook fires in two places. First, NPCPlayer.EquipWeapon reads belt slot 0, calls the hook with that item, and only then calls UpdateActiveItem with the slot's uid. Second, ScientistNPC.EquipWeapon runs after the NPC already holds an entity: it resolves the held entity's item, bails out if the item or its contents are null, calls the hook, and then runs its weapon-selection follow-up code (including a random check).
In both sites the item can be null, so check before reading slot.info or slot.GetHeldEntity(). The NPC's inventory containers are available through nPCPlayer.inventory, which is useful if you want to decide based on other held items.
Declaring the second overload as ScientistNPC scientistNPC, Item item narrows it to scientists only, because Oxide only calls your method when every argument matches the declared parameter type. With the base NPCPlayer signature you receive every NPC type that runs this code path. Use the hook for loadout policies (restricting certain weapons), not for per-tick logic.
Other signatures
Oxide also calls OnNpcEquipWeapon from other places in the game with these parameter types. Declare the overload you need, or several:
object OnNpcEquipWeapon(ScientistNPC scientistNPC, Item item)
Example plugin: Block NPCs from equipping a restricted weapon
using System.Linq;
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;
using UnityEngine;
namespace Oxide.Plugins
{
[Info("Npc Weapon Blacklist", "RustPluginGenerator", "1.0.0")]
[Description("Stops NPCs from equipping weapons listed in the configuration")]
public class NpcWeaponBlacklist : RustPlugin
{
private PluginConfig config;
private readonly HashSet<string> blocked = new HashSet<string>();
private readonly HashSet<string> reported = new HashSet<string>();
private class PluginConfig
{
[JsonProperty("Blocked weapon shortnames")]
public List<string> BlockedShortnames = new List<string> { "lmg.m249", "rifle.ak" };
}
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 OnServerInitialized()
{
blocked.Clear();
reported.Clear();
if (config.BlockedShortnames == null) return;
foreach (string shortname in config.BlockedShortnames)
{
if (!string.IsNullOrEmpty(shortname)) blocked.Add(shortname);
}
Puts($"Loaded {blocked.Count} blocked weapon shortname(s) for NPCs");
}
private object OnNpcEquipWeapon(NPCPlayer nPCPlayer, Item slot)
{
if (nPCPlayer == null || slot == null || slot.info == null) return null;
if (!blocked.Contains(slot.info.shortname)) return null;
if (reported.Add(slot.info.shortname))
{
Puts($"Prevented NPC from equipping blacklisted item '{slot.info.shortname}'");
}
return true;
}
// Scientists run their own EquipWeapon; cover that path explicitly.
private object OnNpcEquipWeapon(ScientistNPC scientistNPC, Item item)
{
return OnNpcEquipWeapon((NPCPlayer)scientistNPC, item);
}
}
}The plugin keeps a configurable list of item shortnames that NPCs are not allowed to use as their active weapon. OnNpcEquipWeapon looks up the incoming item's shortname, compares it against the config list, and returns a non-null object when it matches, which stops the game from calling UpdateActiveItem. Null items pass through untouched.
Common use cases
Ban overpowered weapons on NPCs
Keep loot tables or custom NPC loadouts from handing scientists an item you consider too strong for PvE, in one central list instead of editing spawn code.
Perf/event tuning
On custom event servers you can stop NPCs from pulling particular weapons during an event and restore the list afterwards by editing the config and reloading.
Warn on unexpected loadouts
Log once per shortname when an NPC tries to equip something that is not in the allowed set, so you can spot broken custom loadouts without spamming the console.
Pitfalls
The item can be null
Both injection sites call the hook with a possibly null item. Always check
slot == nullbefore touchingslot.infoorGetHeldEntity().Only two call sites
This hook exists on
NPCPlayer.EquipWeaponandScientistNPC.EquipWeapon. NPC types that use a different equip path will not trigger it, so do not assume every NPC weapon change is visible here.Do not edit inventory here
The hook runs while the game is choosing the active item. Removing or moving items inside the hook can leave the NPC with an inconsistent belt; cancel the equip and let your own timer or spawn code handle the inventory instead.
Build a plugin with OnNpcEquipWeapon
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 OnNpcEquipWeapon
Generate