Classic Computer Magazine Archive COMPUTE! ISSUE 89 / OCTOBER 1987 / PAGE 74

Super Turtle PILOT

Alan Poole

Here's an exciting new language for the Commodore 64. Graphics, sound, and disk commands make it the most powerful and flexible version of PILOT that we've ever seen. And, for even greater flexibility, it allows BASIC commands to be included in your PILOT programs.

PILOT—an acronym for Programmed Inquiry, Learning, Or Teaching—is a programming language developed in 1968 by John Starkweather. Originally designed as a simple language to help educators write computerized lessons, PILOT is also an excellent language for teaching beginners how to program. In addition to including the standard PILOT commands, "Super Turtle PILOT" enhances the language, adding simple commands for turtle graphics, sprites, sounds, and disk file management. If you prefer BASIC for certain tasks, you can even include BASIC commands in your Super Turtle PILOT (STP) programs.

Getting Started

Since STP is a machine language program, you will need to type it in using "MLX," the machine language entry program found else-where in this issue. Be sure you are familiar with MLX before you begin typing in STP. When MLX asks for starting and ending addresses, respond with the following values:

Starting address: 0801

Ending address: 2068

Type in the data and be sure to save a copy before leaving MLX.

Although Super Turtle PILOT is written in machine language, it loads and runs just like a BASIC program.

Program 2 is an example graphics program. Type it in after running STP. Save the program, and then load it and type RUN.

Working with STP is similar to working with BASIC. After you run Super Turtle PILOT, you can use the standard full-screen editor to type in your PILOT programs just as you would BASIC programs. The LIST, NEW, RUN, LOAD, and SAVE commands all work as they normally do in BASIC. Note, how-ever, that multiple-statement lines are not allowed in PILOT.

You can include BASIC commands anywhere in your program, but the one-statement-per-line rule still applies. When assigning values to variables, you must use BASIC's LET command or PILOT's C: command. Normally acceptable BASIC statements such as A=12 or B$ = "TURTLE" are not allowed; you'd need to use statements like LET A =12 or C:B$="TURTLE". If you have a program made up of both BASIC and STP commands, the two can freely share variables.

The following commands have been added to make programming as easy as possible:

PLISTSends a program listing to the printer.
DIRDisplays the disk directory on the screen.
LOCKDisables the RUN/STOP and RESTORE keys and the LIST command.

PILOT Syntax

This article cannot teach you how to program in the PILOT language. If you are already familiar with BASIC, you should find PILOT relatively easy to learn. Before writing your own programs, study and modify the examples given here. If you are new to programming, your library or bookstore may have books that will teach you how to program in PILOT.

Here's a short quiz written in PILOT. Refer to this program as you read the description below of how PILOT instructions are put together. (Many of PILOT's instructions are similar to BASIC commands.)

30	T :
80	T :
90	A :
130	J : *ANSWER
160	J : *ANSWER
190	E :
220	J : *ANSWER

A PILOT instruction is divided into five parts:

  1. 1. Instruction name. One or two letters.
  2. 2. Conditioner. A Y or an N. Instructions with a Y conditioner are executed if the last Match instruction was successful. An N conditioner causes the instruction to be executed if the last Match failed. See below for a description of Match. Conditioners allow the program to make decisions based on user input. The conditioner is optional.
  3. 3. Expression. A comparison of variables, numbers, or strings. Expressions are placed inside parentheses. The instruction is executed only if the expression is true. The expression is optional.
  4. 4. Colon (:).
  5. 5. Object. Everything that follows the colon is part of the object. The object usually contains data for the command. Some instructions have subcommands that are placed in the object.

A special PILOT instruction is the label. A label is a word preceded by an asterisk, and it must be on a line of its own. It is used as a destination for jumps to other parts of the code.

STP Instructions

