PC-98 Touhou Linux Guide

By Daichungus

Submit issues, contribute, or complain through the repo.

This is the guide for the PC-98 era games. The Windows era Touhou guide is here.

Disclaimer

This guide focuses on using DOSBox-X and Neko Project II Kai for a relatively straightforward and consistent experience.

It does not cover:

The goal here is to get most users running their PC-98 Touhou games without too much headaches.

If you're looking for more advanced or alternative methods, other resources may be better suited.

Preparing your Linux environment

Choosing a distro

Skip this section if you already have chosen your distro.

Most major distros and desktop environments should work well with this guide.

The author's only recommendation is to choose a well-known, widely-supported, and stable distro, which includes but is not limited to the following:

This guide has been personally tested by the author with the following distros:

Installing required software

Before continuing, ensure you have the necessary graphics drivers and system firmware installed.

Consult your distro's documentation or other online resources for a proper setup (e.g., RPM Fusion for Nvidia drivers on Fedora, multilib repo on Arch, etc.).

  1. Update your repository using your distro's included package manager.

    Debian/Ubuntu/Linux Mint

    sudo apt update && sudo apt upgrade

    Fedora

    sudo dnf update

    Arch Linux

    sudo pacman -Syu
  2. Install Flatpak on your distribution. If you do not wish to use Flatpak or already have it, skip this step.

Choosing an emulator

Disclaimer

There exists several emulators of the PC-98 platform, many of which work very well on Windows or older hardware.

However, they're more likely to have issues and inconsistent behavior when running on Linux through Wine*, especially on certain distributions and setups.

Hence this guide will mainly cover setup of two Linux-native emulators in detail:

DOSBox-X (skip to setup)

Neko Project II Kai (skip to setup)

A list of other PC-98 emulators can be found here.

DOSBox-X setup

Installation

Install DOSBox-X through your package manager

Flatpak

Recommended option for most users*

flatpak install flathub com.dosbox_x.DOSBox-X

Debian/Ubuntu/Linux Mint

sudo apt install dosbox-x

Fedora

sudo dnf copr enable rob72/DOSBox-X
sudo dnf install dosbox-x

Arch Linux

git clone https://aur.archlinux.org/dosbox-x.git
cd dosbox-x && less PKGBUILD
makepkg -si dosbox-x

* The Flatpak version helps avoid most inconsistencies between distros and will always be the most up-to-date version, at the cost of taking up more storage and less file permissions by default.

Settings to adjust before playing

Configuration file

DOSBox-X relies on a configuration file to apply the correct settings for various types of programs.

By default, DOSBox-X uses its own config file located at:

If the working directory contains a file named dosbox-x.conf, the settings that it contains will override the respective ones in the default config file.

As such, a ready-to-use config file is available for you to download; Simply save it to the same directory as your .hdi files.
It is recommended though, that you look at the contents of it to have a basic understanding of what settings are applied.

If you prefer writing your own config file or directly editing the main config file, continue to the next sections.

Otherwise, download a font to the directory, then start running the games.

Working directory

The working directory is where DOSBox-X will run. By default, DOSBox-X will ask you to choose a directory in your system.*

If you intend on using DOSBox-X only to play the PC-98 Touhou games, set the directory with the .hdi files as the default working directory in the default config file 

[dosbox]
working directory option = default
working directory default = /your/path/to/pc98touhou/

* If ran from the desktop. If it was ran in the terminal, DOSBox-X uses the current directory as the working directory.

Graphics

To always start in fullscreen, set:

[sdl]
fullscreen = true
fullresolution = desktop

To ensure the graphics stay consistent, set:

[sdl]
output = openglpp

[render]
aspect = true
aspect_ratio = -1:-1

Enabling PC-98 mode

To always enable PC-98 mode, set

[dosbox]
machine = pc98

Keyboard

Some DOSBox-X packages (such as the Fedora COPR build) may not enable US keyboard layout in PC-98 mode by default, as the PC-98 was originally meant to be used for Japanese keyboards.

This guide assumes most readers are using a US or similar keyboard layout.

If your DOSBox-X package does not enable the US layout by default (check in the default config file), and you're using a US layout or similar, set 

[pc98]
pc-98 force ibm keyboard layout = true
pc-98 force JIS keyboard layour = false

in either the default config file, or the provided dosbox-x.conf file.

