Skip to content

PLAY_LINUX.md

Latest commit

 

History

History
183 lines (137 loc) · 6.46 KB

PLAY_LINUX.md

File metadata and controls

183 lines (137 loc) · 6.46 KB
Raw

Download, install, and play on Linux

The native Linux reconstruction is the current playable release target. The release includes the established 32-bit x86 product and a native-layout x86_64 product; an AArch64 build is available for hardware validation. Wine, Docker, and the original th08.exe are not runtime requirements.

This is the release-package guide. The source-checkout instructions below build i386 from main; x86_64/AArch64 source builds use the 64-bit branch guide. See port scope and products for the distinction.

What you need

  • a Linux desktop with working OpenGL and audio;
  • the runtime packages listed below;
  • a legally obtained original Japanese TH08 1.00d data directory containing:
    • th08.dat
    • thbgm.dat

Supply the two DAT archives from your own game installation. The selected data directory must be writable because TH08 creates th08.cfg, score.dat, replays, screenshots, backups, and diagnostic logs there.

1. Download the portable release

Open the latest TH08 release and download the archive and matching .sha256 file for your architecture:

Host Status Archive
x86_64 / AMD64 Recommended; full-route tested th08-portable-linux-x86_64.tar.gz
i386 / 32-bit x86 Compatibility build th08-modern-linux-i386.tar.gz
AArch64 / ARM64 Experimental; real-hardware gameplay not yet verified th08-portable-linux-aarch64.tar.gz

Most Intel and AMD Linux computers should use the x86_64 package. Check an unfamiliar machine with uname -m; it normally prints x86_64, i686, or aarch64. GitHub Actions artifacts are development snapshots, while Release assets are the stable player download.

2. Install the runtime libraries

On an x86_64 Debian, Ubuntu, Kali Linux, or compatible system, install:

sudo apt-get update
sudo apt-get install \
  libstdc++6 libgl1 libfontconfig1 \
  libsdl2-2.0-0 libsdl2-image-2.0-0 libsdl2-ttf-2.0-0 \
  fonts-vlgothic

The i386 compatibility package needs the corresponding 32-bit libraries:

sudo dpkg --add-architecture i386
sudo apt-get update
sudo apt-get install \
  libstdc++6:i386 libgl1:i386 libfontconfig1:i386 \
  libsdl2-2.0-0:i386 libsdl2-image-2.0-0:i386 libsdl2-ttf-2.0-0:i386 \
  fonts-vlgothic

On a native AArch64 Debian-family system, install the same unqualified package names as x86_64. Other distributions need equivalent native packages for the C++ runtime, OpenGL, Fontconfig, SDL2, SDL2_image, and SDL2_ttf, plus a Japanese font. Install these packages before running the launcher.

3. Verify and extract the package

For the recommended x86_64 package, run these commands in the directory containing the two downloaded files:

sha256sum -c th08-portable-linux-x86_64.tar.gz.sha256
tar -xzf th08-portable-linux-x86_64.tar.gz
cd th08-portable-linux-x86_64

For i386 or AArch64, substitute the exact archive and checksum names from the table above. Do not continue if the checksum command reports a mismatch.

4. Start TH08

Pass the directory containing your original DAT archives:

./run-th08.sh "/path/to/original/TH08 directory"

For example, if the extracted package is a child of the data directory:

TH08/
├── th08.dat
├── thbgm.dat
└── th08-portable-linux-x86_64/

start it from inside the package with:

./run-th08.sh ..

The launcher resolves the path at startup. Quote paths containing spaces or non-ASCII characters.

First launch

With only the two DAT files present, the game creates its configuration, score, backup directory, and logs automatically. An existing th08.cfg is optional. On a low-resource VM without 3D acceleration, the first fullscreen FPS/vsync calibration can be slow and may temporarily look stalled.

Build and run from a source checkout

These commands apply to the i386 checkout on main, even when the host is x86_64. For a native x86_64/AArch64 build, follow the 64-bit branch procedure.

On Debian or Ubuntu, the one-command developer path installs missing build dependencies, builds the native i386 executable, and launches it:

scripts/setup-modern-linux.sh "/path/to/original/TH08 directory"

After the initial setup, use the incremental path:

scripts/play-modern-linux.sh "/path/to/original/TH08 directory"

An optional Docker environment provides reproducible builds; the resulting game runs directly on the host. See Native Linux playable reconstruction for backend architecture, build isolation, validation coverage, and porting lessons.

Troubleshooting

Run the launcher from a terminal so early errors remain visible:

./run-th08.sh "/path/to/original/TH08 directory"
echo $?

Check the executable and unresolved runtime libraries with:

file ./th08-modern
ldd ./th08-modern | grep "not found"

Runtime diagnostics are written inside the selected data directory:

  • log.txt: normal game log;
  • modern-files.txt: files requested during the current run;
  • modern-crash.txt: symbolizable fatal-signal report;
  • backup/modern-crash.txt: possible early-startup report while score backups are being rotated.

If the program exits unexpectedly, open an issue with those diagnostics, your package version, exit code, distribution, desktop session, GPU/OpenGL environment, and launch command. For a gameplay or rendering bug, include the exact stage/route, mode, difficulty, team, reproduction steps, and screenshots or video. The bug report checklist has the full format. Keep original game files private; share score files or replays when needed to reproduce the issue.

Current limitations

  • MIDI output is a compatibility stub; the normal WAV BGM path is validated.
  • Keyboard input is validated; controller compatibility is not yet a release target.
  • AArch64 has build and emulated-loader coverage; gameplay validation on a real AArch64 desktop remains pending.
  • Stage 4-to-5 dynamic-text tiling and missing enemy/boss art were observed in earlier bring-up builds, but were not reproduced in the final x86_64 full-route and Practice passes. Preserve diagnostics if either regression returns on another driver or desktop.