## Chapter 3: BASIC Programming

### Commodore 64 Compatibility

The Commander X16 BASIC interpreter is 100% backwards-compatible with the Commodore 64 one. This includes the following features:

- All statements and functions
- Strings, arrays, integers, floats
- Max. 80 character BASIC lines
- Printing control characters like cursor control and color codes, e.g.:
  - `CHR$(147)`: clear screen
  - `CHR$(5)`: white text
  - `CHR$(18)`: reverse
  - `CHR$(14)`: switch to upper/lowercase font
  - `CHR$(142)`: switch to uppercase/graphics font

Because of the differences in hardware, the following functions and statements are incompatible between C64 and X16 BASIC programs.

- `POKE`: write to a memory address
- `PEEK`: read from a memory address
- `WAIT`: wait for memory contents
- `SYS`: execute machine language code

The BASIC interpreter also currently shares all problems of the C64 version, like the slow garbage collector.

### New Statements and Functions

There are several new statement and functions. Note that all BASIC keywords (such as `FOR`) get converted into tokens (such as `$81`), and the tokens for the new keywords have not been finalized yet. Therefore, loading BASIC program saved from a different revision of BASIC may mix up keywords.

#### BIN$

TYPE: String Function
FORMAT: BIN$(n)

Action: Return a string representing the binary value of n. If n <= 255, 8 characters are returned and if 255 < n <= 65535, 16 characters are returned.

EXAMPLE of BIN$ Function:

    PRINT BIN$(200)   : REM PRINTS 11001000 AS BINARY REPRESENTATION OF 200
    PRINT BIN$(45231) : REM PRINTS 1011000010101111 TO REPRESENT 16 BITS

#### BOOT

TYPE: Command
FORMAT: BOOT

Action: Load and run a PRG file named `AUTOBOOT.X16` from device 8. If the file is not found, nothing is done and no error is printed.

EXAMPLE of BOOT Statement:

    BOOT

#### CHAR

TYPE: Command
FORMAT: CHAR <x>,<y>,<color>,<string>

Action: This command draws a text string on the graphics screen in a given color.

The string can contain printable ASCII characters (`CHR$($20)` to `CHR$($7E)`), as well most PETSCII control codes.

EXAMPLE of CHAR Statement:

    10 SCREEN$80
    20 A$="The quick brown fox jumps over the lazy dog."
    24 CHAR0,6,0,A$
    30 CHAR0,6+12,0,CHR$($04)+A$   :REM UNDERLINE
    40 CHAR0,6+12*2,0,CHR$($06)+A$ :REM BOLD
    50 CHAR0,6+12*3,0,CHR$($0B)+A$ :REM ITALICS
    60 CHAR0,6+12*4,0,CHR$($0C)+A$ :REM OUTLINE
    70 CHAR0,6+12*5,0,CHR$($12)+A$ :REM REVERSE

#### CLS

TYPE: Command
FORMAT: CLS

Action: Clears the screen. Same effect as `?CHR$(147);`.

EXAMPLE of CLS Statement:

    CLS

#### COLOR

TYPE: Command
FORMAT: COLOR <fgcol>[,<bgcol>]

Action: This command works sets the text mode foreground color, and optionally the background color.

EXAMPLES of COLOR Statement:

      COLOR 2   : SET FG COLOR TO RED, KEEP BG COLOR
      COLOR 2,0 : SET FG COLOR TO RED, BG COLOR TO BLACK

#### DOS

TYPE: Command
FORMAT: DOS <string>

Action: This command works with the command/status channel or the directory of a Commodore DOS device and has different functionality depending on the type of argument.

- Without an argument, `DOS` prints the status string of the current device.
- With a string argument of `"8"` or `"9"`, it switches the current device to the given number.
- With an argument starting with `"$"`, it shows the directory of the device.
- Any other argument will be sent as a DOS command.

