Chapter 8. SPRITES - MOVING PICTURE BLOCKS

If you wish to see a sample program which makes use of sprites, run 
SAMPLE9.PIL on the PILOT distribution diskette.  

PILOT supports the use of sprites. A sprite is a small image or picture 
consisting of a grid of 32 pixels across by 32 pixels up and down. Each pixel 
can be one of three colors or transparent.  Within a PILOT program sprites 
can be displayed on the screen, either standing still or in motion.  

Sprites are stored on disk and within a PILOT program in a sprite table. A 
sprite table consists of eight 32 pixel by 32 pixel sprites, numbered 1 to 8.  
Pictorially, a sprite table can be viewed as follows: 

         A Sprite Table

     +-----+-----+-----+-----+
     |     |     |     |     |
     |  1  |  2  |  3  |  4  |
     |     |     |     |     |
     +-----+-----+-----+-----+
     |     |     |     |     |
     |  5  |  6  |  7  |  8  |
     |     |     |     |     |
     +-----+-----+-----+-----+  


Each of the boxes, numbered 1 to 8, above represents one 32 pixel by 32 pixel 
sprite.  


PILOT allows you to combine the sprites in a table in order to create larger 
sprites. There are several possible ways to create these combinations. The 
first combines two sprites to create a 32 by 64 pixel sprite. This is 
accomplished by simply viewing a sprite table in the following way: 

     +-----+-----+-----+-----+
     |     |     |           |
     |     |     |    11     |
     |     |     |           |
     +  9  +  10 +-----+-----+
     |     |     |           |
     |     |     |    12     |
     |     |     |           |
     +-----+-----+-----+-----+  

Sprites 1 and 5 can be combined and treated as a pair by referring to the 
combination as sprite 9. Sprites 2 and 6 can be combined as sprite 10.  
Sprites 3 and 4 can be combined as sprite 11. And sprites 7 and 8 can be 
combined as 12.  

You can also combine 4 sprites in the two following ways: 

     +-----+-----+-----+-----+
     |           |           |
     |           |           | 
     |           |           |
     +     13    +    14     +
     |           |           |
     |           |           |
     |           |           |
     +-----+-----+-----+-----+  

Sprite 13 is a combination of sprites 1,2,5 and 6. Sprite 14 is a combination 
of sprites 3,4,7 and 8. 

     +-----+-----+-----+-----+
     |                       |
     |          15           | 
     |                       |
     +-----+-----+-----+-----+
     |                       |
     |          16           |
     |                       |
     +-----+-----+-----+-----+  

Sprite 15 is a combination of sprites 1,2,3 and 4. Sprite 16 is a combination 
of sprites 5,6,7 and 8. 

Finally, all 8 sprites can be treated as one large sprite, numbered sprite 
17.  

     +-----+-----+-----+-----+
     |                       |
     |                       |
     |                       |
     +          17           +
     |                       |
     |                       |
     |                       |
     +-----+-----+-----+-----+  


Within one sprite table you can think of the eight sprites in any combination 
that makes sense for your own program. For example, you could use sprite 16 
for a 128 by 32 pixel sprite, use sprite 11 for a 64 by 32 pixel sprite, and 
use sprites 1 and 2 for two 32 by 32 pixel sprites.  


On disk, a sprite table is stored in a 2048 byte file with the file suffix of 
.SPR. For example: 

       ATOMS.SPR

In one PILOT program you can have as many sprite tables as you need, limited 
only by the amount of memory you wish to set aside for sprite tables.  


HOW TO EDIT SPRITE TABLES


The program SE,  Sprite Editor, is provided to create and edit sprite tables. 
With SE you can: 

1. Cut sprite images out of a graphics image file and paste them into a 
sprite table.  

2. Cut sprites out of a sprite table and paste them into a graphics image 
file.  

3. Touch up a sprite in a sprite table.  

4. Create a sprite from scratch via fat bits mode 

5. View any of the 17 possible sprite combinations that can be used.  

To run SE and use sprites, requires a color display adapter. A monochrome 
adapter does not support the use of sprites. You can start SE by entering the 
command: 

       SE

