fix: backlog draining, per-bracket viability and matcher-aware waiter counts

README.md

@@ -19,8 +19,15 @@ Battleground selection per bracket:
   already forming or in progress for that bracket with free slots, players are
   queued into it (not limited to the configured pool).
 - **Otherwise, a random pick** from `BgAutoQueue.Pool`, preferring candidates
-  whose minimum players per team the bracket can fill; if none qualify, the
-  smallest battleground is queued anyway.
+  whose minimum players per team the bracket can fill (a pool candidate that
+  already has uninvited queuers is reinforced first); if none qualify, the
+  smallest battleground is queued anyway to seed it.
+
+Note that while a seeded below-minimum queue waits to fill, the core blocks
+those players from joining the Random Battleground queue, and, unless
+`JoinBGAndLFG.Enable = 1` is set (core default is `0`), also from the Dungeon
+Finder, until the queue pops or they leave it. See the note in
+`conf/mod-bg-auto-queue.conf.dist`.
 
 📖 **For the full, player-facing explanation** — when events fire, what players
 see, opt-out, battleground selection, the complete eligibility list, and the
@@ -33,8 +40,18 @@ commands — see **[docs/how-it-works.md](docs/how-it-works.md)**.
   as [mod-cfbg](https://github.com/azerothcore/mod-cfbg) fills both teams. On a
   stock core the queue itself still requires the minimum in each faction, so
   mode 1 can queue faction-lopsided batches that never pop; set
-  `CrossFaction = 0` there. The module logs a warning when it detects this
+  `CrossFaction = 0` there. Conversely, with mod-cfbg active keep
+  `CrossFaction = 1` (mod-cfbg fills both teams from the total, so per-faction
+  viability under-queues). The module logs a warning on either
   misconfiguration.
+- **Toggling `CFBG.Enable` at runtime.** Players queued while mod-cfbg was in
+  the other state sit in queue buckets the newly-active matcher never reads:
+  they will not be invited until they leave the queue and re-join (or log
+  out). This is a core/mod-cfbg limitation that affects manual queuers too;
+  the module excludes such stale entries from its viability counts and logs a
+  warning when it sees them. After flipping `CFBG.Enable` and reloading,
+  expect players queued before the flip to need a re-queue (a worldserver
+  restart avoids the situation entirely).
 - **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.
@@ -55,6 +72,14 @@ Things to be aware of when running this on a live server:
   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.
+- **A large batch opens several instances.** The core creates at most one new
+  battleground instance per queue update, so after a pass the module keeps
+  nudging the queue every few seconds while a bracket still holds enough
+  uninvited players for another instance. A 60-player bracket therefore fills
+  multiple simultaneous instances within seconds instead of leaving the
+  surplus queued until the next pass. Any leftover below one instance's worth
+  stays queued and is served by normal core behavior (declines, leavers,
+  manual joins) or by the next pass.
 - **`.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
@@ -91,10 +116,18 @@ All options are documented in `conf/mod-bg-auto-queue.conf.dist`:
 - `BgAutoQueue.BroadcastMessage` — the warning text (empty disables it).
 - `BgAutoQueue.CrossFaction` — how the available count is judged against a BG's minimum players per team; `1` requires a cross-faction matcher such as mod-cfbg (see "Interactions with other systems").
 - `BgAutoQueue.SkipGameMasters` — skip GMs in the warning and the queueing.
+- `BgAutoQueue.SkipAFK` — skip players flagged AFK (on by default; note the client auto-flags idle players).
+- `BgAutoQueue.SkipAuras` — CSV of aura IDs whose carriers are skipped for the pass.
 
 ## Commands
 
 - `.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` — *(no argument)* 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.
+
+Note: while a character holds the auto-created queue entry, the client
+silently rejects a manual re-join of that same battleground — solo, and for
+the whole party on "Join as Group" if any member holds the entry. Players who
+want to queue as a group right after a pass must first leave the automatic
+queue (via the queue icon next to the minimap) or wait for the invite.

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

@@ -13,6 +13,14 @@
 #    ".bgevents off" still works but lasts only for the current session, and a
 #    warning is logged at startup. This module does not change the core config.
 #
+#    NOTE: when no pool candidate can reach its minimum player count for a
+#    bracket, the pass still queues the bracket into the smallest battleground
+#    to seed it. Until that queue pops (or the player leaves it), the core
+#    blocks Random Battleground joins, and with "JoinBGAndLFG.Enable = 0" (the
+#    core default) it also blocks joining the Dungeon Finder. Realms where
+#    below-minimum brackets are common should consider "JoinBGAndLFG.Enable=1"
+#    so seeded players keep Dungeon Finder access.
+#
 #    BgAutoQueue.Enable
 #        Description: Enable the automatic, periodic battleground queue pass.
 #                     When enabled, the module periodically gathers eligible
@@ -61,10 +69,12 @@ BgAutoQueue.Level.Max = 79
 #                         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.
+#                     Non-numeric entries and Random Battleground (32) are
+#                     rejected at load with a warning; unknown IDs, arenas and
+#                     battlegrounds disabled via the `disables` table are
+#                     reported with a warning at the first pass after each
+#                     (re)load. 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
 #
 
@@ -125,7 +135,10 @@ BgAutoQueue.BroadcastMessage = "A Battleground event is starting shortly. Type .
 #                     faction, so mode 1 can queue faction-lopsided batches
 #                     that never pop; players stay queued until enough
 #                     minority-faction players appear. Without a
-#                     cross-faction matcher, set this to 0.
+#                     cross-faction matcher, set this to 0. With mod-cfbg
+#                     active (CFBG.Enable = 1) keep this at 1: mod-cfbg fills
+#                     both teams from the total, so per-faction viability
+#                     under-queues (a warning is logged on this combination).
 #        Default:     1 - Cross-faction: total players >= 2 x MinPlayersPerTeam
 #                         (requires a cross-faction matcher such as mod-cfbg)
 #                     0 - Vanilla: Alliance >= min AND Horde >= min
@@ -146,8 +159,11 @@ BgAutoQueue.SkipGameMasters = 1
 #
 #    BgAutoQueue.SkipAFK
 #        Description: Skip players flagged as AFK in both the warning and the
-#                     queueing, so idle characters are not teleported into a
-#                     battleground.
+#                     queueing, so idle characters do not receive queue invites
+#                     they will never answer. (Nobody is ever teleported
+#                     automatically: entering always requires the player to
+#                     click "Enter Battle".) Note that the client flags idle
+#                     players AFK automatically after a few minutes.
 #        Default:     1 - Skip AFK players
 #                     0 - Include AFK players
 #

docs/how-it-works.md

@@ -84,6 +84,9 @@ You're skipped for an event (this event only) if you're:
 - **using the Dungeon Finder (LFG)**,
 - a **Death Knight still in the Ebon Hold starting zone**,
 - a **Game Master** (skipped by default; this can be turned off),
+- **flagged AFK** (skipped by default; this can be turned off — note the game
+  flags you AFK automatically after a few minutes of inactivity, so if you were
+  idle you may get neither the warning nor the pop-up),
 - carrying one of the **configured skip auras** (a server setting).
 
 Once whatever's blocking you clears, you'll be considered again at the next
@@ -94,6 +97,16 @@ event.
 Don't want to wait for an event? Open the Battleground window (press **H**) and
 queue yourself as usual. Events are just a convenience on top of that.
 
+**One catch:** while you hold the queue spot an event gave you, the game
+silently ignores a manual re-join of that **same** Battleground — nothing
+happens when you click. The same applies to **Join as Group**: it silently
+fails for the whole party if any member holds the event's queue spot. To queue
+for that Battleground with friends right after an event, first **leave the
+event queue** (click the battlefields icon next to the minimap and leave), or
+wait for the invite and decline it — then queue as a group normally. Queueing
+for a *different* Battleground is unaffected (you can be in two queues at
+once).
+
 ## Command reference
 
 | Command | Who | What it does |