dwgx@blog:~$dwgx
> cd ../posts

thcrap: turning memory patching into a JSON framework

// created

thcrap is a general-purpose Windows memory patching framework built by the Touhou Patch Center community, originally by brliron and a crew of others. This copy is forked from upstream, purely because I wanted to pry it open and see how it runs internally. Its day job is translating those Japanese Touhou doujin games, but underneath it’s an injection-based patch engine that’s completely game-agnostic.

The core relies on DLL injection to inject the engine and plugins into the target process, and it propagates into child processes too, so it can coexist with injection-based patches like vpatch. Configuration is all JSON, so patches are open and readable by nature. Recursive JSON merging is how layering works: stack a pile of patches by priority, use wildcard blacklists to mask out files, and keep translation, BGM, and image patches independent while still composing them together.

Underneath are the few kinds of hooks I forked this mainly to study:

  • binary hack: write changes straight into memory, basically hand-written assembly;
  • breakpoint: hook an arbitrary instruction to call a function in your own DLL, and read or modify the CPU registers at that moment;
  • these two can be grouped and applied in order, purpose-built for packed EXEs and DRM;
  • file breakpoint: swap a data file in memory for its patched version, and the file-format hook is likewise described in JSON and layerable.

Taken apart, these are all standard reverse engineering moves, but organizing them into a “described in JSON, stackable” framework is where it gets interesting. One more detail: it uses a standalone library called win32_utf8 that transparently adds UTF-8 filename support to old programs using Win32 ANSI functions, so there’s no need for AppLocale anymore. That library is split out on its own, so other projects can use it too. Version identification uses SHA-256 plus EXE file size, so different versions of the same game each match their own patch.

Getting started is just git clone --recursive to pull all the submodules, build it in VS and run it, then follow thcrap_tsa (Team Shanghai Alice’s STG engine) and thcrap_tasofro (the Twilight Frontier ones) to read how the hooks are written. The whole project is Public Domain, so there’s no mental baggage reading it. The fork is at github.com/dwgx/thcrap, upstream is thpatch/thcrap.