feat: revamp module

.github/workflows/core-build.yml

@@ -0,0 +1,12 @@
+name: core-build
+on:
+  push:
+    branches:
+      - 'master'
+  pull_request:
+
+jobs:
+  build:
+    uses: azerothcore/reusable-workflows/.github/workflows/core_build_modules.yml@main
+    with:
+      module_repo: ${{ github.event.repository.name }}

README.md

@@ -1,33 +1,106 @@
 # mod-bg-auto-queue
 
-AzerothCore module that automatically queues players into a battleground on
-login. Players are opted in by default and can opt out with an in-game command.
+AzerothCore module that periodically auto-queues eligible online players into
+battlegrounds, grouped by level bracket, to help battlegrounds reach the
+critical mass needed to pop. Players are opted in by default and can opt out
+with an in-game command.
 
-## Features
+## How it works
 
-- Automatically enqueues eligible players into a battleground on login.
-- Configurable level range that gates the auto-join behavior.
-- Configurable default battleground: Random Battleground, Warsong Gulch, or
-  Arathi Basin. Falls back to Warsong Gulch when the chosen battleground is not
-  available for the player's level.
-- Per-character opt-out persisted in the characters database.
-- `.bgevents` command to enable, disable, or inspect the auto-join state.
+On a configurable interval the module runs a **queue pass**:
+
+1. It gathers every eligible online player and groups them by PvP level bracket
+   (10-19, 20-29, …, 70-79). Brackets are never mixed.
+2. For each populated bracket it selects one battleground:
+   - **Live-battleground reinforcement (priority).** If a battleground of any
+     normal type is already forming or in progress for that bracket and has
+     free slots, players are queued into it so they reinforce the live match.
+     This is not limited to the configured pool.
+   - **Otherwise, a random pick from the configured pool.** With a single
+     eligible candidate it is used as-is. With several, candidates whose
+     minimum players per team cannot be met by the bracket's available count
+     are dropped and one of the rest is chosen at random. If none meet the
+     threshold, the smallest battleground (typically Warsong Gulch) is chosen
+     anyway so players are still queued.
+3. Every player in the bracket is solo-queued (no premade groups) into the
+   chosen battleground.
+
+`WarningLeadTime` seconds before each pass, a generic warning is broadcast to
+the players who would be queued, reminding them how to opt out or back in.
+
+## Behaviour & interactions
+
+- **Per-bracket matching never mixes brackets**; each bracket gets its own
+  battleground.
+- **Solo queue only** — players are queued individually, never as a premade.
+- **Re-queue on decline.** Declining or ignoring the queue popup carries no
+  penalty (no Deserter debuff — that only applies after entering and leaving a
+  battleground). The player is simply considered again on the next pass.
+- **Reload resets the timer** and re-applies `InitialDelay`. A player who logs
+  in between the warning and the pass is still queued, just without a warning.
+- **Deserter tracking noise.** If `Battleground.TrackDeserters.Enable` is enabled,
+  players who decline auto-queue invites may appear in the deserter tracking
+  table. This is informational only, not a player-facing penalty.
+- **Queue announcer.** If `Battleground.QueueAnnouncer.Enable` is on in
+  immediate (non-timed) mode, a mass pass emits one world announcement per
+  player. Consider `Battleground.QueueAnnouncer.Timed` /
+  `…PlayerOnly` to avoid spam.
+
+A player is **eligible** when they are online and in the world, not opted out,
+within the configured level range, not in a dungeon/raid, not already in a
+battleground, not already in a battleground/arena queue, not a deserter, not
+using the LFG system, not a Death Knight still locked to Ebon Hold, and (when
+`SkipGameMasters` is on) not a game master.
+
+## Operational notes
+
+Things to be aware of when running this on a live server:
+
+- **A pass queues everyone in one tick (burst).** All eligible players are
+  queued during a single world update, and a `OnPlayerJoinBG` script hook fires
+  **once per queued player**. On a high-population server this is a noticeable
+  burst: any other module that listens on `OnPlayerJoinBG` (announcers, reward
+  systems, statistics) will fire en masse, and the core BG queue announcer in
+  immediate mode emits one line per player (see "Queue announcer" above —
+  prefer its timed / player-only mode). Spreading the burst across multiple
+  ticks is intentionally not implemented; size your `Interval` accordingly.
+- **`.reload config` restarts the timer.** Every config reload resets the
+  interval and re-applies `InitialDelay`. If you reload more frequently than
+  `Interval`, the next automatic pass is pushed back each time and may never
+  fire — use `.bgevents run` to trigger one on demand, or avoid reloading
+  right before a pass is due.
+- **Opt-out state is read once at startup.** The opt-out set is loaded from
+  `mod_bg_auto_queue_optout` on server startup and is thereafter the in-memory
+  source of truth (mutated by `.bgevents on`/`off` and kept in sync with the
+  table). Editing the table directly while the server is running has **no
+  effect until the next restart**.
 
 ## Installation
 
 1. Clone this folder into `modules/mod-bg-auto-queue/` of your AzerothCore source.
 2. Re-run CMake and rebuild the worldserver.
