CSE2 - The Cave Story decompilation project

Discord server: https://discord.gg/2KamtGD

CSE2 is a decompilation of Cave Story started by Cucky, with an emphasis on accuracy to the original code. Through a combination of machine-conversion and by-hand translation, we've broken the original 2004 EXE back down to a recreation of its original C/C++ source code. As of yesterday, the game is fully completable: from First Cave to Ballos.

You can find the source code here. To compile it on Windows, you'll need Visual Studio or an MSYS2 installation with MinGW-w64.

Right now, one of the biggest deviations from the original code is the rebase from DirectX to SDL2. Personally, I plan to make a fork that moves back to DirectX, but for now SDL2 means better performance, and the ability to run CSE2 natively on Linux, so that's a bonus.

Hopefully I shouldn't have to explain how being able to work with plain C/C++ code will make advanced code modification easier. Writing a DLL chainloader to patch an EXE file is an absolute nightmare in comparison. Not to mention, this could open up the possibility of a community-maintained base for mods, with fancy things like extra TSC commands and .ogg support built right in.

As of writing, the project still isn't complete yet: the goal is to produce an EXE that's identical to the original one from Pixel himself. For now, while the game is playable from beginning to end, there may be slight differences. If you spot anything even a little off, please point it out here.

I suppose I should tell a little story here, about how this thing even got off the ground. Back when I made my DLL loader, I had to figure out how the game worked blind - I didn't even use the assembly compendium. Then GabrielRavier found out that the old Linux port contained leftover debug symbols. These symbols included the original names of practically every bit of code in the game. With this info, we could figure out just about everything we'd ever need to know about the game's code. It even gave us the names of each C/C++ file, and which functions they contained. All of this, combined with a good decompiler, meant making a decompilation was mostly just a matter of matching each bit of decompiled code with its original name.

CSE2 Portable
CSE2 Portable is a branch of CSE2 that ports the game away from DirectX/WinAPI, allowing it to run on other platforms such as Linux, while otherwise trying to preserve the original experience as much as possible. Good for purists.

Source code
Windows build

CSE2 Enhanced (discontinued)

Spoiler

CSE2E is a modified version of CSE2 with extra features:

• Widescreen
• Support for alternate soundtracks
• Options menu
  • Control remapping (keyboard and gamepad)
  • Soundtrack selection
  • V-sync toggle
  • 50FPS/60FPS toggle
  • Option to disable the sprites locking to a 320x240 grid when drawn, making them move smoother
• Bugfixes

Also included are enhancements specifically for modders:

• PNG support
• Full alpha blending support
• Fixed text blending, utilising the aforementioned alpha support
• All resource files moved to the data folder
• Booster's Lab support (open 'data/mrmap.bin')
• PixTone sounds split to .pxt files
• Support for Ogg Vorbis, FLAC, .it, .xm, .mod, .s3m, and PxTone audio formats for music and SFX
• Support for high-resolution sprites (see SPRITE_SCALE in CommonDefines.h)
• Extra TSC commands
  • <MS4
  • <MIM
  • <PHY
• No TSC script size limit (the vanilla limit is around 0x5000 bytes)

Source code
Windows build

How to compile

Spoiler

So you want to compile CSE2?

