OnEntitySnapshot
OnEntitySnapshot is called when the server is about to serialize and send a network snapshot of an entity to a specific client connection.
object OnEntitySnapshot(BaseNetworkable entity, Network.Connection connection)Parameters
| Parameter | Type | Description |
|---|---|---|
entity | BaseNetworkable | The networked entity whose snapshot the server is about to serialize for a client. Check `entity.IsDestroyed` and the concrete type before acting on it. |
connection | Network.Connection | The client connection the snapshot is being sent to. Retrieve the player with `connection.player as BasePlayer`; it can be null during connection setup or for non-player connections. |
Return value
Returning null lets the original serialization proceed normally. Returning any non-null value prevents the snapshot from being written for that entity and connection, which hides the entity from that client for that update; return a value only for the specific cases you intend to block.
How it works
The hook fires inside entity snapshot serialization. BaseNetworkable.SendAsSnapshot calls it once per outgoing snapshot write, and BasePlayer.SendEntitySnapshot calls it while a player receives an entity described inside their own player snapshot. Both the plain and the pre-allocated NetWrite overloads of SendAsSnapshot are patched, so the hook runs for every snapshot dispatch regardless of the write path used.
Snapshot traffic is continuous: movement updates, new entity spawns, and visibility changes all produce snapshots, so this hook runs extremely frequently. Treat it as a hot path. Use connection to identify the receiving client (connection.player as BasePlayer) and entity to inspect what is being sent, filtering by entity is BasePlayer, LootableCorpse, or entity.net.ID.Value.
Declaring entity as a narrower type such as BasePlayer or BaseCorpse makes Oxide skip your method when the argument is a different type, which is the cheapest way to cut the call volume. Because this hook fires before serialization, return values let you suppress a snapshot entirely rather than modify it.
Example plugin: Hide lootable corpses from players beyond a distance limit
using System.Linq;
using System;
using Newtonsoft.Json;
using Oxide.Core;
using UnityEngine;
namespace Oxide.Plugins
{
[Info("Corpse Snapshot Limiter", "RustPluginGenerator", "1.0.0")]
[Description("Stops the server from sending lootable corpse snapshots to players beyond a distance limit")]
public class CorpseSnapshotLimiter : RustPlugin
{
private PluginConfig config;
private class PluginConfig
{
[JsonProperty("Enable corpse snapshot limiting")]
public bool Enabled = true;
[JsonProperty("Maximum snapshot distance (meters)")]
public float MaxDistance = 80f;
}
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);
private object OnEntitySnapshot(LootableCorpse corpse, Network.Connection connection)
{
if (!config.Enabled || corpse == null || connection == null) return null;
var player = connection.player as BasePlayer;
if (player == null || !player.IsConnected) return null;
// Compare squared distances to avoid a square root on this hot path.
float maxDistance = Mathf.Max(config.MaxDistance, 0f);
if ((player.transform.position - corpse.transform.position).sqrMagnitude <= maxDistance * maxDistance) return null;
return true;
}
}
}The plugin targets one of the heaviest snapshot sources on busy servers: player and NPC corpses. OnEntitySnapshot narrows the entity parameter to LootableCorpse so Oxide calls it only for corpses, then resolves the receiving player from connection.player. If the corpse is further away than the configured distance, the hook returns true, which stops the snapshot write and keeps the corpse unknown to that client. The config exposes the distance limit and a global kill switch for quick tuning, and the distance is squared manually to avoid a square root on a hot hook. Nearby players still get normal snapshots, so looting and corpse interaction are unaffected for them.
Common use cases
Reduce network traffic from distant corpses
Block corpse snapshots for players outside a configurable range so large battlefields do not flood clients with corpse descriptions they will not loot.
Hide admin-mode entities from regular players
Return a value when the entity is a marker or test object and the receiver lacks a permission, keeping it out of normal clients' snapshots.
Diagnose snapshot load
Count calls per entity type over a short window started by an admin command, then stop counting so the hot path stays cheap.
Pitfalls
This hook fires constantly
Do not do LINQ queries, string formatting, or distance checks against every player inside the callback. Narrow the parameter type, cache lookups, and exit early.
connection.player can be null
During connection handshakes or for non-player connections the player reference is missing. Always null-check before reading UserIDString or permissions.
Suppressed snapshots may never be re-sent
Blocking a snapshot leaves the client without that entity's state until the server sends a new one for the same connection. Only suppress entities the client does not need to interact with.
Build a plugin with OnEntitySnapshot
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 OnEntitySnapshot
Generate