wow-retail-backport

An Agent Skill + Python toolkit that backports any retail World of Warcraft item, transmog set, weapon or whole expansion to a WotLK 3.3.5a (build 12340) client - fitted to every race of that client, with measured rules and self-verifying gates.

Give it to Claude Code, Codex, OpenCode, Copilot or any agent that reads Agent Skills, point it at your 3.3.5a client, name what you want (“every Midnight set”, “Hallowfall Plate Armor with all its colourways”, “this one weapon”), and it runs a fixed, verified pipeline: retail tables and files in, a patch MPQ + client/server tables + server SQL out.

---

Contents

• What it does
• What a stock client can show
• Install the skill
• Quick start
• The pipeline
• Recipes
• How it fits any client and any race
• How it verifies itself
• Physics
• Repository layout
• Credits and data sources
• Legal

---

What it does

Retail WoW describes an item with database tables (which model each race and sex wears, which textures paint it, which body parts show, which hair a helm hides) and stores it in file formats a 3.3.5a client cannot read. This kit:

1. Reads retail - its DB2 tables and files at ONE pinned build, from wago.tools.
2. Reads your client - its archives in the client’s own priority, its races and body models, its tables, its free ids, its other patches. Stock, HD-patched or a custom realm client.
3. Converts every model, animation, texture, particle and table row with measured rules (each rule cites a retail table field, a wow.exe 12340 address or a measurement, and has a test).
4. Measures your client’s bodies (where each race wears a helm, which body geosets exist) and fits every item to them.
5. Writes the result - one patch MPQ (split automatically when large), the three extended client tables (also for the server), and item_template SQL for AzerothCore or TrinityCore.
6. Gates everything - crash, white, green, black, floating, vanishing, flying parts, missing files - and draws contact sheets you must look at.

Everything you add lives under a private folder and new ids above the client’s own: nothing of the client, the server or another patch is ever replaced.

What a stock client can show (Tier 1 vs Tier 2)

build --extension exports the Tier 2 pieces and a manifest; references/client-extension.md is the exact contract a client mod must meet.

Install the skill

Copy the folder wow-retail-backport/ (keep its name) into your agent’s skills folder:

Requirements: Python 3.11+, python -m pip install numpy pillow, internet access to wago.tools and github.com. Check the kit:

python wow-retail-backport/scripts/bp.py selftest      # must end with OK

Quick start

Ask your agent, for example:

Backport the retail set “Hallowfall Plate Armor” with all its colourways to my 3.3.5a client at C:\WoW\Data.

Or run it yourself (W = a project folder of your choice):

python bp.py init    --work W --client "C:\WoW\Data"
python bp.py scan    --work W
python bp.py find    --work W "Hallowfall"
python bp.py select  --work W --set 3655 --family
python bp.py fetch   --work W
python bp.py newtech --work W
python bp.py measure --work W
python bp.py build   --work W
python bp.py tables  --work W
python bp.py audit   --work W
python bp.py prove-gates --work W
python bp.py pack    --work W
python bp.py sheet   --work W        # then LOOK at every picture in W/sheets
python bp.py status  --work W        # the ticked checklist and the next command

The result is in W/out/: patch-.MPQ (+ more parts if large), dbc/, sql/item_template.sql and INSTALL.txt with the exact player and server-admin steps.

The pipeline

Extra: status (checklist + next step), phys (retail physics dump / rest-pose simulation), convert-model (any single retail model: doodads, effects).

Recipes

How it fits any client and any race

Nothing about races or bodies is hard-coded:

• Races come from the client’s own ChrRaces.dbc (columns located by content, so custom layouts work), matched to retail by id and prefix; custom races map with race_map in bp.json.
• Which helm a body wears: retail’s own cut for that race, else retail’s fallback chain, else an invisible stand-in (never a checker box).
• Helm placement: measured per body from helm files your client and retail both ship (one constant per race/sex; e.g. legacy Human male 6 cm forward, 18 cm up). Without pairs, estimated from the head bone and flagged for review.
• Body geosets: each retail variant your bodies lack (boots 506…510, kneepads 905, …) becomes the closest shape your bodies have, measured mesh to mesh.

How it verifies itself

• A ticking ledger: every step records PASS/FAIL; a step refuses to run until the steps it depends on have passed, and re-running a step un-ticks everything after it.
• Gates (audit): closure (every file exists), check_264 (every array and index the client reads), the unchecked-read crash sites of wow.exe, bone palettes (no vertex on a billboard bone), bounding boxes (nothing vanishes), white batches, sequence 0 resident, motion sampling (nothing flies off), texture limits (size, encoding, header), green-texture rule, helm placement on every body, table integrity.
• prove-gates: plants a floating helm, a green texture, a missing file, a wrong bone palette, shrunken bounds, a white batch, an external sequence 0 and a bone flying 10 m into a copy of your build - the audit must catch every one.
• newtech: compares every retail file against a registry of what the kit has measured; a new chunk, flag, blend mode, texture type or table column stops the run before it is converted wrong.
• 27 unit tests (selftest), pinning rules that once broke items in game.

Physics

Retail moves capes, plumes and chains with a runtime physics engine (.phys); a 3.3.5a client has none. The kit reads .phys completely (phys dumps bodies, shapes, joints, motors) and ships retail’s own engine, ported:

• scripts/ref/physics_domino.{h,cpp} - Blizzard’s “Domino” solver (3D Box2D family) ported instruction by instruction from the Midnight 12.1 client: drive, island, shoulder / revolute / weld joints, capsule and hull contacts (GJK, SAT with feature cache, clipping, reduction), rolling and twist friction, retail’s SSE estimate + Newton numerics. Proven against the client’s own machine code run in an emulator (references/rules.md section 6d). The client-mod contract (addresses, the mirrored scene matrix, the model’s own matrix, data row) is references/client-extension.md section 5.
• physbake.py - offline rest-pose study tool (phys --settle, --survey).

On a stock client models ship in retail’s authored bind pose.

Repository layout

README.md
wow-retail-backport/              the skill (copy this folder)
  SKILL.md                        what an agent reads first: rules, pipeline, recipes, symptoms
  references/
    pipeline.md                   every step in detail + recipes
    rules.md                      every conversion rule with its evidence
    bodies-and-races.md           fitting any client's races and bodies
    delivery.md                   archives, tables, ids, SQL, install, coexistence
    troubleshooting.md            debugging loop, gate failures, every issue met, crash triage, in-game checklist
    new-retail-tech.md            catching and supporting new retail technology
    client-extension.md           Tier 2 contract for client mods (3D pieces, buckles, races, physics)
  scripts/
    bp.py                         the command line
    lib/                          the toolkit (pure Python + numpy + Pillow)
    ref/                          retail's physics engine ported (C++ reference for client mods)
    data/known_tech.json          what retail uses (measured registry)
    tests/                        selftest

Credits and data sources

• wago.tools - retail DB2 tables and files by FileDataID.
• wowdev/wow-listfile - the community listfile.
• wowdev.wiki - M2, BLP, DB2 and PHYS format documentation.
• WoW Model Viewer and wow.export sources - geoset and item-rule cross-checks.
• Rules were measured against the WotLK 3.3.5a (12340) client and retail 12.1.0.69933.

Legal

This is a fan tool, not affiliated with or endorsed by Blizzard Entertainment. It ships no Blizzard assets: it downloads data from public community sources at run time, for your own use. World of Warcraft and its assets are trademarks and copyright of Blizzard Entertainment.