Atari800: Getting Started With the Portable Open-Source Emulator

Atari800 is the long-running free emulator of the Atari 400/800, 1200XL, 600XL/800XL, 65XE/130XE/800XE, XE Game System and 5200. David Firth wrote the original, copyright 1995. It has been maintained since 1998 by the Atari800 Development Team, with Petr Stehlik releasing every version since 0.8.2. It is released under the GPL. Altirra is Windows-only; Atari800's selling point is portability. Supported platforms include Unix/Linux (X11, SDL, curses or a plain "simple" console build), MS-DOS, Amiga, Atari TT/Falcon, Windows, WinCE, Dreamcast, Android and Raspberry Pi. There is also libatari800, the emulator core as a library for embedding in other programs. This guide is based on version 5.2.0 (29 December 2023).

You'll learn: how to get it running with or without ROM images, how to choose a machine, the essential keys and command-line switches, and how to move files in and out with the H: device and tape images.

1. Firmware: you can start without ROMs

Older guides insist that you find the Atari ROMs first. That is no longer true. Since the 4.x series the emulator has included the Altirra OS replacements for the 400/800, XL/XE and 5200, plus Altirra BASIC. Since version 4.1.0 you can use the emulator without providing any ROM images. Version 5.1.0 updated them to Altirra OS 3.41 and Altirra BASIC 1.58.

Real ROMs still give the best compatibility with software that pokes into OS internals. If you dump them from your own machine, these are the sizes and addresses:

Image Size Where it lives
Atari BASIC 8,192 bytes $A000–$BFFF
400/800 OS 10,240 bytes $D800–$FFFF
XL/XE OS 16,384 bytes $C000–$FFFF (the part under the I/O chips appears at $5000–$57FF when PORTB bit 7 is set: dump $C000–$CFFF, then $5000–$57FF, then $D800–$FFFF)
XEGS built-in game 8,192 bytes $A000–$BFFF

Point the emulator at them on the command line (-osb_rom, -xlxe_rom, -basic_rom, etc.) or in the F1 menu's system/ROM settings. Specific revisions can be forced: -800-rev a-ntsc|a-pal|b-ntsc|altirra, -xl-rev 1|2|3|4|…|altirra, -basic-rev a|b|c|altirra.

A caution: many "OS-B" files in circulation are the slightly patched Xformer version. A few titles, such as the original Zaxxon, notice the difference.

2. First run

On most systems you start it from a terminal, optionally passing files to load:

atari800                         # boots the default machine
atari800 -xl -nobasic game.atr   # 800XL, BASIC off, disk in D1:
atari800 -run demo.xex           # load and run an executable
atari800 -xe -pal -run intro.xex # 130XE in PAL mode
atari800 -cart basicxl.car       # insert a cartridge image
atari800 -boottape adventure.cas # attach a tape and boot from it

Disk images on the command line mount in order, so the first goes to D1:, the next to D2:, and so on. Supported files include disks (ATR, XFD, compressed ATR.GZ/ATZ and XFD.GZ/XFZ, DCM, PRO, ATX), programs (COM/EXE/XEX, BAS, LST), cartridges (CAR or raw ROM), tapes (CAS or raw bootable files) and Atari800 state files.

Settings live in ~/.atari800.cfg. -config <file> uses another file, and -autosave-config saves on exit.

3. Choosing the machine

Switch Machine
-atari Atari 800 (RAM configurable 8–48K; -c adds RAM at $C000–$CFFF)
-1200 1200XL
-xl 800XL
-xe 130XE
-320xe / -rambo 320K Compy Shop / RAMBO-style expansions
-576xe, -1088xe larger PORTB expansions
-xegs XE Game System
-5200 5200 SuperSystem

Add -pal or -ntsc, and -basic or -nobasic. As on real hardware, most disk-based games want BASIC off. Axlon and Mosaic expansions for the 800 (-axlon <n>, -mosaic <n>) and MapRAM for the XL/XE (-mapram) are also available.

4. Essential keys

Press F1 at any time for the built-in user interface, where nearly everything is configurable. Esc backs out of a menu.

