The KimiTech Industries Modders GuideThis is a guide for those wishing to create a mod for Cave
Story (AKA Doukutsu Monogatari). This document won't cover everything,
and should be used along side other resources and guides - this is
merely the bare-bones for getting into the most basic of modding. That
said, using just the subjects covered in this document, one would be
able to make a new, if incredibly basic, mod. ;) Jump To:
What You'll Need:Programs and tools that are essential to creating a mod.
Before You Begin:Things to keep in mind while getting started and working through to completion.
The Basics: TSCFirst things first, I'm going to give you the BASICS. TSC is a custom language in many ways unique and undocumented (officially, anyway). And in many ways VERY accessible. The most important points when working with TSC (and the source of most bugs):
An Example TSC Event#0100 Here's what it looks like:
The result of this is, when event 0100 is called, the player input is locked out (so the PC doesn't bounce around), and then a text-box is opened. In the first line of the text box, the text "Hello world, this is my text box!" is displayed. The game then waits for the player to press jump/shoot to advance to the next part. After player input is received, the previous text is erased and the text "This is the second section!" is displayed (this time in the second line of the text-box). Once more the game waits for player input and clears the text-box on receiving it before displaying the last line (in the third and final line of the text box), "I'm going to close it now.". It then waits for player input before closing the text-box and playing a sound. Finally, the entire event #0100 is ended. To get a feel for whitespacing and stuff, try goofing around with that script snippet in Cave Editor. A Note on Head.tscHead.tsc is the global script sheet. You can place events here that you will call frequently (such as beds, save points and the death events). Of important note here:
Adding CommentsComments may be added directly following an <END. As in: I'm going to close it now.<NOD<CLO<SOU0011<END //This line is a comment. Add comments to denote what does what when writing complex scripts. It can really help sort out rats nests. Calling EventsThere are a few ways to call events. The four most common are:
This is important because an event that isn't run is useless, and therefore a waste. Key TSC CommandsThese are commands that everyone who's anyone should know by heart. They are the core commands used by nearly every mod (see tsc.xls for more details on these and other commands). With these 13 commands you should be able to do 80% of what you need to.
The Basics: Music and SoundsTo add background music, use the <CMU command in the format: <CMUXXXX, where X is the number of the song you wish to play. Additionally, all songs except event tracks can be resumed playing with the <RMU command. This is handy for events like getting an item where you have a song playing, switch to the Get Item music and then want to go back to the previous song. The 4 event tracks are as follows: 0003 - Game Over Unlike normal songs they do not automatically loop back to the start. In order to not cut out the entire song, add a <WAI for 0160 before switching back to the original track. The names given are just what they're used for in original Cave Story, not what they have to be used for. Additionally, the <FMU command will reduce the current music to about 1/3 of its volume. Handy for areas with sound effects or for changing tracks without jarring. To play a sound effect, use the <SOU command. Sound effects are short noises that often accompany in-game action. The <SOU command is best reserved for cutscenes and areas with no enemies, though its quick execution doesn't prohibit its use in enemy-rich environments. Some handy values for this are: 0011 - Door opening The Basics: TSC-Based FlagsA flag is a special piece of data that informs the game that something has been done (such as defeating a boss). There are 4 types of TSC-based flags in Cave Story: Hard flags, skip flags, map flags and equip flags. The most commonly used are hard flags (so-called because they are saved to Profile.dat when the game is saved). Hard FlagsThere are 3 commands associated with hard flags: <FL+. <FL-. and <FLJ <FL+ sets a flag. Valid values are between 0001 and 9999. However, due to a limitation, only flags up to 7000 are saved to Profile.dat - Keep this in mind when writing a complex series of flags. As well, an unknown number of flags are reserved, so generally start with flags at 0100 to be safe and not muck up the game. <FL- clears a flag. Again, values from 0001 to 9999 are valid. Clearing a flag that hasn't been set doesn't do anything. <FLJ is the meat of the operation. It takes 2 arguments, the first being the flag it checks, and the second being the event to go to if the flag is set. Functions very similar to an IF statement. To bring this all together: #0100 #0101 What this example will do is, upon calling event #0100, check to see if flag 0100 is set. If it is, it jumps to event #0101 and runs it, which clears the flag. If the flag ISN'T set, it continues event #0100 on to set the flag (which will trigger the jump next time it is run). Don't be afraid to use flags, but be sure to make notes as to what flag is used for what. Lastly, hard flags are the only flags entities with flags 800 or 4000 set respond to. Skip FlagsSkip flags function EXACTLY the same as hard flags, with the exception that they are not saved to Profile.dat EVER. The 3 commands used are: <SK+, <SK-, and <SKJ. These commands have identical syntax to the hard flag commands. Skip flags are used for just that - to skip an event. Generally used in long-winded dialogues before boss fights to allow the dialogue to be skipped or sped up. Generally, no notes are needed for skip flags as their temporary nature allows you to get away with duplicate instances. Map FlagsMap flags are a type of flag discovered by yours truly. Their use is limited, however, to essentially marking areas the PC has visited. There are 2 commands associated with map flags: <MP+ and <MPJ. Note the lack of a command to unset these flags. These are permanent and saved, so keep that in mind. Other than the lack of unsetting ability, they function the same as hard or skip flags with the exception that you are limited to one map flag per map, and that the jump command (<MPJ) assumes it's looking for the flag for the current map (so the format is <MPJXXXX, where X is the event to run if the flag is set). Map flags can be set from anywhere for any level (eg. You can set the map flag for map 0043 from an event in map 0001). For example: #0100 #0101 As a general rule, map flags are limited in their usefulness except for, say, a mapping system that only allows you to view the map if you reach a certain point. Equip FlagsEquip flags aren't totally in line with the other flag types listed, but are included here for organization. These flags only have 2 commands associated with them: <EQ+ and <EQ- - There is no jump for these flags. To achieve a jump-if-equipped, use a hard flag in addition to setting the equip flag. You can use the hard flag for the actual jump, then. But what equip flags do provide, as their name suggests, are equipable items. The following are the ONLY valid values - Any others will do nothing. 0001 - Booster v0.8 Equipment can be added by any event, and you don't technically have to even have an item associated. Of special note are the Boosters - If 0032 is set then 0001 is ignored entirely. As well, equipping the Nikumaru Counter (0256) will start the timer and unequipping it will stop and reset it. To actually save the time recorded, use <STC. The Basics: Items and WeaponsThese are grouped together for the similarity of their mechanics and that they both appear in the inventory screen. In addition, they share a common command - <GIT. For details on <GIT, please refer to the full TSC notes. Weapons - Getting, Losing, Trading and UpgradingTo get a weapon: <AM+XXXX:YYYY - X is the weapon ID, Y is
the ammo you wish to set it to. To not let your cowboy into the bar because he's holding a 6-shooter: #0100 #0101 (Note: Weapon ID 0002 is the Polar Star) Items - Getting, Losing, TradingTo get an item: <IT+XXXX - X is the ID To not let a Leper into the city because he's carrying Leprosy: #0100 #0101 (Note: Assumes item 0003 is Leprosy) Using Items as FlagsIn order to save flags (they can become scarce in a long or complicated mod), you can use an item as a pseudo-flag. This is especially useful with items like keys or passwords. Weapons can also be used, though I'll leave you to figure out why a bar won't let you in if you're holding a gun. The Basics: EntitiesThis section details the flags that the various entities can have set. This only covers the basic, global ones - Some entities have special flags and things they do. What is an Entity?An entity is an object on the map that can be interacted with by the PC in one or several ways - enemies, save points and weapon energy are all entities. When editing an entity in Cave Editor, the following screen can be seen: The section highlighted in red is the portion relating to entities. Of note here:
Flag 2000This will be your go-to flag from most script/entity interaction. For starters, it will be the flag you set on all doors (usually) and any save points etc. Second, this will set the entity to be non-hostile - less used but still useful. If an enemy doesn't damage you, it probably has this flag set. The event called is the Event # associated with the entity. Flag 200Also called the boss flag, as that is one of its primary uses. It causes the entity to call Event # when it is killed. By setting every enemy to this and linking it to a global experience script in head.tsc, you could create an RPG-esque level-up system. Or something. Flags 100For the majority of entities, setting this flag will cause it to run a script on PC touch. This could be used with items to allow for automatic pick-up. Some entities, however, behave differently when this is set. Flag 1000This flag is for custom things and varies by-entity. Some entities will only animate if it is set, or will behave differently when this is set. Some entities have a second appearance accessible by setting flag 1000. Flags 800 and 8000These are two very useful things on an entity. Basically, it cause the game to check if a flag matching Entity ID is set. If it is, the entity is set (in)visible. An example of this is the Jellyfish in Grasstown - they only appear after you talk to Chaco. Setting both will result in 8000 winning out - 800 will be ignored. Other FlagsThe ones I've elaborated on are just the most useful. The other flags can be fun to play with, so feel free to experiment with different combinations. The Basics: Lyger's PartThe following series of images was created by friend and fellow forum-goer Lyger. As he has disappeared from reality at the moment, I am not sure if permission is given to use them, but I am hoping that it has been. I have included them here for two reasons: The first is that they provide a handy reference for map design and text-box information, and to back them up for future note (as Lyger's Photobucket is suspended as of writing). As well, seeing as the information was already well written and demonstrated, I figure I'd avoid creating duplicate works. As these may prove useful to many people:[Download all 3 images in a RAR] The Basics: Getting AroundThis section outlines how to get around, and look good while doing it. Inter-Map TravelThere is only one command to do this, <TRA. And it's a clunker - requiring 4 arguments. This is a case best suited for example. So: Example 1: Script on map 0000: Script on map 0001: This is the most basic example possible. It literally takes you from map 0000 and drops you into map 0001. No fades, no fancy sounds, nothing. So how can we spice this up? Well, we could add a couple fades, and consult the handy-dandy Table of Directions! to help us. Example 2: Script on map 0000: Script on map 0001: If you haven't guessed, this example has fades. More exactly, fade 0004 (both in and out). In the case of fading, you can use direction 0004 to fade in/out to/from the center. But what if that was a door we walked through? Wouldn't it make a noise? I assume you know how the <SOU command works, so we can skip this example. So instead, lets run a complicated script. Example 3: Script on map 0000: Script on map 0001: Let's parse this, shall we? First, you'll notice that I've added a few commands not mentioned in this document. These (<ZAM, <CNP) are detailed in the TSC Notes, so we can suffice to say they do cool things for now. However, there are a couple of commands I will go over: <HMC and <SMC. <HMC hides your character, and can be used to simulate going through a door or vanishing. <SMC does the opposite - It shows the PC. Ignoring the fancy add-ons, this is essentially the same script as example 1. That's the beauty of <TRA - It's really all you need. Everything else is icing on the cake. Look, Over There! *Kicks*Want the PC to look to the left and then to the right for an epic dance? It's as easy as adding <MYD0000 and <MYD0002 somewhere in your script. Keep in mind that a <PRI will delay it working until <END, so try to use this with <KEY if possible. To spice up that dance, you can add a <MYB0000, <MYB0002 and <MYB0001 which will knock you to the right, to the left, and straight up respectively. The directions for <MYB are a *little* goofed - Just remember that 0000 bumps you FROM the LEFT and 0002 bumps you FROM the RIGHT. Again, Table of Directions! can help. Table of Directions!This table lists the direction codes used by several TSC commands
* Only works with <FAI/<FAO Intra-Map TravelThere's two ways you can move the PC around the map locally - The lame, long, boring way of using <TRA and pointing to the same map, or the <MOV command. There are few commands simpler than <MOV - Just plug in your X and Y destination and off you go. Just remember to include all 4 digits or you can end up a thousand blocks off course. The Basics: Common EntitiesThis is a list of entities commonly used for various things - Things such as doors and save points:
The entities listed here are those that are common in 2 regards: First that they are commonly used, and second that they can be used on ANY map. The majority of entities (enemies, in particular) are associated to a specific sprite set. As a map can only have 2 sprite sets attached to it, it's good to know a few global ones. The Basics: Bringing It All TogetherThe following is an example of a starting map. Of note: Event #0200 is the default event that is run when the game is started. In original Cave Story, this event is the "From somewhere, a transmission..." scene. Illustrated in this are several commands not discussed in this document - Refer to the TSC Notes for further detail. With the recent influx of new modders making new mods, I figure I'd give them a break and host these few basic TSC scripts for functions common to most mods. They are very, very basic, only expanding a little into flags, but, with a few changes to the numbers provided in the examples, you can use these for many, many things. I may expand to include a teleports script and a few others, such as a pitfall trap or a basic boss fight. I don't intend to make this a script-mart for easy scripts, I intend this to be a dissection of the basic functions, as well as a learning tool. The scripts, while *theoretically* just usable as a copy-and-paste idea, will probably have to have a few values changed (and thus learn what the values do). I encourage those reading this to a.) view my organized and fully-explained TSC notes found here and b.) experiment with everything.
Example #1: Starting MapThe Script: #0090 #0100 #0102 #0200 Entities used: The door is event #0100 with flag 2000 set, the chest is event #0102 with flag 2000 and 4000 set with an entity ID of 100. A treasure chest (open) entity one tile above the closed chest has flags 2000, 1000 and 800 set and is event #0001 (global "Empty..." message) with an entity ID of 100. Explanation: The above is explained in its comments. This is for two reasons: a.) The script is of enough length to warrant comments and b.) It demonstrates correct comment placement. The following examples are explained in the explanation section. Example #2: Basic Door (Inter-map)The Script (Map 0000): #0100 The Script (Map 0001): Entities used: Explanation: Example #3: Basic Door (Intra-map)The Script: #0100 #0101 Entities used: Explanation: Example #4: Locking Inter-map Door (Item)The Script: #0100 #0101 Entities used: Explanation: Example #5: Locking Intra-map Door (Item)The Script: #0100 #0101 #0102 Entities used: Explanation: Example #6: Lock-if-has (Inter)The Script: #0100 #0101 #0102 Entities used: Explanation: Example #7: Chest (Basic)The Script: #0100 #0101 Entities used: Explanation: Example #8: Teleporter (Intra)The Script (Intra): #0101 #0103 Entities Used: Explaination: The Basics: Graphic Editing TipsThis is a reference for important points in graphic editing. Of importance is that images are not limited to any specific colors in an external editor (Cave Editor limits you to a few) - You can convert all PBM/BMP files to 24 bit if you want - Though this will increase the file size significantly. Sprite and Tile DimensionsFirstly, the difference between a sprite and a tile: A tile is a section of the map, a sprite is the graphic for an entity. Tiles are ALWAYS 16 by 16 pixels and are stored in CS Directory/data/stage as Prt[TilesetName].pbm (or .bmp). To figure out how many tiles can fit on a map, divide the width and height by 16. If you get a fractional number, adjust the dimensions to be evenly divisible by 16. Sprites vary. A lot. As a general rule they are at least 16 by 16, but there are some extremely massive sprites (Balfrog, The Core). As an additional guide, the dimensions will usually be divisible by 8, so a 24 x 24 sprite is possible. The two global spritesheets are found in CS Directory/data, with the other entity sheets stored in /Npc. The "(C)Pixel" RequirementAs a means of preventing random goofing around with the game files, Pixel included a check in the game to verify if the images have been tampered with. This is accomplished by a hex string appended to the end of image files. Because of the way bitmaps save, if the image is edited the appended hex string is lost, and therefore will error out when the game tries to load it. I won't discuss how to use a hex editor to re-append the "(C)Pixel" string to the end of an image; I'll leave that to you to try. Built into Cave Editor is a way around this, though. In fact, 2 ways. The first is the manual way: You can edit images in CE's built-in editor. It will automatically append the required string. However, if you want to use an external editor, I suggest checking the "Remove (C)Pixel requirement for Images" box, like so:
Using BMP ImagesIf you wish to use *.bmp as your image extension, just change the file extension in CE. It will automatically change all the *.PBMs into *.BMPs. On a side note, *.pbm and *.bmp are the same format - Bitmap Image - Pixel probably chose to use *.pbm for the same reason as using the (C)Pixel string.
Advanced Stuff
|
TSC Code
|
<Un>Official Title
|
Resource Name
|
0000
|
<None>
|
XXXX
|
0001
|
Mischevious Robot
|
WANPAKU
|
0002
|
Safety
|
ANZEN
|
0003
|
<Game Over>
|
GAMEOVER
|
0004
|
Gravity
|
GRAVITY
|
0005
|
On To Grasstown
|
WEED
|
0006
|
Meltdown 2
|
MDOWN2
|
0007
|
Eyes of Flame
|
FIREEYE
|
0008
|
Gestation
|
VIVI
|
0009
|
Mimiga Town
|
MURA
|
0010
|
<Get Item>
|
FANFALE1
|
0011
|
Balrog's Theme
|
GINSUKE
|
0012
|
Cemetary
|
CEMETARY
|
0013
|
Plant
|
PLANT
|
0014
|
Pulse
|
KODOU
|
0015
|
<Boss Defeated>
|
FANFALE3
|
0016
|
<Get Life Capsule>
|
FANFALE2
|
0017
|
Tyrant
|
DR
|
0018
|
Run!
|
ESCAPE
|
0019
|
Jenka 1
|
JENKA
|
0020
|
Labyrinth Fight
|
MAZE
|
0021
|
Access
|
ACCESS
|
0022
|
Opression
|
IRONH
|
0023
|
Geothermal
|
GRAND
|
0024
|
Cave Story
|
CURLY
|
0025
|
Moonsong
|
OSIDE
|
0026
|
Hero's End
|
REQUIUM
|
0027
|
Scorching Back
|
WANPAK2
|
0028
|
Quiet
|
QUIET
|
0029
|
Final Cave
|
LASTCAVE
|
0030
|
Balcony
|
BALCONY
|
0031
|
Charge
|
LSTBTL
|
0032
|
Last Battle
|
LSTBT3
|
0033
|
The Way Back Home
|
ENDING
|
0034
|
Zombie
|
ZONBIE
|
0035
|
Break Down
|
BDOWN
|
0036
|
Running Hell
|
HELL
|
0037
|
Jenka 2
|
JENKA2
|
0038
|
Living Waterway
|
MARINE
|
0039
|
Seal Chamber
|
BALLOS
|
0040
|
Toroko's Theme
|
TOROKO
|
0041
|
<King's Theme>
|
WHITE
|
This is all fine and handy and all, but it doesn't tell you how to actually replace the resources. To that, you'll need Resource Hacker or a similar program. Once you have that, replacing music (or any resource, really) is as simple as the following steps.
Instructions
|
Screenshot
|
Step 1: Open the CS executable you wish
to swap the music in.
|
|
Step
2: Open the "ORG" resource catagory and find the song you wish to
replace (according to the table above. ACCESS is my example. Take note
of the name.
|
|
Step 3: Under the action menu select
"Replace Other Resource..."
|
|
Step
4: A dialogue will pop up. To begin, press "Open file with new
resource" and find the song you wish to import. The dialogue will
change to the one on the right; enter the information exactly as you
see it, replacing Resource name with the name of the track you're
replacing (Eg. Access). Press the replace button, then goto file >
save to save the EXE.
|
|
This guide is not a replacement for learning. To succeed, you will have to study the references provided, but more over experiment. What I hope I have left you with are the tools to figure out the rest. Following are a couple miscellaneous tips for improving your mod.
FPS Counter