How evil-morfar/rclootcouncil2 works
RCLootCouncil is a World of Warcraft addon, built as an Ace3-based Lua application. Its architecture is centered on a small core, a set of feature modules, shared data/utilities, and UI frames that all run inside the WoW client and talk through the game’s event and addon-message APIs.
1. Entry points and bootstrap
The addon is rooted in RCLootCouncil.toc, with top-level runtime files such as core.lua, ml_core.lua, Classes/Core.lua, and embeds.xml. These files initialize the addon, register Ace3 embeds, and wire together core services, modules, and UI components.
2. Core runtime and global state
Classes/Core.lua plus Core/ files (Constants.lua, CoreEvents.lua, Defaults.lua, GlobalUpdates.lua) define the addon’s shared runtime contract: constants, event names, default settings, and global update/compatibility behavior. This is the central coordination layer that other subsystems depend on.
3. Main feature modules
Modules/ contains the user-facing capabilities: loot history, trade UI, voting frame, loot frame, session frame, version checks, sync, options, and CSV import. These modules represent the high-level flows of the addon and are the primary boundaries for loot distribution, candidate voting, item handoff, and history management.
4. Data model layer
Classes/Data/ contains the persistent and structured data objects: Player, Council, and MLDB. These classes model raid members, council members, and master-looter database state, and they are the main abstraction over saved variables and operational state.
5. Communication and restrictions
Classes/Services/Comms.lua and CommsRestrictions.lua implement addon-to-addon communication, likely over AceComm-3.0 and ChatThrottleLib. This is the cross-client synchronization boundary for votes, session state, version checks, and loot-related messages; restrictions govern when and what may be sent.
6. UI layer
UI/ and UI/Widgets/ provide reusable frames, buttons, icons, text controls, import/export dialogs, and larger export views. Higher-level modules use these widgets to render voting, trade, session, and import/export screens. UI code is separated from logic, but closely driven by module state.
7. Utility and domain helpers
Classes/Utils/ and Utils/ hold domain helpers such as item parsing, group loot handling, logging, temp tables, item storage, token/transmog/encounter journal data, popup handling, and backwards compatibility. These utilities reduce duplication and concentrate WoW-specific item and loot logic in one layer.
8. History import/export pipeline
Modules/History/ and Modules/History/lootHistory.lua manage loot history capture, while CSVImport.lua and the UI/Widgets/ImportFrame.lua / export widgets support importing and exporting historical records. The repository also includes tests for JSON and CSV import/export, indicating this is a notable data interchange boundary.
9. Reactive/event-driven internals
The vendored Classes/Lib/RxLua/ suggests some internal flows use observable streams and subjects rather than only direct callbacks. This is useful for modeling transient UI and event sequences such as votes, roll announcements, and state changes.
10. External libraries and platform dependencies
The addon embeds Ace3 libraries (AceAddon, AceComm, AceConfig, AceDB, AceGUI, AceEvent, AceTimer, etc.), plus LibDeflate, LibDialog, LibSharedMedia, LibWindow, and dropdown/menu helpers. These are infrastructure dependencies that shape the architecture: addon lifecycle, configuration, persistence, messaging, timers, and UI construction are all delegated to these libraries.
11. WoW API boundary
The addon is tightly coupled to the World of Warcraft API. The __tests/wow_api/ emulation layer mirrors frame, tooltip, dropdown, and player/item APIs so logic can be tested outside the game client. This boundary is important because most runtime behavior depends on game events, frames, item links, and raid context.
12. Testing and validation architecture
The .specs/ tree contains unit, integration, and emulation-based tests using Busted, plus helpers for raid setup and login emulation. Tests cover core item math, comms, trade flow, voting behavior, tooltip handling, history import/export, and WoW API frame emulation, showing a layered test strategy around the same subsystem boundaries as production code.
13. Build, release, and distribution
GitHub Actions workflows (busted.yml, release.yml, discord-changelog.yml) and scripts in .scripts/ handle testing, packaging, deployment, and release notifications. This is a CI/CD boundary rather than runtime logic, but it matters for understanding how the addon is validated and shipped.
14. Overall data flow
At runtime, WoW events and user actions enter through the core and module layer, are transformed by data/services/utils, synchronized across players via comms, and rendered through the UI. Persistent state flows into AceDB-backed storage and loot history exports/imports, while tests exercise the same paths with mocked WoW APIs and saved-variable fixtures.
Main entry points: Core.lua Addon core · README.md Specs · UI.lua UI root · Utils.lua Utils
Components 34
Bootstrap
Addon entrypoints and wiring
Core runtime
Shared state, services, data, and utility layers
- Addon core · Central addon object that coordinates state, services, and modules
Classes/Core.lua - Constants · Shared identifiers and configuration keys
Core/Constants.lua - Events · Internal event names and dispatch vocabulary
Core/CoreEvents.lua - Defaults · Default profile and option values
Core/Defaults.lua - Updates · Backward-compatibility and global update behavior
Core/GlobalUpdates.lua - Comms · Cross-client message transport and synchronization boundary
Classes/Services/Comms.lua - Restrictions · Rules governing when and what can be transmitted
Classes/Services/CommsRestrictions.lua - Player · Structured raid member and candidate state
Classes/Data/Player.lua - Council · Council membership and access state
Classes/Data/Council.lua - MLDB · Master-looter persistent database and session state
Classes/Data/MLDB.lua - Utils · Shared WoW-specific helpers and compatibility utilities
Utils/Utils.lua - Item helpers · Item parsing, storage, and item-centric calculations
Classes/Utils/Item.lua - Loot helpers · Group loot and auto-pass behavior helpers
Classes/Utils/GroupLoot.lua
Feature modules
Main user-facing addon flows
- History · Loot history capture and persistence boundary
Modules/History/lootHistory.lua - CSV import · Import pipeline for historical records
Modules/History/CSVImport.lua - Trade UI · Trade-related candidate and item handoff workflow
Modules/TradeUI.lua - Voting · Voting, roll collection, and vote coordination
Modules/votingFrame.lua - Loot frame · Primary loot distribution and selection flow
Modules/lootFrame.lua - Session · Loot session management and state transitions
Modules/sessionFrame.lua - Sync · Module-level synchronization and state exchange
Modules/Sync.lua - Version check · Addon version probing and coordination
Modules/versionCheck.lua - Options · Addon configuration and settings integration
Modules/options.lua
UI
Reusable widgets and frames
- UI root · Shared UI entrypoint and frame orchestration
UI/UI.lua - Widgets · Reusable frames, buttons, icons, text, and dialogs
UI/Widgets/widgets.xml - Export UI · Export dialogs and larger export views
UI/Widgets/ExportFrame.lua - Import UI · Import dialogs and data entry screens
UI/Widgets/ImportFrame.lua
Dependencies
Embedded libraries and platform boundary
- Ace3 · Lifecycle, config, db, event, and timer infrastructure
Libs/AceAddon-3.0/AceAddon-3.0.lua - UI libs · Shared media, dialog, window, and dropdown helpers
Libs/LibSharedMedia-3.0/LibSharedMedia-3.0.lua - RxLua · Observable and subject primitives for event-driven flows
Classes/Lib/RxLua/Observable.lua - WoW API · In-game API for frames, events, items, and chat
Tests
Behavioral and API emulation coverage
- Specs · Unit, integration, and API-emulation coverage
.specs/README.md
Connections 39
- TOC → Core init: loads · Manifest loads the main bootstrap file
- TOC → ML core: loads · Manifest also loads the master-looter bootstrap
- Core init → Addon core: initializes · Bootstrap creates and wires the central addon core
- ML core → Addon core: extends · Master-looter path builds on the shared addon core
- Addon core → Constants: uses · Core runtime consumes shared constants
- Addon core → Events: uses · Core runtime relies on shared internal events
- Addon core → Defaults: uses · Core runtime loads default settings
- Addon core → Updates: uses · Core runtime applies compatibility updates
- Addon core → Comms: uses · Core coordinates addon-to-addon communication
- Comms → Restrictions: governed by · Transmission behavior is constrained by comms rules
- Addon core → MLDB: owns state · Core keeps the main persistent loot/session database
- Addon core → Player: models · Core tracks raid member and candidate records
- Addon core → Council: models · Core tracks council membership state
- Addon core → Utils: uses · Core shares generic helpers and compatibility logic
- Utils → Item helpers: includes · Item helpers concentrate parsing and lookup logic
- Utils → Loot helpers: includes · Loot helpers isolate group loot behavior
- Addon core → UI root: drives · Core state and events drive UI composition
- UI root → Widgets: builds from · Higher-level frames are assembled from reusable widgets
- UI root → Export UI: contains · Export flows are rendered through dedicated UI frames
- UI root → Import UI: contains · Import flows are rendered through dedicated UI frames
- Addon core → History: feeds · Loot and session events flow into history capture
- History → CSV import: round-trips with · History supports import/export data interchange
- Addon core → Sync: orchestrates · Core coordinates sync module behavior
- Sync → Comms: syncs via · Sync module exchanges state across clients through comms
- Addon core → Trade UI: orchestrates · Core state drives trade handoff workflow
- Addon core → Voting: orchestrates · Core state drives voting and roll collection
- Addon core → Loot frame: orchestrates · Core state drives loot distribution UI
- Addon core → Session: orchestrates · Core state drives session transitions
- Addon core → Version check: orchestrates · Core coordinates version probing and checks
- Addon core → Options: configures · Core exposes settings through the options module
- Ace3 → Addon core: provides · Ace3 supplies lifecycle, config, db, and event infrastructure
- UI libs → Widgets: provides · Embedded UI libraries support custom controls and dialogs
- RxLua → Addon core: enables · Reactive primitives support event-driven internal flows
- WoW API → Addon core: hosts · Runtime code executes against the WoW client API
- Specs → Addon core: validates · Specs cover core logic and shared data behavior
- Specs → Trade UI: validates · Integration tests cover the trade flow
- Specs → Voting: validates · Integration tests cover voting behavior and rolls
- Specs → History: validates · Specs cover history import/export behavior
- Specs → WoW API: uses · Specs rely on an emulated WoW API boundary