visualnovel:problems

GNU/Linux

If your visual novel didn’t work with Wine after following our VNs on GNU/Linux Guide, don’t give up! There are plenty more tricks you can try, depending on the issue you’re facing.

If the game won’t start at all, or you get a black screen instead of the opening movie, or the text is garbled, see our Quick Fixes section first. If you’re experiencing issues with fullscreening the game, want to resize the game window, or face other windowing issues, you need Gamescope.

This page assumes you have installed the visual novel inside the default Wineprefix Lutris creates for you, ~/Games/game-name. If your Wineprefix location is different, make sure to change that whenever a sample command specifies WINEPREFIX.

These are some quick-and-dirty fixes to the most common problems players encounter. They won't work in all cases, but they're a good place to start.

These fixes require an up-to-date version of the Winetricks script, which you can install here: https://github.com/Winetricks/winetricks#installing

Unattended Installs

We recommend using Unattended Installs when using Winetricks, as some installers will fail to work when run without this option.

You can perform an Unattended Install with winetricks -q.

You probably need to use a 64-bit Wineprefix. You can create a new 64-bit Wineprefix like this:

WINEPREFIX=~/.local/share/wineprefixes/vn64 WINEARCH=win64 wineboot

Then select the Wineprefix you just created inside of the Configuring settings in the Game Options tab for the game in Lutris.

The game likely expects Windows Media Player to be present. You can install Windows Media Player 10 in your 32-bit Wineprefix with this command:

WINEPREFIX=~/Games/game-name winetricks -q wmp10

If you're using a 64-bit Wineprefix, you need WMP11 instead:

WINEPREFIX=~/Games/game-name winetricks -q wmp11

If this doesn't work, see our section on Broken Media Playback.

Window displays Japanese text when using fakejapanese.

In the System Options tab and under the Game Execution section, add a new environment variable. Use TZ as the key and Asia/Tokyo as the value for the environment variable.

DXVK seems to be having some trouble using Vulkan to draw the game. You can try turning off DXVK in Lutris, which may result in better compatibility.

(Various Issues) Japanese Locale

Make sure you're running the game in the Japanese Locale, as this can cause text issues:

LANG=ja_JP.UTF-8 WINEPREFIX=~/Games/game-name wine <game-executable.exe>

You can also specify Japanese Locale inside of Lutris in the game's settings under the System Options tab, or globally in Lutris in Preferences.

There is currently no way to use Japanese Locale for Lutris' installer wizard.1)

Mangled Filenames

If your visual novel came from the publisher in a compressed archive with Japanese characters, the filenames may be mangled (this is called 文字化け) when you attempt to decompress it.

If it's a zip file, you can try this:

unzip -O SHIFT_JIS <game-archive.zip>

If that doesn't work, try The Unarchiver, which is in many distribution's repositories (usually under unarchiver or unar). It automatically detects and handles Shift JIS character encoding for every archive format. You can use it like this:

unar <game-archive.zip>

Text Files With Garbled Text

If your game files also came with text files that aren't displaying properly, you can convert those text files from Shift JIS to a character encoding your text editor will understand:

iconv -f SHIFT_JIS -t UTF-8 <input.txt> -o <output.txt>

In-Game Text Not Displaying Properly

You are most likely missing a font the game needs. Winetricks can fool the game into believing you have the right font installed with the fakejapanese verb. You can install it with the following command:

WINEPREFIX=~/Games/game-name winetricks fakejapanese

If this doesn't work, see our section on Japanese Characters Not Displaying Properly.

While there are several issues you might face when playing visual novels through Wine, these three are the most common.

You will need to install Winetricks before you can follow the steps in this section.

Maybe the Japanese characters in your visual novel are garbled like this:

Window displays boxes instead of Japanese text.

Don’t panic just yet—we can probably fix this. There are two likely reasons the characters are not displaying properly.

The Game is Dependent on a Microsoft Windows Font

The visual novel might want a specific Japanese font, and because it believes you’re on Windows, it assumes you have access to all these Microsoft fonts that ship with the operating system. Unfortunately, most of these fonts are only available under a non-free license, and so cannot be packaged for a GNU/Linux distribution.

