The bulk of the code for a Smash game will usually be the location files, that is, one code file for every location you have in your game. You need more than just the location files to get your game working, however. Smash requires certain other files to be present. Here is a list of what those files are and what must go in each.

(Note that all filenames should be in lower case characters. Upper case is disallowed in filenames and, therefore, location names, too.)

Required: game.txt

The game.txt file contains very basic information about your game. The first line of the file must contain the title of your game. This is the only required component of the file.

Lines after the first may be used to set the game's credits, synopsis, difficulty level, and/or Hall of Fame parameters. As long as these lines appear after the first line of the file, they can appear in any order. Each such line starts with one letter and a colon. The various lines of this type that you can have are documented as follows:

• Credit lines start with c: and specify the credits for the game. Each line will appear with line breaks between them, so you do not need to use HTML tags to create line breaks. Here is an example game.txt file that makes use of credit lines:

  Space Adventure c:By Snook Draddots c:Based on characters created by Ignatz Pluckskin

• Synopsis lines start with s: or S: and specify a brief description of the game, similar to the blurbs found on the backs of paperbacks and DVD cases. The simplest way to do this is just to use s: lines, but S: lines may be used if you want to support both a short and long synopsis. In a nutshell, s: lines will appear in both the short and long synopses, while S: lines will only appear in the long synopsis. Here are two sample game.txt files, one that only uses s: lines and one that uses both s: and S: lines:

  Space Adventure s:Travel through space and time on an epic s:adventure! Search for the Great Celestial Cookie and s:establish sugar mining facilities on its surface! s:But beware the lurking menace of the evil Space Dentures, s:which are also searching madly for the Great Celestial Cookie s:with the hope of chewing it up into tiny little pieces. It's s:an unforgettable race against time!

  Space Adventure s:Travel through space and time on an epic s:adventure! Search for the Great Celestial Cookie and s:establish sugar mining facilities on its surface! s:But beware the lurking menace of the evil Space Dentures, s:which are also searching madly for the Great Celestial Cookie s:with the hope of chewing it up to tiny little pieces. It's s:an unforgettable race against time! S:Space Adventure features hours of play, challenging puzzles, S:dozens of interactive characters, and four exciting worlds to S:explore!

• The difficulty line starts with d: and lets you specify a difficulty rating for the game. This rating should normally be between 1 and 10, but Smash only requires that the value be a whole number. Here is an example game.txt file that makes use of a difficulty line:

  Space Adventure d:6

• Hall of Fame lines start with h: and let you specify that you would like your game to have a Hall of Fame and also what columns you would like to have on it. If no Hall of Fame lines appear in a game.txt file, then the game will not support a Hall of Fame. Most games should support a Hall of Fame, but there may be rare instances where a Hall of Fame is not appropriate. For example, The Trainer is a small, easy demo game that illustrates some of the potential of the Smash engine. There is no Hall of Fame for The Trainer. It's too easy to warrant one, and if it had one it would be an unmanageable size anyway, as thousands of people have completed it.

  If the game.txt file has only an empty Hall of Fame line (that is, h: on a line with nothing after it), then the game will have a Hall of Fame with the default columns, namely: Name, Moves, and Date. This will be sufficient for many games.

  If you want to add extra columns to the Hall of Fame (such as "Score"), then one h: line should be used for each additional Hall of Fame column. For example, the line h:Score would add a "Score" column to the Hall of Fame. Be aware that if you define any extra columns for your Hall of Fame, you'll need to supply the information that should go into each of these columns in the w (or W) commands you issue to end the game. If the fields in your game.txt file don't match up with the data supplied with your w and W commands, the game won't function properly!

  Unless you have defined extra Hall of Fame columns for your game, you can skip the rest of this section.

  There's a slight hiccup associated with adding columns to the Hall of Fame, and that is that when you view the Hall of Fame and try to sort it on one of the new columns, you might want to sort them differently from the default way. By default, extra columns that you define will be sorted numerically, in descending order. This is perfect if you have defined a "Score" column, which gives the number of points each player finished with: all the highest scoring players are listed at the top.

  But what if you were writing the "Military Ascension" game, given above, where one of the extra columns is "Demerits"? Presumably, the best performing players receive the fewest demerits, so you want to sort the Hall of Fame in ascending order (lowest first) rather than descending order.

  Furthermore, the extra field "Rank" might indicate what military rank (General, Colonel, Major, etc) you achieve in the game. These ranks cannot be sorted numerically, or even alphabetically.

  If you have special sorting needs (i.e., anything other than "descending numerical") for the extra Hall of Fame columns you define, then you can specify sorting instructions on the h: lines for those columns. Simply append a pipe ("|") character to the line and then fill in a sorting code. The sorting codes are as follows:

  Code	Meaning
  n<	Descending Numeric
  n>	Ascending Numeric
  a<	Descending Alphabetic
  a>	Ascending Alphabetic

  This takes care of every situation except in situations that require a custom sorting scheme, such as the aforementioned military rank column. When you have something like this, which requires a custom sorting scheme, then you simply list out all possible values that can appear in that column, in order, each separated by a pipe character. Here is an example of what the game.txt might look like for our theoretical Military Ascension game:

  Military Ascension h:Score h:Demerits|n> h:Rank|General|Colonel|Major|Captain|Lieutenant|Sergeant|Private

  Note that the "Score" column does not need to be explicitly listed as sorted in descending numerical order, because this is the default sorting scheme.

