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 (loader 0x61bb19..) and in the hero file (loadHero 0x606632.., saveHero 0x60444c..). 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.

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, lastDifficulty, migratedFrom, heroFrom), hero (AMH as cEngine::SaveHero writes it), world<d> (AMS as cEngine::Save writes it). Written to a temp file, then moved over.
• CharacterNN.autosave.sacredK: same layout, one world (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\.

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 row's second line (call 0x71db2a to SetText 0x736f00) shows "Stufe N - difficulty".
• Laden (action 4 / 0xb) opens the difficulty dialog when there is more than one choice: worlds, newer autosaves "(Autosave)", and "(neu)" for every difficulty up to max(highest world, Silber) without a world (needs the shared hero; not in multiplayer, byte 0x182cb6c).
• "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

• Unlocking by story completion (counters at save header +0x88..).
• Reset a difficulty.
• Remove the export / import UI.
• Silent autosave every 10 minutes.
• Quickload (row 0) does not know characters.
• Multiplayer (see todo.md).