mirror of
https://github.com/Corfirean/coa-server-manager.git
synced 2026-11-19 11:25:56 +00:00
229 lines
15 KiB
Markdown
229 lines
15 KiB
Markdown
# Per-race availability audit
|
||
|
||
Date: 2026-10-27. This is an internal implementation audit, not a supported-feature guide.
|
||
|
||
## Frozen sources
|
||
|
||
Separate `feat/per-race-toggles` branches and checkouts:
|
||
|
||
| Component | Checkout | Fetched base |
|
||
| --- | --- | --- |
|
||
| Manager | `C:/games/source/per-race-manager` | `origin/master`, `925a81f` |
|
||
| Core | `C:/games/source/per-race-core` | `origin/coa-bots`, `1c658cab46d5057a8972cebd84c840aa6fbc4a91` |
|
||
| CoA Companions | `C:/games/source/per-race-companions` | `origin/master`, `6a289fc2230ce9425924ca86dee02d0bb8d3d344` |
|
||
| Build | `C:/games/source/per-race-build` | `origin/main`, `89795b6` |
|
||
|
||
The build runbook explicitly selects `Corfirean/azerothcore-wotlk-coa:coa-bots`, not its `main`.
|
||
The old `C:/games/source/server/azerothcore-wotlk-coa` checkout instead tracks jealous-sound upstream
|
||
and has local modifications. It must not be used as the feature's release base.
|
||
The primary Manager and Companions checkouts also contain unrelated work and remain untouched.
|
||
|
||
SQUID is a separate repository, `Zyth45/mod-playerbots`, not `Corfirean/mod-coa-playerbots`.
|
||
Existing research checkout: `C:/games/source/squid-playerbots`. Its current local branch is
|
||
`fix/custom-races-existing-bots`, one commit ahead of `origin/coa`. Build policy selects the highest
|
||
stable numeric tag, so that local branch must not silently become the shipped dependency.
|
||
|
||
## Manager integration points
|
||
|
||
- `crates/coa-core/src/custom_races.rs`: package version `1.9.2`, release URLs, MPQ/root/addon lists,
|
||
hash manifests, client status, install, enable/disable and uninstall.
|
||
- `PatchTransaction`, `SavedFile`, `recover_patch_transaction`: shared client-relative journal in
|
||
`.coa-races-transaction/journal.json`, saved files and `committed` marker. Uncommitted changes roll back.
|
||
Paths use `fsx::safe_join`; file moves handle cross-volume addon locations.
|
||
- `patch_lock`: exclusive OS file lock on `.coa-races.lock`. The empty file's existence is normal and
|
||
does not prove another operation is active. Do not delete it as a stale-lock workaround.
|
||
- Client mutations reject `client::is_running`; reuse this gate and lock for availability changes.
|
||
- `patch_files`, `matches_patch`, `preserve_original`: ownership and preservation depend on manifests
|
||
and hashes, not just a filename. Availability overlay ownership needs its own verified record.
|
||
- `modules/catalog.json`: `custom-races` uses `coa_custom_races.conf` and `CoACustomRaces.Enable`.
|
||
Companions use `mod_coa_playerbots.conf` / `CoaBots.Enable`; SQUID uses
|
||
`playerbots.conf` / `AiPlayerbot.Enabled`.
|
||
- `crates/coa-core/src/modules.rs`: `toggle`, `settings_in`, `save_settings_in` write current module
|
||
configuration. Bot switches enforce stopped servers and the existing control lock.
|
||
- `src/screens/ModulesPage.tsx`: Custom Races card, master toggle, install/progress/status UI.
|
||
- `src/lib/api.ts` and `src-tauri/src/lib.rs`: existing `custom_races_status`,
|
||
`custom_races_install`, `custom_races_uninstall`, `custom_races_toggle_client` commands.
|
||
There is no per-race command or verified availability status yet.
|
||
- `src-tauri/src/lib.rs::play`: local launch reads `realms::state`, calls `client::sync_realm`, then
|
||
launches. Remote launch has a separate realmlist override path; it cannot infer a remote race policy.
|
||
- `crates/coa-core/src/realms.rs`: modes CoA, Wildcard and Warcraft Reborn; current configs are captured
|
||
under `Settings/realm-profiles/<mode>.json`. Use this mechanism rather than a parallel realm store.
|
||
Existing bot restrictions for non-CoA modes must remain effective.
|
||
- `crates/coa-core/src/clientdl.rs::apply`: manifest-based client updates, `keep_modified`, staging,
|
||
preservation of replaced files. No availability-overlay invalidation or rebuild exists today.
|
||
|
||
### Confirmed reconciliation risk
|
||
|
||
`custom_races.rs::sync_bot_races_config` writes a replacement `AiPlayerbot.ExcludedBotRaces` value:
|
||
recommended full exclusions or experimental `65,72,77,80,81`. It does not preserve arbitrary user
|
||
exclusions. `modules.rs` calls it from the master switch and BotsEnable saving; some callers discard
|
||
errors. Per-race integration cannot rely on this overwrite behavior.
|
||
|
||
`playerbots_conf_paths` can also copy a `.dist` file when no active config exists; it is not a purely
|
||
read-only discovery API. Status inspection should avoid adding more implicit writes.
|
||
|
||
## Core gates and bypasses
|
||
|
||
- `modules/mod-coa-custom-races/src/mod_coa_custom_races.cpp`: `WorldScript` loads the master switch;
|
||
`AccountScript::CanAccountCreateCharacter` accepts stock IDs 1–8, 10, 11 or an enabled master switch.
|
||
No disabled-ID list is implemented. Stock ID 9 is deliberately not included.
|
||
- `modules/mod-coa-custom-races/conf/coa_custom_races.conf.dist`: Enable and BotsEnable exist;
|
||
DisabledRaceIds does not.
|
||
- `src/server/game/Handlers/CharacterHandler.cpp`: normal character creation invokes
|
||
`sScriptMgr->CanAccountCreateCharacter` inside its finalization callback and rejects with
|
||
`CHAR_CREATE_DISABLED`. A packet from an unpatched client reaches that gate too.
|
||
- `src/server/game/Scripting/ScriptDefines/AccountScript.cpp`: hook aggregation must be preserved.
|
||
- `src/server/game/DataStores/DBCStores.cpp::LoadDBCStores`: chooses `DataDir/dbc_races/<file>` if
|
||
the master switch is enabled and that file exists, otherwise `DataDir/dbc/<file>`.
|
||
Per-race creation policy must not remove DBC rows or change login data.
|
||
- `.agents/docs/systems/ascension-character-creation.md`: native client compatibility depends on
|
||
`CharBaseInfo.dbc`; race button indices are not RaceIDs. Existing race/class checks must stay intact.
|
||
|
||
## Both bot systems
|
||
|
||
### CoA Companions
|
||
|
||
`module/src/BotSpawnRandom.cpp::GetValidBotRaces` reads the global and bot custom-race switches,
|
||
`CoaBots.CustomRaces.Enable`, and both AiPlayerbot/CoaBots exclusion lists. It checks DBC presence.
|
||
Its experimental defaults apply only when the combined exclusion set is empty: adding an owner list
|
||
to that set would silently remove those defaults. Keep those policies independent.
|
||
|
||
`CreateBotClone`, `CreateOneRandomBot`, and leveled spawning clone SQL character data directly;
|
||
they bypass the account creation hook. Enforce new-character policy at the common clone creation
|
||
entry as well as random selection. Preserve existing bots and faction selection via
|
||
`Player::TeamIdForRace`.
|
||
|
||
Additional confirmed callers: `module/src/BotBattlegroundFill.cpp::QueueBotForSide` and
|
||
`module/src/BotLfgFill.cpp` call `CreateOneRandomBot` after trying to reuse an existing bot.
|
||
The existing-bot reuse path must remain separate from creation restrictions.
|
||
|
||
`tools/offline_bot_factory.py` is another direct-SQL creation path. Its main loop chooses a
|
||
template by class and faction, then copies `template.race` into the new character overrides.
|
||
It currently does not read the custom-race creation policy. Reject or filter prohibited
|
||
templates before generating new accounts, GUIDs or SQL; do not rewrite their races.
|
||
|
||
### SQUID Playerbots
|
||
|
||
`src/PlayerbotAIConfig.cpp` loads `AiPlayerbot.ExcludedBotRaces` and adds
|
||
`AiPlayerbot.CrashingBotRaces`; it reads BotsEnable. `src/CoaBotRacePolicy.h` implements
|
||
`IsCoaBotRaceAllowed`. `src/Bot/Factory/RandomPlayerbotFactory.cpp::CreateRandomBot` applies
|
||
that policy before faction and race/class selection.
|
||
|
||
The same predicate also appears in `src/Bot/RandomPlayerbotMgr.cpp` and
|
||
`src/Bot/PlayerbotMgr.cpp`, including existing-character admission. Do not append owner creation
|
||
restrictions globally to this shared exclusion vector: that would also affect existing bots.
|
||
The predicate currently does not itself require `CoACustomRaces.Enable`.
|
||
`RandomPlayerbotFactory.cpp` calls `Player::Create` directly without the account hook.
|
||
Use a creation-only check in this factory, leaving existing-character admission unchanged.
|
||
|
||
## Portable Characters
|
||
|
||
Manager import code is under `crates/coa-core/src/portable/realm/`.
|
||
`import.rs` validates identity namespaces and race/class start data (`UnknownRaceClass`).
|
||
Availability policy must not become an import rejection or an identity rewrite. The inspected
|
||
creation hook is in the normal packet handler, not this importer. In the core,
|
||
`src/server/coa/CoAPortableImport.cpp` checks `GetPlayerInfo(model.Race, model.Class)` and writes
|
||
`model.Race` to the imported character and character cache. It does not invoke the account
|
||
creation hook. Preserve this separation. Live compatibility is still untested.
|
||
|
||
## Client experiment, actual observations
|
||
|
||
The owner updated `C:/games/Ascension` from 1.9.1 to 1.9.2 during this audit; its manifest now says
|
||
`# CoA Custom 1.9.2`. A separate physical client copy is being prepared under
|
||
`C:/games/source/per-race-evidence/client`; game assets are outside Git. The copy completed:
|
||
25646 files copied, zero failures. The separate server file copy also completed, but has not
|
||
been configured or started. No database service has been started for this task.
|
||
|
||
Read-only MPQ membership probing found ChrRaces in patch-ZZZF, ZZZE, ZZZC, ZZZ, ZZW, ZZV, ZZU,
|
||
ZZS, T, M and several locale archives. CharacterCreate.lua has multiple owners too.
|
||
The old `mpqprobe.py` precedence model explicitly admits an inference for Ascension multi-letter
|
||
archives. Therefore `patch-ZZZF.MPQ` is a candidate source, not runtime-confirmed effective data.
|
||
`patch-ZZZZ.MPQ` exists already; no overlay filename has been qualified.
|
||
|
||
Extracted from `patch-ZZZF.MPQ`:
|
||
|
||
- WDBC, 95 records, 69 fields, record size 276, string block 2428, total bytes 28668.
|
||
- SHA-256 `b78635b08bf0bd63d2898fce97c1fb162c8a9c41632703172eefa88bae79061f`.
|
||
- Actual rows: Sethrak 82, Gnoll 83, Saberon 97. Their Flags are 12.
|
||
- String block starts with `Hu`, not NUL; imposing an initial empty-string invariant incorrectly
|
||
rejects this real table. String boundaries and referenced offsets still need validation.
|
||
- Sethrak experiment changes only Flags 12 → 13. All other bytes compare equal.
|
||
- One generated MPQ was read back through StormLib; its DBC equals the expected patched bytes.
|
||
- The installed `pympq` Python extension crashed during interpreter finalization. The experimental
|
||
tool instead uses the installed Unicode StormLib DLL directly. It is not a runtime dependency
|
||
proposal for Manager or its users.
|
||
|
||
`tools/race_availability_poc.py` requires an explicit source archive and creates output only in a new
|
||
directory. It does not select an archive order, install an overlay or assert in-game success.
|
||
`tools/test_race_availability_poc.py` uses synthetic bytes only.
|
||
|
||
### Background verification after interactive testing was deferred
|
||
|
||
The owner requested no screen capture/input and no client/server/MySQL launches while other bot
|
||
tests run. These restrictions remain active. The owner reported that the copied client launches;
|
||
this does not confirm creation behavior or effective DBC loading.
|
||
|
||
- 17 DBC/fingerprint tests and 8 synthetic MPQ integration tests pass (25 total, none skipped).
|
||
- Native tests use the explicitly selected existing Unicode StormLib DLL, with no new install.
|
||
- Output is built and verified in a temporary directory before publishing the offline result folder.
|
||
Failures leave no published result; this is not the future client transaction implementation.
|
||
- One and fifty disabled races both produce one MPQ. StormLib adds an internal `(listfile)`;
|
||
the sole game payload is `DBFilesClient/ChrRaces.dbc`.
|
||
- Every referenced localized race-name offset is bounds-checked; invalid UTF-8 is rejected.
|
||
- The experimental fingerprint includes original DBC SHA-256, normalized IDs, algorithm version
|
||
and explicitly recorded profile. A profile label does not prove client compatibility.
|
||
- The real three-race offline experiment is in
|
||
`C:/games/source/per-race-evidence/multiple-races-offline/report.json`.
|
||
Source MPQ SHA-256: `40eac695cfcafb598b8376f3b9a61ecc037e4d445b87279cfe387a91edad32c3`.
|
||
Generated DBC SHA-256: `243fb36837b76ebd6943da574cc095be548b4530be7f06487debea6703db10d3`.
|
||
|
||
The first copy launch showed a missing-critical-files message and subsequently crashed on exit.
|
||
The crash report identifies `AMDXN32.DLL` in the AMD graphics driver at the fault address; this
|
||
does not establish the root cause. EXE, Extensions, dinput8, d3d9, dxgi, EsteriaAppearance and
|
||
patch-ZZZF hashes matched the primary client during comparison. The experimental overlay was
|
||
not installed. No graphics-driver or client-runtime changes were made to work around the crash.
|
||
|
||
## Reference implementations and update preservation
|
||
|
||
Inspected read-only reference clones:
|
||
|
||
- `aspollon/AFK-Realm` at `ea9c5bf691c98cace8cc03c06183c161022946de`.
|
||
- `aspollon/mod-custom-races` at `5a8f2ff8a0d494ffadf64e677a438aa7f5a6671b`.
|
||
|
||
`mod-custom-races/afk-realm.json` declares client patch generation and GlueXML Lua insertion.
|
||
`client/CustomRaces.lua` extends and lays out buttons, using race names/files and configured IDs.
|
||
This is a reference, not evidence of compatibility with the current CoA/Esteria UI or a reason
|
||
to replace CSM's prebuilt-server distribution.
|
||
|
||
`crates/coa-core/src/config/merge.rs` performs additive `.dist` merging: missing keys are added,
|
||
existing user values and unknown keys are retained. A new DisabledRaceIds key should use this
|
||
path. Existing realm snapshots already capture module `.conf` files. Neither mechanism currently
|
||
coordinates an availability overlay with client update/repair; that remains implementation work.
|
||
|
||
## Open gates
|
||
|
||
Update after the owner found the existing Hide Races panel: see
|
||
[existing-filter research](docs/PER_RACE_EXISTING_FILTER_RESEARCH.md). The inspected Lua already
|
||
supports personal name/index-based hiding, but it is not a realm-scoped RaceID policy. Nine
|
||
offline Lua 5.1 probes confirmed key behavior and limitations. Reusing its layout/UI is now a
|
||
candidate to investigate before choosing a production DBC implementation. This is not evidence
|
||
that the DBC approach failed, and it does not qualify client support.
|
||
|
||
The owner subsequently confirmed the GlueXML probe: restricted races disappeared from selection
|
||
and were grey, unchecked and disabled in Hide Races. The production client integration should
|
||
reuse this filter; changing DBC flags is no longer the selected implementation path.
|
||
|
||
Server controls, strict catalog-bound configuration, the core creation hook and both bot factory
|
||
guards are implemented and have passed offline checks and native builds. Existing-bot admission
|
||
and user/crashing exclusions remain separate from the new creation policy.
|
||
|
||
Remaining gates:
|
||
1. Integrate automatic client reconciliation, ownership and recovery with realm settings.
|
||
2. Qualify client update/repair and shared-client PLAY behavior.
|
||
3. Verify live creation rejection/re-enable, existing-character login, imports and both bot systems
|
||
when the owner's database test environment becomes available.
|
||
|
||
Status: **PARTIAL** — server implementation and builds pass; live server acceptance and production
|
||
client synchronization remain pending. See docs/PER_RACE_TOGGLES_TESTS.md for exact scope.
|
||
No existing character data, production service, release channel, or primary client archive was changed.
|