EXAMPLES of DOS Statement:

      DOS"$"          : REM SHOWS DIRECTORY
      DOS"S:BAD_FILE" : REM DELETES "BAD_FILE"
      DOS             : REM PRINTS DOS STATUS, E.G. "01,FILES SCRATCHED,01,00"

#### FRAME

TYPE: Command
FORMAT: FRAME <x1>,<y1>,<x2>,<y2>,<color>

Action: This command draws a rectangle frame on the graphics screen in a given color.

EXAMPLE of FRAME Statement:

    10 SCREEN$80
    20 FORI=1TO20:FRAMERND(1)*320,RND(1)*200,RND(1)*320,RND(1)*200,RND(1)*128:NEXT
    30 GOTO20

#### GEOS

TYPE: Command
FORMAT: GEOS

Action: Enter the GEOS UI.

#### HEX$

TYPE: String Function
FORMAT: HEX$(n)

Action: Return a string representing the hexadecimal value of n. If n <= 255, 2 characters are returned and if 255 < n <= 65535, 4 characters are returned.

EXAMPLE of HEX$ Function:

    PRINT HEX$(200)   : REM PRINTS C8 AS HEXADECIMAL REPRESENTATION OF 200
    PRINT HEX$(45231) : REM PRINTS B0AF TO REPRESENT 16 BIT VALUE

#### JOY

TYPE: Integer Function
FORMAT: JOY(n)

Action: Return the state of a joystick.

`JOY(1)` through `JOY(4)` return the state of SNES controllers connected to the system, and `JOY(0)` returns the state of the "keyboard joystick", a set of keyboard keys that map to the SNES controller layout. See `joystick_get` for details.

If no controller is connected to the SNES port (or no keyboard is connected), the function returns -1. Otherwise, the result is a bit field, with pressed buttons `OR`ed together:

Value | Button
--- | ---
$800 | A
$400 | X
$200 | L
$100 | R
$080 | B
$040 | Y
$020 | SELECT
$010 | START
$008 | UP
$004 | DOWN
$002 | LEFT
$001 | RIGHT

Note that this bitfield is different from the `joystick_get` KERNEL API one. Also note that the keyboard joystick will allow LEFT and RIGHT as well as UP and DOWN to be pressed at the same time, while controllers usually prevent this mechanically.

EXAMPLE of JOY Function:

    10 REM DETECT CONTROLLER, FALL BACK TO KEYBOARD
    20 J = 0: FOR I=1 TO 4: IF JOY(I) >= 0 THEN J = I: GOTO40
    30 NEXT
    40 :
    50 V=JOY(J)
    60 PRINT CHR$(147);V;": ";
    70 IF V = -1 THEN PRINT"DISCONNECTED ": GOTO50
    80 IF V AND 8 THEN PRINT"UP ";
    90 IF V AND 4 THEN PRINT"DOWN ";
    100 IF V AND 2 THEN PRINT"LEFT ";
    110 IF V AND 1 THEN PRINT"RIGHT ";
    120 GOTO50

#### KEYMAP

TYPE: Command
FORMAT: KEYMAP <string>

Action: This command sets the current keyboard layout. It can be put into an AUTOBOOT file to always set the keyboard layout on boot.

EXAMPLE of KEYMAP Statement:

    10 KEYMAP"SV-SE"    :REM SMALL BASIC PROGRAM TO SET LAYOUT TO SWEDISH/SWEDEN
    SAVE"AUTOBOOT.X16"  :REM SAVE AS AUTOBOOT FILE

#### LINE

TYPE: Command
FORMAT: LINE <x1>,<y1>,<x2>,<y2>,<color>

Action: This command draws a line on the graphics screen in a given color.

EXAMPLE of LINE Statement:

    10 SCREEN128
    20 FORA=0TO2*\XFFSTEP2*\XFF/200
    30 :  LINE100,100,100+SIN(A)*100,100+COS(A)*100
    40 NEXT

#### LOCATE

TYPE: Command
FORMAT: LOCATE <line>[,<column>]

Action: This command positions the text mode cursor at the given location. The values are 1-based. If no column is given, only the line is changed.

