OnHorseLead
OnHorseLead is called when a player starts or stops leading a RidableHorse, before the game applies the new leading state. Returning a non-null value cancels the change.
object OnHorseLead(RidableHorse ridableHorse, BasePlayer player)Parameters
| Parameter | Type | Description |
|---|---|---|
ridableHorse | RidableHorse | The RidableHorse entity whose leading state is about to change. Use it to read position, owner, health or the current leader before the change is applied. |
player | BasePlayer | The BasePlayer that is starting or stopping the lead. This is the player who pressed the interact key on the horse, not necessarily the horse's owner. |
Return value
Returning null lets the game continue and call SetLeading with the new leader. Returning any non-null value skips that call, so the horse keeps its current leading state (a player cannot start leading, and an already-leading player cannot release the horse this way).
How it works
The hook fires inside RidableHorse.SERVER_Lead, which the game runs when a player toggles the lead on a horse: either attaching themselves as the leader or releasing the lead they currently hold. It runs after the game's own permission checks (owner, ability to stop) pass, so by the time your plugin sees it the player is otherwise allowed to make the change. The ridableHorse argument is the horse entity, and player is the player performing the toggle. Both are plain reference types, so you can narrow the first parameter to RidableHorse (already specific) but the second can be left as BasePlayer; declaring a different player subtype would make Oxide skip the call. Use the hook to gate leading by permission, team membership, region or cooldown. Because the return value is checked before SetLeading runs, returning anything non-null blocks the state change for both starting and stopping a lead. Note it does not fire for hitching, which has its own hooks.
Example plugin: Restrict horse leading to a permission
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;
namespace Oxide.Plugins
{
[Info("Horse Lead Permission", "RustPluginGenerator", "1.0.0")]
[Description("Restricts starting and stopping horse leads to players with a permission.")]
public class HorseLeadPermission : RustPlugin
{
private const string PermUse = "horseleadpermission.use";
private PluginConfig config;
private class PluginConfig
{
[JsonProperty("Denied message")]
public string DeniedMessage = "You are not allowed to lead horses on this server.";
[JsonProperty("Admins bypass permission")]
public bool AdminsBypass = true;
}
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"] = "You are not allowed to lead horses on this server."
}, 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(PermUse, this);
}
private object OnHorseLead(RidableHorse ridableHorse, BasePlayer player)
{
if (ridableHorse == null || player == null) return null;
// Allow a leading player to release the horse they already hold.
if (ridableHorse.HasFlag(BaseEntity.Flags.Reserved6)) return null;
if (config.AdminsBypass && player.IsAdmin) return null;
if (permission.UserHasPermission(player.UserIDString, PermUse)) return null;
string message = string.IsNullOrEmpty(config.DeniedMessage)
? Msg("Denied", player.UserIDString)
: config.DeniedMessage;
player.ChatMessage(message);
return true;
}
}
}The plugin registers a permission horseleadpermission.use in Init. When OnHorseLead fires, it checks whether the player has that permission. Players without it are blocked from toggling the lead, and a chat message is sent through the language file so they know why. The hook returns a non-null value when the permission is missing, which stops SetLeading from running, and null otherwise so normal behaviour continues. Configuration lets admins change the denial message and choose whether admins bypass the permission. Because OnHorseLead can fire often on busy horse servers, no console logging happens inside the hook.
Common use cases
Permission-gated leading
Only players with a specific permission may start or stop leading a horse. Useful on PvE or roleplay servers where animal control is a privilege.
Team-only horse handling
Compare
player.currentTeamwith the horse owner's team and block leading by outsiders. Prevents randoms from stealing unattended horses.Combat lockout
Cancel leading while the player is recently damaged or in a building-blocked zone, using a stored last-damage timestamp from
OnEntityTakeDamage.
Pitfalls
It also fires when releasing the lead
The same hook runs when a leading player stops leading. If you blanket return non-null, players cannot release horses they already hold, which can look like a bug. Return null when
playeris already the horse's leader, or handle that case explicitly.Hitching is a separate hook
OnHorseHitchandOnHorseUnhitchcover tying a horse to a hitch trough.OnHorseLeaddoes not control that path, so gate both if you want full control.Return value is ignored for `void` methods except for cancellation
SERVER_Leadreturns void, so any non-null value only serves to skipSetLeading. Do not return meaningful data expecting it to be used; only null vs non-null matters.
Build a plugin with OnHorseLead
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 OnHorseLead
Generate