🚦 Event Queues

Event Queues let players join an event before it starts.

This system is EventForge's event hype phase and lobby countdown flow. Instead of forcing every player into an event automatically, server owners can let players opt in, wait in a queue, optionally teleport to a lobby, and start the event with only queued players able to score.

info

Manual queues are included in EventForge v1.0.3. Classic automatic event behaviour is still the default.

---

Participation modes

EventForge supports two participation modes:

AUTOMATIC
MANUAL

---

AUTOMATIC mode

AUTOMATIC is the classic EventForge behaviour.

Players can participate normally without joining a queue.

Events start instantly when triggered by commands, schedules, votes, scheduled votes, API calls, or compatible addons.

This remains the default for new installs.

---

MANUAL mode

MANUAL opens a timed queue before the event starts.

Players join with:

/events join <event>

When the queue ends, EventForge starts the event if enough players joined.

Only queued players can score.

---

Global default mode

The global default is configured in config.yml.

participation:
  default-mode: AUTOMATIC

Keep this as AUTOMATIC if you want existing events to behave like previous EventForge versions.

Set it to MANUAL if you want events that use participation.mode: GLOBAL to open queues by default.

---

Per-event participation config

Each event can override the global mode.

participation:
  # GLOBAL = use config.yml participation.default-mode.
  # AUTOMATIC = classic EventForge behaviour.
  # MANUAL = open a timed queue before the event starts.
  mode: MANUAL

  queue-duration: 30s
  min-players: 1
  max-players: 0
  allow-leave-before-start: true

  lobby:
    enabled: false
    world: "world"
    x: 0.5
    y: 80.0
    z: 0.5
    yaw: 0
    pitch: 0

---

Participation settings

Setting	Description
mode	GLOBAL, AUTOMATIC, or MANUAL
queue-duration	How long the queue stays open
min-players	Minimum queued players required to start
max-players	Maximum queued players allowed. 0 means unlimited
allow-leave-before-start	Lets players leave before the event starts
lobby.enabled	Teleports players to a waiting lobby after joining
lobby.world	Lobby world name
lobby.x/y/z	Lobby position
lobby.yaw/pitch	Lobby facing direction

---

Queue flow

When a manual event is started, EventForge does not start the event instantly.

Flow:

event start requested
→ queue opens
→ players join with /events join <event>
→ optional lobby teleport happens
→ queue bossbar can display
→ 3, 2, 1 title countdown can display
→ event starts if enough players joined
→ only queued players can score

If not enough players join, the queue cancels and the event does not start.

---

Player commands

Join an open queue:

/events join <event>

Leave an open queue:

/events leave <event>

Teleport to an active event location:

/events tp <event>
/events teleport <event>

/events tp is for active events that have a teleport location, such as Mob Invasion.

---

Backwards compatibility

The old /events join <event> teleport behaviour still works as a fallback.

If a queue exists, /events join <event> joins the queue.

If no queue exists and the event is active with a teleport location, /events join <event> still teleports the player.

New docs should recommend:

/events tp <event>

for event teleporting.

---

Queue bossbar

Manual queues can show a live bossbar countdown.

This is configured in config.yml.

participation:
  queue-bossbar:
    enabled: true
    title: "&ePreparing for &f{event_display} &8| &f{time_left} &8| &7Joined: &f{players}&8/&f{max_players}"
    color: YELLOW
    style: SOLID

By default, the queue bossbar is disabled on new installs.

Enable it when you want a visible queue countdown.

---

Queue bossbar placeholders

{event}
{event_display}
{time_left}
{players}
{min_players}
{max_players}

Example:

title: "&ePreparing for &f{event_display} &8| &f{time_left} &8| &7Joined: &f{players}&8/&f{max_players}"

The bossbar updates when players join or leave and automatically disappears when the queue starts, cancels, reloads, or clears.

---

Queue title countdown

Manual queues can show 3, 2, 1, GO titles before the event starts.

This is configured in config.yml.

