OnPlayerWound
OnPlayerWound is called when a player is about to enter the wounded state, before Rust applies the crawling state and its side effects. Returning a non-null value cancels the wounding.
object OnPlayerWound(BasePlayer player, HitInfo info)Parameters
| Parameter | Type | Description |
|---|---|---|
player | BasePlayer | The BasePlayer who is entering the wounded (crawling) state. Never null when the hook fires from BecomeWounded. |
info | HitInfo | The HitInfo describing the hit that triggered the wounding. Can be null when the server calls BecomeWounded without damage context, so always null-check it before reading damageTypes. |
Return value
Returning any non-null value stops BecomeWounded from continuing, so the player is not put into the wounded state. Returning null lets the original wounding logic run unchanged.
How it works
This hook fires inside BasePlayer.BecomeWounded(HitInfo info), which the server calls when a player's damage crosses into the wounded threshold (for example a lethal hit while a team member could revive them, or a fall that leaves them crawling). The guard at the top of the method checks IsWounded() first, so an already-wounded player will not trigger the hook again. When it does fire, player is the victim and info is the hit that caused it - useful for reading info.damageTypes.GetMajorityDamageType(), info.isHeadshot or the attacker via info.InitiatorPlayer. Because info is null when the method is invoked without damage context, guard it before use. Declaring player as a narrower type such as BasePlayer is already the exact type here; narrowing further (e.g. ScientistNPC) would skip the call for normal players. This is a good place to apply server rules about downing, announce the wound, or tag the event for stats collection.
Example plugin: Turn downing into an instant kill on a survival server
using System.Collections.Generic;
using System;
using Newtonsoft.Json;
using Oxide.Core;
using UnityEngine;
namespace Oxide.Plugins
{
[Info("Wound To Death", "RustPluginGenerator", "1.0.0")]
[Description("Instantly kills players who would otherwise enter the wounded state.")]
public class WoundToDeath : RustPlugin
{
private const string PermUse = "woundtodeath.use";
private PluginConfig config;
public class PluginConfig
{
[JsonProperty("Kill players below max health fraction")]
public float HealthFractionThreshold = 0.35f;
[JsonProperty("Ignore fall damage")]
public bool IgnoreFallDamage = true;
[JsonProperty("Notify the victim")]
public bool NotifyPlayer = true;
}
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>
{
["Wounded"] = "You were downed and finished off instead of crawling."
}, this);
}
private string Msg(string key, string userId = null, params object[] args)
{
return string.Format(lang.GetMessage(key, this, userId), args);
}
private void Init()
{
permission.RegisterPermission(PermUse, this);
}
private object OnPlayerWound(BasePlayer player, HitInfo info)
{
if (player == null || !player.IsConnected || player.IsDead())
return null;
if (config.IgnoreFallDamage && info != null && info.damageTypes != null)
{
if (info.damageTypes.GetMajorityDamageType() == Rust.DamageType.Fall)
return null;
}
if (!permission.UserHasPermission(player.UserIDString, PermUse))
return null;
float threshold = player.MaxHealth() * Mathf.Clamp01(config.HealthFractionThreshold);
if (player.health > threshold)
return null;
if (config.NotifyPlayer)
player.ChatMessage(Msg("Wounded", player.UserIDString));
float remaining = player.health;
if (remaining <= 0f)
remaining = 1f;
player.Hurt(remaining + 1f, Rust.DamageType.Bullet);
return true;
}
}
}The plugin listens on OnPlayerWound. When the feature is enabled in config, it reads the majority damage type from info and, once the player's health is at or below the configured threshold, hurts them for their remaining health plus a small buffer and returns a non-null value. That return value cancels BecomeWounded, so instead of crawling the player dies immediately. Health is capped to the configured maximum so a single wounding hit cannot spawn a death that looks like a bug, and both the notification and the kill are gated behind the woundtodeath.use permission so only opted-in players are affected. Falls are ignored by default to keep the behavior predictable.
Common use cases
Instant-kill rules for PvP servers
Force players below a health or armor threshold to die instead of crawling, removing guaranteed revives from combat.
Wound statistics and analytics
Read
info.InitiatorPlayerand the damage type to record who downed whom, then feed those numbers into your own data file for a leaderboard.Team revive protection
Cancel wounding for solo players or players without a nearby teammate, so only teams can go down and be picked back up.
Pitfalls
info can be null
BecomeWoundedis not always called with a HitInfo. Dereferencinginfo.damageTypeswithout a null check will throw and skip your logic.Not called for already-wounded players
The method returns early when
IsWounded()is true, so repeat hits on a crawling player never reach this hook. UseOnPlayerRecoverfor the reverse transition.Killing inside the hook still needs a reason
If you return non-null to cancel wounding, the player keeps their current health. Call
HurtorDieyourself, otherwise they can stay alive at near-zero health.
Build a plugin with OnPlayerWound
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 OnPlayerWound
Generate