![doukutsu-rs](./res/sue_crab_banner_github.png)

A fully playable re-implementation of Cave Story (Doukutsu Monogatari) engine written
in [Rust](https://www.rust-lang.org/).

[Join the Discord server](https://discord.gg/fbRsNNB)

![https://ci.appveyor.com/api/projects/status/github/doukutsu-rs/doukutsu-rs](https://ci.appveyor.com/api/projects/status/github/doukutsu-rs/doukutsu-rs)

- [Get nightly builds from AppVeyor](https://ci.appveyor.com/project/alula/doukutsu-rs) (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)
  
  **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](https://github.com/doukutsu-rs/doukutsu-rs/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](https://github.com/doukutsu-rs/game-data)
builds or [NXEngine(-evo)](https://github.com/nxengine/nxengine-evo) or from a supported copy
of [Cave Story+](https://www.nicalis.com/games/cavestory+).

#### 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.
  
<details>
<summary>Manual extraction guide</summary>

Tools required:
- Windows version of the game (1.0.0.6), original Japanese or with Aeon Genesis patch.  
- [Resource Hacker](http://www.angusj.com/resourcehacker/#download)
- [Booster's Lab](https://www.cavestory.org/download/editors.php)
    
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/`:

![files in /data/](https://media.discordapp.net/attachments/745322954660905103/947915770376102008/unknown.png?width=844&height=629)

`data/Org`:
![files in /data/Org/](https://media.discordapp.net/attachments/745322954660905103/947915770690687016/unknown.png)

</details>
    
- 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

<details>
<summary>Steam release (Win/Mac/Linux)</summary>

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!

![image](https://user-images.githubusercontent.com/53099651/155904982-eb6032d8-7a4d-4af7-ae6f-b69041ecfaa4.png)
</details>

<details>
<summary>Epic Games Store</summary>

Check your default installation directory.

![image](https://user-images.githubusercontent.com/53099651/155905035-0080eace-bd98-4cf5-9628-c98334ea768c.png)
</details>

<details>
<summary>GOG</summary>

Check your default installation directory.

![image](https://user-images.githubusercontent.com/53099651/155906494-1e53f174-f12f-41be-ab53-8745cdf735b5.png)
</details>

<details>
<summary>Humble Bundle</summary>

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

![image](https://user-images.githubusercontent.com/96957561/156861929-7fa03951-442b-4277-b673-474189411103.png)
</details>

<details>
<summary>WiiWare</summary>

Extract the `.wad` in order to get valid [Cave Story assets](https://user-images.githubusercontent.com/53099651/159585593-43fead24-b041-48f4-8332-be50d712310d.png)

</details>

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

<details>
<summary>Nintendo Switch</summary>

Extract the `data` folder directly from the ROM. 

</details>

#### 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

<details>
<summary>Freeware</summary>

![JP Freeware 2](https://user-images.githubusercontent.com/53099651/155924461-c63afc93-a41f-4cfd-ac9f-8f021cebcb04.png)

![Toroko Fight Freeware](https://user-images.githubusercontent.com/53099651/155924215-d492907a-ed0e-4323-bd46-61745b8fb32a.png)

![No Lighting Freeware](https://user-images.githubusercontent.com/53099651/155923814-621cf29e-bb20-4680-a96d-f049aaef1f88.png)

</details>

<details>
<summary>Original CS+</summary>

![CS+ Sand Zone](https://user-images.githubusercontent.com/53099651/155923620-db230077-0df5-4de4-b086-be6b4dcbc6df.png)

![CS+ Showoff Outer Wall](https://user-images.githubusercontent.com/53099651/155920013-3967cd03-8d69-4fc5-8f1d-fe659ff2e953.png)

![CS+ Challenge](https://user-images.githubusercontent.com/53099651/155919381-7e8159a0-a7cf-461a-8be2-2ce864631299.png)

</details>

<details>
<summary>Remastered CS+</summary>

![Balcony Switch](https://user-images.githubusercontent.com/53099651/155918810-063c0f06-2d48-485f-8367-6337525deab7.png)

![Dogs Switch](https://media.discordapp.net/attachments/745322954660905103/947895408196202617/unknown.png)

![Almond Switch](https://media.discordapp.net/attachments/745322954660905103/947898268631826492/unknown.png)

![Hell Switch](https://user-images.githubusercontent.com/53099651/155918602-62268274-c529-41c2-a87e-0c31e7874b94.png)

</details>

#### Credits

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