What is this branch?

This branch adds several Quality-Of-Life improvements to the game's backend to make it easier to mod. If you're reading this and you're not a modder, this stuff probably doesn't interest you, since it changes nothing flashy about the game itself.

Additions:

• Modular background support with <BKG and its sub-commands, which allow for the creation of dynamic backgrounds with offsets and animations.
• NOXID-type layer support, (where NOXID is the first user to implement this type of layering system), allowing for multiple tile layers to be drawn on top of each other
• Animated tiles
• Desktop support for the glutin backend (primarily useful if the game needs to be resized without halting the program, which SDL doesn't do)
• Libxmp-lite support for tracker music
• Additional helper TSC commands (see the documentation page)
• Framework for bitmap and NPC rotation

To see how to use these features for modifying the game, please take a look at the the Documentation page.

Also, for more info for modding Cave Story in general, please see the Community Wiki page.

The rest of this readme is unchanged.

---

...And that branch is based on this branch

This branch adds the ability to build d-rs into a retroarch core. This way, d-rs can take advantage of all the features that Retroarch provides like a common controller API and custom shaders.

This branch is an updated version of the work I did in my dedicated d-rs retroarch repo. Putting it here makes it easier to keep up to date with upstream changes, but if you want to see the project's deep git history, look at the other repo.

Feature Checklist

• Screen drawing (openGL)
• Screen drawing (openGLES)
• Screen drawing (software?)
• Screen rescaling (see core display settings)
• Game timing
• Audio (asynchronous)
• Audio (synchronous?)
• V-Sync support
• Core restarting
• Input (Keyboard) (implemented, but disabled because the keyboard can be mapped to the virualPad)
• Input (touch) (carryover from the android port where certain items like menus can be interacted with)
• Input (Gamepad)
• Core display settings (aspect ratio, scale, etc.)
• Filesystem
• Platforms
  • Windows
  • Linux
  • Mac OS (at least openGL 3 required)
  • Android
  • iOS
  • tvOS (Apple TV 4 or newer)

Use

It its current state, d-rs runs on 5/5 "big" platforms. (mac OS was tried, but the compatibility context for hardware rendering was broken. Shaders for the backend would not compile, and if the openGL context were set to a version where they'd work, the frontend's shaders would break. This doesn't matter too much since d-rs already has a native mac port)

Note: the mac OS port now works, but requires at least openGL 3.3 to run. Older versions are not supported by the newest Retroarchs for Mac.

Since this port isn't currently part of libretro's upstream build system, some extra steps need to be taken in order to use it with Retroarch.

Before loading in the core, the doukutsu-rs-libretro.info file must be placed with the other info files in Retroarch's documents directory. This is because even though the core will work just fine without it, the Retroarch UI requires the info file to understand how to load files to the core. Without it, the frontend will refuse to start the game.

To use the UI with the Nintendo switch port of Cave Story, you need to put a dummy target in next to the data directory. This is because the UI requires some file to "load in", regardless if the core actually uses it or not. An empty text file named Target.exe will work just fine for this purpose (the only important part is the .exe extension).

If the command line is used to load in the core instead, both of these prerequisites can be ignored.

Building

Simply run the cargo build command from within the drsretroarch subdirectory to build the core for the parent system. To build it for other systems, the process is no different than building a generic library. (For instance, for android, you'd use cargo ndk, or for iOS, cargo lipo.)

Optionally, there's a makefile in the drsretroarch subdirectory that automates things like codesigning for the IOS libraries and renaming for the linux and android libraries. (It automatically downloads the proper targets for compilation and trims the lib prefix from the built libraries to match the retorarch naming semantics.) Using make will build the retroarch library for the current system. make ios will build for IOS (requires cargo lipo), make android will build for android (requires cargo ndk).

Personal notes

Notes

To compile retroarch to use openglES, use:
./configure --disable-videocore --disable-opengl1 --enable-opengles --enable-opengles3 --enable-opengles3_1
then
make

---

to compile on mac for iOS, use cargo lipo --release

then use codesign to give it an ad-hoc signature so it will run in retroarch: codesign -s - doukutsu-rs-libretro.dylib

check sign status with codesign -d -v doukutsu-rs-libretro.dylib

For convenient developing, just use the make ios command in the drsretroarch subdirectory. It will sign and rename the output dll for you. (I need to add makefile support for the other systems as well, since the linux-based distros automatically add 'lib' to the front of the output.)

The ad-hoc signed files work with both the sideloaded and appstore versions of retroarch, but it's impossible to put the core in the framework directory with the rest without jailbreaking the phone, so at that point, it's just easier to use the sideloaded version. (also moving the core directory doesn't work because the apple sandbox forbids loading outside frameworks)

MacOS needs a debug version of Retroarch to properly debug the core on the system, since the MacOS locks out the debugger from any apps that aren't explicitly flagged as "executable"

Built versions using xcode can be found in: /Users/USER/Library/Developer/Xcode

(xcode project found in pkg/apple) here and here

how to build for a tier 3 system: cargo +nightly build -Zbuild-std --target=aarch64-apple-tvos

The rest of this readme is unchanged.

---

D-RS

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

Join the Discord server

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

  Permalinks to latest builds from master branch:

  • Windows (64-bit)
  • Windows (32-bit)
  • macOS (Intel, 64-bit, 10.14+)
  • macOS (Apple M1, 11.0+)
  • Linux (64-bit)
  • Android (armv7/arm64/x86)

• Get stable/beta builds from

  • GitHub Releases
  • Flatpak (Linux only)

Note

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

Note

If you get issues with Epic Games Store version, scroll down 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 freeware data files or NXEngine(-evo) or from a supported copy of Cave Story+.

How to set up data files on Android

If your phone has an app called "Files":

1. Launch this app.
2. Press ☰ on the top left corner.
3. Tap on "doukutsu-rs game data".
4. Copy your game data files to the opened folder.

If your phone does not have this app:

1. Install the "Material Files" app from Hai Zhang and launch it(Google Play | F-Droid | Github Releases).
2. Press ☰ on the top left corner.
3. Press "+ Add storage".
4. In the window that pops up, press "External storage".
5. Press ☰ on the top left corner.
6. Tap on "doukutsu-rs game data".
7. Press the large blue button at the bottom labelled "USE THIS FOLDER".
8. Then click on ☰ in the top left corner again and open.
9. Tap on "files" above "+ Add storage".
10. Copy your game data files to the opened folder.

Supported game editions and data file acquisition guides

Freeware

doukutsu-rs works out of the box when it's placed in the same directory as the original Doukutsu.exe executable. On the initial startup, doukutsu-rs will automatically extract the additional resources that are embedded in the vanilla game into the data directory. Until that is done, both doukutsu-rs and the vanilla executable have to exist in the directory.

Example root 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!

Warning

EPIC GAMES STORE VERSION WARNING

Nicalis for some reason ships a stray opengl32.dll DLL from Windows 7 with the Epic Games Store copies of Cave Story+.

However as the game is 32-bit and the dll is 64-bit it has no effect on the original version, but as it's a core Windows DLL and doukutsu-rs ships 64-bit builds and uses OpenGL, it's makes the game crash on startup.

The fix is to simply delete opengl32.dll, as it's not used anyway.

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

1. Dump Your WiiWare .wad
2. Extract and decompress the data folder Example of a valid uncompressed data folder

Remastered version (first released in 2017 on Switch)

Note

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 (contained in romfs) from your console using tool such as nxdumptool.

Important notes:

• doukutsu-rs doesn't rely on the original ROM or executable, you just need the data files, go to RomFS options menu to just extract the files to SD card so you don't need to do any extra steps.
• Ensure you're dumping the files with update included (Use update/DLC option), as 1.0 isn't supported.

Nintendo Switch homebrew port specific info

If you're running the homebrew port (drshorizon.nro) on your Switch, you can avoid the dumping step, doukutsu-rs will automatically detect and mount the data files if you run it over Cave Story+ in Title Override mode (hold R while starting CS+ and launch d-rs from hbmenu).

You can put your own data files in /switch/doukutsu-rs/data directory on SD Card, which will be overlayed over RomFS if you run it in setup described above.

Controls

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

To change, use the control customization menu or 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 / Skip cutscene	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
• AppleHair - icon redesign for all platforms(crabsue-icon).
• @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.
• Zoroyoshi - k12x10 font we use as built-in font.