OnPlayerHandcuffed
OnPlayerHandcuffed is called after a player has been successfully restrained with handcuffs by another player, once the cuff item is equipped, the lock flag is set and the lock effect has played.
void OnPlayerHandcuffed(BasePlayer victim, BasePlayer handcuffer)Parameters
| Parameter | Type | Description |
|---|---|---|
victim | BasePlayer | The BasePlayer who was just restrained. Already has the handcuffs equipped in the belt slot and the lock flag set when the hook fires. |
handcuffer | BasePlayer | The BasePlayer who applied the handcuffs. Use it to check permissions, team membership or distance for the victim. |
Return value
The return value is ignored. SV_HandcuffVictim returns void and the hook is injected as the final statement, so returning anything (or nothing) cannot undo the cuffing or change later behavior.
How it works
This hook fires at the end of Handcuffs.SV_HandcuffVictim, the server-side routine that applies restraints. By the time it runs, the victim already has the handcuff item equipped in belt slot 0, the active belt slot change has been sent to the client, SetLocked(true, ...) has been applied and the lock effect has been played. It does not fire for failed attempts (out of range, no handcuffs, already cuffed).
Because the injection point is the last line of the method, you cannot use this hook to prevent the cuffing. Permission or allowlist checks belong in OnPlayerHandcuff or in a command/item interception. Here you handle the consequences: logging the event, notifying teammates, applying effects, teleporting the victim to an event area, or starting a jail timer.
Both parameters are non-null in normal play, but keep null checks for safety, and check victim.IsConnected before sending chat or console output. Declaring the parameters as BasePlayer is the only useful narrowing: the handcuffer is always a real player, never an NPC entity. Avoid heavy work here since cuffing is player-driven and can happen in bursts during raids.
Example plugin: Notify team and log when a player is handcuffed
using UnityEngine;
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;
namespace Oxide.Plugins
{
[Info("Handcuff Alert", "RustPluginGenerator", "1.0.0")]
[Description("Notifies teammates and logs when a player is handcuffed")]
public class HandcuffAlert : RustPlugin
{
private class PluginConfig
{
[JsonProperty("Notify teammates")]
public bool NotifyTeammates = true;
[JsonProperty("Log to console")]
public bool LogToConsole = true;
[JsonProperty("Team message")]
public string TeamMessage = "{0} was handcuffed by {1} at {2}";
}
private PluginConfig config;
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>
{
["CuffedAlert"] = "<color=#ff6b6b>{0}</color> was restrained by <color=#ffd166>{1}</color> at {2}"
}, this);
}
private string Msg(string key, string userId = null, params object[] args)
=> string.Format(lang.GetMessage(key, this, userId), args);
private void OnPlayerHandcuffed(BasePlayer victim, BasePlayer handcuffer)
{
if (victim == null || handcuffer == null) return;
var pos = victim.transform != null ? victim.transform.position : UnityEngine.Vector3.zero;
var loc = string.Format("{0:0}, {1:0}", pos.x, pos.z);
if (config.LogToConsole)
{
PrintWarning($"{victim.displayName} ({victim.UserIDString}) cuffed by {handcuffer.displayName} at {loc}");
}
if (!config.NotifyTeammates || victim.currentTeam == 0) return;
var team = RelationshipManager.ServerInstance.FindTeam(victim.currentTeam);
if (team == null) return;
foreach (var memberId in team.members)
{
if (memberId == victim.userID.Get()) continue;
var member = BasePlayer.FindByID(memberId);
if (member == null || !member.IsConnected) continue;
SendReply(member, string.Format(config.TeamMessage, victim.displayName, handcuffer.displayName, loc));
}
}
}
}The plugin listens for OnPlayerHandcuffed and, if enabled in config, sends a chat line to the victim's teammates with the victim and the person who applied the cuffs. It also prints a console line for admins watching the server so they can track raids and kidnappings. Config holds the chat and console message wording and a broadcast toggle, loaded through the standard config helpers. Messages are sent via SendReply and PrintToChat, all guarded by connection checks. Timers are not used, so Unload only needs to exist for symmetry.
Common use cases
Raid and kidnapping logs
Record who cuffed whom, when and at what coordinates to a data file so admins can review incidents without digging through server logs.
Team notifications
Send a chat message to every online teammate of the victim so they know their friend has been restrained and by whom.
Jail and event systems
Start a jail timer, teleport the victim to a holding area, or mark them as an event prisoner once the cuffs are applied.
Pitfalls
Cannot block the cuffing
The hook fires after the restraint is fully applied. Use
OnPlayerHandcuffif you need to refuse the action or check permissions before it happens.Hooks fire for NPC handcuffs only in edge cases
The handcuffer is always a BasePlayer in vanilla Rust, but custom plugins can call
SV_HandcuffVictimdirectly - checkIsNpcor null before trusting the parameter.Do not use for heavy saves
Cuffing can happen in quick succession during PvP. Buffer log entries in memory and flush on a timer or in
Unloadrather than writing to disk on every call.
Build a plugin with OnPlayerHandcuffed
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 OnPlayerHandcuffed
Generate