That’s okay, because we can trick the game into thinking we have those fonts, when we’re actually substituting them for the freely-licensed Adobe Han Sans CJK fonts. Use the fakejapanese verb with Winetricks:

WINEPREFIX=~/Games/game-name winetricks fakejapanese

When you start the visual novel again, the fonts will most likely display Japanese characters instead of empty boxes or some nasty garbled symbols. The best part is we didn’t need to use any non-free libraries or fonts to achieve this—Winetricks just added some registry hacks to the Wineprefix. It won't be perfect as we're using a different font than the game intended, but it's better than garbled text!

Window displays Japanese text when using fakejapanese.

If the fakejapanese verb doesn’t work, see the next section.

The Characters Are Encoded in Shift JIS

Japanese characters can be encoded in Unicode (UTF-8), but they’re sometimes encoded in Shift JIS. This is an older, kludgier character encoding disliked by many, but it is widespread. While the GNU/Linux distributions we know of do not include Shift JIS support by default, you can compile locale support today thanks to HerbalNekoTea from Broken Dragon Translations.

The Broken Dragon Translations page provides detailed instructions for installing the Shift JIS locale, so we’ll leave it to HerbalNekoTea to explain: https://brokendragontranslation.com/shift_jis_linux.html

However, we recommend only attempting to acquire the Windows Fonts if using the Shift JIS locale alone doesn’t work, and don’t acquire them in the way HerbalNekoTea suggests. Please be aware that Microsoft explicitly forbids you from copying Microsoft-owned fonts to another computer.2)

Last Resort: Acquiring The Actual Fonts

It’s possible you may need to obtain the exact font the game needs for it to work. However, please be aware that Microsoft explicitly forbids you from copying Microsoft-owned fonts to another computer. You can license many Microsoft-owned fonts from Monotype, a font foundry. Once you obtain these fonts, you should install them in your Wineprefix: ~/Games/game-name/drive_c/windows/Fonts.

Broken media is the most likely affliction to affect your visual novel. The opening movie may be replaced by a black screen, although the audio might be fine. It’s possible the game will even crash, preventing you from moving on. If you’ve installed all the Gstreamer codecs available for your distribution and you’re still facing this issue, you will need to turn to Microsoft’s non-free libraries.

First, we need to understand the two main Windows Video APIs that are used in visual novels. Which API your visual novel uses is largely determined by when it was released. If it was released before 2011, it likely uses DirectShow, and if it was released after 2011, it likely uses Media Foundation.

DirectShow (Before 2011)

DirectShow (formerly ActiveMovie) was a multimedia framework designed to decode video, but came with limited codec support. It did not, for example, support popular formats like H.264 / MP4. If developers wanted to use a video in an unsupported format, they needed to acquire third-party DirectShow filters for them. That’s where LAVFilters and ffdshow came in.

These two free software libraries contained many of the filters visual novel developers wanted to use. LAVFilters has by far the larger library of filters and is more mature, while ffdshow was abandoned in 2006.

DirectShow was Windows’ main Video API until 2006, when Media Foundation was introduced. It took quite a long time, but by 2011, DirectShow was officially deprecated. Of course, that doesn’t mean developers moved to the new platform immediately after that date, either, so it's difficult to know for sure what multimedia framework a game uses based solely on the release date.

Because developers often used third-party libraries with DirectShow, we may need to install multiple components to enable full media support for DirectShow.

First, we need to to install Quartz for DirectShow support:

WINEPREFIX=~/Games/game-name winetricks -q quartz

The visual novel may work now, but if it is still facing issues decoding video, you should install either LAVFilters or ffdshow. We recommend trying LAVFilters first.

WINEPREFIX=~/Games/game-name winetricks -q lavfilters

If that doesn’t work, you can try ffdshow:

WINEPREFIX=~/Games/game-name winetricks -q ffdshow

Many games will break when these filter libraries are installed in the same Wineprefix, but some will only work when both of them are installed. You may also need to install Windows Media Player, as some visual novels expect it to be there for playback:

WINEPREFIX=~/Games/game-name winetricks -q wmp10

You may need to mix-and-match these components, but hopefully, the game will work with some combination of these installed.

