# Zone Locked

Zone Locked is a data-driven World of Warcraft Retail challenge addon. The first
zone in a route is available immediately; completing every tracked objective in
that zone unlocks the next route entry.

## In game

- `/zl` opens the route and objective window.
- `/zl start` rolls a starting zone on your current enabled continent.
- `/zl start kalimdor` rolls on a named enabled continent.
- `/zl add` appends the zone you are standing in to the route.
- `/zl status` prints progress for the current zone.
- `/zl next` prints the current unlocked progression zone.
- `/zl roll` randomly unlocks an unvisited adjacent outdoor zone after reaching 100%.
- `/zl mini` toggles the persistent compact Mini-List.
- `/zl history` opens the completion history.
- `/zl blackout` toggles the locked-zone screen cover.
- `/zl settings` opens the Blizzard AddOns settings page.

The LibDBIcon minimap launcher is titled Zone Locked and uses the challenge
crest. Left-click opens the tracker, right-click opens Settings, and dragging
remembers its position around the minimap.

The blackout is visual-only: movement, camera controls, action bars, and the
rest of the interface remain usable so the player can safely leave a locked zone.
Completed zones already present earlier in the route remain freely revisit-able
and never trigger the blackout.

Capital cities and sanctuary hubs are neutral travel spaces: they cannot be
added to a route and never trigger the blackout.

Instances are linked to their surrounding outdoor route zone. The dedicated
Instances category expands into each dungeon or raid, then into the same
Achievements, Battle Pets, Decor, Mounts, Quests, Rare Drops, and Transmog
subcategories used outdoors. Their ATT objectives contribute to the outdoor
zone's completion, and entering the instance is permitted whenever that parent
zone is active or cleared. Gnomeregan is linked to Dun Morogh and Karazhan is
linked to Deadwind Pass, including their interior floor maps.

Expansion packs can be enabled independently in Blizzard Settings. Every pack
is enabled by default and the versioned saved-variable migration preserves later
user choices. Disabled expansions disappear from journey selection and future
rolls while existing history remains intact. Vanilla uses an explicit outdoor
zone allow-list so later content physically located in Eastern Kingdoms or
Kalimdor cannot leak into the Vanilla pool.

Zone Locked relies on ATT's own login refresh and requests another guarded ATT
refresh only after Zone Locked records a new tracked completion—the same event
which produces its collection toast. Currency, unrelated loot, bag changes,
travel, and challenge configuration do not refresh ATT. Missing transmog item
names are resolved asynchronously from their source and item IDs.

The journey chooser is continent-based. Vanilla begins only in a valid starting
zone for the character's faction; race-locked introductions such as Kezan are
available only to the corresponding race. Opposing-faction questing territories
are excluded from that character's completion pool. Expansions with mandatory
story entries constrain their first roll to the appropriate entry zone or zones.

## Supplying zone data

The Retail API can check collection state for known IDs, but cannot enumerate
all historical quests or every item dropped in a zone. Add definitions to
`data.lua`, or load a separate data file after it:

```lua
local _, ZL = ...

ZL.Catalog[MAP_ID] = {
    name = "Optional zone name",
    catalogComplete = true,
    achievements = { ACHIEVEMENT_ID },
    quests = { QUEST_ID },
    mounts = { MOUNT_JOURNAL_ID },
    pets = { BATTLE_PET_SPECIES_ID },
    decor = { HOUSING_DECOR_RECORD_ID },
    transmogs = { ITEM_MODIFIED_APPEARANCE_ID },
    rares = {
        {
            npcID = NPC_ID,
            itemID = ITEM_ID,
            sourceID = ITEM_MODIFIED_APPEARANCE_ID, -- optional transmog source
            name = "Rare name: Drop name",
        },
    },
}
```

The zone-story achievement is discovered automatically where Blizzard provides
one. Quests, mount sources, battle-pet species, transmog sources, and rare loot require catalog IDs.
Cached item information is never treated as ownership; rare items are remembered
when seen in loot or the player's bags.

`catalogComplete = true` is deliberately required before a zone can unlock the
next route entry. This prevents a partially populated catalog from reporting a
misleading 100% completion.

## Included catalog

