What this covers:
- Initial thcrap configuration (kinda)
- How to make a new patch
- How to get thcrap to load your new patch
What this doesn't cover:
- How to publish your patch
- How to use thtk beyond extracting assets
This guide has not been fully updated for the recent restructuring update, but should be close enough. Double-check your paths to patches, and if all else fails, make your repository in the repos folder instead.
You'll need a text editor that doesn't explode if it doesn't see CR EOL markers. Notepad++, VSCodium, and Sublime are some examples if you don't have one.
You'll need thcrap set up with some Touhou games first. Get a basic patch configured (i.e., just lang_en) and confirm you can run it first.
If you don't have thcrap you can get it here: https://github.com/thpatch/thcrap/releases
If you don't have Touhou games you can get some here: https://www.dlsite.com/eng/circle/profile/=/maker_id/RG46179.html
Optional, but highly recommended, UTL. This will let you run a configuration with a game without having to create shortcuts: https://github.com/thpatch/Universal-THCRAP-Launcher/releases
Optional, but useful, thtk: https://github.com/thpatch/thtk/releases
Full instructions on how to set up thcrap are here: https://www.thpatch.net/wiki/Touhou_Patch_Center:Download
You can choose basically any patch but to get started it will be easiest to use the English patch since it provides some handy base assets and gets all of the files thcrap needs to do its thing. Here's the short version:
- Extract thcrap
- Run thcrap_configure. I would recommend actually reading the text, it is intended to be informative.
- Click "Next" or press enter to download information about published patches.
- There will be a very long list of patches to select from. Scroll up until you seee a big list of "lang_**" patches - the one you want is lang_en. Double-click on it to select it, adding it and its dependencies to the selected patches list at the bottom. thcrap_configure will scroll to the bottom for you so you can confirm this.
- When you're satisfied, click Next or press Enter. This will download some data.
- You'll be asked to enter a name for this configuration. Choose whatever you want, it's easy to change later. For this tutorial, we can leave it as en. After this you'll be given confirmation of what your run configuration is.
- You will need to tell thcrap about your games now. The text displayed is very helpful. If you have all of your Touhou games in the same root folder (i.e. C:\Games\Touhou) you can navigate to this folder and select it in the prompt that comes up. (Protip for later: games.js can take relative folder paths. Also you can edit games.js directly to add new games.)
- If you've run thcrap_configure before, you can press k unless you want to add new games.
- You'll be asked if you want shortcuts. This will create one new shortcut for every single game in your games list - this can be dozens if you have all the games. If you use UTL you don't need to do this - you can use UTL instead This is explicitly what UTL was designed for and it works well. It's up to you if you want to deal with the shortcuts or not.
- thcrap_configure will download all of the files now. This can take a while.
- You're done. Open up UTL or a shortcut and launch the game, then confirm it's in English.
Ask in #support on the thpatch Discord. https://discord.thpatch.net/ Pro tip: alt + print screen will take a screenshot of the currently focused window only, so you can easily share what you're seeing without oversharing. thcrap_log.txt in the thcrap folder is also very helpful - there's also the immediate last log in thcrap_log.1.txt.
thcrap patches have a very simple directory structure. Game-independent data is stored in the root (as well as some game-dependent run configuration data), with each game-specific folder being what you'd expect to see after unpacking a game's assets with thdat and thanm. All patches are unencrypted and open-source, meaning you can simply open up the directory to see how they're structured and what their contents are.
Published patches are stored in a repository, or repo, where all content managed by a certain user or organization lives. For a local patch, you can create your own local repo, or just make a new folder anywhere you like. It'll be most convenient to keep it in the thcrap folder (you'll find out later). Following the restructuring update, these are all located in the repos folder in the thcrap folder.
For this tutorial we'll use a folder called "Local" in the root of the thcrap folder.
Some assets (usually full dumps of the game's dat file(s)) can be found here: https://www.thpatch.net/wiki/Asset_Repository Ripped assets will be in the directory structure thcrap expects.
The best way to get assets is dumping them from your own copy of the game. You can use thtk. This will involve the command prompt. Note that thdat.exe will extract all of the asset files into the current working directory - I strongly recommend keeping things organized with a dedicated assets directory somewhere near the thtk directory, and somewhere near your games too. Then you can invoke path/to/thdat.exe -x path/to/thXX.dat in that directory for the contents of the dat to be extracted into the current directory.
You'll notice a lot of sprites are missing - many of them are bundled in anm files. You can extract them with thanm. Here's a command for command prompt (cmd) which should extract all of them:
FOR %A IN (*.anm) DO path/to/thanm.exe -x %A
Run this in the directory you extracted the assets into, replacing path/to/thanm.exe with the actual path to thanm.exe, and all of the anm files will be extracted.
This is the fun part. All of the assets thcrap loads are stored in unencrypted files in common formats (i.e., normal text, PNG, JPG, WAV...). Reference the original assets from the game, and where they are in the assets folder, and place them in the corresponding folder in your patch folder.
For concrete examples, take a look at thpatch/lang_en - anything with Japanese text in the original assets has been translated to English here, and you can poke around to get an idea of what your patch's folder can look like. There will also be English translations of dialog located in the .msg.jdiff files - these are just JSON objects, every single one can take two lines, and if you write too much it'll just get cut off, so go nuts.
Easy example: Say you want to edit the title screen of HSiFS so it displays a different logo, perhaps one defaced with your favorite topical meme. If you have an asset dump of HSiFS, you'd find the original in title/title_logo.png. You can also find an English translated logo in thcrap/thpatch/lang_en/th16/title/title_logo.png. Once you do your magic in your image editing program, you can save the final result in thcrap/Local/th16/title/title_logo.png.
If you make any text files, please make sure they're in Unix (LF) or git will do weird things to it later.
If you want ideas of what you can slap into your mod, try poking around the thpatch mirror, hosting many third-party mods. You can see what the directory structure is like without having to download the entire mod. http://mirrors.thpatch.net/
If you have a sprite on a sprite sheet completely transparent, thcrap will assume you don't want to modify it and load something from an earlier patch or the base files instead. This can be useful if, say, you only want to replace text in stage logos but not the art, or knives with baseballs, but if you want to delete a sprite this can be annoying.
The trick you can use to work around this is something I've taken to calling a "magic pixel" - a single pixel of value #00000001 - black, but almost totally transparent. Place this in a sprite, and thcrap will load this essentially invisible sprite, making it look like the original sprite has been deleted.
There's an entire tutorial posted on the thpatch wiki. Here it is: https://www.thpatch.net/wiki/BGM_modding Pay special attention to Splashman's BGM list.
If you want examples of what a BGM mod is supposed to look like, try Splashman/bgm_sc88pro, WindowDump/chipin, or pgj1997/hq-rips. The only hard part is making a seamless loop.
I haven't figured this out myself yet so here's links to people that have.
ECL (Enemy Control Language) was designed by pbg for the Seihou Project (original source code here) and now has many years of ZUN gunk duct taped on top of it. It's an assembly-like language with no official documentation, because ZUN never expected anyone else to use it.
This stuff is really crazy and it may not be feasible to do what you want in a reasonable amount of effort. If you just want to make some bullets pop out and stuff, look into Danmakufu which kinda sucks but is a lot easier to get started with. (Danmakufu Woo Edition is suggested instead.) If you're willing to deal with the hassles, you'll be able to modify the games almost as well as ZUN can.
Nutzer has a basic tutorial here: http://nutzer.bplaced.net/ecl_01.html
You can use an eclmap file to add neumonics to the opcodes, making it easier to read and write, almost like a real language. Here's some from Priw8: https://github.com/Priw8/eclmap
Guy (AKA dass) has documentation on what most of those instructions do here: https://en.touhouwiki.net/wiki/User:Mddass/Touhou_File_Format_Specification/ECL
All you need to do is add your new patch to a run configuration. You can open up en.js (created earlier in the tutorial) or any of the other .js files in the thcrap folder other than games.js or config.js. You'll see a JSON object, with an array of patches at the end. This tells thcrap where to look to find replacement files for the game's assets, and in what order. All we need to do is add our new patch (Local) to this list and thcrap will load it.
Here's what it could look like:
{
"console": false,
"dat_dump": false,
"patches": [
{
"archive": "repos/nmlgc/base_tsa/"
},
{
"archive": "repos/nmlgc/base_tasofro/"
},
{
"archive": "repos/nmlgc/script_latin/"
},
{
"archive": "repos/nmlgc/western_name_order/"
},
{
"archive": "repos/thpatch/lang_en/"
},
{
"archive": "Local/"
}
]
}Go ahead and save it. Now, the next time you open UTL or the shortcut and run th17 (HSiFS) with en.js, you'll have your new logo appear on the title screen.
Note that you can save this file as anything you want. thcrap loads configurations as arguments when it's launched - it needs a patch configuration (i.e. en.js) and a target executable (something from games). It will launch the game, hook into it so files can be patched, and then start replacing them as the game runs. If you save it as anything else, you need only pass thcrap_loader the new name. This is what the shortcut generator does. UTL handles this for you, which is why it's a very useful tool for mod users and patch developers.
Note that these are all relative paths under "archive" - thcrap can also accept absolute paths, but those are longer.
Your patch won't show up in thcrap_configure unless you prepare it for distribution. Don't worry, it's still there.
Go crazy. The world is your oyster, and you have tools that allow you to make meme images in ways that Photoshop can only dream of.
thcrap has hot patching - a file will be loaded from the patches intead of the original files every time it's attempted to be loaded. This means that every time you load the title screen, it will load all the title screen assets. If you change something on it, enter a stage, and then return to the title screen, the title screen assets will be reloaded by the game, detoured by thcrap, and then load your freshly saved changes. This works for every single file, including things like .ecl files. You don't need to reload the game
If you're making dialogue mods, thpatch/skipgame will remove all the bullets from the game, allowing you to visually inspect your changes for cut off text or typos.
Outside the scope of this document right now. Dumb short version: make a new folder in your thcrap folder you want to be your repo name, move Local in there, rename it to something that describes what it actually is. Update any run configs you have that reference it. Install Python 3, make sure it's in your PATH. Install Git, get an account on some Git hosting service. Save .gitattributes from here into your repo folder, it'll prevent many common errors from happening. https://github.com/thpatch/thcrap-tsa/blob/master/.gitattributes You're now ready to follow the thpatch tutorial. https://www.thpatch.net/wiki/Touhou_Patch_Center:Servers#Building_your_own_patch_server
If Git complains to you about EOL encoding when you try to make a commit go convert the mentioned files to CR EOL. If you don't do this the files will be corrupted and no one will be able to download your mod.