Fractured/contrib/fractured-dev-extras/CLIENT-PATCHES.md

Fractured Client Patches

Binary client artifacts that pair with this server. They live on the Releases page, not in the tree, so the repo stays lean and binaries can be re-downloaded without bloating git clone.

This file is the table of contents and install guide.

---

What ships in a release

Artifact	Size	Purpose
patch-enUS-4.MPQ	~5 MB	DBC + GlueXML bake. Adds CLASS_PARAGON (id 12), the character-create slot, glue strings, talent-tab DBC entries, and the Paragon resource bar definitions. Required for character creation as Paragon to even show up.
patch-enUS-5.MPQ	~40 KB	FrameXML overrides. Replaces stock PlayerFrame.lua / RuneFrame.lua / ComboFrame.lua / UnitFrame.lua with Paragon-aware versions: rune simulator, combo-point simulator, server-authoritative resource sync over the PARAA addon channel, action-button usability + click guards.
patch-enUS-6.MPQ	~160 KB	The ParagonAdvancement addon. Replaces the talent pane (N key) for Paragon characters with the Character Advancement panel: per-class spell tabs, talent grid, Overview/Search tabs, AE/TE currency, commit / reset / preview, login-time toast suppression.
Wow.exe	~7.5 MB	3.3.5a (build 12340) client byte-patched to skip the MPQ signature check so custom patch-enUS-N.MPQ files load. Diff against stock is a few bytes; everything else is unchanged.

Server and client work as a pair: the addon talks to mod-paragon on the worldserver via WHISPER addon-channel messages with the PARAA prefix (currency push, spell/talent snapshot, commit, combo points, rune cooldowns, learn-toast silence window). Mismatched versions usually manifest as the panel rendering blank or AE/TE reading 0/0.

---

Install

You need a 3.3.5a (build 12340) WoW client. ChromieCraft's free 3.3.5a download is the canonical clean source if you don't already have one.

1. Download every artifact from the latest release matching this server build: https://github.com/Dawnforger/Fractured/releases/latest
2. Replace Wow.exe at the root of your client install with the patched one from the release. Keep a backup of the original if you want.
3. Drop patch-enUS-4.MPQ, patch-enUS-5.MPQ, patch-enUS-6.MPQ into Data/enUS/. (For other locales, rename the suffix accordingly — contents are locale-independent, only the filename ordering matters to the loader.)
4. Edit Data/enUS/realmlist.wtf to point at your server, e.g. set realmlist your.host.tld.
5. Launch Wow.exe. The login screen should reach the realm list. Make a Paragon character (the new class entry on the create screen) and press N in-world to open the Character Advancement panel.

If the panel opens empty / AE+TE read 0/0 / N opens the stock talent pane: your client is loading an older patch-enUS-6.MPQ, or the worldserver image is older than commit 4d2a80d (the character_paragon_panel_spell_revoked migration). Pull both ends to the same release tag and rebuild the worldserver image.

If the client shows the Paragon class on the create screen but the server replies Character Creation Failed when you pick it: the worldserver's on-disk DBC set still does not define class 12 (ChrClasses.dbc). SQL migrations alone cannot fix that when chrclasses_dbc in MySQL is empty (normal for stock AC — AzerothCore loads .dbc files from data/dbc/ and only merges optional DB rows on top). See Worldserver DBC sync below.

---

Worldserver DBC sync (required for Paragon character create)

The Fractured client learns about Paragon from patch-enUS-4.MPQ (DBC + GlueXML). The worldserver never reads your MPQs — it reads plain .dbc files under its DataDir (.../data/dbc/ by default).

Stock Docker installs populate data/dbc/ from a vanilla 3.3.5a extract (ac-client-data-init in docker-compose.yml). That tree has no ChrClasses row for id 12, so CharacterHandler rejects the create with CHAR_CREATE_FAILED and logs:

Class (12) not found in DBC while creating new char ... wrong DBC files or cheater?

Fix: merge every .dbc that ships inside patch-enUS-4.MPQ under DBFilesClient/ (or the archive's dbc/ root — same layout depending on tool) into the server's data/dbc/ directory, then restart only ac-worldserver. Copy the whole set from the MPQ, not just ChrClasses.dbc, so dependent stores (CharBaseInfo, SkillRaceClassInfo, TalentTab, PowerDisplay, etc.) stay consistent with the client patch.

Extract from the MPQ (any OS)

Use Ladik's MPQ Editor, mpqcli, or any StormLib tool. You want every *.dbc that Fractured added or changed in that patch, staged into a host folder (example: ./paragon-dbc-extract/).

Docker: write into the named volume

Compose uses ${DOCKER_VOL_DATA:-ac-client-data} (see docker-compose.yml). Discover the real volume name:

docker volume ls | grep -i client-data

Copy extracted .dbc files into the volume's dbc/ subdirectory. Example (Linux / macOS — adjust volume name and host path):

docker run --rm \
  -v ac-client-data:/data \
  -v "$PWD/paragon-dbc-extract:/patch:ro" \
  alpine sh -c 'cp -f /patch/*.dbc /data/dbc/'
docker compose restart ac-worldserver

Windows PowerShell (same idea; escape backticks if you wrap lines):

docker run --rm `
  -v ac-client-data:/data `
  -v ${PWD}\paragon-dbc-extract:/patch:ro `
  alpine sh -c "cp -f /patch/*.dbc /data/dbc/"
docker compose restart ac-worldserver

If your compose project name prefixes the volume (e.g. fractured_ac-client-data), use that full name from docker volume ls.

Native install (no Docker)

Copy the same extracted .dbc files into:

<CMAKE_INSTALL_PREFIX>/data/dbc/

then restart worldserver.

Verify

After restart, search startup logs for errors mentioning ChrClasses or dbc. On failure you would still see the Class (12) not found line at create time — if that disappears, the DBC merge worked.

---

Building the patches yourself

The MPQs are reproducible from the dev tree (not in this repo — Classless Dev/Paragon Patch UI/ and Classless Dev/Paragon Advancement/ on the maintainer's workstation) via two PowerShell scripts in tools/:

tools\build_paragon_ui_patch.ps1 -Deploy            # -> patch-enUS-5.MPQ
tools\build_paragon_advancement_patch.ps1 -Deploy   # -> patch-enUS-6.MPQ

patch-enUS-4.MPQ is the DBC + GlueXML bake; the bake scripts live with the rest of the dev tooling and are not part of this repo by design (see the repo-tidy policy in README.txt next to this file).

The patched Wow.exe is a one-time hex-edit of the stock 3.3.5a client. The diff is publicly documented in the WoW emulation community under names like "MPQ signature patch" / "no-CD-signature patch".

---

Versioning

Releases are tagged to match the state of main they were built from. The release notes call out which server commit shipped alongside each artifact set, so a contributor running git checkout <tag> on this repo can pull the matching client bundle and have a guaranteed-aligned end-to-end build.