CPU speed

The default CPU cycle count (3000) is too low for the Touhou games, resulting in extremely slow gameplay.

For a consistently smooth experience,* set

[cpu]
cycles = 74000

If your hardware allows it,† set

[cpu]
core = dynamic_x86

* In testing, most values between 10000 and 100000 worked well for the Touhou games. 74000 is suggested in this guide for most systems.

† DOSBox-X used less of the CPU compared to "Normal" during testing by the author with the same number of cycles.

Auto-execution

This is especially helpful if you intend on always using only one .hdi file* and do not want to always type the commands by hand every time you start DOSBox-X.

[autoexec]
IMGMOUNT C TOUHOU.HDI
BOOT C:

(Substitute TOUHOU.HDI with the actual name of your .hdi file.)

* For example, an .hdi with all the PC-98 Touhou games or a full system

Neko Project II Kai setup

Installation

There are many different ways to have NP21kai installed to your system.

RetroArch

You may want to familiarize yourself with the RetroArch standard keyboard bindings before continuing to this section.

  1. Install RetroArch. Choose the version that suits you the most.

    This guide recommends the latest stable version for most users for consistency and ease of use.

  2. Run RetroArch either by GUI or in the terminal.

    Flatpak

    flatpak run org.libretro.RetroArch

    Non-Flatpak

    retroarch

  3. If you installed RetroArch through your distro's package manager, follow the next set of instructions. Otherwise you can skip this part.

    1. In "Settings" → "User Interface" → "Menu Item Visibility", set Show 'Online Updater' and Show 'Core Downloader' to ON.

    2. Close RetroArch (Esc key twice), then navigate to ~/.config/retroarch.

    3. Edit the following settings in retroarch.cfg, as this will allow you to install cores without requiring root privileges. 

      libretro_directory = "~/.config/retroarch/cores"
      libretro_info_path = "~/.config/retroarch/cores/info"

    4. Launch RetroArch again and continue with the following steps.

  4. In the Main Menu, select (Enter/Return key) "Load Core", then "Download Core"

  5. Scroll down the list to NEC - PC-98 (Neko Project II Kai), then select to install it.

  6. Adjust settings before playing

AUR package (Arch Linux)

If you're new to Arch, please consider first reading the Arch Wiki article on how to install packages from the AUR, along with the article on makepkg.

  1. Install gtk2 from the AUR

    git clone https://aur.archlinux.org/gtk2.git
    cd gtk2 && less PKGBUILD
    makepkg -si gtk2

  2. Clone the np21kai repo from the AUR

    git clone https://aur.archlinux.org/np2kai-git.git

    Check the PKGBUILD for security, and modify the CMake flags if desired. *

    cd np2kai-git && less PKGBUILD
    makepkg -si np21kai

  3. Proceed with adjusting the necessary settings.

* Currently as of writing, the PKGBUILD will create 6 versions of np21kai by default

and their SDL equivalents with the sdl prefix instead of x.

Building from source (xnp21kai)

