OnLiquidVesselFill
OnLiquidVesselFill is called from BaseLiquidVessel.FillCheck just before a water vessel decides whether and how it fills, letting a plugin block the fill.
object OnLiquidVesselFill(BaseLiquidVessel liquidVessel, BasePlayer ownerPlayer, LiquidContainer facingLiquidContainer)Parameters
| Parameter | Type | Description |
|---|---|---|
liquidVessel | BaseLiquidVessel | The BaseLiquidVessel (water bucket, jug, etc.) that is running its fill check. Use it to inspect or modify the vessel's item, contents or skin. |
ownerPlayer | BasePlayer | The BasePlayer who owns the vessel and is triggering the fill. Check permissions, building privileges or team status on this player. |
facingLiquidContainer | LiquidContainer | The LiquidContainer the player is aiming at, or null when they are filling from a world water source. Null means the vessel is trying to draw from the world, not from a container. |
Return value
Return null to let the vessel fill normally. Return any non-null object (for example true) to stop the original fill path, so the vessel does not take on liquid this check. Since FillCheck returns void, the specific returned value is only used as a signal.
How it works
Oxide fires this hook inside BaseLiquidVessel.FillCheck, which the vessel runs during its normal fill update while a player holds it and is trying to collect liquid. It runs after the fill-rate calculation and after the game resolves what the player is facing, but before the actual fill logic branches on whether a LiquidContainer is present or the vessel can fill from the world.
The three parameters cover the whole decision: liquidVessel identifies the vessel, ownerPlayer identifies who is filling, and facingLiquidContainer is the container being drawn from or null when the source is the world (a lake, the ocean, a water barrel placed in the world, etc.).
Because the arguments have fixed types, declaring a more specific parameter type narrows nothing useful here: the game only passes a BaseLiquidVessel, BasePlayer and an optional LiquidContainer. The realistic lever is the return value. Only non-null returns matter; returning null lets the fill proceed normally.
Avoid heavy work in this method: it is invoked repeatedly while a player holds a fillable vessel near a source.
Example plugin: Limit water filling to players with a permission
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;
using UnityEngine;
namespace Oxide.Plugins
{
[Info("Water Fill Permission", "RustPluginGenerator", "1.0.0")]
[Description("Restricts filling water vessels to players holding a permission")]
public class WaterFillPermission : RustPlugin
{
private const string PermUse = "waterfillpermission.use";
private PluginConfig config;
private readonly Dictionary<ulong, float> lastNotice = new Dictionary<ulong, float>();
private class PluginConfig
{
[JsonProperty("Blocked message cooldown (seconds)")]
public float NoticeCooldown { get; set; } = 5f;
}
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>
{
["NoPermission"] = "You do not have permission to fill water vessels."
}, 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(PermUse, this);
}
private object OnLiquidVesselFill(BaseLiquidVessel liquidVessel, BasePlayer ownerPlayer, LiquidContainer facingLiquidContainer)
{
if (liquidVessel == null || ownerPlayer == null) return null;
if (permission.UserHasPermission(ownerPlayer.UserIDString, PermUse)) return null;
NotifyOnce(ownerPlayer);
return true;
}
private void NotifyOnce(BasePlayer player)
{
float now = Time.realtimeSinceStartup;
float last;
if (lastNotice.TryGetValue(player.userID, out last) && now - last < config.NoticeCooldown) return;
lastNotice[player.userID] = now;
player.ChatMessage(Msg("NoPermission", player.UserIDString));
}
private void Unload()
{
lastNotice.Clear();
}
}
}The plugin registers a waterfillpermission.use permission and checks it in OnLiquidVesselFill. When the player lacks the permission, the hook returns true, which stops FillCheck before any liquid is added, so the vessel simply never fills. When the player has permission it returns null and filling behaves exactly as vanilla. Messages go through the language file so admins can localize them, and a short throttled chat reply tells the player why the vessel stayed empty without spamming them on every fill tick.
Common use cases
Permission-gated water collection
Restrict filling buckets or jugs to a donor or staff permission so water collection becomes a gated resource on survival servers.
Block filling from world sources only
Return non-null when
facingLiquidContaineris null to force players to use placed water barrels instead of lakes and oceans.Area-based water restrictions
Check the owner's position against a list of restricted monuments or zones and block filling while they stand inside one.
Pitfalls
Returning false still blocks
The patched check only tests whether the return value is non-null. Returning
falsestops the fill just like returningtrue; returnnullwhen you want vanilla behavior.Fires on every fill tick
FillCheck runs repeatedly while a player holds a fillable vessel near a source, so avoid chat spam, logging and expensive lookups inside the hook. Throttle player-facing messages per player.
Null container is normal
facingLiquidContaineris null whenever the source is the world, not an error. Handle that branch explicitly instead of assuming a container exists.
Build a plugin with OnLiquidVesselFill
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 OnLiquidVesselFill
Generate