OnActiveItemChanged
OnActiveItemChanged is called from BasePlayer.UpdateActiveItem after the player's active belt item has been switched and network updates were sent, giving you the new and previous Item.
void OnActiveItemChanged(BasePlayer player, Item activeItem, Item activeItem2)Parameters
| Parameter | Type | Description |
|---|---|---|
player | BasePlayer | The BasePlayer whose held item changed. Always the local player entity that ran BasePlayer.UpdateActiveItem. |
activeItem | Item | The new active Item after the change, or null when the player now holds nothing (or a non-item belt slot). |
activeItem2 | Item | The Item that was active before the change, or null if the player previously held nothing. Useful for comparing old and new. |
Return value
The return value is ignored. The original method returns void and injection is a plain call, so returning anything from your hook has no effect on the game. Use it purely for observation and side effects such as UI updates or notifications.
How it works
Oxide fires this hook at the end of BasePlayer.UpdateActiveItem, which the game calls whenever a player's active held item changes: pressing a belt slot hotkey (1-6), scrolling the hotbar, swapping to a different item, or clearing the active slot. Because the call happens after inventory.UpdatedVisibleHolsteredItems() and the optional network update, the new item is already the player's held item when your plugin runs.
player is the owner. activeItem is the item now selected (may be null), and activeItem2 is the item that was selected before the switch (may be null). Compare the two to detect entering or leaving a particular weapon or tool.
The parameter types match BasePlayer and Item exactly, so declaring them more specifically is not useful here; you can only null-check. The hook fires very often on busy servers (every hotbar press), so keep handlers cheap and never call Puts or PrintWarning inside it. Fetch activeItem.info.shortname or activeItem.info.itemid to branch on what the player is holding.
Example plugin: Show a HUD hint when a player equips a weapon
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;
using UnityEngine;
namespace Oxide.Plugins
{
[Info("Active Weapon Notifier", "RustPluginGenerator", "1.0.0")]
[Description("Notifies players when they equip a weapon or a configured item.")]
public class ActiveWeaponNotifier : RustPlugin
{
private const string PermUse = "activeweaponnotifier.use";
private PluginConfig config;
private class PluginConfig
{
[JsonProperty("Enable notifications")]
public bool Enabled = true;
[JsonProperty("Only notify for these shortnames (empty = any weapon)")]
public List<string> Shortnames = new List<string>();
[JsonProperty("Notify only players with permission")]
public bool RequirePermission = false;
}
protected override void LoadDefaultConfig() => config = new PluginConfig();
protected override void LoadConfig()
{
base.LoadConfig();
try
{
config = Config.ReadObject<PluginConfig>();
if (config == null) throw new System.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>
{
["Equipped"] = "You equipped {0}. Check the rules before using it here.",
["EquippedGeneric"] = "You equipped {0}."
}, 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 void OnActiveItemChanged(BasePlayer player, Item activeItem, Item activeItem2)
{
if (!config.Enabled || player == null || activeItem == null || activeItem.info == null)
return;
if (activeItem == activeItem2 || activeItem.info.shortname == activeItem2?.info?.shortname)
return;
if (config.RequirePermission && !permission.UserHasPermission(player.UserIDString, PermUse))
return;
if (!ShouldNotify(activeItem)) return;
string display = activeItem.info.displayName?.english ?? activeItem.info.shortname;
player.ChatMessage(Msg("EquippedGeneric", player.UserIDString, display));
}
private bool ShouldNotify(Item item)
{
if (config.Shortnames == null || config.Shortnames.Count == 0)
return item.info.category == ItemCategory.Weapon;
foreach (string shortname in config.Shortnames)
{
if (shortname == item.info.shortname) return true;
}
return false;
}
}
}The plugin reads activeItem.info.category (or a configurable list of shortnames) when OnActiveItemChanged fires. If the newly held item is a weapon and differs from the previous item, it sends a short chat reminder and, when enabled, a console command the player can use. Because the hook fires on every belt press, the handler returns early when the new item is null or matches the old one, keeping the work minimal. A config flag toggles the feature and a permission restricts it to players who have activeweaponnotifier.use, so admins can roll it out gradually. No timers or state are kept, so nothing needs cleanup in Unload.
Common use cases
Weapon-switch reminders
Notify players when they equip a specific weapon, for example reminding them that PvP is disabled in a safe zone or that a tool is required in a build area.
Tool-based rules
React to players switching to a building tool or repair hammer to enable a per-player overlay showing available commands or remaining resources.
Analytics of equipped items
Count how often each weapon shortname is selected per session and store the totals in oxide/data for balance reporting.
Pitfalls
Fires on every belt press
Players cycle items constantly. Keep the handler cheap, avoid string concatenation of long lists and never log in this hook.
Both items can be null
When a player empties their belt slot or drops the active item,
activeItemis null. Always null-check before touchinginfo.Not the same as equipping
This hook reports the selected belt item, not whether a HeldEntity spawned. For deployable or held-entity logic use entity events instead.
Build a plugin with OnActiveItemChanged
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 OnActiveItemChanged
Generate