The steps below are referenced from the original README document and the AUR PKGBUILD file.

  1. Install the required programs and libraries

    Debian/Ubuntu/Linux Mint

    Installing these libraries may cause some of your programs or dependencies to be automatically removed. Always check what packages will be installed and removed before confirmation.

    sudo apt install git build-essential cmake ninja-build nasm libx11-dev libglib2.0-dev libgtk2.0-dev libsdl2-dev libsdl2-mixer-dev libsdl2-ttf-dev libsdl1.2-dev libsdl-mixer1.2-dev libsdl-ttf2.0-dev libusb-1.0-0-dev libfreetype-dev libfontconfig1-dev libssl-dev

    Fedora

    sudo dnf group install "development-tools"

    sudo dnf install gcc-c++ cmake ninja-build nasm /usr/lib64/libusb.so SDL-devel SDL_mixer-devel SDL_ttf-devel SDL2-devel SDL2_mixer-devel SDL2_ttf-devel gtk2-devel libX11-devel fontconfig-devel freetype-devel

  2. Clone the np21kai repo

    git clone https://github.com/AZO234/NP2kai.git

  3. Navigate to the repo and prepare for building

    cd NP2kai
    sed 's|no-incompatible-function-pointer-types|no-incompatible-pointer-types -Wno-implicit-int|g' -i CMakeLists.txt

    Without the above sed command, the compiler might throw an Error 2 message, halting the build process.

  4. Create the build directory and create the CMake files.

    mkdir build
    cd build

    Default build command (X11 and SDL2)

    Recommended for most users, for simplicity ;)

    cmake . -B build -DBUILD_X=ON

    This will create xnp21kai (legacy X11 support), and sdlnp21kai (more modern version used by RetroArch).

    X11 only, no SDL

    cmake -S . -B build -DBUILD_X=ON

    Full install (X11, SDL2, i286, HAXM)

    Do this only if you want to mirror the AUR on a non-Arch distro or you want all versions, possibly for your own testing.

    You can also use this command as a reference for fine-tuning.

    cmake -S . -B build \
    -DCMAKE_INSTALL_PREFIX=/usr/local \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_MANDIR=/usr/share/man/man1 \
    -DBUILD_X=ON \
    -DBUILD_SDL=ON \
    -DBUILD_I286=ON \
    -DBUILD_HAXM=ON \
    -DUSE_X=ON \
    -DUSE_SDL2=ON \
    -DUSE_SDL=OFF \
    -DUSE_SDL_MIXER=ON \
    -DUSE_SDL_TTF=ON \
    -DUSE_HAXM=OFF \
    -DUSE_ASYNCCPU=ON \
    -DUSE_VST3SDK=OFF \
    -G Ninja

    Handy CMake flag options

    The following table contains not all, but noteworthy CMake options

    CMake flag (with -D prefix) Default value with just cmake -D BUILD_X=ON Created program(s) if set to ON Description
    CMAKE_INSTALL_PREFIX /usr/local Programs will be installed to /usr/local/bin when the install command is ran.
    The AUR installs them to /usr/bin instead.
    BUILD_X ON x* Creates X11 versions of the following programs.
    BUILD_SDL ON sdl* Creates SDL versions of the following programs.
    USE_SDL2 ON Uses SDL2 for the SDL versions of the programs. If set to OFF, uses SDL1
    BUILD_I286 OFF xnp2kai,
    sdlnp2kai     		If set to ON, creates the i286 version, which can only run 16-bit operating systems and programs.
    BUILD_HAXM OFF xnp21kai_HAXM,
    sdlnp21kai_HAXM     		If set to ON, creates a IA32 version with HAXM, which uses hardware virtualization.
    Only use this if you want to, and have an Intel CPU that supports HAXM.

  5. Build the program. Errors and warnings are normal.

    Default (faster)

    cd build/
    make -j

    Without going into build/

    cmake --build build

  6. Install the program(s) to the system

    Default (while in build/)

    sudo make install

    Without going into build/

    sudo cmake --install build
  7. Run the program, and adjust settings

    X11 version

    xnp21kai

    SDL2 version†

    sdlnp21kai

† sdlnp21kai has some differences compared to xnp21kai, but the most important are as follows:

Settings to adjust before playing

RetroArch

  1. Go back* to the previous menu and select the respective core. On the Main Menu, "Start Core" will be in place of "Load Core".

  2. Start the core without content and press F1 to open the Quick Menu

  3. Select "Core Options", and apply the following settings:

    The following two settings are required for smooth gameplay:

    Optional, but more authentic (or loud) music experience:

  4. Go back and restart the core.

  5. Install the necessary font and ROM files

* Backspace key on keyboard

xnp21kai

  1. In the menu bar, adjust these settings for a smooth experience. To apply them, hit "Reset" in "Emulator"

  2. Install the necessary font and ROM files to ~/.config/xnp21kai/

* The default multiplier of 20 should be enough for most systems, but can result in slowdowns on sections with large amount of enemies or danmaku.

† Testing by the author in xnp21kai has shown that a buffer of 100 ms or more will result in noticeable sound delay, especially for sound effects.

sdlnp21kai

The process is similar to xnp21kai, except for the following differences.

Also note that for some reason, sdlnp21kai does not save its settings by default, so you may have to manually create a config folder for it.

cd ~/.config
mkdir sdlnp21kai
touch np21kai.cfg

This will also be relevant for the next section.

ROM and font files

ROM files

You may need to install some PC-98 ROM files for your emulator to work properly. These can be found elsewhere online.

Neko Project II kai and DOSBox-X both already include most of the necessary ROM files for basic operations.

