Touhou Patch Center:Wine tips

Welcome to the thpatch *nix user guide!

──────────────────── .∘° ❀ °∘. ────────────────────
This compendium was written with our practical knowledge of Linux.
Help us improve it by writing about MacOS, FreeBSD, or Android.
──────────────────── ॱ∘ₒ︎ ❀ ₒ︎∘ॱ ────────────────────

Wine secrets

Getting Started

motivation

Almost every Touhou Project since 2002 has been released exclusively for Microsoft Windows. The top concern for players migrating away from the Windows ecosystem is ensuring their games remain playable after switching. Sadly, running windows games on other platforms has always been (and will always be) prone to malfunction. In practice, many small things stop working properly and you're left wondering how to fix them. This guide exists to catalogue these issues and their remedies.

Wine and Unix-likes

The term Unix-like refers to a myriad of operating systems—Linux, SteamOS, MacOS, FreeBSD, Android—that share Unix as their common ancestor. To run windows software on these platforms, you must have a component that acts as a translator between your OS and the foreign binaries. This translator can be a virtual machine (emulator) or it can be a compatibility layer. For PC games, compatibility layers are preferred due to faster performance and lighter resource usage. WINE (acronym: Wine Is Not an Emulator) is a layer that adds interoperability between Unix-likes and programs compiled for Windows. It can be used on its own, or through a third-party manager.

Choosing

Wine managers

A manager in the context of Wine is a graphical frontend designed to organize multiple wine versions, configure their settings, enable/disable optional features, and launch applications.
Without a manager, much of your interaction with wine would be from the command line.

Lutris ⭐ best for beginners A game library manager designed to unify all of your games under one user interface. Source Code Large userbase meaning you're more likely to find help Some options hidden from users and spread out across many disparate menus	Heroic A slick game launcher focused on appearance and usability. Source Code Most menus are organized neatly into a single tabular column Only Wine-GE and Proton-GE runners available
Bottles A minimalist app for managing wine runners and "bottle" profiles (wine prefixes). Source Code User interface is simple and easy to navigate Has a CLI tool for running commands inside specific bottles Distributed as Flatpak, but other builds are available from some repositories	Steam Official client for the Steam storefront, maintained by Valve. Closed Source Automatic updates for Touhou games and the Proton runner DRM embedded in games, which will cripple many Touhou mods (vpatch, thprac) No derivative runners available (Proton GE not included)
– none – Use wine as the developers intended: through your terminal emulator. Great for players who prefer to launch games using shell scripts Some utilities and frameworks may need to be installed manually

Wine runners

A runner in the context of Wine is the engine your OS uses to interpret Windows executables. Most runners today are based on the WINE project maintained by WineHQ.
Proton, CrossOver, Soda, and other names are all derivative variants (forks) of Wine.

Wine The original Wine! Development has come a long way, but there are still loads of issues. Source Code Can easily be installed as a stand-alone runner through popular package managers Mono must be installed separately Problems with full-screen mode and many other oddities	Proton A fork of Wine built specifically for the Steam* client, tailored for gaming. Source Code Steam can easily install proton for you if games require it Numerous Wine issues are fixed
Wine-GE (deprecated) A modified version of Proton Experimental, made for non-steam games. Source Code Works well with wine managers such as Lutris	Proton-GE A modified version of Proton Experimental, made for Steam* games. Source Code *Proton and Proton-GE can be used to run games outside of Steam if run with managers such as the ones mentioned above.

Installing

Wine managers

common pitfalls

For Linux novices, I would discourage installing wine-related software through Flatpak; its runtime environment introduces exotic issues that are tough to troubleshoot. Due to the way applications are sandboxed, Flatpak-based managers and runners may not work properly on some distros. But if you know what you're doing, feel free to give Flatpak a try.

Lutris

Lutris is a beginner-friendly game library manager. It provides a graphical interface for configuring wine runners. This manager comes with many wine mods pre-installed, which can be enabled/disabled for individual games.

Lutris supported platforms

