OnExcavatorMiningToggled
OnExcavatorMiningToggled is called when the giant excavator at the HQM quarry switches between mining and idle, once from ExcavatorArm.BeginMining and once from ExcavatorArm.StopMining.
void OnExcavatorMiningToggled(ExcavatorArm excavatorArm)Parameters
| Parameter | Type | Description |
|---|---|---|
excavatorArm | ExcavatorArm | The ExcavatorArm entity whose mining state changed. Never null when the hook runs; use it to read its position, owner, flags and current mining status. |
Return value
Both injection points ignore the return value, so returning null, true or any object never changes whether the excavator starts or stops mining. Use the hook purely as a notification; to influence output you need the resource hooks instead.
How it works
The hook fires at the end of both state transitions of the ExcavatorArm entity: BeginMining after the server switches the excavator effects on, registers the start time and sends the world notification, and StopMining after the mining effects are disabled, the resource production invoke is cancelled and the On flag is cleared. Because both paths call the hook, the parameter itself carries no direction flag. Determine the direction either by checking excavatorArm.HasFlag(BaseEntity.Flags.On) (set while mining, cleared in StopMining before the hook call) or by comparing excavatorArm.excavatorStartTime against the current network time. You can also track state yourself by remembering the last seen value per arm.
The hook only exists on the excavator arm, so you do not need to filter entities. Declaring the parameter as ExcavatorArm already narrows dispatch to that type; there is no useful narrower type. Use it for notifications, event hooks such as double-yield windows, statistics about how long the excavator runs, or for kicking off timers that should only run while mining is active. The return value is ignored on both sites.
Example plugin: Announce excavator start and stop and log mining durations
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;
using UnityEngine;
namespace Oxide.Plugins
{
[Info("Excavator Mining Announcer", "RustPluginGenerator", "1.0.0")]
[Description("Announces excavator start and stop events and reports how long mining ran")]
public class ExcavatorMiningAnnouncer : RustPlugin
{
private class PluginConfig
{
[JsonProperty("Broadcast start and stop to all players")]
public bool Broadcast { get; set; } = true;
[JsonProperty("Log mining durations to server console")]
public bool LogDurations { get; set; } = true;
}
private PluginConfig config;
private readonly Dictionary<ulong, float> miningStart = new Dictionary<ulong, float>();
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>
{
["Started"] = "The HQM quarry excavator has started mining.",
["Stopped"] = "The HQM quarry excavator has stopped mining.",
["RanFor"] = "The excavator ran for {0}."
}, this);
}
private string Msg(string key, string userId = null, params object[] args) => string.Format(lang.GetMessage(key, this, userId), args);
private void OnExcavatorMiningToggled(ExcavatorArm excavatorArm)
{
if (excavatorArm == null) return;
ulong id = excavatorArm.net.ID.Value;
bool isMining = excavatorArm.HasFlag(BaseEntity.Flags.On);
if (isMining)
{
miningStart[id] = UnityEngine.Time.realtimeSinceStartup;
if (config.Broadcast) Server.Broadcast(Msg("Started"));
return;
}
float duration = 0f;
if (miningStart.TryGetValue(id, out float startTime))
{
duration = UnityEngine.Time.realtimeSinceStartup - startTime;
miningStart.Remove(id);
}
if (config.Broadcast) Server.Broadcast(Msg("Stopped"));
if (config.LogDurations && duration > 0f)
{
PrintWarning(string.Format("Excavator {0} at {1} mined for {2:0}s", id, excavatorArm.transform.position, duration));
}
}
private void Unload()
{
miningStart.Clear();
}
}
}The plugin listens to OnExcavatorMiningToggled and works out the direction by reading the On flag on the arm: BeginMining sets it before calling the hook, StopMining clears it. On start it stores the current time per arm network id, broadcasts a chat message to all players and logs a warning to the server console with the arm position. On stop it loads the stored start time, computes the run duration and broadcasts how long the excavator ran. State is kept in a Dictionary<ulong, float> guarded by null checks, and the dictionary is cleared in Unload. Messages go through the language file so admins can translate them.
Common use cases
Global announcements
Broadcast to all players when the excavator starts or stops so groups know when the HQM quarry is active and worth contesting.
Mining statistics
Record start time and duration per arm to report which teams ran the excavator and for how long, useful for wipe stats or admin audits.
Event windows
Start a timed multiplier window the moment mining begins, and cancel it on the next stop, so bonus output only applies while the excavator is actually running.
Pitfalls
No direction parameter
The same hook signature is used for start and stop. Reading
Flags.Onor tracking the previous value yourself is required; assuming every call means 'started' leads to wrong announcements.Called for every arm
Each ExcavatorArm entity raises the hook independently. Use
excavatorArm.net.ID.Valueas a key if you store state, otherwise data from one arm overwrites another.Return value does nothing
Returning
falseor any other value does not cancel mining. If you need to control resource output, use the excavator gather hooks instead.
Build a plugin with OnExcavatorMiningToggled
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 OnExcavatorMiningToggled
Generate