Skip to content

Generator

Jump to bottom
Amelia Magee edited this page Oct 14, 2026 · 1 revision

Generator

The Generator is the Python pipeline that builds the map art and Lua data tables for the addons. It lives in src/generator/ and is not packaged with either addon.

It reads World of Warcraft game data from Blizzard's CASC archives and writes:

Output Goes to Used by
Low-resolution World and Continent maps src/addon/client/WorldMap/ Client
High-resolution *HD maps src/addon/art/WorldMap/ Art
FDIDMap.lua, CaveData.lua and other tables src/addon/client/data/ Client

Requirements

pip install -r requirements.txt   # Pillow, numpy, scipy

The Generator targets one pinned game build, set in hfwm/config/build.py. Caches are stored per build in src/generator/.cache-<product>-<build>/, so retail data cannot mix in.

Usage

Run from src/generator/:

python generateHFWM.py                        # full build
python generateHFWM.py --zones Elwynn,Durotar # limit to some zones
python generateHFWM.py --dry-run              # print the plan, write nothing
python generateHFWM.py --list-art-passes      # describe the art passes and exit

Useful flags:

  • --lowres-only: skip the high-resolution output.
  • --caves-only: run only the cave table pass (CaveData.lua).
  • --tables-only: rebuild only the Lua tables.
  • --skip-fdid-map: do not regenerate FDIDMap.lua.
  • --no-original: skip the second, unpainted dump. This saves about 175 MB and roughly half the phase-3 time.
  • --refresh: re-download cached inputs.
  • --threads, --dl-threads: control parallel work.

Pipeline

The orchestrator is hfwm/cli/main.py. It runs these phases in order:

  1. Zone database. Reads the build-pinned DB2 exports and the WDT MAID chunks.
  2. Tile download. Fetches every unique minimap tile FDID and caches it on disk.
  3. Zone processing. Stitches, crops and fits the art for the World and Continent maps. Encodes BLP2 files.
    • 3b. Runs the same stitch with every art pass off, into Original/.
  4. FDIDMap.lua. Maps each FileDataID to its bundled texture path.
  5. CaveData.lua. Rebuilds the interior map table that this build's UiMap does not list, using hfwm/gamedata/microdungeon.py.

Phase 5 downloads its own data, so --caves-only can run it alone.

Art passes

Art passes change pixels after stitching. Each one is toggled by a --<name> flag. Run --list-art-passes for the current list, options and defaults. --no-art-passes turns them all off, leaving the raw stitch with gaps black.

Code layout

Path Contents
generateHFWM.py Entry point. Calls hfwm.cli.main.
hfwm/cli/ Argument parsing and phase sequencing.
hfwm/pipeline/ Downloads and per-zone processing.
hfwm/imaging/ Art passes: ocean, effects, resampling.
hfwm/caves/ Interior and cave art, including WMO handling.
hfwm/gamedata/ DB2 readers and microdungeon data.
hfwm/formats/ BLP and WDT readers.
hfwm/lua/ Writers for FDIDMap.lua and CaveData.lua.
scripts/ Standalone helpers, such as minimap and cave tile emitters.

Release use

Both addon release workflows run the generate-world-map-assets action, which runs this pipeline. The weekly generate-world-map-assets.yml run also builds and caches the output.

Clone this wiki locally