Skip to content
RustPluginGenerator

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.

Signature
object OnPlayerWound(BasePlayer player, HitInfo info)

Parameters

Hook parameters
ParameterTypeDescription
playerBasePlayerThe BasePlayer who is entering the wounded (crawling) state. Never null when the hook fires from BecomeWounded.
infoHitInfoThe 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

WoundToDeath.cs
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.InitiatorPlayer and 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

    BecomeWounded is not always called with a HitInfo. Dereferencing info.damageTypes without 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. Use OnPlayerRecover for 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 Hurt or Die yourself, 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.

Prompt: Instant-kill rules for PvP servers using the OnPlayerWound hook, with a config file and a permission
Generate this plugin

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