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

Feb 25, 2019 at 7:29 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
BLink's ULTIMATE guide to modding Freeware Cave Story in 2023

There are many different releases of cave story, but for the the case of 99% of mods, modders use either Freeware, or Cave Story Engine 2 (usually shortened to just CSE2). Freeware is the version of the game that was released back in 2004 (It's probably older than you are if this is your first time visiting this thread!). At the very least, it's a very old game by PC standards, but there has been a lot of work done to document the engine, and there are a ton of assembly hacks made specifically for that version of the game, including adding widescreen support, .ogg playback, and more to make it more modernized. CSE2 on the other hand is a decompilation of the original back to the source code. The code base for CSE2 has been updated to handle more modern backends (such as SDL2), and it has some extra features, as well, such as widescreen support, ogg playback, and more. However, CSE2 is a lot newer compared to it's Freeware counterpart, and is not as well documented and explored. Writing code for CSE2 is much, much easier than Freeware, but freeware has more stuff made for it already.

If you don't plan on writing much code, doing any large overhauls, and don't care to have the more modern backend, and portability to other systems, such as linux, mac, ect. Then use Freeware.
If you want to tinker with the codebase a lot more, plan on doing more reconstruction of game mechanics, and/or want to get your mod to run natively on other platforms, choose CSE2

This Guide assumes that you are making a mod on Windows, it is possible to make mods on Linux (or mac) but you are limited if you use Freeware:
Some tools are not fully compatible with Operating systems that aren't Windows. Linux is mostly fine thanks to WINE, but Mac has very limited support. Along with this, some of the information on this thread may differ for you regarding setup/execution, if you're using one of these alternative platforms. There are also some minor issues regarding sound emulation in WINE in some cases (In WINE it uses the "best" sample conversion rate, while windows XP by default, and win7 and Win10 are forced, to use "good" leading to .orgs sounding wildly different with the drums in some cases). Also if you choose to use the modloader .dll you will need to go to winecfg>Libraries>New override for library, add dsound.dll and modloader.dll and save

If you're looking for something native to Linux/Mac/WiiU/PSP/Anything, to dodge all the sketchy stuff mentioned above, then check out the guide to modding Cave Story Engine 2

This guide also assumes that you are making a mod of Vanilla, Freeware Cave Story (2004), not CSE2, NxEngine, CS+, CS Switch or any other version of CS. Either coded from the ground up, or a published version from NiCALiS.

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

Tool you NEED to mod CS.

Boosters Lab [link]
This is your map editor, also comes with a LOT of premade ASM hacks that you can just hit "apply" on. Almost every hex patch for very basic things can be done just through this. Editing bullets, editing starting data and so much more.

Clownacy's Mod Loader [link]
While not necessary, an absolute staple in most mods, if you want widescreen, the ability to make your internal resolution higher/lower the ability to play .ogg files in-game, and pixel unlock this is a must. Drag and drop this into your mod folder and it works, options are super easy to edit so give that a go. It even works on WINE, but requires adding the .dlls to the winecfg via winecfg>Libraries>New overrride for library, adding dsound and mod_loader.dll to the list, and saving.

Reshacker (old, compatible version with CS) [link] (direct download)
let's you dig into the exe itself and replace the icons the game has, as well as the mouse graphic, the orgs (the game's native music format) as well as the Credit's image for the game.

SeaTone [link] (direct download)
This let's you edit Sound effects for the game, Including ORG drums. This also comes with a pusher.exe that let's you pull the sounds from the game and put them back into the exe.

Orgmakerx210 [link] (direct download)
This program let's you make .org files (Cave Story's native music format) If you like making orgs there's a dedicated discord ran by mLurker you can check out here.

WaveGen100 [link]
Allows you to edit the sounds of every ORG instrument (not including drums)

Doukutsu Club [link]
The Doukutsu club is a site where you can upload your CS mods once you finish them.

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.

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.

====================
---===ASSEMBLY===---
====================