Here are some typical game.txt files that you might have with your game:

Sonny Bumpkin's Wild Tractor Ride c:By Samuel Stoddard s:Careen through 16 amazing levels of fun! Dodge s:squirrels and potholes on your race to the chicken farm! h:

Reach For the Stars s:How high can you go? d:4 h:Height h:Crash Landings|n>

Required: start.sma

The start.sma file is a file containing the Smash code that is executed when a new player first starts up a Smash game. Almost any Smash code can appear here. Minimally, there must be a g command, to indicate what location the player starts out in. If there is no g command in your start file, the game will not work.

Frequently the start file will also contain a p command, to display an introduction to the game or some initial instructions to the new players. You might also set the initial values of any global variables or timers that need to be initialized to values other than zero. (All variables are initialized to zero by default.)

You might also use the start file to set initial status lines, or hide certain constant options (see below) that you don't want to be initially available to the player.

Note: You cannot assign state variables in the start file. The reason is that when the start file is executed, the player has not yet been placed at a location within the game (even if you're at a point in the start file that's after a g command!), so there is no location to attach the state variable to. Furthermore, note that if you make use of a scoped state variable within an expression, it will always resolve to zero, because no state variables could have been defined by this point.

Optional: copts.sma

If you want your game to have any "constant options" -- that is, menu options that are (at least mostly) always available, no matter where the player is in the game -- then you must have a copts.sma file where these constant options are defined.

The copts.sma file may only contain constant option blocks and function blocks. A constant option block is a @ command for each constant option and the block of code to be executed when it is selected. Any and all constant options defined in the copts.sma file will be initially visible to the player by default. If you want to have one or more constant options initially hidden from the user, the appropriate @ - commands should be given in the start.sma file.

Note that if you refer to unscoped state variables within a constant option block, it will look at the state variables attached to the current location. Since constant options can typically be chosen from just about any location in the game, this could mean referring to a different variable of the same name each time the option is selected. It's possible you might want to achieve exactly this behavior, but not unless you know what you're doing. In general, don't refer to unscoped state variables from the copts.sma file.

Optional: repeatpre.sma and repeatpost.sma

If you have code you'd like to execute every turn, you can put it in repeatpre.sma or repeatpost.sma, and it'll automatically execute every move. Most games probably won't have a need for these files, but for those games that do, it saves a lot of bug-prone coding to make use of them.

The only difference between the two is when they execute. repeatpre.sma executes after the move code executes but before the location code executes. repeatpost.sma executes after the location code executes. See the page on Program Flow for further information.

Note: You cannot assign state variables in the repeat files.

Optional: admin.sma

admin.sma can be used as a regular .sma file, but it is recommended to reserve its use for a series of debugging or game analysis functions. While not a requirement of the Smash language, some Smash engines provide the ability to load existing saved games, run a function in admin.sma, and display the results -- without saving the existing saved game at all.

This provides game designers with the ability to write functions that figure out where players are in the game. It can be particularly useful when a player wants a hint about what to do next but the author doesn't know what's been done and what hasn't been done. An admin.sma function could be used to check variables and inventory and use the area and/or action description texts to print out information about where the player is in the game and what should be done next.

Optional: objects.txt

If you have any carryable objects in your game (regular objects, not enumerated), then you will need to have an objects.txt file that lists what these objects are. The format of the file is fairly simple. Each line contains information about one item in the game. You need as many lines in the file as there are regular objects in the game.

The contents of the file should look like this:

coin|Gold Coin choc|Box of Chocolates canoe|Wooden Canoe

Each line starts with the object's tag, which is a short string made up of letters, numbers, and/or underscores. It does not matter what this string is, so long as it is different from the object tags of all the other regular objects. For readability, you should pick something that reminds you what the object is. This tag is what you use to refer to the object in your code, for example in a and d commands (which add and drop items from the player's inventory).

After the tag comes a | (an "or bar" or a "pipe"), and then comes the string that will be shown to the player when his current inventory is displayed.

If (and only if) you have an objects.txt file, you will also need an objectactions.sma file that defines what should happen when a player selects one of the items in his inventory:

Optional: objectactions.sma

The objectactions.sma file is a file containing Smash code. Although you can have other code in this file as well, and it can even double as a location within your game, it is strongly recommended, for readability, that you only use this file to store one function for each object in your objects.txt file, which defines what should happen when a player selects an object in his inventory.

Each function should be named after the object tag of a corresponding object. Normally, all these functions should do is display a description of the object. Sometimes you might want to display an image of the object as well. But depending on the needs of your game, you could have other things happen also.