-3. Copy `mod-bg-auto-queue.conf.dist` to `mod-bg-auto-queue.conf` in your worldserver's
-   configuration directory and adjust as needed.
+3. Copy `mod-bg-auto-queue.conf.dist` to `mod-bg-auto-queue.conf` in your
+   worldserver's configuration directory and adjust as needed.
 4. The module installs its characters-database table automatically through the
    AzerothCore SQL updater on first run.
 
 ## Configuration
 
-See `conf/mod-bg-auto-queue.conf.dist` for the full list of options.
+All options are documented in `conf/mod-bg-auto-queue.conf.dist`:
+
+- `BgAutoQueue.Enable` — enable the automatic periodic pass (calling `.bgevents run` works even when disabled).
+- `BgAutoQueue.Level.Min` / `BgAutoQueue.Level.Max` — eligible level range.
+- `BgAutoQueue.Pool` — CSV of `battleground_template` IDs to pick from.
+- `BgAutoQueue.Interval` — minutes between passes (`0` disables the schedule).
+- `BgAutoQueue.InitialDelay` — seconds before the first pass after startup/reload.
+- `BgAutoQueue.WarningLeadTime` — seconds before a pass to broadcast the warning.
+- `BgAutoQueue.BroadcastMessage` — the warning text (empty disables it).
+- `BgAutoQueue.CrossFaction` — how the available count is judged against a BG's minimum players per team.
+- `BgAutoQueue.SkipGameMasters` — skip GMs in the warning and the queueing.
 
 ## Commands
 
-- `.bgevents on` — enable auto-join for the current character (default state).
-- `.bgevents off` — disable auto-join for the current character.
-- `.bgevents status` — show the current auto-join state.
+- `.bgevents on` — opt the current character back into battleground events.
+- `.bgevents off` — opt the current character out (future passes only; does not dequeue an existing queue).
+- `.bgevents status` — show the opt-in state and the time until the next scheduled pass.
+- `.bgevents run` — *(GM, console-capable)* run a queue pass immediately, even when the automatic schedule is disabled. Does not reset the periodic timer.

conf/mod-bg-auto-queue.conf.dist

@@ -8,69 +8,120 @@
 # mod-bg-auto-queue
 #
 #    BgAutoQueue.Enable
-#        Description: Enable the automatic battleground queue on login.
-#                     When enabled, every eligible player will be enqueued
-#                     automatically into the configured battleground on login.
+#        Description: Enable the automatic, periodic battleground queue pass.
+#                     When enabled, the module periodically gathers eligible
+#                     online players, groups them by level bracket and queues
+#                     each bracket into a battleground.
+#                     NOTE: This gates ONLY the automatic schedule: even when
+#                     disabled, a GM can still fire a pass on
+#                     demand with ".bgevents run".
 #        Default:     1 - Enabled
-#                     0 - Disabled
+#                     0 - Disabled (manual ".bgevents run" only)
 #
 
 BgAutoQueue.Enable = 1
 
 #
 #    BgAutoQueue.Level.Min
-#        Description: Minimum character level for which the automatic queue is
-#                     applied. Players below this level are skipped.
+#        Description: Minimum character level eligible for the automatic queue.
+#                     Players below this level are skipped.
 #        Default:     10
 #
 
 BgAutoQueue.Level.Min = 10
 
 #
 #    BgAutoQueue.Level.Max
-#        Description: Maximum character level for which the automatic queue is
-#                     applied. Players above this level are skipped.
-#        Default:     59
+#        Description: Maximum character level eligible for the automatic queue.
+#                     Players above this level are skipped.
+#        Default:     79
 #
 
-BgAutoQueue.Level.Max = 59
+BgAutoQueue.Level.Max = 79
 
 #