participation:
  queue-countdown:
    enabled: true
    seconds:
      - 3
      - 2
      - 1
    title: "&e{seconds}"
    subtitle: "&f{event_display} &7starts soon..."
    go-title: "&aGO!"
    go-subtitle: "&f{event_display} &7has begun!"
    fade-in: 0
    stay: 20
    fade-out: 10

By default, queue countdown titles are disabled on new installs.

The GO! title is only shown if the event actually starts.

If the queue cancels because not enough players joined, the event does not start and the GO! title is not shown.

---

Queue lobby

Manual queues can teleport players to a waiting area when they join.

participation:
  mode: MANUAL
  lobby:
    enabled: true
    world: "world"
    x: 100.5
    y: 70.0
    z: -250.5
    yaw: 90
    pitch: 0

If the lobby world or location is unavailable, EventForge still lets the player join the queue and sends a safe warning message.

It does not crash the event.

---

Minimum players

Use min-players to require enough players before the event starts.

participation:
  mode: MANUAL
  queue-duration: 30s
  min-players: 3

If fewer than 3 players join before the queue ends, the queue cancels.

---

Maximum players

Use max-players to limit queue size.

participation:
  mode: MANUAL
  max-players: 10

Use 0 for unlimited:

max-players: 0

---

Leaving queues

Allow players to leave before the event starts:

allow-leave-before-start: true

Block leaving:

allow-leave-before-start: false

When leaving is disabled, /events leave <event> tells the player they cannot leave the queue.

---

Manual scoring protection

Manual queue events are protected by a central score gate.

For manual events:

only queued players can score
non-queued players are ignored by objective scoring
non-queued players do not appear on the leaderboard
non-queued players do not receive participation rewards

This applies to built-in objectives, custom objective sessions, admin score commands, and public API score methods.

---

Voting and scheduled voting

Manual queues work with event voting.

If a vote winner uses manual mode, EventForge opens the queue instead of starting the event instantly.

The same applies to scheduled voting winners.

Example:

scheduled vote starts
players vote for mining_rush
mining_rush wins
mining_rush opens a queue
players join the queue
event starts after the queue countdown

---

TextEffect support

Queue bossbars and countdown titles support TextEffect tags when TextEffect integration is enabled.

Example:

participation:
  queue-countdown:
    enabled: true
    title: "<g>{seconds}</g>"
    subtitle: "<neb>{event_display}</neb> &7starts soon..."
    go-title: "<love>GO!</love>"

If TextEffect is disabled or missing, EventForge falls back safely to normal text.

---

PlaceholderAPI

Manual queues include PlaceholderAPI support.

Common placeholders:

%eventforge_queue_active%
%eventforge_queue_event%
%eventforge_queue_event_display%
%eventforge_queue_time_left%
%eventforge_queue_players%
%eventforge_queue_min_players%
%eventforge_queue_max_players%
%eventforge_queue_joined%

Event-specific example:

%eventforge_queue_mining_rush_time_left%
%eventforge_queue_mining_rush_players%
%eventforge_queue_mining_rush_joined%

See the PlaceholderAPI page for the full list.

---

Validation

/eventforge validate checks manual queue settings.

It can warn about:

invalid participation mode
queue duration problems
negative min/max player values
min-players higher than max-players
missing lobby world
suspicious lobby height
invalid lobby pitch
invalid queue bossbar color/style
invalid countdown seconds or timings

---

Example manual event

participation:
  mode: MANUAL
  queue-duration: 30s
  min-players: 2
  max-players: 20
  allow-leave-before-start: true

  lobby:
    enabled: true
    world: "world"
    x: 100.5
    y: 70.0
    z: -250.5
    yaw: 90
    pitch: 0

This setup:

opens a 30 second queue
requires at least 2 players
allows up to 20 players
allows players to leave before start
teleports joined players to the lobby
starts only if enough players joined
only lets queued players score

---

Recommended setup

For most servers, keep global participation automatic:

participation:
  default-mode: AUTOMATIC

Then enable manual mode only on events where queues make sense:

participation:
  mode: MANUAL

This keeps normal events simple while letting larger events use the premium queue/hype phase flow.