Enabled sound effects in SDK, added to example game, stub in engine

Author: SlithyMatt

README.md

@@ -742,6 +742,7 @@ Technically, levels don't have any specifically required keys. Not even a bitmap
 
 * **bitmap** - Filename of the level background bitmap, which should be an indexed 16-color 320x200 raw image file. It should have a raw 24-bit palette file that has the same filename appended with ```.pal```. If that file is not available, the bitmap will use the default palette, offset 0. It will be converted to X16 format and stored across 4 banks of banked RAM when that level's zone is loaded. The starting bank is based on the level number. Using N for the level number, it will be stored in banks 6N+2 through 6N+5. So, that would be banks 2-5 for level 0 (loaded from **Z000L0.02.BIN** for zone 0, for example), banks 8-11 for level 1 and so on up to banks 56-59 for level 9. The palette for this bitmap will be written to palette offset N+1 (e.g. level 0 = palette offset 1) when the level's zone is loaded.
 * **music** - Filename of the level music VGM file. It is converted into a more X16-friendly format and stored in bank that it shares with sound effects in banked RAM. Using N for the level number, that bank number will be 6N+6. So, level 0 of zone 0 music and sound effects would be loaded from **Z000L0.06.BIN** and stored in bank 6.
+* **sound** - Defines a sound effect. The first value is the identifier that will be used by the **play** key, and the second is the filename of the 4578 Hz signed 8-bit raw PCM file to play. As the music and sound effects are in the same bank for each level, the total number of sound effects used in each level must not exceed 8 kB when added to the size of the music file and a few extra bytes for a header. The header size will be 3 + 2(N+1) bytes where N is the number of sound files specified. In theory, up to 127 sound effects could be added to a level, but with only 8 kB available in total, even without music there would be room for only 1.79 seconds of sound effects.
 * **init** - This key is placed at the beginning of the level initialization sequence. It has no values. It will always be the first sequence run when the level is loaded. It must appear before any other sequences.
 * **first** - This key is placed at the beginning of the sequence that is run after initialization the very first time the level is loaded. It has no values. This is good for exposition, explaining what the level is supposed to be.  This sequence will not be run when the level is re-visited.  Must appear after the **init** sequence (if defined) and before any others.
 * **end_anim** - Marks the end of of an **init**, **first**, **tool_trigger** or **item_trigger** animation sequence. Has no values.
@@ -762,6 +763,7 @@ Technically, levels don't have any specifically required keys. Not even a bitmap
 * **tiles** - Displays a row of tiles starting from a specific location. Unlike sprites, tiles are not placed at arbitrary screen positions but at discrete positions within the 40x30 tile map. Rather than being moved or removed, they can only be replaced. By default, the entire game level bitmap area is tiled with all transparent tiles (index 0).  A single **tiles** key can display a single row of tiles with all the same palette offset, which is the first number in the key's space-delimited value. The next two numbers are the starting x and y coordinates of the tile row. The x coordinate must be between 0 and 39, and the y coordinate between 1 and 25 to be within the level bitmap area. The remaining values are an ordered list of tile indexes, appended with H and/or V if they are to be flipped. Note that if the number of tiles is greater than 40-x, then not all will be visible as the x coordinate of at least the rightmost tile will exceed 39. If any of the tiles need to be removed during the level, they need to be replaced with transparent tiles (index 0).
 * **wait** - Pauses a sequence for a specified number of "jiffys". A jiffy is 1/60 of a second, so a ```wait 60``` will pause for a whole second before executing any later keys in its sequence.  It will not stop the progress of a preceding key that is still executing (such as **sprite_move**). The wait time can be up to 255 jiffys, or 4.25 seconds.
 * **sprite_move** - Starts moving a sprite in a specified direction. Note that the sprite needs to be shown via a preceding **sprite** key in order for the movement to be visible. Its value contains exactly 5 space-delimited numbers. The first number specifies the sprite index (1-127, index 0 is reserved for the mouse cursor). The second number (1-255) is the number of jiffys in between each step of the movement (e.g. 2 jiffys between steps will produce 30 fps movement). The third number is the number of steps to execute (1-255), so the total duration of the movement will be the product of the second and third numbers (e.g. 30 steps at 2 jiffys per step will go on for a whole second before the movement stops). The fourth and fifth numbers are the x,y vector of the movement (x is 0-255, y is 0-208). This means that each step the sprite will move x pixels to the right and y pixels down. Leftward and upward movements require negative x and y values, respectively. The final position of the sprite will be its previous position plus the number of steps times the movement vector, so take care to make sure that the full range of movement will be valid sprite positions, as specified for the **sprite** key.
+* **play** - Plays a sound effect. The only value is an identifier defined by one of the **sound** keys. The sound will continue to play until it is finished, another sound is played, or a level transition occurs, whichever happens first.
 * **get_item** - Places an item in the inventory. The first value is the name of the item as it appears in the inventory file. The second value is the number that is added to the current quantity. Should usually be preceded by a sequence that lets the player knwo what they are getting, like some text or a trigger sequence that makes a representation of the item disappear from the screen.
 * **go_level** - Goes to another level once reached in the sequence. Note that any instructions after this in the sequence will not be run, so it should onyl appear at the end of a sequence. Putting it in an init sequence will prevent any other sequences from ever running. It has two values, the zone (0-255) and level (0-9) numbers.
 * **gif_start** - *Emulation Only* - Starts recording screen to GIF file, specified on the host command line.
@@ -779,6 +781,7 @@ Let's take a look at the next level (Zone 0, Level 1) to see game state and trig
 
 bitmap mygame_kitchen.data
 music zone0.vgm
+sound coffee coffee.raw
 
 init
 # coffee maker
@@ -897,7 +900,8 @@ if_not cup_taken
    if holding_carafe
       clear
       text 1  Sure, pour the whole pot.
-      wait 60
+      play coffee
+      wait 44
       # empty carafe
       tiles 0  19 12  164 165
       clear_state holding_carafe