Media Foundation (After 2011)

If your visual novel was released after 2011, it likely uses Media Foundation for video playback. Wine has implemented some support for Media Foundation, but it is incomplete.3)

Valve is working on improving compatibility with Steam games by transcoding the in-game videos of games to a free format that GNU/Linux distributions can easily decode, rather than bundling decoders with the Steam Runtime for legal reasons. Unfortunately, this doesn’t help you if your visual novel is not on Steam.

You may have some luck decoding these videos when you install Windows Media Player with Winetricks. If you’re using a 32-bit Wineprefix, you should install Windows Media Player 10:

WINEPREFIX=~/Games/game-name winetricks -q wmp10

If you’re using a 64-bit Wineprefix, you should install Windows Media Player 11:

WINEPREFIX=~/Games/game-name winetricks -q wmp11

You can also try installing an incomplete list of the Media Foundation DLLs with Winetricks. Microsoft does not offer some of the Media Foundation DLLs for public download, so Winetricks has no legal way to create a verb for them. You can install the publicly available libraries with the mf verb:

WINEPREFIX=~/Games/game-name winetricks -q mf

You may still get errors like this, however, and there’s not much you can do without the native Media Foundation libraries:

0140:err:module:import_dll Library mfplat.dll (which is needed by L"C:\\windows\\system32\\mfreadwrite.dll") not found
0140:err:module:import_dll Library MFPlat.DLL (which is needed by L"C:\\windows\\system32\\Mf.dll") not found

You could also try Wine-GE-Custom inside of Lutris, which includes more Media Foundation patches.

Wine has very limited support for DRM. This is the “feature” most likely to break when attempting to run a visual novel through Wine. Avoid DRM-encumbered games, because there is no legal way to get them to work in most cases. Most digital releases from Japanese publishers are encumbered by DRM, so we recommend buying physical releases, although not all physical releases are DRM-free, either.

There is, however, an easy restriction to bypass; the type that checks whether you’re running the Japanese version of Windows:

Window displays Japanese text when using fakejapanese.

All you need to do is set this environment variable when launching the game: TZ=Asia/Tokyo.

Our Buying Guide exhaustively lists DRM-free publishers, so we recommend reading it before making a purchase. Unfortunately, Japanese publishers rarely identify whether their physical releases are encumbered by DRM, but there are two sites that document DRM in releases. VNDB lists the type of DRM, if any, a game is encumbered with. It indicates DRM status for releases in all languages. You can easily filter for DRM-free releases.

Seiya-Saiga.com has a large list of physical Japanese releases with their DRM status and started tracking DRM long before VNDB, so is currently more comprehensive. The site indicates whether the game can be played “ディスクレス” or not. If the answer is “可”, then the game either does not come encumbered by DRM, or the publisher has provided a DRM-removal patch, as in the case of August with Aiyoku no Eustia. The answer you want to look out for is “初回のみ不可” and similar wording, which means it performs a DRM check to ensure the disk is in the drive on first startup. Most disk-checking DRM does not work in Wine.

If you already have a visual novel encumbered by DRM, and it isn't identified on VNDB, see if you can identify your DRM below:

Disk-Checking DRM

The physical releases of some visual novels are encumbered with disk-checking DRM. This type of DRM checks whether the disk is in the disk drive on first launch before permitting the customer to play the game. These are the disk-checking DRM implementations we know about:

Name Status Workaround
AlphaROM Doesn’t workGo to the SETTEC site and enter your serial key. They’ll provide a .sig file you need to place in the same directory as the game executable.
Siglus EngineUnknown  

Activation DRM

Many digital vendors require you to “activate” the game before you can play it. This may involve logging in or entering a valid serial number.

Name Status Workaround
PlayDRM (DLsite) Works  
SoftDenchi (DMM, DLsite)Doesn’t work 
DMM Game Launcher (DMM) Doesn’t work 
Buddy Launcher (DMM) Doesn’t work 
Generic Disk Checking DRM Fix

It's sometimes possible to bypass disk-checking DRM by creating an ISO copy of the game disk in your drive and load it with CDEmu. One way to create such an ISO is using GNOME Disks.

