TSC Essentials

Looking to create the coolest, longest and best mod on the forums? Ready to start a giant project filled with story and bosses?

Stop doing that. This is a huge problem that most new modders have (including me) when they begin their mod. They have a head full of ideas, and inspiration to create one of the first truly finished mods. However, they need a level of skill to match their enthusiasm and creativity, which doesn't come pre-packaged.

Before you even touch an editor, you have to keep organized. Try to plot out your entire story, characters, and assets in a text file so that you know what you're doing. There's nothing worse than having your mod hastily end with a cookie cutter plot twist final boss, and an unappealing ending which tries desperately to wrap up split ends.

But enough of that, on to the meat of this tutorial. This tutorial should help you learn some of the basics of scripting in Cave Story. This will be a more condensed version for modders just starting out, and should help people avoid common pitfalls that occur while scripting.

The images in this tutorial are screenshots of scripts from Booster's Lab, but the syntax are exactly the same, and they both look almost identical except for some parts highlighted in green in Booster's Lab, which show code that is not run. This is useful for making comments or notes, and organizing the code.

First of all, let's look at some script within the game.

Depending on how much practice you have with TSC scripting, this may or may not look familiar to you.

The first important point is towards the event numbers.

1. Event Numbers

These numbers represent what script is run at which event. The event number is found when a certain entity is interacted with, or through a specific TSC command <EVE. More on that later.

The important part is the order of the numbers, as well as where they are in comparison to the rest of the code. EVENTS MUST BE IN THE CORRECT ORDER. If you switched the placement of the two events, so that #0200 is first and #0110 is second, it is very likely that the game will not be able to correctly find the event number and weird things may happen to your game.

An event line comprises of the "#" symbol, followed by exactly four digits. This is the event's number. Putting in more or less than the required four digits can cause various issues; best-case scenario, you will hear some text sounds ingame, worst-case scenario, you might crash your game. Either way it's unprofessional, so don't do it.

2. Essential Map Starting Code

There are a few commands that are almost always in the starting event for a map - that is to say, the event that is run when the map is loaded.

These events highlight some of the commands used for starting a map. As you can probably see, they do mostly the same thing. The only difference is the value of <FAI.

<MNA is used to show the caption of the map for a few seconds in the middle of the screen. For example, the first playable map uses <MNA to display "Start Point". <CMU, followed by a four-digit value, starts a specific music track specified by the four-digit string. Remember that it must be four digits. <FAI, followed by a four-digit value, causes the game to "fade in" to a map. This basically means the game fades in from a blue screen to the map you are currently in. If you don't fade in to a map after fading out from another map, you will be able to move but won't be able to see anything. Make sure that you remember to put these in. Values 0-4 set which direction the game fades in from. <END simply ends the event.

There are more commands that can be useful for starting maps, but these are the basic commands that are usually important. Two other commands that are worth noting are <KEY and <FOM. <KEY prevents any movement of the player for the duration of the event. <FOM, followed by a four-digit value, focuses the screen on the player. The value represents the number of ticks it takes to shift the screen - 0001 is immediate, 0016 is the normal speed. The normal speed is the speed at which the screen moves throughout the game, so you must reset the speed to 0016 after changing it. Also, setting the value to 0000 crashes the game on the spot. Don't do that.

3. Essential Map Ending Code

Ending an event is easy; you need two commands and a few values. Extra commands are used for things like making noises, opening doors and the like, but that's not really important.

Make sure to include a <FAO, and <TRA command when changing maps. <FAO, followed by a number 0-4, fades out in a specific direction. It is exactly the same as <FAI, but it fades out instead of in. You will end with a blue screen. <TRA is a bit more complicated, and has four parameters, or values. The correct structure is <TRA XXXX:YYYY:ZZZZ:WWWW. In order from left to right, the values correspond to map number, the number of the event that is called after changing maps, and the x and y values of the player in the next map. After running <TRA, the map will be immediately changed to the one specified by XXXX.