Linux
Solus Gentoo Mageia openSUSE Slackware Clear Linux	Debian └── Ubuntu ├── Mint ├── Pop! OS └── Elementary OS	Red Hat ├── RHEL └── Fedora └── Nobara	Arch ├── Manjaro └── SteamOS	* └── Flatpak

Lutris installer scripts

Users can install Touhou games using YAML or JSON files, which Lutris interprets as runnable scripts.

Requirements:

• original game files from the installation disk or an ISO image
• an internet connection to download thcrap and patches

Script types:

• vt = vsync mod and translation patches (vpatch + thcrap)
• vtp = and custom practice mode (vpatch + thcrap + thprac)

1 – 5	6 – 9	9.5 – 12	12.3 – 13.5	14 – 15.5	16 – 18	18.5 – now	other
TH01	TH06 vt	TH09.5	TH12.3	TH14	TH16	TH18.5	alcostg
TH02	TH07 vt	TH10	TH12.5	TH14.3	TH16.5	TH19	NSML
TH03	TH07.5	TH10.5	TH12.8	TH14.5	TH17	TH20	megamari
TH04	TH08 vt	TH11	TH13	TH15	TH17.5		marilega
TH05	TH09	TH12	TH13.5	TH15.5	TH18
Editor’s Note – Only a few touhou games have scripts right now. We should write more installers after integrating thprac.

If you'd like to write your own Lutris scripts, check out the official guide ➔ Writing Installers

frameworks

Mono

Mono is an open-source derivative of the .NET framework which allows your system to run programs written in C#. You need it while using the Thcrap Configuration Tool (v3) loaded by thcrap.exe for installing patches. If it's not working, you can try the old configurator written in c++: bin/thcrap_configure.exe

Wine and Mono work together to support both PE and .NET apps through the same wine command. Typically, every runner except the original Wine will have Mono already installed, meaning you can skip this step. For users who need to add it manually, I recommend installing Mono directly inside the wine prefix (not as a system package) to avoid unforeseen distro-related issues. To do this, follow the guide from WineHQ, or have the wine client install it for you, if prompted.

virtual devices

MIDI synthesizer

As many of you know, the older Touhou games let players choose between 'WAV' (PCM) and 'MIDI' arrangements of their soundtracks. In order for wine to play midi music, your system needs a physical or emulated midi synthesizer. Since most of us don't own a hardware sound module, like a Roland SC-88 Pro, we'll discuss the simplest alternative: software synthesis through soundfonts. A SoundFont is a file containing many sound samples that your virtual synth can use to vocalize midi notes; it declares how all the instruments are supposed to sound. This is necessary because the MIDI signals themselves carry no sound information.

FluidSynth

FluidSynth is a software synthesizer that converts MIDI signals to PCM audio that your computer can play. An SF2 soundfont must be supplied by the user for this synth to produce sound. FluidSynth can be used to play individual MIDI files, but for our use-case, we wanna launch it in server mode so that wine can communicate with it.

fluidsynth -lisa alsa --gain 0.54 /path/to/your/soundfont.sf2

Now re-launch your game and the MIDI playback should work (hopefully).

SoundFonts

Users have a lot of options to choose from. If you want to stay true to ZUN's musical intent, you'll probably want a font that mimics some model of Roland Sound Canvas. Here's the ones we've tested:

HiDef by stgiga

• close (but not perfect) imitation of an SC-88 Pro; sounds better in some cases
• massive size, will consume over 4 gibibytes of RAM when loaded
• some instruments don't sound as plucky as they should be

Building

One of the struggles of being a Linux user is that developers often choose not to publish software builds for your OS. This means you have to compile those programs yourself from source code, or run their windows-native binaries through wine. But running everything through a compatibility layer is usually not ideal, especially for command line tools. If source code is available, it's worth the effort to compile certain programs yourself for whatever *nix you're using.

Touhou Toolkit

thtk is a suite of CLI utilities for decoding and remaking various game assets from the Touhou Project.

making

