Sprite state management.  Set zero or more properties of a sprite.

 

SPRITE allows you to set most of the properties of a sprite, which is a hardware image that me be freely placed over (or sometimes behind) other elements on the screen.  There are 8 hardware sprites provided by the (40-column) VIC-II(e) chip.  No sprites are available on the (80-column) VDC chip.  Hardware trivia: the C128 has a VIC-IIe, while the C64 has a VIC-II.  These operate the same in terms of sprites (and most other things), although BASIC v2 of the C64 does not have any sprite commands.

 

The parameter sprite indicates which one you would like manipulate, and is the only required parameter.  All other parameters, except chipColor, act as flags to enable/disable certain properties of a sprite (described below).  I call these values 'absolute boolean' because unlike the relational and boolean operators of BASIC (which are signed values, 0 or -1) these must be unsigned values.  You can use ABS or negation (-) to convert a BASIC boolean expression into a value compatible with SPRITE.

 

Although any parameter (execept sprite) may be omitted (in which case it will keep its previous value), BASIC does not set any SPRITE properties when you RUN a program.  So any program using sprites should define all properties at least once.  In fact, except for SPRDEF, BASIC never initializes any of the SPRITE properties!  The KERNAL I/O initialize routine, called on power-up and STOP + Restore, sets all absolute boolean parameters of all sprites to zero/false.  It also sets the chipColor of each sprite to the corresponding sprite number.  So sprite 3, for example will be set to chipColor 3 (red).

 

The enable parameter makes the sprite potentially visible (if its value is 1/true).  To actually be visible, the image of the sprite must have at least one non-transparent pixel (see SPRDEF and SPRSAV), it must be within the visible screen area (see MOVSPR), and it must not be hidden behind other objects (see behind below).  Even when these conditions are met, you may not "see" the sprite if its pixels are the same color as the pixels it covers (similar to a cameleon).  If enable is zero/false, then sprite will not be displayed.

 

The chipColor sets one of the colors used in the sprite's image.  High-resolution sprites only have one color; any pixel in the sprite's image set to 1 will have the chipColor.  Multi-color sprites have three colors avaialble: the chipColor set here (which applies only to this sprite) plus two more colors shared by all multi-color sprites (see SPRCOLOR).  For multi-color sprites, the pixels in its image which are set to binary 10 will use the chipColor.  For both types (high-resolution and multi-color), any pixel having value zero will be transparent.

 

The behind parameter, when set to one/true, allows the sprite to appear behind foreground pixels (a sprite always appears above background pixels).  Typically it is desired that a sprite appears over all screen elements (i.e., behind set to zero/false).  However there are some exceptions.  The sprite will never appear over the border, and when the (non-transparent) pixels of two (or more) sprites occur at the same coordinate (pixel) then the sprite with the lowest number will have priority (appear "above" the others, hiding them).

 

The expandX and expandY will double the size of the sprite's image in the horizontal and vertical directions, respectively, when set to one/true.  When expanded, the pixels of the sprite's image will be drawn at twice their normal (un-expanded) size (in particular, you do not get any extra pixels to use in the image).  A normal (un-expanded) sprite is 24 high-resolution pixels wide and 21 pixels tall.  Using expandX, the sprite becomes 48 high-resolution pixels wide.  Using expandY, the sprite becomes 42 pixels tall.

 

The final parameter, multiColor, will render the sprite (when enabled) in multi-color mode when this parameter is one/true, or in high-resolution mode when this parameter is zero/false.  In high-resolution mode, each bit in the sprite's image selects a "color": transparent or chipColor.  In multi-color mode, each pair of bits in the sprite's image selects a "color": %00 = transparent, %01 = mcColor1, %10 = chipColor, or %11 = mcColor2.  However, the VIC-II(e) does not allow any more memory to define the image of the sprite, nor does it reduce the on-screen size of the sprite.  Instead, a multi-color sprite appears with each pixel in its image twice as wide.  The implies that the resolution of a multi-color sprite is reduced from 24 to 12 pixels in width (but remember it still occupies 24 high-resolution pixels of space).  Because the resolution is cut in half (horizontally) it looks a bit "chunky"; when combined with expandX it looks down-right blocky.

 

The mode of the sprite (multi-color or high-resolution) is independant and unrelated to the current display mode (high-res bitmap or multi-color bitmap or high-res text).  However when the screen is in multi-color bitmap mode, it is important to note that bitmap pixels defined with values of either 0 or 1 are considered background and the sprite will always appear above them.  The sprite may appear above or behind bitmap pixels having a value of 2 or 3 depending on the parameter behind.

 

If sprite is omitted, any parameter is an invalid expression, or if any extra parameter(s) are given, then SYNTAX ERROR occurs.  If any parameter is not numeric, TYPE MISMATCH ERROR occurs; you may manually convert a string with VAL.  Any floating-point parameter is automatically converted with INT.  If the result is not a Legal Value (see table above), ILLEGAL QUANTITY ERROR occurs.

 

There are several important properties of the sprite that are not set by SPRITE.  These include the sprite's image (see SPRDEF and SSHAPE), its position and speed (see MOVSPR), and for a multi-color sprite, the shared sprite colors (see SPRCOLOR).

 

Examples (you should first use SPRDEF to define sprite 1's image to see results) :

SPRITE 2,0 : REM turn off sprite 2

READY.
SPRITE 1,1,4 : REM turn on sprite 1 and make color it Cyan

READY.
SPRITE 1,,,1 : REM make it appear behind foreground objects

READY.
SPRITE 1,,,,0,1 : REM make it twice as tall but normal width (1x and 2y)

READY.
SPRITE 1,,,,0,0,1 : REM normal size (1x and 1y), but multi-color mode

READY.

 

 

COLOR, GRAPHIC

 

DS, JOY, PEN, POS, POT, RDOT, RSPPOS, RSPRITE, ST
 

MOVSPR, SPRCOLOR, SPRDEF, SPRSAV