Added build and documentation for tools

Author: SlithyMatt

README.md

@@ -828,7 +828,11 @@ Technically, levels don't have any specifically required keys. Not even a bitmap
 * **sprite_frames** - Defines an animation loop for a particular sprite. The value is a set of space delimited values, starting with the sprite index, followed by the palette offset to use for the sprite in this loop. The remaining values are an ordered list of sprite frame indexes (maximum of 31), appended with H and/or V if the frame needs to be flipped. The next movement for that sprite will step from frame to frame starting with the first listed, then throught he list and back to the beginning if there are enough movement steps before the next **sprite_frames** key with the same sprite index value. If there is only one sprite frame listed, then the sprite frame will not change until the next **sprite_frames** or **sprite_hide** key with the same sprite index value. The sprite will change to the first frame immediately when this instruction is run.
 * **sprite** - Displays a sprite at a specific screen location. The sprite will be its most recently defined frame. If preceded by a **sprite_frames** key, it will be the first frame specified in its list. The value is a set of up to 3 space delimited number values. The first number is the sprite index. The next two numbers in the value are the x and y screen coordinates, in that order. For game levels, the x coordinate should be between 0 and 304, and the y coordinate between 8 and 192, which will ensure the sprite is completely visible with no "overhang" past the level bitmap. Note that the coordinates will be for the upper-left corner of the sprite frame, not the center.
 * **sprite_hide** - Hides a sprite. The value is the sprite index. The specified sprite will not be visible again until the next **sprite** key with the same index. By default, all sprites are hidden, so this is only required for sprites that had already been made visible in the current level.
-* **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).
+* **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). If you want to include ASCII tiles, you can use the **decascii** tool to generate the tile indices like this:
+```
+$ ./decascii.exe Hello, World!
+72 101 108 108 111 44 32 87 111 114 108 100 33
+```
 * **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.
@@ -1118,6 +1122,12 @@ host:~/x16-xci/sdk$ make
 
 After this you will see multiple calls to gcc. If no errors are reported, **xci.exe** should be in the current directory.
 
+The **sdk/tools** directory will also be populated with three executables than can be used to help develop your project source code:
+
+* **decascii.exe** - Command line tool that can generate a set of decimal ASCII indices from a string. See the entry for **tiles** in the [Level File keys section](#level-file-keys) for usage.
+* **hexsprites.exe** - Converts raw data bitmaps to ASCII hex sprites. See [Tiles Hex File](#tiles-hex-file) for usage.
+* **hextiles.exe** - Converts raw data bitmaps to ASCII hex tiles. See [Sprites Hex File](#sprites-hex-file) for usage.
+
 ### Building Engine
 You will need to have GNU make (available as part of [gcc](https://gcc.gnu.org/)) and [cc65](https://cc65.github.io/) installed.
 

sdk/Makefile.mingw

@@ -1,15 +1,19 @@
 ALL_OBJS = $(patsubst %.c,%.o,$(wildcard *.c))
 ALL_HDRS = $(wildcard *.h)
 
-all: $(ALL_OBJS) $(ALL_HDRS)
+all: $(ALL_OBJS) $(ALL_HDRS) dev_tools
 	x86_64-w64-mingw32-gcc -o xci.exe $(ALL_OBJS)
 %.o: %.c
 	x86_64-w64-mingw32-gcc -c $< -o $@
 
 clean:
 	rm -f xci.exe $(ALL_OBJS)
+	$(MAKE) -C tools -f Makefile.mingw clean
 
 test: bitmap_test
 
 bitmap_test: bitmap.h bitmap.c
 	x86_64-w64-mingw32-gcc -o bitmap.exe -DTEST bitmap.c
+
+dev_tools:
+	$(MAKE) -C tools -f Makefile.mingw