xLIBC tutorial

I've been looking around the forums to find a xLIBC tutorial, but I found only this, but that is only for drawing sprites, so I decided to create one. I will do this, because there are tons of questions about it, especially the DrawMap and DrawSprite routines.

I will first handle all these functions and after that I will create a game to make a good example.

For the people who found this useful: I am using DoorsCSE 8.2 and TokenIDE. There are probably more useful programs for that, but I chose these. I based my explanation on the xLIBC libraries wiki, so if you don't follow me, take a look there.

I'm going to start; if you don't have DoorsCSE 8.2 and TokenIDE installed, please do that first. Each function is supported by some images.
For all the colors xLIBC use, take a look here. If you have any question, feel free to ask!


For a tutorial how to make sprites and a tilemap, please look at my next post.

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
real(0 - xLIBCSetup

The basic of the the xLIBC functions is the half-resolution. This works as follows: the screen as you normally see will being splitted in two halves. One half would be stretched, the other half you don't see, that would being our buffer. That would look like this:

As you can see, there is no second half.
Very important! All the xLIBC functions expected to be in half-res mode!

These are the functions of real(0 :

GetXLIBCVersion
Code:

SetupGraphics
Code:

Very important! Don't forget to switch the half-res mode off, or the TIOS will stuck in this mode!


SetSpeed
Code:

Note: the default CPU speed is 15MHz. Try it, and see the difference.

SetupColorMode
Code:



---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
real(1 - UserVariables

xLIBC has the facility to utilize 'internal user variables' for data storage and calculations as opposed to using TI-OS variables. They work exactly the same, but the main difference is, is that they are faster, and temporary, which means that you cannot 'save' them for other programs. Some xLIBC functions expected (only) UserVars, so it is always handy to learn and use these.

These are the functions of real(1:

GetUservar
Code:
This returns the value of the UserVar in Ans

SetUservar
Code:
This function writes (value) to UserVar

AddToUservar
Code:
This function add (value) to UserVar

SubFromUservar
Code:
This function subtracts (value) to UserVar

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
real(2 - GetKey

These routines have been significantly overhauled from the TI-BASIC getKey function and are even more comprehensive.

These are the functions of real(2:

GetKey
Code:
Key code stored in Ans
Very important! These values are NOT the same as the values of getKey, but it returns the values of _GetCSC:


GetKeyCheckList
Code:
This updates (getkey_uservar) by (getkey_value) if you pressed (getkey_keyvalue). (getkey_checknum) is the amount of UserVars to update. Useful for counters or sprites.

GetKeyArrows
Code:
This updates (uservar_x) and (uservar_y) with respective (value_x) and (value_y) if you pressed any arrow.

If up is pressed then USERVAR_Y = USERVAR_Y - VALUE_Y
If down is pressed then USERVAR_Y = USERVAR_Y + VALUE_Y
If left is pressed then USERVAR_X = USERVAR_X - VALUE_X
If right is pressed then USERVAR_X = USERVAR_X + VALUE_X

GetKeyArrowsDiagonals
Code:
This works the same as GetKeyArrows, with the exception that a combination of the arrows also will update the UserVars.

If up is pressed then USERVAR_Y = USERVAR_Y - VALUE_Y
If down is pressed then USERVAR_Y = USERVAR_Y + VALUE_Y
If left is pressed then USERVAR_X = USERVAR_X - VALUE_X
If right is pressed then USERVAR_X = USERVAR_X + VALUE_X
If up+left is pressed then USERVAR_Y = USERVAR_Y - VALUE_Y, USERVAR_X = USERVAR_X - VALUE_X
If up+right is pressed then USERVAR_Y = USERVAR_Y - VALUE_Y, USERVAR_X = USERVAR_X + VALUE_X
If down+left is pressed then USERVAR_Y = USERVAR_Y + VALUE_Y, USERVAR_X = USERVAR_X - VALUE_X
If down+right is pressed then USERVAR_Y = USERVAR_Y + VALUE_Y, USERVAR_X = USERVAR_X + VALUE_X

GetKeyArrowsCheckTile
Code:
This routine will only update the UserVars with their values if the move is to a walkable tile (see real(3) - DrawMap). You must specify an UserVar with the width of the map (that is often 20, 160/. It checks for a box from (X_left, Y_top) to (X_right, Y_bottom). For a single sprite of 8x8 pixels, that would be (X_sprite+0, Y_sprite+0, X_sprite+7, Y_sprite+7).

GetKeyArrowsDiagonalsCheckTile
Code:


GetKeyArrowsCheckTileList
Code:
It works the same as real(2,3....), but now it will return information regarding any keypress and any collided tiles in a 'real list' contained in a user-defined list named "XL".
XL have the following format:
{key_press , num_collided_tiles , collided_tiles_list}
key_press returns ~1 for noarrow, 0 for up, 1 for down, 2 for left and 3 for right.
num_collided_tiles is the number of tiles collided against
collided_tiles_list is a list of collided tiles against.

GetKeyArrowsDiagonalsCheckTileList
Code:
Same as above, now with diagonals.

All of these routines are pretty useful, for smarter and better movement.


---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
real(3 - DrawMap

There exist many games which have a background. That background can't you (often) make with only shapes, that is why there DrawMap exist. This routine displays a bunch of sprites, which would being a fixed background.

These are the functions of real(3:

DrawMapA (TI-OS Values)
Code:
This routine draws a tilemap at position (X,Y). Mapwidth is the count of sprites next to each other, counted in blocks of 8x8, which is often 20 (160/. The height will be automatic calculated. Mapstring is the NUMBER of string which contains the tilemap data. For Str9, it will be 9. If you don't want do draw the whole background, you can specify the bounds of drawing, by changing x_start, y_starat, x_end and y_end. With these values you can display a specific box instead of the whole background.

DrawMapB (Uservar Values)
Code:
This is the same routine as above, but now instead of TI-OS values, like A or G, it takes UserVars as the X- and Y-position. And the mapwidth must be stored to an UserVar.

DrawMap_GetTileA (TI-OS Values)
Code:
This routine gets the tile at position (X,Y). Mapwidth and mapstring works the same way as real(3,0). Most people don't use xOffset and yOffset, just put 0 there.
Very important! X and Y must be in pixels, not in blocks of 8x8!!

DrawMap_GetTileB (Uservar Values)
Code:
Same as above, now with UserVars. Also here are uservar_x and uservar_y in pixels.

DrawMap_SetTile (TI-OS Values)
Code:
This routine replaces a tile at (X,Y) width tile tile_id.
Very important! X and Y must be in blocks of 8x8!!

DrawMap_ReplaceTile (TI-OS Values)
Code:
This routine can replace very fast multiple tiles, instead of one with real(3,4). Checknum is the amount of tiles you want to replace. All the tiles with tile_id_X are replaced with replace_tile_id_X.
->
I replaced only one tile_id, here are the results. Note: you must redraw the map to actually see it. My code was
Code:


real(3,6 - real(3,9 are coming soon!

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
real(4 - DrawSprite

Almost every game will use sprites, which are easy to display and move on the screen. That is why it is important to understand this right, that is always useful.
Very important! You must load tiledata into temp memory before drawing tilemaps. See real(5).

These are the functions of real(4:

DrawSpriteA (TI-OS Values)
Code:

This routine draws a sprite at (X,Y) with a width and height of WIDTH*HEIGHT 8x8 blocks. xOffset and yOffset are unused, so set these always to 0. Transindex means the color of the color palette, that every pixel that matches that color, will not being drawn. This is very useful for sprites which are not in blocks of 8x8. Update_LCD will I explain later. Then follows pic_index_N. Note that N must be equal to WIDTH*HEIGHT. Here you must enter a list of argument(s) for each index of the sprite (in 8x8 chunks). Pic_index_start equals the number, from where the list of argument(s) will start.
Very important! The sprites draws *column* first. So a 16x16 sprite will look like

Code:
and a 16x24
Code:
For the actual tile-index, look at my next post, at the location "Some general information". This routine has even an addition: it can display a sprite based on a variable. You can use the PICINDEXSTART argument to specify which sprite to draw out of a list of sprites. This can be useful for drawing a different sprite depending on a direction variable. For example drawing an 8x8 sprite where pic index 10=up, 11=down, 12=left & 13=right, and you have a direction variable "A" which holds 0=up, 1=down, 2=left & 3=right you can do:

Code:
This will select index 10 if A=0, 11 if A=1, 12 if A=2 & 13 if A=3 and so on.

DrawSpriteB (Uservar Values)
Code:
This works exactly the same as above, but now takes uservar_x and uservar_y as (X,Y).


...will be continued...

In this post I will describe how to create sprites and/or a tilemap.
First you absolutely need is TokenIDE. I will make screenshots if it's too difficult to explain in words.

--------------------------------------------------------------------------------------------------------------------------------------------------------------
How to make sprites
1) Open TokenIDE
2) Open the Hex Sprite Editor by pressing Ctrl+Shift+H or click on Tools > Hex Sprite Editor > Color Sprites.
3) Set the width to 128 and the height to 64, zoom to 7, and select the "Draw Grid" checkbox. From the dropdown-menu, select the option "xLIBC".
For me it looks like this:



4) Create some sprites, by selecting a color and painting in the editor. This could be anything, but it would be nice, if the width and height are products of 8.



5) Save the sprites, by pressing Ctrl+S or click on File > Save (as). Be sure to save this as "xLIBC Tiles", and name it anything you want.


Now you're ready to use all the sprites in your program. Just send this appvar, name_of_appvar.8xv to you calculator, and voilà.

Some general information:
When displaying sprites, you should know the tile-index. The numbers correspond to each 8x8 square.


If I take my sprites, then my happy face is tile index 0, the large circle 1, and my rectangle 5.


--------------------------------------------------------------------------------------------------------------------------------------------------------------
How to make a tilemap

1) Open the xLIBC Map Editor, by pressing Ctrl+M or click on Tools > xLIBC Map Editor.
2) Add Tiles, by pressing Ctrl+O or click on File > Add Tiles. Select your spritesheet.
3) Set zoom to whatever you want, and select the "Draw Grid" checkbox.
For me it looks like this:



4) Make any tilemap you want, by selecting a sprite and paint the editor with that sprite. I will make this:



5) When you are ready, import and exit, by pressing Ctrl+I or click on File > Import and Exit. You will see now a bunch of characters in the TokenIDE editor. This is very important. Copy this to your program, this is your tilemap-data, which is necessary for real(3 - DrawMap (see my previous post).

Good luck with this, and if you have any questions, feel free to ask!