CanUseLockedEntity
CanUseLockedEntity is called when a player attempts to open or close an entity protected by a CodeLock or KeyLock, before the lock decides whether to grant access.
object CanUseLockedEntity(BasePlayer player, CodeLock codeLock)Parameters
| Parameter | Type | Description |
|---|---|---|
player | BasePlayer | The player who is trying to open or close the locked entity (door, box, cupboard and so on). |
codeLock | CodeLock | The CodeLock being used. Declare a CanUseLockedEntity(BasePlayer, KeyLock) overload to also receive calls from key locks. |
Return value
Return true or false to decide the result of the open/close attempt immediately; the lock's own permission and code checks are skipped. Return null (or any non-bool) to run the vanilla checks unchanged.
How it works
The hook fires inside CodeLock.OnTryToOpen and CodeLock.OnTryToClose (and the matching KeyLock methods) whenever a player interacts with the parent entity to open or close it while a lock is attached. The lock's normal logic — checking whether it is locked, whether the player knows the code, has a key, or has lock permission — runs after the hook. Return a bool to bypass that decision entirely, or return null to let the game continue.
Use it to enforce server-wide rules on who may interact with locked entities: block raiding players from opening doors during a grace timer, deny access to locks inside blocked build zones, restrict cupboard locks to team members, or allow admins to open anything. Both parameters are useful: player is the actor, codeLock gives you the entity through codeLock.GetParentEntity() plus OwnerID and other lock state. Declaring CodeLock in your method only receives calls from code locks — key locks need the separate overload, otherwise Oxide skips those calls because the argument is not a CodeLock.
Other signatures
Oxide also calls CanUseLockedEntity from other places in the game with these parameter types. Declare the overload you need, or several:
object CanUseLockedEntity(BasePlayer player, KeyLock keyLock)
Example plugin: Run a raid cooldown on code-locked doors
using UnityEngine;
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;
namespace Oxide.Plugins
{
[Info("Lock Raid Grace", "RustPluginGenerator", "1.0.0")]
[Description("Starts a per-player cooldown on code locks and denies access while it is active.")]
public class LockRaidGrace : RustPlugin
{
private const string PermBypass = "lockraidgrace.bypass";
private class PluginConfig
{
[JsonProperty("Cooldown in minutes")]
public float CooldownMinutes = 15f;
[JsonProperty("Allow owner during cooldown")]
public bool AllowOwner = true;
}
private PluginConfig config;
private readonly Dictionary<ulong, double> cooldowns = new Dictionary<ulong, double>();
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>
{
["Denied"] = "This lock cannot be opened yet. Try again in {0} minute(s)."
}, this);
}
private void Init()
{
permission.RegisterPermission(PermBypass, this);
}
private string Msg(string key, string userId = null, params object[] args) => string.Format(lang.GetMessage(key, this, userId), args);
private object CanUseLockedEntity(BasePlayer player, CodeLock codeLock)
{
if (player == null || codeLock == null) return null;
if (permission.UserHasPermission(player.UserIDString, PermBypass)) return null;
if (codeLock.GetParentEntity() == null) return null;
bool isOwnerAllowed = config.AllowOwner && codeLock.OwnerID == player.userID.Get();
if (isOwnerAllowed) return null;
if (IsOnCooldown(player))
{
player.ChatMessage(Msg("Denied", player.UserIDString, Math.Ceiling(RemainingMinutes(player))));
return false;
}
StartCooldown(player);
return null;
}
private object CanUseLockedEntity(BasePlayer player, KeyLock keyLock)
{
return null; // Key locks stay vanilla.
}
private bool IsOnCooldown(BasePlayer player)
{
double end;
return cooldowns.TryGetValue(player.userID.Get(), out end) && end > UnityEngine.Time.realtimeSinceStartup;
}
private double RemainingMinutes(BasePlayer player)
{
double end;
if (!cooldowns.TryGetValue(player.userID.Get(), out end)) return 0d;
double remaining = end - UnityEngine.Time.realtimeSinceStartup;
return remaining > 0 ? remaining / 60d : 0d;
}
private void StartCooldown(BasePlayer player)
{
cooldowns[player.userID.Get()] = UnityEngine.Time.realtimeSinceStartup + config.CooldownMinutes * 60d;
}
private void Unload()
{
cooldowns.Clear();
}
}
}Opening a code lock starts a per-player cooldown, and while it is active the player is denied access unless they own the lock or hold the bypass permission. For opening, the plugin allows the owner regardless of cooldown, which prevents a timed raid from punishing the base owner. The config holds the cooldown in minutes and a toggle for the owner rule, and the bypass permission is registered in Init. Returning null for players who are not on cooldown lets the game run its own checks unchanged; returning true for the owner skips the code-entry flow. When a non-owner is blocked, the player gets a chat message with the remaining time.
Common use cases
Restrict access to team members
Return false when
player.currentTeamis not the lock owner's team so only the owning team can open their doors and boxes.Admin override
Return true when
player.IsAdminand the player also has a specific permission, letting staff inspect locked containers without the code.Raid cooldown by player
Block opening locked entities for a fixed time after a combat event, or during a server event, to protect online players during that window.
Pitfalls
Key locks use a different signature
The hook fires for both implementations, but Oxide skips calls where the second argument is not a
CodeLock. To handle key locks, declare theKeyLockoverload as well and share the logic in one method.The lock and its parent are separate
The lock is not the entity the player sees — call
codeLock.GetParentEntity()and null-check it before reading owner, position or building privilege data.Returning bool bypasses code entry
Returning
trueopens the entity without the player knowing or entering the code, as if the lock were unlocked. Only return true when you are certain the actor should be allowed, never as a default value.
Build a plugin with CanUseLockedEntity
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 CanUseLockedEntity
Generate