SuperBASIC 64

Martin C. Kees

How would you like to be able to access 37 valuable new commands when you're programming on your 64? SuperBASIC adds sprite, color, graphics, sound, and memory management features and also enhances eight of BASIC'S own commands. And it's designed to work as easily and as quickly as any ordinary BASIC instruction. Typing it into your computer is foolproof; you won't be allowed to go on to the next line if you make a typing error. (See the instructions for using the MLX entry method, on page 216.) Once you try it, you'll wonder how you programmed without Super­BASIC — it's an especially valuable addition to any 64 owner's library of programs. As a bonus, there's also a PET emulator and several demonstration programs so you can see SuperBASIC in action.

SuperBASIC adds commands to BASIC using a special technique. BASIC is automatically copied to its matching RAM and modified to change the STOP command to a wedge vector (similar to Apple's ampersand (&) wedge). The character chosen was the left bracket ([). Then, using four-letter mnemonics following the wedge character, you can select what you want SuperBASIC to do.

These machine language routines make it very easy to control virtually all the VIC-II chip special features. Sprites and hi-res graphics can be controlled from BASIC without having to POKE or use Boolean functions to enable special graphics modes. Since BASIC was moved to RAM to implement the [ wedge, this made it convenient to enhance a few BASIC commands. I added the use of variable expressions for GOTO and GOSUB, and RESTORE by line number. These changes to BASIC in RAM don't slow execution as they would have if CHRGET wedging techniques had been used.

SuperBASIC Command Format

The commands can be used in both direct or program mode. The general format is [xxxx <exp>,<exp> where xxxx represents the four-character mnemonic and <exp> is a number, variable, or a valid BASIC expression. When a color is selected, use the standard value ordinarily POKEd to the VIC chip. I have used the same coordinate system for sprite positions as given in Commodore documentation. The hi-res upper-left corner is 0,0, and the lower-right is 319,199. Commands that switch a function on or off use 0 for off and 1 for on.

SuperBASIC includes two types of changes to normal BASIC, enhanced commands and new commands. Enhanced commands include GOTO and GOSUB and variants with IF and ON. You can use a line number expression for these commands. This can help in program readability, allowing constructions such as GOTO KEY where KEY=1000. This would transfer control to line 1000. RESTORE can also be followed by a line number expression. RESTORE KEY would cause the next READ to use the first DATA statement encountered at or after line 1000. This allows DATA statements to be selected under program control. Small files could be maintained in DATA statements and accessed by line number. When LISTing a program, the SHIFT key pauses the list until released. The ASC function will return a value of zero for null strings.

The new commands can be divided into five categories: sprite, sound, color control, VIC memory mapping, and graphics control. A convenience command [ CATA is also included. This lists to the screen all mnemonics defined in SuperBASIC.

Loading The Program

To type in SuperBASIC 64 (Program 1), you must use the "MLX Machine Language Editor" program presented elsewhere in this issue. Be sure that you read the MLX article and understand how to use MLX before attempting to enter SuperBASIC.

The numbers you type in create a low memory loader for SuperBASIC which can be LOADed and RUN as if it were a BASIC program. Because the data for the SuperBASIC loader must go into the same area of memory where BASIC normally resides, a special tactic must be used to prevent the SuperBASIC data from overwriting MLX as it is entered. First, turn the computer off and back on to reset memory pointers to their normal values. Next, type in the following line in direct mode (without a line number) and hit RETURN:

POKE 44, 22 : POKE 642, 22 : POKE 5632, 0 : NEW

This moves up the start of the memory area used by BASIC so that all of the data for SuperBASIC will fit below MLX without interference. Now LOAD and RUN the MLX program in the normal manner. When MLX asks for the starting and ending addresses for SuperBASIC, give 2049 as the start and 5264 for the end. When you finish typing in the data for SuperBASIC, use the MLX Save command to store a copy of the SuperBASIC loader on disk or tape. If you do not type in all the data for SuperBASIC in one session, you must repeat the procedure for moving up the start of BASIC before loading MLX to complete your entry.

When you have a complete copy of the loader, you must reset memory to its normal conditions before LOADing and RUNning SuperBASIC. You can do this by turning the computer off and back on, or with the command SYS 64738. When you RUN the SuperBASIC loader, it first copies BASIC from ROM into the underlying RAM and makes modifications to certain commands. Then it copies the machine language for the rest of the SuperBASIC routines into memory at $C000 – $CC00. No other machine language subroutines which use memory starting at $C000 can be used with SuperBASIC 64, but the DOS Wedge program can be used without conflict. The loader erases itself from the BASIC memory area after it is RUN.

The SuperBASIC commands will be enabled until you hit RUN/STOP-RESTORE or POKE 1, 55. Once loaded, SuperBASIC can be reenabled with POKE 1, 54. The programs you write with SuperBASIC commands are loaded and saved in the normal manner. The only conflict with normal BASIC is the use of the STOP command. It is not available; use END instead. When SuperBASIC commands are listed while SuperBASIC is disabled, the [ character will print as STOP.

Sprite Commands

[DSPR [MOVE [KSPR [ESPR [BSPP

These commands are used in defining sprite characteristics and controlling sprite movement. [DSPR (Define Sprite) is a general setup command that initializes a sprite for the VIC-II chip. The ten arguments in the parameter (see SuperBASIC commands at the end of the article) specify most of the options available for sprite control. [DSPR enables the selected sprite (numbered 0 – 7), stores block (blk) address in current screen pointer table, expands if xexp or yexp = 1, determines initial display position (xpos, ypos), and sets sprite color registers. Multicolored sprites are selected by setting multi = 1, single color by multi = 0. Mc0 and mc1 are optional arguments in the list which set up multicolor 0 and 1. [MOVE moves the selected sprite to xpos, ypos. Horizontal values greater than 255 are handled automatically. [KSPR and [ESPR kill or enable the selected sprite. [BSPP sets background/sprite priority for the selected sprite (sel = 1 sets background in front of sprite).

Sound Commands

[SSND [PLAY

These commands access some of the features of the SID chip. [SSND (Set up sound) produces a sound from one of the three voices of the SID chip. Voice (1 – 3) selects the voice, ad and sr control the attack/decay and sustain/release registers of the selected voice. Wave controls the waveform, gating, and special effects functions of the sound chip. Wave, ad, and sr use the same values that would normally be POKEd to these registers. Freq controls the frequency of the voice but is a 16-bit value in the range 0 – 65535. Pwidth is the pulsewidth value for the pulse waveform and is needed only when wave = 65. Pwidth is an 11-bit value in the range 0 – 12228. [SSND sets the volume register to 15. [PLAY is a short form of [SSND that assumes AD/SR values have been set previously. Waveform and voice values are coded into the first parameter argument by wave*256 + voice. Freq and pwidth are used the same as in [SSND.

VIC Color Control

[BKGD [BKG4 [EXTC [FCOL

These commands control background, border, and text character color. [BKGD sets the background to the selected color. [EXTC sets the exterior border color to the selected color. [BKG4 sets all four background color registers (used in extended color and multicolor bitmap modes). [FCOL (fill color memory) fills the color memory block with the selected color. This causes all text on the current screen to be displayed in the selected color. [FCOL is also useful in multicolor bitmap mode to set multicolor pixels.

VIC Memory Mapping

[BANK [VS1K [CB2K

The VIC chip views memory differently than does the 6510 chip. VIC sees only 16K at a time and maps the ROM character set into part of this 16K bank at times. These commands allow changes to the normal locations of the screen and character sets. [BANK selects which one of four banks (0 – 3) the VIC chip sees. Normally this is bank 0. [BANK resets the pointer BASIC uses to locate the screen. [VS1K determines which 1K block of the 16 available is used for the text screen. The blocks are numbered 0 – 15. The BASIC screen pointer is reset for this location. [CB2K controls which 2K block of the 8 available is used for the character set. In banks 0 and 2 the ROM set is located at 2K blocks two and three. [CB2K is also used to select which 8K block is used for the bitmap screen, values 0 – 3 select the lower 8K block, and values 4 – 7 select the upper 8K block. These three commands must be used in coordination to smoothly relocate the screen. Caution must be exercised in selecting locations since a system crash will result if the screen overwrites important RAM such as page zero. Banks 2 and 3 must be used with great care. (More on bank 3 usage later.) Program 6 demonstrates relocation to PET standard locations for the screen and BASIC.

Graphics/Text Control

[ECGR [MCGR [BMGR

These commands select extended color, multicolor, or bitmap graphics modes. A value of 0 turns the mode off and a value of 1 turns the mode on. Only multicolor and bitmap work in conjunction with each other to form a combined mode. When extended color and bitmap are both on, the screen will appear blank. This effect might be useful for temporarily hiding the screen.

[MXGR [KMXG [CMXV

These commands set up a simple interrupt routine that allows mixed modes to appear in two sections of the screen. [MXGR will change the contents of one VIC register (reg) or part of its contents (the bits OFF in mask) each time the raster counter register equals one of the two raster select values (rast1 and rast2). The values in val1 or val2 will be stored into the selected VIC register. You must determine the appropriate value for the particular register. For example, [MXGR 33,240,152,6,252,1 will cause screen lines 51 to 151 to be displayed with background white and lines 152 to 251 with background blue.

The visible portion of the screen extends from raster 51 to raster 251. [KMXG will kill the interrupt and leave the selected register in an unknown state. [CMXV (change mixed-mode values) allows changing val1 and val2 while mixed mode is in force. By setting them equal, a known state will be in effect after [KMXG. The interrupt routines are simple in that normal IRQ still occurs (keyboard scan, clock update, etc.) so that the transition will tend to creep. To keep the change precise, you must disable interrupts from the CIA. This will kill the keyboard, however, so I/O would be limited to joystick ports only.

[SIZE [XYSC

These commands help use the smooth scroll registers of the VIC chip. [SIZE selects 40 or 38 columns for the text display chosen by setting colsel to 1 or 0 (colsel = 1 selects 40 columns) and sets number of lines to 25 or 24 (rowsel = 1 selects 25 lines). [XYSC moves the entire text screen up to seven pixels horizontally or vertically. By setting xpos and ypos to a value in the range 0 – 7, the screen can be stepped a pixel at a time to produce a smooth scroll. When used in conjunction with a machine language scroll routine or the automatic scroll up, text can be scrolled smoothly across or up the entire screen.

[DLCS

[DLCS (download character set) assists in using banks without ROM character set images and in designing custom character sets. You can copy the uppercase graphics set, upper- and lowercase set, or both by setting set equal to 0, 1, or 2 respectively. This is followed by the address of the first location in memory where you wish the ROM set to be positioned. This should be on a 2K boundary unless you wish to change the order of the set. When the address is 53248, the set will be copied into the RAM beneath the ROM set for use in bank 3.

[FBMS [FSCR

The current hi-res screen (determined by the last [CB2K command) can be filled with any byte value with [FBMS (fill bitmap screen). [FBMS 0 would clear the entire 8K screen. [FSCR works in a similar way with the current text screen. The entire screen is filled with a byte value. Since the text screen is used for color control in hi-res mode, [FSCR can be used for hi-res color control.

[PLOT [FLIP [CLPX [MCPL

These commands are used in plotting pixel points in hi-res graphics modes. The first three plot in 320 × 200 resolution two-color mode, the last in 160 × 200 resolution four-color mode. [PLOT sets the selected pixel on, [CLPX turns the pixel off, and [FLIP changes the pixel to the opposite state. [MCPL (multicolor plot) accepts horizontal coordinates in the range 0,159 and plots in one of four colors determined by sel, with sel in the range 0,3. A value of 0 selects background color, 1 selects text screen low-byte color, 2 selects text screen high-byte color, and 3 selects color memory color. Before you execute any of the plotting commands, [CB2K must be used to select the appropriate 8K block and [BMGR 1 must be in force for the plot to be seen. Remember that y coordinates increase as you go down the screen.

[DRAW

[DRAW is used to draw line segments on the hi-res screen. [CB2K and [BMGR must be used in preparation as in plot commands. [DRAW connects the endpoints given in the parameter list. The line is drawn from xl,yl toward x2,y2.

[HRCS [CHAR [CHRX [CODE

These commands make it easy to put text on the hi-res screen. [HRCS (hi-res character set) stores the address of the character set to be used. It need not be located on a 2K boundary or even be the same set as used on the text screen. The address given is of the first byte of the set. A value of 53248 will select the ROM set (upper/graphics). [CHAR and [CHRX plot an 8 × 8 character to a selected position on the current hi-res screen. The character code (char) to select which character to plot corresponds to the screen POKE codes as listed in Commodore documentation. Example: [CHAR 1,100,100 would plot the letter A with position 100,100 being the upper-left corner of the 8 × 8 character cell. [CHAR plots the cell to the hi-res screen absolutely while [CHRX uses the exclusive OR function to flip the cell pixels. So [CHRX can be used to unplot a previously plotted character. [CODE helps in translating to the screen POKE code used by [CHAR and [CHRX in character selection.

The argument for [CODE must be the name of a defined string variable. Upon execution the ASCII values stored in the string will be converted to screen POKE codes. The RVS ON and RVS OFF control characters can be used within the string to select the upper 128 or lower 128 characters of the set. All other control characters will produce unpredictable results. Once the string is converted using [CODE, use the ASC function and MID$ function to read the codes. The ASC function will give correct results for the 0 character of the set. Be careful when using strings not built to high memory because [CODE will modify the actual string data stored within the BASIC text area.

[HRAM [LOOK [STUF

These commands make use of [BANK 3 possible from BASIC. When bank 3 is selected, the VIC chip uses RAM in the 64 from $C000 to $FFFF and ignores ROM located at the same addresses, including the ROM character set. SuperBASIC allows the location of one text screen ([VSIK block 3 located at $CC00) in bank 3. RAM from $D000 to $FFFF can be used for character sets, sprites, and a hi-res screen. The main problem confronting the bank 3 user is the switching required to read and write to these RAM locations. All plotting commands need to read as well as write to RAM so they can be preceded by [HRAM to accomplish this in bank 3. For example, [HRAMDRAW 1,0,100,100 would draw to the hi-res screen in RAM under the $E000 and $F000 ROMs. [HRAM should be used in this manner with [PLOT, [FLIP, [CLPX, [MCPL, [DRAW, [CHAR, and [CHRX in bank 3. [MXGR should be avoided in bank 3. Using the first 3K of bank 3 will crash SuperBASIC, so make sure the text screen is relocated by [VSIK 3. When the transition to bank 3 is accomplished, the 1K block at $0400 can be reclaimed for BASIC program storage. [LOOK and [STUF are PEEK and POKE equivalents that can be used with [HRAM to examine and change RAM. [LOOK is different from PEEK in that a defined variable name is used in the parameter list to store the value read from memory. [STUF works the same as POKE and is primarily useful for storing to block $D000 RAM (for example, [HRAMSTUF 53248,255).

SuperBASIC Commands

Enhanced BASIC Commands

RESTORE <exp>
GOTO <exp>
GOSUB <exp>
IF <exp> GOTO <exp>
IF <exp> GOSUB <exp>
ON <exp> GOTO <exp1>,<exp2>...
ON <exp> GOSUB <expl>,<exp2>,...
LIST (Shift Key halts list)

New SuperBASIC Commands

Sprite Commands

[DSPR spr, blk, xexp, yexp, xpos, ypos, multi, sprcolr, mc0, mcl
[MOVE spr, xpos, ypos
[KSPR spr
[ESPR spr
[BSPP spr, sel

Sound Commands

[SSND voice, ad, sr, wave, freq, pwidth
[PLAY 256*wave + voice, freq, pwidth

VIC Color Control

[BKGD col
[BKG4 co10, co11, co12, co13
[EXTC col
[FCOL col

VIC Memory Mapping

[BANK sel
[VSIK sel
[CB2K sel

Graphics Control

[ECGR sel
[MCGR sel
[BMGR sel
[MXGR reg, mask, rast1, val1, rast2, val2
[KMXG
[CMXV val1, val2
[SIZE colsel, rowsel
[XYSC xpos, ypos
[DLCS set, address
[FBMS byte
[FSCR byte
[PLOT x,y
[FLIP x,y
[CLPX x,y
[MCPL x,y,sel
[DRAW xl, yl, x2, y2
[HRCS address
[CHAR char, x, y
[CHRX char, x, y
[CODE str$
[LOOK address, variable
[STUF address, byte
[HRAM <SuperBASIC mnemonic>
<parameter list>

Programs 2 – 6 are demonstration programs which should be helpful in seeing the commands used in actual applications.

If you're not up to typing in SuperBASIC yourself, send $3 along with a blank disk (no tapes) and a stamped, self-addressed mailer to:

Martin C. Kees
711 West Henry
Pasco, WA 99301