The SE program prompts you for the name of the sprite table you wish to work 
on. If the sprite table already exists, enter the root name of the sprite 
table file (without the .SPR on the end).  To create a new sprite table, 
either enter the name of the new the sprite table file (without the .SPR on 
the end) or push the ENTER key.  

Next, SE prompts you for the name of a graphics image file. This file must be 
in the bit-mapped format. It could be made by GIE, the PILOT GSX: statement 
or another graphics creation program that saves images in bit-mapped format.  
Images saved in a compressed format will not load into the sprite editor. If 
you intend to cut sprites out of a graphic image and paste them into the 
sprite table, enter the name of the graphics image at this point. Be sure to 
enter the entire file name, including the suffix. If you do not wish to work 
with a graphics image, just push ENTER.  

Once SE has started, the top left portion of the screen displays the sprite 
table you are working on.  The top right portion of the screen displays a 
help menu. If you have loaded a graphics image, part of it is displayed in 
the bottom portion of the screen.  Note also that on the bottom left portion 
of the image a sprite-sized cut-out box overlays the bit-mapped image.  

The sprite editor is controlled by means of the various function and cursor 
keys. The operations you can perform are shown below.  


F1 - select sprite to work on 

Each time you push F1, the next sprite in line is selected for operation. The 
current sprite is indicated by a colored number under the sprite.  


F2 - select sprite layout 

Each time you push F2, the sprite layout changes. You will see the possible 
combinations that can be created by referring to sprites numbered 1 through 
17. Notice that the cut-out box on the graphic image changes size to reflect 
the sprite layout and sprite number selected.  


F3 - copy from image to sprite 

F3 copies the contents of the cut-out box on the graphic image to the 
currently selected sprite. (If you make a mistake, you can undo the last 
operation by pushing the Esc key at any time.) With this feature, you can use 
any paint program, such as GIE or its equivalent, to create sprites, then use 
the F3 function in SE to cut the picture out of the graphics image and paste 
it into a sprite table.  

F4 - copy from sprite to image 

F4 copies the currently selected sprite to the graphic image within the cut-
out box. (If you make a mistake, the Esc key can be used to undo the 
mistake.) Using the F4 key you can copy a sprite back to a graphic image so 
that you can later use a graphics editor to modify the sprite.  


F5 - load new sprite table 

When you push F5, SE prompts for the name of a sprite table. The new sprite 
table will be loaded over the currently loaded sprite table.  When you push 
F5, the prompt for a table name contains the last table name you entered in 
brackets. If you wish to load the same table just push ENTER. Loading a new 
table destroys the currently loaded table in memory so be sure to save the 
current table first if you wish to do so. If you wish to load another table 
name, type the name (without the .SPR appended to the name), and push ENTER. 
You can precede the file name with a drive or path designation if needed. If 
you have made a mistake and wish to cancel the load command, push the Esc key 
prior to pushing ENTER.  

F6 - save sprite table on disk 

If you wish to save the sprite table without leaving the SE program, push the 
F6 key. SE prompts for the name of the file to be saved. If you wish to save 
to the file name shown in brackets, just push ENTER. If you wish to enter 
another file name, type it without the .SPR suffix, then push ENTER. If you 
wish to cancel the save operation, push the Esc key.  

F7 - load graphics image 

The F7 key loads a new graphics image for display on the bottom portion of 
the screen. SE prompts for the name of the image file to be loaded, showing 
the last supplied name in brackets. To load the same file just push ENTER. To 
load a different file, type the file name and push ENTER. To cancel the 
operation push Esc.  

F8 - save graphics image 

The F8 key saves the current graphics image on disk.  To save the image to 
the file name shown in brackets, just push the ENTER key. To save to another 
file, enter the file name then push ENTER. To cancel the save operation push 
Esc.  

F9 - enter fat bits, or touch-up mode 

This key can be used only when a sprite number in the range 1 through 8 is 
selected. The selected sprite is shown in an expanded format so that 
individual pixels can be identified and edited. This mode can be used to 
create a totally new sprite from scratch or can be used to edit or touch up, 
a sprite created previously. See Fat Bits Mode below for more information. On 
combination sprites (numbers 9-17) you will have to edit one 32 by 32 pixel 
segment at a time.  