-#    BgAutoQueue.Battleground
-#        Description: Battleground to enqueue the player into on login.
-#                     If the chosen battleground is unavailable for the
-#                     player's level, the module falls back to Warsong Gulch.
-#        Default:     0 - Random Battleground
-#                     1 - Warsong Gulch
-#                     2 - Arathi Basin
-#                     3 - Eye of the Storm
-#                     4 - Alterac Valley
-#                     5 - Strand of the Ancients
-#                     6 - Isle of Conquest
+#    BgAutoQueue.Pool
+#        Description: Comma-separated list of battleground_template IDs the
+#                     module may randomly pick from for each bracket. The IDs
+#                     are BattlegroundTypeId values:
+#                         1  = Alterac Valley
+#                         2  = Warsong Gulch
+#                         3  = Arathi Basin
+#                         7  = Eye of the Storm
+#                         9  = Strand of the Ancients
+#                         30 = Isle of Conquest
+#                     Invalid IDs, arenas and Random Battleground (32) are
+#                     rejected at load with a warning. If the pool ends up
+#                     empty, only live-battleground reinforcement can queue
+#                     players.
+#        Default:     "2,3,7" - Warsong Gulch, Arathi Basin, Eye of the Storm
 #
 
-BgAutoQueue.Battleground = 0
+BgAutoQueue.Pool = "2,3,7"
 
 #
 #    BgAutoQueue.Interval
-#        Description: Interval, in minutes, between automatic battleground
-#                     queue passes. On every tick, every eligible online
-#                     player that hasn't opted out is enqueued into the
-#                     configured battleground.
-#                     Set to 0 to disable the periodic pass entirely.
-#
+#        Description: Minutes between automatic queue passes. Set to 0 to
+#                     disable the periodic pass entirely (".bgevents run" still
+#                     works).
 #        Default:     45
 #
 
 BgAutoQueue.Interval = 45
 
+#
+#    BgAutoQueue.InitialDelay
+#        Description: Seconds before the FIRST pass after startup or a config
+#                     reload. 0 means wait one full Interval before the first
+#                     pass. A small value (e.g. 30) fires the first event
+#                     quickly on a test server.
+#        Default:     0
+#
+
+BgAutoQueue.InitialDelay = 0
+
+#
+#    BgAutoQueue.WarningLeadTime
+#        Description: Seconds before each pass to broadcast the warning message.
+#                     Must be smaller than the Interval (and than InitialDelay
+#                     for the first pass) to fire. Set BroadcastMessage to an
+#                     empty string to disable the warning.
+#        Default:     60
+#
+
+BgAutoQueue.WarningLeadTime = 60
+
 #
 #    BgAutoQueue.BroadcastMessage
 #        Description: System message sent to every eligible online player
-#                     two minutes before the periodic queue pass fires.
-#        Default:     "BG Event starting in 2 minutes, you can opt-out by typing .bgevents off. You can always join manually by pressing H and going to the BG tab"
+#                     WarningLeadTime seconds before a pass. It should remind
+#                     players of both ".bgevents off" (opt out) and
+#                     ".bgevents on" (opt back in). An empty string disables
+#                     the warning.
+#        Default:     "A Battleground event is starting shortly. Type .bgevents off to opt out, or .bgevents on to opt back in. You can also join manually by pressing H."
+#
+
+BgAutoQueue.BroadcastMessage = "A Battleground event is starting shortly. Type .bgevents off to opt out, or .bgevents on to opt back in. You can also join manually by pressing H."
+
+#
+#    BgAutoQueue.CrossFaction
+#        Description: How the available player count is judged against a
+#                     battleground's minimum players per team when several
+#                     pool candidates exist.
+#        Default:     1 - Cross-faction: total players >= 2 x MinPlayersPerTeam
+#                     0 - Vanilla: Alliance >= min AND Horde >= min
+#
+
+BgAutoQueue.CrossFaction = 1
+
+#
+#    BgAutoQueue.SkipGameMasters
+#        Description: Skip game masters in both the warning and the queueing.
+#                     Set to 0 on a test server to allow queueing a GM.
+#        Default:     1 - Skip GMs
+#                     0 - Include GMs
 #
 
-BgAutoQueue.BroadcastMessage = "BG Event starting in 2 minutes, you can opt-out by typing .bgevents off. You can always join manually by pressing H and going to the BG tab"
+BgAutoQueue.SkipGameMasters = 1
 
 ###################################################################################################

data/sql/db-characters/base/mod_bg_auto_queue.sql

@@ -1,6 +1,5 @@
 --
--- Table tracking characters that opted out from the automatic battleground
--- queue performed by mod-bg-auto-queue.
+-- Table tracking characters that opted out from the automatic battleground queue performed by mod-bg-auto-queue
 --
 CREATE TABLE IF NOT EXISTS `mod_bg_auto_queue_optout` (
     `guid` INT UNSIGNED NOT NULL,