OnDeepSeaTeleport
OnDeepSeaTeleport is called when an entity enters a deep sea portal trigger and the portal is about to teleport it. Returning a non-null value cancels the teleport.
object OnDeepSeaTeleport(TriggerDeepSeaPortal triggerDeepSeaPortal, BaseEntity ent)Parameters
| Parameter | Type | Description |
|---|---|---|
triggerDeepSeaPortal | TriggerDeepSeaPortal | The TriggerDeepSeaPortal entity the entity walked into. It carries the portal state and its owning DeepSeaPortal, so you can read PortalMode and position from it. |
ent | BaseEntity | The entity that entered the deep sea portal trigger. In practice this is a player or a vehicle (boat, sub, car) whose bounds overlapped the trigger. |
Return value
Returning null lets the game proceed with its normal entrance/exit teleport logic. Returning any non-null object stops the original code path for that entity, so the entity stays where it is and no teleport, effect, or portal cooldown runs.
How it works
The hook fires inside TriggerDeepSeaPortal.OnEntityEnter, after the game has checked the trigger's WillTeleport flag and before the portal decides whether it is an entrance or an exit and moves the entity. The triggerDeepSeaPortal parameter is the trigger that was entered, and ent is the entity that entered it. In practice ent is usually a BasePlayer on foot or the vehicle the player is driving, since deep sea portals sit at the transition between the surface and the underwater monument.
Because Oxide dispatches by declared parameter type, you can type the second parameter as BasePlayer to only be called for players on foot, or as BaseVehicle/MiniCopter to narrow it to mounts. Declaring BaseEntity (as the signature does) catches everything and lets you inspect ent yourself.
Returning non-null blocks the teleport for that entity only; other entities entering the same trigger still get processed. The hook fires on every entry attempt, so avoid logging or expensive work inside it.
Example plugin: Block deep sea teleports during a cooldown or when the player is wanted
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;
namespace Oxide.Plugins
{
[Info("Deep Sea Teleport Guard", "RustPluginGenerator", "1.0.0")]
[Description("Adds a cooldown and optional permission check to deep sea portal teleports")]
public class DeepSeaTeleportGuard : RustPlugin
{
private const string PermUse = "deepseateleportguard.use";
private PluginConfig config;
private StoredData data;
private class PluginConfig
{
[JsonProperty("Cooldown seconds between teleports")]
public int Cooldown = 300;
[JsonProperty("Require permission")]
public bool RequirePermission = false;
}
private class StoredData
{
[JsonProperty("Last teleport (unix seconds per user id)")]
public Dictionary<string, int> LastTeleport = new Dictionary<string, int>();
}
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>
{
["Cooldown"] = "Deep sea portal is on cooldown. Try again in {0} seconds.",
["NoPermission"] = "You do not have permission to use deep sea portals."
}, 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(PermUse, this);
data = Interface.Oxide.DataFileSystem.ReadObject<StoredData>(Name) ?? new StoredData();
}
private object OnDeepSeaTeleport(TriggerDeepSeaPortal triggerDeepSeaPortal, BaseEntity ent)
{
if (triggerDeepSeaPortal == null || ent == null) return null;
var player = ent as BasePlayer;
if (player == null) return null;
if (config.RequirePermission && !permission.UserHasPermission(player.UserIDString, PermUse))
{
player.ChatMessage(Msg("NoPermission", player.UserIDString));
return "blocked";
}
if (config.Cooldown > 0)
{
int now = Facepunch.Math.Epoch.Current;
int last;
if (data.LastTeleport.TryGetValue(player.UserIDString, out last))
{
int remaining = config.Cooldown - (now - last);
if (remaining > 0)
{
player.ChatMessage(Msg("Cooldown", player.UserIDString, remaining));
return "cooldown";
}
}
data.LastTeleport[player.UserIDString] = now;
}
return null;
}
private void Unload()
{
Interface.Oxide.DataFileSystem.WriteObject(Name, data);
}
}
}The plugin registers a permission and a configurable cooldown. When a portal trigger is entered, the hook narrows the entity to a BasePlayer: mounted vehicles are ignored because the player enters via their mount. It reads the player id, checks the stored last-teleport timestamp and refuses the teleport if the cooldown has not elapsed, sending a localized message instead of return null. It also blocks players lacking the permission when that check is enabled. On a successful teleport the timestamp is updated and, since timers cannot be relied on for long cooldowns, the data is flushed in Unload.
Common use cases
Cooldown between deep sea trips
Stop players from hopping back and forth through a portal by returning non-null when their stored last-teleport time is too recent. This keeps the underwater loot loop paced without editing portal prefabs.
Restrict portals by permission or team
Only allow members of a given permission group or team to use deep sea portals, or block solo players from following a team that already entered. The hook gives you the entering entity before the move happens.
Cancel teleports during server events
Hook into a scheduled event flag in your plugin and return a dummy object while it is active, so portals stay inert until the event ends. Because the return cancels per entity, other mechanics keep running.
Pitfalls
The entity may be a vehicle
If you declare
BasePlayeryou will miss mounted players and vehicles that pass through the trigger. Either handleBaseVehicleseparately or keepBaseEntityand inspectent as BasePlayerplusGetMounted().Returning false is not a cancel
The injection checks the return value against null, so returning
falseor0still counts as non-null and blocks the teleport. Always return a real object reference such as a string marker when you intend to block.Fires for both entrance and exit
The call runs before the game branches on
PortalMode, so the same hook covers surface-to-deep-sea and back. If your rule should only apply one way, inspecttriggerDeepSeaPortal.Portaland its mode.
Build a plugin with OnDeepSeaTeleport
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 OnDeepSeaTeleport
Generate