Feb 25, 2019 at 7:29 AM
Join Date: Apr 5, 2013
Location: In my mind and of my body.
Posts: 1640
Age: 27
Pronouns: he/him
BLink's ULTIMATE guide to modding Freeware Cave Story in 2023
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:
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.
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!
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
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.
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:
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.
