OnQueueCycle
OnQueueCycle is called at the start of every ConnectionQueue.Cycle, before the server admits queued players into free connection slots. Returning a non-null value skips that cycle entirely.
object OnQueueCycle(int availableSlots)Parameters
| Parameter | Type | Description |
|---|---|---|
availableSlots | int | Number of connection slots the server has free for the current queue cycle. Passed by ConnectionQueue.Cycle; useful for deciding whether to let new players in or hold the queue. |
Return value
Return null (or any null object) to let the queue cycle proceed normally. Returning any non-null value stops the injected call and makes ConnectionQueue.Cycle return early, so no queued players are admitted and reserved-slot cleanup is skipped for that cycle. The return value itself is not used.
How it works
The hook fires from ConnectionQueue.Cycle(int availableSlots) on the server's connection queue, which runs frequently while players are waiting to join. availableSlots is how many connections the server can accept this cycle. Because the hook is dispatched before any queue processing, returning a non-null object makes Cycle return immediately: no players move from the queue into the server, and cleanup of reserved slots is also skipped for that pass. Returning null lets the normal admission logic run.
There are no other injection points, so this hook cannot filter individual players — it only gates the whole cycle. To act on specific players use OnConnectionDequeue or OnConnectionQueue. Declaring availableSlots as int is required; there is no more specific type to narrow by.
Because it fires often, keep the body cheap and avoid logging on every call. A typical use is to pause admissions under a condition (for example a maintenance flag or a slot threshold) and let them resume later.
Example plugin: Pause queue admissions during maintenance
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;
namespace Oxide.Plugins
{
[Info("Queue Maintenance Hold", "RustPluginGenerator", "1.0.0")]
[Description("Pauses Rust connection queue admissions while a maintenance flag is enabled.")]
public class QueueMaintenanceHold : RustPlugin
{
private const string PermUse = "queuemaintenancehold.use";
private const string DataFile = "QueueMaintenanceHold";
private PluginConfig config;
private StoredData data;
private class PluginConfig
{
[JsonProperty("Held slot count reported to staff")]
public int ReportedSlots { get; set; } = 0;
}
private class StoredData
{
[JsonProperty("Hold admissions")]
public bool Hold { get; set; }
}
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>
{
["Enabled"] = "Queue hold enabled. Queued players will not be admitted.",
["Disabled"] = "Queue hold disabled. Admissions resumed.",
["Status"] = "Queue hold is currently {0}.",
["NoPerm"] = "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(PermUse, this);
data = Interface.Oxide.DataFileSystem.ReadObject<StoredData>(DataFile) ?? new StoredData();
}
[ChatCommand("queuehold")]
private void CmdQueueHold(BasePlayer player, string command, string[] args)
{
if (player == null) return;
if (!player.IsAdmin && !permission.UserHasPermission(player.UserIDString, PermUse))
{
player.ChatMessage(Msg("NoPerm", player.UserIDString));
return;
}
ToggleHold(player.UserIDString);
}
[ConsoleCommand("queuehold.toggle")]
private void CcmdToggle(ConsoleSystem.Arg arg)
{
if (arg == null || !arg.IsAdmin) return;
ToggleHold(null, arg);
}
private void ToggleHold(string userId, ConsoleSystem.Arg arg = null)
{
data.Hold = !data.Hold;
Interface.Oxide.DataFileSystem.WriteObject(DataFile, data);
string msg = data.Hold ? Msg("Enabled") : Msg("Disabled");
if (arg != null) arg.ReplyWith(msg);
else
{
BasePlayer player = BasePlayer.FindByID(ulong.Parse(userId));
if (player != null) player.ChatMessage(msg);
}
}
private object OnQueueCycle(int availableSlots)
{
if (!data.Hold) return null;
return true;
}
private void Unload()
{
if (data != null) Interface.Oxide.DataFileSystem.WriteObject(DataFile, data);
}
}
}The plugin adds a queuehold.toggle chat command for admins (also usable from RCON via the console command wrapper) that flips a persisted maintenance flag using oxide/data. While the flag is on, OnQueueCycle returns a non-null object, which makes ConnectionQueue.Cycle return before admitting anyone, so queued players stay queued. State is saved on every toggle and loaded on startup; the reply uses registered lang messages. availableSlots is included in the admin feedback so staff see how many slots are being held back.
Common use cases
Freeze the queue during restarts
Hold admissions while a maintenance window or plugin reload is in progress by returning a value from OnQueueCycle, then release once the server is ready.
Cap admissions by slot count
Inspect availableSlots and skip cycles when the free slot count exceeds a threshold you want to throttle, letting the queue drain more gradually.
Delay admissions until a whitelist check passes
Block cycles while a dependent plugin or external state is still initializing, so players are not admitted before permissions and data are ready.
Pitfalls
Blocking the queue for everyone
A non-null return skips the entire cycle, so every queued player is held, including admins. Gate the block behind a flag and make sure you can clear it from console.
High-frequency hook
Cycle runs repeatedly while players wait. Avoid PrintWarning, chat broadcasts, or data writes in the hook body; do that work in the command handler instead.
Forgetting to release the hold
If the plugin is unloaded while holding the queue, the flag must be reloaded correctly on startup or players stay stuck. Persist the flag and clear it explicitly.
Build a plugin with OnQueueCycle
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 OnQueueCycle
Generate