OnHelicopterTarget
OnHelicopterTarget is called from HelicopterTurret.SetTarget right before a patrol helicopter turret stores a new target. Returning a non-null value blocks the target assignment.
object OnHelicopterTarget(HelicopterTurret helicopterTurret, BaseCombatEntity newTarget)Parameters
| Parameter | Type | Description |
|---|---|---|
helicopterTurret | HelicopterTurret | The HelicopterTurret component calling SetTarget. Use its owner (the PatrolHelicopter) and its transform to check position, range, or which turret of the helicopter fired. |
newTarget | BaseCombatEntity | The BaseCombatEntity the turret is about to acquire. May be a player, an NPC, or another combat entity; it can be null when the turret clears its target. |
Return value
Returning null lets the original code run: the turret stores newTarget as _target and refreshes visibility. Returning any non-null value (commonly true) skips that block entirely, so the turret keeps its previous target.
How it works
The hook fires inside HelicopterTurret.SetTarget, which is the single point where a helicopter gun turret adopts a target. The patrol helicopter calls it while scanning for players and other combat entities, so it can fire repeatedly during a chase as targets are re-evaluated, and it also fires when the turret's target changes to null.
helicopterTurret gives you the turret instance, so you can read its position and reach the parent PatrolHelicopter through helicopterTurret.GetParentEntity() or the turret's transform. newTarget is the entity about to become the target; check newTarget as BasePlayer to restrict behavior to players, or inspect IsNpc.
You cannot narrow the dispatch by declaring a different parameter type here — the game passes the turret outright — so do your filtering inside the method. Because the hook runs on every target swap, keep the body cheap: no chat output, no entity scans, just the checks you need. Return true (or any non-null value) to veto the assignment.
Example plugin: Protect authorized players from helicopter turrets
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;
using UnityEngine;
namespace Oxide.Plugins
{
[Info("Helicopter Friendly Fire", "RustPluginGenerator", "1.0.0")]
[Description("Lets players with a permission stay invisible to patrol helicopter turrets")]
public class HelicopterFriendlyFire : RustPlugin
{
private const string PermShield = "helicopterfriendlyfire.shield";
private const string PermAdmin = "helicopterfriendlyfire.admin";
private PluginConfig config;
private class PluginConfig
{
[JsonProperty("Require building authorization near the player")]
public bool RequireBuildingAuth { get; set; } = false;
}
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>
{
["Granted"] = "Helicopter shield granted to {0}",
["Revoked"] = "Helicopter shield revoked from {0}",
["NoPlayer"] = "No player found with that name or id",
["Usage"] = "Usage: /helishield <name or id>"
}, this);
}
private void Init()
{
permission.RegisterPermission(PermShield, this);
permission.RegisterPermission(PermAdmin, this);
}
private object OnHelicopterTarget(HelicopterTurret helicopterTurret, BaseCombatEntity newTarget)
{
if (helicopterTurret == null || newTarget == null) return null;
var player = newTarget as BasePlayer;
if (player == null || player.IsNpc) return null;
if (!permission.UserHasPermission(player.UserIDString, PermShield)) return null;
if (config.RequireBuildingAuth && !player.IsBuildingAuthed()) return null;
return true;
}
[ChatCommand("helishield")]
private void CmdHeliShield(BasePlayer player, string command, string[] args)
{
if (player != null && !player.IsAdmin && !permission.UserHasPermission(player.UserIDString, PermAdmin))
{
Reply(player, Msg("Usage", player.UserIDString));
return;
}
if (args == null || args.Length < 1)
{
Reply(player, Msg("Usage", player?.UserIDString));
return;
}
var target = BasePlayer.FindAwakeOrSleeping(args[0]);
if (target == null)
{
Reply(player, Msg("NoPlayer", player?.UserIDString));
return;
}
if (permission.UserHasPermission(target.UserIDString, PermShield))
{
permission.RevokeUserPermission(target.UserIDString, PermShield);
Reply(player, string.Format(Msg("Revoked", player?.UserIDString), target.displayName));
}
else
{
permission.GrantUserPermission(target.UserIDString, PermShield, null);
Reply(player, string.Format(Msg("Granted", player?.UserIDString), target.displayName));
}
}
private void Reply(BasePlayer player, string text)
{
if (player != null) SendReply(player, text);
else Puts(text);
}
private string Msg(string key, string userId = null) => lang.GetMessage(key, this, userId);
}
}The plugin lets admins grant a permission that makes a player invisible to patrol helicopter turrets. OnHelicopterTarget inspects newTarget as a BasePlayer and checks the permission, plus the optional RequireBuildingAuth config flag, which requires the player to be authorized on a nearby building privilege. When the conditions match, the hook returns true, so SetTarget never stores the player and the turret keeps looking for other prey. A small chat command lets staff grant or revoke the permission at runtime, and messages go through the language file.
Common use cases
Make staff or VIP players invisible to helicopter turrets
Grant a permission and veto the target assignment for players holding it, so they can inspect or play without the patrol helicopter shooting at them.
Keep turrets away from non-combatant building owners
Check whether the player is authorized on a nearby building privilege and block targeting while they are inside their base perimeter.
Restrict targeting to a specific zone
Compare the player's position with an allowed area and return true when the player is outside it, keeping a custom event arena safe from helicopter fire.
Pitfalls
Fires repeatedly, not once
The turret re-evaluates targets during a chase, so the hook can run many times per second in a fight. Avoid PrintWarning, chat messages, or expensive lookups inside it.
newTarget is not always a player
SetTarget accepts any BaseCombatEntity, including NPCs and animals, and null when the target is cleared. Cast with
as BasePlayerand null-check before reading player members.Vetoing does not remove aggro already applied
Returning non-null only stops this assignment. A player already stored as the turret target stays until SetTarget is called again, so temporary protection should also clear existing targets.
Build a plugin with OnHelicopterTarget
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 OnHelicopterTarget
Generate