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

OnCupboardAuthorize

OnCupboardAuthorize is called when a player is about to be added to a tool cupboard or vehicle privilege authorization list. Returning a non-null value cancels the authorization.

Signature
object OnCupboardAuthorize(BuildingPrivlidge buildingPrivlidge, BasePlayer player)

Parameters

Hook parameters
ParameterTypeDescription
buildingPrivlidgeBuildingPrivlidgeThe tool cupboard (BuildingPrivlidge) that the player is being authorized on. For the vehicle overload this argument is a VehiclePrivilege, so null-check and treat it as the entity being modified.
playerBasePlayerThe BasePlayer attempting to add themselves to the authorization list. Use its UserIDString for permissions, or check team membership and building rights.

Return value

Returning null (or nothing) lets the game continue and add the player to the auth list. Returning any non-null value skips the AddPlayer call at that site, so the authorization is silently denied; there is no error message unless you send one yourself.

How it works

This hook fires right before the game writes a player into the auth list. Three call paths feed it: deploying a tool cupboard (ItemModDeployable.OnDeployed) auto-authorizes the placer, using the cupboard's own auth action (RustCore.IOnCupboardAuthorize) authorizes the interacting player, and VehiclePrivilege.AddSelfAuthorize authorizes a player on a vehicle privilege. In all cases the game calls the hook first and only calls AddPlayer when the hook returns null.

The cupboard argument is what you inspect for ownership and the current guest list: OwnerID, authorizedPlayers, transform.position, and GetBuildingPrivilege() on nearby blocks. The player argument lets you gate by permission, team, CanBuild, or authorization on a neighbouring cupboard. Because dispatch is type-based, declaring VehiclePrivilege in a second overload lets you handle vehicles separately from cupboards.

A common pattern is a per-team or per-player auth limit: count current authorized players, and return a non-null value when the limit is exceeded so the game skips adding the player. Because the hook runs for online interactors only, sleeping players and offline list edits are not intercepted.

Other signatures

Oxide also calls OnCupboardAuthorize from other places in the game with these parameter types. Declare the overload you need, or several:

  • object OnCupboardAuthorize(VehiclePrivilege vehiclePrivilege, BasePlayer player)

Example plugin: Limit authorized players on each tool cupboard

CupboardAuthLimit.cs
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;

namespace Oxide.Plugins
{
    [Info("CupboardAuthLimit", "RustPluginGenerator", "1.0.0")]
    [Description("Limits how many players can be authorized on a single tool cupboard")]
    public class CupboardAuthLimit : RustPlugin
    {
        private const string PermBypass = "cupboardauthlimit.bypass";

        private PluginConfig config;

        private class PluginConfig
        {
            [JsonProperty("Max authorized players per cupboard")]
            public int MaxAuthorized { get; set; } = 5;
        }

        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>
            {
                ["AuthLimitReached"] = "This tool cupboard already has the maximum of {0} authorized players."
            }, 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(PermBypass, this);
        }

        private object OnCupboardAuthorize(BuildingPrivlidge buildingPrivlidge, BasePlayer player)
        {
            if (buildingPrivlidge == null || player == null || !player.IsConnected)
                return null;

            if (config.MaxAuthorized <= 0)
                return null;

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

            int current = buildingPrivlidge.authorizedPlayers != null ? buildingPrivlidge.authorizedPlayers.Count : 0;
            if (current < config.MaxAuthorized)
                return null;

            player.ChatMessage(Msg("AuthLimitReached", player.UserIDString, config.MaxAuthorized));
            return true;
        }
    }
}

The plugin caps how many players a single tool cupboard can authorize. On every OnCupboardAuthorize, it checks that the cupboard and player are valid, then counts the current authorizedPlayers. If that count already meets the configured limit, it sends the player a chat message through the language file and returns a non-null value to block the authorization. Players with the cupbboardauthlimit.bypass permission skip the check entirely. The limit is read from config, so admins can change it without recompiling. Because the hook is cheap and fires only on manual auth, no timers or per-tick work are needed.

Common use cases

  • Enforce a maximum team size per cupboard

    Count authorizedPlayers and block additions past a configurable number, keeping large clans from overcrowding shared bases.

  • Restrict auth to trusted players

    Return non-null unless the player holds a permission node, so only whitelisted admins or VIPs can authorize on cupboards.

  • Log authorization events for audits

    Record the player ID and cupboard position into an Oxide log file for later review of who granted access to which structures.

Pitfalls

  • Hook does not fire for bulk edits

    Clear-list and manual list management do not necessarily route through this hook, so a limit cannot be enforced purely here. Pair it with a periodic check if you need hard caps.

  • Vehicle privilege uses a different argument type

    VehiclePrivilege.AddSelfAuthorize passes a VehiclePrivilege instead of a BuildingPrivlidge. If you declare BuildingPrivlidge, the vehicle call is skipped by dispatch, so vehicle auth is unaffected by your limit.

  • Silent denial confuses players

    Returning non-null cancels auth without any game message. Send an explanatory chat line or the player will assume the cupboard is broken.

Plugin recipes that use OnCupboardAuthorize

Build a plugin with OnCupboardAuthorize

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

Prompt: Enforce a maximum team size per cupboard using the OnCupboardAuthorize 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 OnCupboardAuthorize

Generate