OnEntityEnter
OnEntityEnter is called when an entity enters a trigger volume, such as a comfort trigger, radiation zone or custom trigger zone. Returning a non-null value stops the game from registering the entity in that trigger.
object OnEntityEnter(TriggerBase triggerBase, BaseEntity ent)Parameters
| Parameter | Type | Description |
|---|---|---|
triggerBase | TriggerBase | The trigger volume the entity just entered. It is the TriggerBase subclass instance (for example TriggerComfort, TriggerRadiation, TriggerPlayerArea); cast it or check its type to identify the zone. |
ent | BaseEntity | The entity that entered the trigger, usually a BasePlayer or a vehicle/animal. Cast it to the type you need and null-check it before use. |
Return value
Returning null lets the game continue and adds the entity to the trigger's tracked set. Returning any non-null value skips that registration, so the trigger ignores the entity; the original method returns void, so the value itself is discarded.
How it works
The hook fires from TriggerBase.OnEntityEnter right after the trigger's internal entity set is checked, before the entity is added to it. For comfort triggers it fires from TriggerComfort.OnEntityEnter, but only for players and ridable horses, so vanilla comfort zones never report animals or NPCs.
triggerBase is the trigger instance itself. Cast it by its concrete type (TriggerComfort, TriggerRadiation, TriggerPlayerArea, or a custom TriggerBase subclass) to know which zone the entity entered. ent is the entity entering the volume; it is normally a BasePlayer, RidableHorse or another BaseEntity subtype.
You can narrow the call by declaring a more specific parameter type: object OnEntityEnter(TriggerComfort trigger, BaseEntity ent) is only dispatched for comfort zones. Declaring BasePlayer for the second parameter makes Oxide skip calls where the entity is not a player, which is useful but hides vehicle and NPC entry.
The hook is called whenever the game processes an entry, so it can fire for each player walking into a zone. Keep the body cheap and avoid repeated logging.
Other signatures
Oxide also calls OnEntityEnter from other places in the game with these parameter types. Declare the overload you need, or several:
object OnEntityEnter(TriggerComfort triggerComfort, BaseEntity ent)
Example plugin: Restrict radiation zones and warn players on entry
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;
using UnityEngine;
namespace Oxide.Plugins
{
[Info("Radiation Zone Guard", "RustPluginGenerator", "1.0.0")]
[Description("Warns players and applies extra damage when they enter a radiation trigger zone.")]
public class RadiationZoneGuard : RustPlugin
{
private const string PermExempt = "radiationzoneguard.exempt";
private PluginConfig config;
private readonly Dictionary<ulong, float> lastWarn = new Dictionary<ulong, float>();
private class PluginConfig
{
[JsonProperty("Extra damage per entry")]
public float ExtraDamage { get; set; } = 5f;
[JsonProperty("Warning cooldown in seconds")]
public float WarningCooldown { get; set; } = 30f;
}
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>
{
["Warning"] = "You entered a radiation zone. Get out before it burns through your gear."
}, this);
}
private string Msg(string key, string userId = null, params object[] args) => string.Format(lang.GetMessage(key, this, userId), args);
private void Init()
{
permission.RegisterPermission(PermExempt, this);
}
private object OnEntityEnter(TriggerBase triggerBase, BaseEntity ent)
{
var radiation = triggerBase as TriggerRadiation;
if (radiation == null) return null;
var player = ent as BasePlayer;
if (player == null || !player.IsConnected || player.IsDead()) return null;
if (permission.UserHasPermission(player.UserIDString, PermExempt)) return null;
if (config.ExtraDamage > 0f)
{
player.Hurt(config.ExtraDamage, Rust.DamageType.Radiation);
}
float now = UnityEngine.Time.realtimeSinceStartup;
float last;
if (lastWarn.TryGetValue(player.userID.Get(), out last) && now - last < config.WarningCooldown) return null;
lastWarn[player.userID.Get()] = now;
player.ChatMessage(Msg("Warning", player.UserIDString));
return null;
}
}
}The plugin declares OnEntityEnter with a TriggerBase parameter and checks the trigger type with as BasePlayer. It returns null immediately when the entering entity is not a connected player, or when the trigger is not a TriggerRadiation. For radiation zones it applies a configurable damage multiplier by calling Hurt on the player and sends a localized warning through Oxide's language system, with a per-player cooldown so the message does not spam. Because the hook returns null in every path, vanilla zone behavior is untouched and the player is still tracked by the trigger.
Common use cases
Warn players entering radiation zones
Detect
TriggerRadiationentry and send a localized chat reminder, and optionally apply extra damage or slow them down while inside the zone.Block zone registration for specific players
Return a non-null value to stop the trigger from tracking a player, for example to make an admin immune to a custom comfort or damage zone.
Track custom trigger zones
Log or notify an event when a player enters a custom
TriggerBasesubclass placed on the map, without modifying the trigger's own behaviour.
Pitfalls
Comfort triggers only report players and horses
TriggerComfort.OnEntityEnteris only called forBasePlayerandRidableHorse, so you will never see animals or NPCs there. Use a generic trigger if you need broader coverage.Returning non-null changes vanilla behavior
Any non-null return stops the entity from being added to the trigger's set. For radiation, comfort or damage zones this can silently disable the zone's effect for that entity.
Throttle messages
The hook fires on every entry and can be called repeatedly when players walk across zone boundaries. Use a cooldown or only react to specific trigger types to avoid chat spam and expensive work.
Build a plugin with OnEntityEnter
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 OnEntityEnter
Generate