🎟️ EventQueueService API

EventQueueService is the public API for EventForge manual event queues.

Use it to read active queues, check whether players are queued, join queues and leave queues.

Manual queues are used by events with:

participation:
  mode: MANUAL

---

Getting the service

if (!EventForgeAPI.isAvailable()) {
    return;
}

EventQueueService queueService = EventForgeAPI.getEventQueueService();

---

Check if any queue is active

boolean active = queueService.isQueueActive();

This returns true if at least one manual event queue is currently open.

---

Get the first queue

queueService.getFirstQueue().ifPresent(queue -> {
    String eventId = queue.getEventId();
    String display = queue.getEventDisplayName();
});

This is useful for scoreboards or simple dashboards where only one queue needs to be shown.

---

Get a queue by event ID

queueService.getQueue("mining_rush").ifPresent(queue -> {
    int players = queue.getJoinedCount();
    long secondsLeft = queue.getSecondsLeft();
});

---

Get all queues

List<EventQueueInfo> queues = queueService.getQueues();

The returned list contains immutable queue snapshots.

---

Get queued event IDs

List<String> eventIds = queueService.getQueuedEventIds();

---

Check if a player is queued

boolean queued = queueService.isPlayerQueued(
        player.getUniqueId(),
        "mining_rush"
);

---

Join a queue

boolean joined = queueService.joinQueue(player, "mining_rush");

This uses the same queue rules as /events join <event>.

It returns true only when the player successfully joins.

---

Leave a queue

boolean left = queueService.leaveQueue(player, "mining_rush");

This uses the same queue rules as /events leave <event>.

It returns true only when the player successfully leaves.

If the queue has allow-leave-before-start: false, this will return false.

---

EventQueueInfo methods

Useful methods:

queue.getEventId();
queue.getEventDisplayName();
queue.getOpenedAtEpochSecond();
queue.getClosesAtEpochSecond();
queue.getSecondsLeft();
queue.getJoinedCount();
queue.getMinPlayers();
queue.getMaxPlayers();
queue.hasMaxPlayers();
queue.isLeaveBeforeStartAllowed();
queue.isLobbyEnabled();
queue.isClosed();
queue.hasExpired();
queue.hasEnoughPlayers();
queue.getJoinedPlayerIds();
queue.isJoined(player.getUniqueId());

---

Example scoreboard status

EventQueueService queueService = EventForgeAPI.getEventQueueService();

queueService.getFirstQueue().ifPresent(queue -> {
    String line = queue.getEventDisplayName()
            + " | "
            + queue.getSecondsLeft()
            + "s | "
            + queue.getJoinedCount()
            + "/"
            + (queue.hasMaxPlayers() ? queue.getMaxPlayers() : "∞");

    player.sendMessage(line);
});

---

Example queue check before opening a custom menu

EventQueueService queueService = EventForgeAPI.getEventQueueService();

if (!queueService.isQueueActive()) {
    player.sendMessage("No event queues are currently open.");
    return;
}

queueService.getFirstQueue().ifPresent(queue -> {
    if (queue.isJoined(player.getUniqueId())) {
        player.sendMessage("You are already queued for " + queue.getEventDisplayName() + ".");
    } else {
        player.sendMessage("Queue open: " + queue.getEventDisplayName());
    }
});

---

Queue start and cancel events

For event-driven integrations, listen to Bukkit events instead of polling constantly.

Useful queue events:

EventForgeQueueOpenEvent
EventForgeQueueJoinEvent
EventForgeQueueLeaveEvent
EventForgeQueueStartEvent
EventForgeQueueCancelEvent

EventForgeQueueStartEvent only fires after the queued event successfully starts.

EventForgeQueueCancelEvent can include reasons such as:

NOT_ENOUGH_PLAYERS
START_FAILED

See the Bukkit Events page for examples.

---

Snapshot safety

EventQueueInfo is immutable and does not expose EventForge's internal queued event object.

The API does not expose:

QueuedEvent
internal queue maps
bossbar managers
runtime queue objects

This keeps queue state safe while still allowing useful addon integrations.