T Type. Displays the text specified in the object. Quotation marks are not used. Variables can be displayed by preceding the variable name with a pound sign (#) for numeric variables, or with a dollar sign for string variables. The variable name must be followed by a space or any other character that is not a letter or number. If you place a back arrow (←) at the end of the object, the computer will continue printing the next line at the same position on the screen (similar to the effect of using a semicolon at the end of a PRINT statement in BASIC).

R Remark. Used to put comments in the program. R: is similar to the BASIC command REM.

A Accept. Similar to BASIC's INPUT statement. Makes the computer stop and wait for the user to type a line. Any character (including commas) may be typed. An object is not required, but the input can be assigned to a particular variable by placing the variable name in the object.

M Match. The object contains a series of items (words or numbers) separated by commas. The computer will search the last line typed from an Accept for a match with one of the items in the list. If a match is found, the Y conditioner is set. Otherwise, the N conditioner is set. The position of the matching item in the list is also recorded.

J Jump. Similar to BASIC's GOTO command. Makes the computer continue executing the program at the label that matches the one in the object.

JM Jump on Match. Similar to BASIC's ON-GOTO command. The object contains a series of labels separated by commas. The computer will jump to the label at the position in the list corresponding to the position of the matched item in the most recently executed Match instruction. For example, if the last Match instruction found a match for the third item in its object list, the JM: instruction will cause a jump to the third label in the series.

U Use. Similar to BASIC's GO-SUM command. The computer jumps to the label in the object. It will return to the line following the Use when an E (End) instruction is executed.

UM Use on Match. Similar to BASIC's ON-GOSUB command. Like JM:, the object contains a series of labels separated by commas, and the computer will jump to the label at the position of the most recent match.

E End. Has two functions. If a Use instruction has been executed, the computer will return to the line following the Use. If a Use has not been executed, the program ends.

C Compute. Similar to BASIC's LET command. Assigns values to a numeric or string variable. The object should consist of the variable name, an equal sign (=), and the value to be assigned to the variable. The rules for naming variables are the same as in BASIC: Variable names must begin with an alphabetic character and can include any number of alphanumeric characters, but only the first two are significant (for example, DOWN and DOG are both equivalent to DO). String variable names must end with a $. The value to be assigned to the variable can be either a literal value or an expression to be evaluated. The expression can include other variables, even ones defined in BASIC lines, and any of the BASIC arithmetic operators and functions. For example, C : X = 4 and C : X = (Y * 2) + COS(Z) are both valid.

PA Pause. Creates a delay. The object specifies the length of time to pause (in 1/60-second units).

PC Position Cursor. Sets the screen position of the cursor. The object contains two numbers separated by a comma. The first number is the vertical row (0–24). The second number is the horizontal column (0–39).

H Home. Clears the screen and places the cursor in the top left corner.

S Sound. This must precede all sound commands. See the discussion of sound commands below.

G Graphics. This must precede all graphics commands. See the discussion of graphics commands below. Multiple graphics commands can follow a G: instruction if the commands are separated by semicolons (;).

F File. This must precede all disk commands. See the discussion of file commands below.

DS Define Sprite. Use this command to define the shapes of a sprite. The first instruction in each pattern definition should consist of DS: followed by a # and the sprite number (0–7). Subsequent DS: instructions are used to define the pattern for each line of the sprite. The object for each DS: pattern instruction is a series of up to 24 periods and X's. An X tells the computer to draw a dot in the corresponding position. A period indicates that nothing is to be drawn. Each sprite can be up to 21 lines in height, so up to 21 DS: pattern instructions can be used for each sprite. See the SPRITE command below for additional information about using sprites in STP.


To use the sound commands most effectively, you should be familiar with the operation of the 64's SID chip. Check your Programmer's Reference Guide or COMPUTE!'s Mapping the 64 for details.

To create a sound, the S: instruction is followed by one, two, or three pairs of numbers. The first number in each pair is the pitch (1–65535). The second number is the duration (1–255).

To change the character of the sound produced, the S: instruction can also be followed by one of the following commands:

VOLUME Followed by a number from 0 to 15.

WAVE Followed by a value which specifies the waveform: 1 for triangle, 2 for sawtooth, 3 for pulse, or 4 for random noise.

PULSE Followed by a number from 0 to 4095 to set the pulse width.

ADSR Followed by two numbers separated by a comma. The first number is the attack/decay setting (0–255). The second number is the sustain/release value (0–255).

Graphics Commands

All of the following graphics commands must be preceded by PILOT's G: instruction. More than one command can follow the G:, but multiple commands must be separated by semicolons.

Some commands manipulate a turtle, a kind of graphics cursor that shows your current screen position. The turtle walks across the screen, dragging a pen. You can tell the turtle what direction to go, how far to go, and what color of pen to drag. Turtles make geometric drawing simple. For example, here's a sample program that draws a blue square:

10	G : CLEAR
30	G : DRAW 25; TURN 90; DRAW {SPACE}25; TURN 90; DRAW 25; TURN 90; DRAW 25

CLEAR Sets up and erases a high-resolution graphics screen with a four-line text window at the bottom.

FULL Makes the text window disappear to display full-screen graphics.

MIX Displays a four-line text window at the bottom of the hi-res graphics screen.

QUIT Returns the screen to normal text mode.

POINT Draws a dot on the graphics screen. The command is followed by two values separated by a comma. The values specify the horizontal (x) and vertical (y) coordinates of the point. The Super Turtle PILOT screen coordinate system is quite different from the commonly used one which places the 0,0 point in the upper left corner of the screen. In STP, the 0,0 point is at the center of the screen. As a result, the x coordinate can range from –79 to 80, and the y coordinate can range from –99 to 100. Positive values specify points above or to the right of the center, while negative coordinates are below or to the left.

LINE Draws a line. LINE is followed by coordinates of the first point, the word TO, and the coordinates of the second point. The coordinates used are the same as those used for the POINT command, with the x coordinate in the range –79 to 80 and the y coordinate in the range –99 to 100.

DRAW Tells the turtle to draw a line in the direction of its current heading. The length of the line in pixels is specified by the number following the DRAW command. The turtle can move freely on or off the screen.

DRAWTO Makes the turtle draw a line from its current position to the point specified by the coordinates following the DRAWTO command. The coordinate system is the same as that used in the POINT command.

GO Moves the turtle a specified number of pixels in the direction of its current heading without drawing a line on the screen.

GOTO Makes the turtle jump to the specified coordinates without drawing a line.

TURN Tells the turtle to turn the number of degrees indicated by the number following the TURN command. A positive number turns the turtle counterclockwise, and a negative number turns it clockwise. For example, if the turtle's current heading is 90 degrees, then a TURN 45 command will change the heading to 135 degrees.

TURNTO Sets the angle of the turtle's heading. The angle is specified in degrees, where 0 is east (right), 90 is north (straight up), 180 is west (left), and 270 is south (straight down). Since there are 360 degrees in a circle, the heading is periodic with respect to 360 degrees. For example, TURNTO 360 is equivalent to TURNTO 0, and TURNTO 450 is equivalent to TURNTO 90. The next time you move the turtle, it will move in the specified direction.

PEN Sets the turtle's pen color. The command should be followed by a color number from 0 to 15 or by one of these color names: BLACK, WHITE, RED, CYAN, PURPLE, GREEN, BLUE, YELLOW, ORANGE, BROWN, LT RED, DARK GRAY, MED GRAY, LT GREEN, LT BLUE, or LT GRAY. The PEN command may also be followed by UP, to make the turtle stop drawing lines, or by DOWN, to return it to drawing. PEN ERASE tells the turtle to erase rather than draw as it moves.

FILL Moves the turtle like the DRAW command, but the turtle also fills in to the right with color as it moves. The fill continues until it is blocked by something previously drawn on the screen. If the fill reaches the right side of the screen, it continues on the other side. As a result, you should use this command only when the turtle is in a previously drawn enclosed shape.

BKGD Sets background color of the graphics or text screen.

WINDOW Sets background color of the text window on the graphics screen.

BORDER Sets the border color of the graphics or text screen.

SPRITE Draws a sprite on the text or graphics screen. The command should be followed by the sprite number, a comma, and the coordinates at which the sprite is to be positioned. Unlike the other graphics commands, the SPRITE command uses the standard VIC chip coordinates to specify sprite position—x coordinates can be in the range 0–511, and y coordinates can be in the range 0–255. However, only x coordinates of 24–343 and y coordinates of 50–249 place the sprite fully on the visible portion of the screen. (For values outside these ranges, the sprite may be partially or completely hidden behind the screen border.) Sprite color is set according to the most recent PEN command.

PRINT Sends a printout of the graphics screen to the printer. This command will work only if your printer is a Commodore 1525 or compatible, or if your printer interface provides 1525 emulation. You should also make sure that the printer is turned on before giving this command. The command should be followed by a 1, 2, or 3 to indicated the size of the image to be printed.

The following program demonstrates a variety of the graphics, sprite, and sound commands:

20	 G : LINE -79, 100 TO 80, 100
30	 G : LINE 80, 100 TO 80, -99
40	 G : LINE 80, -99 TO -79, -99
50	 G : LINE -79, -99 TO -79, 100
60	 S : ADSR 0, 242
70	 DS : #0
80	 DS : ..XXXX
90	 DS : .XXXXXX
120	 DS : .XXXXXX
130	 DS : ..XXXX
140	 C : X = 180
150	 C : Y = 150
170	 C : CX = RND (1) * 10 - 5
180	 C : CY = RND (1) * 10 - 5
190	 J (CX < 2 AND CY < 2) : 170
200	 C : X = X + CX
210	 C : Y = Y + CY
220	 G : SPRITE 0, X, Y
230	 U (X > 333 OR X < 29) : *BOUNCE1
240	 U (Y > 241 OR Y < 52) : *BOUNCE2
250	 GET K$
260	 J (K$ = " ") : 140
270	 J : 200
280	 *BOUNCE1
290	 C : CX = -CX
300	 S : 8000, 3
310	 E :
320	 *BOUNCE2
330	 C : CY = -CY
340	 J : 300

File Commands

The F: instruction provides the following commands for manipulating disk files:

WRITE Sends all output from subsequent T (Type)instructions to a sequential file on the disk. The WRITE command should be followed by the name of the file. No quotation marks are used around the filename.

READ Takes all input for subsequent A (Accept) instructions from a sequential file on the disk. The filename is specified following the READ command.

CLOSE Closes any open diskfiles and returns input and output to normal. The command requires no following name or number.

Note : The author has available a 36-page Super Turtle PILOT Reference Manual, which includes many programming examples. For information, write:

Alan Poole
610 Crestwood Cir.
Bountiful, UT 84010

For instructions on entering these programs, please refer to "COMPUTE's Guide to Typing In program" elsewhere in this issue.