Assembly hacking is where you crack open the .exe of the game and look at the actual code of the game. The language the game is in, is x86 assembly, referred to as x86 or just asm for short.


BEFORE YOU GO AND LEARN ASSEMBLY PLEASE LEARN THE FUNDAMENTALS FOR MAKING CS MODS.
This is very, very important. Nobody is going to praise your mod if you have cool assembly hacks in it, but can't even put together a level that doesn't have 20 deathtraps in it, frustrating gameplay, and a lack of quality and polish put into it. Assembly is the last frontier for your mods. It is the most powerful, but has the power to destroy your creation (both literally and figuratively) if you do not have the fundamentals of modding down.

Assembly Compendium [link] (direct download)
This is a generic text file with a lot of info on assembly, a lot of the data in this file is VERY dated, and some of it is incorrect, but it is a starting point.

Noxid's Function list (Enlight's Edit) [link] (direct download)
This is Noxid's list of all the known functions in the game. This file is also pretty old so some things in it are outdated, but both this and the previous file plan to be updated sometime in the future.

OllyDBG (Txin's bugfixed version+BLink's skins) [link] (direct download)
This will let you edit the .exe of the game, if there isn't a hex patch or pre-made hack for what you need then you'll have to dig into the code yourself. Using this tool is only recommended if you have to make edits to already existing code and don't plan to completely overwrite it. (Unless your name is Thomas Xin)

Doukutsu Assembler [link] (direct link)
This is another hacking tool, if you are writing entire functions (suck as NPCs) this is the go-to tool to write your code in cases where you don't have to inject it into other code. There are a plethora of DouA hacks (mostly made by me lol) that you can find here. [link]
If you use these hacks PLEASE credit the people who originally made these hacks!
Original thread(s) with these hacks.
http://www.cavestory.org/forums/threads/4040/
http://www.cavestory.org/forums/threads/5256/
(I think Hina made a thread but I can't find it anywhere...)

Carrotlord's ASM hacking guide [link]https://www.cavestory.org/forums/threads/beginners-guide-to-cavestory-assembly.2305/
Be sure to check out version 1.04b and 2.0 because there is some info that is not in both versions. This teaches you about asm, but goes a bit off into the weeds talking about things that really don't apply to most CS mods. All the information is valuable, but things like the stack aren't exactly ""beginner"" friendly overall, going over details of the language but not exactly how to build functions and the like based off of it.

Also this guide lies, you CAN use EBX, EDI, and ESI freely, so feel free to do so in your asm hacks. (Doukutsu assembler by default uses EDI for it's pointers to NPCs now, so be sure to not use EDI for anything other than that though if you're writing NPC code)

BLink's NPC hacking guide [link]
This assumes some knowledge related to Carrotlord's guide, but not very much. It's more aimed at absolute beginners and can ease you into logic on how to actually build things in asm.

BLink's ASM video tutorial for writing code (informal edition)

BLink's informal ASM hacking guide for NPC modifcations (SUPER informal edition but I haven't seen another ollydbg walkthrough before...)

Txin's ASM hacking guide [link] (google doc)
This is more accurate and up to date than Carrotlord's guide, but has a somewhat steep learning curve. Goes very in depth into using asm. (currently incomplete)


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

Misc Modding tutorials:
https://www.cavestory.org/forums/threads/modding-mini-tutorials.3966/

Noxid's Video Guide: (fairly outdated in some ways but still useful)
https://www.cavestory.org/forums/threads/some-video-about-modding-or-whatever.3429/#post-135130

Dabaski's Video Guide: (more updated than Noxid's but lots of crossover information between the two.)
https://www.youtube.com/playlist?list=PLMvKHwT4UXpa01GDl6_gumcRRm48nfa2k

The Cave Story Modding Wiki (tons of info, but very scatted and a mixed bag)
https://cave-story-modding.fandom.com/wiki/Getting_Started

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

