Getting Started with FastBasic

FastBasic is a modern BASIC for the Atari 8-bit family, written by dmsc and developed in the open on GitHub since at least 2018. It looks familiar to anyone who knows Atari BASIC or Turbo-BASIC XL, but it throws away line numbers and GOTO in favour of structured code, uses fast integer arithmetic by default, and compiles your program to compact bytecode before running it. You can use it entirely on a real Atari through its tiny full-screen editor, or write on a PC and cross-compile to an executable for an emulator or real hardware.

You will learn: how to get and run FastBasic, the main differences from Atari BASIC, its loops, conditions and procedures, integer/byte/floating-point data, strings and DATA arrays, a player/missile example, and how to call machine code.

You need: any Atari 8-bit (the IDE itself fits in about 8K) or an emulator such as Altirra; for cross-compiling, a Windows, Linux or macOS computer. Releases, the manual and the cross-compiler are published at https://github.com/dmsc/fastbasic/releases, with the manual in the repository as manual.md.

1. Two ways to work

On the Atari. Boot the FastBasic ATR and you get a full-screen editor. You type your program (no line numbers), and the IDE parses and compiles it in one pass straight to bytecode, then runs it. Two IDEs are supplied: an integer-only one, which the author has kept under 8 KB through many releases (8,166 bytes in 4.5.2), and a slightly larger one with floating-point support. From version 4.7 there are also command-line compilers for the DOS prompt (FBC PROG.BAS PROG.COM, plus an integer-only FBCI).

On a PC. The cross-compiler reads a plain text file and produces an Atari executable (.xex), including only the parts of the runtime your program uses — as of Release 3, a one-line ? "Hello" compiled to 453 bytes. Run it with something like:

fastbasic hello.bas

and open the resulting hello.xex in Altirra. If the compiler cannot find its support files, set the FASTBASIC_HOME environment variable to the installation folder (supported since 4.7). The cross-compiler can also build cartridge images, which load instantly in an emulator.

2. What is different from Atari BASIC

  • No line numbers, no GOTO. Programs are structured with loops, IF blocks and procedures.
  • Integers by default. Plain variables are 16-bit integers, which is a big part of the speed. Floating-point variables end in % (for example A% = 1.23) and need the floating-point version.
  • Comments start with '.
  • Abbreviations exist for most statements (PR. for PROC, @ for EXEC), and ? is PRINT.
  • Strings work differently: there are real string arrays, and substrings use square brackets.
  • USR does not push an argument count, unlike Atari BASIC (see section 7).

3. Loops, conditions and procedures

All the structured forms will be familiar from Turbo-BASIC XL:

' Count, test and loop
FOR I = 1 TO 10
  IF I MOD 2 = 0
    ? I; " IS EVEN"
  ELIF I = 5
    ? "FIVE!"
  ELSE
    ? I
  ENDIF
NEXT I

N = 0
REPEAT
  INC N
UNTIL N = 100

DO
  IF KEY() THEN EXIT
LOOP

ELIF chains conditions without nesting, EXIT leaves any loop, INC/DEC add or subtract one from an integer variable, and KEY() is true when a key has been pressed. WHILE ... WEND is also available.

Procedures are defined with PROC and called with EXEC or @. Since version 4.5 they can take parameters:

PROC Greet N
  ? "HELLO, PLAYER "; N
ENDPROC

@Greet 1
@Greet 2

4. Data types and memory

  • Integer arrays: DIM SCORE(9).
  • Byte arrays save memory and are often faster: DIM MAP(255) BYTE. (INC and DEC work on word arrays, not byte or floating-point arrays.)
  • String arrays: DIM NAME$(9) then NAME$(3) = "CARL" — something Atari BASIC never had.
  • Substrings use [start,length]: ? A$[4,5]; [start] alone takes the rest of the string.
  • DATA arrays are declared rather than READ: DATA PRIMES() BYTE = 2, 3, 5, 7, 11, 13. Strings can be stored the same way with DATA MSG() BYTE = "TEXT", and the cross-compiler offers a ROM variant for data that should stay in the executable.
  • ADR() and the & operator return the address of a variable (4.5 and later), and DPEEK/DPOKE read and write 16-bit values.

