SmileBASIC Tutorial: The Touchscreen

This tutorial, as well as any and all of my future tutorials, assume that you understand basic programming concepts such as variables, keywords, control structures, branching, etc.  If you don't understand these things, there's actually a primer in the digital manual for SmileBASIC.  Just select it on your 3DS' home menu and tap the Manual button.  I'm mainly going to focus on accomplishing specific tasks, which will be supplemented with simple programs.  The task of putting all of this knowledge together and making a game out of it will be left as an exercise for the reader.

SmileBASIC also has a complete reference to all of its built-in keywords and functions.  Just start typing something.  See the keywords and so forth that appear in the green boxes at the top of the touchscreen?  Tap one of them, then tap the question mark on the right.  Instant reference for anything in the language, and it's super helpful.

That said, let's begin.

The touchscreen is pretty simple to read from in SmileBASIC.  Consider this line of code.

TOUCH is the meat and potatoes of this instruction.  There's actually another parameter that can go between TOUCH and OUT that specifies the "Terminal ID", this is for writing programs that make use of the 3DS' wifi card.  Wireless connectivity is outside the scope of this tutorial, so let's move on.  OUT directs the output to the three variables provided.  The first one, TIME, is the amount of time that the touchscreen has been touched.  If this is zero, the user is not touching the touchscreen.  X and Y are the coordinates of the touch.  The origin (0, 0) is the top left corner of the screen.  However, SmileBASIC won't return a touch in the outermost five pixels of the touchscreen on each side, so the range you have to work with is 5..314 for X, and 5..234 for Y.

To actually get started, you'll need to set the screen mode using the XSCREEN instruction.  SmileBASIC defaults to XSCREEN 0, which allows the top screen to use stereoscopic 3D effects, but doesn't use the bottom screen.  The bottom screen will continue to be the on-screen keyboard.  XSCREEN 1 disables stereoscopic 3D on the top screen, but also doesn't use the touchscreen.  To actually use the touchscreen, you'll want XSCREEN 2, XSCREEN 3, or XSCREEN 4.  XSCREEN 4 is a bit weird for tutorial purposes, and you probably won't want to mess around with the stereoscopic 3D just as you're learning to work with the touchscreen, so the one you'll want is XSCREEN 3.  XSCREEN has other arguments, that deal with sprites and background images, but they're optional, so let's keep it simple and not pass values to them for now.

However, before that, you don't really know with 100% certainty what state the screens are in.  You could have been messing around in DIRECT mode just running instructions, or a previous program could have left stuff there.  You'll want to return to a nice known state, and this is made very easy with the ACLS instruction.  Inspect the help on it to see exactly what it does, because it does a lot of stuff.  The important thing to know is that after the ACLS instruction, the displays and graphics pages will always be in a known state, so it can only help to begin your program with it.  Since it explicitly sets some things that you may want to override for the purposes of your own program, make sure it's the first line of code and all your changes happen after it.

Like any other form of reading input, you'll want to read from the touchscreen in a loop.  It's fair to assume that you'll also be reading button input in this loop, as you get on to bigger and better projects.  Consider this sample code.

That code should give you an idea of what your game loop might look like in its most basic form.  We read button input so that our loop can check to see if the Y button is among those being pressed, and if it is, the loop will exit.

Now, let's actually output some stuff, so you can see what you're reading from the touchscreen.  This is a rather simple application of LOCATE, the FORMAT$() function, the PRINT statement, and the VSYNC instruction.  Behold, our modified sample code.

The VSYNC instruction is important, because it waits for the rest of the screen to be drawn before letting execution continue.  The argument, in this case, 1, speciifies the number of frames to wait.  Since we want to grab input on every frame, we specify 1.  Specifying 1 is actually optional, but I like to do it.  It's handy at times to update the screen multiple times per frame, perhaps to draw several things at once, but in this case all we're doing is outputting text, so it's pointless to output more than once per frame.

From there, the sky's your limit.  I turned it into a program that allowed drawing on the touchscreen, using the d-pad to change sliders for the RGB value of the color, so that drawing in different colors could happen.  If you'd like to check it out, the public key is B5EXV23E.