Docker Build
fae3ff5028
Stock Docker installs fill data/dbc/ from the vanilla 3.3.5a extract
in `ac-wotlk-client-data`, which has no class 12 in ChrClasses.dbc and
no class-12 bit on SkillRaceClassInfo.dbc. CharacterHandler.cpp's
sChrClassesStore.LookupEntry(12) returns null and the create fails
with CHAR_CREATE_FAILED ("Class (12) not found in DBC ...") before the
contributor ever sees the panel. Fixing it required hand-copying the
patched DBCs onto the named volume — undocumented, fragile, and not
portable to native installs.
DBCStores.cpp::LoadDBC merges every <table>_dbc world-DB row on top of
the on-disk DBC store (storage.LoadFromDB after storage.Load). We use
that merge layer to ship Paragon's class-12 deltas as SQL:
- chrclasses_dbc: 1 row defining class 12 (Paragon, power=Mana,
family=Warrior, expansion=2). Resolves CHAR_CREATE_FAILED.
- skillraceclassinfo_dbc: 235 rows REPLACEing stock entries with the
patched ClassMask (class-12 bit OR'd in) so baseline skills (defense,
weapon skills, etc.) are available to Paragon characters.
The new `modules/mod-paragon/data/sql/db-world/updates/2026_05_09_00.sql`
is applied automatically by AC's DBUpdater on every fresh `ac-db-import`
run (Docker) or first worldserver boot (native). End-to-end verified
locally: truncate -> docker compose up ac-db-import -> rows reappear
with hash 33B1A05 recorded in updates table.
The migration is auto-generated by
fractured-tooling/from-workspace-root/_gen_paragon_dbc_overlay_sql.py
(outside this repo per the repo-tidy policy). Re-run it whenever the
DBC bake changes.
CLIENT-PATCHES.md is rewritten so contributors no longer need the
manual DBC sync section as their primary install path. Manual overlay
is preserved as a labelled fallback for tools that read data/dbc/
directly.
Co-authored-by: Cursor <cursoragent@cursor.com>
182 lines
8.0 KiB
Markdown
182 lines
8.0 KiB
Markdown
# 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 on a
|
|
**very old** server checkout (predating commit landing
|
|
`modules/mod-paragon/data/sql/db-world/updates/2026_05_09_00.sql`):
|
|
pull `main` and run `docker compose up -d ac-db-import`. Recent
|
|
Fractured server builds ship the Paragon DBC overlay as a SQL
|
|
migration (see **Server-side Paragon DBC overlay** below); fresh
|
|
checkouts do **not** need the patched DBCs copied into `data/dbc/`.
|
|
|
|
---
|
|
|
|
## 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.
|