hatari - Atari ST/STE/TT/Falcon emulator
hatari [options] [directory|diskimage|program]
Hatari is an Atari ST/STE/TT/Falcon emulator for Linux, FreeBSD, BeOS and other
Systems which are supported by the SDL library.
With Hatari one can run games, demos or applications written for Atari ST, STE
or Falcon. Atari TT support is experimental. Hatari supports the commonly used
*.st, *.msa and *.stx disk images, and hard disk emulation.
To run the emulator a TOS ROM image is needed. EmuTOS, a free implementation of
TOS is shipped with Hatari. It boots faster than original TOS versions, but
some buggy (floppy only) programs won't work correctly with it. For best
compatibility, it's recommended to use a TOS ROM from a real Atari.
As an argument, one can give either a name of a directory that should be
emulated as a virtual GEMDOS hard disk, a floppy disk image or an Atari
program that should be autostarted. In the last case the program's directory
will be used as the C: drive from where this program will be started. These
shortcuts correspond to "-d <dir>", "--disk-a <floppy
image>" and "-d <dir> --auto C:<program>"
options.
Booting will be done from the disk image or directory that's given last on the
command line as an option or the argument (and which corresponds to A: or C:).
If you want to give floppy image name with an autostarting program name, give
it with --disk-a option before the program name.
Hatari options are split into several categories:
- -h, --help
- Print command line options and terminate
- -v, --version
- Print version information and terminate
- --confirm-quit <bool>
- Whether Hatari confirms quitting
- -c, --configfile <filename>
- Read additional configuration values from <file>, these override
values read from the global and user configuration files
- -k, --keymap <file>
- Load keyboard mapping from <file>
- --fast-forward <bool>
- On fast machine helps skipping (fast forwarding) Hatari output
- --auto <program>
- Autostarts given program, if TOS finds it. Program needs to be given with
full path it will have under emulation, for example
"C:\DIR\PROGRAM.PRG". This is implemented by providing TOS a
virtual INF file, including that path as what TOS should start
automatically
- -m, --mono
- Start in monochrome mode instead of color
- --monitor <x>
- Select monitor type (x = mono/rgb/vga/tv)
- --tos-res <x>
- Select TOS resolution for color monitors (x =
low/med/high/ttlow/ttmed)
- -f, --fullscreen
- Start the emulator in fullscreen mode
- -w, --window
- Start the emulator in windowed mode
- --grab
- Grab mouse (also) in windowed mode
- --resizable <bool>
- Allow window resizing
NOTE: this is supported only by Hatari SDL2 build
- --borders <bool>
- Show ST/STE/Falcon screen borders (for low/med resolution overscan
demos)
- --frameskips <x>
- Skip <x> frames after each displayed frame to accelerate emulation
(0=disabled, >4 uses automatic frameskip with given value as
maximum)
- --slowdown <x>
- Slow down emulation by factor of x (used as multiplier for VBL wait
time)
- --mousewarp <bool>
- To keep host mouse better in sync with Atari mouse pointer, center it to
Hatari window on cold reset and resolution changes
- --statusbar <bool>
- Show statusbar (with floppy leds etc etc)
- --drive-led <bool>
- Show overlay drive led when statusbar isn't shown
- --max-width <x>
- Preferred / maximum window width for borders / zooming
- --max-height <x>
- Preferred / maximum window height for borders / zooming
- --bpp <bool>
- Force internal bitdepth (x = 8/15/16/32, 0=disable)
- --disable-video <bool>
- Run emulation without displaying video (audio only)
- --desktop-st <bool>
- NOTE: this has effect only for SDL1 Hatari build. In SDL2 build,
--desktop option controls also ST/STe mode.
Whether to use desktop resolution on fullscreen to avoid issues related to
resolution switching (messing multi-screen setups, several seconds delay
needed for resolution switching by some LCD monitors and the resulting
sound break). Otherwise fullscreen will use a resolution that is closest
to the Hatari window size.
As Hatari ST/STe display code doesn't support zooming (except low-rez
doubling), it doesn't get scaled (by Hatari or monitor) when this is
enabled, and you may get large black borders around ST/STe screen.
Therefore this is mainly useful only if you suffer from the described
effects, but still want to grab mouse and remove other distractions from
the screen just by toggling fullscreen mode. (disabled by default)
- --spec512 <x>
- Hatari uses this threshold to decide when to render a screen with the
slower but more accurate Spectrum512 screen conversion functions (0 <=
x <= 512, 0=disable)
- -z, --zoom <x>
- Zoom (double) low resolution (1=no, 2=yes)
- --video-timing <x>
- Wakeup State for MMU/GLUE (x=ws1/ws2/ws3/ws4/random, default ws3). When
powering on, the STF will randomly choose one of these wake up states. The
state will then affect the timings where border removals and other video
tricks should be made, which can give different results on screen. For
example, WS3 is known to be compatible with many demos, while WS1 can show
more problems.
Zooming to sizes specified below is internally done using integer scaling
factors. This means that different Atari resolutions may show up with
different sizes, but they are never blurry.
- --desktop <bool>
- Whether to use desktop resolution on fullscreen to avoid issues related to
resolution switching. Otherwise fullscreen will use a resolution that is
closest to the Hatari window size. (enabled by default)
- --force-max <bool>
- Hatari window size is forced to specified maximum size and black borders
used when Atari resolution doesn't scale evenly to it. This is most useful
when recording videos of Falcon demos that change their resolution.
(disabled by default)
- --aspect <bool>
- Whether to do monitor aspect ratio correction (enabled by default)
- --vdi <bool>
- Whether to use VDI screen mode. Doesn't work with TOS v4. TOS v3 memory
detection isn't compatible with larger VDI modes (i.e. you need to skip
the detection at boot)
- --vdi-planes <x>
- Use extended VDI resolution with bit depth <x> (x = 1, 2 or 4)
- --vdi-width <w>
- Use extended VDI resolution with width <w> (320 < w <=
1280)
- --vdi-height <h>
- Use extended VDI resolution with height <h> (200 < h <= 960)
- --crop <bool>
- Remove statusbar from the screen captures
- --avirecord
- Start AVI recording. Note: recording will automatically stop when
emulation resolution changes.
- --avi-vcodec <x>
- Select AVI video codec (x = bmp/png). PNG compression can be much
slower than using the uncompressed BMP format, but uncompressed video
content takes huge amount of space.
- --png-level <x>
- Select PNG compression level for AVI video (x = 0-9). Both compression
efficiency and speed depend on the compressed screen content. Highest
compression level (9) can be really slow with some content. Levels
3-6 should compress nearly as well with clearly smaller CPU overhead.
- --avi-fps <x>
- Force AVI frame rate (x = 50/60/71/...)
- --avi-file <file>
- Use <file> to record AVI
- -j, --joystick <port>
- Emulate joystick with cursor keys in given port (0-5)
- --joy<port> <type>
- Set joystick type (none/keys/real) for given port
- --printer <file>
- Enable printer support and write data to <file>
- --midi <bool>
- Whether to enable MIDI support (PortMidi only)
- --midi-in <filename>
- Enable MIDI support and write raw MIDI data to <file> (Linux
only)
- --midi-out <filename>
- Enable MIDI support and read raw MIDI data from <file> (Linux
only)
- --rs232-in <filename>
- Enable serial port support and use <file> as the input device
- --rs232-out <filename>
- Enable serial port support and use <file> as the output device
- --drive-a <bool>
- Enable/disable drive A (default is on)
- --drive-b <bool>
- Enable/disable drive B (default is on)
- --drive-a-heads <x>
- Set number of heads for drive A (1=single sided, 2=double sided)
- --drive-b-heads <x>
- Set number of heads for drive B (1=single sided, 2=double sided)
- --disk-a <file>
- Set disk image for floppy drive A
- --disk-b <file>
- Set disk image for floppy drive B
- --fastfdc <bool>
- speed up FDC emulation (can cause incompatibilities)
- --protect-floppy <x>
- Write protect floppy image contents (on/off/auto). With "auto"
option write protection is according to the disk image file attributes
- -d, --harddrive <dir>
- GEMDOS HD emulation. Emulate harddrive partition(s) with <dir>
contents. If directory contains only single letter (C-Z) subdirectories,
each of these subdirectories will be treated as a separate partition,
otherwise the given directory itself will be assigned to drive
"C:". In the multiple partition case, the letters used as the
subdirectory names will determine to which drives/partitions they're
assigned. If <dir> is an empty string, then harddrive's emulation is
disabled
- --protect-hd <x>
- Write protect harddrive <dir> contents (on/off/auto). With
"auto" option the protection can be controlled by setting
individual files attributes as it disables the file attribute
modifications for the GEMDOS hard disk emulation
- --gemdos-case <x>
- Specify whether new dir/filenames are forced to be in upper or lower case
with the GEMDOS HD emulation. Off/upper/lower, off by default
- --gemdos-time <x>
- Specify what file modification timestamps should be used, emulation
internal (atari) ones, or ones from the machine (host) on which the
machine is running. While Atari emulation and host clocks are in sync at
Hatari startup, they will diverge while emulation is running, especially
if you use fast forward. Default is "atari". If you modify files
accessed by the Atari side, directly from the host side while Hatari is
already running, you may want to use "host" option
- --gemdos-conv <bool>
- Whether GEMDOS file names with 8-bit (non-ASCII) characters are converted
between Atari and host character sets. On Linux, host file name character
set is assumed to be UTF-8. This option is disabled by default, in case
you've transferred files from Atari machine without proper file name
conversion (e.g. by zipping them on Atari and unzipping on PC)
- --gemdos-drive <drive>
- Assign (seprately specified) GEMDOS HD to given drive letter (C-Z) instead
of default C:, or use "skip" to specify that Hatari should add
GEMDOS HD after IDE and ACSI drives (assumes Hatari and native HD driver
parse same number of partitions from HD images partition tables)
- --acsi <id>=<file>
- Emulate an ACSI hard disk with given BUS ID (0-7) using image
<file>. If just filename is given, it's assigned to BUS ID 0
- --ide-master <file>
- Emulate an IDE master hard disk with an image <file>
- --ide-slave <file>
- Emulate an IDE slave hard disk with an image <file>
- --memstate <file>
- Load memory snap-shot <file>
- -s, --memsize <x>
- Set amount of emulated ST RAM, x = 1 to 14 MiB, or 0 for 512 KiB. Other
values are considered as a size in KiB
- -s, --ttram <x>
- Set amount of emulated TT RAM, x = 0 to 256 MiB (in 4MB steps)
- -t, --tos <imagefile>
- Specify TOS ROM image to use
- --patch-tos <bool>
- Use this option to enable/disable TOS ROM patching. Experts only! Leave
this enabled unless you know what you are doing!
- --cartridge <imagefile>
- Use ROM cartridge image <file> (only works if GEMDOS HD emulation
and extended VDI resolution are disabled)
- --cpulevel <x>
- Specify CPU (680x0) to use (use x >= 1 with EmuTOS or TOS >= 2.06
only!)
- --cpuclock <x>
- Set the CPU clock (8, 16 or 32 Mhz)
- --compatible <bool>
- Use a more compatible, but slower 68000 CPU mode with better prefetch
accuracy and cycle counting
- --cpu-exact <bool>
- Use cycle exact CPU emulation (cache emulation)
- --addr24 <bool>
- Use 24-bit instead of 32-bit addressing mode (24-bit is enabled by
default)
- --fpu <x>
- FPU type (x=none/68881/68882/internal)
- --mmu <bool>
- Use MMU emulation
- --machine <x>
- Select machine type (x = st, megast, ste, megaste, tt or falcon)
- --blitter <bool>
- Enable blitter emulation (ST only)
- --dsp <x>
- Falcon DSP emulation (x = none, dummy or emu, Falcon only)
- --timer-d <bool>
- Patch redundantly high Timer-D frequency set by TOS. This about doubles
Hatari speed (for ST/e emulation) as the original Timer-D frequency causes
most of the interrupts.
- --fast-boot <bool>
- Patch TOS and initialize the so-called "memvalid" system
variables to by-pass the memory test of TOS, so that the system boots
faster.
- --mic <bool>
- Enable/disable (Falcon only) microphone
- --sound <x>
- Sound frequency: 6000-50066. "off" disables the sound and speeds
up the emulation. To prevent extra sound artifacts, the frequency should
be selected so that it either matches evenly with the STE/TT/Falcon sound
DMA (6258, 12517, 250033, 50066 Hz) or your sound card frequencies (11025,
22050, 44100 or 6000...48000 Hz). Check what your sound card
supports.
- --sound-buffer-size <x>
- SDL's sound buffer size: 10-100, or 0 to use default buffer size. By
default Hatari uses an SDL buffer size of 1024 samples, which gives
approximatively 20-30 ms of sound depending on the chosen sound frequency.
Under some OS or with not fully supported sound card, this default setting
can cause a bigger delay at lower frequency (nearly 0.5 sec). In that
case, you can use this option to force the size of the sound buffer to a
fixed number of milliseconds of sound (using 20 is often a good choice if
you have such problems). Most users will not need this option.
- --sound-sync <bool>
- The emulation rate is nudged by +100 or 0 or -100 micro-seconds on
occasion. This prevents the sound buffer from overflowing (long latency
and lost samples) or underflowing (short latency and repeated samples).
The emulation rate smoothly deviates by a maximum of 0.58% until
synchronized, while the emulator continuously generates every sound sample
and the crystal controlled sound system consumes every sample.
(on|off, off=default)
- --ym-mixing <x>
- Select a method for mixing the three YM2149 voice volumes together.
"model" uses a mathematical model of the YM voices,
"table" uses a lookup table of audio output voltage values
measured on STF and "linear" just averages the 3 YM voices.
- -W, --wincon
- Open console window (Windows only)
- -D, --debug
- Toggle whether CPU exceptions invoke the debugger
- --debug-except <flags>
- Specify which exceptions invoke debugger, see --debug-except help
for available (comma separated) exception flags.
- --bios-intercept
- Toggle XBios command parsing. Allows Atari programs to use all Hatari
functionality and change Hatari state through Hatari specifit XBios(255)
calls. XBios(20) printscreen calls produce also Hatari screenshots.
- --conout <device>
- Enable console (xconout vector functions) output redirection for given
<device> to host terminal. Device 2 is for the (CON:) VT52 console,
which vector function catches also EmuTOS panic messages and MiNT console
output, not just normal BIOS console output.
- --disasm <x>
- Set disassembly options. 'uae' and 'ext' select the dissasembly engine to
use, bitmask sets output options for the external disassembly engine and
'help' lists them.
- --natfeats <bool>
- Enable/disable (basic) Native Features support. E.g. EmuTOS uses it for
debug output.
- --trace <flags>
- Activate debug traces, see --trace help for available (comma
separated) tracing flags
- --trace-file <file>
- Save trace output to <file> (default=stderr)
- --parse <file>
- Parse/execute debugger commands from <file>
- --saveconfig
- Save Hatari configuration and exit. Hatari UI needs Hatari configuration
file to start, this can be used to create it automatically.
- --no-parachute
- Disable SDL parachute to get Hatari core dumps. SDL parachute is enabled
by default to restore video mode in case Hatari terminates abnormally
while using non-standard screen resolution.
- --control-socket <file>
- Hatari reads options from given socket at run-time
- --log-file <file>
- Save log output to <file> (default=stderr)
- --log-level <x>
- Log output level (x=debug/todo/info/warn/error/fatal)
- --alert-level <x>
- Show dialog for log messages above given level
- --run-vbls <x>
- Exit after X VBLs
- --benchmark
- Start in benchmark mode (use with --run-vbls). This allows to measure the
speed of the emulation in frames per second by running at maximum speed
(don't wait for VBL). Disable audio/video output to have as little OS
overhead as possible
Hatari provides special input handling for different purposes.
Joystick can be emulated either with keyboard or any real joystick supported by
your kernel / SDL library. First joystick button acts as FIRE, second as SPACE
key.
Middle button mouse click is interpreted as double click, this is especially
useful in Fast Forward mode.
Mouse scrollwheel will act as cursor up and down keys.
Keys on the keyboard act as the normal Atari ST keys so pressing SPACE on your
PC will result in an emulated press of the SPACE key on the ST. How the PC
keys are mapped to Atari key codes, can be changed with keyboard config file
(-k option).
The following keys have special meanings:
- Alt
- will act as the ST's ALTERNATE key
- left Ctrl
- will act as the ST's CONTROL key
- Print
- will emulate the ST's HELP key
- Scroll lock
- will emulate the ST's UNDO key
AltGr will act as
Alternate as well as long as you do not press it
together with a Hatari hotkey combination.
The
right Ctrl key is used as the fire button of the emulated joystick
when you turn on joystick emulation via keyboard.
The cursor keys will act as the cursor keys on the Atari ST as long as joystick
emulation via keyboard has been turned off.
The shortcut keys can be configured in the configuration file. The default
settings are:
- AltGr + a
- record animation
- AltGr + g
- grab a screenshot
- AltGr + i
- boss key: leave full screen mode and iconify window
- AltGr + m
- (un-)lock the mouse into the window
- AltGr + r
- warm reset the ST (same as the reset button)
- AltGr + c
- cold reset the ST (same as the power switch)
- AltGr + d
- open dialog to select/change disk A
- AltGr + s
- enable/disable sound
- AltGr + q
- quit the emulator
- AltGr + x
- toggle normal/max speed
- AltGr + y
- enable/disable sound recording
- AltGr + k
- save memory snapshot
- AltGr + l
- load memory snapshot
- AltGr + j
- toggle joystick emulation via cursor keys
- AltGr + F1
- switch joystick type on joy port 0
- AltGr + F2
- switch joystick type on joy port 1
- AltGr + F3
- switch joystick type for joypad A
- AltGr + F4
- switch joystick type for joypad B
- AltGr + b
- toggle borders on/off
- AltGr + f or F11
- toggle between fullscreen and windowed mode
- AltGr + o or F12
- activate the Hatari options GUI
You may need to hold SHIFT down while in windowed mode.
- Pause
- Pauses the emulation
- AltGr + Pause
- Invokes the internal Hatari debugger
There are multiple ways to interact with the SDL GUI.
TAB and cursor keys change focus between UI elements. Additionally Home key
moves focus to first item, End key to last one. Initially focus is on default
UI element, but focus changes are remembered between dialog invocations. Enter
and Space invoke focused item. UI elements with underlined characters can be
invoked directly with Alt + key with that character. Alt + arrow keys will act
on arrow buttons.
Most importantly:
- Options GUI main view
- Enter accepts configuration, ESC cancels it.
- Options GUI dialogs
- Enter (or End+Enter if focus was moved) returns back to main view.
- Fileselector
- Page up and down keys scroll the file list. Enter on focused file name
selects it. Enter on OK button accepts the selected file. ESC cancels the
dialog/selection.
- Alert dialogs
- Enter accepts and ESC cancels the dialog.
The main program documentation, usually in /usr/local/share/doc/. Among other
things it contains an extensive usage manual, software compatibility list and
release notes.
The homepage of Hatari: http://hatari.tuxfamily.org/
Other Hatari programs and utilities:
hmsa(1),
zip2st(1),
atari-convert-dir(1),
atari-hd-image(1),
hatariui(1),
hconsole(1),
gst2ascii(1),
hatari_profile(1)
- /usr/local/etc/hatari.cfg
- The global configuration file of Hatari.
- ~/.hatari/
- The (default) directory for user's personal Hatari files;
hatari.cfg (configuration file), hatari.nvram (NVRAM content
file), hatari.sav (Hatari memory state snapshot file which Hatari
can load/save automatically when it starts/exits), hatari.prn
(printer output file), hatari.wav (recorded sound output in WAV
format), hatari.ym (recorded sound output in YM format).
- /usr/local/share/hatari/ (or /usr/local/share/hatari/)
- The global data directory of Hatari.
- tos.img
- The TOS ROM image will be loaded from the data directory of Hatari unless
it is specified on the command line or the configuration file.
This manual page was written by Marco Herrn <marco@mherrn.de> for the
Debian project and later modified by Thomas Huth and Eero Tamminen to suit the
latest version of Hatari.