EXAMPLE of LOCATE Statement:

    100 REM DRAW CIRCLE ON TEXT SCREEN
    110 SCREEN0
    120 R=25
    130 X0=40
    140 Y0=30
    150 FORT=0TO360STEP1
    160 :  X=X0+R*COS(T)
    170 :  Y=Y0+R*SIN(T)
    180 :  LOCATEY,X:PRINTCHR$($12);" ";
    190 NEXT

#### MON

TYPE: Command
FORMAT: MON (Alternative: MONITOR)

Action: This command enters the machine language monitor. See the dedicated chapter for a description.

EXAMPLE of MON Statement:

      MON
      MONITOR

#### MOUSE

TYPE: Command
FORMAT: MOUSE <mode>

Action: This command configures the mouse pointer.

Mode | Description
--- | ---
0 | Hide mouse
1 | Show mouse, set default mouse pointer
-1 | Show mouse, don't configure mouse cursor

`MOUSE 1` turns on the mouse pointer and `MOUSE 0` turns it off. If the BASIC program has its own mouse pointer sprite configured, it can use `MOUSE -1`, which will turn the mouse pointer on, but not set the default pointer sprite.

The size of the mouse pointer's area will be configured according to the current screen mode. If the screen mode is changed, the MOUSE statement has to be repeated.

EXAMPLES of MOUSE Statement:

    MOUSE 1 : REM ENABLE MOUSE
    MOUSE 0 : REM DISABLE MOUSE

#### MX/MY/MB

TYPE: Integer Function
FORMAT: MX
FORMAT: MY
FORMAT: MB

Action: Return the horizontal (`MX`) or vertical (`MY`) position of the mouse pointer, or the mouse button state (`MB`).

`MB` returns the sum of the following values depending on the state of the buttons:

Value | Button
--- | ---
0 | none
1 | left
2 | right
4 | third

EXAMPLE of MX/MY/MB Functions:

    REM SIMPLE DRAWING PROGRAM
    10 SCREEN$80
    20 MOUSE1
    25 OB=0
    30 TX=MX:TY=MY:TB=MB
    35 IFTB=0GOTO25
    40 IFOBTHENLINEOX,OY,TX,TY,16
    50 IFOB=0THENPSETTX,TY,16
    60 OX=TX:OY=TY:OB=TB
    70 GOTO30

#### OLD

TYPE: Command
FORMAT: OLD

Action: This command recovers the BASIC program in RAM that has been previously deleted using the `NEW` command or through a RESET.

EXAMPLE of OLD Statement:

      OLD

#### PSET

TYPE: Command
FORMAT: PSET <x>,<y>,<color>

Action: This command sets a pixel on the graphics screen to a given color.

EXAMPLE of PSET Statement:

    10 SCREEN$80
    20 FORI=1TO20:PSETRND(1)*320,RND(1)*200,RND(1)*256:NEXT
    30 GOTO20

#### RECT

TYPE: Command
FORMAT: RECT <x1>,<y1>,<x2>,<y2>,<color>

Action: This command draws a solid rectangle on the graphics screen in a given color.

EXAMPLE of RECT Statement:

    10 SCREEN$80
    20 FORI=1TO20:RECTRND(1)*320,RND(1)*200,RND(1)*320,RND(1)*200,RND(1)*256:NEXT
    30 GOTO20

#### RESET

TYPE: Command
FORMAT: RESET

Action: Performs a software reset of the system.

EXAMPLE of RESET Statement:

    RESET

#### SCREEN

TYPE: Command
FORMAT: SCREEN <mode>

Action: This command switches screen modes.

For a list of supported modes, see Chapter 2: Editor. The value of -1 toggles between modes $00 and $03.

EXAMPLE of SCREEN Statement:

      SCREEN 3 : REM SWITCH TO 40 CHARACTER MODE
      SCREEN 0 : REM SWITCH TO 80 CHARACTER MODE
      SCREEN -1 : REM SWITCH BETWEEN 40 and 80 CHARACTER MODE