Q: Which is better, Cave Editor or Booster's Lab?
A: Booster's Lab. Here is a list (credits to Serri) showing off the differences in features between these two.
p368558-0-triy9k.png

Q: Wait... What's Sue's Workshop?
A: A very outdated editor. It doesn't allow assembly hacks, or even swapping out org music without it starting to corrupt the executable. It's very outdated, and likely older than you are if this is your first time around here.

Q: How do I place entities in Boosters lab???
A: The "i" key

Q: How do I edit images?
A: Open up the game in boosters lab once, then all the images convert to .bmp and can easily be edited using any image editing program except MSpaint. That corrupts the palettes for the .bmps. We recommend that you use something like Paint.net or Aseprite instead.

Q: My changes aren't being saved?
A: Did you make sure your files aren't read-only? By default CS, when downloaded, has the files marked that way to prevent tampering, but that's the opposite of what we want to do. Just right click on the folder your mod is in and go into properties. There is a checkbox marked "read only". Make sure it's unchecked!

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 TSC commands packaged in with BL under help > oh god what do i do.

Q: How do I replace ORGs?
A: Check out this post by Wedge of Cheese.

Q: How do I add more ORGs to the game?
A: Check this out!

Q: How do I change the drums to custom WAVs?
A: Install the OrgKutsu hack (download and tutorial in this thread). Don't forget to install Python in order to use Autohacker 2. (This also conflicts with <VAR so proceeds with caution)

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

Q: Can I port my mod to Cave Story+/NxEngine/PSP Port/Other releases?
A: Yes, you can try and stuff your changes into the default versions of these releases, but It's highly recommended to use CSE2's portable branch, since that will let your port to basically anything, and it doesn't put any nasty restrictions on you such as no custom code, or hard map limits. (as well as give you all the other extras you want to put into CSE2)

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 asm hacks, 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+ that has been distributed by NiCALiS. (ie wind fortress)

With that, good luck and happy modding!
 
Last edited:
Feb 25, 2019 at 8:01 AM
War criminal
"Life begins and ends with Nu."
Join Date: Jun 27, 2013
Location: Phoenix
Posts: 2758
Age: 29
As a dedicated Booster's Lab user, there is an alternative to both the map editors and the Hacking Tool/Hex Patcher features in the program, to those who can't seem to make the program work or they don't like the aesthetic.

Cave Editor [link]
The solution to Sue's Workshop, while the program is older than Booster's Lab, it can perform everything needed on map editing and on writing the TSC scripts, and it's cross-compatible with BL should you decide to change your mod editor preference.

ADVISORY (as suggested by BLink): Should you use the program in conjunction with Booster's Lab or if you switch to CE, and you work on a mod previously made with BL, it is recommended to delete the Scriptsource folders in the data and data/stage directories, and/or open up the mod in BL to disable Scriptsource reading altogether.

