BLink's ULTIMATE resource guide to modding (CSE2) Cave Story 2023 edition

BLink's ULTIMATE guide to modifying the Cave Story Engine 2 source code of Cave Story.

Spoiler: Why Should I use CSE2?

CSE2 is a decompilation of the original freeware Cave Story; If you want to learn more of how this was done; check out the gitdab's readme

Now, onto the WHY?

CSE2e is a modified version of the source code from Freeware Cave Story. It should be fairly obvious how directly editing the source code is much more applicable to making better mods than having to tinker with assembly.

However this isn't just regular cave story, there are a lot more features that have been added since the source code has been updated to modern standards:

.png/alpha support
Based in SDL2 for portability to other platforms (Mac, Linux, Wii, Switch)
external .org and .pxt files
more screen sizes
V-sync
pixel unlock
editing the original code
and more!

===================
---===GENERAL===---
===================

Setup:

CSE2EX is going to be the main branch of what we're editing. (if you don't know what a branch is, that's perfectly fine! I'll go over everything in a minute)

Because we're compiling the game from the source code, we need to setup a development environment that can compile code using Cmake.

Spoiler: Windows

You can use multiple ways to compile Cmake files, including using Visual Studio, or CodeBlocks; but the officially supported version of compilation is using MSYS2 (and now Visual studio as well)

On a clean MSYS2/MinGW64 install you'll want these packages:

Required:
git
mingw-w64-x86_64-cmake
make
mingw-w64-x86_64-gcc

Optional packages for non-local build :
mingw-w64-x86_64-SDL2
mingw-w64-x86_64-freetype

Optional packages for non-local GLFW3 build :
mingw-w64-x86_64-glfw


Installing packages in MSYS2 is done with Arch-based package installer, pacman if you don't know how to use pacman read the wiki page for it on the Arch Wiki (you're probably looking for the section about installing packages btw).

Spoiler: Mac

I've never touched a mac and never will; when somebody tries to setup stuff on a mac tell me so I can add this.

Spoiler: Linux

Setup on linux is incredibly easy; And if you're running linux you *probably* already know how to use a terminal/compile code/clone a repository.

Here's a Dependency list for a lot of different versions of Linux.

Clownacy/CSE2

Decompilation of Cave Story (v1.0.0.6). Contribute to Clownacy/CSE2 development by creating an account on GitHub.

github.com

Now that you have your environment; (assuming you're using MSYS2 or a Linux terminal) just run git clone https://github.com/EwanGreen4/CSE2EX then cd CSE2EX
finally you want to run git checkout enhanced so you're compiling CSE2EX instead of just CSE2

building is done with

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

Once built, the executable can be found in the game_english/game_japanese folder, depending on the selected language.


Alright; now that we have the ability to build the code, it's time to get down and learn how to mod!

Tools:

Booster's Lab [link]
Currently this is the only CS editor that supports modding of CSE2; to modify it just load up mrmap.bin in the data folder and then it's identical to vanilla CS (you can't apply hex patch mods because of fairly obvious reasons though :v )
Currently 5.1.0.0+ of Booster's lab is the only editor that supports CSE2e, so be sure you're using a relatively recent version of BL.

SeaTone [link]
This let's you edit Sound effects for the game, Including ORG drums. This program naively runs on windows exclusively, but WINE does emulate it properly if you want to edit the sound effects windows free.

WaveGen100 [link]
Allows you to edit the sounds of every ORG instrument (not including drums).
Currently there's only a windows build; but the source code is freely available.

Cave Story Modding Community Discord. [link]
This is the Discord for the Modding community. There are a lot of misc resources you can find here as well as many helpful people that know much about the game to help you get started on your modding journey.

Cave Story Engine 2 Discord [link]
This server is a hellish landscape ever since the official DCMA of CSE2, it has devolved into a dead and shitposting server, beware, all who enter.

Also please, please, please watch this video on level design in CS. It fairly long but very important if you don't want to get slammed in your mod thread for making death trap spikes everywhere.

===============================
----====OTHER RESOURCES====----
===============================

In BL there is an option under `help > oh god what do i do` this will help you get a bit of a grip on things possibly.

Rundown on Quote's default physics:

https://www.cavestory.org/forums/threads/modding-reference-sheets.792/

TSC 101

http://www.cavestory.org/guides/tsc_r2.txt

The Cave Story Modding Wiki (tons of info, but very scatted and a mixed bag)

Getting Started

This is the index directory for getting started on your Cave Story modding adventure. This index contains video tutorials, essentials, written documents, and external links. As of now, this index is far from being complete. The mission is to make this index as user friendly as possible with...

cave-story-modding.fandom.com

===================
----====FAQ====----
===================

Q: I can't get the program to build....
A: stop by the CSE2 discord and ask us if you need a hand.

Q: How do I use this scripting thing??
A: Check this out to get started!

