Altirra BASIC in Practice: What Changes from Atari BASIC
If you run an Atari emulator without supplying ROM images, the BASIC you get is almost certainly Altirra BASIC. Both Altirra and atari800 fall back to it when no Atari BASIC ROM is configured. It is a free, from-scratch 8K replacement written by Avery Lee, and it runs nearly all Atari BASIC programs. "Nearly" is the important word for anyone typing in magazine listings. This guide covers the practical differences: what loads and runs unchanged, what fails when typed in and why, how much faster it is, and how to use its extra statements in your own programs. For the background and history, see the Altirra BASIC entry in the software section.
What you need: Altirra, or atari800 4.1 or later. atari800 5.2.0 reports Altirra 8K BASIC 1.58 at power-up. On a real machine, use the atbasic.bin ROM image on a flash cartridge or EPROM, or run atbasicx.xex from DOS (48K and a free $A000–$BFFF area needed).
Everything below was tested side by side in atari800 5.2.0, with Altirra BASIC 1.58 (-basic-rev altirra) against a real Atari BASIC revision C ROM (-basic-rev c), both running on the emulator's built-in Altirra OS.
1. Recognising it
The banner gives it away: Altirra 8K BASIC 1.58 and a prompt that reads Ready with lower-case letters, where Atari BASIC says READY. Error messages also differ in style: Error- 3 at line 100 rather than ERROR- 3 AT LINE 100. The error numbers follow the same scheme (3 is a value error, 9 a DIM error and so on), so the usual error code tables apply.
To switch between the two in atari800, use -basic-rev altirra or -basic-rev c (with -basic_rom pointing at your Atari BASIC image). In Altirra, add or remove the Atari BASIC ROM in the firmware list.
2. Saved programs: the safe route
Tokenised programs (files written with SAVE or CSAVE) load straight into Altirra BASIC. The program and variable name tables have the same format, and the statement and function tokens of Atari BASIC have the same values. A test program that uses variables called DIR, CP, MOVE, ERR and MISSILE, all names that Altirra BASIC reserves, shows this. Saved from Atari BASIC and loaded into Altirra BASIC, it LISTed correctly and ran, printing the right answer.
That works because a tokenised file never goes back through the parser. Variable names are stored once in the name table, and the program refers to them by number. So the rule is:
.BASfiles saved by Atari BASIC: load and run. This covers most disk images.- Listings (
.LSTfiles viaENTER, or typing): every line is re-parsed, and here the differences below can bite.
Going the other way is riskier. A program saved from Altirra BASIC loads into Atari BASIC only if it uses nothing but Atari BASIC tokens. Hex constants, MOVE, block IF and the other extensions can crash Atari BASIC on LOAD.
3. Names that break when you type them in
Altirra BASIC adds statements and functions that Atari BASIC doesn't have: among them DIR, MOVE, ERASE, RENAME, PROTECT, UNPROTECT, BGET, BPUT, DPOKE, LOMEM, ELSE, ENDIF, MISSILE, PMCLR, PMCOLOR, PMGRAPHICS, PMMOVE, CP (another name for DOS), and the functions ERR(), DPEEK(), HEX$(), HSTICK(), VSTICK(), PMADR() and BUMP(). A program that uses one of those words as a variable name is perfectly legal Atari BASIC, but it may not parse in Altirra BASIC.
We typed the same short lines into both interpreters. The results show a clear pattern:
| Line typed | Atari BASIC rev C | Altirra BASIC 1.58 |
|---|---|---|
DIR=1, MOVE=2, CP=4, ERASE=8, MISSILE=9, LOMEM=10, BGET=12, PMCLR=13, RENAME=14, PROTECT=20 |
accepted | syntax error |
DIRX=15, MOVES=16, ELSEWHERE=18 |
accepted | syntax error |
ERR=3, DPEEK=11, HEX=5, BUMP=6 |
accepted | accepted |
X=ERR+1, ? ERR;HEX, Q=DPEEK+VSTICK |
accepted | syntax error |
Y=DIR+1, Z=HEX+BUMP |
accepted | accepted |
IFFY=1 |
syntax error | accepted, but as IF FY=1 (a block IF) |
In plain terms:
- A new statement name at the start of a statement is always read as that statement. This includes longer names that merely begin with it, so
DIRXandMOVESfail too. Atari BASIC behaves the same way with its own statements (see below), but it has fewer of them. - A new function name inside an expression is read as the function.
ERR=3is fine because the line starts as an assignment, butX=ERR+1is not. - Names that only clash with a statement are fine inside expressions.
Y=DIR+1works, because DIR is only special at the start of a statement.
Some traps are shared by both interpreters, which is worth knowing when a listing "doesn't work" on either. COLORS=1 is silently stored as COLOR S=1, PRINTER=1 becomes PRINT ER=1 and DATAS=1 becomes DATA S=1, with no error at all. POKER=1, FORM=1, GETX=1, DIMX=1 and ENDX=1 are rejected by both. ENDIF=19 is rejected by both, for different reasons.
How to fix a listing: LIST the program to see which lines were flagged with Error-, then rename the offending variable throughout (for example DIR to DR, MOVE to MV, ERR to ER). If you have the original as a tokenised .BAS file, just LOAD it instead.
4. How much faster?
Altirra BASIC is generally faster than Atari BASIC, and the difference is easy to measure with the jiffy clock at locations 19 and 20:
10 DIM A$(20),T(4)
20 POKE 19,0:POKE 20,0
30 FOR I=1 TO 1000:A=I*2+1:NEXT I
40 T(1)=PEEK(19)*256+PEEK(20)
50 POKE 19,0:POKE 20,0
60 FOR I=1 TO 500:GOSUB 900:NEXT I
70 T(2)=PEEK(19)*256+PEEK(20)
80 POKE 19,0:POKE 20,0
90 FOR I=1 TO 200:X=SIN(I)+SQR(I):NEXT I
100 T(3)=PEEK(19)*256+PEEK(20)
110 POKE 19,0:POKE 20,0
120 FOR I=1 TO 300:A$=STR$(I):B=VAL(A$):NEXT I
130 T(4)=PEEK(19)*256+PEEK(20)
140 FOR I=1 TO 4:PRINT "TEST ";I;": ";T(I);" JIFFIES":NEXT I
150 END
900 RETURN
Results in jiffies (1/60 second, NTSC), on the same machine and OS:
| Test | Atari BASIC rev C | Altirra BASIC 1.58 | Speed-up |
|---|---|---|---|
| 1. 1,000-pass loop with arithmetic | 356 | 190 | 1.9× |
| 2. 500 GOSUB/RETURN | 120 | 48 | 2.5× |
| 3. 200 × SIN + SQR | 1031 | 677 | 1.5× |
| 4. 300 × STR$ + VAL | 127 | 60 | 2.1× |
Program flow (GOSUB, FOR/NEXT) gains the most: Altirra BASIC caches the return points of FOR and GOSUB and, when it can, searches for line numbers starting from the current line. Floating-point maths gains the least. Both interpreters ran on the emulator's built-in replacement OS; on a real machine with Atari's OS ROM the absolute figures will differ.
Two tuning tips from the manual work differently from Atari BASIC. Because line searches start at the current line, a GOTO to a lower line number can be slower than one to a higher number, the opposite of the old advice to put hot loops at the top. And an inline IF ... THEN is faster than a block IF when the condition is false, because the block form has to scan statement by statement for its ELSE or ENDIF.
5. New statements worth using
All of these were tried in Altirra BASIC 1.58:
10 DIR "H1:*.*"
20 ? HEX$(DPEEK(88)),$FF&$0F,$F0!$0F,6%3
30 DIM A$(10):A$="**********"
40 MOVE ADR("ABC"),ADR(A$)+2,3:? A$
Line 10 lists a directory without leaving BASIC (on a disk, DIR alone lists D1:*.*). Line 20 prints 9C40 (the screen address in hex), then 15, 255 and 5: &, ! and % are bitwise AND, OR and exclusive OR on 16-bit values, and $ marks a hex constant. Line 40 copies three bytes into the middle of a string, printing **ABC*****. MOVE with a negative length copies downwards, for overlapping blocks.
Other useful additions:
- Block IF:
IF condon its own, then lines of statements, optionalELSE, andENDIF. - ERR(0) and ERR(1): the last error number and its line, for TRAP handlers (the same as
PEEK(195)andDPEEK(186)). - ERASE, RENAME, PROTECT, UNPROTECT: file management, so you rarely need the DOS menu.
- BGET and BPUT: binary block reads and writes through an IOCB, useful for loading screens or fonts.
- LOMEM: raise the bottom of BASIC memory to reserve space for machine code or graphics. It clears the program, so use it before loading.
One trap: DIR uses I/O channel 7, the same channel ENTER uses. When we put a DIR line in a file run by ENTER, the listing appeared but ENTER then stopped with error 133. Use DIR from a program or by typing it.
6. Player/missile graphics without POKEs
Atari BASIC programs need dozens of POKEs and a string trick to use sprites. Altirra BASIC has statements for them:
10 REM ALTIRRA BASIC P/M DEMO
20 GRAPHICS 3:COLOR 1:SETCOLOR 0,12,8
30 PLOT 0,0:DRAWTO 39,0:DRAWTO 39,19:DRAWTO 0,19:DRAWTO 0,0
40 PMGRAPHICS 2:PMCLR 0:PMCOLOR 0,1,14
50 Y=56:P=PMADR(0)+Y
60 FOR I=0 TO 7:READ B:POKE P+I,B:NEXT I
70 DATA 60,126,219,255,189,195,126,60
80 X=120:PMMOVE 0,X
90 ? "STEER INTO THE WALL WITH THE JOYSTICK"
100 X=X+HSTICK(0)*2:D=VSTICK(0)*2
110 IF X<44 THEN X=44
120 IF X>204 THEN X=204
130 IF Y-D<16 OR Y-D>104 THEN D=0
140 Y=Y-D:PMMOVE 0,X;D
150 T=PEEK(20)
160 IF PEEK(20)=T THEN 160
170 POKE $D01E,0:T=PEEK(20)
180 IF PEEK(20)=T THEN 180
190 IF BUMP(0,8)
200 SOUND 0,100,10,8:SETCOLOR 4,4,6
210 ELSE
220 SOUND 0,0,0,0:SETCOLOR 4,0,0
230 ENDIF
240 GOTO 100
- PMGRAPHICS 2 sets up double-line players and missiles (1 is single-line, 0 turns them off). GRAPHICS turns them off again, so call it after the mode change.
- PMCLR 0 clears player 0's memory, and PMCOLOR 0,1,14 sets its colour as hue and luminance, like SETCOLOR.
- PMADR(0) returns the start of player 0's strip. In double-line mode the visible area is offsets 16 to 111, so the shape is POKEd in at offset 56.
- HSTICK() and VSTICK() return −1, 0 or +1 for each axis, which makes movement a single addition. VSTICK is +1 for up.
- PMMOVE 0,X;D sets the absolute horizontal position and moves the shape vertically by D rows, positive meaning up. The vertical part is relative, so the program tracks Y itself to stop the player leaving the screen.
- BUMP(0,8) reports a collision between player 0 and playfield 0 (the colour drawn with COLOR 1 in GRAPHICS 3). Values 8–11 mean playfields 0–3, and 0–3 mean players.
Lines 150 to 180 follow the manual's advice on reliable collisions. The hardware only notices an overlap while it is drawing that part of the screen. Our first version cleared the collision register and checked BUMP only a few statements later, and with the player pressed against the wall it still showed no collision. Waiting for one frame before clearing and another before checking makes it dependable, at the cost of running at half the frame rate.
In Atari BASIC, this program fails as soon as it is entered: lines using PMGRAPHICS, PMADR, HSTICK, BUMP, hex constants or the block IF are all flagged with errors, and RUN stops with error 17 at the first one.
7. Writing for both interpreters
If you share programs, decide up front:
- Atari BASIC compatible: use only the classic statements, avoid the reserved names in section 3, and SAVE from either interpreter. The manual lists exactly which tokens are safe.
- Altirra BASIC (or BASIC XL) only: use the extensions freely, and say so in the program's first REM line. Altirra BASIC deliberately uses the same token values as OSS BASIC XL, so its programs also load into BASIC XL and BASIC XE.
- Turbo-BASIC XL: the shared extensions such as MOVE have different token values, so exchange programs as LISTings, not SAVEd files.
Troubleshooting
Error-lines appear while ENTERing a listing that works in Atari BASIC: a variable name clashes with an Altirra BASIC keyword. Rename it, or LOAD a tokenised copy instead.- A line silently changes when listed (
COLOR S=1): the variable name starts with a statement name. This happens in Atari BASIC too. - A program that pokes into BASIC's zero page fails: Altirra BASIC uses page zero differently, apart from the documented locations.
- Atari BASIC crashes loading a program: it was saved from Altirra BASIC with extended tokens. LIST it to a file from Altirra BASIC, remove the extensions and ENTER it in Atari BASIC.
- Collisions are missed: wait a frame after moving before you clear the registers, and another before you check them.
- You need real Atari BASIC behaviour for testing: supply the ROM and select it explicitly (
-basic-rev cin atari800).
Further reading
- Avery Lee, Altirra BASIC Reference Manual (free PDF from the Altirra website), especially "Compatibility with other BASICs" and "Special techniques".
- On this site: the Altirra BASIC software entry, Atari BASIC Essentials, Atari BASIC Error Codes Explained, Player/Missile Graphics in Atari BASIC, BASIC XL and BASIC XE: A Programmer's Guide.
Credits
- Picture: The player/missile example in section 6: the smiley touches the wall, BUMP() reports the collision and the background changes colour. — Program authors; screenshot by the site
- Altirra BASIC Reference Manual, 2018 edition (Avery Lee) — compatibility, P/M graphics, file management, special techniques, token tables — Avery Lee (Altirra), 2018
- Altirra home page and change log (virtualdub.org) — Screenshot from Avery Lee's Altirra page, virtualdub.org
- Atari800 emulator — built-in Altirra OS / Altirra BASIC (see site guide atari800-emulator-guide) — atari800.github.io
