VIC20 3k Super-Expander Cartridge User Manual Programs created with Super Expander's special statements wi11 not work on a machine without the Super Expander plugged in. Finally, the extra 3K memory expansion is provided automatically when you plugin the Super Expander... you will see the screen come up with approximately 3000 extra bytes of memory when you turn it on. GETTING STARTED 1. Turn on your television set. 2, Turn your VIC 291 off. 3. Insert the cartridge. 4. Turn the VIC 20 on. 5. Your Super Expander is now activated and you may write programs in BASIC using the special commands, statements and functions listed below. II. USING SUPER EXPANDER GRAPHICS A few special notes are in order before you begin working through the manual. To begin with, it should be noted that for purposes of graphics plotting, the Super Expander cartridge divides the screen area into 1024, by 1024 coordinates. For example, if you type POINT1,512,512 you will draw a point at the very middle of the screen. These are "Pseudo-coordinates" which means the VIC accepts inputs based on 1024x1024 dot coordinates and scales the plotting down to the VIC's actual screen size/resolution. A full range of graphic instructions is automatically added to your VIC's standard BASIC instruction set when you plug in the Super Expander cartridge. These instructions are listed and explained below. NOTE: WHEN WORKING WITH GRAPHICS THERE ARE TWO IMPORTANT PARAMETERS WHICH YOU MUST INCLUDE AT THE BEGINNING OF YOUR PROGRAM. These setup the graphics screen so you can plot, include characters mixed with graphics, etc. The two graphic commands you should begin your program with are: GRAPHIC and COLOR. GRAPHIC sets the VIC in the "GRAPHIC MODE" you want to use, and "COLOR" specifies the colors you will be working with. INSTRUCTION EFFECT GRAPHIC Prepares the screen for graphics SCNCLR Clears a graphic screen COLOR Select screen, border, character, and auxiliary coler,s REGION Select character color DRAW Plots a line between two points POINT Plots asingle point CIRCLE Draw a circle, ellipse, or arc PAINT Fill in an enclosed area in a color CHAR Puts text on the graphic screen SOUND Set 4 tones and volurne all at once FUNCTION RETURN VALUE RG R (x) Current graphic mode RCOLR(X) The value in a color register RDOT(x,y) The color of a point on the screen RPOT(X) The position of the game paddle RPEN(X) The positlon of the light pen RJOY(x) The position of the joystick RSND(x) The value in a sound register GRAPHIC n This sets up the graphic screen and activates the graphics instruction set. There are 5 different GRAPHIC modes, which are activated by typing GRAPHIC and the number, as an instruction in your program. Exannple: 10 GRAPHIC 2 20 COLOR 1, 2, 3, 4 Type RUN and hit RETURN. Value of n Mode 0 Text mode (norrnal) 1 Muuti-color mode 2 High resolution mode 3 Mixed multi and high-res 4 Return to text mode Mode 0 is the VIC's normal text mode. Once the mode has been changed, the GRAPHIC 4 statement is used to return to this mode. In mode 1, there are 80 points across a line, and 160 lines. Each point is drawn in one of the 4 color registers: screen color, border color, character color, or auxiliary color, A point placed in the screen color is invisible, since it is the same as the background; this can be used to erase other points. Points drawn in either the screen, border, or auxiliary colors will change instantly when these colors are changed. The character color is associated with each specific 4 dot by 16 dot space of the screen. This means that if a dot is plotted in that space in a character color, all other points in that space that were drawn in the character color will change to the new character color. In mode 2, there are 160 points across a line, and 160 lines. The points are half as wide as in mode 1, and therefore give twice as fine resolution to the screen. However, the color resolution is more limited. Dots can be plotted only in a character color.Within each specific space on the screen, which is an 8 by 8 dot area. there can be only one character color, so you can only have dots in that color displayed on the screen. Mode3 is a mixture of modes 1 and 2. When the character color is less than 8, the plotting is done in high resolution. When the character color is greater than 7, multi-color mode is in effect. Mode 4 returns the screen to text mode from a graphic mode. WARNING: if the VIC was already in text mode, this will mess up the VIC until you turn it off and then on again. SCNCLR This statement clears the entire graphic screen. It may be typed directly or included in a program line. COLOR sc, bo, ch, au This sets up the 4 different color registers. The variables here have these limits: sc = 0 to 15 bow= 0 to 7 ch = 0 to 7 normal, 8 to 15 multi-color au = 0 to 15 The colors are: 0 black 1 white 2 red a cyan 4 purple 5 green 6 blue 7 yellow 8 orange 9 light orange 10 pink 11 light cyan 12 light purple 13 light green 14 light blue 15 light yellow NOTE: in GRAPHIC 3 mode, character color numbers greater than 7 set multi-color mode. In this case, the actual character in that spare is the color number minus 6. EXAMPLE: COLOR 1, 2,3,4 REGION c This works like the COLOR statement, except that only the character color is affected. EXAMPLE: REGION 7 DRAW c, x1, y1 TO x2, Y2 [TO x3, y3... TO xn, yn] or DRAW c TO x1, y1 This allows you to draw lines in the screen. The variable c is the color of the line, on the following chart: c High-res Multi-color 0 screen screen 1 character border 2 character character 3 character auxiliary The x and y variables are the coordinates of the end-points of the line. The values of X and Y can be f rom 0 to 1023. An X value of 0 is the left edge of the screen, and X=1023 is the right edge, and the Y values determine the up-and-down position. The values from 0 to 1023 are scaled down to the actual (160 by 160 or 80 by 160) size of the screen. EXAMPLE 1: DRAW 1, 0, 0 TO 100, 100 EXAMPLE 2: DRAW 1, 0, 0 TO 0, 100 TO 100, 100TO100,0TO0,0 EXAMPLE 1 EXAMPLE'2 {pictures omitted} POINT c, x, y or POINT c, x1, y1, x2, Y2, ..., xn, yn This sets a point or points on the screen in the specified color. The points are given in the 0 to 1023 form. EXAMPLE 1: POINT 1, 500,500 EXAMPLE 2: POINT 2, 500, 500, 600, 600, 700, 700 CIRCLE c, x, y, rx, ry [,as,ae] Where: c is the color register (see chart in DRAW statement) in which the circle is drawn x and y are the coordinates of the center of the circle rx and ry are width and height of the circle as and ae are the optional starting and ending angles of the arc, in gradians (0 to 100 degrees in a full circle) EXAMPLE 1: CIRCLE 1, 511,511, 300,400 EXAMPLE 2: CIRCLE 1, 200, 900, 100, 100 EXAMPLE 3: CIRCLE 2,500,600,200,300,10,70 EXAMPLE 1 {pictures omitted} EXAMPLE 2 EXAMPLE 3 {pictures omitted} PAINT c, x, y This paints an enclosed area in a color. c is the color register, and x and y are any point within the area to be painted. Each area can only be painted once. Because of the color limitations of some GRAPHIC modes, some nearby shapes may be distorted by this operation. If an area is bounded by multi-color mode areas, it must be PAINTed in the multi-color mode. EXAMPLE: 10 GRAPHIC 1 20 COLOR 1, 7, 0, 1 0 30 CIRCLE 2, 511, 511, 200, 300 40 PAINT 3,.511, 511 50 PAINT 1, 511, 0 CHAR ro, co, "text" This will put norrnal text on a graphic screen. The ro and co variables are the row and column on which the text is to appear. The text can be any string variable or text inside quote marks. Text should only be displayed when in the high-resolution mode, or the mixed mode, but never in multi-color mode. EXAMPLE: CHAR 1, 1, "HELLO THERE" SOUND s1, s2, s3, s4, v This sets all 4 sound "speakers" and the volume control all at once. The Sl value is put into register 1. If its value is less than 128, no sound will play from that speaker. The volume can range from 0 (off) to 15. This lets you create multi-speaker sound effects. EXAMPLE: SOUND 225,225,225,0,15 RGR(X) This function reads the graphic mode that was set with the GRAPHIC command. The value of x can be from 0 to 255, and doesn't effect the result. EXAMPLE: X = RGR(O) RCOLR(X) This reads the color from any of the 4 registers depending on the value of x on the following table: X COLOR REGISTER 0 screen color 1 border color 2 character color 3 auxiliary color EXAMPLE: X = RCOLR(2) RDOT(X, Y) This reads the color value of a dot on the screen. The values of x and y are the coordinates of the point, and the color value returned is the register of the color on that space. EXAMPLE: X = RDOT(511, 511) RPOT(X) This reads the value of the paddle. If x = 0, paddle X is read, and if x = 1, paddle Y is read. EXAMPLE: 10 GRAPHIC2:COLOR11,6,6,6 20 X=RPOT(0):Y=RPOT(1):J=RJOY(0) 30 IFJ=12THEN:SCNCLR 40 IFJ=4THEN:REGION2 50 IFJ=STHEN.REGION6 60 POINT2,X*4,Y*4:GOTO20 RPEN(X) This reads the screen coordinate of the light pen. It x=O, the X coordinate is returned, and if x=1, the Y coordinate. EXAMPLE: X = RPEN(0) RJOY(X) This reads the value of the joystick. The x variable must be between 0 and 255, and has no effect on the outcome. EXAMPLE: 10 GRAPHIC2:COLOR11,6,6,6:X=170:Y=170 20 J=RJOY(0) 30 X=X+((JAND4)=4)-((JAND8)=8) 40 Y=Y+((JAND1)=1)-((JAND2)=2) 50 POINT3,X*3,Y*3:IFJ=128THEN:SCNCLR 60 GOT020 RSND(X) This reads the value of any of the sound registers, depending on the value of x from this chart: X sound register 1 sound 1 2 sound 2 3 sound 3 4 sound 4 5 volume III. WRITING SUPER EXPANDER MUSIC The Super Expander's music writing mode lets you play notes directly by typing on the keyboard, or, more important, by using the PRINT statement in your BASIC PROGRAMS. It is "interrupt driven", which lets music play while the program proceeds with other tasks. It is designed primarily for playing of music, as opposed to sound effects, and makes writing programs with chords much easier. Music mode is entered by holding down the CTRL key and hitting the left arrow (<=). When you type this in quotes in a program a "reverse f" should appear. This is a special symbol that shows you where music mode is included in your program. Now any key you type will be interpreted by the music package, until the RFTURN key is hit. Here are the characters recognized by music mode: Character Effect p Screen echo on 0 Screen echo off v Volume selection S Sound register selection 0 (the letter 0, not the number) Octave selection T Temposelection R Rest for 1 beat C, D, E, F, G, A, B Play note # Play the next note sharp $ Play the next note flat RETURN Ends music mode When PRINTING strings of these characters, the semicolon (;) can be used to prevent the RETURN character from ending music mode. The screen echo is normally off. Any characters recognized by the music, package are not displayed on the screen. However, when the echo is turned on, they appear normally. Some of the letters recognized by music mode must be followed by a single digit. Here is a table of these letters and their associated numbers: Letter Numbers Value of numbers v 0 to 9 0 is quietest, 9 loudest 5 1 to 4 Speaker no. 0 1 to 3 1 is lowest, 3 is highest T 0 to 9 Tempo The tempo is selected according to this chart: Tempo Beats per Duration of note number minute times 1/60 second 0 900 4 1 600 6 2 450 8 3 300 12 4 225 16 5 15d 24 5 112.5 32 7 56.25 64 a 28. 128 9 14. 255 Each sound register has 3 complete octaves in its range. However, since register 2 is one octave higher than register 1, the three, octaves are different. When playing notes in different sound registers, be sure that the octaves used are chosen correctly. Here are some examples of strings that play music (the reversed f symbol means hold down the CTRL Key and type the left arrow key at the top left corner of the keyboard). 10 PRINT"ALL THE SAME NOTE {ctrl <=} T7 V9 Sl 03 C S2 C S3 01 C" 20 PRINT "SCALE {ctrl <=} T3 V9 S2 01 CDEFGAB 02 BDEFGAB 03 CDEFGAB" 30 PRINT "CHORDS {ctrl <=} T5 V9 S1 03 C S2 E S3 01 G"; 40 PRINT "S1 03 D S2 02 #F S3 01 B"; 50 PRINT "S1 03 E S2 02 A S3 02 C" IV. PROGRAMMABLE FUNCTION KEYS There are 8 functions that can be accessed with the function keys along with the SHIFT key. These are pre-assigned to the following: Key Text fl GRAPHIC f2 COLOR f3 DRAW f4 SOUND f5 CIRCLE f6 RUN + RETURN f7 POINT f8 LIST + RETURN Any time you hit these keys, the characters with which they are programmed enter the input buffer exactly as if you had typed them in yourself. Each key can be programmed with up to 128 characters, using the KEY command. KEY or KEY n, "string" The word KEY all by itself makes the VIC display a list of all 8 func- tion keys and their current value. This is formatted on the screen so the contents of the strings can be edited by moving the cursor up to the string, making the desired change, and hitting RETURN, just like editing a program. You can change any key in the KEY MENU by changing the information inside the quotation marks and hitting return or by typing the KEY command using the forrnat showm in the example below. When followed by a number, this command changes the string value of the key to the new value. This can be up to 128 characters, including cursor and color controls, the RETURN (CHR$(13)), or any other character. The keys can be changed. under program control as well. EXAMPLE: KEY 1, "ISN'T IT AMAZING?" V. 3K MEMORY EXPANSION When the 3K cartridge is used to expand the VIC-20, the BASIC program area is changed so it starts at location 1024 ($0400). Note that with the 3K cartridge plugged in, only on-board memory (4096-8191 or $1000-1FFF) can be used as VIC screen and hi- resolution graphics areas.