F10 - exit sprite editor 

The F10 key terminates processing of the SE program.  If you have made any 
changes to the sprite table, SE prompts for the name of a file in which to 
save the sprite table. If you have previously given a sprite table name, the 
name is shown in brackets. To save to the same file name just push ENTER. To 
save to another file name, enter the file name and push ENTER. If there is no 
name shown in brackets (ie, you have not previously entered a sprite table 
file name), you must enter the name of a file in order to save the sprite 
table; just pushing ENTER in this case bypasses the save operation.  To force 
a bypass of the save operation, push the Esc key.  

If the graphics image has been modified, SE prompts similarly for the name of 
a file to which the graphics image is to be written. If you write the 
graphics image to the same file name, then the original graphics image is 
overwritten on disk. If you wish to retain the original image then enter a 
different file name.  If you wish to discard the loaded image then push the 
ESC key to bypass the save operation.  


ESC - undo last operation 

The Esc key can be used to back out of an erroneous operation. If pushed 
after F3 or F4, the copy operation is undone. If pushed when prompted for a 
file name to load or save, the load or save is canceled.  

ARROW KEYS - roll graphics image 

The four arrow keys: up, down, left and right can be used to roll the 
graphics image one pixel in any direction. Holding shift while pushing any of 
the arrow keys rolls the graphics image by 32 pixels at a time. As the image 
is rolled, it wraps around from the left to the right or the top to the 
bottom.  Notice that even though part of the image is hidden behind the upper 
portion of the SE screen, as the image is rolled up or down, the hidden 
portion can be brought into view on the bottom of the screen. Using these 
keys, the image can be adjusted to place any desired portion within the cut-
out box shown in the lower left part of the screen.  


FAT BITS MODE 

The F9 key can be used to enter fat bits mode.  To use fat bits mode the 
currently selected sprite number must be in the range 1 to 8. F9 is ignored 
for higher numbered sprites.  

In fat bits mode, the sprite is displayed in normal size and an expanded size 
that shows the color of each individual pixel. Also shown is a help menu and 
several status indicators. To the right of the sprite is a number from 1 to 3 
showing which color is presently selected for pixel setting. Next to the 
number is a plus sign, if stream set mode is selected, or a minus sign, if 
stream clear mode is selected. Also shown is a model TS:, TYPE SCREEN 
statement, showing the mode and background colors you would use in your PILOT 
program to produce the same color combinations.  

Within the expanded sprite, a small box-shaped  cursor shows the position of 
the current pixel within the sprite.  

The sprite can be modified, pixel by pixel, through the use of the various 
function and cursor keys as shown here.  

To set or clear a pixel you can move the cursor to the desired pixel, then 
push F1 or F2. If you wish to set or clear several contiguous pixels, you can 
use stream set or stream clear modes.  With either stream mode set each pixel 
is set or cleared immediately as the cursor is moved from one pixel to 
another by the arrow keys.  


F1 - set a pixel 

The F1 key sets the current pixel to the currently selected color. F1 also 
turns off either stream mode, if set.  

F2 - clear a pixel 

The F2 key clears the current pixel to the background color. F2 also turns 
off either stream mode if set.  

Shift F1 - stream set mode on 

Shift-F1 turns on stream set mode. When stream set mode is on, the cursor 
keys automatically set each pixel to the current color as the cursor moves 
from one pixel to another.  

Shift F2 - stream clear mode on 

Shift-F2 turns on stream clear mode. When stream clear mode is on, the cursor 
keys automatically clear each pixel to the background color as the cursor 
moves from one pixel to another.  

Shift F5 - clear entire sprite to background 

The shift-F5 combination erases the entire sprite to background color.  

F8 - change screen mode 

The F8 key alternates between screen modes 4 and 5. Note that the color 
combinations change as does the model TS: statement shown next to the sprite. 
This allows you to see the sprite as it will appear in your PILOT program.  

F10 - exit fat bits mode 