git clone --recursive https://github.com/thpatch/thtk.git thtk_source  # download the git repo and any submodules
cd thtk_source                                                         # navigate to the repo's directory
date=$(git show -s --date=format:'_%Y-%m-%d' --format=%cd)             # (optional) include commit timestamp in final name
mkdir build && cd build                                                # make a build folder and switch to it
cmake .. -D CMAKE_INSTALL_PREFIX=../../thtk$date                       # generate makefiles (and choose where thtk gets installed)
make && make install                                                   # compile program using makefiles

• If everything worked, a new folder thtk_YYYY-MM-DD should appear, in which you'll find

1. the executables inside bin/
2. the shared libraries inside lib64/
3. the manuals inside share/man/man1/

• Now, if you want to run the toolkit from anywhere

1. add thtk's bin folder to your PATH
2. add thtk's lib64 folder to your LD_LIBRARY_PATH

• Older versions of thtk may not compile with the most recent libraries

1. don't git checkout thtk release 12 for compiling
2. use the latest commit from the master branch

using

• If you see lots of � symbols (mojibake), convert the tool's output to UTF-8 using iconv
• The following examples are use-case specific and not sufficient for learning the toolkit itself.

thmsg -d7 msg1.dat | iconv -f ms932 -t utf8   # change thtk's output to something your terminal can display
iconv -f utf8 -t ms932 msg1.utf8 > /tmp/m && thmsg -c7 /tmp/m msg1.dat  # recompile from UTF-8 encoded file

Managing

Steam

integration

There are some problems initially when running Steam games directly through thcrap. Most players launch their patched touhous through auto-generated desktop shortcuts, which have a few disadvantages.

1. Steam's PLAY button is not configured to use thcrap patches
2. Player status won't show as "In-Game"
3. User's play time is not tracked by Steam

Steam wrapper for thcrap

The most elegant solution we've seen so far is tactikauan's thcrap-steam-proton-wrapper. It works by refactoring the game's launch options to include thcrap with any patch you like. It even installs thcrap and thprac for you.
Unfortunately, this wrapper does not work properly on some distros right now.

It may not work on:

Steam client from RPM Fusion

Running

launching games, tools, and updates

command line usage

These instructions are for standalone Wine installations (non-Lutris).

please note

• the following commands must use Unix-style paths
• each /path/to/ is a placeholder for where you installed the software
• XX represents the numeral of the touhou game, such as 07

launching Japanese (possibly non-Unicode) programs

LANG=ja_JP.UTF-8 wine start /unix /path/to/touhou/thXX.exe              # touhou game
LANG=ja_JP.UTF-8 wine start /unix /path/to/touhou/vpatch.exe            # vsync patch
LANG=ja_JP.UTF-8 wine start /unix /path/to/touhou/kouma_update102f.exe  # ZUN's update

working with thcrap

wine /path/to/thcrap/thcrap.exe                              # launch the configurator
ls -1 --ignore={games.js,config.js} /path/to/thcrap/config/  # show all installed patch stacks

launching through thcrap with English patch stack applied

• language patches have names beginning with ISO 639 language codes
• you can't load a patch stack unless all of its dependency patches have been installed by the configurator—the loader won't auto-install them

LANG=ja_JP.UTF-8 wine /path/to/thcrap/thcrap_loader.exe en.js thXX                        # main game (games.js form)
LANG=ja_JP.UTF-8 wine /path/to/thcrap/thcrap_loader.exe en.js /path/to/touhou/thXX.exe    # main game (absolute form)
LANG=ja_JP.UTF-8 wine /path/to/thcrap/thcrap_loader.exe en.js thXX_custom                 # options panel (games.js form)
LANG=ja_JP.UTF-8 wine /path/to/thcrap/thcrap_loader.exe en.js /path/to/touhou/custom.exe  # options panel (absolute form)

Fixing

usability

games not recognized by thcrap

While installing thcrap patches using the latest Thcrap configuration tool, some users are unable to add their games to the list. Typically, those users reach the Find games step, choose Find games in a specific folder..., and select the folder with all their games in it. In this scenario, the tool might not detect any of the games.

In wine, there is a subtle issue with how folders are searched recursively. If the game files are in a subfolder of the user-selected folder, the configuration tool may fail to search that subfolder, never finding the games.

