OnBoomboxToggle
OnBoomboxToggle is called when a player toggles playback on a boombox, right before the server applies the new play state. Returning a non-null value cancels that change.
object OnBoomboxToggle(BoomBox boomBox, BasePlayer player, bool flag)Parameters
| Parameter | Type | Description |
|---|---|---|
boomBox | BoomBox | The BoomBox entity whose play/pause state is changing. Can be a handheld boombox item entity or a DeployableBoomBox. |
player | BasePlayer | The BasePlayer who sent the toggle request. Can be null, so always check before reading player members. |
flag | bool | True when the player is starting playback, false when they are stopping it. |
Return value
Returning null lets the toggle proceed and the server updates the boombox play state. Returning any non-null value aborts ServerTogglePlay before the state change is applied, so the boombox stays in its previous state. Because the method returns void, the value itself is discarded — only null vs non-null matters.
How it works
The hook fires inside BoomBox.ServerTogglePlay, which runs when a client sends the toggle-play message for a boombox. The arguments are the BoomBox entity, the BasePlayer who requested the change, and a bool that is true for starting playback and false for stopping it.
Because BoomBox is the declared parameter type and the hook is passed the entity directly, you can inspect subtype data: cast to DeployableBoomBox to check radio/station state, or treat it as a placed entity when it is not held. player can be null (the RPC carries a player reference but it is not guaranteed connected), so null-check it. Use flag to distinguish starting from stopping playback — for example to block only the start of music.
The hook fires only on the toggle path, not on volume changes or station changes; those are separate hooks. If you only care about one direction, test flag and return null otherwise. Avoid chatty logging here since it fires on each toggle.
When you declare BoomBox as the parameter type, Oxide skips nothing meaningful here because the injected argument is always that type, but declaring BaseEntity would also match. Return handling is described below.
Example plugin: Block boombox playback while the player is building blocked
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;
using UnityEngine;
namespace Oxide.Plugins
{
[Info("Boombox Toggle Guard", "RustPluginGenerator", "1.0.0")]
[Description("Blocks starting boombox playback for players who are building blocked.")]
public class BoomboxToggleGuard : RustPlugin
{
private const string PermBypass = "boomboxtoggleguard.bypass";
private PluginConfig config;
private class PluginConfig
{
[JsonProperty("Deny when building blocked")]
public bool DenyWhenBuildingBlocked { get; set; } = 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"] = "You cannot start boombox music here."
}, 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(PermBypass, this);
config = config ?? new PluginConfig();
}
private object OnBoomboxToggle(BoomBox boomBox, BasePlayer player, bool flag)
{
if (boomBox == null || !flag)
return null;
if (player == null || !player.IsConnected || player.IsNpc)
return null;
if (!config.DenyWhenBuildingBlocked)
return null;
if (permission.UserHasPermission(player.UserIDString, PermBypass))
return null;
if (!player.IsBuildingBlocked())
return null;
player.ChatMessage(Msg("Blocked", player.UserIDString));
return true;
}
}
}The plugin blocks a player from starting boombox playback when they are building blocked, which stops music being used to leak information inside restricted zones while keeping normal toggles working.
OnBoomboxToggle checks flag so only the start action is evaluated. It confirms the player is connected and not NPC, then calls IsBuildingBlocked(). When blocked, the plugin returns a non-null value (an empty object) which cancels the state change, and sends the player a single chat line from language messages. Otherwise it returns null and the toggle goes through. A permission, boomboxtoggleguard.bypass, lets trusted players skip the check; it is registered in Init and checked before the building-block test. There are no timers or config needed, keeping the plugin minimal.
Common use cases
Disable boomboxes in event areas
Return a non-null value from the hook when a boombox is inside a PvP zone or monument radius so playback cannot be started there.
Combat logging of music
Use the hook to notify admins or log when a specific player starts playback, while returning null so the toggle still works.
Permission gating of playback
Deny the start toggle when a player lacks a permission, allowing servers to restrict boomboxes to a donor group.
Pitfalls
Blocking both play and stop
Always check
flagbefore returning non-null. If you block the stop toggle too, a boombox can never be turned off until it despawns, which confuses players.Assuming player is non-null
The player argument can be null. Reading player.UserIDString or IsBuildingBlocked without a null check throws each time the hook fires.
Build a plugin with OnBoomboxToggle
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 OnBoomboxToggle
Generate