For the Touhou games, you don't need to install these ROM files. However...

Font files

Both Neko Project II Kai and DOSBox-X require a font file in order to properly display Japanese characters.

Some popular font files are available to download from here:

Anex86-compatible fonts

Recommended for DOSBox-X

* The FREECG98 font does not work with Neko Project II Kai.

Neko Project-compatible fonts

Recommended for Neko Project II Kai.

Installation

DOSBox-X

If you have the original ROM files, simply copy/move them to the same directory as your PC-98 Touhou .hdi file(s).

Otherwise, DOSBox-X already includes FREECG98.BMP for convenience.

To use a different compatible font:

  1. Move/copy the file to the working directory.

  2. Edit the config file so that under the [pc98] section, pc-98 anex86 font is set to the font's filename.

RetroArch

  1. Navigate to the RetroArch system folder.

    Flatpak 
    ~/.var/app/org.libretro.RetroArch/config/retroarch/system/
    Non-Flatpak 
    ~/.config/retroarch/system/

  2. Create a directory called np2kai.

  3. Copy/move the files to to np2kai.

    If you're using a compatible font besides FONT.ROM, rename the file to font.bmp (case-insensitive).

xnp21kai

Copy/move the font and ROM files to ~/.config/xnp21kai.

If you are using a compatible font besides FONT.ROM, there are two possible options:

sdlnp21kai

Similar to the process for xnp21kai, but the directory is ~/.config/sdlnp21kai, and the configuration file is np21kai.cfg.

Running the PC-98 Touhou games

Disclaimer

This guide assumes that you have acquired your copies of the PC-98 Touhou games as .hdi or .fdi file(s)

While the author has tested running the games from the original "loose" files (such as those in the compilation disc), with DOSBox-X, most readers are unlikely to be in a similar situation.

Therefore the following sections will not cover on how to run the games from the original files.

Regardless, it is highly recommended that you store your .hdi files in a directory named "Games" or "Touhou" for ease of rememberance.

DOSBox-X

GUI/Desktop

  1. If prompted, select the directory with your .hdi files as your working directory.

  2. Wait for DOSBox-X to finish loading*, then run these two commands in DOSBox-X:

    IMGMOUNT C TOUHOU.HDI
    BOOT C:
    Substitute TOUHOU.HDI with the actual filename† of the .hdi file‡ you want to load.

  3. Enjoy!

  4. See this section for information about savestates.

    See this section on how to remove or change the .hdi file

* You should see a CLI with Z:¥> as the prompt. If not, check your dosbox-x.conf file to see that machine = pc98.

† The filename is case-sensitive!

‡ Depending on the type of .hdi file you obtained, you'll either directly boot into the game or a menu with the games listed.

Command Line

  1. Navigate to the directory folder with your .hdi(s) and config file, then run

  2. Follow the same remaining steps as above

Neko Project II Kai

RetroArch

  1. In the Main Menu, select "Load Core", then "NEC - PC-98 (Neko Project II Kai)"

  2. If it's your first time loading the .hdi file:

    1. Select "Load Content"

    2. Navigate to to directory with the file and select it

    If you have loaded the .hdi file before:

    1. Select "Playlists", then "History"

    2. Select the .hdi file, then run it.

  3. Enjoy!

  4. See this section for information about savestates.

    To remove the .hdi file, go into the Quick Menu and select "Close Content"

xnp21kai

  1. In the menu bar, select "HardDisk"

  2. Choose IDE0-0*, then "Open"

  3. Find your Touhou .hdi file and open it.

  4. Reset the emulator.

  5. Enjoy!

  6. See this section for information about savestates.

    To remove† the .hdi, simply choose "Remove" on the "hard disk" the .hdi is located in and reset the emulator.

* If only IDE0-0 or IDE0-1 is loaded, that will be the default drive. If both are loaded, xnp21kai will prompt you to choose a drive to boot after the memcheck.

† To switch to another .hdi, simply choose "Open" again.

sdlnp21kai

Similar to xnp21kai, but with the following differences

Using savestates

Savestates allow you to create a "snapshot" of your PC-98 system at any given time, so long as your .hdi file still exists in the same location as when you last used it, and there's enough open slots left.

In the context of the PC-98 Touhou games, savestates are useful for applications such as continuing where you left off in-game, or practicing certain sections.

