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](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` | ~50 KB | FrameXML overrides. Replaces stock `PlayerFrame.lua` / `RuneFrame.lua` / `ComboFrame.lua` / `UnitFrame.lua` / `SpellBookFrame.lua` + `SpellBookFrame.xml` with Paragon-aware versions: rune simulator, combo-point simulator, server-authoritative resource sync over the `PARAA` addon channel, action-button usability + click guards, an expanded spellbook (higher `MAX_SPELLS`, 24 skill-line tabs instead of stock 8) so all-class spells render, and a tooltip post-processor that appends ", Paragon" to the "Classes:" line on class-restricted gear / glyphs (the server bypasses `AllowableClass` for class 12, but the engine paints the line red and omits Paragon — the Lua hook recolors it green and adds the name so the player can tell it's wearable). |
| `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** (sometimes shown as
"Error creating character") when you pick it -- **or** the character
is created but spawns with no weapon / armor proficiencies (auto-attack
greys out, can't equip anything beyond a fist), or with the proficiency
**skills** but no **passive spells** like Block, Parry, Dual Wield --
the worldserver is missing one of four pieces of class-12 data. All
ship as SQL migrations under
`modules/mod-paragon/data/sql/db-world/updates/` and are auto-applied
by AzerothCore's DBUpdater on every `ac-db-import` run, but the SQL
files are baked into the dbimport Docker image at build time -- so a
stale image won't pick up new migrations. Fix:

```bash
git pull origin main
docker compose build ac-db-import ac-worldserver
docker compose up -d ac-db-import
docker compose restart ac-worldserver
```

Existing class-12 characters created before these migrations will
keep their broken state -- the cascade only fires inside
`Player::Create` and `Player::LearnDefaultSkill` at character spawn.
Delete the old Paragon and re-roll after the rebuild.

The four migrations:

- `2026_05_09_00.sql` -- DBC overlay rows for `chrclasses_dbc` and
  `skillraceclassinfo_dbc`. Without this the server can't even
  resolve class 12 in `sChrClassesStore`. See **Server-side Paragon
  DBC overlay** below.
- `2026_05_10_00.sql` -- `playercreateinfo`, `playercreateinfo_action`,
  and `player_class_stats` rows for class 12. Without this
  `Player::Create` rejects every (race, class=12) pair as an
  "invalid race/class pair" and the worldserver prints
  `class-N Level-L does not have stats data!` integrity warnings on
  load.
- `2026_05_10_01.sql` -- 20 `playercreateinfo_skills` rows
  (`classMask = 2048` = class 12) granting every weapon /
  armor proficiency at level 1. Without this a Paragon spawns with
  only the universal `classMask = 0` skills (Defense, Unarmed,
  Cloth, languages, Mounts) -- no Swords, no Mail, no Shield, etc.
- `2026_05_10_02.sql` -- 3,314 `skilllineability_dbc` rows opening
  the class-12 bit on every SkillLineAbility row our patched
  `SkillLineAbility.dbc` modified. AC reads these rows in
  `Player::LearnDefaultSkill` to drive the `skill -> passive spell`
  cascade. Without it the proficiency *skills* from `_01.sql` exist
  but the *passive spells* (Block, Parry, Dual Wield, Defense,
  weapon Shoot, racial Mace/Sword Specialization, etc.) never auto-
  learn, so the spellbook past the racials looks empty.

After the rebuild + restart, `ac-worldserver` should log
`>> Loaded 72 Player Create Definitions` (was 62 pre-Paragon),
`>> Loaded 1391 Player Create Skills` (was 1371),
`>> Loaded 10219 SkillLineAbility MultiMap Data` (unchanged total --
the SQL overlay replaces existing rows by ID, doesn't add new ones),
and character creation succeeds for any DK-eligible race with a full
weapon / armor kit and the matching passive spells.

If the client **logs in** successfully but **disconnects immediately**
when entering the realm: the auth server is handing your client the
wrong world-server address. On a fresh local install the seed defaults
to `127.0.0.1` (commit landing this paragraph). If your DB was
imported from an older Fractured checkout, the seed may still point at
`hsrwow.net`, which sends the client to our production world server
instead of yours. Fix:

```bash
# Docker:
docker exec ac-database mysql -uroot -ppassword \
  -e "UPDATE acore_auth.realmlist SET address='127.0.0.1' WHERE id=1;"
docker compose restart ac-authserver
```

Substitute your public hostname/IP for `127.0.0.1` if remote players
will be connecting. See `BUILD-NATIVE.md` -> *Production deployment
overrides* for the full list of values to set on a production box.

---

## Server-side Paragon DBC overlay (automatic)

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** and no class-12 bit on
`SkillRaceClassInfo` rows, which would normally trigger:

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

…and reject the create with `CHAR_CREATE_FAILED`.

To remove that gap, the repo ships
`modules/mod-paragon/data/sql/db-world/updates/2026_05_09_00.sql`,
which `INSERT`s the Paragon class-12 deltas into:

- `chrclasses_dbc` — 1 row defining class 12 ("Paragon", power=Mana,
  family=Warrior, expansion=2).
- `skillraceclassinfo_dbc` — 235 rows replacing stock entries with the
  patched ClassMask (class-12 bit OR'd in) so every baseline skill is
  available to Paragon characters.

`AzerothCore`'s DBC loader (`DBCStores.cpp::LoadDBC` -> `LoadFromDB`)
merges these rows on top of whatever `data/dbc/` contains at every
worldserver boot. The DBUpdater in `ac-db-import` (Docker) or the
worldserver itself (native) applies the migration automatically — so
the **only** steps a fresh contributor needs are `git clone` and
`docker compose up -d`.

### Regenerating the migration

The SQL is auto-generated from the patched DBCs that already live
inside `patch-enUS-4.MPQ`. The bake script lives outside this repo
(per the repo-tidy policy) at:

`fractured-tooling/from-workspace-root/_gen_paragon_dbc_overlay_sql.py`

Re-run it whenever you change the Paragon DBC bake — for example,
adding a new race to the Paragon class mask. It diffs the patched
DBCs against a stock 3.3.5a DBC extract and emits a fresh
`2026_05_09_00.sql` (or successor migration with a new timestamp if
deltas change). Workflow:

```powershell
# Extract the patched DBCs once:
.\tools\mpq\mpqcli.exe extract `
    "ChromieCraft_3.3.5a\Data\enUS\patch-enUS-4.MPQ" `
    -o "$env:TEMP\paragon-dbc-extract"

# Regenerate the SQL migration:
python fractured-tooling\from-workspace-root\_gen_paragon_dbc_overlay_sql.py
```

If the regenerated SQL has new content, commit it as a **new** dated
migration filename (e.g. `2026_06_01_00.sql`) — never edit a file that
has already been applied to live databases, AC's DBUpdater will detect
the hash change and re-run the SQL, which can be fine but is best
reserved for emergencies.

### Manual DBC overlay (rare, fallback)

If you ever need the patched DBCs *on disk* — e.g. for a tool that
reads `data/dbc/` directly outside the worldserver, or to verify a
client-vs-server DBC mismatch — extract `patch-enUS-4.MPQ` and copy
its `DBFilesClient/*.dbc` into `data/dbc/`:

**Docker:**

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

**Native:** copy into `<CMAKE_INSTALL_PREFIX>/data/dbc/` and restart.

This is **not required** for normal operation — the SQL migration
covers everything `mod-paragon` needs at runtime. Use the manual
overlay only when you're consciously bypassing the SQL merge layer.

---

## 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.