— Easiest Fix —

Users could add each game folder one-by-one during the Find games phase. For this to work, each selected folder must directly contain the game's executable (.exe) files.

text

tofu ⍰⍰⍰⍰

Many players have noticed box-like symbols appearing in some parts of their translated games. These strange rectangles replace individual characters in text. They often look like this ⎕ but are known to have other allographs. Some fonts represent this glyph with a ? or an X inside, while others leave the frame hollow. It is formally known as the .notdef glyph, but most people call it tofu.

Learn more ➔ Fonts

— Easiest Fix —

Install cjkfonts using winetricks. Also, make sure Japanese locale is enabled for Wine.

— Other Fixes —

Font-link specific fonts to restore missing glyphs ➔ Font Link Tofu Fix

mojibake “Œ•û

When running Touhou games, installers, updaters, or reading text files, players may discover that some (or all) Japanese text is replaced by a variety of unintelligible symbols that spell out gibberish. These types of glyph transformations are referred to as mojibake.

Learn more ➔ Encoding

— Easiest Fix —

Set your locale to Japanese. Also, make sure this locale uses the UTF-8 encoding.
Note: this solution won't work outside of Wine.

— On Linux —

Check if your system supports the correct Japanese locale:

$ locale -a | grep ja_JP

If you don't see anything resembling ja_JP.utf8 then you should install this locale.
Finally, make sure this locale used when running Touhou games and installers through wine.

Environment Variable: LANG=ja_JP.UTF-8

graphics

full-screen not upscaling [unsolved]

When full screen is selected in game settings, players expect the game's interface to resize to the full resolution of their monitor. This does not happen with some wine runners; the game window looses its border decorations, but does not scale in resolution.

At first, it seemed to be an XWayland issue, but thurther testing from users undermined this theory. We don't know yet what causes this glitch on some systems.

performance

stages running at 40fps [unsolved]

Once in a while, some stages (and their replays) inexplicably run at a lower frame-rate for the entire scene, fluctuating around ~40 FPS. Such stages often have noteworthy geometric features, like an infinite flight of stairs in th07. It is currently unknown what conditions trigger such frame-drops; they may periodically occur without any changes to game settings.

sound

distorted audio [unsolved]

In some situations, players have noticed that the in-game audio quality has inexplicably deteriorated. Also, on some wine runners, there are momentary hiccups in the music a few seconds after Touhou games start.

MIDI not playing

Most distros don't enable virtual MIDI synthesis by default. If you're not using a hardware sound module, you'll need additional software to generate sound from midi sources. In case you haven't already, read this guide's MIDI section. The Wine devs explain that if midi playback works on you host system, it should work for applications running in wine too.

system

thcrap-loader "zombie" process

The thcrap_loader.exe starts running by design every time you launch a game through thcrap. After quitting the game, users have observed that the loader does not terminate and remains in the process table. This is a known bug that affects all versions of Wine and Proton. While technically not a zombie process, it's just as sneaky, eating more system resources with each successive game session.

— Easiest Fix —

Use the following command to manually kill all remaining thcrap processes:

$ killall -q thcrap_loader.exe

— Bug Info —

thcrap issue #156 #251

Troubleshooting

game crashes

• Is your wine version older than 2021-08-30?

Update your wine runner to the latest stable release

• Have you placed any DLL files in the thcrap root folder?

Remove them

They enabled a workaround for an old issue that's no longer relevant

• Are you using a custom (non-distro) kernel?

Ensure the kernel was compiled with CONFIG_CROSS_MEMORY_ATTACH enabled

Thcrap requires this feature to access the game executables' memory for patching

Finding Help

If you've read this far into the guide, it's likely you still have unanswered questions. We do too!

where to ask

On our Discord server or IRC channel. We have members who are experienced with wine.
Please be patient and don't get upset if your question goes unanswered.
It means we haven't found a solution to your specific problem.

other guides

Touhou Wiki | Running in Linux and macOS
Visual Novel Wiki | guides for running games on multiple platforms
Thyrsus Enterprises (don't bother them) | How To Ask Questions The Smart Way