• Most people probably don't realise this, but this forum has had two editors for a number of years. One is the xenForo default editor, and the other is a custom editor I made years back I called BBCEd.

    All the settings for which editor you use was lost during the upgrade. You can find the setting under Account Settings > Preferences > Editor.

BLink's ULTIMATE guide to modding (vanilla) Cave Story 2019 edition

Old topic!
The last post in this thread is over 60 days old. Posting in this thread will be considered a bump, so please make an attempt to be courteous if you go ahead with it.

If the last post is over 6 months old, it may instead be a better idea to start a new topic. If you aren't sure about what to do, feel free to ask a staff member for help, or try to locate a 'general questions'-type thread if it exists in this (sub-)forum.
Feb 25, 2019 at 7:29 AM
Everything Else Is Irrelevant
Modding Community Discord Admin
"Bleep, Bloop, Bleep, Bloop"
Join Date: Apr 5, 2013
Location: In my mind and of my body.
Posts: 1595
Age: 22
#1
BLink's ULTIMATE guide to hacking vanilla Cave Story in 2019

Ok so basically next to none of the modding advances in the last 3 or 4 years have really been documented, let alone in one place. Dooey's guide STILL has a thread on how to edit images by manually renaming the file and EDITING BACK IN THE SIGNATURE IN HEX. This has been completely irreverent for like at least 6 years because BL automatically removes the need for it anyway and converts them to .bmp anyway. This has like, been a thing since before I even joined the forums 6 years ago.

So because of the severe outdated-ness of that thread, instead of trying to revive it, we're starting again from square one, so let's get going.

This Guide assumes that you are making a mod on Windows, it is possible to make mods on a mac but you are limited in a lot of ways as many tools are not compatible with mac. Along with this, some of the information on this thread may differ for you regarding setup/execution, ect ect

This guide also assumes that you are making a mod of Vanilla, Freeware Cave Story (2004), not CSE/CSE2, NxEngine, CS+, 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, 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.

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]
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: 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 because that corrupts the palettes for the .bmps. We recommend that you use something like Paint.net.

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 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: Alright, I've finished my mod! Where do I upload it to?
A: pixeltellsthetruth.solutions

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+ distributed by NiCALiS. (ie wind fortress)

With that, good luck and happy modding!
 
Last edited:
Feb 25, 2019 at 8:01 AM
Pokemon Master
"Life begins and ends with Nu."
Join Date: Jun 27, 2013
Location: Aspertia, Unova
Posts: 2015
Age: 24
#2
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
Cave++ Developer
"Keep on rollin'!"
Join Date: Sep 22, 2012
Location: Hugging a tentacle monster
Posts: 421
#3
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
Novice Member
"Officially Worth 1 Rupee"
Join Date: Jan 19, 2017
Location:
Posts: 1
#4
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
Fluffin' around
"In Soviet Russia, graves keep YOU!"
Join Date: Jul 20, 2015
Location: Under sea level or something
Posts: 670
Age: 20
#5
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: South Florida
Posts: 1364
Age: 23
#6
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
Fluffin' around
"In Soviet Russia, graves keep YOU!"
Join Date: Jul 20, 2015
Location: Under sea level or something
Posts: 670
Age: 20
#7
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
Pokemon Master
"Life begins and ends with Nu."
Join Date: Jun 27, 2013
Location: Aspertia, Unova
Posts: 2015
Age: 24
#8
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
Everything Else Is Irrelevant
Modding Community Discord Admin
"Bleep, Bloop, Bleep, Bloop"
Join Date: Apr 5, 2013
Location: In my mind and of my body.
Posts: 1595
Age: 22
#9
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
Fluffin' around
"In Soviet Russia, graves keep YOU!"
Join Date: Jul 20, 2015
Location: Under sea level or something
Posts: 670
Age: 20
#10
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
Pokemon Master
"Life begins and ends with Nu."
Join Date: Jun 27, 2013
Location: Aspertia, Unova
Posts: 2015
Age: 24
#11
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
Everything Else Is Irrelevant
Modding Community Discord Admin
"Bleep, Bloop, Bleep, Bloop"
Join Date: Apr 5, 2013
Location: In my mind and of my body.
Posts: 1595
Age: 22
#12
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
Pokemon Master
"Life begins and ends with Nu."
Join Date: Jun 27, 2013
Location: Aspertia, Unova
Posts: 2015
Age: 24
#13
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.
 
Top