You then need to load the disk file with CDEmu. With any luck, the game will detect that the disk is present and let you play the game. Some information on how to start working with CDEmu can be found here.

It’s common for visual novels—particularly old ones that support a maximum of 800×600 resolution—to fail when fullscreening the game. It could give you a fullscreen window, but with 80% of the screen black and the actual game only a small square in the top left. And if you can’t fullscreen the game, there’s nothing you can do, because you can’t resize the window. Or it could succeed, but change your desktop’s overall resolution to 800×600. The game might crash when you switch virtual desktops. You might not be able to move the game window at all!

Try Gamescope. It’s a micro-compositor developed primarily by Joshua Ashton, Simon Ser for Sourcehut, and Pierre-Loup A. Griffais for Valve. Gamescope works inside of an X11 or Wayland session. It gives you much finer control over the game, allowing you to resize the window at will and fullscreen the Gamescope compositor without affecting your desktop.

Windowing and focus issues tend to disappear once you start using Gamescope. Instead of fullscreening the game, you’re fullscreening the compositor. Games won’t behave strangely when you switch workspaces anymore, because Gamescope behaves as if you’re still focused on the game.

Gamescope can be installed as a Flatpak package, which can integrate with the Flatpak versions of Lutris and Bottles:

flatpak install com.valvesoftware.Steam.Utility.gamescope

If you don't want to use Flatpak, some distributions provide an official package, but others do not. If they don't, you will need to build Gamescope—the build instructions are here: https://github.com/ValveSoftware/gamescope#building

You can easily enable Gamescope in Lutris by going to System Options for the game and clicking Enable Gamescope. If you don't want to start the game in fullscreen, click Advanced at the top of the window and change the Window Mode.

You can also use it in Bottles by clicking on Settings and enabling Gamescope. Gamescope can be configured by clicking on the cog icon.

This is the syntax for using Gamescope in the Terminal:

gamescope -- wine <game-executable.exe>

You can fullscreen the Gamescope compositor (and your game) with SUPER+F, but there is a bug on GNOME that requires you to use the ALT key with all Gamescope shortcuts. If you want to fullscreen Gamescope in GNOME, you need to press SUPER+ALT+F.

Gamescope can also upscale games on AMD (toggle FSR with SUPER+U or -U) and NVIDIA (toggle NIS with SUPER+Y or -Y) GPUs. Upscaling is the process of redrawing the game’s frames at a higher resolution while attempting to maintain the same quality.

Don’t bother with virtual desktops—just use Gamescope!

Wine is a large project that re-implements many Microsoft Windows libraries and APIs across many different layers, but they’re all connected to each other. If one link in the chain is broken, that can be enough to stop the game from working. To fix that layer, we need to understand how it works.

Once we understand how it works, we need to find out which non-free library our game requires and override the builtin Wine component with it.

The following section is a brief overview of the layers relevant to visual novels.

Direct3D Compatibility

Whenever game developers need to draw something on the screen in Windows, they need to use a graphics API like Direct3D, which is what most visual novels use. Wine has built-in compatibility for every version of the Direct3D API with their WineD3D and VKD3D renderers, so it will support a lot of Direct3D games by default.

DXVK is an alternative implementation for several newer Direct3D APIs and has better compatibility and performance in most cases, so we recommend installing it.

What’s The Difference Between WineD3D, VKD3D, and DXVK?

WineD3D works by translating the game’s Direct3D API calls to OpenGL calls. OpenGL is a graphics API that supports Linux and many other operating systems. OpenGL was superseded by the Vulkan API in 2016. VKD3D is another part of the Wine project that translates D3D12 calls to Vulkan.

WineD3D has great compatibility for older versions of the Direct3D API, but DXVK is a better option for newer versions. DXVK is another implementation of D3D9, D3D10, and D3D11 developed independently from the Wine Project. DXVK translates Direct3D calls to Vulkan. Vulkan offers better performance than OpenGL, especially for newer games.

There is ongoing work to provide an alternative Vulkan translation layer in WineD3D for newer Direct3D versions,4) but DXVK’s implementation is more mature in most cases.

