Skip to content
BranchesTags

Repository files navigation

DOSKUTSU

Quickstart | Status | Requirements | Download | Usage | Building | How It's Developed | Components and License

DOSKUTSU is a faithful port of Cave Story (Doukutsu Monogatari) to MS-DOS 6.22 on retro Pentium-class hardware. It plays Daisuke "Pixel" Amaya's 2004 freeware classic on real 1990s-era PCs via SDL3's DOS backend, DJGPP, and CWSDPMI.

The name is a portmanteau of DOS and Doukutsu Monogatari (Cave Story's original Japanese title).

DOSKUTSU exists for preservation and the engineering challenge of running Cave Story on a 1990s MS-DOS PC.

This project was 100% built agentically using Claude Code.

Screenshots
DOSKUTSU title screen running in DOSBox-X First lab room with Quote and the broken teleporter
Title Screen First Lab Room
First Cave with Quote, HUD, and a Heart pickup SETUP.EXE main menu with detected system profile
First Cave SETUP.EXE

captures from DOSBox-X running DOSKUTSU.EXE and SETUP.EXE

Demo

Cave Story running on DOS (DOSKUTSU) -- watch on YouTube

DOSKUTSU running on Gateway 2000 reference hardware

Quickstart

  1. Get the binaries. Build from source or download the latest doskutsu-<version>.zip release and unzip it.
  2. Add game data. DOSKUTSU ships no Cave Story content. See ASSETS.md for details.
  3. Copy the folder containing binaries and assets to a DOS system, or mount it in DOSBox-X.
  4. Configure sound. Run SETUP.EXE to auto-detect sound cards or manually configure.
  5. Play. Run DOSKUTSU.EXE from the game folder.

See Download, Game Assets, Building, Usage, Configuration for details.

Status

Features

  • DOSKUTSU plays the full game, start to finish
  • Sound Blaster, AdLib, OPL3 FM, WaveBlaster, General MIDI, Gravis UltraSound, and PicoGUS sound support
  • Original Organya soundtrack or MIDI music with selectable arrangements (see docs/SOUND.md)
  • Gameport joystick/gamepad support and input remapping
  • DOS-era like SETUP.EXE configuration utility
  • Up to ~33fps (depending on CPU and bus bandwidth)
  • TAS support (see docs/TAS.md)

Frame rate depends on CPU, video card, and audio backend. Figures below are real-hardware measurements from an identical 102-second replay:

CPU Frame rate Best configuration
Pentium OverDrive 83 ~33 fps AdLib + S3 ViRGE
Am5x86-133 ~33 fps AdLib + S3 ViRGE
486DX2-66 ~25 fps AdLib + S3 ViRGE
486DX2-50 ~19 fps AdLib + S3 ViRGE, choppy

docs/BENCHMARKS.md is the full report: 157 cells across two measurement rounds, four CPUs, three video cards, and three sound cards, with charts, method, and raw logs.

Cave Story runs at 50 fps natively; on this hardware it renders at up to ~33 fps, but Fixed-Timestep mode keeps game logic advancing at the correct 50 Hz regardless of render rate.

See the changelog for development and progress details.

Requirements

Recommended

  • CPU: Pentium 75 MHz or faster
  • RAM: 32 MB
  • Video: VESA 1.2+ with 320x240 support
  • Sound: Sound Blaster 16 or compatible; AdLib/OPL2-only and Gravis UltraSound (or PicoGUS) cards also supported
  • OS: MS-DOS 6.22 or compatible
  • Disk: 10 MB free

Minimum

  • CPU: 486DX2-66 with FPU
  • RAM: 16 MB
  • Video: VESA 1.2+
  • Sound: Sound Blaster 16 or compatible; AdLib/OPL2-only and Gravis UltraSound (or PicoGUS) cards also supported
  • OS: MS-DOS 6.22 or compatible
  • Disk: 10 MB free

Fixed-Timestep mode

Cave Story's engine ties game logic to the render rate, so at 30 fps it also runs at ~60% speed. Fixed-Timestep mode decouples the two: logic advances on a fixed 50 Hz clock regardless of frame rate, so the game plays at its intended speed even with fewer frames drawn. Motion is less smooth; speed is correct.

On by default; set SDL_HINT_DOS_FIXED_TIMESTEP=0 for the legacy frame-coupled loop.

Audio backends

Music plays through either Cave Story's original Organya synthesizer or MIDI. Organya is more faithful but costs significant CPU; MIDI runs on a hardware synthesizer, off the CPU, and is the recommended default. Supported hardware:

  • Sound Blaster OPL3 FM -- the default; works on any Sound Blaster; sound effects on the SB DAC
  • WaveBlaster / DreamBlaster -- wavetable daughterboard on the SB16 WaveBlaster header
  • AdLib / OPL2 -- music on a card with no Sound Blaster (music only; no sound effects)
  • Gravis UltraSound (or PicoGUS) -- GF1 wavetable music and sound effects; no Sound Blaster needed
  • Organya -- Pixel's original tracker synth, in software (higher CPU cost)

MIDI backends offer a choice of music sets: an org2mid conversion of the original score (default), the WiiWare arrangement, or a custom drop-in set. Configure everything in SETUP.EXE; see docs/SOUND.md for sound configuration and docs/CONFIG.md for every setting and environment variable.

Download

See Releases for pre-built binaries, or build from source (see Building).

Latest release: doskutsu-1.7.0.zip (v1.7.0)

Each bundle (doskutsu-<version>.zip) contains DOSKUTSU.EXE, SETUP.EXE, the CWSDPMI.EXE DPMI host, license texts, and NXEngine-evo's GPLv3 engine data. The engine is the program; game data is user-supplied, like a Doom source port shipping without an IWAD.

Game Assets

DOSKUTSU ships no Cave Story game data and plays nothing on its own. Users supply their own copy of the 2004 EN freeware assets, extracted from the canonical Doukutsu.exe.

docs/ASSETS.md is the canonical, complete procedure -- follow it start to finish; it covers fetching the freeware bundle, extracting the full data tree (maps, sprites, music, SFX), and the expected directory layout. The two scripts below automate only the Pixtone-SFX slice of that workflow; running them alone does not produce a playable DATA\ tree:

  • scripts/fetch-cs-pxt.py is the one-shot orchestrator: fetches the 2004 EN freeware bundle from cavestory.one (SHA-256-pinned), extracts Doukutsu.exe to a tempdir, runs the Pixtone extractor, and cleans up. The archive doesn't persist after it runs.
  • scripts/extract-pxt.py is the canonical extractor, transcribed from NXEngine-evo's extract/extractpxt.cpp. It reads file offsets in Doukutsu.exe and emits ASCII Pixtone parameter files.

Same posture as the broader Cave Story port community (NXEngine-evo, doukutsu-rs): engine code is open source, game data is user-supplied freeware.

Usage

DOSKUTSU.EXE, the CWSDPMI host, and the Cave Story data all live together in one directory:

C:\DOSKUTSU\
  DOSKUTSU.EXE     the game
  SETUP.EXE        hardware / sound configurator (run once before first play)
  SETUP.BAT        launcher for SETUP.EXE (clears stale audio settings first)
  CWSDPMI.EXE      the DPMI host - must sit beside DOSKUTSU.EXE
  DOSKUTSU.CFG     written by SETUP.EXE (optional; the game runs without it)
  DATA\            Cave Story assets, user-extracted (see Game Assets)

See Quickstart to get binaries/assets and set up the game directory.

The DOS machine needs a standard DJGPP boot environment: HIMEM.SYS loaded, NOEMS, a SB16-compatible BLASTER variable, and a VESA 1.2+ video BIOS (a software VESA driver works as a fallback).

Run SETUP.EXE once to configure sound (Configuration), then run the game:

C:\DOSKUTSU> SETUP          (once, to configure)
C:\DOSKUTSU> DOSKUTSU       (play)

The title screen appears within a few seconds. Controls follow NXEngine-evo's defaults:

Key Action
Arrow keys Move / navigate menus
Z Jump / confirm
X Fire / cancel
A / S Cycle weapons
Q Inventory
W Map
Escape Pause menu
F11 Toggle fullscreen (no-op on DOS; always fullscreen)

Use SETUP.EXE to map keys and configure joystick support.

Configuration

Use SETUP.EXE to configure DOSKUTSU -- sound, input and other settings:

C:\DOSKUTSU> SETUP

SETUP detects hardware, recommends settings, and configures sound, performance, and input. It can play a sound effect and the Title theme to confirm audio works, then writes DOSKUTSU.CFG, which the game reads at startup. See docs/SETUP.md for the full reference and docs/SOUND.md for sound configuration.

Or skip SETUP and use DOS environment variables (SET in AUTOEXEC.BAT or at the prompt). Precedence: environment variable > DOSKUTSU.CFG > built-in default. See docs/CONFIG.md for every option.

Building

Building needs a Linux (or WSL) host with:

  • the DJGPP cross-compiler -- the one prerequisite that isn't a package install (~30 min one-time build)
  • cmake, git, make, gcc, python3, unzip, zip
  • dosbox-x -- runs the automated build-verification smoke tests

docs/BUILDING.md covers distro install commands, the DJGPP install, each build stage, DOSBox-X testing, and common errors.

Once DJGPP is installed -- the one-command path:

git clone https://github.com/ecliptik/doskutsu.git   # or ssh: git@github.com:ecliptik/doskutsu.git
cd doskutsu
./scripts/bootstrap.sh          # verify prereqs, fetch upstreams, apply patches, build

Or run stages individually:

./scripts/setup-symlinks.sh     # one-time: link tools/djgpp (only if using the ~/emulators hub)
./scripts/fetch-sources.sh      # clone the upstream repos at pinned SHAs
./scripts/apply-patches.sh      # apply DOS-port patches
make                            # orchestrate all four build stages
make smoke-fast                 # headless DOSBox-X smoke (fast config)
make setup                      # build SETUP.EXE (the configurator)
make setup-test                 # host-side SETUP unit tests

make dist bundles the game, CWSDPMI.EXE, and live-audio SETUP.EXE into a ready-to-deploy archive.

How This Project Is Developed

DOSKUTSU is developed agentically with Claude Code.

  • Claude Code authors the patches across the SDL3 DOS backend, NXEngine-evo, the build system, scripts, and docs, landing as patches/<vendor>/NNNN-*.patch files in this repository.
  • Human developers drive testing and iteration: TAS replays, real-hardware playthroughs, bug reports, and deciding what to fix next.
  • Workspace-local patches only. Nothing is contributed upstream to libsdl-org/SDL, libsdl-org/SDL_mixer, libsdl-org/SDL_image, or nxengine/nxengine-evo.

Components and License

DOSKUTSU's own source -- the build system, scripts, and documentation -- is MIT-licensed (LICENSE). The shipped DOSKUTSU.EXE is GPLv3: it statically links NXEngine-evo (GPLv3), which governs the combined binary. Patches under patches/ are derivative works of their upstreams and carry those licenses: GPLv3 for the NXEngine-evo patches, zlib for the SDL3 patches. Redistributed bundles include the GPLv3 license text and a pointer back to this repository.

Each component below is listed with its purpose, license, and whether it links into DOSKUTSU.EXE:

Component Purpose License In DOSKUTSU.EXE
DOSKUTSU port source (this repo) Build system, patches, scripts, docs MIT n/a - source, not the binary
NXEngine-evo The C++11 re-implementation of the Cave Story engine GPLv3 Yes - governs the binary
SDL3 Platform layer; its DOS backend is what makes the port possible zlib Yes
SDL3_mixer Audio mixing zlib Yes
SDL3_image Image loading zlib Yes
DJGPP libc 32-bit DOS C runtime, by DJ Delorie free to use unmodified + GCC Runtime Library Exception for linked libgcc code Yes - neither imposes GPL on the result
CWSDPMI DPMI host, by Charles W. Sandmann freeware, redistributable No - ships alongside as a separate program
Cave Story game data Maps, sprites, music, and SFX, by Daisuke Amaya (2004) freeware, 2004 terms User extracted, not redistributed

Built with the DJGPP toolchain (installed via build-djgpp by Andrew Wu), tested with DOSBox-X and real hardware.

Full attribution detail: THIRD-PARTY.md.

About

A port of Cave Story to DOS using SDL

Topics

agentic-aicave-storydosdosboxmsdosretrocomputingretrogamingsdl

Resources

Readme
License
Activity

Stars

6 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Contributors

Languages