sacred_k/docs/characters.md

# Characters and difficulties (one file per character)

## Request (2026-10-19)

Get rid of exporting characters. One character = one save file; inside it one
world state per difficulty. The hero (gear, level, attributes, skills, chest,
everything) is shared between the difficulties; only the unlocked portals are
per difficulty (they have to be found again on each level).

- Unlocking: Bronze and Silver are open from the start; each following
  difficulty opens by completing the story on the one before it. More
  difficulties shall be addable later.
- The export / import screen goes away. The load window lists characters;
  loading asks for the difficulty.
- "Spiel speichern" saves the current character into its current difficulty.
  No "switch difficulty" button: save, end the game, load on another
  difficulty. No save on quit.
- A silent autosave every few minutes into a separate slot, so the player
  still decides when the real save is updated.
- Existing saves are migrated.
- Delete a character (everything of it); reset a single difficulty.
- Multiplayer: later (see `todo.md`).

Decided (2026-10-19, follow-up):
- Unlocking by story completion only; Bronze and Silver always open (maybe
  only Bronze after a later rebalance). No level ranges: enemies always scale
  with the player and the difficulty.
- Autosave every 10 minutes for now (a game setting later); the load window
  offers it per character when it is newer than the real save.
- The game's own autosaves on story steps also go into the autosave slot,
  silently.
- Migration as proposed (group by hero name + class), a backup of all saves
  first. Done by hand once:
  `Documents\Sacred\backup\2026-10-19_before_characters` (Documents save
  folder and game save folder); the migration code makes its own backup too.

## Measured / read so far

### Files

- Save games `GAMEnn.PAK` ("AMS", version 0x1b): a full world dump; the hero
  is one object in it (`* Objects`, ref 1, family 3) and its items are in
  `* Inventory`. Chunks are listed by the loader's log (`* Engine`, `* world`,
  `* calendar`, `* Blood`, `* RegionInfo`, `* Team/AllianceInfo`,
  `* Objects`, `* Inventory`, `* Particles`, `* Views`, `* Weather`,
  `* Scripts`).
- Hero files `Heronn.pax` ("AMH"): written by `ItemDataMgr::saveHero`
  `0x6046f0`; header 0x22c bytes + chunks (items, inventories, chest, stats
  block). The hero's **portals** and world position are part of it (log
  `saveHero ... wpos[..] portals[%x]`; portal bits on the hero at +0x578).

### Functions

| Address | What |
|---|---|
| 0x60ac70 | `cEngine::cEngine`: new game or save-game load |
| 0x61b790 | `cEngine::Load(path, quiet)`: reads a `GAME.PAK` (version check 0x15..0x1b), chunk loop, logs `---LOADING SAVEGAME.PAK` |
| 0x619c90 | `cEngine::Save(path)`: called from the render thread when engine +0x54 has 0x40/0x80; row = engine +0x68 |
| 0x60dc00 | `cEngine::InitGame`: new game (campaign start, start equipment) |
| 0x61cda0 | `cEngine::SaveHero(path)`: hero export (`saveHero` into a RAM file, then to disk) |
| 0x7d7c40 | session singleton (0x3ad0 bytes, `g_session` 0x182cb68) |
| 0x7efd90 | `Session::SelectHeroSlot(slot 1..8)`, ret 4: loads `Save\Hero%02d.pax` into the session's RAM file +0x3a3c, sets +0x49 = 1 (hero from file), +0x37b8 = slot, reads the hero header into +0x16a (0x22c bytes) |
| 0x755ac0 | `cCommand_armaPlay::execute`: posts 0x8002 (mode 1 load row, 4 load multi, else init) to the main window |
| 0x706b90 | difficulty list for a hero level (Bronze .. Niob) |

- With session +0x49 set, the engine constructor loads the hero from the
  session's file into the **loaded save game** (`loadHero` at 0x60ba65) and
  destroys the old hero's items afterwards. That is the vanilla mechanism for
  "this world, that hero" and the base of the shared hero.
- In-game save / load: engine +0x54 flags 0xc0 (save row +0x68 via
  `cEngine::Save`), 0x200 (load row via `cEngine::Load`).