Autohacker 2 [link]
A hex patching tool, though it works slightly different than the Hex Patcher in BL. Requires a Python installation in order to be used. (EDIT: Python download link changed to an older version because I was a dummy who didn't test it out, sumimasen!)

You're welcome, @ColdCallerLoopy, @Tpcool, and @CyberSoup
 
Last edited:
Feb 26, 2019 at 1:33 AM
Stoned Member
"All your forum are belong to us!"
Join Date: Sep 22, 2012
Location: Hell
Posts: 557
Damn I wish wavegen100 was a thing when I was working on Nimbase.

Well, at least I get to brag about being one of the few people to make a custom wave100 before that.
Neat resource, thank you Blink very cool.
Maybe I should make a tutorial on how to make pretty levels.
 
Feb 26, 2019 at 3:01 AM
Neophyte Member
"Fresh from the Bakery"
Join Date: Jan 19, 2017
Location:
Posts: 3
Age: 22
Wow lmoa
I was just thinking today about starting my first cs mod. Mad coincidental my guy, you sure you're not psychic?

Nahh but seriously I appreciate this a ton, hopefully this'll inspire even more people to make CS mods
 
Feb 26, 2019 at 8:29 AM
Deliverer of Sweets
Bobomb says: "I need a hug!"
Join Date: Jul 20, 2015
Location: Under sea level or something
Posts: 785
Age: 25
Excuse me if this is mentioned in the video since I didn't check it out but-
Q: How do I use this scripting thing??
A: http://www.cavestory.org/guides/tsc.txt
As far as i know that file is only a reference of all commands and their inputs. If you are totally new to tsc(or even new to scripting or programming for that matter) I don't think this file will help any much.
 
Feb 26, 2019 at 9:06 AM
Tommy Thunder
Discord Group Admin
Org Discord Moderator
"Run, rabbit run. Dig that hole, forget the sun."
Join Date: Jan 24, 2011
Location: New Westminster, BC
Posts: 1368
Age: 28
As far as i know that file is only a reference of all commands and their inputs. If you are totally new to tsc(or even new to scripting or programming for that matter) I don't think this file will help any much.
I think it's a good reference to have on hand, because even though Booster's Lab explains each TSC event already, this has a lot of useful information besides that (like stuff related to music, sound, items, equips, etc.)... though, admittedly Booster's Lab may have all of this in a list somewhere already. I still use this particular reference page because I don't know any better. :p However, I do agree that the list is not a good answer to the posed hypothetical question you quoted. I think that's more a job for one of the guides or video tutorials so the language can be explained more thoroughly.

Also worth noting is that the list was updated, so it's probably better to use this one: http://www.cavestory.org/guides/tsc_r2.txt

Oh, and big props to you for taking the time out to do this, BLink. I think we've needed an updated resource list for a while, so this is great.
 
Feb 26, 2019 at 9:22 AM
Deliverer of Sweets
Bobomb says: "I need a hug!"
Join Date: Jul 20, 2015
Location: Under sea level or something
Posts: 785
Age: 25
Yeah I'm not gonna deny that it is a great reference to have around. I still use it every now and there in the rare times I do modding.
Reminds me that I still wanted to write a guide on tsc of my own, from the basics to some cool examples to things like oob flags. If only I could get myself more motivated to get into doing that...
 
Feb 26, 2019 at 9:59 AM
War criminal
"Life begins and ends with Nu."
Join Date: Jun 27, 2013
Location: Phoenix
Posts: 2758
Age: 29
Yeah I'm not gonna deny that it is a great reference to have around. I still use it every now and there in the rare times I do modding.
Reminds me that I still wanted to write a guide on tsc of my own, from the basics to some cool examples to things like oob flags. If only I could get myself more motivated to get into doing that...
And we really need a guide for some of the custom TSC commands that exist out there. Commands like <CMN, <IMG, <MS4, and <MIM should be very self-explanatory, but then we also have commands like <BUY, <PHY, <NAM, and specifically <VAR (which really needs a better tutorial, in my opinion).
 
Feb 26, 2019 at 8:43 PM
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
As far as i know that file is only a reference of all commands and their inputs. If you are totally new to tsc(or even new to scripting or programming for that matter) I don't think this file will help any much.

It is mentioned in the OP that Booster's lab has full documentation on all (vanilla) TSC commands including a door setup tutorial and the <ANP list.... in the Question asked right below the one you just quoted even.

And we really need a guide for some of the custom TSC commands that exist out there. Commands like <CMN, <IMG, <MS4, and <MIM should be very self-explanatory, but then we also have commands like <BUY, <PHY, <NAM, and specifically <VAR (which really needs a better tutorial, in my opinion).

<BUY is explained pretty well in the readme file, as well as in the thread it's posted it.
also <PHY is explained pretty well iirc, I read over it once and fully understood it when it first came out.
but yes noxid's commands aren't explained super well sometimes, not to mention that before dungeon_hacks, they were actually broken...
I mean TECHNICALLY <VAR is explained perfectly well, but without showing some examples it's hard to get a grasp on what it can really do. (similar to my <BKG hack, and yes that's getting an update and becoming a lot more user friendly here really soon)
 