#### VPEEK

TYPE: Integer Function
FORMAT: VPEEK (<bank>, <address>)

Action: Return a byte from the video address space. The video address space has 20 bit addresses, which is exposed as 16 banks of 65536 addresses each.

EXAMPLE of VPEEK Function:

      PRINT VPEEK(1,$B000) : REM SCREEN CODE OF CHARACTER AT 0/0 ON SCREEN

#### VPOKE

TYPE: Command
FORMAT: VPOKE <bank>, <address>, <value>

Action: Set a byte in the video address space. The video address space has 20 bit addresses, which is exposed as 16 banks of 65536 addresses each.

EXAMPLE of VPOKE Statement:

      VPOKE 1,$B000+1,1 * 16 + 2 : REM SETS THE COLORS OF THE CHARACTER
                                   REM AT 0/0 TO RED ON WHITE

#### VLOAD

TYPE: Command
FORMAT: VLOAD <filename>, <device>, <VERA_high_address>, <VERA_low_address>

Action: Loads a file directly into VERA RAM.

EXAMPLES of VLOAD:

    VLOAD "MYFILE.BIN", 8, 0, $4000  :REM LOADS MYFILE.BIN FROM DEVICE 8 TO VRAM $4000.
    VLOAD "MYFONT.BIN", 8, 1, $F000  :REM LOAD A FONT INTO THE DEFAULT FONT LOCATION ($1F000).

### Other New Features

#### Hexadecimal and Binary Literals

The numeric constants parser supports both hex (`$`) and binary (`%`) literals, like this:

      PRINT $EA31 + %1010

The size of hex and binary values is only restricted by the range that can be represented by BASIC's internal floating point representation.

#### LOAD into VRAM

In BASIC, the contents of files can be directly loaded into VRAM with the `LOAD` statement. When a secondary address greater than one is used, the KERNAL will now load the file into the VERA's VRAM address space. The first two bytes of the file are used as lower 16 bits of the address. The upper 4 bits are `(SA-2) & 0x0ff` where `SA` is the secondary address.

Examples:

      10 REM LOAD VERA SETTINGS
      20 LOAD"VERA.BIN",1,17 : REM SET ADDRESS TO $FXXXX
      30 REM LOAD TILES
      40 LOAD"TILES.BIN",1,3 : REM SET ADDRESS TO $1XXXX
      50 REM LOAD MAP
      60 LOAD"MAP.BIN",1,2 : REM SET ADDRESS TO $0XXXX

#### Default Device Numbers

In BASIC, the LOAD, SAVE and OPEN statements default to the last-used IEEE device (device numbers 8 and above), or 8.

### Internal Representation

Like on the C64, BASIC keywords are tokenized.

- The C64 BASIC V2 keywords occupy the range of $80 (`END`) to $CB (`GO`).
- BASIC V3.5 also used $CE (`RGR`) to $FD (`WHILE`).
- BASIC V7 introduced the $CE escape code for function tokens $CE-$02 (`POT`) to $CE-$0A (`POINTER`), and the $FE escape code for statement tokens $FE-$02 (`BANK`) to $FE-$38 (`SLOW`).
- The unreleased BASIC V10 extended the escaped tokens up to $CE-$0D (`RPALETTE`) and $FE-$45 (`EDIT`).

The X16 BASIC aims to be as compatible as possible with this encoding. Keywords added to X16 BASIC that also exist in other versions of BASIC match the token, and new keywords are encoded in the ranges $CE-$80+ and $FE-$80+.

### Auto-Boot

When BASIC starts, it automatically executes the `BOOT` command, which tries to load a PRG file named `AUTOBOOT.X16` from device 8 and, if successful, runs it. Here are some use cases for this:

- An SD card with a game can auto-boot this way.
- An SD card with a collection of applications can show a menu that allows selecting an application to load.
- The user's "work" SD card can contain a small auto-boot BASIC program that sets the keyboard layout and changes the screen colors, for example.