### Difficulty

- `g_gameLevel` 0x182cdc4: current difficulty, from the save header (log
  `GameLevel[n]`). Index mapping still to confirm (0 = Bronze ..).
- Story completion: `cStatsManager` (`cStatsManager::Instance(player)`
  0x425160) +0x5704, one byte counter per difficulty (6 entries).
  `0x424bc0` (k) increments, `0x424be0` (k) reads, `0x424c00` (k, value) sets.
  The script opcode at 0x4aed26 increments counter[`g_gameLevel`]: the story
  end. The counters travel in the save header (dwords at +0x88.., loader
  0x61bb19..) and in the hero header chunk 0xc3 (bytes at +0xed.., written by
  0x604360, read by loadHero 0x606632..; +0xec is `g_gameLevel`). Checked in
  a character file (2026-10-20): Silber and Gold completed, played on Platin =
  [0, 1, 1, 0, 0] in the hero and the Platin world. The console cheats
  `bronze` / `silber` / ... (0x615d00..) increment them too.
- Vanilla offers a difficulty by **hero level**, not by completion:
  thresholds `0xad2dc4..0xad2dd4` (5 dwords, parsed from the balance data key
  `StartLevMulti` at 0x5ef12c). Silver for levels [dc4, dcc], Gold
  [dc8, dd0], Platinum [dcc, dd4], Niob >= dd0, Bronze <= dc8. The same
  thresholds reduce experience when the hero is far above the difficulty
  (0x57dd60). Values: to be logged at runtime.

### Runtime log (2026-10-19, vanilla flows)

| Flow | What happened |
|---|---|
| load row 2 | `armaPlay load [2]` -> `cEngine(0x00000002)` -> `cEngine::Load("./SAVE/GAME02.PAK", 1)`; engine +0x68 = row |
| in-game save | `cEngine::Save("SAVE/GAME02.PAK")`, engine +0x54 = 0x444 |
| new game, exported hero, Silver | `cUI_Character::executeAction(IMPORT_DO) difficulty[1]`, `cEngine(0x80080000)`: bit 31 new game, bits 16..23 = hero slot + 1; `InitGame` creates a start hero of class session +0x44 (9) with start equipment, then `LoadHeroFile("Save\Hero07.pax", 1, 0)` (`0x61d190`, cdecl) loads the exported hero onto it |
| new game, new hero, Bronze | `armaPlay init`, `cEngine(0x80000000)`, class +0x44 = 6, no hero file |

- `g_gameLevel`: 0 Bronze, 1 Silver (2 Gold, 3 Platinum, 4 Niob). The
  battlemage row is Silver.
- Level thresholds at runtime: 20, 60, 100, 140, 180.
- `Session::SelectHeroSlot` and session +0x49 are not used in single player
  (multiplayer). The hero swap block after it (0x60ba1c..) is not on the
  single-player load path.
- `LoadHeroFile(path, 1, 0)` puts a hero file onto the existing player hero,
  start items and all: the same operation the shared hero needs after a
  world load.
- Confirmed in-game (2026-10-19/20): `LoadHeroFile(hero, 1, 0)` called right
  after `cEngine::Load` returns puts the hero onto the loaded world's hero.
  An exported battlemage loaded onto another character's world came out
  exact: level, attributes, skills, gear, backpack, chest; nothing
  duplicated or left behind. It even replaced the class (dwarf hero onto a
  battlemage world). The result survives an in-game save and reload, with no
  cheat-check message.

## Follow-up requests (2026-10-20)

- Numbered files (`CharacterNN.sacredK`), one list row per character; the
  difficulty is chosen when loading, in a dialog (or a newer autosave, marked).
- Rename a character from the load window.
- Every difficulty below the highest played one is always available; one
  without a world starts a new game with the shared hero.
- The save key and the Esc menu ("Spielstände" becomes "Speichern") save
  directly, without the save window.
- Main menu: "Kampagne Ancaria", "Kampagne Underworld" and "Spielstände"
  become one "Spielen": the characters, loaded or started in either campaign
  on any difficulty; new characters from there too. A character file holds a
  world per campaign and difficulty; the format must take more difficulties
  later. Decided: no level requirement for the Underworld (vanilla: hero level
  25, 0x70c48b), story completions open the next difficulty in both campaigns,
  "Neuer Charakter" is a button in the Spielen window.

