The Guide to
TI-83+ Silver Edition BASIC Grayscale
Version 1.4

1. Introduction

Welcome to The Guide to TI-83+ Silver Edition BASIC Grayscale. After reading this tutorial you will be able to program revolutionary BASIC games with unbelievable graphics never seen before on the TI-83+ SE, TI-84+ and TI-84+ SE calculator. This package allow you to make sprite based games and picture based games like puzzle and RPGs, but maybe other things would be possible too. To learn BASIC Grayscale programming you will require a few things:

-A TI-83+ Silver Edition, TI-84+ or TI-84+ Silver Edition calculator (for decent looking grayscale a regular 83+ is not recommended, altough simple games might run at a reasonable speed)
-Beign competent in TI-BASIC language (it's the easiest programming language in the world)
-If you have Keyfont 73 fonts on your computer it will be easier to read program source code showed in this page.
-This guide (duh ^_^)

You will also need the following ASM libraries that are included with this guide:

-Omnicalc v.1.25: Application made by Detached Solutions. Required to display fast sprites (you need version 1.20 or higher)
-XLIB: ASM library by Patrick Prendergast. Needed to display tilemaps. This avoids slow map rendering (people who played ROL3 know what I'm talking about)
-DevPic: a program by Kevtiva Interactive and BAPG that allow you to have 40 pic files instead of 10. Useful if you run out of pictures.
-Zpic: ASM program by Kevtiva Interactive. Needed to display archived pictures.
-Flash Gordon: Another ASM program by Kevtiva Interactive. Can run archived programs without unarchiving them.
-Codex: 32 ASM librarys by Justin Whales. If you run out of memory it might be useful.
-Setcon: A part of BASIC tools package by Michael Vincent. Use it to temporary change screen contrast. You may find it useful.

AARRRGGGGHHHHH!!!!!! Ok I know that most of you hate Omnicalc and don't want to use it. However, Omnicalc is THE only way to make decent looking grayscale in BASIC. It can display 62x96 sprites using a library that is directly integrated in the TI-OS when it's installed. I know that Zapi and Zsprite make big sprites too and that they can also have sprite height higher than 62 pixels, but due to the fact that they are external and that your inputs need to be stored in variables to be executed, they need more processor time so they are not fast enough to make good grayscale. Also their speed will vary depending of the free RAM you have (I think it has something to do with the Asm( command) so if your game runs with 2 KB, expect to have a maximum of 1 frame per second with an ugly pattern moving around the screen. Omnicalc will run at the same speed regardless of the amount of RAM you have. Other note is about Zapi tilemapper. It doesn't work at all! Or if you can ever get it to work you will have to do more archiving/unarchiving because Flash Gordon cannot run ASM programs (We have to deal with RAM limitations a lot with grayscale because programs and sprites are twice bigger than without grayscale). Also most of the bugs in Omnicalc have been fixed in version 1.23 so it's not as dangerous as before, it's now compatible with all TI-OSes and you can now group and send program using Omnicalc functions without any problem. However don't take any chance with ASM programs and make a lot of backups of your projects because if you do a mistake while using them you risk of crashing your calculator and lose all your work. I will not held responsible of any data loss and calculator damages. Now let's settle things:

First of all I recommend you to reset your RAM. Delete all the pictures files and matrix [A] from your calc if you have them. After that send Omnicalc to your calc with Ti-Graph Link or TI-Connect Device Explorer. This guide IS NOT a calculator linking turorial and DON'T e-mail me to know how to send programs to your calc. There is plenty of useful info about this on the web. After Omnicalc is sent, Open the APPS menu, select Omnicalc and press ENTER four times then press CLEAR. What you just done here is to install it :). Now send all the 8xp and 8xi files found in the same folder than this guide to your calculator RAM. After that you are ready to begin.

Note: In this guide I will often refer to Silver Edition calculators, but it also design the TI-84+s as well.

2. Before Starting

For all those who claimed that grayscale is impossible in BASIC, you were wrong :). Surely TI-BASIC it's a very slow interpreted language where every line of code have to be translated in thousand of assembly lines of code, scanned for errors before beign executed, but with the help of a few ASM libs it's fast enough to make flickerless 3-level grayscale on the Silver Edition. It's not as good as Durk Kingma 4-level Grayscale Programming Package, but with my guide you don't need to learn ASM in order to program games that look almost like those on the GameBoy :). Also now you can do all the stuff directly on your calc! I understand people who don't have a computer at home and may have used school or library computers to download this. Those people cannot program ASM so this BASIC grayscale package might be useful for them.

Now let's see if you installed all the stuff correctly. Go in the PRGM menu and run prgmA2. If everything is OK, the screen will come blank and after a few seconds you should have this screen:

Pretty amazing for BASIC, isn't it? If the screen stay blank, maybe you forgot one step in the installing procedure. Just press 2^nd and the up (or down) arrow to reset the contrast settings. If you get ERR:ARGUMENT you forgot to install Omnicalc. Refer back in the installation procedure. If it worked, make sure you don't move on the house, rocks and trees or outside of the screen because I haven't implemented the collision detection in this program yet so it will screw up sprites if you move on them and it will cause ERR:DOMAIN when moving out of the screen. Anyway, the most important thing for the moment is grayscale. Instead just move the little dude around and see. If you look carefully you will notice a strange pattern on the gray areas. This is what I'll explain later.

3. BASIC grayscale programs

Now exit the demo program using the ON key and let's look at the code:

If you are good at BASIC programming, you will understand the code very well (and maybe it still need some optimizations). Try adding ->[A] after the second matrix so you will have the following screen when running the program again:

However, the most important things in this code are the new real(20,8,0,0,96,62,0,0 commands (real(20, is the same thing than the old Omnicalc Sprite( token but it's more stable and faster) put in the walking loop, which are similar in purpose to grayscale interrupts in ASM. In order to perform decent grayscale in TI-BASIC you need to put these interrupts after each line of code in the loop. If you omit too many of them you can forget about your grayscale effect. If you want quality but don't care about speed put three real(20,8,0,0,96,62,0,0 interrupts between every line of code instead of just one. Putting two interrupts is a bad idea because the pixels showed in picture 7 will be displayed for a longer time than the inverted sprites so it will display a static pattern made of dark grey and light grey pixels. Also don't put more than three interrupts because your game will run incredibly slow and you will not see any more improvement in grayscale quality. Other note is about If statements. If, for example you have lines of code that look like If A=1:2->B:real(20,8,0,0,96,62,0,0, you could change them to If A=2:Then:real(20,8,0,0,96,62,0,0:2->B:End:real(20,8,0,0,96,62,0,0. That way, gameplay will be a tad slower, but it will improve grayscale quality. Make sure you don't put an interrupt between an If statement and a Then instruction :).

With those grayscale interrupts, the program execution is halted at least 25 times per seconds to switch pixels ON and OFF in sprites areas that must be gray so it doesn't flicker. However, because TI-BASIC is TI-BASIC, we have to optimize the thing by storing the whole tilemap generated by xLIB in one picture file then storing it again in another picture, but using another sprite sheet (I'll explain sprites later). After that, the first picture must be displayed (except the 63^th and 64^th pixel row), as well as the little dude walking around, then the weird command do the rest of the work to achieve grayscale. Displaying the little dude before entering the getkey loop is very important, otherwise it will be displayed only once you'll press a key. Now let's go back to our real(20,8,0,0,96,62,0,0 commands. Actually, when Omnicalc is installed (you installed it, didn't you :) ?), it takes a 96x62 sprite located in Picture 8 at (x,y) coordinate of (0,0) and display it on the graph screen at (0,0) using the XOR logic. The black parts of the incredibly huge sprite will invert all the pixels that intersect with and the white parts will do nothing. Run that interrupt 25 (or more) times per seconds to create that awesome (for BASIC) 3-level grayscale effect.

You can change the value in the real(20, command (refer to Omnicalc sprite documentation for more info) if sometimes, in your game, grayscale is only displayed on some part of the screen (for example, when a text box is displayed) or if you use different pictures. In my Grayscale RPG project, I used Pic0 so the command was real(20,0,0,0,96,62,0,0. Also you can use a graphical moving sprite instead of ASCII, it can be faster if you store it in the graph buffer and display it only at the next grayscale command (refer to Omnicalc doc for more info on how to do that) so it runs faster.

One final note: NEVER use Lbl/Goto instructions when you program a BASIC grayscale game. We need regular interrupt speed, NOT slow down.

4. Sprites

We talked a bit about how to deal with sprites during program execution, now we are going to talk about THE GOOD way to draw them.

In the Pic1 file you sent to your calc you have a sprite sheet:

Notice how the tiles are different from what you've seen during the demo execution. Now there is no grayscale at all. Obviously, because it's only the first sprite layer. Now let's look at Pic2 sprite sheet:

GAAAAHHHH!!!!! What the hell is that????? Well, this is the second sprite layer. Now let me explain something. In ASM or BASIC, each grayscale sprites are actually two monochrome (black and white) sprites combined together. I don't have much ASM knowledge but I know that the process of displaying grayscale sprites in ASM is different than in BASIC because ASM allows you four levels of gray. However BASIC only allows you three. If you archived both pictures on your calc unarchive them for now. Now type 1->X:Asm(prgmZPIC or ClrDraw:RecallPic 1 on the home screen to recall the picture 1. Now type our so beloved real(20,8,0,0,96,62,0,0 command and see. Nothing much different, but actually all the pixels corresponding to the black areas on the sceond screenshot have been inverted. Now run prgmBB to see what it does when those sprites are inverted 25 times per second:

That being said, I will say that making sprites is probably the hardest part of BASIC grayscale game making. We cannot use Calc Graphic Studio to make them because we need to store our sprites in picture format, not in z80 format. Also there is a particular way to make them. I know that many programmers here may think that they simply have to draw their sprite layers like this:

This is a brillant but bad idea, because all layer 1 sprites corresponding to the black areas in layer 2 will be turned ON or OFF at the same time, making a very annoying seizure-inducing flickering effect. Unless you want to make a psychedelic game with plenty of flashing goodies around ^_^, you will have to reduce this effect by creating a pattern in the sprite layer 1 so it may look like this:

This will create an optical illusion making your eyes think it doesn't flicker :). You will just see a scanline effect depending of the ambient light in the room you are playing and your calculator contrast. Also avoid making a pattern made of horizontal or vertical lines because it doesn't look quite impressive. If you have a computer, there is some programs that can do the pattern for you by converting the picture in monochrome format (Paint Shop Pro, Photofiltre, Photoshop, etc.) then you have to convert the picture with Image Studio (found at ticalc.org), which can speed up things a lot when making 16x16 or bigger sprites. Other thing is about how to make such sprites. Use the following method to draw them if you don't have a computer. If you don't I can guarantee you that making them will give you a brain aneurysm.

Now let's draw a beautiful sprite (I hope you know how to use the DRAW commands). Clear your graph screen and recall picture 1 and draw the following sprite to the right of the top-most cavern wall like this:

Store this picture in Picture 1. Now clear the graph screen and recall the Picture 2. Then execute real(20,1,72,0,8,8,72,0 to display your sprite again. Now fill all the white areas in the sprite with black pixels (the sprite here act as a guide) and once it's finished run the real(20,1,72,0,8,8,72,0 command again. It should look like this:

Store this picture in Picture 2. Now clear the graph screen and recall the picture 1 again. You now need to draw your pattern like this:

Store this again to picture 1 and that's it. Now run prgmBB to see if you did the work correctly. You should have the following screen:

Basically, what it means is that you must NOT draw your pattern before (or even on) the second sprite layer. Otherwise, you will give up after working 15 minutes on the same sprite.

Final note (again?): In xLIB you are allowed to store 8x12 sprite maps. However in the TI-OS you cannot use the 96^th pixel column so you have to store your sprite somewhere else, save your picture, erase the sprite with Omnicalc (using real(20,), displaying it in the 12^th row and saving your picture again. Also NEVER use the 8^th sprite row because a bug in xLIB will cause dotted lines to be displayed at the bottom of each sprites. Also after drawing my sprite sheet I noticed that the first sprite to the top-left (the brick wall) is displayed as garbage with xLIB so don't use it too.

5. Tile maps

Now that you know how to make your sprites let's talk about tile maps. Basicaly, a tile map is made of numbers, each one corresponding to a sprite stored in a sprite sheet. In our case tilemaps are stored in a matrix and displayed with xLIB using a proper syntax. In text-based maps, it's best to store them into strings by using the ASCII sprites themselves so we can merge a bunch of strings of 16 characters together and instantly display them on the home screen or even make a fast scrolling map (ever played ''Zelda: Dark Link Quest''? It works in the same way.). However, with graphical tile maps it's best to use matrices to display them instantly with xLIB. We are going to use 12x8 tilemaps made of 8x8 sprites. However, making them directly in the built-in TI-OS matrix editor is a pain, A REAL pain!!!!!!! So I built a small tile map editor for you. Its program name is AMAPED. Just run it to see.

Ok, now I understand that some sprites have changed into the circle you drawn above :) , now it look a bit like the arcade game arena in ROL3 RPG, but anyway, this part of the tutorial is to learn how to use the editor, not to make good maps. If it's too annoying, go to your computer and send both 8xi files again to your calc.

For speed reason, grayscale is not enabled in the editor so we have to deal with this. Also I noticed that you cannot use the top-left 8x8 sprite sheet area with xLIB because that sprite change to garbage so just don't use it.

Once you enter the editor, default sprite ID is 11. I recommend you use the 11^th sprite of the first row as a walk-onable (and empty) tile. Here is the controls:

-Map edition mode: Use 2^nd to put a sprite, DEL to erase one and MODE to enter Sprite select mode. Arrows (duh) move the cursor.

-Sprite Select mode: Use 2^nd to select a sprite and DEL or MODE to cancel. Arrows... guess what they does :) !

In general, if you ever used Sam Heald Mario Level Editor you should be okay with this one too. But before creating a new map don't forget to store the last one in a program.

6: Grayscale Programs Compatibility

TI-BASIC grayscale programs are compatible with TI-83+, TI-83+ SE, TI-84+ and TI-84+SE calculators with any TI-OS version. However there is some things you should care about.

-Programs will not work in Virtual TI 2.5, Virtual TI 3.0 alpha and TI Flash Debugger. Virtual TI 2.5 doesn't support archive memory so you can't install Omnicalc on it. The two others have archive support but grayscale will not work on it, not to mention that in VTI 3.0 alpha you have to copy your programs by hand. If you want to make screenshot of your game you must copy them pixel by pixel in MS paint or similar programs :(.

-Grayscale programs take a lot of Pic files. If 10 pictures isn't enough for you, use the DevPic program included in this package. It will allow you to store up to 40 pictures on your calc and recall them using the Zpic program included with this package. However, those pictures cannot be sent using TI-Connect 1.5 so in your readme.txt you will have to specify that your game is not compatible with TI-Connect 1.5 if you decide to rely on Devpic.

-Remember that grayscale isn't very good on the regular 83+, altough it can be quite nice for simple BASIC games.

-Other thing is about LCD (liquid crystal display). TI-83+ contrast is lower than on the TI-83+ Silver Edition while TI-84+ contrast is darker. If you are planning to make a multi-platform game with automatic contrast change (using Setcon library) it would be a good idea to prompt the user to set contrast by himself during game execution. In my case the program above is quite dark on my TI-83+ SE but on my 83+ grayscale is very hard to see.

-Always use Omnicalc 1.23 or above to ensure game compatibility.

7: Ready to program?

You probably learned a lot so far! Now that you know the most important stuff about BASIC grayscale programming, you are probably ready to program (you know how to program, don't you?). However, even if you mastered TI-BASIC language, you should follow the following advices. Don't start with something too huge. Grayscale programs are generally twice bigger than normal programs in memory and you only have 24 KB or RAM and using archive is not always possible. Also they are twice slower because of grayscale interrupts so if you expected to make a Zelda or Mario game forget about it. Unexpectedly, TI-BASIC on a Silver Edition is fast enough to display 3-level flickerless grayscale, but it still has speed limitations we have to deal with (otherwise we must switch to ASM :p). Other note is about regular 83+ calculators. I tried running the demo included in this package on it and the grayscale wasn't that bad but it looked a bit fuzzy and some more complex games may run incredibly slow on it. When you are thinking about making a game, start planning first, don't start making something. Once you planned start coding only ONE thing at once. For example, in a RPG, you should never code the battle engine, the map engine and the menu all at once or you will get lost and you will lose motivation. Also, please don't make games just to raise your ticalc.org download stats. Make them for bringning the best of the TI community. We don't have enough good games yet, even in ASM. Also what I hate is when you find a new and awesome web page with a cool project under developpement. You say ''WOW! It look soooo promising! I can't wait for playing it''. So you start visiting the site often to see weekly updates and suddently after a few months, no more updates! So you wait, wait and wait, then stop visiting the page. After 6 months you go visit the site again and still no updates, so you say to yourself: ''Another dead project. It's always the same thing.''. So planify your projects before starting coding :). Good luck, and I hope this guide helped you very much!

8: Submiting your games

Oh, you made a game!!!! Awesome (can't wait to download it!)! Now let's talk about something. If you decide to use this package for making games, I would like you to give some acknowledgements to me and people who made the ASM utility included in this package, depending of which ASM programs (mentionned at the beginning of this guide) you used. Also, don't forget to include the required ASM libraries with your games. I remember the day I uploaded my alpha version of Grayscale RPG Demo at ticalc.org, without including Omnicalc ^_^. Talking about Omnicalc, you must include its documentation, source code and everything included with it with your games because it's released under the General Public licence. Don't put the map editor with your game of course unless you are making some kind of game with external levels.

9: Special thanks

First of all, I would like to say MANY great thanks to Detacheds Solutions for having made Omnicalc. Many people including me complained a lot in the past for its many bugs and its compatibility problems, but since that time it improved A LOT, not to mention it now feature the fastest sprite routine avaliable for BASIC programmers. Without their hard work, BASIC grayscale on the Silver Edition and TI-84+ calculators would never have been possible. Many great thanks too to Patrick Prendergast for the xLIB program. Without it, rendering a grayscale map in BASIC would have taken at least 20 seconds, even with Omnicalc. And thanks also to Kevtiva Interactive for their programs than can run pictures and programs from archive without unarchining them, to Justin Whales for the Codex program, to Michael Vincent for Setcon (which is a part of his BASIC tools package he made) and finally to you for having read this so far.

Did I forgot somebody? Anyway thanks also to those I forgot to mention :).

10: Disclaimers

-You are free to use the sprites, code and programs included in this package as long as you give credits to me or people who made them (actually, the only thing I didn't made in this package are the 6 ASM libs). Remember to include Omnicalc source too to not violate GPL policies. Also please note that I might also use those sprites in my future projects so if you use them there is some chance that you will have similar graphics than those in my games. Try to be creative and try making some of them by yourself :).
-What you just say here? You want to program in grayscale but you are anti-Omnicalc? My only awnser to that question is: Learn ASM.
-Feel free to e-mail me about comments, suggestions and question regarding my grayscale programming kit. It's complete but maybe I forgot to mention something. However, DON'T e-mail me to ask me ''How do I send files to my calc?'' or things like that because you will probably never be awnsered, depending of my mood.
-I will not held responsible for any data loss or damage caused to your calc.
-No animal were harmed during the making of this package :).

(c) 2004, by Kévin Ouellet. This package is a property of Omnimaga and Epic Programming Studio. The ASM libraries included in this package, however, are property of their respective owners.

11: Website links

Epic Programming Studio
Omnimaga: Your Calculator RPGs Headquarter