Feb 27, 2019 at 9:49 AM
Deliverer of Sweets
Bobomb says: "I need a hug!"
Join Date: Jul 20, 2015
Location: Under sea level or something
Posts: 785
Age: 25
It is mentioned in the OP that Booster's lab has full documentation on all (vanilla) TSC commands including a door setup tutorial and the <ANP list.... in the Question asked right below the one you just quoted even.
Ah whoops I can't read right after waking up
So basically this is a list of modding resources and guides? With all due respect when I first saw the title I honestly assumed it'd contain guides rather than links and references to them.
 
Feb 28, 2019 at 1:09 AM
War criminal
"Life begins and ends with Nu."
Join Date: Jun 27, 2013
Location: Phoenix
Posts: 2758
Age: 29
Q: How do I add more ORGs to the game?
A: check this out
Yo BLink, you should probably include this thread as well, it helps make the whole org adding more hassle-free, especially since Noxid's tutorial really only allows for 1-2 more orgs, depending on the internal filename for the org you wanna include.
 
Mar 12, 2019 at 8:38 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
Thread updated to add my (very informal) video guide for making NPCs and how I personally go about thinking up designs and writing up code itself.

(Before you say anything YES I KNOW there's a bunch of black nothing at the beginning, and no, I'm not going to take another 7 hour to re-upload it.)
 
Jun 10, 2019 at 5:26 AM
War criminal
"Life begins and ends with Nu."
Join Date: Jun 27, 2013
Location: Phoenix
Posts: 2758
Age: 29
New question to add to the FAQ, because we completely forgot all about it:
Q: How do I change the drums to custom WAVs?
A: Install the OrgKutsu hack (download and tutorial in this thread). Don't forget to install Python in order to use Autohacker 2.
 
Mar 29, 2020 at 9:39 AM
War criminal
"Life begins and ends with Nu."
Join Date: Jun 27, 2013
Location: Phoenix
Posts: 2758
Age: 29
Forgive me for the bump, but I've noticed the download link for Autohacker 2 has been down. Here's a new download link for the program, I'm pretty sure there's a tutorial for using the program in the original thread.
 
Mar 29, 2020 at 2:54 PM
Junior Member
"It's dangerous to go alone!"
Join Date: Aug 10, 2015
Location:
Posts: 32
Also, the download for the Assembly Compendium links to Txin's bugfixed OllyDBG. Not sure how useful it still is, since I'm still new to ASM, but it's something I've noticed.
 
Mar 29, 2020 at 6:16 PM
War criminal
"Life begins and ends with Nu."
Join Date: Jun 27, 2013
Location: Phoenix
Posts: 2758
Age: 29
May 3, 2020 at 11:05 PM
Life keeps going, but my temper doesn't.
"..."
Join Date: Aug 12, 2013
Location:
Posts: 383
I haven't been around, but I'm pleasantly surprised to see that modding CS is still a thing and that there's even more tools and accessibility (and a new engine?) than when I first dabbled in things. To be expected after half a decade, but this is a very good thread.
 
May 4, 2020 at 12:03 AM
War criminal
"Life begins and ends with Nu."
Join Date: Jun 27, 2013
Location: Phoenix
Posts: 2758
Age: 29
I haven't been around, but I'm pleasantly surprised to see that modding CS is still a thing and that there's even more tools and accessibility (and a new engine?) than when I first dabbled in things. To be expected after half a decade, but this is a very good thread.
Well, welcome back! We hope modding is more to your liking now! :D
 
Aug 19, 2020 at 7:11 AM
Neophyte Member
"Fresh from the Bakery"
Join Date: Aug 19, 2020
Location: Bend, Oregon
Posts: 5
Age: 17
I am going to make a Cave Story Mod

I will make more of my Cave Story Mod Tomorrow. It will have 10 levels!!
 
Top