### Campaigns (measured / read 2026-10-20)

- `g_campaign` 0x182cdc8 (u16): 0 Ancaria, 1 Underworld. The main menu's
  event handler (0x711fa0) sets it by entry name before an entry handles an
  event (UI_LABEL_NEWGAME 0, UI_LABEL_NEWADDON 1); both entries show
  UI_CHARACTER. `cEngine::Save` writes it to the save header +0x24 (2
  Ancaria, 3 Underworld, 0x61a5c5), `cEngine::Load` sets it from there
  (0x61bafd). The load window lists only saves of the running campaign
  (0x71e2b9).
- Story completions are counted per difficulty only (the same counter for
  both campaigns).
- Main menu (cUI_MainMenu, entries built by 0x712f30): cUI_StaticText64FX
  entries (constructor 0x753d70), name +0x30, rect +0x24 (0x20 apart), text
  id +0x78, command +0x88; main page vector +0x158, children +0x90.

## Implementation (`src/mods/characters.cpp`, `charfile.{h,cpp}`)

### Files

- `Documents\Sacred\save\characters\CharacterNN.sacredK`: "SKCH", version 1,
  section count, then `{name[16], offset, size}` entries. Sections: `meta`
  (JSON: format, name UTF-8, class, level, lastCampaign, lastDifficulty,
  migratedFrom, heroFrom, heroFromCampaign), `hero` (AMH as
  `cEngine::SaveHero` writes it), one world per campaign and difficulty,
  `ancaria<d>` / `underworld<d>` with d = `g_gameLevel` (AMS as
  `cEngine::Save` writes it). Sections are named, not slotted: a higher
  difficulty (or another campaign) is one more section. Files of the first
  format named Ancaria's worlds `world<d>`; they are renamed when read
  (charfile.cpp) and written under the new name at the next save. Written to
  a temp file, then moved over.
- `CharacterNN.autosave.sacredK`: same layout, one world (`meta.campaign`,
  `meta.difficulty`).
- The game's save folder is redirected to `characters\_work` (userfolders);
  the game reads and writes `world.PAK` / `hero.pax` there.
