OnMeleeAttack
OnMeleeAttack is called on the server when a player performs a melee attack, after the HitInfo for the swing has been built but before the hit is validated and applied.
object OnMeleeAttack(BasePlayer player, HitInfo obj)Parameters
| Parameter | Type | Description |
|---|---|---|
player | BasePlayer | The BasePlayer swinging the melee weapon. Null-check it and its net connection before acting on the attack. |
obj | HitInfo | The HitInfo the server built for this swing. Before your hook fires, Initiator, Weapon, WeaponPrefab, Predicted and damageProperties are already filled in, so you can read or change the target, damage types and hit data. |
Return value
Returning a non-null value cancels the swing: the method returns immediately and the attack is not resolved, so no damage, durability loss or hit effect is produced for that swing. Returning null lets the attack continue unchanged.
How it works
The hook fires inside BaseMelee.PlayerAttack, which the server runs when a melee weapon swing arrives from a client. At this point the game has already set obj.Initiator to the attacking player, obj.Weapon and obj.WeaponPrefab to the BaseMelee item entity, obj.Predicted to the client connection and obj.damageProperties to the melee definition's damage settings. The hit itself has not been applied yet: right after the hook call the server checks obj.IsNaNOrInfinity() and proceeds with the attack resolution, so anything you change on the HitInfo is what the game acts on.
This makes the hook the right place to veto a swing (for example in a safe zone or during a cooldown), to adjust damage scaling per weapon or per target, or to record the swing for tracking. Declare obj as HitInfo and player as BasePlayer; narrowing player further is not useful because the caller always passes a player. Damage is not applied yet, so obj.HitEntity may still be null when the swing is aimed at nothing.
Example plugin: Make melee damage scale with weapon tier
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using UnityEngine;
namespace Oxide.Plugins
{
[Info("Melee Damage Tiers", "RustPluginGenerator", "1.0.0")]
[Description("Scales melee damage per weapon and can stop melee swings near unauthorized bases")]
public class MeleeDamageTiers : RustPlugin
{
private class PluginConfig
{
[JsonProperty("Damage multipliers by shortname")]
public Dictionary<string, float> Multipliers = new Dictionary<string, float>
{
["rock"] = 1.5f,
["torch"] = 2f,
["machete"] = 1.25f,
["knife.combat"] = 1.25f
};
[JsonProperty("Block melee inside other players' building privilege")]
public bool BlockInForeignPrivilege = true;
}
private PluginConfig config;
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 OnMeleeAttack(BasePlayer player, HitInfo obj)
{
if (player == null || obj == null || obj.Weapon == null) return null;
if (config.BlockInForeignPrivilege)
{
var privilege = player.GetBuildingPrivilege();
if (privilege != null && !privilege.IsAuthed(player))
{
return false;
}
}
string shortname = obj.Weapon.ShortPrefabName;
if (string.IsNullOrEmpty(shortname) || obj.damageTypes == null) return null;
float multiplier;
if (!config.Multipliers.TryGetValue(shortname, out multiplier)) return null;
if (Mathf.Approximately(multiplier, 1f)) return null;
obj.damageTypes.ScaleAll(multiplier);
return null;
}
}
}The plugin scales melee damage by weapon shortname before the hit is applied. In OnMeleeAttack it reads obj.Weapon.ShortPrefabName (or the weapon prefab name) and looks up a multiplier in the config; if the weapon is not listed the swing is untouched. Multipliers are applied with obj.damageTypes.ScaleAll(...), which changes every damage type on the HitInfo before the server resolves the attack. A second config option lets admins stop melee attacks near building privileges they are not authorized on, which is done by returning a non-null value so the swing is cancelled. All tunables live in the JSON config, and the plugin does no logging inside the hook to keep it cheap under heavy combat.
Common use cases
Weapon-specific damage tuning
Apply multipliers to
obj.damageTypesso certain melee weapons hit softer or harder than vanilla without touching every item definition.Cancel swings in restricted areas
Check the player's position against safe zones or private claims and return a non-null value to stop the attack before any damage lands.
Track melee usage
Count swings per weapon or per player, for example to cap attacks per minute or to feed a stats database.
Pitfalls
The HitInfo can be incomplete
The hit target may still be unknown when the hook fires, so never assume
obj.HitEntityorobj.HitPositionWorldis set; guard those checks.Cancelling skips more than damage
Returning non-null stops the whole
PlayerAttackpath, so the swing produces no hitmarker, no durability loss and no sound event from the server.Keep the hook cheap
It runs on every melee swing in combat; avoid permission lookups, allocation-heavy strings or PrintWarning inside it.
Build a plugin with OnMeleeAttack
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 OnMeleeAttack
Generate