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

**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 (Steam) - (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.
- PC release (EGS) - (Untested, but the game is essentially the same as Steam release) Same thing as with Steam version.
- Switch release - (Tested once, no guarantee to work) You need a hacked Switch and physical release. Google should help you.

#### Gameplay support roadmap

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

- [ ] 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
- [ ] 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+ (PC/Switch)
    - [x] Base mod
    - [ ] Mod loading
    - [x] Curly Story
    - [ ] Wind Fortress
    - [ ] Boss Run
    - [x] Seasonal graphics
    - [x] Co-op gameplay

*(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)

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

Lua time 2021-01-01 01:46:01 +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
Lua time 2021-01-01 01:46:01 +00:00			`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.`
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.`
Lua time 2021-01-01 01:46:01 +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)~~
add data files guide to readme 2020-08-28 20:16:27 +00:00			- 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+`

Lua time 2021-01-01 01:46:01 +00:00			- PC release (Steam) - (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.
			`- PC release (EGS) - (Untested, but the game is essentially the same as Steam release) Same thing as with Steam version.`
			`- Switch release - (Tested once, no guarantee to work) You need a hacked Switch and physical release. Google should help you.`
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.`

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 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`
Lua time 2021-01-01 01:46:01 +00:00			`- [ ] Cave Story+ (PC/Switch)`
update the readme a bit 2020-10-30 02:03:41 +00:00			`- [x] Base mod`
			`- [ ] Mod loading`
Updated README 2020-12-06 23:51:16 +00:00			`- [x] Curly Story`
Lua time 2021-01-01 01:46:01 +00:00			`- [ ] Wind Fortress`
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 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
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.