Skip to content
RustPluginGenerator
Structure hookOxide + CarbonCompiled against Rust 2635.289.1 / Oxide 2.0.7839 · checked Oct 26, 2026

OnLockerSwap

OnLockerSwap is called when a player sends the Locker equip RPC to load a stored gear set, before the locker checks whether it is already equipping.

Signature
object OnLockerSwap(Locker locker, int slotIndex, BasePlayer player)

Parameters

Hook parameters
ParameterTypeDescription
lockerLockerThe Locker entity the player is interacting with. Use it to read the owner, position, building privilege or create per-locker restrictions.
slotIndexintThe zero-based gear set slot index the player tried to equip. Valid range is 0 to maxGearSets minus 1; invalid values are already rejected before the hook result is evaluated.
playerBasePlayerThe BasePlayer sending the equip RPC. Check IsConnected, IsDead, building privilege or team membership to decide whether the swap is allowed.

Return value

Return null to let the gear swap proceed. Return any non-null value (for example false or a string) to stop the original method immediately, so the player's equipped items are not replaced by the stored set.

How it works

The hook fires inside Locker.RPC_Equip, which is the RPC a client sends when the player clicks a gear set slot in the locker UI. Before your hook runs, the server has already read the slot index from the message and rejected anything outside 0 <= index < maxGearSets. After your hook returns, the method checks IsEquipping() and then the usual conditions (IsDead(), CanBeLooted(player)) before the actual gear swap happens.

locker gives you the entity, so you can inspect OwnerID, look up GetBuildingPrivilege(), or compare net.ID.Value against a whitelist. slotIndex is useful if you want to allow only certain sets (for example a VIP-only slot). player is the sender of the RPC and the best place to check permissions, team, or combat state.

Because the interception happens before the loot/open checks, blocking here also blocks the swap for players who could otherwise loot the locker, so use it for policy decisions (permission, raid state, cooldowns) rather than for validating access the base game already validates. The hook is dispatched per RPC, meaning it can run several times per second per player if they spam the UI.

Example plugin: Require a permission to use VIP locker gear sets

LockerSlotPermission.cs
using System.Collections.Generic;
using Oxide.Core;
using UnityEngine;

namespace Oxide.Plugins
{
    [Info("Locker Slot Permission", "RustPluginGenerator", "1.0.0")]
    [Description("Restricts a locker gear set slot behind a permission.")]
    public class LockerSlotPermission : RustPlugin
    {
        private const string PermVip = "lockerslotpermission.vip";
        private const int RestrictedSlot = 4;

        protected override void LoadDefaultMessages()
        {
            lang.RegisterMessages(new Dictionary<string, string>
            {
                ["Denied"] = "You do not have permission to use this locker gear set."
            }, this);
        }

        private string Msg(string key, string userId = null, params object[] args)
        {
            return string.Format(lang.GetMessage(key, this, userId), args);
        }

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

        private object OnLockerSwap(Locker locker, int slotIndex, BasePlayer player)
        {
            if (locker == null || player == null || !player.IsConnected)
                return null;

            if (slotIndex != RestrictedSlot)
                return null;

            if (permission.UserHasPermission(player.UserIDString, PermVip))
                return null;

            player.ChatMessage(Msg("Denied", player.UserIDString));
            return false;
        }
    }
}

The plugin lets admins assign a permission to any player who may use the highest gear set slot in a locker. OnLockerSwap checks whether the requested slotIndex matches the configured restricted slot. If it does, the plugin verifies that the player holds lockerslotpermission.vip; if not, it sends a localized chat message and returns false, which halts RPC_Equip before the swap. Every other slot returns null and behaves normally. The restricted slot index and the permission name are defined once as constants and the permission is registered in Init, so there is no config to get out of sync.

Common use cases

  • VIP-only gear sets

    Gate one or more locker slot indexes behind a permission so only paying or staff players can load those kits.

  • Block gear swaps while raided

    Return a value when the locker is inside a building with an active raid state (for example an explosive was recently used) to prevent quick re-equipping.

  • Anti-cheat slot index logging

    Cross-check slotIndex against locker.inventory contents to detect clients sending equip RPCs for slots they cannot see.

Pitfalls

  • Hook fires before loot validation

    The IsDead() and CanBeLooted(player) checks happen after the hook, so if you rely on them here they have not been evaluated yet. Do your own checks if you want them.

  • Returning true for allowed swaps still blocks

    The injection treats any non-null return as a veto. Return null for allowed swaps and a non-null value only when you want to stop the equip.

  • Spammy RPC call rate

    The equip RPC can be triggered repeatedly from the UI. Keep hook logic cheap and avoid chat messages on every allowed swap.

Build a plugin with OnLockerSwap

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

Prompt: VIP-only gear sets using the OnLockerSwap 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 OnLockerSwap

Generate