DOSBox-X

Savestates in DOSBox-X are known to have issues, such as buggy behavior after loading.

For most of the Touhou games, the author recommends pausing the game before creating a savestate.

Creating savestates

Manual method

To create a savestate, navigate to "Capture", then click on "Save state" F12 + S

You'll be prompted to give it a unique name.*

To store more than one savestate, navigate† to an empty slot in "Select save slot" under "Capture". DOSBox-X has 100 empty slots by default.

To remove a slot's content without writing any data to it, click "Remove state in slot" under "Select save slot" after you've already selected the slot that you want to clear.

* This will overwrite all data in the current selected save slot, so make sure to navigate to the next empty slot if you want to create a separate save state.

† For faster navigation, use F12 + . for the next slot, and F12 + , for the previous slot; both are relative to the current selected save slot.

Auto-saving

DOSBox-X allows for automatic and periodic creations of savestates. This means you can have something akin to "auto-save" in most modern video games.

To start creating auto-saves, navigate to "Capture", then "Auto-save settings".

Below is a table of possible settings. Note that x, y, z are to be substituted for positive integer values.

Time interval (secs)* Start slot End slot Savestates created
0 0 0 Default setting, does nothing regardless of the value of the time interval.
z x y Iteratively create new savestates in slots x through y, inclusive, every z seconds.
If the current slot is within the range, saving will start on that slot.
z x 0 Create a savestate at slot x every z seconds.
z 0 0 Create a savestate at the current slot† every z seconds.
z 0 y Create a savestate from the current slot† to slot y, inclusive, every z seconds.

For the Touhou games, since this guide assumes most people are not directly using the original game files, we can ignore settings for individual programs.

* To reduce the possibility of your system slowing down, it's recommended that the shortest interval for general use be 60 seconds.
Please also note that this means the game will briefly pause when a new savestate is being created.

† Please ensure that you're not overwriting any slots you want to keep or manually save!

Loading savestates

Warning: Before loading a savestate, you must be currently running exactly the same game, from exactly the same .hdi file when you created that savestate.

To load a savestate, select "Load state" F12 + L on the selected slot that you want to load it from.

Neko Project II Kai

RetroArch

Savestates can be stored in up to 1000 slots.

Before loading a savestate, you must be currently running the same .hdi file that you want to load the savestate from. Otherwise you'll only see a black screen.

In-game method:

F2 to quickly create a savestate to the current slot.

F4 to quickly load a savestate from the current slot.

F6 and F7 to navigate between slots. A thumbnail of the slot's savestate will be shown for reference.

In-menu method:

Go to "Save States", then click on "Save State" to create a savestate to the current slot.

To load a savestate from the current slot, click on "Load State".

To navigate between slots, enter "State Slot" and navigate to your desired slot.

xnp21kai/sdlnp21kai

To enable savestates, add the following line to xnp21kairc (or np21kai.cfg)

STATSAVE = true

(Re)start the program. There should be a new section in the menu bar titled STAT. Under that, you can save and load two slots.

Important and useful tips

DOSBox-X

Neko Project II Kai

RetroArch

xnp21kai/sdlnp21kai

Other

Common Issues

This section is under expansion. Submit issues and fixes through the repo.

RetroArch

Flatpak version can't go fullscreen in KDE

Right click on the title bar of the window.

Go to "More Actions" → "Special Window actions".

In the new window, click "Add property" in the bottom left. Find "Fullscreen" in the list and add it.

Go back and make sure you set "Fullscreen" to "Yes".

If you have multiple monitors, and the program launches on the wrong one, you can also add "screen" property.

The changed settings can be found under System Settings → "Window Management" → "Window Rules" → Pencil icon of "Window settings for com.libretro.RetroArch".

xnp21kai

No sound

Try stopping the program and run it again. (Ctrl+C if launched from the terminal)

Can't close/freezes

Includes errors being thrown even when pressing Ctrl+C in the terminal. Unfortunately, This is arbitrary behavior that there is no exact solution to so far.

Testing by the author suggests that directly running xnp21kai from /usr/local/bin/ may solve this issue if it repeatedly happens.

Fullscreen isn't fullscreen

Unfortunately there is currently no option to scale up the display.

Additional Resources and References

Special Thanks

The author thanks the following for their support: