Touhou Community Reliant Automatic Patcher
Basically, this is an almost-generic, easily expandable and customizable framework to patch Windows applications in memory, specifically tailored towards the translation of Japanese games.
It is mainly developed to facilitate self-updating, multilingual translation of the Touhou Project games on Touhou Patch Center, but can theoretically be used for just about any other patch for these games, without going through that site.
Main features of the base engine
Easy DLL injection of the main engine and plug-ins into the target process.
Full propagation to child processes. This allows the usage of other third-party patches which also use DLL injection, together with thcrap. (Yes, this was developed mainly for vpatch.)
Uses JSON for all patch configuration data, making the patches themselves open-source by design. By recursively merging JSON objects, this gives us...
Patch stacking - apply any number of patches at the same time, sorted by a priority list. Supports wildcard-based blacklisting of files in certain patches through the run configuration.
Automatically adds transparent Unicode filename support via Win32 API wrappers to target processes using the Win32 ANSI functions, without the need for programs like AppLocale.
Patches can support multiple builds and versions of a single program, identified by a combination of SHA-256 hashes and .EXE file sizes.
Binary hacks for arbitrary in-memory modifications of the original program (mostly used for custom assembly).
Breakpoints to call custom DLL functions at any instruction of the original code. These functions can read and modify the current CPU register state.
Multiple sets of sequentially applied binary hacks and breakpoints, for working around EXE packers and DRM schemes.
File breakpoints to replace data files in memory with replacements from patches.
Wildcard-based file format patching hooks called on file replacements - can apply patches to data files according to a (stackable!) JSON description.
Optional Steam integration for games that are available through Steam, but don't come with Steam integration themselves. Can be disabled by deleting
... and all that without any significant impact on performance.
win32_utf8: A UTF-8 wrapper library around the Win32 API calls we require. This is a stand-alone project and can (and should) be freely used in other applications, too.
thcrap: The main patch engine.
thcrap_loader: A command-line loader to call the injection functions of
thcrapon a newly created process.
thcrap_configure: A GUI wizard for discovering patches, configuring patch stacks, and locating supported games.
thcrap_tsa: A thcrap plug-in containing patch hooks for games using the STG engine by Team Shanghai Alice.
thcrap_tasofro: A thcrap plug-in containing patch hooks for various games by Twilight Frontier.
thcrap_update: Contains updating functionality for patches, digitally signed automatic updates of thcrap itself, as well as an updater GUI.
thcrap_update.dllcan be safely deleted to disable all online functionality.
thcrap_bgmmod: A helper library to handle the non-game-specific parts of BGM modding for originally uncompressed PCM music, like codec support and loop point handling. Currently statically linked into
thcrap_tsaas this module is currently the only one with support for BGM modding, but already split into a separate library to be ready for covering more engines in the future.
A ready-made Visual Studio build configuration, covering all modules and their dependencies, is provided as part of this repository. To set up the build:
Install Visual Studio Community 2019.
- Visual Studio 2019 or newer is required to build thcrap_configure_v3. For all other components, Visual Studio Community 2017 will also work
- You can also use Visual Studio Community 2022. During installation, make sure to install the v141 and v141_xp toolsets (v141_xp is the Visual Studio 2017 compiler with Windows XP compatibility, and v141 is required by v141_xp).
Make sure that you've pulled all Git submodules together with this repo:
git clone --recursive https://github.com/thpatch/thcrap.git
(Optional) If your thcrap build should be able to automatically update itself, you need to create a code signing certificate. To do this, run the following commands on the Visual Studio command prompt (
vcvarsall.bat) in the root directory of this repo (the one with
makecert -n "CN=Your Name,Efirstname.lastname@example.org" -$ individual -a sha256 -len 4096 -r -cy authority -sky signature -pe -sv cert.pvk cert.cer pvk2pfx -pvk cert.pvk -spc cert.cer -pfx cert.pfx
cert.pfxis used to sign the binaries as part of the build, so don't change the file name.
thcrap.sln, choose Debug or Release from the drop-down menu in the toolbar (or the Configuration Manager) and run Build → Build Solution from the main menu.
You can also build from the command line by running the Visual Studio tool environment batch file (
vcvarsall.bat), then run
msbuild /m /p:Configuration=Debug
msbuild /m /p:Configuration=Release
in the thcrap directory. The binaries will end up in the
Signing a release archive for automatic updates
cert.pvk to a .pem file using OpenSSL, then use this file together with
openssl rsa -inform pvk -in cert.pvk -outform pem -out cert.pem python release_sign.py -k cert.pem thcrap.zip
Using different compilers
Visual Studio Community 2017 is recommended for building, and the build configuration references the Visual Studio 2017 platform toolset with Windows XP targeting support by default. However, the project should generally build under every version since Visual C++ 2010 Express after changing the
<PlatformToolset> value in
Base.props. For a list of all platform toolsets available on your system, open the
Properties dialog for any included project and refer to the drop-down menu at Configuration Properties → General → Platform Toolset.
Compilation with MinGW is currently not supported. This is not likely to change in the foreseeable future as we don't see much value in it.
All required third-party libraries for the C/C++ code are included as Git submodules in the thcrap_external_dependencies submodule, which also contains pre-built DLLs, .lib files, export definitions and PDBs. These are:
Jansson, required for every module apart from
libpng (>= 1.6.0), required by
thcrap_tsafor image patching.
zlib, required by
thcrap_updatefor CRC32 verification. It's required by
thcrap_bgmmodcurrently supports the following codecs via third-party libraries:
The scripts in the
scripts directory are written in Python 3. Some of them require further third-party libraries not included in this repository:
- PyCrypto is required by
- pathspec is required by
repo_update.py. Can be easily installed via
The Touhou Community Reliant Patcher and all accompanying modules are released to the Public Domain, unless stated otherwise. This means you can do whatever you want with this code without so much as crediting us.
That said, we do appreciate attribution.
Love our work? Become a backer of Touhou Patch Center on Open Collective, and help us decide the priorities of thcrap's future development.
Thank you to all our backers!