doukutsu-rs/README.md

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)
  • macOS (Intel, 64-bit, 10.14+)
  • macOS (Apple M1, 11.0+)
  • Linux (x86_64)

  macOS note: If you get a "doukutsu-rs" can't be opened message, right-click doukutsu-rs.app and click open.

• 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.

WiiWare

Extract the .wad in order to get valid Cave Story assets

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

Extract the data folder directly from the ROM.

Controls

Same controls as the default for freeware and Cave Story+ keyboard.

To change, edit doukutsu-rs\data\settings.json within your user directory.

	P1	P2
Movement	← ↑ ↓ →	, L . /
Jump	Z	B
Shoot	X	N
Cycle Weapon	A and S	G and H
Inventory	Q	T
Map	W	Y
Strafe	LShift	RShift

• Alt + Enter - Toggle Fullscreen
• F2 (While paused) - Quick Restart

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.