Key Function
F1 Emulator menu
F2 / F3 / F4 OPTION / SELECT / START
F5 / Shift+F5 Warm reset / cold reboot
F6 HELP (XL/XE)
F7 BREAK
F8 Machine-code monitor
F9 Exit
F10 Screenshot
F12 Turbo (maximum speed)
Alt+R / D / C / T Run program / disk / cartridge / tape management
Alt+Y Select system
Alt+S / Alt+L Save / load state
` (SDL) Atari inverse key
Home Clear screen
Arrow keys Cursor movement (Atari Ctrl+−/=/+/*)
Ctrl+\ Ctrl+Esc (Windows workaround)

Note that F2 is OPTION and F4 is START. That is the reverse of Altirra, where F2 is START and F4 is OPTION. People switching between the two get caught by this.

In the SDL build, keyboard joystick emulation is on for joystick 0 by default, with keys defined under Controller Config → Define layout. Real USB pads are picked up through SDL. -joy-distinct (added in 5.1.0) gives each physical pad its own emulated stick, for four-player games. The mouse can stand in for paddles, light pen/gun, KoalaPad, Touch Tablet, trak-ball, or ST/Amiga mice (-mouse pad, -mouse koala, and so on).

5. Moving files in and out: the H: device

The H: device maps host folders into the Atari as a CIO device:

atari800 -H1 ~/atari/work -hreadwrite

From BASIC you can then SAVE "H1:TEST.BAS", LOAD "H:TEST.BAS" or copy files with DOS. As in Altirra, H6:–H9: are aliases of H1:–H4: that convert line endings between ATASCII and host text. This is the recommended way to handle BASIC source:

LIST "H6:PROGRAM.LST"
ENTER "H6:PROGRAM.LST"

New in 5.2.0: the host device letter can be renamed, for example to D:, using the Emulation configuration → Host device settings, or the -Hdevicename <X> option. Programs with a hard-coded "D:" can then run from a host folder. C:, E:, K: and S: are excluded. H: works through the OS patches, so it is unavailable if you start with -nopatchall.

6. Tapes

When you attach a CAS image, the emulator behaves as if PLAY were held down, so the tape rolls whenever the Atari switches the motor on. Points from USAGE:

  • With the SIO patch on, loads and saves are fast. Some protected tapes only load with it off (-nopatch). Toggling the patch mid-operation breaks the transfer.
  • To save, switch the tape's Record option on first, as you would press RECORD on a real deck. Switch it off before loading again. New blocks are always appended to the end of the image. Make blank tape creates a new CAS ready to record.
  • Only standard 600-baud blocks can be saved, and non-standard protection signals aren't supported.
  • Don't save a state file mid-load: the tape operation isn't stored in it.

See our cassette guide for the CLOAD / RUN "C:" / START-boot rules.

7. Video and sound tweaks

-ntsc-artif ntsc-old|ntsc-new|ntsc-full turns on NTSC artifact colours, which games such as Choplifter need. ntsc-full is a complete NTSC filter with composite, S-video, RGB and monochrome presets. -pal-artif pal-blend simulates PAL colour blending. Colours can be tuned live (tint, saturation, contrast, brightness, gamma, GTIA colour delay) with LAlt+1…6, or loaded from an ACT palette file. -stretch, -image-aspect real and -horiz-area tv give a TV-like picture. Stereo POKEY is supported. Audio can be recorded to WAV (or MP3 with LAME), and Alt+V records AVI video.

Troubleshooting

  • Black screen or crash on boot with a disk game: use -nobasic, and try -atari with an OS-B ROM for early software.
  • H:, P: and R: don't work: you started with -nopatchall, which disables all OS patches. That flag is required for MIO, Black Box and 1400XL/1450XLD emulation, which is why it is sometimes recommended.
  • Protected tape or disk fails: disable the SIO patch (-nopatch).
  • Settings don't stick: they are only written if you save the configuration from the UI, or run with -autosave-config.
  • Need a debugger: F8 opens the monitor, which can disassemble, inspect memory and, in recent versions, read XEX files for patching. Altirra's debugger is more capable if you can run it.

Further reading

  • The project's DOC/USAGE file is the complete, current list of every switch and key. DOC/FAQ and DOC/NEWS explain behaviour changes between versions.
  • Our Altirra setup guide covers the main alternative, and disk image formats explains ATR, XEX, CAS and CAR, including the CAR cartridge header that Atari800 introduced in version 0.8.0.

Credits