COAX HER OUT OF HER SHELL
"Yes, Virginia, there is a turtle." And just to prove it, we've coaxed her (or is it he? ) to show herself to you on a sketchpad that lets you use the joystick to draw in any of the turtle's regular colors. We hope that this entertaining "tool" will be so fun that you'll play with it all year long. Although it is only 128 lines long, this amazing little program will show you how to read the joystick, get input directly from the keyboard, and move a player both horizontally and vertically using PMG but without using a machine language routine!
We know what you're thinking: next, they'll claim that they're rewriting Missile Command in PILOT. We may, someday, but for our present purposes we don't need speed, just a shape that will let us see where the cursor is without interfering with the design. Leaving PILOT is not necessary. We need only C:ompute the new location values and character shape into the RAM locations PILOT uses to create the screen image, and we're set.
When RUN, SketchPad presents you with a title page, which then directs you to draw using a joystick in Port 1. If you press the fire button, the turtle fills as it draws. Pressing [R], [Y], or [B], prompts turtle to use a red, yellow, or blue pen. Press [U] (for up) to move without drawing, and [E] to erase. As with regular turtle graphics, you cannot fill while erasing. So that vou know where the turtle is at all times, a PMG player is positioned in the same location as the turtle, and shadows it wherever it goes.
Our program does not check the cursor location to ensure that the player stays on the screen at all times. As a result, if you drive off the bottom of the screen and keep going, you will eventually poke the player into the display list and get quite a bit of garbage on the screen.
Go off the side of the screen, and the player will quickly return to the screen's opposite side, but the turtle will keep marching to the left (or right) for another 32,748 units or so before starting back toward the other side of the screen.
Going off the top of the screen will - eventually - march your player through the program memory and alter the listing beyond recognition.
Now that you know why you should stay on the screen, you may think about ways in which you can keep the turtle from leaving it. Adding that code would be good programming practice. Let's look at the listing and see how SketchPad works. To speed things up, we've placed the least-used routines at the end of the program. We J:ump to them in line 10 so that the computer never has to see them again. The routine called *PLAYER (starting at line 20) gives the GR:aphics commands to the turtle and POKEs the player into it's new location.
First, we keep the trigger value variable. A zero here means that the fire button has not been pushed. A one means that it has. We "froze" %T8 into variable #T so that the value won't change if you stop firing midway through the routine.
Line 40 is executed if the trigger is not pressed or if the pen is set to erase. To determine if the pen is set to erase, look into the special memory location where PILOT stores the current pen color -- @B1363. A zero here means erase, one means red, two means yellow, and three means blue. The command is executed if either of the conditions is true. This tells the turtle to draw to its new location (as decided by another routine).
The turtle's present coordinates are contained in PILOT machine variables %X and %Y. Adding #B to the current location in %X gives us the new horizontal coordinate. By using the same simple step, but this time subtracting #A from %Y, we can produce the new vertical position. The NORTH, SOUTH, etc. routines C:ompute values into #B and #A, depending on the joystick location.
Line 50 tells the turtle to fill to the same new location, if the trigger is pressed and the pen is not set to erase. (Multiplying conditions means they all must be true for the command to operate.)
Next, we'll show you how to move the player and stay with the turtle. Remember that #A is the change in the vertical position. Since the player moves vertically in half-steps, we must multiply #A by two (Line 6O) before it can be used to increment the player's position. Variable #J indicates the old vertical position of the player.
Line 70 adds the player-movement amount we C:omputed in line 60 to the old player position in #J to give us the new player location. Line 80 stores the new value as #Y.
Ready for the fun part? When the player moves vertically, it must be moved within the computer memory, and C:omputed into the new location byte-by-byte. This process is just like C:omputing a new character set into RAM (which was explained in detail in ANTIC, "Pilot Your Atari," page 37, August 1983). The decimal values for each line within the player are C:omputed into B#Y and the next nine bytes in lines 90-270. The zeros at the edges of the player are used to erase any piece left behind during the move.
To the computer, our player looks like this:
00000000 = 0
00000000 = 0
00100010 = 34
00010100 = 20
00001000 = 8
00001000 = 8
00010100 = 20
00100010 = 34
00000000 = 0
00000000 = 0
Because PILOT will not accept C:@B#Y+1=0, we must increment the byte in one line and C:ompute the value into the next.
Horizontal movement is easy. Just add the change in position (#B) to the old position (#X) and C:ompute the new value into B53248, which is the horizontal position register for player zero. Atari's powerful graphics chip, ANTIC, takes care of horizontal travel. Lines 300 and 310 reset the values of #A and #B (our position changes) for the next time through the loop.
In line 320, we remind the turtle which color she is supposed to draw or fill with by C:omputing #C into B1363. The #C is set by *COLORCHANGE at lines 850 through 960. B764 holds the internal hardware value for the last key pressed. If that key is a [Y], [B], [R], [E], [U], or [CTRL C], the proper GR:aphics command will be executed. Line 930 "rings the internal bell" if any one of the command letters has been pressed.
Remember to press [ESC] before pressing [CTRL] and  when typing this line. The new pen color is stored in #C, and B764 is reset with a 255 so that it's ready to be checked for new input.
The *MAINLINE routine that starts at line 330 puts a zero into B77 (the attract flag) to keep the screen colors from changing. Normally, they rotate to protect the screen if no input is entered on the keyboard within nine minutes. This kind, of protection is required whenever you use joysticks for input. Next, *MAINLINE checks the keyboard @B764 to see if there is a number other than 255 there. A number other than 255 means that the user wants to change pens, so the program U:ses *COLORCHANGE.
Beginning at line 360, *MAINLINE A:ccepts the joystick position (%J0), M:atches it against its possible values, and J:umps to whichever routine correctly C:omputes the changes in position (#A and #B). We then J:ump back to *PLAYER to move the turtle and player, and start through the cycle again. Be careful when you type line 370. For each value to be significant, there must be a space both before and after it! If you do not include the comment at the end of line 370, you must add an underline after the five at the end of the line.
*SETUP (starting at line 600) contains the heart of the PMG. After clearing the screen, setting the pen color and turtle position, saving the initial pen color as #C, and T:yping "please wait," we need to initialize the player. First, we must enable the PMG routines. Computing a 62 into B559 tells ANTIC that we will be using PMG and that we want a standard-sized playfield, players and missiles (although we won't use all of them), as well as one-line player resolution.
By defining #I as 6K less than the real amount of memory available (@B106), and POKEing that value into B54279 (PMBASE), we allow ANTIC to use the top 6K of memory to take care of players and missiles. C:omputing a zero into B53256 tells ANTIC that the player is normal-sized (line 680). Line 690 sets the player's original byte position (#J), which is the page (#I) multiplied by 256 (bytes per page) and added to 1,024 (which is how far ANTIC says player zero must be from the PM base).
*CLEARPLAYER (line 710) keeps you from having two players on the screen if the program is being rerun. It puts a zero into the first byte of the player (#J), increments #J and a loop counter (#X), and loops through until all of the 256 bytes available to player zero are cleared.
We must then recalculate the player's original byte position and add 124 to it, so that the player will appear in the center of the screen. Putting a one into B623 tells ANTIC that the player has priority over all of the background colors. #X is set at 124, the original horizontal position of the player, and is C:omputed into B53248 to let ANTIC know where the player is.
(Clearplayer prevents two players from appearing when you re-RUN the program. If you [BREAK] the program and attempt to clear the screen, however, the screen will fill with garbage. Just hit [RESET]. --KWH)
The player's color is set to white (line 800) and the players are lit up by C:omputing a three into B53277. A zero here makes the player disappear. Now, all of our housekeeping is finished, and our player is ready to go!
The remainder of the program types the instructions and the title page. This section is followed by a set of R:emark Statements that list the variables used and what they mean. (Including a table like this in a program is a very good habit to form. A few weeks - or even a few days - after you have written a program, you may wish to modify it. Being reminded which variables are available for use, and which ones have been defined, is a real time-saver.)
In conclusion, we hope that you have a New Year full of fun designing with Sketchpad and writing Player/Missile graphics programs of your own. Good luck! Next month. it's back to Logo for a look at a wide range of books and resource materials that are available for home and school.
This winter season brings back those coding elves of the North (Puyallup, Washington, that is), Kathy and Phil Bergh. Their "Turtle SketchPad" program is a tour de force that integrates PILOT and Player/Missle graphics (PMG). PMG mechanics have been fully covered in other ANTIC articles; I have also found Educational Software's "Tricky Tutorial" on the subject to be excellent. But for this program, just type away; it works fine. - Ken Harms