doukutsu-rs

A fully playable re-implementation of Cave Story (Doukutsu Monogatari) engine written in Rust.

Join the Discord server

• Get nightly builds from AppVeyor (recommended for now, has latest fixes and improvements)

  Permalinks to latest builds from master branch:

  • Windows (x86_64): https://ci.appveyor.com/api/projects/alula/doukutsu-rs/artifacts/doukutsu-rs_win64.zip?branch=master&job=windows-x64
  • macOS (Intel, 64-bit, 10.14+) https://ci.appveyor.com/api/projects/alula/doukutsu-rs/artifacts/doukutsu-rs_mac-intel.zip?branch=master&job=mac-x64
  • macOS (Apple M1, 11.0+) https://ci.appveyor.com/api/projects/alula/doukutsu-rs/artifacts/doukutsu-rs_mac-m1.zip?branch=master&job=mac-arm64
  • Linux (x86_64) https://ci.appveyor.com/api/projects/alula/doukutsu-rs/artifacts/doukutsu-rs_linux.zip?branch=master&job=linux-x64

• Get stable/beta builds from GitHub Releases (executables only, no data files bundled, see below for instructions)

Data files

In order to work doukutsu-rs needs to be paired with supported data files. This repository does not contain any data files.

doukutsu-rs works fine with pre-extracted freeware data from this repository builds or NXEngine(-evo) or from a supported copy of Cave Story+.

Supported game editions and data file acquisition guides

Freeware

• Vanilla freeware can't be just used without additional work, because some important data files are embedded inside the executable. An automatic extractor might be available in future.

Manual extraction guide

Tools required:

• Windows version of the game (1.0.0.6), original Japanese or with Aeon Genesis patch.
• Resource Hacker
• Booster's Lab

1. Open Doukutsu.exe in Resource Hacker.
2. Click on ORG group, select Action -> Save [ORG] group to an .RC file.
3. Navigate to data folder and create a folder named Org and save the .RC file there.
4. Click on BITMAP group, select Action -> Save [BITMAP] group to an .RC file.
5. Save them in data folder (NOT in Org folder).
6. Go to file explorer and navigate to data folder.
7. Delete Bitmap.rc
8. Go to Org folder.
9. Delete Org.rc
10. Rename extension of all files from .bin to .org - you won't have music if you don't do that!
11. Close Resource Hacker.
12. Open Booster's Lab
13. Load Doukutsu.exe in Booster's Lab - you can ignore the fact it tries to apply any patches or renames .pbm to .bmp, d-rs doesn't care.
14. Select File -> Export mapdata -> stage.tbl
15. Close Booster's Lab, saving isn't necessary.
16. Optionally delete leftover files and folders - .boostlab, ScriptSource, tsc_def.txt
17. That's all, you have everything to use it with doukutsu-rs now.

If you followed the above steps, the directory structure should look like this:

data/:

data/Org:

• https://github.com/doukutsu-rs/game-data - Pre-extracted freeware game data, graphics converted to .png, already distributed with AppVeyor builds for your convenience. (recommended)
• https://github.com/nxengine/nxengine-evo/releases/download/v2.6.5-1/NXEngine-Evo-v2.6.5-1-Win64.zip - copy NXEngine-evo-2.6.5-1-xxx/data from the archive to runtime directory

Cave Story+

doukutsu-rs can be used as drop-in replacement for CaveStory+.exe. No modifications to game files are needed.

Original version (first released in 2011 on Steam) - expand for instructions

Steam release (Win/Mac/Linux)

The data folder is in the same place across all platforms.

If you want to use doukutsu-rs as a substitute for Mac version of Cave Story+ (which at moment of writing doesn't work on 10.15+ anymore), do the following:

1. Find the doukutsu-rs executable:
   • In AppVeyor builds, it's in doukutsu-rs.app/Contents/MacOS/doukutsu-rs
   • In your own builds, it's in target/(release|debug)/doukutsu-rs
2. Open Steam Library, select Cave Story+, press the Manage button (gear icon) and select Properties...
3. Select Local Files and press Browse....
4. Open the Cave Story+.app bundle and navigate to Contents/MacOS directory.
5. Rename the Cave Story+ executable to something else or delete it.
6. Copy the doukutsu-rs executable and rename it to Cave Story+.
7. Launch the game from Steam and enjoy!

Epic Games Store

Check your default installation directory.

GOG

Check your default installation directory.

Humble Bundle

The archive from Humble Bundle contains the necessary data folder, in the same folder as CaveStory+.exe.

Remastered version (first released in 2017 on Switch)

Note that this version is incompatible with saves from the original version.

Interchanging the save files may result in spawning in wrong locations, softlocks, graphical glitches, or other issues.

Nintendo Switch

(Only 1.2+ has been tested, earlier versions may not work properly due to lack of 2P/Original Graphics support.)

Your interest is only in data directory placed in romfs.

Requires a hackable/modchipped console. If you got your Switch early, it's likely that it's hackable so give it a shot - just be very careful to not get your console banned. There's tons of guides you can easily find online so we won't cover it there.

You can dump the ROM (or just dump the romfs directly but it's just a bit slow so we recommend doing it on PC instead) using nxdumptool.

Once you got the keys and ROM dumped you can use the romfs extraction feature in Ryujinx or yuzu emulators to grab the data files.

Screenshots

Freeware

Original CS+

Remastered CS+

Credits

• Studio Pixel/Nicalis for Cave Story
• @Daedily - brand artwork (Icon / Banner / Server), screenshots for this guide.
• ggez - parts of it are used in crate::framework, notably the VFS code.
• Clownacy - widescreen camera code.
• LunarLambda for organism - used as basis for our Organya playback engine.