From 390cc4515379fbd8acdf9c977fbc0cabb8c5749e Mon Sep 17 00:00:00 2001
From: Alula <6276139+alula@users.noreply.github.com>
Date: Mon, 28 Feb 2022 18:53:18 +0100
Subject: [PATCH] updated readme [ci skip]
---
README.md | 186 +++++++++++++++++++++++++++++++++++++++++++++---------
1 file changed, 156 insertions(+), 30 deletions(-)
diff --git a/README.md b/README.md
index 924dd87..7e1b4e5 100644
--- a/README.md
+++ b/README.md
@@ -1,54 +1,180 @@
# doukutsu-rs
-
-
-[Download latest Nightly builds](https://github.com/doukutsu-rs/doukutsu-rs/actions) (Requires being logged in to GitHub)
-
-A fully playable re-implementation of Cave Story (Doukutsu Monogatari) engine written in [Rust](https://www.rust-lang.org/).
+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)
+
+
+- [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)
+- [Get nightly builds from AppVeyor](https://ci.appveyor.com/project/alula/doukutsu-rs) (select platform -> Artifacts ->
+ download the .zip)
+
#### Data files
-This repository does not contain any copyrighted files.
+In order to work doukutsu-rs needs to be paired with supported data files. This repository does not contain any data
+files.
-For better user experience, AppVeyor builds are distributed with slightly modified freeware game 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+).
-*doukutsu-rs* should work fine with pre-extracted and tweaked data files from [this repository](https://github.com/doukutsu-rs/game-data), [NXEngine(-evo)](https://github.com/nxengine/nxengine-evo) extracted freeware data files and [Cave Story+](https://www.nicalis.com/games/cavestory+) data files.
-
-Vanilla Cave Story does not work yet because some important data files have been embedded inside the executable. and we don't have a loader/extractor implemented yet.
-
-##### Where to get them?
+#### Supported game editions and data file acquisition guides
**Freeware**
-- https://github.com/doukutsu-rs/game-data - Freeware game data distributed with CI builds, based on those two below.
-- https://github.com/nxengine/nxengine-evo/releases/download/v2.6.4/NXEngine-v2.6.4-Win32.zip - copy `NXEngine-evo-2.6.4-xxx/data` from the archive to runtime directory
+- 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
-**Cave Story+ (not fully supported)**
+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. That's all, you have everything to use it with doukutsu-rs now.
+
+
+- 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
-- Original version (first released in 2011 on Steam)
- - PC release (Steam) - Copy `data` folder from installation directory ([guide for Steam](https://steamcommunity.com/sharedfiles/filedetails/?id=760447682)) to the runtime directory.
- - PC release (Epic Games Store) - Essentially the same thing as with Steam version.
- - PC release (Humble Bundle) - Essentially the same thing as with Steam version.
- - PC release (GOG) - Essentially the same thing as with Steam version.
-- Remastered version (first released in 2017 on Switch)
- - Switch release - (tested only with eShop version) Extract `data` directory from romfs. Requires a hacked console and a recent and legal copy of the game. If you don't know how, look in Google how to exactly do that because the methods really differ.
+**Cave Story+**
-#### Mandatory screenshots
+doukutsu-rs can be used as drop-in replacement for `CaveStory+.exe`. No modifications to game files are needed.
-**Freeware data files:**
+**Original version (first released in 2011 on Steam)** - expand for instructions
-
+
+Steam release (Win/Mac/Linux)
-**Cave Story+ data files:**
+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
+
+We haven't tested it so no screenshots, but it very likely works. Feel free to PR screenshots to this guide.
+
+
+**Remastered version (first released in 2017 on Switch)**
+
+Note that this version is **incompatible** with saves from the original version.
+
+Intercharging the save files may result in spawning in wrong locations, softlocks, etc.
+
+
+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](https://github.com/DarkMatterCore/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](https://twitter.com/Daedliy) - brand artwork (Icon / Banner / Server)
-- [ggez](https://github.com/ggez/ggez) - parts of it are used in `crate::framework`, notably the VFS code.
+- 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.