The F10 key returns to the SE main screen with the edited sprite placed in 
the sprite table.  
 
ARROWS - move pixel cursor 

The up, down, right and left arrow keys can be used to move the pixel cursor 
one space in any direction.  If the stream set or stream clear mode is on, 
then moving the cursor also sets or clears the pixel to which the cursor 
moves.  

PLUS and MINUS - change background color 

The + key increments the background color. The - key decrements the 
background color. The possible colors are 0 through 31. Backgrounds 16 
through 31 are the same as 0 through 15 except that the foreground colors are 
brighter. Note that as the background color changes on the screen, the model 
TS: statement changes to reflect the current color number. This command lets 
you see the sprite displayed with in the colors you will see in your PILOT 
program.  

USING SPRITES IN A PILOT PROGRAM

To use sprites in a PILOT program follow these steps: 

1. Use SE to create a sprite table. The sprite table is saved on a disk file, 
say MINE.SPR 

2. In the PILOT program, create a string variable 2218 bytes longs to hold 
the sprite table. The following statement would work fine: 
  
       D:MINE$(2218)

3. Read the sprite table from disk into the string variable via statements 
such as: 

       FX:MINE.SPR
       FI:0,MINE$

4. Set the screen mode to a graphics mode valid for sprites (mode 4, 5 or 6).  
For example: 

        TS:M4

5. Use the Graphics statement to specify the current sprite table via: 

        G: S MINE$

6. Use the Graphics statement to display or move sprites on the screen.  

Sprites are manipulated via turtle graphics commands on the Graphics 
statement. The turtle graphics commands allow you to move an invisible turtle 
around on the screen by commands such as forward, right, left and draw. To 
manipulate sprites you can: 

1. Draw any sprite at the current turtle location and leave it there.  

2. Remove a previously drawn sprite from the screen.  

3. Draw a sprite at the current turtle location and attach it to the turtle 
so that it is dragged around on the screen when the turtle is moved.  

4. Leave a sprite on the screen, move the turtle to some other location on 
the screen, then return to the spot where the sprite was left to move or 
remove it.  

SPRITE DRAWING 

When a sprite is drawn on the screen, it is located such that the upper left 
pixel of the sprite is at the turtle location. If a sprite hangs off the 
right side of the screen, it wraps to the left side.  Likewise, if the sprite 
hangs off the bottom of the screen, it wraps to the top of the screen.  

When a sprite is drawn, it is combined with the data already on the screen so 
that the background-colored bits in the sprite are transparent. That is, the 
previous display data shows through wherever the sprite pixels are not set to 
a color.  

Colored pixels in a sprite are combined with the previous display data so 
that when the sprite is again removed, the previous display data is restored.  
This means that a sprite can pass over another complex picture without 
changing the other picture.  In mathematical terms, sprites are drawn via an 
exclusive or operation. This means also that drawing a sprite once in a 
location makes it appear, then drawing it again in the same location makes it 
disappear again.  

SPRITE COMMANDS

The specific commands that affect sprites are as follows.  

G: S V$

Makes string variable V$ the current sprite table.  V$ must have been first 
dimensioned at least 2218 bytes and must have been read from a sprite file as 
shown above. There may be any number of sprite tables in memory and you can 
change the current sprite table as often as necessary.  

G: Sn

Displays (or erases) sprite number n, (n from 1 to 17). Also attaches sprite 
n to the turtle.  

G: S0

If any sprite is attached to the turtle, it is detached and left in its 
current location. This command insures that no sprite is attached to the 
turtle.  

G: Fn

The normal forward command which moves the turtle. If a sprite is attached to 
the turtle, it is moved along with the turtle to the new location. When a 
sprite is attached to the turtle no line is drawn by the forward command.  

G: Rn;Ln

The normal turtle right and left turn commands.  These commands are used to 
set the direction of motion of a sprite when attached to the turtle.  

G: Dx,y

The normal draw to pixel x,y command which, when a sprite is not attached to 
the turtle, draws a line to the absolute pixel named. When a sprite is 
attached to the turtle, no line is drawn, but the sprite is moved from the 
old location to the new location.  

