OnHotAirBalloonToggled
OnHotAirBalloonToggled is called after a HotAirBalloon's engine state changes, once for turning on and once for turning off.
void OnHotAirBalloonToggled(HotAirBalloon hotAirBalloon, BasePlayer player)Parameters
| Parameter | Type | Description |
|---|---|---|
hotAirBalloon | HotAirBalloon | The HotAirBalloon entity whose engine state was just switched. Use it to read position, the pilot, flags and owner. |
player | BasePlayer | The BasePlayer who triggered the engine switch. Can be null for non-player toggles, so always null-check it. |
Return value
The hook's return value is ignored, so returning null or any other value does not change the engine switch. React to the toggle with side effects such as messages, timers or data updates instead of trying to block it here.
How it works
This hook fires inside HotAirBalloon.EngineSwitch after the balloon's engine toggle has already been applied. The game checks the new state: if the engine is now on it schedules ScheduleOff for 60 seconds and then calls the hook; if the engine is now off it cancels that invoke and calls the hook. In both cases the balloon's On flag has already been updated, so hotAirBalloon.IsOn() reflects the new state, and it is safe to check it to learn which direction the toggle went. Because the hook fires after the switch, this is a notification rather than a veto point; the original method returns void, so the return value has no effect.
player is the player passed along with the engine switch message and may be null. Declaring a more specific parameter type gives no benefit here since there is only one balloon type; instead guard against a null player and a destroyed or null balloon. Use the hook to react to engine usage: warn nearby players, log balloon activity, charge a fuel or usage fee, or broadcast that a balloon has been started or stopped. Avoid heavy work or per-tick logic.
Example plugin: Announce and charge for hot air balloon engine use
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;
using Oxide.Core.Plugins;
using UnityEngine;
namespace Oxide.Plugins
{
[Info("Balloon Engine Monitor", "RustPluginGenerator", "1.0.0")]
[Description("Announces hot air balloon engine toggles and optionally charges a usage fee.")]
public class BalloonEngineMonitor : RustPlugin
{
private const string PermDiscount = "balloonenginemonitor.discount";
[PluginReference] private Plugin Economics;
private PluginConfig config;
private class PluginConfig
{
[JsonProperty("Broadcast toggles to all players")]
public bool BroadcastToggles { get; set; } = false;
[JsonProperty("Charge a fee per toggle")]
public bool ChargeFee { get; set; } = false;
[JsonProperty("Fee amount")]
public float FeeAmount { get; set; } = 25f;
}
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>
{
["BroadcastOn"] = "{0} started a hot air balloon engine.",
["BroadcastOff"] = "{0} stopped a hot air balloon engine.",
["FeeCharged"] = "You paid {0} for using the balloon engine.",
["NoFunds"] = "You cannot afford the balloon engine fee of {0}."
}, 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(PermDiscount, this);
}
private void OnHotAirBalloonToggled(HotAirBalloon hotAirBalloon, BasePlayer player)
{
if (hotAirBalloon == null || hotAirBalloon.IsDestroyed) return;
bool running = hotAirBalloon.IsOn();
string playerName = player != null ? player.displayName : "Someone";
if (config.BroadcastToggles)
{
string key = running ? "BroadcastOn" : "BroadcastOff";
Server.Broadcast(string.Format(lang.GetMessage(key, this), playerName));
}
if (!config.ChargeFee || player == null || Economics == null || config.FeeAmount <= 0f) return;
float fee = config.FeeAmount;
if (permission.UserHasPermission(player.UserIDString, PermDiscount)) fee *= 0.5f;
bool paid = Economics.Call("Withdraw", player.UserIDString, (double) fee) is bool result && result;
if (paid)
{
player.ChatMessage(Msg("FeeCharged", player.UserIDString, fee));
}
else
{
player.ChatMessage(Msg("NoFunds", player.UserIDString, fee));
}
}
}
}The plugin reacts to every hot air balloon engine toggle. On load it reads a config that controls whether usage is broadcast to the server and whether a per-toggle cost is collected through the optional Economics plugin. When OnHotAirBalloonToggled fires, it null-checks the balloon and player, then checks hotAirBalloon.IsOn() to learn whether the engine was switched on or off, taking the schedule-off timer into account. It broadcasts a short chat line with the player name and balloon state, and if Economics is loaded and the price is above zero it calls Withdraw and informs the player. Messages are localized through the language file, and Init registers the permission that gates the fee.
Common use cases
Log balloon engine activity
Write a line to a data file or a broadcast each time a player starts or stops a balloon engine, useful for staff auditing vehicle use on busy servers.
Charge a fuel or usage fee
Deduct a configurable amount of currency per toggle via Economics to give balloon travel a running cost.
Notify nearby players
When a balloon engine turns on, warn players near it that a balloon is starting to lift, giving them a chance to climb aboard or move clear.
Pitfalls
The engine state is already changed
The hook fires after the toggle is applied, so use
hotAirBalloon.IsOn()to tell on from off. Blocking is not possible from this hook.Player can be null
Some engine switches are not driven by a connected player, so
playermay be null. Null-check before readingdisplayNameor calling anything on it.Called twice per switch cycle
Both the on and off branches call the hook, so any fee or message logic runs for each direction. Decide in your code whether to act only when the engine is on.
Build a plugin with OnHotAirBalloonToggled
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 OnHotAirBalloonToggled
Generate