WineD3D targets compatibility for all types of Windows software, while DXVK targets compatibility and performance for games. DXVK’s D3D10 and D3D11 implementations are generally much better than WineD3D’s, but WineD3D’s D3D9 implementation is currently more compatible than DXVK’s equivalent.

VKD3D-Proton is Valve's fork of VKD3D, the Wine project's D3D12➜Vulkan translation layer. VKD3D-Proton has support for more features in D3D12 and has better performance than VKD3D. Neither of these translation layers are as mature as those available for D3D11 and older. Some games can fallback to D3D11 rendering. We recommend choosing this option when available.

Getting DXVK

You’ll need to install vulkan support for your distribution first. We recommend using Lutris, as it bundles DXVK with its runtime and allows you to easily toggle it off.

Alternatively, if you want to install the latest release of DXVK in your Wineprefix, Winetricks is the easiest way:

WINEPREFIX=~/Games/game-name winetricks dxvk

Note: If you install DXVK with Winetricks, it will not prompt you to update the DLLs when there is a new release of DXVK. It will also not allow you to update it if you execute the verb normally. You need to run Winetricks with --force to force Winetricks to install the newest version of DXVK:

WINEPREFIX=/Games/game-name winetricks --force dxvk

You can also manually install DXVK using the official install instructions.

.NET Framework Compatibility

If your game relies on Microsoft’s .NET Framework, Wine will prompt you to install Wine Mono5), which is a cross-platform and free software implementation of the .NET Framework. In most cases, Wine Mono will work perfectly fine for visual novels. If you’re experiencing issues related to .NET, you can try installing the right dotnet verb with Winetricks.

Visual C++ Compatibility

Wine has implemented enough of the Visual C++ libraries to support most visual novels. However, Wine has not implemented MFC6), so in the unlikely event a visual novel requires this library, you will need to use the native non-free library, which you can install with Winetricks.

If a game requires special configurations that might break other games, you should create a dedicated Wineprefix for it in the game directory. To create a Wineprefix called .vncompat inside the game directory, you can use the $PWD variable, which will expand to the full directory path of the directory you're currently in.

Make sure you run this command once you are in the game directory!

WINEPREFIX="$PWD/.vncompat" wineboot

You can then apply the configurations to this Wineprefix.

Non-free libraries are also called “native” DLLs, in comparison to the re-implemented DLLs provided by Wine, which are referred to as “builtin” DLLs. If your program complains about lacking mfc90.dll, you can override the builtin DLLs from Wine with the native DLLs from the non-free Visual C++ 2008 Libraries released by Microsoft.

The easiest way to install non-free libraries is with Winetricks.

You can see a full list of the DLLs Winetricks can install with:

winetricks dlls list

To install non-free libraries selectively, you need to understand the errors you’re receiving. If you’re using Lutris, you need to go into Show Logs when running the game. If you’re running Wine from the terminal, it will provide output by default.

The output may contain an error like this:

err:module:import_dll Library mfc90.dll (which is needed by L"C:\\Program Files\\Chem3D\\Chem3D.exe") not found

The important thing to notice is the mfc90.dll part. Because Winetricks lists the DLLs each verb provides, we can filter the output easily:

winetricks dlls list | grep -i mfc90

We can see it’s part of the Visual C++ 2008 Runtime:

vcrun2008                Visual C++ 2008 libraries (mfc90,msvcp90,msvcr90) (Microsoft, 2011) [downloadable,cached]

So let’s install that:

WINEPREFIX=~/Games/game-name winetricks -q vcrun2008

We recommend always specifying the -q option when installing a Winetricks verb, as the installation will more reliably complete successfully when run silently.

Now you can try running the visual novel again in this Wineprefix, and hopefully the non-free library will be agreeable to the game.

If you need more advanced logs, see WineHQ's page on Debug Channels.

Advanced: Debugging & Recovering a Wineprefix

Winetricks provides the alldlls verb, which can be set to default or builtin. Normally, you would never need to touch this verb, but if you manage to break your Wineprefix or need to compare between Wine’s builtin DLLs and the native DLLs you installed with Winetricks, this verb can be useful.

alldlls=builtin will tell Wine to use builtin DLLs where possible. Wine does not provide a replacement for every DLL Winetricks installs, so Wine will still use the native versions of those DLLs.