Here is a sample objectactions.sma file for the sample objects.txt file given above:

~ coin p It is shiny. ~ choc p The chocolates look tasty, though perhaps aged a bit beyond the expiration date. Some of them have thumb imprints on the bottom, from when someone tried to sneak a peek at the fillings inside. ~ canoe i canoe.jpg p It's a hefty, unwieldy canoe to be carrying around everywhere you go.

Optional: eobjects.txt

The eobjects.txt file serves the same purpose as the objects.txt file, except for enumerated objects rather than regular objects. Enumerated objects are those objects you can have one or more of. In the example above, we defined "coin" as one of your inventory objects. But if you could, at various points in your game, have one coin, two coins, five coins, or any other number of coins, you can accomplish this by defining the coins as an enumerated object.

The contents of the eobjects.txt file is similar to that of the objects.txt file except that it contains one extra field:

coins|Gold Coin|Gold Coins picks|Guitar Pick|Guitar Picks keyrings|Key Ring|Key Rings

The first field in each line is the tag of the enumerated object, that string which will refer to the object in your Smash code, such as in e commands. The second field is the singular form of the object as it will be displayed to the user. The third field is the plural form. Smash will determine for itself whether it should display the singular form or the plural form at any given time. Note that it doesn't matter whether the tag is singular or plural: it will only ever be used in code, so it doesn't really matter. Technically, the tag doesn't even need to be an English word. You may find it useful, however, to adopt the convention of using plural words for enumerated object tags.

If you have an eobjects.txt file, you must also have a corresponding eobjectactions.sma file, to define what occurs when the user selects an enumerated object from his inventory:

Optional: eobjectactions.sma

Like the objectactions.sma file, the eobjectactions.sma file contains Smash code. Normally, it will just contain one function per enumerated object, each function named with the enumerated object tag of the enumerated object it refers to.

Again, normally you simply want to display a description when a player selects an object from his inventory. Since you can usually have any number of enumerated objects, however, you may find you need a singular version of the description as well as a plural version. To illustrate how you can accomplish this, here's a sample eobjectactions.sma file for the sample eobjects.txt file given above:

~ coins c e:coins = 1 p It is shiny. C p They are shiny. ~ picks c e:picks = 1 p It's just a bit of cheap plastic. C p They're just bits of cheap plastic. ~ keyrings c e:keyrings = 1 p The key ring seems ordinary. It jingles C p They seem ordinary. They jingle P in your pocket every time you take a step. You wonder if the noise is attracting too much attention to yourself. i keyrings.jpg

Optional: lose.txt

If you have a lose.txt file, its contents will be displayed to the player when he does something in the game to cause him to lose -- i.e., whenever an l command is encountered in your Smash code.

The lose.txt can be free-form text, including HTML tags if you wish to use them. Note that the contents of this file will always be displayed when the player loses the game. If you want different things to be displayed based on where and how the player loses, this should be done with action description text (set by p commands).

Within the lose.txt file, you can use []s to display images in the same way that images can be embedded in area and action description texts. You can also use {}s to evaluate expressions; however, note that any functions called with the f: operator within {}s in the lose.txt file may not execute commands that alter the state of the game.

Optional: win.txt

This file works precisely like the lose.txt, except its contents are displayed when the player wins the game.

Within the win.txt file, you can use []s to display images in the same way that images can be embedded in area and action description texts. You can also use {}s to evaluate expressions; however, note that any functions called with the f: operator within {}s in the win.txt file may not execute commands that alter the state of the game.

Optional: hints.txt

If you wish to have hints for your game, you can list a series of questions and answers in a hints.txt file. Whatever hints you supply in this file will be freely viewable by anyone, no matter where they are in the game, so be careful not to supply too many spoilers. The format of the file is fairly simple: separate each problem/hint pair with two hyphens on its own line, and separate a problem from its hint with a blank line. An example follows:

How do I get past the three-armed crazy man? Try finding something that will restrain his deadly whirling limbs. -- I've been to the store, the farm, the amusement park, and the restroom, but I can't find anything that the travelling salesman wants to buy from me! Keep poking around the amusement park. -- Every time I start up the jacuzzi, poison chlorine gas fills the stadium, and everyone dies from asphyxiation! How am I supposed to relax my tense muscles? Try to rig up a mechanical device with the door hinge, the rubber bands, the pillow, the firecrackers, and the honeydipper.

Optional: graphic.gif

If you want your game to have a title graphic, it needs to be a GIF file called graphic.gif. This will be displayed while the game is being played. If you do not supply a graphic.gif file, the Smash engine/interpreter will display the game's title in whatever way it deems appropriate.

Optional: Other Image Files

Obviously you must provide any and all image files that you refer to in the code of your game. These files may be JPG files, GIF files, or PNG files.

Use of images is optional. It's perfectly all right to make a game that does not use any images. But, of course, nice images can add to the flavor of a game.