OnExperimentStart
OnExperimentStart is called when a player begins an experiment at a Workbench, right before the workbench consumes the input item and starts the experiment cycle. Returning a non-null value cancels the experiment.
object OnExperimentStart(Workbench workbench, BasePlayer player)Parameters
| Parameter | Type | Description |
|---|---|---|
workbench | Workbench | The Workbench entity that the player is interacting with. Use it to read the workbench tier (via the workbench's position/upgrade level or type), block experiments by returning a value, or send feedback near it. |
player | BasePlayer | The BasePlayer who triggered the experiment RPC. Use it to check permissions, health, inventory state, or to send a chat/UI message before the experiment proceeds. |
Return value
Returning null lets the experiment run normally. Returning any non-null value (even false or 0) makes the patched method return early, so the input item is not consumed and no experiment starts; the value itself is not otherwise used.
How it works
This hook fires inside Workbench.RPC_BeginExperiment, after the game has confirmed the workbench tier still has locked items for the player and immediately before it reads slot 0 of the inventory to consume the experiment input. It runs only for the player who sent the RPC to that specific workbench, so the workbench parameter is the exact entity being used and player is the caller. Because it fires before any item is taken, returning a value here prevents the experiment entirely with no side effects. The hook fires often on busy servers (anyone scrapping for blueprints), so avoid heavy work or logging in it. You can narrow dispatch by declaring the first parameter as a more specific type, but Workbench is already the concrete class, so narrowing rarely adds value; instead gate on the workbench tier or the player inside the method.
Example plugin: Block experiments at Tier 3 workbenches
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;
namespace Oxide.Plugins
{
[Info("WorkbenchExperimentGuard", "RustPluginGenerator", "1.0.0")]
[Description("Blocks experiments at configured workbench tiers with an optional permission bypass.")]
public class WorkbenchExperimentGuard : RustPlugin
{
private const string PermBypass = "workbenchexperimentguard.bypass";
private PluginConfig config;
private class PluginConfig
{
[JsonProperty("Block tier 1 workbenches")]
public bool BlockTier1 = false;
[JsonProperty("Block tier 2 workbenches")]
public bool BlockTier2 = false;
[JsonProperty("Block tier 3 workbenches")]
public bool BlockTier3 = 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>
{
["Blocked"] = "Experiments are disabled at this workbench tier."
}, this);
}
private string Msg(string key, string userId = null) => lang.GetMessage(key, this, userId);
private void Init()
{
permission.RegisterPermission(PermBypass, this);
}
private object OnExperimentStart(Workbench workbench, BasePlayer player)
{
if (workbench == null || player == null || player.IsNpc)
return null;
if (permission.UserHasPermission(player.UserIDString, PermBypass))
return null;
if (!IsBlocked(workbench))
return null;
player.ChatMessage(Msg("Blocked", player.UserIDString));
return false;
}
private bool IsBlocked(Workbench workbench)
{
if (config.BlockTier1 && workbench.HasFlag(BaseEntity.Flags.Reserved8))
return true;
if (config.BlockTier2 && workbench.HasFlag(BaseEntity.Flags.Reserved9))
return true;
if (config.BlockTier3 && workbench.HasFlag(BaseEntity.Flags.Reserved10))
return true;
return false;
}
}
}The plugin reads a config flag and blocks experiments performed at high-tier workbenches, useful on servers that want to force players to use specific bench tiers for blueprint research. On OnExperimentStart it checks the workbench tier by comparing against the configured blocked tiers and, if matched, sends the player a localized message and returns false to stop the game from consuming the item. The tier is detected from the workbench's flags for each tier (the game sets BaseEntity.Flags on the bench), so no prefab string parsing is required. A permission check lets admins bypass the restriction.
Common use cases
Tier gating
Restrict blueprint experimentation to specific workbench tiers so progression follows your server's rules. Return a value to cancel experiments at disallowed tiers.
Cost or cooldown enforcement
Check a player's inventory, permission, or a stored cooldown before allowing an experiment. Returning non-null stops the item from being consumed, letting you enforce your own economy.
Event or area restrictions
Block experiments while a player is inside a raid zone, event area, or has PvP combat recently, based on position checks on the workbench entity.
Pitfalls
Returning false does not mean allow
Any non-null value cancels the experiment. To let it proceed you must return null, not
trueorfalse.Fires very often
Players experiment constantly. Never call Puts or PrintWarning inside this hook; send messages only to the affected player.
Item not yet consumed
The input item in slot 0 has not been taken when the hook runs, so do not try to read or modify the consumed state; just decide whether to allow or cancel.
Build a plugin with OnExperimentStart
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 OnExperimentStart
Generate