OnDebrisSpawn
OnDebrisSpawn is called from DecayEntity.SpawnDebris right before a decaying entity spawns its visual debris pieces. Returning a non-null value cancels the debris spawn for that call.
object OnDebrisSpawn(DecayEntity decayEntity, UnityEngine.Vector3 localPos, UnityEngine.Quaternion rot, bool dropToTerrain)Parameters
| Parameter | Type | Description |
|---|---|---|
decayEntity | DecayEntity | The DecayEntity whose SpawnDebris method is running, normally a building block, deployable or other decaying structure. Use it to identify the owner, position and type of the entity producing debris. |
localPos | UnityEngine.Vector3 | Debris spawn position in the entity's local space. Combine with decayEntity.transform.TransformPoint(localPos) to get a world position. |
rot | UnityEngine.Quaternion | The rotation passed to the debris spawn, in world space. |
dropToTerrain | bool | True when the game will raycast downward from the spawn point (up to 6 units) and snap the debris onto the first hit surface. |
Return value
Returning null lets the original SpawnDebris code run and the debris spawns normally. Returning any non-null value (for example true) makes the method return immediately, so no debris is spawned for that call.
How it works
This hook fires inside DecayEntity.SpawnDebris, which the game calls when a decaying structure or deployable breaks apart and emits debris (for example a building block being destroyed by decay or damage). The arguments are the entity itself, the debris position in local space, the rotation and whether the debris will be dropped onto the terrain via a short downward raycast. Because the only parameter that is a game type is DecayEntity, that is the only parameter you can narrow: declaring decayEntity as BuildingBlock makes Oxide call your method only for blocks, while other DecayEntity subclasses are skipped. Other parameters must keep their types. The hook runs for every debris batch, so keep it lightweight and avoid logging. It is useful for suppressing debris (performance on busy servers), adding custom effects or drops, or conditioning debris on the entity owner. The debris position is local; convert it with decayEntity.transform.TransformPoint(localPos) if you need a world coordinate.
Example plugin: Suppress debris for twig blocks and spawn a custom effect
using System;
using Newtonsoft.Json;
using Oxide.Core;
using UnityEngine;
namespace Oxide.Plugins
{
[Info("Debris Control", "RustPluginGenerator", "1.0.0")]
[Description("Cancels or replaces debris spawned by decaying building blocks")]
public class DebrisControl : RustPlugin
{
private const string PermAdmin = "debriscontrol.admin";
private PluginConfig config;
private class PluginConfig
{
[JsonProperty("Suppress twig debris")]
public bool SuppressTwig { get; set; } = true;
[JsonProperty("Effect prefab to play instead")]
public string EffectPrefab { get; set; } = "assets/bundled/prefabs/fx/dig_effect.prefab";
}
protected override void LoadDefaultConfig() => config = new PluginConfig();
protected override void LoadConfig()
{
base.LoadConfig();
try
{
config = Config.ReadObject<PluginConfig>();
if (config == null) throw new System.Exception();
}
catch
{
PrintWarning("Configuration file is invalid, using defaults");
LoadDefaultConfig();
}
SaveConfig();
}
protected override void SaveConfig() => Config.WriteObject(config);
private void Init()
{
permission.RegisterPermission(PermAdmin, this);
}
private object OnDebrisSpawn(BuildingBlock block, Vector3 localPos, Quaternion rot, bool dropToTerrain)
{
if (block == null) return null;
bool suppress = config.SuppressTwig && block.grade == BuildingGrade.Enum.Twigs;
if (!suppress)
{
// Let vanilla debris spawn for every other grade.
return null;
}
if (!string.IsNullOrEmpty(config.EffectPrefab))
{
Vector3 worldPos = block.transform.TransformPoint(localPos);
Effect.server.Run(config.EffectPrefab, worldPos);
}
return true;
}
}
}The plugin registers the hook with BuildingBlock as the parameter type so it only runs for building blocks, not every DecayEntity. When SuppressTwig is enabled in the config and the block grade is Twigs, the hook returns true, which cancels the vanilla debris spawn. It then converts localPos to a world position and runs a configurable effect there. Other grades return null and keep default behavior. The effect prefab and toggle are loaded from oxide/config/DebrisControl.json, and no chat or console output is produced per call, keeping the hook cheap under heavy decay.
Common use cases
Reduce debris on large bases
Return true for blocks above a certain size threshold so big bases crumbling under decay do not flood the server with debris entities.
Custom destruction effects
Cancel the default debris and run your own effect or sound at the transformed world position for a themed destruction look.
Owner-based debris rules
Only allow debris for entities owned by specific players or groups, returning true otherwise to skip the spawn.
Pitfalls
Local position, not world
localPos is in the entity's local space. Using it directly as a world coordinate places effects at the wrong location; always call TransformPoint on the entity transform.
Runs very frequently
OnDebrisSpawn fires for every debris batch during decay and destruction. Avoid Puts, PrintWarning or expensive loops here; do the work once at startup instead.
Narrowing skips other entities
Declaring the first parameter as BuildingBlock means other DecayEntity types never reach your hook. Keep DecayEntity if you need to affect all decaying entities.
Build a plugin with OnDebrisSpawn
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 OnDebrisSpawn
Generate