Here is an example of an exit map code. Note the <FAO and <TRA commands. <FOM is added in because of a special circumstance, and can be ignored for this tutorial.

4. Beginning and Ending Messages

It's important to make sure your scripts run properly so that the game can run normally. This is a common problem for modders, especially with message boxes.

Knowledge of the <MSG command is vital for most mods, but it will not be covered here. Instead, we will discuss how to end and begin messages.

To start a message, there are three commands that are commonly used. (Technically there are five, counting <MS2 and <MS3, but those aren't important right now.) These commands are <FAC, <GIT, and of course <MSG.

<FAC creates a facepic that corresponds with the following value within the message box. Make sure to limit the value to four digits, as always. One important case is <FAC 0000, which clears the current facepic. You don't have to do this if the event ends afterwards, as it automatically resets the current facepic to 0000, but pay attention if you need to change the message box so that the next line does not need a facepic. This command is also similar to <GIT, although the latter is used to display an item or weapon image. The value corresponds to the item or weapon, and is referenced from armsimage.pbm and itemimage.pbm. Weapon images range from values 0001-0013. If you wish to display an item image instead, take the value of the item and add 1000 to it. For example, to display a Life Capsule you would enter <GIT 1006, as opposed to <GIT 0006. The latter would show the Missiles image, instead.

To end a message, there are also three commands that are commonly used. These are <NOD, <CLR, and <CLO. <NOD simply waits for key input - it will wait at this point until you press the attack button or the jump button. Putting a <CLR after this will erase the text but keep the message box on the screen. <CLO will erase the text as well as closing the message box. If your event ends with the message, <CLO is not technically necessary, as the game will automatically close the message box when the event ends.

One more point: the limit for characters for each line within the message box is about 35 characters. Keep in mind that part of the final character may still be cut off if you have the maximum 35 characters on a line. Also, when using a facepic the limit is lowered to 27 characters. The text is supposed to wrap around, but that isn't always the case and you shouldn't rely on it.

5. Stabilizing Events

Making sure the event starts and ends properly is extremely important. Failing to do this can result in the game cycling through each event in the script without stopping, or the player accidentally falling off the map while in the middle of an event!

An event is usually started with <KEY or <PRI, although there are a few exceptions. <KEY is used to restrict movement of the player, as stated before. This stops your character from moving into places it shouldn't. This is bad for many reasons, two being that your character can skip through movement triggers, and can avoid almost all damage. <PRI is like <KEY, but universal. When using <PRI, everything except for the message box will be frozen until the end of the event. Keep in mind that you cannot create cutscenes with moving characters while using <PRI.

Events are ended in one of three ways. The commands that correspond to this are <END, <EVE, and <TRA. We've already talked about <TRA: it sends us to a different map and begins a new event. <EVE is like this - it begins a new event, but it does not send the player to a different map and does not move the player. It has one parameter, a (four-digit) value that determines the event that is changed to. <END, evidently enough, does nothing but ends the event. The unique, and perhaps obvious properties of <EVE and <TRA, are that they also act as <END commands. Anything after these commands is ignored, as the current event is finished.

As had been mentioned before, green text is text that is never run. You can clearly see that <END is not run, then. This is because the <TRA that is before <END ends the event, so the final <END is not actually required and not run anyway. This is the same for <EVE.

To summarize:

· Make sure to properly begin and end your events

· Event numbers should look proper and come in sequence

· Code can be written outside of what is actually run to essentially comment your code

· There is a limit for characters within a message box - 35, or 27 with a facepic

· Please close your message boxes and reset <FAC and <GIT or your game will look ugly

· For the love of god, and all that is holy, DO NOT PUT MORE OR LESS THAN FOUR DIGITS FOR EVERY SINGLE PARAMETER

Hopefully, reading this guide has helped you gain a better understanding of how the event system works, and will help you be able to find errors in your code easily or prevent them from ever happening. However, if you're absolutely stumped, you can always ask the experts.