- Deleted characters move to `characters\deleted\`.

### Main menu (`src/mods/mainmenu.cpp`)

After the build (0x712f30) the NEWGAME and NEWADDON entries are removed (out
of both vectors, deleted) and UI_LABEL_LOADGAME ("Spielstände", shows
UI_WND_SAVEGAME) moves to the top with the text "Spielen"; the others move up,
keeping the gap before "Beenden".

### Load window (cUI_Savegame)

- Before each scan (0x71e330) one preview `GAMEnn.PAK` per character is
  written into `_work` (header, thumbnail, world time, description
  "Name - Klasse"); row nn = character nn. The preview's campaign field is
  the running campaign, so the window lists every character. The row's
  second line (call 0x71db2a to SetText 0x736f00) shows
  "Stufe N - Campaign - difficulty".
- Laden (action 4 / 0xb) opens the world dialog when there is more than one
  choice: per campaign worlds, newer autosaves "(Autosave)", and "(neu)" for
  every difficulty without a world up to the highest open one (needs the
  shared hero; not in multiplayer, byte 0x182cb6c). Open: Bronze and Silber,
  every difficulty up to the highest with a world in either campaign, and the
  one after each difficulty whose story the shared hero completed (hero
  header +0xed..). `g_campaign` is set to the chosen world's before loading
  or starting.
- "Neuer Charakter" (two places below Löschen; main menu only) asks for the
  campaign, sets `g_campaign`, hides the window and shows UI_CHARACTER (the
  game's character creation, as the main menu's campaign entries did). The
  first save makes the character file.
- Vanilla made no new heroes for the Underworld: `cUI_Character::Show`
  (vf24 0x70e2a0) switches to mode 7 in single player with `g_campaign` 1
  (0x70e3e8), the import of an exported hero of level 25+ (0x70eedc); with no
  exported heroes its slots were empty, and slots below level 25 never lit
  up (render 0x70f4df / 0x70f57c) (reported 2026-10-20). All eight campaign
  checks of the window (0x70c473, 0x70d199, 0x70e3e8, 0x70eade, 0x70eeb2,
  0x70f4df, 0x70f57c, 0x70f6aa) read a constant Ancaria instead: creation
  with all classes in both campaigns; the start (ExecuteAction 0x70d0f0,
  action 1) uses `g_campaign` as set.
- Class selection without "Importieren" (request 2026-10-20): button +0x3a0
  (caption UI_IMPORT in modes 0/1); its modes-0/1 draw (0x70f67e) is removed,
  its click (0x70eab4 / 0x70eac7, SetMode(7)) jumps to the handler's end.
- Load window without "Speichern" (request 2026-10-20; saving is direct):
  button +0x820 (action 1, disabled in load mode, so its click falls through)
  is not drawn (jump over 0x71ddbc); Löschen (+0x8dc) takes its rect, our
  buttons follow below it.
- "Umbenennen" (below Löschen; not for the character being played) asks for
  a name; keys go to the field through the input key capture. The name is
  only in the hero header chunk 0xc3 (+8, UTF-16, 0x40 chars): rewritten in
  the hero, every world and the autosave, plus `meta.name`. Confirmed: the
  game loads renamed characters without complaint.
- Dialog buttons are cUI_Button2 copies of the load button
  (`game::NewButtonLike`); their captions are our own text ids with
  overrides (texts.cpp checks overrides for our ids too).

### Load

`cEngine::Load` (0x61b790) of a listed row: the chosen world and the hero are
unpacked to `_work`, the original loads `world.PAK`, then `LoadHeroFile`
(0x61d190) puts the shared hero on. The world's portals (hero +0x578) and
position (+0x18..+0x28) are put back afterwards: the hero file holds the
whole hero object and `loadHero` deserialises it over the hero, position
included (measured: the hero stood where it was saved on another
difficulty; the hero stays the same object). A migrated character without a
shared hero takes it from the first loaded world (`heroFrom`).

### New world on a difficulty

As `cUI_Character::executeAction(IMPORT_DO)` (0x70d637): session (0x7d7c40)
+0x14 = 1, +0x44 = class, GameSetup (0x417e50) +0 = 1, `g_gameLevel` = d,
then cCommand_armaPlay (vtable 0x894ff4, execute 0x755ac0) mode 1, argument
`0x80000000 | 1 << 16`. cEngine's constructor runs InitGame and then
`LoadHeroFile("Save\Hero00.pax")` (0x60bf2c); our hook loads the character's
hero instead, keeps the start position, clears the portals and makes the
game the character's.

### Save

`cEngine::Save` (0x619c90) writes `world.PAK`, then `SaveHero` writes
`hero.pax`; both go into the current character (a new one gets the next free
number). Story autosaves (engine event 0xf subtype 2 with the flag at +0x18,
noted in `cEngine::ReceiveEvent`) go into the autosave file.

Direct save (K key, Esc menu "Speichern"): on the next engine tick, as the
quicksave does (0x618ebb): `cUI_Manager::CanOpenWindow` (0x75a690),
`cEngine::CaptureScreen` (0x613710, 1), description +0x6a, row +0x68 = 0,
flag +0x54 |= 0x40. The Esc menu line keeps its action (Show
`UI_WND_SAVEGAME`); `cUI_Manager::ReceiveEvent` (0x757120) turns that into the
direct save while a game runs. Its text is patched at 0x6bc1f7 (id 0x41b is
used by other windows too). Loading is from the main menu only.

### Migration

On first start (no `characters\` folder): after a backup in
`Documents\Sacred\backup\<stamp>_characters_migration`, `GAME*.PAK` and
`Hero*.pax` are grouped by (name, class); the newest world per difficulty is
kept, the newest file overall is the shared hero.

## Open

- Reset a difficulty.
- Remove the export / import UI.
- Silent autosave every 10 minutes.
- Quickload (row 0) does not know characters.
- Multiplayer (see `todo.md`).