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".

### Spielen screen (cUI_Savegame)

Request 2026-10-20: redesign the load window, 16:9, using the space (layout
agreed: characters left, the character in the middle, worlds right, buttons
below; our own background). Built on the shared screen kit
(docs/screens.md); the window's own drawing and mouse handling are not used.

- The window still scans: before each scan (0x71e330) one preview
  `GAMEnn.PAK` per character is written into `_work`; row nn = character nn.
  Its entries are only needed for the load.
- Left: the characters, newest save first (name, class, level; "im Spiel" for
  the one being played). Click selects, double click plays.
- Middle: name, class and level, the world played last with its date, and
  the hero in 3D with its equipment (2026-10-20): the game's cUI_NetGranny
  (game/ui/granny.h), the control the export screen and the multiplayer
  lobby showed heroes with. The character's hero file goes to
  `_workpreview.pax`, LoadHeroFile (path, 0, info) reads its hero info
  (class, equipment looks) without touching the player hero. Drawn without
  its name label, with the white light set, size factor 3.8 (game 2.5); its
  x is moved by (1365 - 1024) / 2, as it centres the model as in a 1024
  layout. Migrated characters without the shared hero show none until
  played.
- Right: a grid campaigns x difficulties. A cell shows the save's date,
  "+ Autosave" when the autosave is newer, "Story abgeschlossen", "Neu" for a
  difficulty that is open but has no world, "–" when closed. 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..); new worlds need the shared hero, not in multiplayer
  (byte 0x182cb6c). Click selects, double click plays. With a newer autosave
  "Laden von:" picks the save or the autosave (default: the autosave).
  "Welt zurücksetzen" for a saved world (not the character being played).
- Buttons: Neuer Charakter (main menu only), Umbenennen, Löschen (not for the
  character being played), Zurück (action 0xc), Spielen.
- Spielen: a saved world loads through the window's load action (4, with its
  "really load?" confirmation in a game): the window's selection is set to
  its first entry and `g_loadRow` names the row, which `Engine_Load` takes
  instead of the entry's. A new world starts a game (below; in a game after
  stopping the running one). The window's own load / default actions (Enter)
  run Spielen too; its delete actions (7, 8) are ignored.
- Dialogs over the screen: rename (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`), campaign of a new character, confirmations of reset and
  delete. Buttons are cUI_Button2 copies of the load button
  (`game::NewButtonLike`) with our own text ids and overrides.
- Delete moves the character file and its autosave to `charactersdeleted`.
- Neuer Charakter: 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.
- Reset (decided 2026-10-20) removes the world section (a copy goes to
  `charactersdeletedCharacterNN.sacredK.<section>.PAK`) and an autosave of
  that world, and clears the shared hero's story completion of that
  difficulty (hero header +0xed + d); the game counts it per difficulty, so
  the next difficulty closes in both campaigns unless a world keeps it open.

### Character window (cUI_Character)

- 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

`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.

Silent autosave: 10 minutes after the last save of any kind (or the game's
start), `SaveOnTick` does the direct save marked as an autosave, so it goes
into the autosave file. While a window is open or a save runs it waits for
the next tick. A character never saved yet gets its character file from it.
Interval: options window, *Allgemein*, *Autosave (Min.)* (docs/options.md); kept in
`sacredK.ini` `[characters] AutosaveMinutes` (default 10, 0 off).

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).

The Esc menu: "Exportieren" became "Laden" (requests 2026-10-20). The line
(text id 0x419 pushed at 0x6bc272, now "Laden") keeps its command, which shows
UI_CHARACTER (the export screen) and hides the menu; in a game
`UiManager_ReceiveEvent` turns that into showing the load window. The load
window always opens in load mode (`cUI_Savegame::Show` vf24 0x71cfb0 picks
save mode in a game; `SetMode` 0x71c4f0 (2) after it). In a game every
world can be loaded, the current one too (a reload from its last save; the
game's in-game load, engine flag 0x200). A "(neu)" world needs a new engine:
the running game stops as "Beenden" stops it (`cCommand_armaStop`, execute
0x755b30, vtable 0x88ee2c: posts 0x8001 to the main window, whose handler
deletes the engine), and when the engine is gone (`OnGameEnd`) the new game's
start command follows (0x8002), without the main menu. The character being
played cannot be deleted. The export screen (cUI_Character
mode 5) is unreachable; its mod (charexport.cpp, an erase button for export slots) was deleted.

### 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

- Quickload (row 0) does not know characters (not needed, user 2026-10-20).
- Spielen screen: scrolling the list beyond 9 characters.
- Multiplayer (see `todo.md`).