mirror of
https://github.com/Corfirean/coa-server-manager.git
synced 2026-11-19 11:25:56 +00:00
Imports a canonical snapshot into a stopped disposable realm through the existing Db abstraction, in one MySQL transaction: guids allocated inside the transaction from the realm's own tables and every reference remapped, orphan cleanup, name and start-position handling, self-asserting result, and a marker row. Untrusted strings and blobs reach SQL only as hex literals from a typed encoder. Manager mappings are recorded only after the realm commit, in one local transaction; an import journal (schema 3) plus the marker recover a crash between the two commits. Preflight refuses wrong ruleset, running realm, missing account/content and more before anything is written. Stock character_talent rows are never written: a real worldserver asserts on a non-talent row. Item identity no longer includes the crafter (v2). Production import remains the designed in-core PortableImportService (docs/PORTABLE_IMPORT_SERVICE.md); nothing of it is implemented. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
760 lines
64 KiB
Markdown
760 lines
64 KiB
Markdown
# Portable Characters - Phase 0 audit
|
|
|
|
Status: **Phase 0 output. No production code was written.** Everything marked *fact* was read from the real code or
|
|
from a real database schema; everything marked *proposal* or *decision* is a recommendation that needs the owner's
|
|
sign-off before the phase that depends on it.
|
|
|
|
Scope of the audit: the Manager (`Corfirean/coa-server-manager`) and the core
|
|
(`azerothcore-wotlk-coa`, characters database and the C++ that reads and writes it). The bots module was only checked
|
|
for what it puts into the characters database.
|
|
|
|
---------------------------------------------------------------------------------------------------------
|
|
|
|
## 0. Method and evidence base
|
|
|
|
| Source | What was used |
|
|
|---|---|
|
|
| Manager | `origin/master` at `cd3a963` (v0.6.4), read in a clean worktree. Baseline `cargo test --workspace --locked`: **242 tests, all green** |
|
|
| Core | local checkout `coa-core-fork`, branch `codex/squid-disabled-startup`, commit `641251c4f` (2026-10-05). Line numbers below refer to this commit and will drift |
|
|
| Characters schema | **real**, not inferred from SQL files: a disposable fixture database (`coa-schema-fixture-20261005`, copied and opened read-only on a private MySQL instance with no network port; the owner's live database was never touched). 163 tables |
|
|
| Real data shape | a second disposable fixture (`coa-fixture`, 1861 characters, 1815 of them bots, 46 on non-bot accounts) for formats and sizes. Only aggregate numbers appear in this document |
|
|
|
|
Caveats that matter for the conclusions:
|
|
|
|
* Three core revisions are in circulation on the owner's machine (the Manager's own architecture notes say the same).
|
|
Every compatibility decision below must be keyed by an **exact core commit / schema contract**, never by "latest".
|
|
* The `coa-fixture` data is older (core 0.3.0) than the schema fixture, so it has no `core.ascension_build.*` /
|
|
`core.wildcard.*` settings rows. Those sources are known from the *code*, not from sample data.
|
|
* All of the real characters in the fixtures are level 80 (45 of 46) or 21 (1), so level-cap behaviour was audited from
|
|
code only.
|
|
|
|
---------------------------------------------------------------------------------------------------------
|
|
|
|
## 1. Executive summary
|
|
|
|
**Verdict: no architectural contradiction was found that blocks Phase 1** (local canonical storage), and the model in
|
|
the task description holds. But the audit found seven facts that change *how* Phases 2-8 must be built. Each is
|
|
presented as a decision in section 14; the first three need an answer **before Phase 3**.
|
|
|
|
1. **CoA's character state is not in the stock AzerothCore tables.** CoA has 21 classes (class ids 12-32; no stock
|
|
classes in the real data) and keeps talents/builds/spec bars in `character_spell` plus **`character_settings`**
|
|
(sources `core.ascension_*`, `core.wildcard.*`, ...). `character_talent` has **0 rows** in real data. The stock
|
|
`.pdump` tool does not know `character_settings`, the wardrobe tables or any `coa_*` table, so it would silently
|
|
export a character with no build, no spec, no spec bars.
|
|
2. **Writing into a *running* realm's characters database is unsafe.** The worldserver hands out character, item and
|
|
pet ids from counters it reads once at startup, and keeps a name cache it never re-reads. An external importer that
|
|
inserts rows while the realm is up can collide with ids the server is about to hand out, and the imported
|
|
character is invisible to name lookups until a restart. The core's own `.pdump load` solves exactly this *inside*
|
|
the server. Options and a recommendation are in section 10.
|
|
3. **The database is stale during play.** Characters are persisted on an autosave timer, on logout and on a few
|
|
events, not every 60 seconds. There is no console command that saves **one** character (`.save` is player-only,
|
|
`.saveall` saves every online player, bots included). The 60-second checkpoint of Phase 5 therefore needs a small
|
|
core change.
|
|
4. **Loading a character is destructive.** The server deletes items whose entry it does not know, conjured items after
|
|
15 minutes offline, out-of-season holiday items, expired refund data, and **mails** items it cannot equip. So a
|
|
realm's *export* is not the character; applying "replace canonical with export" would permanently lose anything the
|
|
destination had to filter. Export must be reconciled against the canonical snapshot per item (section 8.4).
|
|
5. **Level-cap projection (Phase 8) cannot be done by rewriting rows.** An item above the cap's required level is
|
|
*mailed away and removed from the inventory table* on load. Phase 8 needs core-side hooks, not just a projected
|
|
snapshot.
|
|
6. **Collections are account-wide, keyed by the destination's account id, loaded into memory at login, and strictly
|
|
additive** (`INSERT IGNORE` only, no `DELETE` anywhere in the code). Union semantics are correct and safe. They are
|
|
small (hundreds to low thousands of ids), not tens of thousands.
|
|
7. **The Manager has no database driver.** Every query is a string passed to the bundled `mysql` command-line client
|
|
(also inside a Docker container for Docker installs). That is acceptable for Manager-authored queries but unsafe for
|
|
importing data that came from another user's Manager (SQL injection through names, settings, text). Phases 3 and
|
|
15 should use a real driver with prepared statements.
|
|
|
|
Things that came out **better** than feared:
|
|
|
|
* One snapshot is small: a real level-80 character has about 1,300 spells, 105 reputations, 23 skills and at most ~40
|
|
inventory rows. Raw data is tens of KB; compressed, a few KB. A 60-second checkpoint is cheap.
|
|
* The database engine is InnoDB for every relevant table (3 MyISAM tables are bot name lists), so multi-table
|
|
transactions work. There are only 4 foreign keys, none involving characters or items, and no triggers or stored
|
|
procedures, so import order is not constrained by the schema.
|
|
* Item state is compact and fully contained in `item_instance` (no hidden per-item side tables except gifts, refund
|
|
and BoP-trade windows).
|
|
|
|
---------------------------------------------------------------------------------------------------------
|
|
|
|
## 2. Rulesets and class model (fact)
|
|
|
|
* Real data: classes **12-32** (21 classes, none of the stock 1-11), races 1-8, 10, 11 (no 9). Class and race ids are
|
|
therefore *CoA-specific numbers* and must be stored under a namespace, not as bare "WoW class ids"
|
|
(`coa:class:12` rather than `class=12`).
|
|
* The Manager already has two **realm profiles** (`crates/coa-core/src/realms.rs:15-40`): `Coa` (realm id 1, schemas
|
|
`acore_characters` / `acore_world`) and `Wildcard` (realm id 2, `acore_characters_wildcard` /
|
|
`acore_world_wildcard`), sharing one `acore_auth`. Wildcard has its own rules (skill cards, `core.wildcard.*`
|
|
settings, account-bound season state). **A portable character must carry its `ruleset`**, and CoA <-> Wildcard
|
|
transfer should be refused unless the owner decides otherwise (decision D5).
|
|
* Content is global within a ruleset: item ids such as 2977351 (welcome warchest) and spell ids >= 500000 are the same
|
|
on every CoA realm that uses the same content pack. That is what makes numeric ids meaningful *inside* a ruleset;
|
|
across rulesets or modded realms they are not (hence the namespacing rule in the task).
|
|
|
|
---------------------------------------------------------------------------------------------------------
|
|
|
|
## 3. Real tables (fact)
|
|
|
|
`acore_characters` has **163 tables**. Every one is classified below; the classification is the first draft of the
|
|
exporter's *table registry* (see risk R5: a test must fail when a new per-character table appears that is in no
|
|
class). Columns are shown as they exist in the schema fixture. There are no foreign keys between these tables
|
|
(only `highrisk_chest_item -> highrisk_chest` and three `mail_server_*` links), so relationships below are
|
|
**logical** and enforced only by the server code.
|
|
|
|
### A. Portable character state (v1 scope) (22 tables)
|
|
|
|
| Table | Role | Columns |
|
|
|---|---|---|
|
|
| `character_account_data` | per-character client blobs: macros (type 5) only in v1 | guid,type,time,data |
|
|
| `character_action` | active action bar rows | guid,spec,button,action,type |
|
|
| `character_appearance` | CoA wardrobe: equipped appearance per category; v1.1 | guid,category_id,appearance_id |
|
|
| `character_appearance_outfit` | CoA wardrobe outfits; v1.1 | guid,name,appearances |
|
|
| `character_appearance_settings` | CoA wardrobe visibility flags; v1.1 | guid,can_see_item,can_see_spell |
|
|
| `character_equipmentsets` | equipment-manager sets; item0..18 are item GUIDs, `setguid` is a global counter (remap); v1.1 | guid,setguid,setindex,name,iconname,ignore_mask,item0,item1,item2,item3,item4,item5,item6,item7,item8,item9,item10,item11,item12,item13,item14,item15,... |
|
|
| `character_gifts` | wrapped-gift content of an item; `item_guid` (remap) | guid,item_guid,entry,flags |
|
|
| `character_glyphs` | glyph slots | guid,talentGroup,glyph1,glyph2,glyph3,glyph4,glyph5,glyph6 |
|
|
| `character_inventory` | bag/slot placement; `item` is an item GUID (remap) | guid,bag,slot,item |
|
|
| `character_pet` | hunter/summon pets; `id` is a pet number (remap) | id,entry,owner,modelid,CreatedBySpell,PetType,level,exp,Reactstate,name,renamed,slot,curhealth,curmana,curhappiness,savetime,abdata |
|
|
| `character_pet_declinedname` | pet declined names; `id` is the pet number | id,owner,genitive,dative,accusative,instrumental,prepositional |
|
|
| `character_queststatus` | active quests + objective progress | guid,quest,status,explored,timer,mobcount1,mobcount2,mobcount3,mobcount4,itemcount1,itemcount2,itemcount3,itemcount4,itemcount5,itemcount6,playercount |
|
|
| `character_queststatus_rewarded` | completed quests | guid,quest,active |
|
|
| `character_reputation` | faction standing | guid,faction,standing,flags |
|
|
| `character_settings` | CoA gameplay state (`core.*` sources): active spec, build slots, spec bars, resets, starter flag | guid,source,data |
|
|
| `character_skills` | skill values | guid,skill,value,max |
|
|
| `character_spell` | known spells (CoA talents are spells) | guid,spell,specMask |
|
|
| `character_talent` | stock talents (empty on CoA, kept for stock/Wildcard compatibility) | guid,spell,specMask |
|
|
| `characters` | identity/progression/appearance columns only (see section 6); position, flags and cache columns are not carried | guid,account,name,race,class,gender,level,xp,money,skin,face,hairStyle,hairColor,facialStyle,bankSlots,restState,playerFlags,position_x,position_y,pos... |
|
|
| `item_instance` | item state; `guid` item GUID (remap), `owner_guid` player GUID (remap), `creatorGuid`/`giftCreatorGuid` foreign player GUIDs (zero) | guid,itemEntry,owner_guid,creatorGuid,giftCreatorGuid,count,duration,charges,flags,enchantments,randomPropertyId,durability,playedTime,text |
|
|
| `mod_craftsmans_codex` | extra profession slots (extension `mod:craftsmans-codex`) | guid,slots,first_used_at,last_used_at |
|
|
| `pet_spell` | pet spells; `guid` is the pet number (remap) | guid,spell,active |
|
|
|
|
### B. Portable collections (account-wide, union semantics) (6 tables)
|
|
|
|
| Table | Role | Columns |
|
|
|---|---|---|
|
|
| `account_appearance_collection` | CoA wardrobe unlocks, account-wide, INSERT IGNORE only (monotonic) | account_id,appearance_id,source_item |
|
|
| `account_vanity_collection` | CoA vanity unlocks, account-wide, INSERT IGNORE only (monotonic) | account_id,item_id |
|
|
| `coa_wildcard_skill_card` | Wildcard ruleset only: card collection + progress, account-bound | account,card,progress |
|
|
| `coa_wildcard_skill_card_account` | Wildcard ruleset only: bonus pack progress | account,bonus_progress |
|
|
| `coa_wildcard_skill_card_pending` | Wildcard ruleset only: unopened cards | account,id,card |
|
|
| `coa_wildcard_skill_card_purchase` | Wildcard ruleset only: purchase counters (price escalation) | account,type,count |
|
|
|
|
### C. Account-level / realm-account state (not portable in v1) (10 tables)
|
|
|
|
| Table | Role | Columns |
|
|
|---|---|---|
|
|
| `account_ascension_settings` | character-screen sort order | account_id,sort_order |
|
|
| `account_data` | client account-wide blobs | accountId,type,time,data |
|
|
| `account_instance_times` | instance entry throttle | accountId,instanceId,releaseTime |
|
|
| `account_tutorial` | tutorial flags | accountId,tut0,tut1,tut2,tut3,tut4,tut5,tut6,tut7 |
|
|
| `coa_account_warchest` | one-time welcome mail marker (per realm account) | account,claimed_at |
|
|
| `coa_wildcard_specialization_cache` | one-time claim marker (per realm account) | account,claimed_at |
|
|
| `mod_ascension_bank_item` | personal bank / realm bank items (item GUIDs) | owner_kind,owner_id,tab_index,slot,item_guid |
|
|
| `mod_ascension_bank_log` | bank event log | log_id,owner_kind,owner_id,tab_index,event_type,player_guid,item_or_money,stack_count,dest_tab,timestamp |
|
|
| `mod_ascension_bank_money` | personal bank / realm bank money | owner_kind,owner_id,money |
|
|
| `mod_ascension_bank_tab` | personal bank (owner_kind 0) / realm bank (owner_kind 1) tabs | owner_kind,owner_id,tab_index,name,icon,text |
|
|
|
|
### D. Per-character state deliberately not portable in v1 (59 tables)
|
|
|
|
| Table | Role | Columns |
|
|
|---|---|---|
|
|
| `ascension_manastorm_bonus` | Manastorm run state (D6) | guid,mode,pity,caches |
|
|
| `ascension_manastorm_cache` | Manastorm caches; `item` is an item GUID (D6) | item,guid |
|
|
| `ascension_manastorm_clear` | Manastorm clears (D6) | guid,mode,depth,scene,mail_id,completed_at |
|
|
| `ascension_manastorm_loadout` | Manastorm loadout (D6) | guid,slot,spell |
|
|
| `ascension_manastorm_xp` | Manastorm xp (D6) | guid,amount |
|
|
| `ascension_player_ticket` | GM tickets | id,account,creator_guid,creator,title,category,priority,affected_character,status,assigned_to,closed_by_creator,created,closed,locale |
|
|
| `ascension_player_ticket_message` | GM tickets | ticket,id,from_gm,gm_only,sender,message,created,read_by,read_at |
|
|
| `character_achievement` | achievements (out of scope for v1) | guid,achievement,date |
|
|
| `character_achievement_offline_updates` | queued achievement updates | guid,update_type,arg1,arg2,arg3 |
|
|
| `character_achievement_progress` | achievement criteria (out of scope for v1) | guid,criteria,counter,date |
|
|
| `character_arena_stats` | arena MMR (explicit non-goal) | guid,slot,matchMakerRating,maxMMR |
|
|
| `character_ascension_state` | character-screen active/inactive flag (realm-local) | guid,active |
|
|
| `character_aura` | temporary auras (explicit non-goal) | guid,casterGuid,itemGuid,spell,effectMask,recalculateMask,stackCount,amount0,amount1,amount2,base_amount0,base_amount1,base_amount2,maxDuration,remain... |
|
|
| `character_banned` | bans (explicit non-goal) | guid,bandate,unbandate,bannedby,banreason,active |
|
|
| `character_battleground_random` | random-BG daily flag | guid |
|
|
| `character_brew_of_the_month` | event marker | guid,lastEventId |
|
|
| `character_coa_lfg_settings` | LFG preference (realm-local) | guid,composition_mode,challenge_size |
|
|
| `character_declinedname` | name declensions (ruRU only) | guid,genitive,dative,accusative,instrumental,prepositional |
|
|
| `character_entry_point` | battleground/transport return point | guid,joinX,joinY,joinZ,joinO,joinMapId,taxiPath0,taxiPath1,mountSpell |
|
|
| `character_homebind` | regenerated at the destination (hearthstone) | guid,mapId,zoneId,posX,posY,posZ |
|
|
| `character_instance` | instance locks (explicit non-goal) | guid,instance,permanent,extended |
|
|
| `character_queststatus_daily` | realm-clock reset state | guid,quest,time |
|
|
| `character_queststatus_monthly` | realm-clock reset state | guid,quest |
|
|
| `character_queststatus_seasonal` | realm event state | guid,quest,event |
|
|
| `character_queststatus_weekly` | realm-clock reset state | guid,quest |
|
|
| `character_social` | friends/ignore (explicit non-goal) | guid,friend,flags,note |
|
|
| `character_spell_cooldown` | cooldowns (explicit non-goal) | guid,spell,category,item,time,needSend |
|
|
| `character_stats` | derived cache, rewritten on save | guid,maxhealth,maxpower1,maxpower2,maxpower3,maxpower4,maxpower5,maxpower6,maxpower7,strength,agility,stamina,intellect,spirit,armor,resHoly,resFire,r... |
|
|
| `character_worldforged_loot` | world pickup ledger (realm-local) | guid,spawn_id,entry,looted_at |
|
|
| `coa_bot_gear_history` | bots only | guid,slot,item_guid,entry,replaced_at |
|
|
| `coa_bot_gear_queue` | bots only | guid |
|
|
| `coa_challenge_completion` | challenge history (D6) | guid,challengeId,level,completeTime,startTime |
|
|
| `coa_challenge_failure` | challenge history (D6) | guid,challengeId,level,deaths,failTime |
|
|
| `coa_character_challenge` | challenge/hardcore state (ruleset-local, decision D6) | guid,challengeId,level,deaths,hunger,thirst,startTime |
|
|
| `coa_character_condition` | challenge flags (D6) | guid,flag |
|
|
| `coa_character_fatigue` | fatigue (D6) | guid,challengeId,fatigue |
|
|
| `coa_character_gamemode` | game-mode flag (D6) | guid,gameMode |
|
|
| `coa_character_gamemode_lives` | game-mode deaths (D6) | guid,gameMode,deaths |
|
|
| `coa_character_looted_item` | challenge loot ledger (D6) | guid,itemGuid |
|
|
| `coa_character_objective` | challenge objectives (D6) | guid,challengeId,objective |
|
|
| `coa_character_survival` | survival needs (D6) | guid,hunger,thirst |
|
|
| `coa_custom_trial` | custom trials authored by the character (D6) | guid,trialId,title,about,icon,author |
|
|
| `coa_custom_trial_active` | (D6) | guid,trialId,startTime |
|
|
| `coa_custom_trial_completion` | (D6) | guid,trialId,startTime,completeTime |
|
|
| `coa_custom_trial_entry` | (D6) | guid,trialId,challengeId,level,description |
|
|
| `coa_custom_trial_vote` | (D6) | guid,trialId,upvote,downvote |
|
|
| `corpse` | corpse state (explicit non-goal) | guid,posX,posY,posZ,orientation,mapId,phaseMask,displayId,itemCache,bytes1,bytes2,guildId,flags,dynFlags,time,corpseType,instanceId |
|
|
| `highrisk_chest` | High-Risk death-chest escrow (realm-local) | id,owner,map,phase,x,y,z,o,gold,original_gold,gold_claimant,created,gold_claimed_at |
|
|
| `highrisk_chest_item` | High-Risk escrow items, item GUIDs (realm-local) | chest_id,slot,item_guid,entry,count,claimant,claimed_at,active_item_guid |
|
|
| `item_loot_storage` | loot container contents (item GUID) | containerGUID,itemid,count,item_index,randomPropertyId,randomSuffix,follow_loot_rules,freeforall,is_blocked,is_counted,is_underthreshold,needs_quest,c... |
|
|
| `item_refund_instance` | refund window of an item (item GUID) | item_guid,player_guid,paidMoney,paidExtendedCost |
|
|
| `item_soulbound_trade_data` | BoP trade window of an item (item GUID) | itemGuid,allowedPlayers |
|
|
| `lfg_data` | LFG state | guid,dungeon,state |
|
|
| `mod_coa_bot_guild_gather_orders` | bots only | bot_guid,item_entry,target_count,gathered_count,remaining_count,target_map,target_x,target_y,target_z,has_target_location |
|
|
| `pet_aura` | temporary auras | guid,casterGuid,spell,effectMask,recalculateMask,stackCount,amount0,amount1,amount2,base_amount0,base_amount1,base_amount2,maxDuration,remainTime,rema... |
|
|
| `pet_spell_cooldown` | cooldowns | guid,spell,category,time |
|
|
| `player_anticheat_alert` | anticheat log | id,date,account,guid,name,reason,details,size |
|
|
| `quest_tracker` | quest analytics | id,character_guid,quest_accept_time,quest_complete_time,quest_abandon_time,completed_by_gm,core_hash,core_revision |
|
|
| `recovery_item` | item-recovery module (realm-local) | Id,Guid,ItemEntry,Count,DeleteDate |
|
|
|
|
### E. Realm operations (never portable) (66 tables)
|
|
|
|
`active_arena_season`, `addons`, `arena_team`, `arena_team_member`, `auctionhouse`, `banned_addons`, `battleground_deserters`, `bugreport`, `calendar_events`, `calendar_invites`, `channels`, `channels_bans`, `channels_rights`, `chat_filter`, `coa_keepers_scroll_blessing`, `coa_squid_migrations`, `creature_respawn`, `ethereal_bazaar_meta`, `ethereal_bazaar_stock`, `game_event_condition_save`, `game_event_save`, `gameobject_respawn`, `gm_subsurvey`, `gm_survey`, `gm_ticket`, `group_member`, `groups`, `guild`, `guild_bank_eventlog`, `guild_bank_item`, `guild_bank_right`, `guild_bank_tab`, `guild_eventlog`, `guild_member`, `guild_member_withdraw`, `guild_rank`, `instance`, `instance_reset`, `instance_saved_go_state_data`, `lag_reports`, `log_arena_fights`, `log_arena_memberstats`, `log_encounter`, `log_money`, `mail`, `mail_items`, `mail_server_character`, `mail_server_template`, `mail_server_template_conditions`, `mail_server_template_items`, `petition`, `petition_sign`, `playerbots_arena_team_names`, `playerbots_guild_names`, `playerbots_names`, `pool_quest_save`, `profanity_name`, `pvpstats_battlegrounds`, `pvpstats_players`, `reserved_name`, `spam_reports`, `updates`, `updates_include`, `warden_action`, `world_state`, `worldstates`
|
|
|
|
### 3.1 Primary keys and logical relationships of the portable set
|
|
|
|
| Table | Primary key | Logical reference |
|
|
|---|---|---|
|
|
| `characters` | `guid` | `account` -> `acore_auth.account.id` |
|
|
| `character_inventory` | **`item`** (unique) and unique `(guid, bag, slot)` | `guid` -> character, `item` -> `item_instance.guid`, `bag` -> the bag's *item guid* (0 = on the character) |
|
|
| `item_instance` | `guid` | `owner_guid` -> character (0 for bank/escrow items), `creatorGuid`/`giftCreatorGuid` -> *other* characters |
|
|
| `character_spell` | `(guid, spell)` | `spell` -> DBC |
|
|
| `character_skills` | `(guid, skill)` | |
|
|
| `character_reputation` | `(guid, faction)` | |
|
|
| `character_queststatus` | `(guid, quest)` | `quest` -> `acore_world.quest_template` |
|
|
| `character_queststatus_rewarded` | `(guid, quest)` | |
|
|
| `character_action` | `(guid, spec, button)` | |
|
|
| `character_glyphs` | `(guid, talentGroup)` | |
|
|
| `character_pet` | `id` (global pet number) | `owner` -> character |
|
|
| `pet_spell` | `(guid, spell)` | `guid` -> `character_pet.id` |
|
|
| `character_pet_declinedname` | `id` | `id` -> `character_pet.id`, `owner` |
|
|
| `character_settings` | `(guid, source)` | `source` is a free-form string (see section 7) |
|
|
| `character_account_data` | `(guid, type)` | |
|
|
| `character_equipmentsets` | `setguid` (global 64-bit auto-increment) | `guid` -> character, `item0..18` -> `item_instance.guid` |
|
|
| `character_gifts` | item guid | `item_guid` -> `item_instance.guid` |
|
|
| `character_appearance` / `_outfit` / `_settings` | `(guid, category_id)` / `(guid, name)` / `guid` | CoA wardrobe, per character |
|
|
| `account_appearance_collection` | `(account_id, appearance_id)` | `source_item` = item entry that unlocked it |
|
|
| `account_vanity_collection` | `(account_id, item_id)` | |
|
|
|
|
---------------------------------------------------------------------------------------------------------
|
|
|
|
## 4. Identifier domains and what must be remapped (fact)
|
|
|
|
| Domain | Allocated by | Where it appears | Remap on import |
|
|
|---|---|---|---|
|
|
| **Character guid** (32-bit) | `ObjectMgr` generator, seeded `MAX(guid)+1` at startup (`ObjectMgr.cpp:7633-7636`) | every `guid` / `owner_guid` / `owner` column, `character_inventory.guid`, `mod_ascension_bank_item.owner_id`, ... | **yes**, one new value |
|
|
| **Item guid** (32-bit) | item generator, seeded `MAX(item_instance.guid)+1` (`ObjectMgr.cpp:7639`) | `item_instance.guid`, `character_inventory.item` **and** `.bag` (a bag is an item), `character_gifts.item_guid`, `character_equipmentsets.item0..18`, `character_aura.itemGuid`, `item_refund_instance`, `item_soulbound_trade_data`, `item_loot_storage.containerGUID`, `mod_ascension_bank_item.item_guid`, `highrisk_chest_item.item_guid`, `ascension_manastorm_cache.item`, `coa_character_looted_item.itemGuid`, `mail_items.item_guid`, `auctionhouse.itemguid`, `guild_bank_item.item_guid` | **yes**, a map old->new, applied to *both* `item` and `bag` |
|
|
| **Pet number** (32-bit) | `ObjectMgr::GeneratePetNumber`, seeded `MAX(character_pet.id)+1` (`ObjectMgr.cpp:8169-8214`) | `character_pet.id`, `pet_spell.guid`, `pet_aura.guid`, `pet_spell_cooldown.guid`, `character_pet_declinedname.id` | **yes** |
|
|
| **Equipment set guid** (64-bit) | `_equipmentSetGuid`, seeded `MAX(setguid)+1` (`ObjectMgr.cpp:7669`) | `character_equipmentsets.setguid` | yes (v1.1) |
|
|
| **Account id** | auth database | `characters.account`, every `account_*` / `coa_wildcard_*` collection table | **yes**, destination account (provisioned per realm) |
|
|
| Mail id, guild id, arena team id, group, instance id | server | mail, guild, ... | not carried |
|
|
| Foreign **player** guids inside portable rows | n/a | `item_instance.creatorGuid`, `giftCreatorGuid` (item crafted/gifted by *another* character), `character_aura.casterGuid` (auras are excluded anyway) | set to **0** (or to the new guid when it equals the character itself); the crafter's *name* may be kept as display text |
|
|
|
|
Observed facts that affect the remap design:
|
|
|
|
* `character_inventory` is keyed by **`item`**, so one item can be in exactly one place; a remap that changes both
|
|
`item` and `bag` consistently is required (a bag's contents point to the bag's item guid).
|
|
* Player guids **are reused**: the generator restarts from `MAX(guid)+1`, so deleting the newest character frees its
|
|
guid. `Player::DeleteFromDB` (`Player.cpp:4217`) deletes only stock tables; module tables are cleaned by
|
|
`OnPlayerDelete`/`OnPlayerDeleteFromDB` hooks, and the audit found only **two** such handlers
|
|
(`AscensionCompat.cpp:6650` for outfits, `AscensionManastorm.cpp:1859`). Rows of `character_appearance`,
|
|
`coa_character_*`, `character_worldforged_loot`, `mod_craftsmans_codex`, ... can therefore be **orphaned** and attach
|
|
to a later character that reuses the guid. The importer must therefore run a complete
|
|
`DELETE ... WHERE guid = <new guid>` over every per-character table (portable or not) before inserting, inside the
|
|
same transaction.
|
|
* Item guids of *other* tables (mail, auction, guild bank) are never moved, so remapping stays inside the portable set.
|
|
|
|
---------------------------------------------------------------------------------------------------------
|
|
|
|
## 5. Portable vs world-local (fact + proposal)
|
|
|
|
| | Portable (v1) | World-local (never carried) |
|
|
|---|---|---|
|
|
| Identity | name, race, class, gender, skin/face/hair/facial style, `playerFlags` subset | `account`, `guid`, creation date, `at_login`, ban/delete info |
|
|
| Progression | level, xp, money, `arenaPoints`, honor columns, `knownCurrencies`, titles (`knownTitles`, `chosenTitle`), explored zones, taxi mask | `online`, `totaltime`/`leveltime`, rest state, `logout_time` |
|
|
| Build | known spells, skills, glyphs, stock talents, `character_settings` `core.*` sources, `talentGroupsCount`/`activeTalentGroup`, `extraBonusTalentCount`, `resettalents_*` | cooldowns, auras |
|
|
| Inventory | all `character_inventory` rows (equipment 0-18, bags 19-22, backpack 23-38, **bank 39-66 and bank bags 67-73**, keyring 86-117, currency-token slots 118-149) with their `item_instance` rows | buyback slots 74-85 (not persisted), mail, auction, guild bank |
|
|
| Quests | active + objectives, completed | daily / weekly / monthly / seasonal (tied to the destination's clock), quest tracker |
|
|
| Gameplay | action bars (`character_action` + per-spec bars in settings), macros, equipment sets | friends, ignore, guild, group, instance/raid locks, battleground and arena state |
|
|
| Position | **nothing**; destination chooses | map, x/y/z, orientation, zone, transport, corpse, `death_expire_time`, homebind |
|
|
|
|
Positions: `Player::LoadFromDB` falls back to the race/class start location when the map or coordinates are invalid
|
|
(`PlayerStorage.cpp:5202`, `:5247`) and recreates `character_homebind` from `playercreateinfo` when the row is missing or
|
|
invalid (`PlayerStorage.cpp:7173-7222`). Both fall back to the class/race start **only if `playercreateinfo` has an
|
|
entry for that race/class pair** - an import must verify that, because otherwise the character cannot load. The
|
|
importer should write the destination's own start position (read from its world database) instead of relying on the
|
|
error path.
|
|
|
|
---------------------------------------------------------------------------------------------------------
|
|
|
|
## 6. `characters` column map (fact + proposal)
|
|
|
|
| Columns | Class | Notes |
|
|
|---|---|---|
|
|
| `guid`, `account` | remapped | destination values |
|
|
| `name` | identity | `varchar(25)`, collation **`utf8mb4_bin`** (case-sensitive; widened by `rev_1789996074311168500.sql`). Name uniqueness is enforced by the server through its name cache, not by a unique key |
|
|
| `race`, `class`, `gender`, `skin`, `face`, `hairStyle`, `hairColor`, `facialStyle` | identity | CoA class/race numbers; namespaced in the model |
|
|
| `level`, `xp` | progression | |
|
|
| `money` | progression | `int unsigned`; the server clamps to `MAX_MONEY_AMOUNT` = 2,147,483,646 copper (~214,748 gold) (`Player.h:926`, `PlayerStorage.cpp:5120`). Largest real value seen: 200,060,523 |
|
|
| `arenaPoints`, `totalHonorPoints`, `todayHonorPoints`, `yesterdayHonorPoints`, `totalKills`, `todayKills`, `yesterdayKills`, `knownCurrencies` | progression | `knownCurrencies` must be consistent with the currency-token items (see the Rune of Ascension migration comment: the Currency page stays blank if the bit is 0) |
|
|
| `chosenTitle`, `knownTitles` | progression | cheap to carry; achievements themselves stay out of v1 |
|
|
| `exploredZones`, `taximask`, `bankSlots`, `stable_slots`, `talentGroupsCount`, `activeTalentGroup`, `extraBonusTalentCount`, `resettalents_cost`, `resettalents_time`, `grantableLevels`, `watchedFaction`, `actionBars`, `ammoId`, `innTriggerId` | progression/build | `actionBars` is the "which bars are visible" bitmask; it is not the bars |
|
|
| `playerFlags`, `extra_flags` | partly | only the cosmetic flags (helm/cloak visibility); never GM/ghost/AFK bits |
|
|
| `position_*`, `map`, `instance_id`, `instance_mode_mask`, `orientation`, `zone`, `trans_*`, `transguid`, `taxi_path`, `death_expire_time` | world-local | rewritten |
|
|
| `health`, `power1..7`, `drunk`, `restState`, `rest_bonus`, `is_logout_resting`, `cinematic`, `totaltime`, `leveltime`, `logout_time`, `latency`, `online`, `at_login`, `equipmentCache`, `order`, `creation_date`, `deleteInfos_*`, `deleteDate` | world-local / derived | `equipmentCache` is rebuilt on every save; `at_login` must **not** contain `AT_LOGIN_FIRST` (0x20) or the first-login rewards run again |
|
|
|
|
---------------------------------------------------------------------------------------------------------
|
|
|
|
## 7. CoA-specific state (fact)
|
|
|
|
### 7.1 Talents, builds, spec bars live in `character_spell` + `character_settings`
|
|
|
|
* `character_settings` has primary key `(guid, source)`; `data` is a space-separated list of unsigned integers
|
|
(`PlayerSettingsStore::SerializeSettingsData`, `PlayerSettings.cpp`). Sources starting with **`core.` are mandatory
|
|
gameplay state** and are loaded even when optional player settings are disabled (`PlayerSettings.cpp:116-120`).
|
|
* Sources found in code (`grep` over `src/` and `modules/`):
|
|
|
|
| Source | Meaning |
|
|
|---|---|
|
|
| `core.ascension_active_spec` | active specialization id (61 call sites; present on 1857 of 1861 real characters) |
|
|
| `core.ascension_starter` / `core.ascension_starter_live` | starter kit already granted - **must travel**, or the starter items are granted again at the destination (duplication) |
|
|
| `core.ascension_slot.active`, `core.ascension_slot.<n>` | active build slot and per-slot data (`AscensionCompat.cpp:1970-1977`) |
|
|
| `core.ascension_build.<specId>` and `core.ascension_slot.<n>.build.<specId>` | stored talent picks: `[count, entryId*10+rank, ...]` (`AscensionCompat.cpp:1970-2060`) |
|
|
| `core.ascension_bar.<specId>` and `core.ascension_slot.<n>.bar.<specId>` | stored action bar per spec: `[count, button, spell, ...]` |
|
|
| `core.ascension_reset_credits` | ability/talent reset credits |
|
|
| `core.spell_charge.<spellId>` | spell charge state (one row per spell; 40+ distinct spells in real data) |
|
|
| `core.wildcard`, `core.wildcard.{cards,spec,path,bars,scrolls,scrolls.spec2,rewards,rerolls,repurchase,unlearned,startercards}` | Wildcard ruleset state |
|
|
| `core.destiny_weaver`, `core.dynamic_xp.preset`, `core.runemaster.echoes`, `core.coa_prestige`, `core.coa_prestige_bar`, `core.coa_glory`, `core.ascension.tutorial_*` | module / UI state |
|
|
| `coa.bot.gear`, `coa.bot_profile`, `coa.gear_pref_*`, `coa.gameplay_test`, `coa.highrisk` | bots, preferences, tests - not portable |
|
|
|
|
* **Proposal:** treat `character_settings` as a namespaced key -> integer-vector map (`coa:settings:<source>`),
|
|
exported by an **allowlist of source patterns** that lives in a versioned policy file inside the Manager. Sources not
|
|
on the allowlist are preserved in the canonical snapshot as opaque extension data and are not imported (the
|
|
quarantine behaviour demanded for modded content).
|
|
* Because a CoA "talent" is a spell, **stock `character_talent` can be empty and the build still be fully described**
|
|
by `character_spell` + the sources above. The audit found no other store.
|
|
|
|
### 7.2 Spells
|
|
|
|
`character_spell` holds the entire spellbook (avg ~1,284, max 1,568 rows for a level-80 character). `specMask`
|
|
distinguishes dual-spec ownership. Because spells are a set of ids from a ruleset-global DBC, they can be carried as a
|
|
sorted integer set (delta + varint) at a few KB per character.
|
|
|
|
### 7.3 Pets
|
|
|
|
`character_pet` stores **every** pet type, not only hunter pets: the real data has 5 rows, all `PetType = 0` (summon
|
|
pets of CoA's own classes), 0 hunter pets (CoA has no stock Hunter). `Pet::SavePetToDB` (`Pet.cpp:502`) writes the
|
|
current pet and stabled pets with `slot` (current / stable 1-4 / "not in slot"). Portable v1: all `character_pet` rows
|
|
for the character + `pet_spell` + `character_pet_declinedname`; **not** `pet_aura` and `pet_spell_cooldown`. The pet
|
|
number is remapped (section 4). `characters.stable_slots` must be carried or the stable looks empty.
|
|
|
|
### 7.4 Items
|
|
|
|
`item_instance` columns: `itemEntry, count, duration, charges (5 ints), flags, enchantments (36 ints = 12 slots x
|
|
[id, duration, charges]), randomPropertyId (negative = suffix), durability, playedTime, text, creatorGuid,
|
|
giftCreatorGuid`. Real data: all 46k rows have a 72-character enchantment string; 22 items have a random property.
|
|
Item `flags` bits that carry state: soulbound, refundable, BoP-tradeable, wrapped, ...
|
|
|
|
Special item-related state outside `item_instance`:
|
|
|
|
| State | Table | v1 |
|
|
|---|---|---|
|
|
| wrapped gift | `character_gifts` | carry (part of item) |
|
|
| refund window (2h) | `item_refund_instance` | drop; the server clears the flag itself after load |
|
|
| BoP trade window | `item_soulbound_trade_data` | drop; the server clears the flag |
|
|
| bag contents | `character_inventory.bag` | structural |
|
|
| personal bank | `mod_ascension_bank_*` `owner_kind = 0` (items stored as `item_instance` rows with **`owner_guid = 0`**) | **decision D3**: a character's personal bank is really inventory; excluded rows would be silently lost if the realm ever deleted the character |
|
|
| realm bank | `owner_kind = 1`, keyed by **account** | not portable (account/realm local) |
|
|
|
|
### 7.5 Account-wide collections
|
|
|
|
| Collection | Table | Key | Written by | Notes |
|
|
|---|---|---|---|---|
|
|
| Wardrobe appearances | `account_appearance_collection(account_id, appearance_id, source_item)` | account | `INSERT IGNORE` (`AscensionCompat.cpp:5018`) | monotonic |
|
|
| Vanity items | `account_vanity_collection(account_id, item_id)` | account | `INSERT IGNORE` (`:5038`, `:5053`) | monotonic. When config `UNLOCK_ALL_VANITY` is on, vanity is *not tracked at all* (the table stays empty) |
|
|
| Equipped appearance / outfits / visibility | `character_appearance`, `character_appearance_outfit`, `character_appearance_settings` | **character** | `REPLACE` / `DELETE` of that character's rows | per character, small |
|
|
| Wildcard skill cards | `coa_wildcard_skill_card*` (4 tables) | account | Wildcard module | season-bound, Wildcard ruleset only |
|
|
|
|
Facts for Phase 6:
|
|
|
|
* **No code path deletes from the two account collections** (`grep` for `DELETE` on them: none). Union semantics are
|
|
safe and match reality.
|
|
* They are **loaded once at login** into `PlayerCollectionState` (`AscensionCompat.cpp:4912-4965`). New unlocks written
|
|
to the database while a character is online are invisible to that session. The Manager must therefore write
|
|
collections only for a character that is not logged in (before join / after the final sync).
|
|
* Real size: the fixture's wardrobe has 387 rows for the whole realm. Even a generous estimate for a full collector is a
|
|
few thousand ids; a sorted, delta + varint encoded `u32` set is ~1-2 bytes per id. The 10k / 50k test sizes in the
|
|
task are good stress tests but not realistic production sizes.
|
|
* Collections are keyed by the **destination** account id, so a `PortableProfile` -> realm-account mapping is part of
|
|
account provisioning (Phase 12).
|
|
|
|
### 7.6 Ruleset-local progression that is **not** portable in v1 (decision D6)
|
|
|
|
Challenge / hardcore state (`coa_character_*`, `coa_challenge_*`, `coa_custom_trial*`), Manastorm run state
|
|
(`ascension_manastorm_*`), High-Risk chests, world-pickup ledger. Moving a character with an active challenge or
|
|
game-mode flag would silently turn a hardcore character into a normal one. Proposal: **refuse "Make Portable"** (or
|
|
warn) for characters that have rows in the challenge/game-mode tables.
|
|
|
|
---------------------------------------------------------------------------------------------------------
|
|
|
|
## 8. What the server does when it loads and saves a character (fact)
|
|
|
|
### 8.1 Load (`PlayerStorage.cpp:5022` `LoadFromDB`, query list `CharacterHandler.cpp:72`)
|
|
|
|
The login holder runs ~30 queries by guid (spells, quests, inventory, actions, reputation, skills, glyphs, talents,
|
|
account data, settings, ...). Validation done at load:
|
|
|
|
* `characters.account` must equal the logged-in account, else the load fails (`:5050`). **Importing needs the
|
|
destination account id in `characters.account`.**
|
|
* Name is re-validated (`CheckPlayerName`); an invalid or reserved name sets `AT_LOGIN_RENAME` and fails the load.
|
|
* Race/class pair must have a `playercreateinfo` row.
|
|
* Money is clamped; titles/explored zones loaded as raw blobs.
|
|
* Banned characters (`character_banned`) cannot load.
|
|
|
|
### 8.2 Save (`PlayerStorage.cpp:7244` `SaveToDB`)
|
|
|
|
One transaction per save: character row, entry point, inventory (**only changed items**), quests, talents, spells,
|
|
cooldowns, actions, auras, skills, achievements, reputation, equipment sets, glyphs, settings, stats, current pet.
|
|
Save triggers: autosave interval, logout, and explicit calls. Everything is `InnoDB`, so one realm save is atomic.
|
|
|
|
### 8.3 Item load is destructive (`PlayerStorage.cpp:6104` `_LoadItem`, `:5972` `_LoadInventory`)
|
|
|
|
| Condition at load | What the server does |
|
|
|---|---|
|
|
| `itemEntry` not in `item_template` | **deletes** the item from `character_inventory` and `item_instance` |
|
|
| `Item::LoadFromDB` fails | deletes it |
|
|
| limited to another map/zone | deletes it |
|
|
| `ITEM_FLAG_CONJURED` and logged out > 15 min | deletes it |
|
|
| holiday item outside its event | deletes it |
|
|
| cannot be placed/equipped (`CanStoreItem` / `CanEquipItem` fails, e.g. level requirement, missing bag) | **removes it from the inventory table and mails it** to the character |
|
|
| refundable without `item_refund_instance` row / BoP-tradeable without trade row | clears the flag |
|
|
|
|
### 8.4 Consequence: export is a *view*, not the truth (proposal)
|
|
|
|
Because of 8.3 a realm may legitimately return fewer items than it was given. Therefore:
|
|
|
|
* Every portable item carries a stable **portable item id** (UUIDv7) in the model. The per-realm mapping
|
|
`portable item id <-> local item guid` is stored in the Manager (extension of `CharacterServerMapping`).
|
|
* `Export` at checkpoint/final sync is diffed against the **base snapshot** that was imported at join (`revision_at_join`).
|
|
An item that was in the base, is missing from the export, and is *known to have been filtered* (unknown entry at
|
|
destination, or found in mail at the destination) stays in the canonical snapshot as **quarantined**; an item that is
|
|
missing without such an explanation is treated as deleted by the player (vendored/destroyed).
|
|
* This is the same mechanism that Phase 7 (mod extensions) and Phase 8 (cap projection) need, so it should be in the
|
|
data model from Phase 1 even though the diff logic comes later.
|
|
|
|
---------------------------------------------------------------------------------------------------------
|
|
|
|
## 9. Transactions and atomicity (fact + proposal)
|
|
|
|
* All relevant tables are InnoDB: one `START TRANSACTION ... COMMIT` can cover the whole import (character, items,
|
|
pets, settings, spells, quests, ...). On failure, the connection closing (or `ROLLBACK`) removes everything: **no
|
|
half-imported character is possible if the import is a single transaction**.
|
|
* The core's `PlayerDumpReader::LoadDump` (`PlayerDump.cpp:764-968`) is the existing reference: it builds one
|
|
`CharacterDatabaseTransaction`, remaps items/pets/mails/equipment sets from the live generators, commits, then
|
|
refreshes the name cache and advances the in-memory counters (`sCharacterCache->AddCharacterCacheEntry`,
|
|
`GetGenerator<HighGuid::Item>().Set(...)`, `_hiPetNumber`, ...). It also sets a temporary name and `AT_LOGIN_RENAME` on
|
|
a name clash and caps accounts at 10 characters.
|
|
* Which operations can be transactional **from outside** (Manager -> MySQL): all inserts and the guid
|
|
allocation *if the server is not running*. With the server running they can be transactional in MySQL but are not
|
|
coherent with the server's memory (section 10).
|
|
* Restoring a database requires the game servers to be stopped; the Manager already enforces this (`backup.rs` header),
|
|
which is a useful precedent for "destructive replacement of a character requires the character, or the whole server,
|
|
to be offline".
|
|
|
|
---------------------------------------------------------------------------------------------------------
|
|
|
|
## 10. Running realm vs. external writes (fact -> decision D1)
|
|
|
|
Facts:
|
|
|
|
1. Id counters are in memory, seeded once from `MAX(...)` at startup (`ObjectMgr.cpp:7633-7681`, `:8169`).
|
|
2. `CharacterCache` (name -> guid -> account/race/class/level) is filled once at startup
|
|
(`CharacterCache.cpp:63`). `RefreshCacheEntry` exists and is reachable from the console as `.cache refresh`
|
|
(`cs_cache.cpp:38`, `Console::Yes`); whether that command can address a guid the cache does not know yet (it takes a
|
|
`PlayerIdentifier`) must be verified before relying on it.
|
|
3. `World::UpdateRealmCharCount` refreshes `acore_auth.realmcharacters`; a direct insert leaves the character count of
|
|
the account wrong.
|
|
4. Collections are cached per login; `Player` state is only written back by the Player object (an online character's
|
|
next save overwrites anything written to its rows underneath it).
|
|
5. `Player::SaveToDB` is not called every 60 s (autosave interval, default 15 minutes in stock AzerothCore; the real
|
|
value is in the realm's `worldserver.conf`; the core default is `PlayerSaveInterval = 900000` ms, `WorldConfig.cpp:223`).
|
|
`.save` (`cs_misc.cpp:122`) is `Console::No`; `.saveall` (`cs_misc.cpp:123`) is `Console::Yes` but calls
|
|
`SaveToDB` for **every** online player, bots included, in one pass (`ObjectAccessor.cpp:286-293`), which is not a
|
|
per-character checkpoint and gets expensive on a realm with many bots.
|
|
6. The Manager's RA client exposes **a fixed set of typed operations** only (`ra.rs:1-2`, `:68-166`); adding an
|
|
operation is a deliberate code change.
|
|
|
|
Options:
|
|
|
|
| | A. Offline-only import | B. Reserved id range + external writes | C. In-core importer |
|
|
|---|---|---|---|
|
|
| How | server stopped (or realm DB offline) when importing; Manager allocates `MAX+1..` itself | Manager allocates ids from a high reserved range (e.g. >= 2^31) so it can never collide with the live counters; name cache refreshed by restart or a new command | new core console command(s) that take a Manager-produced portable payload and do remap/insert/commit/cache-refresh inside the server (extend the `.pdump` machinery) |
|
|
| Core change | none | optional small command to refresh cache | new commands + the CoA tables in the dump list |
|
|
| Works for a *public host with players online* | **no** | partly (character invisible to name lookups until refresh; realm char count stale) | **yes** |
|
|
| Works for the Phase 3 vertical slice on two disposable DBs | **yes** | yes | yes |
|
|
| Risk | lowest | id space gets sparse; subtle cache gaps | largest, but the *safest at runtime* |
|
|
|
|
**Recommendation:** do Phase 3 and Phase 4 with **A** (it is enough to prove the model and is fully testable on
|
|
disposable databases), and decide **C** for production hosting in parallel as a core-side workstream. B is a stopgap and
|
|
is not recommended. For C and for the 60-second checkpoints the core needs (all small, console-only, RA-callable):
|
|
|
|
1. `.character save <name>` - persist one online character now (checkpoint without `.saveall`).
|
|
2. `.portable import ...` / `.portable export ...` - or CoA-aware extension of `.pdump` - doing remap + commit + cache
|
|
refresh in the server.
|
|
3. If B is ever used: confirm that the existing `.cache refresh` can address a not-yet-cached guid, otherwise add the
|
|
guid variant plus a `UpdateRealmCharCount` call.
|
|
|
|
Whatever option is chosen, **an import must refuse a character that is online**, check `characters.online`, and verify
|
|
`acore_auth.account.online` for the target account.
|
|
|
|
---------------------------------------------------------------------------------------------------------
|
|
|
|
## 11. Account and authentication side (fact)
|
|
|
|
* `acore_auth.account` (`salt`, `verifier`, ...) is created through the world console (`ra.rs:80 create_account`, the
|
|
typed RA operations), because the SRP6 verifier depends on the username. The Manager also contains `srp6.rs`.
|
|
* Bot accounts (`COABOTHOST*`) and the Manager's own `COAMANAGER` are filtered out of account listings
|
|
(`accounts.rs:22-28`); the export must apply the same filter so that bots are never offered for "Make Portable".
|
|
* `acore_auth.realmcharacters(realmid, acctid, numchars)` must be kept correct after an import
|
|
(`World::UpdateRealmCharCount` at `World.cpp:1660`).
|
|
* The Manager can already discover a realm's databases, ports and credentials for both bundled-MySQL and Docker
|
|
installations (`db.rs:68-120`), including the Wildcard schema routing.
|
|
|
|
---------------------------------------------------------------------------------------------------------
|
|
|
|
## 12. Level cap and content scaling (fact, input for Phase 8)
|
|
|
|
* The realm's level cap is `CONFIG_MAX_PLAYER_LEVEL` (`MaxPlayerLevel`); content scaling computes a progression layout
|
|
from it once at startup and requires a restart when it changes
|
|
(`docs/coa-content-scaling-architecture.md` section 3.1).
|
|
* No clamp of a loaded character's level to the cap was found in `LoadFromDB`; the cap only stops XP gain/level-up
|
|
(`Player.cpp:2519`, `:2735`, `:6097`, `:10723`; `PlayerQuest.cpp:808`). A level-80 character on a cap-60 realm would
|
|
currently load *as level 80*.
|
|
* Per-viewer scaling (`mod-destiny-weaver`, `LocalLevelScaling`) already scales the **world around** a character and
|
|
never lowers the character (`docs/coa/level-scaling.md`). So a projection that *lowers the character* is new
|
|
behaviour, and it interacts with 8.3: gear above the projected level would be mailed away. Phase 8 therefore needs
|
|
an item-equip/level-requirement override for projected sessions, not just a snapshot transformation.
|
|
|
|
---------------------------------------------------------------------------------------------------------
|
|
|
|
## 13. Exact integration points
|
|
|
|
### 13.1 Manager (`origin/master` `cd3a963`)
|
|
|
|
| Concern | File | Notes |
|
|
|---|---|---|
|
|
| Manager-wide state directory | `src-tauri/src/lib.rs:74` `data_dir()` = `%LOCALAPPDATA%\CoAServerManager`; `:947` `remote_dir()` | new `portable\` folder goes here; **not** inside an install's `.manager` folder, because a portable character must exist without any install |
|
|
| Atomic file helpers | `crates/coa-core/src/fsx.rs:83,145,151` (`safe_join`, `atomic_write_json`, `read_json`) | reuse for non-DB files |
|
|
| Database access | `crates/coa-core/src/db.rs` (`Db::from_repack`, `Account::{Admin,App}`, `query`, `run_sql_file`, Docker via `docker exec`) | CLI only; see risk R4 |
|
|
| Realm schemas / modes | `crates/coa-core/src/realms.rs:15-40`, `db.rs:79-92` (`schema_of`), `Db::realm_schema` | CoA vs Wildcard routing |
|
|
| Account operations | `crates/coa-core/src/accounts.rs`, `ra.rs` (`create_account`, `set_account_password`, ...), `srp6.rs` | Phase 12 |
|
|
| World console | `crates/coa-core/src/ra.rs` | typed ops only; new ops (`save character`, ...) are added here |
|
|
| Process state | `process.rs`, `driver.rs`, `layout.rs` | "is the realm stopped?" for offline import |
|
|
| Recovery points | `backup.rs` (`create`, `restore_database`, `with_database`) | backup-before-destructive-replacement for Phase 4 reuses this; it already refuses to restore while servers run |
|
|
| Schema contract | `schema_check.rs`, `Scripts/database-schema.json`, `character-save-columns.json` | the compatibility fingerprint ("destination characters schema matches contract") |
|
|
| Migrations ledger | `migrations.rs` (`coa_manager_migrations` in `acore_world`) | the Manager changes realm databases only through this; **the portable store is a separate local database and must not add tables to realm databases** |
|
|
| Networking (Phase 13/14) | `net.rs` (public IP, CGNAT detection), `upnp.rs`, `firewall.rs`, `friends.rs`, `realmlist.rs` | `friends.rs` already advertises the realm address and builds a friend package |
|
|
| Player Mode shell | `src/App.tsx` (`view === "remote"`), `src/screens/RemoteClient.tsx`, `crates/coa-core/src/remote_client.rs`, `src-tauri/src/lib.rs:947-1003` | a "no server" mode already exists (host + client path) and is the natural home for My Characters |
|
|
| Frontend API layer | `src/lib/api.ts`, Tauri `invoke_handler` at `lib.rs:1523` (83 commands) | add one `portable_*` command group, not one command per UI action |
|
|
| i18n | `src/i18n/locales/*.ts`, `tools/check-i18n.mjs` (CI step) | every new string needs a key in en + 4 drafts |
|
|
| CI | `.github/workflows/check.yml`: Windows + Ubuntu, `npm ci`, `check-i18n`, `npm run build` (`tsc`), `cargo test --workspace --locked` | any new crate must build on **both** OSes |
|
|
| Crates available | `uuid` (feature `v4` only - needs `v7`), `sha2`, `zstd`, `serde_json`, `chrono`, `tempfile`; **no** SQLite, MySQL driver, KDF or bitmap crate | |
|
|
|
|
### 13.2 Core (`641251c4f`)
|
|
|
|
| Concern | Location |
|
|
|---|---|
|
|
| Per-character save | `Player::SaveToDB` `PlayerStorage.cpp:7244`; `_SaveCharacter` `Player.cpp:15547`; `_SaveInventory` `PlayerStorage.cpp:7445`; pet `Pet.cpp:502` |
|
|
| Per-character load | `Player::LoadFromDB` `PlayerStorage.cpp:5022`; query holder `CharacterHandler.cpp:72`; `_LoadInventory` `:5972`; `_LoadItem` `:6104`; `Item::LoadFromDB` `Item.cpp:420`; `_LoadHomeBind` `PlayerStorage.cpp:7173`; `_LoadPetStable` `Player.cpp:16741` |
|
|
| Character deletion | `Player::DeleteFromDB` `Player.cpp:4217`; module hooks `OnPlayerDelete` (`PlayerScript.cpp:287`) and `OnPlayerDeleteFromDB` |
|
|
| Id allocation | `ObjectMgr::SetHighestGuids` `ObjectMgr.cpp:7633`; pet number `:8169`, `:8213`; generator `ObjectGuid.h:284-317` |
|
|
| Name cache | `CharacterCache.cpp:63` (load), `:88` (`RefreshCacheEntry`) |
|
|
| Existing live-safe import/export | `PlayerDump.cpp:764` (`LoadDump`), table list `:85-118`; commands `cs_character.cpp:43-47` (`pdump load/write/copy`, all `Console::Yes`) |
|
|
| CoA settings store | `PlayerSettings.cpp:110-185`; keys in `AscensionCompat.cpp:333-335, 1970-2040` |
|
|
| CoA collections | `AscensionCompat.cpp:4912` (load), `:5018`, `:5038` (writes) |
|
|
| Commands to extend | `cs_misc.cpp:122-124` (`save`, `saveall`, `kick`), `cs_character.cpp` |
|
|
|
|
---------------------------------------------------------------------------------------------------------
|
|
|
|
## 14. Risks
|
|
|
|
| # | Risk | Severity | Where it bites | Mitigation |
|
|
|---|---|---|---|---|
|
|
| R1 | External writes into a running realm collide with in-memory counters / stale name cache | High | Phase 3-5 | Option A for Phases 3-4; decision D1 for production; import refuses online characters |
|
|
| R2 | Server load-time deletes/mails items; "replace canonical with export" loses them | High | Phase 4, 5, 8 | item identity ids + base-snapshot diff + quarantine (8.4) designed in from Phase 1 |
|
|
| R3 | Database is stale between saves; 60 s checkpoint impossible without a per-character save | High | Phase 5 | core command `.character save` (D1/D13) |
|
|
| R4 | Untrusted snapshot strings reach SQL through the CLI client | High | Phase 3 import, 15 | prepared statements via a driver crate (D9); validate sizes/charset first; never build SQL from snapshot text |
|
|
| R5 | Per-character state outside stock tables is missed (silent half-export) | High | Phase 2 | the classification above becomes a **registry test**: the test loads the schema contract and fails if a table with a `guid`-like column is in no class; fixture tests export a CoA character with a build and compare |
|
|
| R6 | Orphan rows + guid reuse attach old data to a new character | Medium | Phase 3, 4 | delete across **all** per-character tables for the target guid inside the import transaction |
|
|
| R7 | Collections keyed by destination account id and cached at login | Medium | Phase 6, 12 | write only while the character is offline; profile -> account mapping per realm |
|
|
| R8 | Destination lacks items/spells/quests the character has | Medium | Phase 3, 11 | pre-flight: `item_template`/`quest_template` entries via the destination world DB, schema-contract check, namespaced ids; quarantine rather than import |
|
|
| R9 | CoA vs Wildcard (and Docker installs, secondary world) take different schemas/ports | Medium | all | the portable layer takes a `RealmTarget {ruleset, schema names, Db}` from existing `realms.rs`/`db.rs`; never hardcodes `acore_characters` |
|
|
| R10 | Name clash / reserved name / `utf8mb4_bin` case sensitivity | Low | Phase 3 | follow `PlayerDump`: temporary name + `AT_LOGIN_RENAME`; compare case-insensitively |
|
|
| R11 | One-time rewards re-granted (`AT_LOGIN_FIRST`, starter kit, warchest) | Medium | Phase 3 | `at_login = 0`, carry `core.ascension_starter`; account-level claim tables are per realm and not carried |
|
|
| R12 | Core version drift between realms (3 revisions in use) | Medium | Phase 11 | compatibility keyed by schema contract + `format_version`, shown before JOIN |
|
|
| R13 | `money`/currency overflow, absurd payloads | Low | Phase 15 | caps from the server code (money <= 2,147,483,646), size limits per field and per snapshot |
|
|
|
|
---------------------------------------------------------------------------------------------------------
|
|
|
|
## 15. Decisions needed
|
|
|
|
| # | Decision | Recommendation | Needed before |
|
|
|---|---|---|---|
|
|
| **D1** | How a *running public host* receives a character | Phase 3-4 offline (A); plan the in-core command set (C) as a core workstream | Phase 3 starts for production use; not for the disposable-DB slice |
|
|
| **D2** | `character_settings` scope | allowlist of `core.*` patterns (versioned policy), the rest opaque/quarantined | Phase 2 |
|
|
| **D3** | Personal bank (`mod_ascension_bank_*`, `owner_kind 0`) | include as extension `mod:ascension-bank` in v1.1; realm bank excluded | Phase 2 |
|
|
| **D4** | Equipment sets and per-character wardrobe (`character_appearance*`) | v1.1, after the core slice works | Phase 2 |
|
|
| **D5** | CoA <-> Wildcard transfer | refuse (different rulesets) | Phase 1 (field in model) |
|
|
| **D6** | Challenge / hardcore / Manastorm state | not portable in v1; refuse or warn on "Make Portable" | Phase 2 |
|
|
| **D7** | Achievements, titles | titles columns in v1, achievements out | Phase 2 |
|
|
| **D8** | Which core branch/commit is the supported target; may the owner accept small core patches in the fork | confirm; Phase 5 and production hosting depend on it | Phase 3/5 |
|
|
| **D9** | Database driver in the Manager | add a pure-Rust `mysql` driver crate used only by the portable layer; keep the CLI for existing code | Phase 2 (exporter reads) / 3 |
|
|
| **D10** | Local store | SQLite (`rusqlite`, bundled), WAL, `user_version` migrations | Phase 1 |
|
|
| **D11** | Name clash policy | temporary name + rename-at-login (as `.pdump`) | Phase 3 |
|
|
| **D12** | Daily/weekly/monthly quests | excluded | Phase 2 |
|
|
| **D13** | Checkpoint mechanism | `.character save <name>` core command | Phase 5 |
|
|
|
|
---------------------------------------------------------------------------------------------------------
|
|
|
|
## 16. Decisions approved (2026-10-06)
|
|
|
|
D1-D13 were approved as recommended in section 15, with these amendments:
|
|
|
|
| Topic | Decision |
|
|
|---|---|
|
|
| D1 production import | **in-core path**: the realm itself performs remap + commit + cache refresh through new console commands (small core patches are approved, D8). Offline import stays the path for Phases 3-4 on disposable databases |
|
|
| D5 rulesets | CoA <-> Wildcard transfer is **forbidden** (enforced by the store: a character's ruleset cannot change) |
|
|
| D6 challenge state | an **active challenge / hardcore / Manastorm state blocks transfer** (checked by the exporter in Phase 2 and again in the join pre-flight, Phase 11) |
|
|
| D8 core patches | approved |
|
|
| D9 database driver | a MySQL driver with prepared statements is approved (Phase 2/3) |
|
|
| D10 store | SQLite with WAL is approved (implemented in Phase 1) |
|
|
| D13 checkpoints | keyed **internally by the local guid**: checkpoints arrive as `(server_id, local_guid)` and are resolved to the portable character through `Store::find_by_local` |
|
|
| item mapping | `UNIQUE(character_id, server_id, local_item_guid)` in addition to the primary key (implemented in Phase 1) |
|
|
|
|
**Phase 2.1 / Phase 3 amendments (2026-10-06):** `character_settings` carry list tightened to ten strict key patterns, everything
|
|
else quarantined (`PORTABLE_EXPORT.md`); Phase 3 is an offline importer into a stopped disposable realm that keeps the existing
|
|
`Db` abstraction, writes untrusted text only as hex literals from a typed encoder, imports in one MySQL transaction with
|
|
journaled crash recovery (`PORTABLE_IMPORT.md`); the production importer is an in-core `PortableImportService` triggered over RA by
|
|
an opaque job id (`PORTABLE_IMPORT_SERVICE.md`, design only).
|
|
|
|
---------------------------------------------------------------------------------------------------------
|
|
|
|
## Appendix A. Phase 1 - exact proposed plan (not started)
|
|
|
|
**Goal:** local canonical storage only. No VPS, no relay, no public list, no database access to any realm, no UI.
|
|
|
|
### A.1 Branch and commits
|
|
|
|
`feat/portable-characters` (exists, based on `origin/master` `cd3a963`). One commit per step below.
|
|
|
|
### A.2 New dependencies (crates/coa-core)
|
|
|
|
| Crate | Why | Check |
|
|
|---|---|---|
|
|
| `uuid` feature `v7` | UUIDv7 generation (the `v4` feature stays) | pure Rust |
|
|
| `rusqlite` with `bundled` | transactions, migrations, blobs, metadata queries | needs a C compiler on the build machine: present on the owner's machine (MSVC) and on both CI runners |
|
|
|
|
No other new crates in Phase 1. Collections use a hand-written sorted-set + varint encoding (RoaringBitmap is a Phase 6
|
|
decision). Snapshot compression reuses `zstd`; hashing reuses `sha2`.
|
|
|
|
### A.3 Files
|
|
|
|
```
|
|
crates/coa-core/Cargo.toml + uuid v7, rusqlite
|
|
crates/coa-core/src/lib.rs + pub mod portable;
|
|
crates/coa-core/src/portable/mod.rs re-exports, error type
|
|
crates/coa-core/src/portable/versions.rs PORTABLE_CHARACTER_FORMAT_VERSION = 1, PORTABLE_COLLECTION_FORMAT_VERSION = 1,
|
|
EXTENSION_FORMAT_VERSION = 1, REGISTRY_PROTOCOL_VERSION = 1, RELAY_PROTOCOL_VERSION = 1
|
|
crates/coa-core/src/portable/ids.rs CharacterId / ProfileId / SnapshotId / PortableItemId (UUIDv7 newtypes)
|
|
crates/coa-core/src/portable/model.rs PortableCharacter v1 (section 5/6/7), Extension container (opaque), CollectionSet
|
|
crates/coa-core/src/portable/snapshot.rs envelope (character_id, revision, snapshot_format_version, created_at, source_server_id,
|
|
content_hash), canonical JSON + zstd, size limits, hash
|
|
crates/coa-core/src/portable/collection.rs sorted u32 set (delta+varint), union, collection_revision/hash
|
|
crates/coa-core/src/portable/store.rs SQLite store, transactions, migrations, history/pruning
|
|
crates/coa-core/src/portable/migrations/001_init.sql
|
|
docs/PORTABLE_FORMAT.md the on-disk/serialised format and its version rules
|
|
```
|
|
|
|
No Tauri command, no frontend change, no changelog fragment (internal; `AGENTS.md` asks for fragments only for
|
|
player/admin-visible changes).
|
|
|
|
### A.4 Storage
|
|
|
|
`%LOCALAPPDATA%\CoAServerManager\portable\portable.db`, created lazily on first use. Opened with WAL, `foreign_keys=ON`,
|
|
`PRAGMA user_version` for migrations (forward-only, each in one transaction, refuses a database written by a *newer*
|
|
format). Unit tests use temp directories.
|
|
|
|
```
|
|
profile(profile_id TEXT PK, created_at, format_version)
|
|
character(character_id TEXT PK, profile_id FK, ruleset TEXT, name, race TEXT, class TEXT, gender INT,
|
|
revision INT NOT NULL, created_at, updated_at, archived INT)
|
|
snapshot(character_id FK, revision INT, snapshot_format_version INT, created_at, source_server_id TEXT,
|
|
content_hash BLOB, size INT, payload BLOB, note TEXT, PRIMARY KEY(character_id, revision))
|
|
character_server_mapping(character_id FK, server_id TEXT, local_guid INT, last_revision INT, state TEXT,
|
|
PRIMARY KEY(character_id, server_id), UNIQUE(server_id, local_guid))
|
|
item_mapping(character_id, server_id, portable_item_id TEXT, local_item_guid INT, PRIMARY KEY(character_id, server_id, portable_item_id))
|
|
collection(profile_id FK, kind TEXT, collection_revision INT, collection_hash BLOB, format_version INT, payload BLOB,
|
|
PRIMARY KEY(profile_id, kind))
|
|
setting(key TEXT PK, value TEXT) -- history_keep (default 20), ...
|
|
```
|
|
|
|
### A.5 Operations (Rust API, synchronous, transactional)
|
|
|
|
* `create_character(profile, model, source_server_id)` -> `CharacterId` (UUIDv7), revision 1, in one transaction.
|
|
* `commit_snapshot(character_id, expected_revision, model, source_server_id)` -> new revision; fails with
|
|
`StaleRevision{expected, current}` when `expected != current`; `BEGIN IMMEDIATE`, so concurrent writers serialise.
|
|
* `rollback_to(character_id, revision)` -> creates **a new revision N+1** whose payload is the old one (revision
|
|
numbers never decrease; freshness stays revision-based).
|
|
* `prune(character_id)` keeps the newest `history_keep` revisions, **never** the current one.
|
|
* `get_snapshot`, `list_revisions`, `bind_server(character_id, server_id, local_guid)`, `merge_collection_union(...)`.
|
|
* Hard limits enforced at deserialisation (prepares Phase 15): max payload bytes, max items, max spells,
|
|
max extension blobs; decompression capped by declared size.
|
|
|
|
### A.6 Tests (all in `crates/coa-core`, no network, no realm DB)
|
|
|
|
| Test | Proves |
|
|
|---|---|
|
|
| `create_character_identity` | UUIDv7 (version bits, time-ordered), revision 1, row counts |
|
|
| `revision_increments_monotonically` | 1,2,3,... without gaps |
|
|
| `stale_revision_is_rejected` | commit with an old `expected_revision` -> `StaleRevision`, nothing written |
|
|
| `duplicate_uuid_is_rejected` | inserting an existing `character_id` fails and rolls back |
|
|
| `rollback_creates_new_revision` | state equal to the old one, revision strictly greater |
|
|
| `prune_keeps_current` | history cap respected, current never removed |
|
|
| `serialization_roundtrip` | model -> snapshot -> model structurally equal (incl. empty and maximal characters) |
|
|
| `unknown_extension_is_preserved` | opaque extension survives a roundtrip byte-for-byte |
|
|
| `snapshot_hash_is_stable` | same model -> same `content_hash`; one changed field -> different |
|
|
| `oversized_payload_is_refused` | limits |
|
|
| `migration_idempotent_and_refuses_newer_db` | `user_version` handling |
|
|
| `collection_union_never_removes` | union semantics, hash unchanged when nothing new |
|
|
| `collection_set_roundtrip_10k_50k` | compact encoding, sorted, small |
|
|
| `mapping_unique_constraints` | `(server_id, local_guid)` cannot be bound to two characters |
|
|
|
|
### A.7 Gate
|
|
|
|
* `cargo test --workspace --locked` (baseline today: 242 passing; all new tests added on top, none removed)
|
|
* `npm ci && node tools/check-i18n.mjs && npm run build` (CI parity; no frontend change expected, run to prove it)
|
|
* `cargo build` on Linux is covered by CI; locally the Windows build must pass.
|
|
|
|
### A.8 Migration impact
|
|
|
|
None for existing installs: no change to any realm database, to `install.json`, to recovery points or to the update
|
|
flow. A new directory is created on first use of the portable layer only. Removing the feature leaves one unused
|
|
folder.
|
|
|
|
### A.9 What Phase 1 deliberately does not decide
|
|
|
|
How realm rows are exported/imported (Phase 2/3), the item-diff algorithm (Phase 4), checkpoint transport (Phase 5), the
|
|
final collection encoding (Phase 6), transfer-PIN KDF (Phase 9/15). The model leaves room for all of them
|
|
(`item_mapping`, extension container, collection `format_version`).
|