sacred2_k/CLAUDE.md

CLAUDE.md

Guidance for agents working in this repository. Read README.md (what the project is, build, run, layout), docs/modules.md (the game's modules and address convention) and tools/README.md (RE tools, Ghidra project) first; this file adds how we work and what we learned.

What this is

sacred2K.dll is injected into Sacred 2 Gold with Community Patch 2.65.1 (system\sacred2.exe plus orcSystem, s2core, s2logic, s2logicai, s2render DLLs; 2009, 32-bit, MSVC 8 + STLport) by the launcher sacred2K.exe. It hooks and patches the running game: functions are rewritten and mods change behaviour on top of the original. The game stays playable at every step; the user plays it to test. Sister project: sacredK (Sacred Gold, ../sacred_k), whose framework and working rules this one follows.

• Target files: the user's local installation (see README.md, Supported build). The game folder is given to the launcher once (--game-dir) and kept in build\<preset>\sacred2K.ini, [paths] GameDir. Never hard-code a local path in code, docs or configs.
• Game texts are German (locale\de_DE); keep the game's names when talking about features.
• The user's monitor is 3440x1440.

How the user works (important)

• The user tests in-game and reports back ("1: works, 2: ..."). After a change, say exactly what to test, numbered, in player terms. Don't claim something works until the user (or a test you ran) confirmed it.
• Their game start builds the DLL. A link error LNK1168 (DLL locked) means the game is running; that's expected, not a failure to fix.
• Ask before anything that takes over the desktop (starting the game, autotests).
• Commit only what the user confirmed, or when asked. End commit messages with the attribution line given by the harness.

Principles

• Measure before imitating. Log the original's runtime behaviour instead of guessing from decompiles. Temporary diagnostics: log lines start with diag, code is marked TEMPORARY, both removed before committing.
• No vanilla preservation. Once a mod works, delete the old path, toggles and fallbacks. Keep only migrations (e.g. old save formats).
• Refactor duplicates while writing into shared headers or tables.
• Name as you go. Exported functions are named already (decorated names; prefer hooking them with RE_HOOK_EXPORT). Name what we identify ourselves in tools/names.txt (module 0xADDR Name). No bare hex in logic: named re::Address constants with a comment saying where they come from.
• Data-driven over id lists. Prefer the game's own data tables and scripts over hard-coded ids.
• Document each mod in docs/<topic>.md: the request (with date), what was measured, addresses, how the mod works. docs/todo.md for deferred items.

Build and run

.\build.ps1                           # x86-debug -> build\x86-debug\
build\x86-debug\sacred2K.exe          # start the game with the DLL

New source files must be added to CMakeLists.txt. Output to check: build\x86-debug\sacred2K.log (written anew each start: module check with running bases, hooks, the game's Orc::Log messages as [game:<level>]). Crashes: sacred2K_crash.txt / .dmp next to the DLL (module+offset; the offset is from the running base, add the preferred base for Ghidra).

Code map

• src/re/ — framework: module.h (re::Module, re::Address{module, va}, GameFunction<Fn>, build check by SHA-256), RE_HOOK(address, fn) / RE_HOOK_EXPORT(module, "?decorated@@", fn) / RE_HOOK_API (Detours; define fn_original, null until installed), RE_STARTUP(name, fn), patch helpers in patch.h (all take re::Address and verify the original bytes first), config, log, crash handler.
• src/game/<module or subsystem>/ — the game's structures and functions: orc/string.h (Orc::String), orc/log.cpp (logger hook), render/dx9base.h (cDX9Base, sInitParams).
• src/mods/ — one file per mod; the top comment explains the request, the measured behaviour and the approach. borderless.cpp: always borderless windowed at monitor size (docs/borderless.md).

Reverse-engineering workflow

• Find by name first: node tools/exports.mjs <module> "<regex>"; most classes of the DLLs are exported (?method@Class@@...).
• Decompile: .\tools\decompile.ps1 <module> 0xADDR|symbol -ReadOnly.
• Disassemble: node tools/disasm.mjs <module> 0xVA [n], or objdump -d -M intel --start-address=.. --stop-address=.. <module>.
• Verify calling conventions before hooking or calling: decorated names tell them (QAE/UAE = __thiscall, QAA/UAA = __cdecl with this on the stack, SA = static __cdecl, SG = static __stdcall); still check ret N. Use __fastcall(self, edx, ...) for __thiscall.
• Absolute addresses inside code were relocated with their module: compare and patch them as re::Address, never as raw Ghidra VAs.