feat: better opt-out hint + auto opt-out after repeated declines

.gitignore

@@ -4,3 +4,4 @@
 .vscode/
 .idea/
 build/
+.claude

README.md

@@ -13,6 +13,12 @@ eligible online player, groups them by PvP level bracket (10-19, 20-29, …,
 everyone in that bracket into it. A warning is broadcast `WarningLeadTime`
 seconds before each pass. Players choose whether to accept the queue popup;
 declining carries no penalty and they are simply considered again next pass.
+Declining or ignoring a module invite shows a chat hint about `.bgevents off`
+(see `BgAutoQueue.DeclineHint.Enable`), and after
+`BgAutoQueue.OptOutAfterDeclines` consecutive declined events the character is
+automatically opted out with a notice — reversible with `.bgevents on`;
+accepting an event invite resets the count. Manual queues never trigger any of
+this.
 
 Battleground selection per bracket:
 - **Live-battleground reinforcement (priority).** If a normal battleground is
@@ -86,12 +92,15 @@ Things to be aware of when running this on a live server:
   fire — use `.bgevents run` to trigger one on demand, or avoid reloading
   right before a pass is due.
 - **Opt-out is stored per character via the core PlayerSettings system**
-  (`source = "mod-bg-auto-queue"`, index 0; `1` = opted out). The core loads it
-  on login, saves it on logout, and deletes it when the character is deleted —
-  the module keeps no table of its own. **This requires the core config
-  `EnablePlayerSettings = 1` for the opt-out to persist across logins.** With it
-  `0` (the core default), `.bgevents off` still works but only for the current
-  session, and a warning is logged at startup.
+  (`source = "mod-bg-auto-queue"`; index 0: `0` = opted in, `1` = manual
+  opt-out via `.bgevents off`, `2` = automatic opt-out after consecutive
+  declines; index 1: the consecutive declined-invite counter). The core loads
+  it on login, saves it on logout, and deletes it when the character is
+  deleted — the module keeps no table of its own. **This requires the core
+  config `EnablePlayerSettings = 1` for the opt-out (and the counter) to
+  persist across logins.** With it `0` (the core default), `.bgevents off`
+  still works but only for the current session, and a warning is logged at
+  startup.
 
 ## Installation
 
@@ -118,10 +127,12 @@ All options are documented in `conf/mod-bg-auto-queue.conf.dist`:
 - `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.
+- `BgAutoQueue.DeclineHint.Enable` — chat hint about `.bgevents off` after a declined/expired module invite (the auto-opt-out notice below is always sent).
+- `BgAutoQueue.OptOutAfterDeclines` — consecutive declined module events before the character is automatically opted out (`0` disables the auto-opt-out).
 
 ## Commands
 
-- `.bgevents on` — opt the current character back into battleground events.
+- `.bgevents on` — opt the current character back into battleground events (also resets the consecutive-decline count).
 - `.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.

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

@@ -7,9 +7,10 @@
 ###################################################################################################
 # mod-bg-auto-queue
 #
-#    DEPENDENCY: per-character ".bgevents" opt-out is stored via the core
-#    PlayerSettings system, which only persists across logins when the core
-#    config "EnablePlayerSettings" is set to 1. With it 0 (the core default),
+#    DEPENDENCY: per-character ".bgevents" opt-out and the consecutive-decline
+#    counter (see OptOutAfterDeclines) are stored via the core PlayerSettings
+#    system, which only persists across logins when the core config
+#    "EnablePlayerSettings" is set to 1. With it 0 (the core default),
 #    ".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.
 #
@@ -184,4 +185,35 @@ BgAutoQueue.SkipAFK = 1
 
 BgAutoQueue.SkipAuras = ""
 
+#
+#    BgAutoQueue.DeclineHint.Enable
+#        Description: When a player declines (or lets expire) a Battleground
+#                     invite created by this module, send them a visible chat
+#                     hint explaining ".bgevents off". Gates ONLY the
+#                     per-decline hint; the automatic opt-out notice (see
+#                     OptOutAfterDeclines) is always sent. Manual queues are
+#                     never affected.
+#        Default:     1 - Send the hint
+#                     0 - No hint
+#
+
+BgAutoQueue.DeclineHint.Enable = 1
+
+#
+#    BgAutoQueue.OptOutAfterDeclines
+#        Description: After this many CONSECUTIVE declined or ignored module
+#                     invites, the character is automatically opted out (as if
+#                     they typed ".bgevents off") and told so. Accepting a
+#                     module invite or typing ".bgevents on" resets the count.
+#                     The count is stored via the core PlayerSettings system,
+#                     so it persists across logins only with
+#                     "EnablePlayerSettings = 1" (same dependency as the
+#                     opt-out itself, see the note at the top of this file).
+#        Default:     3
+#                     0 - Never opt out automatically (hints alone keep firing
+#                         if enabled)
+#
+
+BgAutoQueue.OptOutAfterDeclines = 3
+
 ###################################################################################################

docs/how-it-works.md

@@ -28,16 +28,25 @@ the countdown, so the next *scheduled* event still happens at its usual time.
    yourself.
 3. **You decide.** Click **Enter Battle** to join the match, or just ignore /
    decline the pop-up if you don't feel like it this time.
+4. **If you decline or ignore the pop-up**, a chat message reminds you how to
+   turn events off for good (`.bgevents off`), in case you'd rather not be
+   asked at all.
 
 That's it. Accepting drops you into the Battleground like any normal queue.
 
 ## Declining is totally fine
 
-If you ignore or decline the pop-up, **nothing bad happens** — no Deserter
-penalty, no cooldown, nothing. You simply get another chance at the next event.
-The Deserter debuff only ever applies if you *enter* a Battleground and *then*
+If you ignore or decline the pop-up, there's **no penalty** — no Deserter
+debuff, no cooldown — and you get another chance at the next event. The
+Deserter debuff only ever applies if you *enter* a Battleground and *then*
 leave it early, which has nothing to do with this.
 
+One thing to know: if you decline **several events in a row** (a server
+setting, normally 3), the server assumes you're not interested and **stops
+auto-inviting you**. A chat message tells you when that happens, and
+**`.bgevents on`** brings events back whenever you want. Accepting any event
+invite resets the count.
+
 ## Which Battleground you get
 
 - Normally the event picks one **at random** from a pool — currently **Warsong
@@ -68,14 +77,19 @@ If you'd rather never be auto-queued, you can turn it off for your character:
 - **`.bgevents`** — check whether you're opted in, and see how long until the
   next event.
 
+The server also opts you out **automatically** after several declined events
+in a row (see "Declining is totally fine" above) — `.bgevents on` undoes that
+too.
+
 Opting out only affects **future** events; it won't remove you from a queue
 you're already in.
 
 ## When you *won't* be auto-queued
 
 You're skipped for an event (this event only) if you're:
 
-- **opted out** with `.bgevents off`,
+- **opted out** — with `.bgevents off`, or automatically after several
+  declined events in a row,
 - **outside the eligible level range** (by default below 10 or at max level),
 - **in a dungeon or raid**,
 - **already in a Battleground**,
@@ -102,10 +116,11 @@ 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).
+event queue** (click the battlefields icon next to the minimap and leave) —
+then queue as a group normally. You can also wait for the invite and decline
+it, but that counts toward the automatic opt-out described above; leaving the
+queue before the invite pops doesn't. Queueing for a *different* Battleground
+is unaffected (you can be in two queues at once).
 
 ## Command reference