OnWaterCollect
OnWaterCollect is called when a WaterCatcher is about to add water to its own inventory during its periodic collection tick. Returning a non-null value stops that collection for the tick.
object OnWaterCollect(WaterCatcher waterCatcher)Parameters
| Parameter | Type | Description |
|---|---|---|
waterCatcher | WaterCatcher | The WaterCatcher (small or large water barrel) that is about to add water to its inventory. Cast or check the concrete type when you need its inventory, flags or position. |
Return value
Return null to let the catcher continue and add water normally. Return any non-null object (including true) to make CollectWater return early, so no water is added this cycle. The return value itself is not used as a quantity or an item.
How it works
The hook fires from WaterCatcher.CollectWater, which the game runs on each catcher's timed collection cycle. Just before the catcher would add a water item to its inventory, Oxide calls OnWaterCollect with the catcher itself. The same hook name is also called from WaterPump.CreateWater with two arguments (WaterPump, ItemDefinition), so this overload only matches catcher calls.
The parameter is the WaterCatcher entity. Read its inventory, transform.position, OwnerID or HasFlag(BaseEntity.Flags.Reserved8) (the filled state) to decide whether the catcher should collect. Since the first argument is always a WaterCatcher, declaring it as WaterCatcher narrows dispatch to catcher calls only, not pump calls.
Note the injection returns early when the inventory is null or full or the hook returns non-null - so a catcher that is already full stops on its own either way. Keep the hook cheap: it runs on every catcher cycle, roughly once a minute per catcher, and you should not call Puts or PrintWarning here.
Other signatures
Oxide also calls OnWaterCollect from other places in the game with these parameter types. Declare the overload you need, or several:
object OnWaterCollect(WaterPump waterPump, ItemDefinition itemDefinition)
Example plugin: Skip collection for barrels with an owner
using System.Linq;
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;
namespace Oxide.Plugins
{
[Info("Water Catcher Limiter", "RustPluginGenerator", "1.0.0")]
[Description("Blocks water collection on catchers owned by players who are not whitelisted or while the feature is disabled.")]
public class WaterCatcherLimiter : RustPlugin
{
private const string PermAdmin = "watercatcherlimiter.admin";
private PluginConfig config;
private class PluginConfig
{
[JsonProperty("Enable collection")]
public bool Enabled { get; set; } = true;
[JsonProperty("Require owner online")]
public bool RequireOwnerOnline { get; set; } = false;
[JsonProperty("Whitelisted steam IDs")]
public List<string> Whitelist { get; set; } = new List<string>();
}
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>
{
["Status"] = "Collection: {0}. Whitelist size: {1}.",
["On"] = "enabled",
["Off"] = "disabled",
["Toggle"] = "Collection set to {0}.",
["NoPermission"] = "You do not have permission to use this command."
}, this);
}
private string Msg(string key, string userId = null, params object[] args)
=> string.Format(lang.GetMessage(key, this, userId), args);
private void Init()
{
permission.RegisterPermission(PermAdmin, this);
}
// Fire only for water catchers; the same hook name also fires from WaterPump.CreateWater.
private object OnWaterCollect(WaterCatcher waterCatcher)
{
if (waterCatcher == null || config == null) return null;
if (!config.Enabled) return true;
ulong ownerId = waterCatcher.OwnerID;
if (ownerId == 0) return null;
if (config.Whitelist.Contains(ownerId.ToString())) return null;
if (config.RequireOwnerOnline)
{
BasePlayer owner = BasePlayer.FindByID(ownerId);
if (owner == null || !owner.IsConnected) return true;
}
return null;
}
[ChatCommand("waterlimiter")]
private void CmdWaterLimiter(BasePlayer player, string command, string[] args)
{
if (player == null) return;
if (!player.IsAdmin && !permission.UserHasPermission(player.UserIDString, PermAdmin))
{
player.ChatMessage(Msg("NoPermission", player.UserIDString));
return;
}
if (args != null && args.Length > 0)
{
string mode = args[0].ToLowerInvariant();
if (mode == "on") config.Enabled = true;
else if (mode == "off") config.Enabled = false;
else
{
player.ChatMessage(Msg("Status", player.UserIDString, config.Enabled ? Msg("On", player.UserIDString) : Msg("Off", player.UserIDString), config.Whitelist.Count));
return;
}
SaveConfig();
player.ChatMessage(Msg("Toggle", player.UserIDString, config.Enabled ? Msg("On", player.UserIDString) : Msg("Off", player.UserIDString)));
return;
}
player.ChatMessage(Msg("Status", player.UserIDString, config.Enabled ? Msg("On", player.UserIDString) : Msg("Off", player.UserIDString), config.Whitelist.Count));
}
}
}The plugin refuses collection when a water catcher belongs to a player who is currently offline, is not in the list of allowed owners, or when the server-wide toggle is off. In OnWaterCollect it looks up the catcher's owner, checks the config list of permitted steam IDs, and returns true to block the collection. Admins who need unlimited barrels can whitelist their own ID. A short chat command prints whether the plugin is active so operators can quickly confirm the configuration is loaded and behaving as expected without touching the data directory.
Common use cases
Owner-based water limits
Block automatic collection on catchers whose owner is offline or not whitelisted, so only active players keep earning water without manual refills.
Event or raid zones
Inside a designated PvP zone, suppress collection on catchers placed there so teams cannot stockpile water during a fight.
Server-wide toggle
Expose a console command that disables natural water collection for maintenance or seasonal events and re-enables it without restarting the server.
Pitfalls
Two different signatures share the hook name
The same hook also fires from
WaterPump.CreateWaterwith aWaterPumpandItemDefinition. Declare the parameter asWaterCatcherso your handler is not invoked for pumps with an incompatible argument type.Does not affect the inventory directly
Returning a non-null value only aborts the collection for this cycle. If the catcher is already full, the game stops on its own, so blocking is only meaningful when there is room in the container.
Runs frequently per catcher
Each catcher calls the hook every collection interval (60 seconds by default plus jitter). Do not log, broadcast or iterate
BasePlayer.activePlayerListfrom the hook body.
Build a plugin with OnWaterCollect
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 OnWaterCollect
Generate