165 lines
8.9 KiB
Markdown
165 lines
8.9 KiB
Markdown
# CoA offline reference pipeline
|
|
|
|
The reference pipeline prepares source evidence for implementing all 21 Conquest
|
|
of Azeroth classes. It reads existing client files first, generates a searchable
|
|
dataset, and compares source versions. An explicit offline promotion updates the
|
|
active CoA catalogs. CoA remains Needs Testing; source coverage does not certify
|
|
class mechanics or balance.
|
|
|
|
## Sources and version boundaries
|
|
|
|
The default source pair is `H:/resources/client` and `H:/LadiksMPQEditor` when both
|
|
exist. Otherwise the pipeline uses the project's sibling `resources/client` and
|
|
`LadiksMPQEditor` directories together. In this workspace those are under
|
|
`F:/Projects`. To choose another installation, supply both roots explicitly:
|
|
|
|
```powershell
|
|
npm run coa:reference:inventory -- --client-root H:/resources/client --extracted-root H:/LadiksMPQEditor
|
|
npm run coa:reference:build -- --client-root H:/resources/client --extracted-root H:/LadiksMPQEditor
|
|
```
|
|
|
|
The frozen July trees come from
|
|
`data/coa-reference/baselines/coa-july-2026-07-25.json.gz`. Before the first
|
|
promotion, the original active catalog is preserved losslessly in that file.
|
|
Historical reference builds keep using it after active catalog updates. Spell evidence
|
|
comes from the extracted base-client tables under `client-current`: global
|
|
`patch-T` Spell, `patch-M` class and skill metadata, and `patch-S` supporting
|
|
tables. Client `Data/Content` contributes advancement and rank evidence. Relevant
|
|
sources receive hashes and version/source labels. Original files stay intact.
|
|
|
|
July class-spell references also seed identities, including starter spells that
|
|
are absent from talent trees and progression chains. Their old DBC values are
|
|
not imported. Ownership follows global trigger/effect-168 links so the selective
|
|
spell fetch and promotion cover linked payloads in the same CoA scope.
|
|
|
|
The previous importer preferred the Area 52 `patch-D` overlay. The extraction's README
|
|
calls those effective CoA sources, while the external datamine identifies them as
|
|
Free-Pick's overlay and uses the base-client chain for CoA. The new reference
|
|
retains this disagreement as audit evidence. The combined live importer now
|
|
selects global Spell/SkillLineAbility tables for CoA and preserves the existing
|
|
Area 52 preference for classic classes. Shared spell IDs have separate CoA
|
|
wrappers; classic spell resolution and its triggered fallback remain isolated.
|
|
|
|
The optional external source is `srhinos/coa-datamine` at commit
|
|
`5078f9ac22541c45c17a866c23aac6c12073de23`. Its published talent capture is dated
|
|
August 12, 2026. It is a distinct source version applied only by the explicit
|
|
promotion command. A surviving API or capture labeled `live` describes source
|
|
availability/content at capture time, not the current availability of a realm.
|
|
|
|
The explicit supplement fetch downloads the pinned talent capture, all 21 derived
|
|
talent-tree records, and their identity/provenance metadata. It does not download
|
|
the full client extraction or game assets. Git blob hashes and the
|
|
capture's published SHA-256 verify the files. Valid cached files are reused, and
|
|
interrupted downloads resume at file boundaries. No Exiles crawling is performed.
|
|
|
|
## Offline active-catalog promotion
|
|
|
|
```powershell
|
|
npm run coa:reference:fetch
|
|
npm run coa:reference:fetch:spells
|
|
npm run coa:reference:promote
|
|
npm run coa:catalogs:refresh
|
|
```
|
|
|
|
The spell fetch is an explicit, selective download of pinned global BASE raw
|
|
shards needed for spell IDs absent from the local global table. It includes
|
|
linked payloads and verifies the stored shard hashes. It never selects the
|
|
archive's Area 52 table. Unresolved old progression ranks retain their identities
|
|
and are reported as gaps.
|
|
|
|
Promotion reads only verified caches and local files. It resolves React Flight
|
|
text references in the captured builder before normalizing nodes, filters empty
|
|
metadata tabs from playable trees, and checks preservation before atomically
|
|
replacing `src/game/coaLiveData.generated.json`. The machine-readable result is
|
|
`data/coa-reference/promotion-report.json`. A failed check retains the active
|
|
catalog. Repeating promotion with the same inputs produces identical bytes.
|
|
|
|
Existing `coa-entry-*`, `coa-tree-*`, tree IDs, and progression-chain IDs survive.
|
|
Saved talent ranks still follow the normal clamping rules when the captured
|
|
maximum rank decreases. An existing node ID can carry a revised effect: August
|
|
exchanges the spell payloads of Pyromancer's Agonizing Burns/Timed Attacks and
|
|
Cultist's Dark Infusion/Darkward. Saves have no capture-version field, so numeric
|
|
ID preservation does not preserve the old effect. Review affected builds after
|
|
updating. Existing classic spell records, chains, and generated abilities are
|
|
preserved and checked separately.
|
|
|
|
The refresh command regenerates CoA runtime data and its class shards, resolves
|
|
triggered spells from global data, and exports missing icons. It preserves the
|
|
existing non-CoA talent records and UI shards.
|
|
|
|
## Build, search, and audit
|
|
|
|
```powershell
|
|
npm run coa:reference:inventory
|
|
npm run coa:reference:fetch
|
|
npm run coa:reference:build
|
|
npm run coa:reference:audit
|
|
npm run coa:reference:lookup -- --class barbarian --tree Brutality --limit 5
|
|
npm run coa:reference:lookup -- --class barbarian --ability "Ancestral Strike" --limit 5
|
|
npm run coa:reference:lookup -- --spell 800380 --limit 5
|
|
```
|
|
|
|
Fetching is optional and explicit. Build, audit, and lookup work offline. A build
|
|
without the archive produces a local-only reference and identifies the missing
|
|
comparison. Run fetch and then build to add it. `--refresh` is supported only by
|
|
fetch, which revalidates the same pinned revision rather than choosing a new one.
|
|
|
|
`--output-root PATH` chooses a separate reference output directory; `--cache-root
|
|
PATH` chooses the supplemental cache. Defaults are `data/coa-reference` and its
|
|
`cache` subdirectory. Lookup accepts numeric class IDs or HealerMan class names,
|
|
tree names/IDs, spell IDs, and case-insensitive ability-name fragments. Each result
|
|
collection is limited to 20 by default; use `--limit` between 1 and 1000.
|
|
Class and tree searches include linked spell ranks and triggered spell dependencies;
|
|
those dependencies are not presented as learned abilities.
|
|
|
|
Build prints the path to the readable audit. The corresponding `audit.json`
|
|
contains detailed machine-readable findings. `reference.json` preserves nodes,
|
|
spell data, rank relationships, class catalogs, source evidence, and unresolved
|
|
relationships. Class aliases are tied to numeric class IDs, so legacy names such
|
|
as DemonHunter, Monk, and SonOfArugal do not create extra playable classes.
|
|
|
|
The report inventories each class, compares July and August nodes/trees, compares
|
|
local base spell evidence with the previous imported values, and identifies
|
|
runtime-catalog mappings. A mapping is not proof that a talent mechanic works.
|
|
The backlog prioritizes source conflicts and identity gaps before bespoke combat
|
|
behavior, player/companion integration, UI verification, and targeted balance work.
|
|
|
|
## Integrity and limitations
|
|
|
|
Snapshots are content-addressed and immutable. Build writes and verifies all
|
|
files before replacing `current.json`. Failed builds leave the last valid
|
|
snapshot selected. Rebuilding unchanged sources produces the same snapshot ID.
|
|
Audit and lookup verify the selected snapshot's manifest before reading it.
|
|
|
|
If a source file is malformed or a downloaded cache file fails its checksum, the
|
|
command stops with the affected source identified. Restore the original source
|
|
or rerun the explicit fetch before rebuilding. Missing spell/dependency evidence
|
|
is reported as a coverage gap rather than filled with speculative values.
|
|
|
|
An existing immutable snapshot with damaged files is rejected. To regenerate it
|
|
without changing the damaged evidence, build with a fresh `--output-root` and
|
|
point `--cache-root` at the existing verified cache.
|
|
|
|
Client descriptions, effect fields, and identity joins have different certainty.
|
|
The dataset preserves that evidence; it does not invent server-side base stats,
|
|
proc timing/rates, missing coefficients, or acquisition rules. Name matches alone
|
|
do not establish an exact rank identity. CAD catalog presence alone does not prove
|
|
that an ability was trainable in the captured game version.
|
|
|
|
The promoted trees and spell evidence provide the foundation for class mechanic
|
|
implementation. Bespoke procs, resource behavior, acquisition rules, and balance
|
|
still require targeted class work before promotion from Needs Testing.
|
|
|
|
## Validation
|
|
|
|
```powershell
|
|
npm run coa:reference:test
|
|
npx vitest run src/game/coaLiveCatalog.test.ts src/game/coaAbilityCatalog.test.ts src/game/coaAbilityCatalogLoader.test.ts src/game/coaSourceScope.test.ts src/game/coaPromotionPreservation.test.ts src/game/talentCatalog.test.ts
|
|
npm run release:check
|
|
```
|
|
|
|
Focused pipeline tests cover malformed inputs, source pairing/selection, missing
|
|
relationships, independent version comparison, cache integrity/resume, immutable
|
|
snapshot publication, and offline lookup. No full test suite or all-class balance
|
|
sweep is required for this development-reference change.
|