Well, to start, you'll need Visual Studio. I know a lot of people recommend MSYS2 instead, and while it is a lot more lightweight, it's also way more complex, and outright broken in some places, which will make compiling an absolute nightmare (I'm looking at you, Brotli).

So, we'll be using Visual Studio Community 2019. Don't worry - it's free. You can download it here:

Visual Studio: IDE and Code Editor for Software Developers and Teams

Visual Studio dev tools & services make app development easy for any developer, on any platform & language. Develop with our code editor or IDE anywhere for free.

visualstudio.microsoft.com

Once it's downloaded, run `vs_Community.exe`. Follow the installer until you reach this menu:


Here, you'll want to select the 'Desktop development with C++' workload, and then click 'Install'. Once it's done installing, you'll be prompted to restart your computer.

Next, download a copy of CSE2's source code if you haven't already and extract it somewhere. You can find a copy of CSE2 Portable's code here:

https://github.com/Clownacy/CSE2/archive/portable.zip

You are now ready to compile CSE2. To begin, open Visual Studio 2019. If it prompts you to open a project, select 'Continue without code' to skip past it and enter the main IDE. It should look something like this:


From here, select `File/Open/CMake`, and then navigate to where you extracted the CSE2 source code, and open the `CMakeLists.txt` file.

After this, Visual Studio will spend a few minutes configuring itself. You can see all of this in the little text console at the bottom of the window. Eventually, it will conclude, and hopefully not report any errors. The window should now look something like this:


You are now able to produce 64-bit Debug builds of CSE2. To do so, simply select `Build/Build All`. Like before, Visual Studio will spend the next few minutes performing tasks, and reporting back in the text console. It should eventually generate `CSE2_debug.exe` and `DoConfig_debug.exe`, which you can find in CSE2's `game_english` folder.

However, you probably want to be compiling Release builds, not Debug builds. To do so, select the 'Open the CMake Settings Editor' option. It will take you to this menu:


From here, change the 'Configuration type' option to 'Release'. You can now rebuild CSE2, and the files `CSE2.exe` and `DoConfig.exe` will be generated in the `game_english` folder.

And... that's it. If you want, you can edit CSE2's code by expanding the `src` folder on the right, and selecting one of the various `.cpp` files.

EDIT: Cucky told me to add a screenshot, so here's a screenshot. By changing one value in CommonDefines.h, you can make the screen not just wider, but taller:

 

I approve

 

How nifty! Hopefully this will open up the possibility for more consistent frame rates and the like, as I always noticed how wonky CS's frame output was when putting videos together.

 

trying to compile with g++ 8.2 i get the error

src/Star.cpp:111:14: error: expected initializer before ‘PutStar’
 void __cdecl PutStar(int fx, int fy)
              ^~~~~~~

 

Damn. Guess we missed one. It's probably just that __cdecl. It shouldn't be there.

 

How nifty! Hopefully this will open up the possibility for more consistent frame rates and the like, as I always noticed how wonky CS's frame output was when putting videos together.

CSE2 seems to be much smoother in terms of framerate than the original

trying to compile with g++ 8.2 i get the error

src/Star.cpp:111:14: error: expected initializer before ‘PutStar’
void __cdecl PutStar(int fx, int fy)
              ^~~~~~~

We just fixed it

 

Is there any way to compile this with normal MinGW, or does it really require w64?

 

Is there any way to compile this with normal MinGW, or does it really require w64?

it should work assuming GCC and the dependencies are supported

 

it's my understanding that w64 is the "real" mingw now and the other one is just kept around for legacy purposes, so you should probably be using that.

 

So how long 'till this gets Booster's Lab functionality? It'd be pretty neat to just have there be "plugins" that you could add in to your works to bring the engine to greater heights than what is normally shown in a csbd.

 

Compiled it and I have to say it looks amazing so far!

Spoiler

Where's Waldo?

I'm rusty though... I couldn't figure out how to set the FPS to 60 to eliminate tearing before needing to quit. Ended up just setting "#define FRAMERATE 16" in Draw.cpp.

Now once this has all the features of the DLL loader... like smoothed movement for the higher graphics scaling (once I figure out how to do that...)! Or adding the ability to smoothly zoom in and out on characters! Ohh...! Though I guess accuracy will be the focus for now
In any case, well done you two!

 

Wow nice

 

So how long 'till this gets Booster's Lab functionality? It'd be pretty neat to just have there be "plugins" that you could add in to your works to bring the engine to greater heights than what is normally shown in a csbd.

A better question would be how long until Booster's Lab gets this-functionality.

 

A better question would be how long until Booster's Lab gets this-functionality.

Did you forget that Noxid probably wouldn't bother to code that in and that nobody else wants to touch java because it's evil.

 

hey no bullying

 

You're right I'm sorry java you're not that bad, javascript is worse

 

Actually just getting the mapdata moved to a Stage.tbl like CS+ would make it compatible with BL so that's a thing.
Also thank you guys for making the sound effects in their own folder, but what about the ORGs, the icons, and the credits bitmaps?
Since the stage file formats are identical, it should make modding, if people want to mod it, very easy to do since you won't have to deal with baked in things in the exe. (or have to recompile it just to see changes to these things)

 

But the sound effects aren't in their own folder...? They're in the EXE just like the original. And, again, CSE2's goal is accuracy, so splitting all the files and completely switching to CS+'s stage.tbl format is out of the question. That's a job for the 'community-maintained mod base' I mentioned at the start of the thread.

The closest we could possibly do is store stage.tbl in CS+'s format in the source code, and then write a converter that turns it into the vanilla format when the game is built, and embed it in the EXE. That would still leave the issue of Booster's Lab figuring out where the data folder is.

 

@Clownacy, @GreenDev / Cucky

Hey, nice work. Keep it up!

 

Nice. Now i won't need IDA anymore.