Hi3-Patcher/docs/ace.md

ACE patch (Windows, clients ≤ 8.9)

Builds a patched BH3.exe from a capture of the clean client's initialized state. Only BH3.exe is written, without a backup. 9.0+ clients use HoYoKProtect instead.

Discovery (ace/discovery.rs)

Read-only; all checks must pass:

File	Required layout
BH3.exe	7 sections all named .ace*, 4 KiB section alignment, no TLS directory, entry calls the BH3Base.dll ordinal-1 import
BH3_Data/sharedassets0.assets	ChannelConfig resolves to a known region
UnityPlayer.dll	exports UnityMain; three writable decoder globals found via a .text code pattern
BH3_Data/Native/UserAssembly.dll	exports il2cpp_get_api_table; executable .tvm0 section with a virtual tail larger than its raw size

Capture (ace/capture.rs, ace/process.rs)

After confirmation, launches the client (Windows directly; Linux via umu-run + Proton) and reads its memory read-only — no injection or protection tampering. Once the state is stable for 2 s (120 s timeout), it captures the .tvm0 section, the three decoder states and the committed private executable allocations.

Normalize and rebuild (ace/runtime.rs, ace/generate.rs)

runtime.rs checks the captured .tvm0 against the original after PE relocations, resolves FF 25 jump slots against the captured allocations, and emits a position-independent blob and two thunk tables. generate.rs appends .bh3code (the bootstrap.bin stub, patched with the discovered RVAs/sizes per bootstrap.json) and .bh3imp (imports, decoder states and the runtime blob), then repoints the entry point.

A HI3AUTO1 receipt with SHA-256 hashes of the patched image, UnityPlayer.dll and UserAssembly.dll is appended; a repeat run that validates it is a no-op. Written via util::replace::verified.