fix: operator warnings and docs for CrossFaction and the first-pass warning window

README.md

@@ -28,6 +28,13 @@ commands — see **[docs/how-it-works.md](docs/how-it-works.md)**.
 
 ## Interactions with other systems
 
+- **Cross-faction matcher (mod-cfbg).** `BgAutoQueue.CrossFaction = 1` judges
+  viability on the total player count and assumes a cross-faction matcher such
+  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
+  misconfiguration.
 - **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.
@@ -82,7 +89,7 @@ All options are documented in `conf/mod-bg-auto-queue.conf.dist`:
 - `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.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.
 
 ## Commands

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

@@ -119,7 +119,15 @@ BgAutoQueue.BroadcastMessage = "A Battleground event is starting shortly. Type .
 #        Description: How the available player count is judged against a
 #                     battleground's minimum players per team when several
 #                     pool candidates exist.
+#                     Mode 1 assumes a cross-faction matcher (such as
+#                     mod-cfbg) is installed and active. 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; players stay queued until enough
+#                     minority-faction players appear. Without a
+#                     cross-faction matcher, set this to 0.
 #        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
 #
 

src/BgAutoQueue.cpp

@@ -110,6 +110,9 @@ void BgAutoQueue::LoadConfig()
     if (_intervalMs > 0 && _warningLeadMs >= _intervalMs)
         LOG_WARN("module", "BgAutoQueue.WarningLeadTime ({} s) >= Interval ({} min); the warning will not fire.", warningLeadSec, intervalMin);
 
+    if (_initialDelayMs > 0 && _warningLeadMs >= _initialDelayMs)
+        LOG_WARN("module", "BgAutoQueue.WarningLeadTime ({} s) >= InitialDelay ({} s); no warning will fire before the first pass.", warningLeadSec, initialDelaySec);
+
     _crossFaction     = sConfigMgr->GetOption<bool>("BgAutoQueue.CrossFaction", true);
 
     // Mirror mod-cfbg's defaults (CFBG.cpp LoadConfig). Only CFBG on + EvenTeams
@@ -139,9 +142,10 @@ void BgAutoQueue::LoadConfig()
     }
 
     // Reset timing on (re)load. Reload re-applies InitialDelay — accepted.
-    _elapsedMs   = 0;
-    _warningSent = false;
-    _firstPass   = true;
+    _elapsedMs         = 0;
+    _warningSent       = false;
+    _firstPass         = true;
+    _matcherWarnLogged = false;
 
     LOG_INFO("module", "mod-bg-auto-queue: enabled={}, levels=[{}-{}], pool size={}, interval={} min, initialDelay={} s, warningLead={} s, crossFaction={}, evenTeamsStrict={}, skipGM={}, skipAFK={}, skipAuras={}.",
         _enabled, _levelMin, _levelMax, _poolRaw.size(), intervalMin, initialDelaySec, warningLeadSec, _crossFaction, _evenTeamsStrict, _skipGameMasters, _skipAfk, _skipAuras.size());
@@ -403,9 +407,20 @@ BgAutoQueue::QueuedWaiters BgAutoQueue::CountUninvitedWaiters(BattlegroundTypeId
                 if (gInfo->IsInvitedToBGInstanceGUID != 0)
                     continue;
 
+                if (_crossFaction && !_matcherWarnLogged
+                    && (groupType == BG_QUEUE_NORMAL_ALLIANCE || groupType == BG_QUEUE_NORMAL_HORDE))
+                {
+                    LOG_WARN("module", "mod-bg-auto-queue: BgAutoQueue.CrossFaction = 1 but uninvited "
+                        "players sit in a faction-specific queue bucket, so no cross-faction matcher "
+                        "(e.g. mod-cfbg) appears to be active. Total-based viability can queue "
+                        "faction-lopsided batches the core queue never pops. Set "
+                        "BgAutoQueue.CrossFaction = 0 on a stock core.");
+                    _matcherWarnLogged = true;
+                }
+
                 uint32 const count = static_cast<uint32>(gInfo->Players.size());
                 waiters.total += count;
-                if (gInfo->teamId == TEAM_ALLIANCE)
+                if (gInfo->RealTeamID == TEAM_ALLIANCE)
                     waiters.alliance += count;
                 else
                     waiters.horde += count;

src/BgAutoQueue.h

@@ -136,7 +136,8 @@ class BgAutoQueue
 
     // Counts uninvited players already sitting in bgTypeId's core queue, in the
     // candidate BG's own map-relative bracket(s) spanning [minLevel, maxLevel]
-    // (bracket indices are numbered per map), split by faction. Scans every
+    // (bracket indices are numbered per map), split by the players' real faction
+    // (RealTeamID, immune to CFBG's staging mutations of teamId). Scans every
     // solo/premade/cross-faction group bucket because which bucket a manual
     // queuer lands in depends on whether mod-cfbg is active. Groups already
     // invited to a forming instance are skipped.
@@ -205,6 +206,9 @@ class BgAutoQueue
     uint32 _elapsedMs = 0;
     bool _warningSent = false;
     bool _firstPass = true;
+    // Latches the CrossFaction/matcher WARN to once per config load (mutable:
+    // CountUninvitedWaiters is const).
+    mutable bool _matcherWarnLogged = false;
 };
 
 #define sBgAutoQueue BgAutoQueue::instance()