G: Gx,y

The move to absolute pixel command.  If a sprite is attached to the turtle, 
it is detached and left in its present location. The turtle moves to the new 
location without any sprite attached.  

G: Jn

If a sprite other than sprite n is attached to the turtle, it is detached and 
left in its present location. Then the turtle jumps to the location and 
heading, where sprite n was last left on the screen.  

G: Wn

This command causes a wait for n 60ths of a second. It does not directly 
affect sprites, except that it is very useful in adjusting the speed at which 
sprites move.  

All of the above commands, as well as all other Graphic statement commands 
can be combined per the normal G: statement syntax.  


SPRITE HINTS

Often sprites can be used as "little pictures", that is, as a way to display 
small illustrations or diagrams which do not move at all on the screen.  
Sometimes a sprite is an economical way to store a graphic image rather than 
to use an entire screen image.  

To make a sprite move, attach it to the turtle, then use the forward, right 
and left commands in a loop to move the turtle.  

Though a sprite can theoretically be at any pixel location, in actuality 
sprites are drawn at the nearest 2-pixel boundary vertically, and the nearest 
4-pixel boundary horizontally. So moving a sprite in steps less than this 
size may not cause any visible motion.  

There are two ways to affect the speed of motion. The first is by adjusting 
the step size taken by the forward command. The larger the step, the faster 
the apparent motion. The second is to introduce delays into the loop which 
contains the forward command. The G:Wn command can be used to do this. The 
longer the delay at each step, the slower the apparent motion.  

The smoothest motion is attained by the smaller sprites (numbers 1 to 8). The 
larger the sprite, the more processing time it takes to display it, and the 
less smoothly it will appear to move.  

To move more than one sprite at a time, use the G:Jn command to jump back and 
forth between them, moving each one a small amount per iteration.  

To make a sprite change shape as it moves (eg. a man walking across the 
screen), create a series of sprites which depict the man in each position. 
Then as the sprite is moved via forward statements, rotate through the series 
of positions simultaneously.  

A graphics statement command sequence that performs a complex animation can 
be stored in a string variable and called out via the X: statement. Such a 
statement can be up to 256 bytes in length.  

SPRITE EXAMPLES 

SAMPLE9.PIL on the PILOT distribution diskette is a sample sprite program. 
Also, SAMPLE9.SPR contains a sprite table which you could copy and use for 
your own experimentation.  

The following examples assume that these statements have been executed 
previously in the PILOT program.  These statements read the sprite table from 
file MYSPRITE.SPR to the string variable X$, set graphics mode, and set X$ as 
the current sprite table.  

       D:X$(2218)
       FX:MYSPRITE.SPR
       FI:0,X$
       TS:M4
       G:SX$
      
Example 1: To place sprites 1, 2 and 3 at different stationary 
screen locations.  

       G:G100,50;S1; G200,87;S2; G225,125;S3; S0 

Example 2: To make sprite 3 appear, move it across the screen, then make it 
disappear.  

       G:G0,0; S3; H90; *200(F8; W3); S3; S0

Example 3: To make sprite 3 appear, move it from the bottom of the screen to 
the top, then leave it stationary on the screen.  

       G:G100,160; S3; H0; *400(F1); S0

Example 4: To make a sprite appear, then go off and do other things, then 
later to move the sprite to a new location and leave it there.  

       G:G100,60; S6; S0
       < go off and do other things>
       G:J6; D190,20; S0; 

Example 5: To move two sprites simultaneously.  The first statement below 
positions each sprite at its starting position and heading. The second 
statement jumps back and forth between them moving each one a small amount, 
repeatedly.  

       G:G10,10;S3;H180; G280,100;S4;H270; S0
       G:*100(J3;F4; J4;F4; W5); S0

Example 6: move a sprite in a circle 

       G:S7; *40(F10;R9;W1)

Example 7: move a sprite and change the shape as it moves. This example 
assumes that sprites 1 and 2 have been created to show a man walking with 
arms and legs in two different positions.  

       G:*20(S1;W5;F4;S1;S0; S2;W5;F4;S2;S0)