alldlls=default will remove all DLL overrides, completely deleting the registry key. You might use this if you wanted to completely reset the Wineprefix. This won’t be as complete as starting again with a clean Wineprefix (which we recommend), but it’s as good as you’re going to get. You can then selectively add DLL overrides back with winecfg in the Libraries tab.

More Tricks

Wine doesn’t apply anti-aliasing to fonts by default. To improve the look of fonts, Winetricks can install a small registry file which enables anti-aliasing with the fontsmooth verb:

WINEPREFIX=~/Games/game-name fontsmooth=rgb

You can also prevent Wine from hijacking your file associations with mimeassoc:

WINEPREFIX=~/Games/game-name mimeassoc=off

You can prevent your WINEPREFIX from accessing your home directory with isolate_home:

WINEPREFIX=~/Games/game-name isolate_home

For more tricks, run winetricks settings list.

This section will detail some more game-specific fixes you may need to make to get things working. Generally speaking, it may be best to generate a wineprefix specifically for these games so their settings don't break other games.

This game needs the japanese only and garbled text fixes

Can’t Select Menus With Cursor

When running Hatsuyuki Sakura with WineD3D, you won’t be able to select any of the options to start the game! Running the game with DXVK will fix this issue. The easiest way to use DXVK is through Lutris.

Crashes When Trying To Play Opening Movie

This visual novel will only work in a 64-bit Wineprefix with Windows Media Player 11 present—preferably in its own Wineprefix.7) Don't use a 32-bit Wineprefix; install the game in a new, separate 64-bit Wineprefix. Use Winetricks to install Windows Media Player 11 in your new Wineprefix.

You can create a new 64-bit Wineprefix like this:

WINEPREFIX=~/.local/share/wineprefixes/suteki64 WINEARCH=win64 wineboot

Then install WMP11:

mkdir -p ~/.local/share/wineprefixes && WINEPREFIX=~/.local/share/wineprefixes/suteki64 winetricks -q wmp11

The video still won't play, but it won't crash anymore.

These games needed fjfix to launch before this game-breaking bug was fixed in Wine 7.10. Wine 8 and later versions should work with Sono Hanabira games out of the box.

Every game by Silky's Plus is encumbered with some form of Disk-checking DRM at install. It's possible to get these games to install through Wine using this fix.

I encountered serious difficulty trying to get the 32-bit executable to run, luckily this game also ships with a 64-bit executable. (cmvs64.exe and cmvsConfig64.exe)

Muv-Luv will not boot if you are missing mfc140u.dll, which you can rectify with

WINEPREFIX=$PWD/.vncompat WINEARCH=win32 LC_ALL=ja_JP.UTF-8 winetricks mfc140

Microsoft Windows

The first thing you should do, before even installing a visual novel originally written in Japanese, is to change your system locale to Japanese.

Some visual novels are a little more finicky, and may require you changing your timezone to JST.

Older visual novels may require you to use a combination of compatibility mode as well as needing to be run in administrative mode. You'll also want to avoid installing them to C:/Program Files (x86)

For some games, it may be required that your installation be pure Japanese (eg, just setting locale won't work). It might be best to use a virtual machine for this kind of game.

None currently known, perhaps you can contribute?


1)
We've merged a patch for this issue which will likely make it into the 5.14 Lutris release: https://github.com/lutris/lutris/issues/4935
3)
Some Media Foundation support was landed in 2020, but as of July 2023, Wine’s MFPlat.dll implementation is missing roughly half the features: https://source.winehq.org/WineAPI/mfplat.html
4)
To enable the Vulkan renderer backend in WineD3D for D3D9/10/11, you need to set the registry key renderer=vulkan. You can also do this using winetricks with winetricks renderer=vulkan.
5)
The WineHQ wiki has an article about Wine Mono with more information: https://wiki.winehq.org/Mono
6)
You can see what Wine has implemented here: https://source.winehq.org/WineAPI/
7)
You will definitely want a custom wineprefix for this, WMP is known for breaking video playback in various interesting ways
  • visualnovel/problems.txt
  • Last modified: 2024/01/31 09:54
  • by neo