BGH - Battle Ground Helper

First public release of BG Helper. This version ships with full support for all 10 retail PvP battlegrounds, real-time addon sync, a smart macro system, and a built-in BG guide — built from the ground up over several months of iterative development and in-game testing.

Addon Framework

• Full Ace3 integration (AceAddon, AceDB, AceEvent, AceConsole, AceGUI)
• LibDBIcon minimap button — left-click to toggle frame, right-click to open options
• SavedVariables for position, opacity, macro status, and all settings
• Auto BG detection via instanceID, map ID, parent map walk, and name-based fallback
• Slash commands: /bgh, /bgh options, /bgh macro, /bgh test <id>, /bgh sim, /bgh reset, /bgh debug

Real-Time Sync

• C_ChatInfo.SendAddonMessage with automatic channel selection (INSTANCE > RAID > PARTY)
• Structured message format TYPE:BASE:PLAYERNAME — parsed and routed to per-BG handlers
• Duplicate suppression via lastAddonEvent — prevents echo when own actions are re-received
• Tainted string protection — all sender/msg access in pcall for BG combat context

Macro System

• BGH macro — dynamically updated with current movement announcement
• BGH_INC macro — pre-loaded with the most urgent contextual message
• Combat queue — EditMacro calls queued during combat, flushed on PLAYER_REGEN_ENABLED
• Never deletes macros — only EditMacro to preserve action bar placement
• One-click setup in Options: creates both macros and opens the Blizzard Macro window

State Machine

• Left-click to defend a base (DEF_ME state, green row)
• Left-click again to leave (LEAVE message, base turns grey)
• Left-click INC/ALLY base to go help (COMING state, blue — leaves home base orange)
• Left-click home base while COMING to return (BACK message, orange clears)
• Right-click any base to instantly untag (emergency leave)
• DEF_ME + INC = DEF_ME_INC state (orange row); click to mark SAFE

Visual System

• 6 base states: NONE / DEF_ME / DEF_ME_INC / DEF_ALLY / COMING / INC
• Row colors — green (me), dark green (ally), orange (me+INC), red blink (INC no def)
• Defender count badge — shows number of BGH defenders at each base
• INC counter — Nx label with warning icon when enemies incoming
• Unprotected warning — single orange base (lastAbandoned) when defender left; clears when anyone takes it
• Warning levels — at-risk (1:1) and critical (2:1 outnumbered) name color changes

Event Log

• 3-line scrolling event log below base rows for all players
• Color coded: DEF=blue, COMING=yellow, INC=red, SAFE=green, info=grey

• FC tracking — 'I am FC' toggle button; auto-joins DEF team on activation
• Team counters — ATK and DEF player counts with sword/shield icons and hover tooltips
• Shared team state (BGH_UI.flagTeam) synced in real time across all BGH users
• Button highlights — > IN ATK < or > IN DEF < in green when active
• Regroup GY / Attack! / FC CAP! action buttons with flash warning on warnLabel
• Message log — last 3 events (FC, team joins, CAP, Regroup) with color coding

• 4-node base system identical to Arathi Basin (DEF/INC/COMING/BACK)
• Center flag row — FC status label + I have Flag + FC Cap! buttons below base rows
• Event log — shared between base actions and flag events

• 2x2 orb grid — PURPLE, ORANGE, GREEN, BLUE cells
• 3-state per orb: free (dim) → claimed (gentle pulse blink) → DANGER (fast red blink)
• One orb per player — claiming a new orb auto-releases the previous
• GO! button — carrier presses to call for help; button blinks DANGER until someone claims the orb
• orbCarriers table synced across all BGH users via GONNADIE message
• Regroup GY / Go Middle action buttons
• Event log with orb-colored messages (e.g. 'PURPLE DANGER!')

• 3-zone UI (LAVA / WTFL / TROLL) each with: Escort | INC | Safe | Leave buttons
• Escort counter — escort count + INC count shown per zone; hover for player names
• Cross-zone remove — joining a zone auto-removes you from other zones
• INC counter increments per click, Safe resets to 0
• Regroup GY button + event log

• 2-zone UI: Team Cart (green) / Enemy Cart (red) — mirrored after Silvershard
• Escort | INC | Safe | Leave per zone with shared counter
• Crystal section — I have Crystal + FC CAP! with carrier name display
• Cross-zone remove — same logic as Silvershard
• Regroup GY button + event log

Options Panel (AceGUI)

• Addon sync toggle
• Local echo toggle (show own actions in chat)
• Macro announce toggle with status label
• Setup Macros button — creates BGH + BGH_INC and opens Blizzard macro window
• Chat channel selector (Auto / Instance / Raid / Say)
• Defender count display toggle
• Opacity slider
• Auto-reset on BG end toggle
• Reset base data button

Help Panel (? button in title bar)

• AceGUI window with BG-specific guide
• Covers all 10 BGs with strategy tips and BGH-specific instructions
• Auto-selects content based on active BG

Simulator

• Test mode — dropdown to select any BG without being in one
• Simulator panel — DEF / INC / SAFE buttons per base to simulate ally actions
• Full UI preview for all BG types in test mode

Supported Battlegrounds — Instance IDs

Known Limitations — v1.0.0

• Sync only works between players who have BGH installed — no cross-addon parsing
• Minimap icon requires a bgh.tga icon file in BGH/libs/ to display correctly
• CurseForge Project ID is a placeholder in BGH.toc — update after first publish
• Kotmogu orb sync sends carrier names but remote blink requires GONNADIE message (re-click)
• DHR instance ID 1208 not yet confirmed in-game — fallback by name is active

Embedded Libraries

• LibStub
• CallbackHandler-1.0
• AceAddon-3.0
• AceEvent-3.0
• AceDB-3.0
• AceConsole-3.0
• AceGUI-3.0
• LibDataBroker-1.1
• LibDBIcon-1.0