Q: What is <ANP and how do I use it?
A: There's full documentation on how to use all of the vanilla TSC commands packaged in with BL under help > oh god what do i do.
There isn't currently any formal write-up for the commands that are exclusively in CSE2e at the moment, but asking in the discord(s) should prove fruitful in the meantime.

Q: Alright, I've finished my mod! Where do I upload it to?
A: pixeltellsthetruth.solutions (yes, that's the URL of the site!)


This isn't a question but idk where else to put it.
IF YOU USE CONTENT FROM OTHER MODS CREDIT THE ORIGINAL SOURCE!!
This includes code, orgs, graphics and maps. We all stand on the shoulders of giants.
Please show respect to those who made your work possible

Also DO NOT include content from any release of cave story that has been exclusively in any version of CS+ distributed by NiCALiS. (ie wind fortress)

With that, good luck and happy modding!

 

Can't you still use Booster's Lab v500, but edit stage.tbl instead of mrmap.bin? Like, at least take advantage of the bug preventing you from modifying CS+ for CSE2.

 

Use this version of Booster's Lab: https://cdn.discordapp.com/attachments/312733438153326593/690948028156215406/BoostLab-nightly.zip

 

Like, at least take advantage of the bug preventing you from modifying CS+ for CSE2.

I believe that CSE2e does out of the box have stage.tbl support but there was capitalization error somewhere along the lines because windows lack of case sensitivity.

Also what bug?

 

And also, also, if this is gonna be a guide for CSE2, you can at least, you know, provide any tutorials, handmade or preexisting, on how to code in C. The one major obstacle in the way to using CSE2 in the first place.

Also what bug?

Using v500 prevents you from loading up CS+, as it tries loading up the bitmaps in .png format instead of .bmp format. So accidentally, for that reason, it can work with CSE2 because of .png support.

 

Also, you should mention existence of Qt Creator, because it's better than VS.

 

Also, you should mention existence of Qt Creator, because it's better than VS.

There's only official support for MSYS2 and VStudio. I'm not going to recommend anything that isn't supported in the github's compilation instructions, even if I was to personally agree to use something in there.

And also, also, if this is gonna be a guide for CSE2, you can at least, you know, provide any tutorials, handmade or preexisting, on how to code in C. The one major obstacle in the way to using CSE2 in the first place.

I wouldn't call Coding in C any bit a major obstical when it is very easy to look up tons of stuff online that's well documented (unlike x86 being around for almost 50 years, and it being superseded, and is well on it's way to be depreciated)

Regardless, I think if you're getting into a repository, learning how to use git, and want to tinker with code, any C++ tutorial will do. It's already well documented elsewhere, and anything I could link would just be biased towards C or C++ coding mentality, and I'd rather stay far away from that.

I've personally seen people with 0 experience step into using CSE2e already, and learn how to tinker with things just with experience, so I'm not too worried about it.

 

I could link would just be biased towards C or C++ coding mentality, and I'd rather stay far away from that.

Maybe others can suggest links, then. Just felt it should at least be the principle to provide C tutorials considering the ASM tutorials provided in the previous Vanilla modding guides. And when it comes to dummy dumb dumbs like me, it would be a godsend.

 

C Language - Overview

C Language - Overview - C is a general?purpose, high?level language that was originally developed by Dennis M. Ritchie to develop the UNIX operating system at Bell Labs. C was originally first implemented on the DEC PDP-11 computer in 1972.

www.tutorialspoint.com

This might not be the best tutorial in the world, but it's the one I used to learn C back in 2014.

Just be aware - it'll make you install the original MinGW, which pales in comparison to MSYS2. Still, the way I went about it was that I got comfortable with MinGW, learned whatever I could, and when I thought I was ready, I switched to MSYS2. My memory's foggy, but I remember it being pretty painless aside from learning how to wrangle the package manager.

 

because it's better than VS

This is a very dumb argument because any toolchain/development environment can be shit if you don't know how to set it up properly.

Also I fail to see what Qt/qmake has to do with CSE2 and why on Earth you would ever use Qt Creator for this purpose. MSYS2 paired with a somewhat competent editor like vscode, sublime text, notepad++ (or vim/nano if you want a terminal based solution) should be more than enough for anything.

 

please clarify that you need to use pacman -S to install packages

 

please clarify that you need to use pacman -S to install packages

because everyone here uses Arch/MSYS2, obviously

the post does need a link to this wiki entry though: https://github.com/Clownacy/CSE2/wiki/Dependency-lists
and it should be updated to point to CSE2EX instead of CSE2

 

I added a small section about pacman and linked appropriate documentation on how it's used.
Also I did add the dependency list,.

I'll be updating the guide to point to CSE2EX/CuckyCSE2 instead of just CSE2e when either of those forks are ready to have official support for modding. Until then I'm just going to be linking people to CSE2e for the meantime.

 

How do I add a caret to CSE2? etc, one that is spawned by enemies when they die.