================================================================================ == The SMTC Scripting Intro Guide == ================================================================================ This guide is designed to help you new fellas use the premade scripter engine for making your own custom intros! Bear in mind that wussy people will not have the patience for making long intros. So, make one only if you're designing a full blown quest. Contact: saltyjustice@hotmail.com www.supermetroidclassic.com Seriously, that's where you should have got this from anyway. ================================================================================ Table of Contents Short Tutorial Appendix A - Function Listing Appendix B - Argument Definitions Appendix C - Character Movement Index ================================================================================ Short Tutorial Okay, first up, you will need to understand where this script engine is used. When you start a new game of Super Metroid, you see Samus in a close up, explaining the plot. You also see black and white action scenes of Samus shooting stuff and moving around. These scenes are where the scripts are used. Pretty esoteric, huh? Well, to begin, each line of script ends with an enter press (character 13). To end each line, press enter or return, and the script will know that's the line. Simple as that. If a line is invalid (has something illegal on it) then the engine will skip to the next line without doing anything. To determine bugs like this, use the PAUSE function (outlined in the appendix later) to stop the program and observe the script. Each line functions totally independently of all the other lines. Some simple functions are given here, but more are in appendix A. For our examples, we will use DSam(x, y, index) and FRAMEUP. Each script is composed of a series of frames. Some frames are really long, but remember that each frame is the same length of time regardless of how many lines of script it is. The way to move to the next frame is the FRAMEUP code. This will cause the program to draw everything to the screen, then clear the bitmap and move the program ahead by one frame. If your script has no FRAMEUP lines in it, it will only be one frame long. Not very handy is it? During each frame, you are expected to draw stuff to the screen. This is easy enough, since all the drawing functions are listed for you, and most just expect an X, Y and Index. First, you should remember that the X and Y system uses an inverse Y on the screen. That is, the upper left hand corner of the screen is 0,0 and as you move down, Y increases. X increases as you move right. Now then, let's show some example script. DSam(100, 100, 29) //Draw Samus frame #29 for one frame FRAMEUP DSam(100, 100, 30) FRAMEUP DSam(100, 100, 31) FRAMEUP DSam(100, 100, 30) FRAMEUP This is the code to draw Samus' different breathing animations. Some things to remember: Each frame is 1/60 seconds. That is, 15 frames is 1/4 of a second, and 30 is 1/2. It seems like it'd be kind of repetetive to manually increase the frames 60 times for one second, and to draw the necessary bitmaps all 60 times. That's why there are shortcuts for you. Most of the Drawing functions begin with DName, like DSam above. If you want to draw a picture for a certain number of frames, then use the DFSam function. Likewise, you can use the FRAMEUPNO ### function. Example: DFSam(100, 100, 29, 15, 0) //Draw Samus frame 29 for 15 frames after this FRAMEUPNO 015 //Increase frame count by 15 DFSam(100, 100, 30, 15, 0) //Draw Samus frame 30 for 15 frames after this FRAMEUPNO 015 DFSam(100, 100, 31, 15, 0) //Draw Samus frame 31 for 15 frames after this FRAMEUPNO 015 DFSam(100, 100, 30, 15, 0) //Draw Samus frame 30 for 15 frames after this FRAMEUPNO 015 Those eight lines are one second of data. Note the // stuff at the end of some lines. These are comment lines. They MUST be placed after any code on the line (this way, the engine will ignore it) or on blank lines (so the engine will skip it). Just don't place them before code and there won't be a problem. Some things to notice here too. FRAMEUPNO 015 does not need the preceding 0 in it. The max number of Frames you may skip are 999 in one go (just use multiple FRAMEUPNO's to skip more) but you don't need the extra zeroes. If you use FRAMEUPNO 1 then the engine will assume you meant 1 frame. Not too complicated. In the same way, the second last variable of DFSam is the number of frames to draw it for. In case you didn't know anything about functions, the brackets ( and ) indicate the beginning and end of the function. Each value you pass into it is seperated by a comma. If a function expects four arguments and you pass in five, it will assume that something is wrong and ignore the last argument. If it requires four and you pass in three, it will assume something is wrong and not do the function at all correctly. Watch for errors! Summary: Do not pass in fewer arguments than the function expects. More is okay, but don't make it a habit. Anyway, you may be wondering now just what these values mean on DFSam. While the appendix gives a list, it ain't too helpful. The first two are an X and Y listing. Those are just where the Samus picture will be drawn on the screen. The third is the frame index, which you can look at in appendix C, the sam frame index. The last one is the number of frames to perform this action for. You should probably note that if you call DFSam to do 15 frames, then call it again before those 15 frames are done, then you will see two Samus' on screen! So be careful what you type. Each drawing function has 32 timers alloted to it. That is, you may have up to 32 Samus' on screen at once. That should be all you need to know for making simple scripts. See appendix A for function listing, appendix B for argument definitions, and appendix C for enemy and Samus frame lists (appendix C also refers to a bitmap which should come with this document) That's all. Email me at saltyjustice@hotmail.com if you have questions, or post on our message board! ================================================================================ == Appendix A: Function Listing == ================================================================================ Note: To all you scripters (all two of you), check this area at each new SMTC release, since there will probably be some new functions to use. /* Velocity and Acceleration Functions */ Notes: Ordinarily, the DFSam and related functions fix Samus at a specific location. That's all well and good, but you'd have a hell of a time animating a moving Samus like that. Luckily, there's these functions that let you alter Samus' x and y position automatically in the program. Sam_Velocity(xspeed, yspeed, slot) This changes Samus' velocity to the passed variables. Every frame up, the x and y position are increased (or decreased, if you pass a negative) by the appropriate speeds. This lets you make Samus move around the screen as though she were running or jumping. Sam_Accel(xaccel, yaccel, slot) This changes Samus' accelleration to the passed variables. Every frame up, the xspeed and yspeed and changed by the accels. This is chiefly used to make Samus feel gravity, but you can always use it for other stuff. Sam_Velocity_Cap(xspeedcaplow, xspeedcaphigh, yspeedcaplow, yspeedcaphigh, slot) Use this to set the maximum and minimum speeds that Samus can accelerate to. This allows you to not have to manage the Accel function like you normally would. For left or up movement, the low cap should be negative. For right and down, it should be positive. All of these functions accept decimal places up to three long. Gravity is, in SMTC, 1/8 or 0.125. The speed Samus normally runs at is 4, and speed boosting is 9-10. When Samus jumps, her speed is -5. If you do not use these functions in a script, the speeds and accelerations default to 0. /* Screen and Timer Functions */ BEGINTYPESET Instructs the script to enter text mode. This will cause everything you type afterwards until ENDTYPESET to be shown as green text displayed over the background. ENDTYPESET Instructs the script to exit text mode. SETSAMBG Sets the background picture to Samus' close up helmet with blinking. This will override any previous background statements you made. WAITBLINK Causes the program to wait until the user presses a key, but still display the green blinking cursor. Used for text mode stuff. PAUSE Stop the program until you press any key. Handy for observing what is on the screen for debugging. SCREENDUMP Dump all data to the screen without clearing the buffer or advancing the frame. Also used primarily for debugging. FRAMEUP Increase the frame counter by one. Each frame is 1/60th of a second. FRAMEUPNO ### Increase the frame counter by ### frames. Nothing can be done between these frame ups, they go automatically. SETCOLS # Change the colour mode. Handy for the flashback scenes, when it's grayscale. The values are: 0: Grayscale 1: Regular 2: Inverted RGB 3: RG Swap 4: RB Swap 5: GB Swap 6: RG Swap Inverted 7: RB Swap Inverted 8: GB Swap Inverted Inverted RGB uses 256-r, 256-g, 256-b instead of r,g,b. It produces some interesting effects. These are filtered options, so they WILL slow the game down. Note that the changed cols take place right before the buffer is printed to the screen, so it will affect backgrounds and objects alike. /* Drawing Functions */ DSam(x, y, index) DFSam(x, y, index, frames, slot) CLBufSamAll CLBufSam(slot) Draw Samus at [x] and [y] by the provided [index]. The [index values] are detailed in appendix C. The DFSam version allows you to specify the number of [frames] to buffer. CLBufSamAll is short for Clear the Samus Buffers. Simply put, this will make the script stop drawing all of the DFSam's that you have queued up. The [slot] lets you select which of the 32 slots (from 0-31) you want to store the draw in. DSamCycle(x, y, index1, index2, rate, frames, slot) Draws Samus in a cycle, starting at [index1], going to [index2]. Every time [rate] frames pass, the index will increase by 1. The cycle will run for [frames] (if frames is -1, it will run until told to stop by CLBufSam). This method will make Samus cycle from index1 to index2, then back down to index1, switching directions each time. DSamLoop(x, y, index1, index2, rate, frames, slot) Draws Samus in a cycle, basically identical to DSamCycle, except this function draws the indexes looping: index1-index2, index1-index2, etc. To make the frames scroll backwards, make index2 lower than index1, the script will handle the rest. DSamVaryCycle(x, y, index1, index2, frames, slot, rate1, rate2, ...) DSamVaryLoop(x, y, index1, index2, frames, slot, rate1, rate2, ...) The most complicated drawing functions, the same as the DSamCycle function above. However, this function lets you specify how many frames each index must be played for before cycling up. If you place a 0 in a spot, that index will not be displayed. If index2 is 3 and index1 is 0, then you have four indexes to display. As such, you must have four "rates" at the end of the function. Ex: DSamVaryCycle(50, 50, 0, 3, 500, 0, 3, 4, 2, 3) To determine how many rates you need, here is the formula. (index2 - index1) + 1 Always put the correct number of rates, or you will be screwed. /////////////////////////////////// NOTES ////////////////////////////////////// The DSam function is completely independent from the assorted cycle and loop functions. You may therefore have up to 33 Samuses on screen, if you really need that many. Come to think of it, 32 is a hell of a lot. Oh well. Also, any DSam you put on a frame will be overwritten by any DSams that follow it, making the first DSam a complete waste of time and energy. Just though I'd toss that out. Additionally, placing a new DFSam or other loop/cycle function in a slot that is already being used will overwrite whatever was in the slot, so you don't need to use CLBufSam to clear it first. Oh yeah! When using the two DSamVary functions, the max number of frames you can cycle through is 10, since that's the most running frames there are. If for some psychotic reason, you think that I need more (you commie) then put it on my forums and I'll increase the cap. If you make the number of frames exceed 10, then all following frames will be ignored (their rates are defaultedly 0, so it looks like they don't show) If you wish to carry over the previous value of x and y for your Samus' movements, pass in -100 for the values, and keep the slots the same. The values are carried over when you put -100 in for these. In addition, the velocity, acceleration, and speed caps are not reset(keep in mind you need to do that manually). //////////////////////////////////////////////////////////////////////////////// Create_CustBG("Path") Create a custom background using the script at "Path". The path is local to the Scripts directory and must be enclosed in quotes to function correctly. The function listing is located in Drawing.txt. Create a file with the same name as path in the Scripts folder and use the Drawing functions on it. Set_Fade(value) Set_BGFade(value) Set_Fade_In() Set_Fade_Out() Set_BGFade_In() Set_BGFade_Out() Set the fading value to the bracketed term. This value must be between 0(darkest) and 255 (lightest). BG fade will only affect the background. The Set_Fade_In/Out functions determine if the fading is in or out. It is in by default. Use this to make sure Regulate_Fade starts in the correct direction. Regulate_Fade(speedup, speeddown) Regulate_BGFade(speedup, speeddown) Stop_Regulated_Fade() Stop_Regulated_BGFade() Automatically fades in and out at speedup and speeddown, respectively. The stop command removes the regulating flag, but will not reset the fade value. For that, use Set_Fade or its BG equivalent. The regulation speed should be a divisible into 256, as the lowest is 0 and the max 255. Therefore, you can determine how fast the fade will be by dividing 256 by your speed. To take one second (60 frames) you'd need 4 (64 frames) which is close enough, apparantly. /* Spawn and Movement Functions */ Spawn_Rinka(x, y, xspeed, yspeed, slot) Del_Rinka(slot) Note: Rinkas are the small circle enemies near the Mother Brain. Accepted slots are 0-7. Spawn_Brain(x, y, slot) Del_Brain(slot) Note: The Mother Brain, in this case, is the small Brain from Metroid 1. Acceptable slots are 0-7. Spawn_Missile(x, y, dir, slot) Spawn_Missile_Life(x, y, dir, slot, frames) Del_Missile(slot) Note: Fires a regular missile from x, y. Dirs are listed in Appendix B. Spawn_Missile_Life will automatically delete the missile after the frames are expired. Acceptable slots are 0-7. Missiles travel horizontally/vertically at 5 pixels per frame(ppf). They travel diagonally at 3.5 ppf. Spawn_Explosion(x, y) Create an explosion. These automatically terminate themselves. /* Environment Functions */ Load_Env_Bg(path) Set the background for the intro Load_Room(area, number) Terminate_Room Notes: Area index can be found in Appendix B. This will load and display the tiles for that room starting on the left edge. These rooms observe some special rules as well. For example, they do not need to be clipped correctly, or be surrounded by clip zones, since Samus does not actually enter them. Terminate Room will stop drawing the loaded room, or allow you to load another. ================================================================================ Appendix B - Argument Definitions Notes: An argument is something that goes in a bracketed area, such as in a drawing function. Since many functions use the same type of argument, they are listed here for quick reference. x - The x position on the screen. 0 is the left, the value increases to the right. y - The y position on the screen. 0 is the top, the value increases downwards. xspeed - How fast to move horizontally, in pixels per frame. Negative is left, positive is right. This value is usually limited to two decimal places. yspeed - How fast to move vertically, in pixels per frame. Negative is up, positive is down. This value is usually limited to two decimal places. index - A number, defined in Appendix C, which denotes which frame to draw of a sprite. In the DSam case, the index can be used to draw running, shooting, etc. frames - How many frames to continue drawing this image. Positive numbers are accepted, 0 being "Draw until told to stop" and negative numbers will wreck the line. slot - Each object that you generate needs a slot to store its values. You can specify this slot, allowing you to manipulate the object with other functions. The accepted slot values are 0 to 31 (32 slots total). path - The usual pathname, like Scripts//Fix.bmp. The // denotes a single /, so be wary. The path is always local to the SMTC folder, so do not enter C://. dir - Direction of an object. Listed here: RIGHT = 0 LEFT = 1 UP = 2 DOWN = 3 UPRIGHT = 4 UPLEFT = 5 DOWNRIGHT = 6 DOWNLEFT = 7 Area Index: CRATERIA = 0 BRINSTAR = 1 NORFAIR = 2 MARIDIA = 3 WRECKEDSHIP = 4 TOURIAN = 5 ================================================================================ Appendix C - Index for Frames Notes: Only some frames are listed here. In the Samus case, you will be referred to a bitmap image which shows the frames and their indexes.