CSE2 - The Cave Story decompilation project

Feb 10, 2019 at 8:13 PM
Senior Member
CSE Discord Admin
"Fly, Fly, Fly!"
Join Date: Jan 13, 2016
Location:
Posts: 132
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)
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
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:

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

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:

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:
1600976692350.png

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:
1600976867910.png

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:
1600977055199.png

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:
1549833116759.png
 
Last edited:
Feb 10, 2019 at 8:17 PM
Junior Member
"Fresh from the Bakery"
Join Date: May 7, 2018
Location:
Posts: 17
I approve
 
Feb 10, 2019 at 8:39 PM
scrungy
Bobomb says: "I need a hug!"
Join Date: Oct 7, 2011
Location: PrtWeed
Posts: 777
Age: 24
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.
 
Feb 10, 2019 at 8:51 PM
In my body, in my head
Forum Moderator
"Life begins and ends with Nu."
Join Date: Aug 28, 2009
Location: The Purple Zone
Posts: 5998
trying to compile with g++ 8.2 i get the error
Code:
src/Star.cpp:111:14: error: expected initializer before ‘PutStar’
 void __cdecl PutStar(int fx, int fy)
              ^~~~~~~
 
Feb 10, 2019 at 9:05 PM
Senior Member
CSE Discord Admin
"Fly, Fly, Fly!"
Join Date: Jan 13, 2016
Location:
Posts: 132
Damn. Guess we missed one. It's probably just that __cdecl. It shouldn't be there.
 
Feb 10, 2019 at 9:12 PM
Junior Member
"Fresh from the Bakery"
Join Date: May 7, 2018
Location:
Posts: 17
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
Code:
src/Star.cpp:111:14: error: expected initializer before ‘PutStar’
void __cdecl PutStar(int fx, int fy)
              ^~~~~~~
We just fixed it
 
Feb 10, 2019 at 10:49 PM
Veteran Member
"Wacka-Wacka-Wacka-Wacka-Wacka-Wacka-Wacka-Wacka-BLEIUP"
Join Date: Aug 21, 2012
Location: At a computer
Posts: 332
Is there any way to compile this with normal MinGW, or does it really require w64?
 
Feb 10, 2019 at 11:15 PM
Junior Member
"Fresh from the Bakery"
Join Date: May 7, 2018
Location:
Posts: 17
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
 
Feb 11, 2019 at 12:05 AM
In my body, in my head
Forum Moderator
"Life begins and ends with Nu."
Join Date: Aug 28, 2009
Location: The Purple Zone
Posts: 5998
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.
 
Feb 11, 2019 at 3:14 AM
Stoned Member
"All your forum are belong to us!"
Join Date: Sep 22, 2012
Location: Hell
Posts: 557
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.
 
Feb 11, 2019 at 10:08 AM
Indie game enthusiast
"What is a man!? A miserable pile of secrets! But enough talk, have at you!"
Join Date: Apr 18, 2006
Location: Forever wandering the tower...!
Posts: 1787
Compiled it and I have to say it looks amazing so far!
Where's Waldo?
p368294-0-big.png


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!
 
Last edited:
Feb 11, 2019 at 6:46 PM
Senior Member
CSE Discord Admin
"Fly, Fly, Fly!"
Join Date: Jan 13, 2016
Location:
Posts: 132
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.
 
Feb 11, 2019 at 10:47 PM
Stoned Member
"All your forum are belong to us!"
Join Date: Sep 22, 2012
Location: Hell
Posts: 557
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.
 
Feb 12, 2019 at 12:07 AM
In my body, in my head
Forum Moderator
"Life begins and ends with Nu."
Join Date: Aug 28, 2009
Location: The Purple Zone
Posts: 5998
hey no bullying
 
Feb 12, 2019 at 12:19 AM
Stoned Member
"All your forum are belong to us!"
Join Date: Sep 22, 2012
Location: Hell
Posts: 557
You're right I'm sorry java you're not that bad, javascript is worse
 
Feb 12, 2019 at 12:56 AM
The TideWalker
Modding Community Discord Founder
"That dog!"
Join Date: Apr 5, 2013
Location: In my mind and of my body.
Posts: 1640
Age: 26
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)
 
Feb 12, 2019 at 3:13 PM
Senior Member
CSE Discord Admin
"Fly, Fly, Fly!"
Join Date: Jan 13, 2016
Location:
Posts: 132
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.
 
Last edited:
Feb 13, 2019 at 3:09 PM
Junior Member
"Wahoo! Upgrade!"
Join Date: Feb 26, 2018
Location:
Posts: 46
Nice. Now i won't need IDA anymore.
 
Top