wow_bejeweled/docs/architecture.md

Target architecture (post-analysis)

The analysis phase gate is satisfied. This ownership map now governs runtime implementation; currently implemented modules are Core/Init.lua, Core/Constants.lua, Core/Audio.lua, Core/SavedVariables.lua, Engine/Grid.lua, Engine/Matches.lua, Engine/Cascade.lua, Engine/Scoring.lua, Engine/Input.lua, Engine/Session.lua, UI/Fonts.lua, UI/Backdrops.lua, UI/GemPool.lua, UI/Animations.lua, UI/HUD.lua, UI/Summary.lua, UI/Skills.lua, UI/Options.lua, UI/About.lua, UI/Legal.lua, UI/MainWindow.lua, UI/Compartment.lua, and UI/Minimap.lua.

Load order and ownership

1. Core/Init.lua — addon namespace, lifecycle, and subsystem wiring.
2. Core/Constants.lua — stable enums, dimensions, atlas data, and configuration constants.
3. Core/Audio.lua — supported sound playback, legacy identifiers, frame-deferred cue coalescing, combo sequencing, quiet variants, and gem-click throttling. Window visibility is supplied as a predicate; audio owns no frames.
4. Core/SavedVariables.lua — defaulting, legacy base-70 score authentication, exact nine-row Classic save/restore/terminal-clear encoding, account-wide completed-game counts, authenticated Classic/Timed personal bests, validation, and eventual proven migrations.
5. Engine/Grid.lua — deterministic grid representation, coordinates, swaps, and legal-move state.
6. Engine/Matches.lua — pure legacy-order match detection, axis-overlap reporting, and power/hyper-gem classification; clearing and scoring remain downstream responsibilities.
7. Engine/Cascade.lua — transactional clears, matched power-gem expansion, target-color and double-hyper activation, spawned-special preservation, fixed-cell gravity, bounded refill, and repeated transitions to a stable board. It emits immutable award, lightning-link, movement, and refill records but owns no animation or scoring.
8. Engine/Scoring.lua — legacy score arithmetic, combo/mode/level multipliers, wire-compatible statistics, probabilistic skill gains, one-time achievements, rank advancement, pending/explicit level transitions, completed-game achievements, and final score/points-per-second metrics. It emits presentation events and owns no frames, text, sound, or chat publishing.
9. Engine/Input.lua — authoritative selection and move coordination, optimistic adjacent swaps, match validation, immediate engine rollback for invalid moves, legacy hyper activation, move accounting, cascade/scoring handoff, pause gating, and session/presentation locking. Cascade refills no longer force a legal result by default, preserving the legacy no-more-moves terminal path; callers may explicitly request guaranteed-legal refill fixtures.
10. Engine/Session.lua — Classic/Timed session lifetime, pause/resume state, elapsed-time gating, stable-state autosave, authenticated restore, and coordination between input, scoring, persistence, grid projection, and animation clocks. It exclusively consumes pending scoring levels after a stable move, emits copied start/complete presentation records, retains the input lock while presentation is deferred, regenerates a legal board while preserving the counts of power/hyper gems, advances level arithmetic on completion, and only then autosaves. It also detects stable boards with no legal move and Timed expiry, permanently locks terminal input, clears Classic resume state before the wipe handoff, and persists final personal-best metrics when the summary handoff completes.
11. UI/Fonts.lua — the shared live font boundary. It attempts the immutable legacy font first, then falls back to the locale-aware Blizzard standard font (or the built-in Friz Quadrata path) when Retail rejects the legacy TTF, preventing presentation construction from aborting.
12. UI/Backdrops.lua — backdrop-compatible frame construction and fresh-copy presets for tooltip, window, panel, slider, and level-border chrome. Every constructed frame explicitly inherits BackdropTemplate.
13. UI/GemPool.lua — fixed allocation and reuse of the 64 interactive gem frames, the sixteen board-art tiles, input-handler attachment, selection projection, and change-aware projection from authoritative grid cells into normal/hyper texture layers. Power-gem overlays remain UI/Animations.lua ownership.
14. UI/Animations.lua — deterministic swap/rollback and clear/gravity/refill plans, reusable animation groups, session-controlled pause/resume, interaction locking, cancellation, and final-grid normalization. It also owns the legacy-cadence 40-frame hyper atlas, counter-rotating/cross-faded power layers, pooled 16-frame explosion atlas, and pooled 15-tick lightning lines that gate settling. Nonblocking effects share the same pausable 25 ms clock: every cleared gem emits a ten-shard burst, ambient lightwaves propagate across active boards, hints delay and bounce above a selected cell, and reusable floating text supports score and status presentation. Current fall timings are explicit modernization defaults pending in-game tuning.
15. UI/HUD.lua — BackdropTemplate-safe Classic score/level/progress and Timed points-per-second/multiplier/countdown presentation. It consumes copied input/session callbacks, schedules idle hints, emits score and skill floating text through UI/Animations.lua, owns temporary status/achievement and pause overlays, and retains a compact terminal fallback for standalone HUD consumers. Its Update method only refreshes presentation and expiry clocks; Engine/Session.lua remains the sole owner of elapsed time and gameplay transitions.
16. UI/Summary.lua — the board-sized terminal presentation for copied Engine/Session.lua game-over records. It renders the legacy-proven primary metric, elapsed time, level, largest cascade, and largest combo plus modern moves and authenticated personal-best results. Its only actions are local Menu and New Game callbacks; score publication, chat, dropdown, friend, and guild behavior remain absent.
17. UI/Skills.lua — the board-sized, read-only Feats of Skill presentation. It derives the six-rank progress segment, current five-category skill challenges, personal/fun statistics, existing friends/guild Classic/Timed score tables, and unlocked/completed achievement lists from proven profile/account fields. Paginated records are copied for consumers, completed achievements sort first, and the module owns no scoring, roster queries, SavedVariables mutation, chat, or score publication.
18. UI/Options.lua — paginated controls over the proven legacy settings fields. It preserves numeric truthy toggle representation and mutually exclusive Normal/Quiet/Off sound fields, cycles the two legacy opacity values, and reports every change through an injected callback so live window/HUD behavior remains UI/MainWindow.lua ownership.
19. UI/About.lua — local How to Play, PopCap story/project, and credits/acknowledgement tabs. It owns static presentation only and has no external navigation or gameplay state.
20. UI/Legal.lua — first-run and menu-accessible legal/attribution presentation. Explicit acknowledgement writes only the established account-wide legalDisplayed field before returning through an injected callback.
21. UI/MainWindow.lua — the 448×510 movable runtime shell, 400×400 board construction, complete local Menu/New Game/Feats/Settings/About/Legal navigation, Classic Continue/New Game, and a Timed setup screen with a 2–10 minute unit-step slider defaulting to five. It owns session replacement, full-summary handoff, live setting application, first-run legal routing, and show/hide pause behavior; its frame update delegates authoritative elapsed time to Engine/Session.lua, HUD expiry to UI/HUD.lua, and queued sound flushing to Core/Audio.lua. Core/Init.lua assembles and shows this shell after ADDON_LOADED when live UIParent and player identity are available.
22. UI/Compartment.lua — the minimal public-global boundary required by Retail TOC metadata. Its left-click callback acquires or reuses the private runtime and toggles UI/MainWindow.lua; its distinct hover callbacks own anchored GameTooltip help. Right clicks and callbacks for another addon name are ignored.
23. UI/Minimap.lua — the legacy local launcher boundary. It renders the preserved icon inside Blizzard minimap chrome, toggles UI/MainWindow.lua on left click, owns hover help, and converts right-drag cursor coordinates into persisted attached angles or detached UIParent coordinates using the established profile fields. UI/Options.lua changes visibility through the injected UI/MainWindow.lua settings callback; the launcher owns no gameplay state.

Flight timing remains an explicit integration boundary rather than a third engine mode. UI/MainWindow.lua accepts paired flightOptionProvider(window) and onFlightTimedRequested(state, window) callbacks. The provider returns nil when inactive or a copied { seconds = nonnegativeNumber, learning = optionalBoolean, ... } state. Known routes under 60 seconds are shown as too short; learning and longer known routes may be selected. Only the paired request callback can consume that state, so the later Retail event adapter can own taxi observation and session transition without reintroducing the legacy estimator's unreachable APIs.

Data flow

SavedVariables initialization/restore → session-owned lifetime → engine-owned deterministic grid state → input/match/cascade/scoring transitions → UI rendering and animation → session-owned level/game-over gates → stable-state autosave and HUD/audio feedback

The engine owns authoritative game state. UI frames render state and report input; they do not become the source of gameplay truth. Audio and HUD reactions consume copied transition records, and deferred level/game-over presentation must explicitly complete its session handoff.

Compatibility boundary

BejeweledData and BejeweledProfile remain wire-compatible with the legacy snapshot until all analysis batches establish field meanings, invariants, defaults, and migration requirements. No migration schema exists in this phase.