# Fractured Client Patches

Binary client artifacts that pair with this server. They live on the
[Releases page](https://github.com/Dawnforger/Fractured/releases),
**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:

```bash
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):

```bash
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):

```powershell
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.