doukutsu-rs/README.md

# doukutsu-rs

![Release](https://github.com/doukutsu-rs/doukutsu-rs/workflows/Release/badge.svg)

[Download latest Nightly builds](https://github.com/doukutsu-rs/doukutsu-rs/actions) (Requires being logged in to GitHub)

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

**The project is still incomplete and not fully playable yet.**

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

#### Data files

This repository does not contain any copyrighted files. 

For better user experience, pre-built binaries are distributed with slightly modified freeware game files. 

*doukutsu-rs* should work fine with [CSE2-Enhanced](https://github.com/Clownacy/CSE2) or [NXEngine(-evo)](https://github.com/nxengine/nxengine-evo) 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?

**Freeware**

- https://github.com/doukutsu-rs/game-data - Freeware game data distributed with CI builds, based on those two below.
- https://github.com/Clownacy/CSE2/archive/enhanced.zip - copy `game_english/data` from archive to the runtime directory (place you run the executable from, usually project root)
- 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

**Cave Story+**

- PC release - (Tested only with Steam version, both Windows and Linux builds) Copy `data` folder from installation directory ([guide for Steam](https://steamcommunity.com/sharedfiles/filedetails/?id=760447682)) to the runtime directory.
- Switch release - **Not supported or actively tested.** Some of release-specific opcodes have been implemented (no code 
decompilation was involved, just pure data file analysis), so you should be able to play it without any major issues. 
Because methods used to extract game data from cartridge vary, you have to find that out on your own.

#### Gameplay support roadmap

- [x] Checkmarked things = fully implemented
- [ ] Unmarked things = partially or not implemented yet.

- [x] Rendering
  - [x] Backdrops
  - [x] Tilemap
  - [x] Player and it's animations
  - [x] Carets
  - [x] Bullets
  - [x] NPCs
  - [x] Text
  - [x] HUD
- [ ] Text scripts (TSC)
  - [x] Initial implementation
  - [x] Full implementation of gameplay opcodes
  - [x] Shift-JIS encoding support
  - [ ] Credits opcodes
- [ ] Audio
  - [x] Organya BGM playback
  - [x] Text script bindings
  - [ ] CS+ style .ogg BGM playback
  - [x] PixTone SFX
- [ ] NPCs/entities
  - [x] Initial implementation
  - [ ] Miscellaneous entities (~40% done)
  - [ ] Bosses (~30% done)
    - [x] Omega
    - [x] Balfrog
    - [x] Monster X
  - [x] First Cave
  - [x] Mimiga Village
  - [x] Egg Corridor
  - [x] Grasstown
  - [ ] Sand Zone (~50% done)
  - [ ] Labirynth (~10% done)
  - [x] Waterway
  - [ ] Egg Corridor? (~20% done)
  - [ ] Outer Wall
  - [ ] Plantation
  - [ ] Last Cave
  - [ ] Balcony
  - [ ] Hell
  - [ ] Cave Story+ specific NPCs
    - [x] Dashing Gaudis (361)
    - [ ] ??? (362)
- [ ] Weapons
  - [x] Leveling / XP system
  - [x] Initial implementation
  - [x] Snake
  - [x] Polar Star
  - [x] Fireball
  - [ ] Machine Gun
  - [ ] Missile Launcher
  - [ ] Bubbler
  - [ ] Blade
  - [ ] Super Missile Launcher
  - [ ] Nemesis
  - [ ] Spur
- [x] Saving and loading game state
- [ ] Support for different game editions
  - [ ] Vanilla
  - [x] Modified vanilla
  - [ ] Cave Story+
    - [x] Base mod
    - [ ] Mod loading
    - [x] Curly Story
    - [ ] Wind Fortress (~40%)
    - [ ] Boss Run
    - [x] Seasonal graphics
    - [x] Co-op gameplay
    - [ ] Remastered soundtrack

*(tbd)*

#### Mandatory screenshots

**Freeware data files:**

![Japanese Freeware](https://i.imgur.com/eZ0V5rK.png)

**Cave Story+ data files:**

![CS+ with enhanced graphics](https://i.imgur.com/YaPAs70.png)

#### Legal note

This project includes reverse engineered implementations of NPC and game physics algorithms, derived from freeware Cave Story and PC Cave Story+ executables.

Since the game's (non-existent, even for CS+) EULA does not prohibit reverse engineering, 
[according to Secion 103(f)](https://www.law.cornell.edu/uscode/text/17/1201) we could legally revese engineer those parts 
to achieve interoperability.   

#### Credits

- Studio Pixel/Nicalis for Cave Story 
- [Cave Story Tribute Site](https://cavestory.org) - has lots of useful resources related to the game. 
- [CSE2](https://github.com/Clownacy/CSE2) - widescreen fixes, more readable reference for game logic, mutual help in various things.
- [LunarLambda for organism](https://gitdab.com/LunarLambda/organism) - which is being used by us as `.org` playback engine.
initial commit 2020-08-18 16:46:07 +00:00			`# doukutsu-rs`

add links 2020-09-23 19:44:10 +00:00			`![Release](https://github.com/doukutsu-rs/doukutsu-rs/workflows/Release/badge.svg)`

			`[Download latest Nightly builds](https://github.com/doukutsu-rs/doukutsu-rs/actions) (Requires being logged in to GitHub)`

update the readme a bit 2020-10-30 02:03:41 +00:00			`A re-implementation of Cave Story (Doukutsu Monogatari) engine written in [Rust](https://www.rust-lang.org/).`
document/implement cs+ switch opcodes 2020-09-25 22:28:37 +00:00
death effect, minor tweaks 2020-11-14 01:24:32 +00:00			`The project is still incomplete and not fully playable yet.`
initial commit 2020-08-18 16:46:07 +00:00
CaveStory+ data files fixes 2020-08-19 00:55:21 +00:00			`[Join the Discord server](https://discord.gg/fbRsNNB)`
Discord link 2020-08-18 16:52:28 +00:00
initial commit 2020-08-18 16:46:07 +00:00			`#### Data files`

update the readme a bit 2020-10-30 02:03:41 +00:00			`This repository does not contain any copyrighted files.`

death effect, minor tweaks 2020-11-14 01:24:32 +00:00			`For better user experience, pre-built binaries are distributed with slightly modified freeware game files.`
initial commit 2020-08-18 16:46:07 +00:00
death effect, minor tweaks 2020-11-14 01:24:32 +00:00			`doukutsu-rs should work fine with [CSE2-Enhanced](https://github.com/Clownacy/CSE2) or [NXEngine(-evo)](https://github.com/nxengine/nxengine-evo) freeware data files and [Cave Story+](https://www.nicalis.com/games/cavestory+) data files.`
initial commit 2020-08-18 16:46:07 +00:00
update the readme a bit 2020-10-30 02:03:41 +00:00			`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.`
add data files guide to readme 2020-08-28 20:16:27 +00:00
			`##### Where to get them?`

			`Freeware`

releases setup attempt 2020-09-22 20:21:04 +00:00			`- https://github.com/doukutsu-rs/game-data - Freeware game data distributed with CI builds, based on those two below.`
add data files guide to readme 2020-08-28 20:16:27 +00:00			- https://github.com/Clownacy/CSE2/archive/enhanced.zip - copy `game_english/data` from archive to the runtime directory (place you run the executable from, usually project root)
			- 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

			`Cave Story+`

death effect, minor tweaks 2020-11-14 01:24:32 +00:00			- PC release - (Tested only with Steam version, both Windows and Linux builds) Copy `data` folder from installation directory ([guide for Steam](https://steamcommunity.com/sharedfiles/filedetails/?id=760447682)) to the runtime directory.
readme update 2020-11-01 19:58:33 +00:00			`- Switch release - Not supported or actively tested. Some of release-specific opcodes have been implemented (no code`
			`decompilation was involved, just pure data file analysis), so you should be able to play it without any major issues.`
			`Because methods used to extract game data from cartridge vary, you have to find that out on your own.`
add data files guide to readme 2020-08-28 20:16:27 +00:00
death effect, minor tweaks 2020-11-14 01:24:32 +00:00			`#### Gameplay support roadmap`
initial commit 2020-08-18 16:46:07 +00:00
Mimiga Village is done 2020-10-27 01:05:49 +00:00			`- [x] Checkmarked things = fully implemented`
			`- [ ] Unmarked things = partially or not implemented yet.`

check out done things, we're kind of playable now 2020-09-18 09:22:51 +00:00			`- [x] Rendering`
update roadmap 2020-08-27 05:10:54 +00:00			`- [x] Backdrops`
			`- [x] Tilemap`
			`- [x] Player and it's animations`
			`- [x] Carets`
check out done things, we're kind of playable now 2020-09-18 09:22:51 +00:00			`- [x] Bullets`
readme update 2020-09-04 23:47:17 +00:00			`- [x] NPCs`
readme update 2020-08-29 07:44:44 +00:00			`- [x] Text`
check out done things, we're kind of playable now 2020-09-18 09:22:51 +00:00			`- [x] HUD`
initial commit 2020-08-18 16:46:07 +00:00			`- [ ] Text scripts (TSC)`
update roadmap 2020-08-27 05:10:54 +00:00			`- [x] Initial implementation`
death effect, minor tweaks 2020-11-14 01:24:32 +00:00			`- [x] Full implementation of gameplay opcodes`
check out done things, we're kind of playable now 2020-09-18 09:22:51 +00:00			`- [x] Shift-JIS encoding support`
death effect, minor tweaks 2020-11-14 01:24:32 +00:00			`- [ ] Credits opcodes`
readme update 2020-09-03 12:28:34 +00:00			`- [ ] Audio`
			`- [x] Organya BGM playback`
			`- [x] Text script bindings`
			`- [ ] CS+ style .ogg BGM playback`
check out done things, we're kind of playable now 2020-09-18 09:22:51 +00:00			`- [x] PixTone SFX`
update roadmap 2020-08-27 05:10:54 +00:00			`- [ ] NPCs/entities`
readme update 2020-09-04 23:47:17 +00:00			`- [x] Initial implementation`
add Monster X and some tweaks 2020-12-15 22:09:14 +00:00			`- [ ] Miscellaneous entities (~40% done)`
			`- [ ] Bosses (~30% done)`
			`- [x] Omega`
			`- [x] Balfrog`
			`- [x] Monster X`
some progress has been made 2020-09-10 11:38:17 +00:00			`- [x] First Cave`
Mimiga Village is done 2020-10-27 01:05:49 +00:00			`- [x] Mimiga Village`
readme update 2020-11-01 19:58:33 +00:00			`- [x] Egg Corridor`
Update README.md 2020-12-02 14:43:18 +00:00			`- [x] Grasstown`
add Monster X and some tweaks 2020-12-15 22:09:14 +00:00			`- [ ] Sand Zone (~50% done)`
Mimiga Village is done 2020-10-27 01:05:49 +00:00			`- [ ] Labirynth (~10% done)`
add Monster X and some tweaks 2020-12-15 22:09:14 +00:00			`- [x] Waterway`
			`- [ ] Egg Corridor? (~20% done)`
Update README.md 2020-10-04 18:37:12 +00:00			`- [ ] Outer Wall`
			`- [ ] Plantation`
			`- [ ] Last Cave`
			`- [ ] Balcony`
			`- [ ] Hell`
update the readme a bit 2020-10-30 02:03:41 +00:00			`- [ ] Cave Story+ specific NPCs`
death effect, minor tweaks 2020-11-14 01:24:32 +00:00			`- [x] Dashing Gaudis (361)`
Update README.md 2020-10-04 18:37:12 +00:00			`- [ ] ??? (362)`
update roadmap 2020-08-27 05:10:54 +00:00			`- [ ] Weapons`
readme update 2020-10-27 01:20:10 +00:00			`- [x] Leveling / XP system`
check out weapons 2020-09-12 00:46:13 +00:00			`- [x] Initial implementation`
Update README.md 2020-10-04 18:37:12 +00:00			`- [x] Snake`
check out weapons 2020-09-12 00:46:13 +00:00			`- [x] Polar Star`
Update README.md 2020-10-04 18:37:12 +00:00			`- [x] Fireball`
check out weapons 2020-09-12 00:46:13 +00:00			`- [ ] Machine Gun`
			`- [ ] Missile Launcher`
			`- [ ] Bubbler`
			`- [ ] Blade`
			`- [ ] Super Missile Launcher`
			`- [ ] Nemesis`
			`- [ ] Spur`
update the readme a bit 2020-10-30 02:03:41 +00:00			`- [x] Saving and loading game state`
readme update 2020-11-01 19:58:33 +00:00			`- [ ] Support for different game editions`
update the readme a bit 2020-10-30 02:03:41 +00:00			`- [ ] Vanilla`
			`- [x] Modified vanilla`
			`- [ ] Cave Story+`
			`- [x] Base mod`
			`- [ ] Mod loading`
Updated README 2020-12-06 23:51:16 +00:00			`- [x] Curly Story`
death effect, minor tweaks 2020-11-14 01:24:32 +00:00			`- [ ] Wind Fortress (~40%)`
update the readme a bit 2020-10-30 02:03:41 +00:00			`- [ ] Boss Run`
death effect, minor tweaks 2020-11-14 01:24:32 +00:00			`- [x] Seasonal graphics`
Updated README 2020-12-06 23:51:16 +00:00			`- [x] Co-op gameplay`
update the readme a bit 2020-10-30 02:03:41 +00:00			`- [ ] Remastered soundtrack`
update roadmap 2020-08-27 05:10:54 +00:00
			`(tbd)`
initial commit 2020-08-18 16:46:07 +00:00
add a cs+ screenshot, because why not 2020-08-26 01:25:52 +00:00			`#### Mandatory screenshots`
mandatory screenshot 2020-08-26 01:21:46 +00:00
add a cs+ screenshot, because why not 2020-08-26 01:25:52 +00:00			`Freeware data files:`

update the readme a bit 2020-10-30 02:03:41 +00:00			`![Japanese Freeware](https://i.imgur.com/eZ0V5rK.png)`
add a cs+ screenshot, because why not 2020-08-26 01:25:52 +00:00
			`Cave Story+ data files:`

update the readme a bit 2020-10-30 02:03:41 +00:00			`![CS+ with enhanced graphics](https://i.imgur.com/YaPAs70.png)`
mandatory screenshot 2020-08-26 01:21:46 +00:00
death effect, minor tweaks 2020-11-14 01:24:32 +00:00			`#### Legal note`

			`This project includes reverse engineered implementations of NPC and game physics algorithms, derived from freeware Cave Story and PC Cave Story+ executables.`

			`Since the game's (non-existent, even for CS+) EULA does not prohibit reverse engineering,`
			`[according to Secion 103(f)](https://www.law.cornell.edu/uscode/text/17/1201) we could legally revese engineer those parts`
			`to achieve interoperability.`

initial commit 2020-08-18 16:46:07 +00:00			`#### Credits`

death effect, minor tweaks 2020-11-14 01:24:32 +00:00			`- Studio Pixel/Nicalis for Cave Story`
			`- [Cave Story Tribute Site](https://cavestory.org) - has lots of useful resources related to the game.`
			`- [CSE2](https://github.com/Clownacy/CSE2) - widescreen fixes, more readable reference for game logic, mutual help in various things.`
shrug 2020-09-10 11:44:46 +00:00			- [LunarLambda for organism](https://gitdab.com/LunarLambda/organism) - which is being used by us as `.org` playback engine.