The initial Retail catalog contains Elwynn Forest, Dun Morogh, and Tirisfal
Glades. Quest eligibility is filtered by the current character's faction, race,
and class. The ID lists were curated against the MIT-licensed
[All The Things Retail zone database](https://github.com/ATTWoWAddon/AllTheThings/blob/master/db/Standard/Categories/Zones.lua).

When All The Things is enabled, Zone Locked reads its cached map data and
collection state instead of polling every quest and appearance through the WoW
API. The populated ATT group is selected for each zone and instance rather than
an arbitrary shallow reference. Outdoor scans exclude nested instance groups;
dungeons and raids receive independent objective sets. The built-in catalog
remains as a fallback and refreshes are debounced.

The objective view uses a category sidebar with percentages for achievements,
battle pets, decor, instances, mounts, quests, rare drops, and transmog. It supports text search,
missing-only or collected-only views, and ATT-order/name/completion sorting.
Search matches are marked in the sidebar and the first matching category opens
automatically. Completion-category toggles live in Blizzard's AddOns settings.
Rare-owned appearances appear under Rare Drops only.
Guild achievements are excluded from both outdoor and instance progress.

Categories are ordered alphabetically. Tooltips include ATT source/location
context where available. Shift-clicking an objective opens its copy-ready
Wowhead URL; Ctrl-click previews Transmog or Decor in Blizzard's model window;
Alt-click adds its ATT coordinates to TomTom. Alt-clicking a category waypoints
its next missing objective. Addons cannot launch an external browser directly.

Objective filters use explicit All, Missing, and Collected tabs, a searchable
category-aware result view, a clear-search control, result counts, and a dedicated
sort menu. Transmog can additionally be filtered into Zone Drops and Quest
Rewards using ATT source ancestry. The Settings page also includes a forced
Test Alert button, while expansion selection has its own Blizzard Settings page.

The Mini-List is movable, resizable, and remembers its position and dimensions. It shows the overall zone
percentage, individual category percentages, and a compact list of missing
objectives in the style of an ATT collection window. Clicking a category filters
the compact objective list to that category; clicking it again clears the filter.
Right-clicking a category opens it in the main tracker. Missing-objective rows can
be disabled from Settings. Collection alerts are also movable and remember their position.

All The Things must be installed and enabled for complete, accurate zone data,
including Decor. The built-in catalog is intentionally only a limited fallback.
TomTom is optional and is only required for waypoint actions.

## Current world coverage

Enabled expansion packs now recognize outdoor zones dynamically, including the
Eastern Kingdoms and Kalimdor for Vanilla. ATT dynamically discovers instances
whose entrance metadata identifies an outdoor parent zone. The built-in
fallback catalog still contains only Elwynn Forest, Dun Morogh, and Tirisfal
Glades, so ATT remains required for complete objectives. Border adjacency is
built dynamically by sampling Blizzard's zone-under-cursor data on each
continent map, then merged with curated corrections. Rectangle overlap is not
used. If a route reaches a cul-de-sac it continues from an already-completed
frontier; islands use a labelled crossing only after the connected frontier is
exhausted. Finished continents and enabled expansions advance automatically in
chronological order.

The History page records future objective and zone-completion transitions with
local timestamps, zone, instance, and category context. Existing completion
state establishes the baseline and is not backfilled as newly earned history.
Quest turn-ins and newly added transmog sources are also logged directly from
their Blizzard events, preventing an ATT refresh from swallowing the transition.
Tracked loot records a timestamped “Obtained X from Y” row when its loot slot is
actually cleared, rather than merely when the loot window is opened.
Every observed tracked transition is logged, including achievements, quests, mounts,
battle pets, Decor, Transmog, rare drops, instance objectives, and zone
completion. Completed continent legs are archived as journey milestones, while
the complete timestamped history remains visible. Archived journeys can be
expanded to show their route, renamed, or deleted from the History page. Enabled
collection alerts use a queue so simultaneous gains are shown individually
rather than overwriting one another.

History can be searched and filtered by zone completions, quests, or
items/collectibles. The Delete History menu can independently clear all history,
zone completion history, quest history, or item history. Clearing zone history
also rebuilds the route's cached completion state from live collection data, so
an old journey record cannot permanently clear a later reroll. The History
subcategory in Blizzard Settings provides a master tracking switch and separate
toggles for each recorded event category.
Recent Completions and Archived Journeys have persistent collapsible headers,
and each completion row can be deleted individually with confirmation. Decor
collection synchronization during login is treated as baseline data rather than
a new acquisition, preventing false login alerts.
The History toolbar exports events and archived journeys as a pipe-free ZLH2
text payload, or imports and merges either ZLH2 or legacy ZLH1 data while
reporting duplicate and invalid records explicitly.
The world-map route overlay can be disabled independently under Challenge
Interface settings.

The Mini-List header includes a compact-mode toggle beside Close. Compact mode
retains only the active-zone header and overall progress bar, stores its own
dimensions, and can be resized down to a substantially smaller footprint.

The Theme settings page offers nine palettes: Gilded Journal, Explorer's
Parchment, Arcane Ledger, Emerald Expedition, Crimson Chronicle, Frostbound
Atlas, Midnight Cartographer, Rosewood Reliquary, and Monochrome Archivist.
Themes update the main journal, route and history cards, detail panels, Mini-List,
dialogs, borders, headings, state accents, and progress bars immediately. The
gallery uses a compact three-column layout so every palette remains inside the
Blizzard Settings canvas.

Challenge progress is saved per character: routes, collected baselines,
completion history, summaries, and archived journeys are independent. Interface
preferences, expansion toggles, filters, and window positions remain account-wide.
When upgrading from an account-wide save, the first character loaded claims the
existing journey; other characters begin with clean challenge progress.

The route view is an adaptive-height journey timeline with state cards, linked
instance context, and journey-wide progress. Its compact remove action
requires confirmation before removing a zone. The adjacent-zone roll presents
every eligible border zone before revealing the winner.

Only the active zone retains its full ATT objective tree. Cleared zones are
replaced by persistent lightweight progress summaries, so collection events do
not rescan every previous route stop. Clicking a cleared route entry explains
that its data was unloaded and asks before rebuilding the detailed ATT view;
leaving that view releases it again.

The Blizzard world map uses a cached per-zone ownership raster rather than
stacking Blizzard's full-map hover textures. Individual eligible zones are
filled and outlined independently: locked zones are red, completed zones are
green, and the current zone is blue.