FastBasic deliberately has no garbage collector. Each DIM (and each new string allocation) simply takes memory from a pointer that only moves upwards, so re-DIMming an array inside a loop eventually runs out of memory. The author's advice is to DIM everything once, at the start, at the largest size you will need — and to choose your graphics mode before DIMming very large arrays.

5. Fast memory operations

MOVE source, dest, length copies a block (-MOVE copies from the end, for overlapping moves upwards) and MSET address, length, value fills one. Together with PMGRAPHICS and the DLI statement, they replace most of the small machine-code routines BASIC programmers used to need.

6. A player/missile example

FastBasic has built-in player/missile support: PMGRAPHICS 2 turns on double-line players (PMGRAPHICS 0 turns them off), PMADR(n) gives the memory address of player n, and PMHPOS n, x sets its horizontal position.

' Bouncing ball sprite - press a key to stop
DATA BALL() BYTE = $3C,$7E,$FF,$FF,$FF,$FF,$7E,$3C
GRAPHICS 0
PMGRAPHICS 2
P0 = PMADR(0)
MSET P0, 128, 0
POKE 704, $46
X = 120 : Y = 60 : DX = 1 : DY = 1
REPEAT
  PAUSE
  MSET P0 + Y, 8, 0
  X = X + DX : Y = Y + DY
  IF X < 48 OR X > 200 THEN DX = -DX
  IF Y < 16 OR Y > 100 THEN DY = -DY
  MOVE ADR(BALL), P0 + Y, 8
  PMHPOS 0, X
UNTIL KEY()
PMGRAPHICS 0

PAUSE with no argument waits for the next vertical blank, which keeps the movement smooth and flicker-free. Location 704 is player 0's colour register. Each frame erases the eight bytes at the old position, moves, and copies the shape in at the new one.

7. Calling machine code

USR(address, args...) pushes the return address and then each argument and jumps to your routine — but, unlike Atari BASIC, no argument count is pushed, so your routine must not begin with the usual count-discarding PLA. In short, USR() does three things: it pushes the return address, pushes each argument, and calls the supplied address. A routine can be stored in a DATA byte array and copied to page 6 with MOVE:

DATA ML() BYTE = $60
MOVE ADR(ML), 1536, 1
X = USR(1536)

($60 is a bare RTS — replace it with your own code.) Routines written for Atari BASIC must have their initial PLA removed.

8. Recent additions

The 2021 release (4.5) added procedure parameters, ADR of variables, hex characters inside string constants ("Hello"$9B"World"), and PAUSE without a parameter. Version 4.7, released at the start of 2025, added an SIO statement, FujiNet network statements (NOPEN, NCLOSE, NSTATUS, NGET), floating-point ADR and the %() function, a 24-bit %TIME counter, more relaxed PRINT syntax (PRINT "A=" A), and much clearer cross-compiler error messages that show the variable name and point at the error.

Troubleshooting

  • "Can't open target definition file" from the cross-compiler: it cannot find its own files — call it by its full path or set FASTBASIC_HOME.
  • Program dies with a memory error after a while: you are DIMming inside a loop. DIM once at the start.
  • A statement from Atari BASIC is rejected: check the manual — GOTO and line numbers do not exist, and string slicing uses [ ].
  • Floating-point maths gives odd results: use the floating-point IDE or compiler, remember the % suffix, and note that results can depend on the OS's maths routines.
  • A machine-code routine crashes: remove the argument-count PLA.

Further reading

  • The FastBasic manual (manual.md in the GitHub repository) — terse but complete; it reads best alongside an Atari BASIC or Turbo-BASIC manual.
  • The sample programs in the repository's samples folder, including pmtest.bas for player/missile graphics.
  • Entries in the annual BASIC Ten-Liner competition, many of which are written in FastBasic and published with commented source.

Credits