HATARI(1)

📦
version 2.6.1 · 5 versions
, in arch rolling, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, ubuntu resolute, ubuntu stonking

✨ HATARI(1) ✨

like, the manual page for hatari — the Atari ST/STE/TT/Falcon emulator, bestie 💖

🎀 NAME 🎀

hatari — Atari ST/STE/TT/Falcon emulator

🦋 SYNOPSIS 🦋

hatari [options] [directory|diskimage|program]

💜 DESCRIPTION 💜

okay so. Hatari is an Atari ST/STE/TT/Falcon emulator for Linux and other Systems which are supported by the SDL (cross-platform graphics, input and sound) library. it's giving "your whole childhood but on your laptop" and honestly? we're obsessed 🫶

With Hatari one can run games, demos or applications written for Atari ST, STE or Falcon. Atari TT support is experimental — like, it works, but it's in its experimental era, okay? Hatari supports the commonly used *.st, *.msa and *.stx disk images, and hard disk emulation. iconic.

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 and doesn't need separate HD drivers, but some buggy (typically floppy only) programs won't work correctly with it. 😭 For best compatibility, it is 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, either as an option or an argument (and which corresponds to A: or C:). last one wins, no cap 🧚

🌈 OPTIONS 🌈

Hatari options are split into several categories:

💫 General options 💫

  • -h, --help — Print command line options and terminate. the classic "help me bestie" move 💅
  • -v, --version — Print version information and terminate.
  • --confirm-quit <bool> — Whether Hatari confirms quitting. (do you really wanna leave? are you sure?? 🥺)
  • -c, --configfile <filename> — Read additional configuration values from <file>, these override values read from the global and user configuration files. so this one's got main character energy — it wins over the others ✨
  • -k, --keymap <file> — Load keyboard mapping from <file>. "Symbolic" mapping will be used as fallback for keys not defined there.
  • --country <x> — Set EmuTOS ROM country code on Mega/ST/STe machines lacking NVRAM, when EmuTOS indicates supporting multiple ones.

In 512k EmuTOS images, country code selects the TOS keyboard layout and screen refresh (US = 60Hz NTSC, 50Hz PAL otherwise). In 1024k EmuTOS images (coming with Hatari binaries and supporting multiple languages), country code selects also TOS language.

Alternatively, one can use "tos-lang-change" tool from EmuTOS project to modify country code in the ROM image file itself. That works also for TOS v4.

  • --layout <x> — Set NVRAM keyboard layout value. While both TT and Falcon machines have NVRAM, only TOS v4 and EmuTOS 512k / 1024k ROM versions support multiple layouts.

Regardless of whether keyboard layout change is done through the ROM country code or NVRAM setting, it may impact your key mappings in Hatari key mapping files, Hatari Python UI arguments, or key injection in your automation scripts for Hatari debugger, command FIFO or hconsole tool. ⚠️ so yeah, heads up, it ripples.

  • --language <x> — Set NVRAM language value. While both TT and Falcon machines have NVRAM, only TOS v4 and EmuTOS 1024k ROM versions support multiple languages. Default is taken from the LANG environment variable.
  • --fast-forward <bool> — Fast-forward through the boring parts by running emulator at maximum speed. Done by skipping frame update VBL waits. Upper limit for frame skipping is given with the --frameskips option and shown in statusbar "FS" field. literally the "skip intro" button 🏃💨
  • --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 for the boot drive (A: or C:), which tells TOS to start the given program.
  • --fast-forward-key-repeat <bool> — Use keyboard auto repeat when using fast forward mode (default true).

🌸 Common display options 🌸

  • -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. 🐭 gotcha
  • --resizable <bool> — Allow window resizing.
  • --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). the opposite vibe of fast-forward, obviously 💀
  • --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). leds!! 💡
  • --drive-led <bool> — Show overlay drive led when statusbar isn't shown.
  • --max-width <x> — Preferred / maximum Hatari screen width.
  • --max-height <x> — Preferred / maximum Hatari screen height.

Maximum width and height options are part of Hatari's Atari monitor emulation. They limit the size Hatari should aim for its internal SDL framebuffer, and how much of the Atari screen borders are visible.

The framebuffer is then scaled to the Hatari output window based on the specified Hatari zoom factor (see below).

Aim of this is to have all resolutions show up in approximately same size, like on a real Atari monitor. Hatari's internal integer scaling support sets some limits on this, so it's an expert option. 👑

Note: Only reason to change the defaults, should be limiting this to a smaller resolution for performance reasons, e.g. for video recording, or on really underpowered systems, to make monitor do all of the ST-low resolution scaling by forcing Hatari to ask SDL for CGA / QVGA resolution.

  • -z, --zoom <x> — This option overrides max width/height options so that e.g. ST-low resolution gets always doubled, and all resolutions (except TT-high) have approximately the same size, like on a real CRT monitor.

Zoom factor is then used to scale that up (or down) to the Hatari output window. This way scaling results always in approximately same sized Hatari window.

With non-integer zoom factors, linear scaling is used to smooth out the output, with integer zoom factors, scaling is done using nearest neighboring pixels for sharper output. This applies also to window resizes.

To avoid zooming of low resolutions, use "--zoom 1 --max-width 416 --max-height 276" (if you don't need borders, 320x200 size is enough). Disabling low resolution doubling like this is not recommended for Falcon emulation because TOS v4 bootup and some demos switch resolutions frequently. ⚠️

  • --bpp <bool> — Force internal bitdepth (x = 8/15/16/32, 0=disable).
  • --disable-video <bool> — Run emulation without displaying video (audio only). 🎧 all vibes, zero pixels

⭐ ST/STE specific display options ⭐

  • --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).
  • --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. 🎲 roll the dice, bestie

🦄 TT/Falcon specific display options 🦄

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. ✨ crisp, no filter, no blur

  • --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 options 🧚

  • --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). Original TOS desktops use wrong window size in 2-plane (4 color) VDI mode when screen height >= 400 pixels. Because of these issues, using EmuTOS is recommended for VDI mode. 😭 it's a whole situation, fr fr
  • --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 <= 2048).
  • --vdi-height <h> — Use extended VDI resolution with height <h> (160 < h <= 1280).

Because TOS and popular GEM programs have problems with certain screen sizes, Hatari enforces restrictions on VDI screen size. In total VDI screen size is limited to 32-300kB, width to multiple of 16/planes, and height to multiple of 8 pixels (smaller system font height). That translates to following maximum standard resolutions for the VDI mode:

  • monochrome — FullHD (1920x1080), WUXGA (1920x1200) and QWXGA (2048x1152)
  • 2 plane mode (4 colors) — HD (1280x720), WXGA (1280x768) and XGA+ (1152x864)
  • 4 plane mode (16-colors) — qHD (960x540), DVGA (960x640) and WSVGA (1024x600)

🎬 Screen capture options 📸

Like, taking pics of your Atari desktop? We got you 💅

  • --crop <bool> — Chop the statusbar out of your screen captures. Nobody wants that bar in the shot, fr fr. ✂️
  • --avirecord — Kicks off AVI recording. Heads up tho: the recording just stops on its own when the emulation resolution changes. Not me getting jump-scared by that 😭
  • --avi-vcodec <x> — Picks your AVI video codec (x = bmp/png). PNG compression can be way slower than the uncompressed bmp format, but bestie… uncompressed video eats up an absolutely unhinged amount of space. Pick your poison 🫠
  • --png-level <x> — Sets the PNG compression level for AVI video (x = 0-9). Both how well it squishes and how fast it goes depend on what's actually on the compressed screen. Level 9 (the max) can get really slow with some content. Levels 3-6 should compress nearly as well with clearly less CPU overhead — that's the sweet spot, lowkey 👑
  • --avi-fps <x> — Forces the AVI frame rate (x = 50/60/71/...)
  • --avi-file <file> — Records the AVI into file 🎥
  • --screenshot-dir <dir> — Where your screenshots get saved (dir). The default Hatari directory for them is OS specific, iykyk.

🕹️ Devices options 🎀

  • -j, --joystick <port> — Emulates a joystick using your cursor keys in the given port (0-5). Keyboard warrior era 💜
  • --joy<port> <type> — Sets the joystick type (none/keys/real) for that port. Yes, real means an actual physical joystick, no cap.
  • --printer <file> — Turns on printer support and writes the data to file 🖨️
  • --midi <bool> — Whether to enable MIDI device support (this one only works when Hatari is built with PortMidi support)
  • --midi-in <filename> — Enables MIDI support and writes raw MIDI data to file (for when it's not built with PortMidi support)
  • --midi-out <filename> — Enables MIDI support and reads raw MIDI data from file (also for when it's not built with PortMidi support)
  • --rs232-in <filename> — Enables MFP serial port support and uses file as the input device
  • --rs232-out <filename> — Enables MFP serial port support and uses file as the output device
  • --scc-a-in <filename> — Enables SCC channel A serial port support and uses file for the input (only for Mega-STE, TT and Falcon ✨)
  • --scc-a-out <filename> — Enables SCC channel A serial port support and uses file for the output (only for Mega-STE, TT and Falcon ✨)
  • --scc-a-lan-in <filename> — Enables SCC channel A LAN port support and uses file for the input (only for Mega-STE and TT)
  • --scc-a-lan-out <filename> — Enables SCC channel A LAN port support and uses file for the output (only for Mega-STE and TT)
  • --scc-b-in <filename> — Enables SCC channel B serial port support and uses file for the input (only for Mega-STE, TT and Falcon ✨)
  • --scc-b-out <filename> — Enables SCC channel B serial port support and uses file for the output (only for Mega-STE, TT and Falcon ✨)

💾 Floppy drive options 🍓

  • --drive-a <bool> — Turns drive A on or off (default is on)
  • --drive-b <bool> — Turns drive B on or off (default is on)
  • --drive-a-heads <x> — Sets the number of heads for drive A (1=single sided, 2=double sided)
  • --drive-b-heads <x> — Sets the number of heads for drive B (1=single sided, 2=double sided)
  • --disk-a <file> — Sets the disk image for floppy drive A
  • --disk-b <file> — Sets the disk image for floppy drive B
  • --fastfdc <bool> — Speeds up FDC emulation. Fair warning bestie: this can cause incompatibilities 😬
  • --protect-floppy <x> — Write-protects the floppy image contents (on/off/auto). With the "auto" option, write protection follows the disk image file attributes. Vibes-based security fr.

🗄️ Hard drive options 💅

  • -d, --harddrive <dir> — GEMDOS HD emulation. It emulates harddrive partition(s) using the contents of dir. Okay so here's the tea: if the directory contains only single letter (C-Z) subdirectories, then each of those subdirectories gets treated as its own separate partition. Otherwise, the given directory itself gets assigned to drive "C:". In the multiple partition case, the letters used as the subdirectory names determine which drives/partitions they're assigned to. And if dir is an empty string, then harddrive emulation is just… disabled. Periodt.
  • --protect-hd <x> — Write-protects the harddrive dir contents (on/off/auto). With the "auto" option, the protection can be controlled by setting individual file attributes, since it disables the file attribute modifications for the GEMDOS hard disk emulation.
  • --gemdos-case <x> — Says whether new dir/filenames get forced into upper or lower case with the GEMDOS HD emulation. Options are off/upper/lower, and it's off by default.
  • --gemdos-time <x> — Picks which file modification timestamps get used: the emulation internal (atari) ones, or the ones from the machine (host) that the machine is running on. Here's the thing — while the Atari emulation and host clocks are in sync at Hatari startup, they diverge while emulation is running, especially if you use fast forward. Default is "atari". If you're modifying files that the Atari side accesses, directly from the host side while Hatari is already running, you might wanna use the "host" option instead 🕰️
  • --gemdos-conv <bool> — Whether GEMDOS file names with 8-bit (non-ASCII) characters get converted between Atari and host character sets. On Linux, the host file name character set is assumed to be UTF-8. This option is disabled by default, in case you've transferred files from an Atari machine without proper file name conversion (e.g. by zipping them on Atari and unzipping on PC) 😭
  • --gemdos-drive <drive> — Assigns a (separately specified) GEMDOS HD to the given drive letter (C-Z) instead of the default C:, or use "skip" to say Hatari should add the GEMDOS HD after the IDE and ACSI drives. ("skip" assumes Hatari and the native HD driver parse the same number of partitions from the partition tables in HD images.)
  • --acsi <id>=<file> — Emulates an ACSI hard disk with the given BUS ID (0-7) using image file. If you just hand it a filename, it gets assigned to BUS ID 0.
  • --scsi <id>=<file> — Emulates a SCSI hard disk with the given BUS ID (0-7) using image file. If you just hand it a filename, it gets assigned to BUS ID 0.
  • --scsi-ver <id>=<version> — Emulates the specified SCSI version (1-2) for the given BUS ID (0-7). If you just give a version, it's applied to BUS ID 0.
  • --ide-master <file> — Emulates an IDE 0 (master) hard disk with an image file
  • --ide-slave <file> — Emulates an IDE 1 (slave) hard disk with an image file
  • --ide-swap <id>=<x> — Sets the byte-swap option x (off/on/auto) for the given IDE id (0/1). If you just give the option, it's applied to IDE 0.

🧠 Memory options ✨

  • --memstate <file> — Loads the memory snap-shot file
  • -s, --memsize <x> — Sets how much emulated ST RAM you get. x = 1 to 14 MiB, or 0 for 512 KiB. Any other values are considered as a size in KiB. So here's the reality check: while Hatari allows 14 MiB for all machine types, on real HW, ST/STE can have up to 4 MiB, MegaSTE/TT up to 10 MiB, and Falcon up to 14 MiB RAM. Emulator privileges, we love to see it 👑
  • --ttram <x> — Sets how much emulated TT RAM you get, x = 0 to 1024 MiB (in 4MiB steps)

📼 ROM options 🌈

  • -t, --tos <imagefile> — Specifies which TOS ROM image to use
  • --patch-tos <bool> — Use this to enable/disable TOS ROM patching. Experts only! Leave it enabled unless you genuinely know what you're doing, bestie 🙈
  • --cartridge <imagefile> — Uses the ROM cartridge image file (only works if GEMDOS HD emulation and extended VDI resolution are disabled)

⚡ CPU/FPU/bus options 🔥

  • --cpulevel <x> — Specifies which CPU (680x0) to use. (Only use x >= 1 with EmuTOS or TOS >= 2.06!)
  • --cpuclock <x> — Sets the CPU clock (8, 16 or 32 Mhz)
  • --compatible <bool> — Uses a more compatible 68000 CPU mode with better prefetch accuracy and cycle counting
  • --cpu-exact <bool> — Uses cycle exact CPU emulation
  • --data-cache <bool> — Emulates >= 030 CPU data cache
  • --addr24 <bool> — Uses 24-bit instead of 32-bit addressing mode (24-bit is enabled by default)
  • --fpu <x> — FPU type (x=none/68881/68882/internal)
  • --fpu-softfloat <bool> — Uses full software FPU emulation (Softfloat library)
  • --mmu <bool> — Uses MMU emulation

🛠️ Misc system options 🦋

  • --machine <x> — Selects the machine type (x = st, megast, ste, megaste, tt or falcon)
  • --blitter <bool> — Enables blitter emulation (ST only)
  • --dsp <x> — Falcon DSP emulation (x = none, dummy or emu, Falcon only)
  • --rtc-year <x> — With the default value 0, RTC date and time are taken from the host. If an application doesn't handle current dates, you can use this to change the RTC year to a more compatible one. See also the --gemdos-time option.
  • --timer-d <bool> — Patches the redundantly high Timer-D frequency that TOS sets. This can increase Hatari speed significantly (especially for ST/e emulation), because the original Timer-D frequency causes a large amount of extra interrupts to emulate. Speedrun strats, honestly 🏃‍♀️
  • --fast-boot <bool> — Patches TOS and initializes the so-called "memvalid" system variables to by-pass the memory test of TOS, so the system boots faster. We love a shortcut 💖

🔊 SOUND OPTIONS 🔊

okay bestie, this is where we make the beeps and boops happen 💖

  • --mic <bool> — turns the microphone on or off — and heads up, this is Falcon only, so don't come for me if your ST doesn't have opinions about it 🎤
  • --sound <x> — sets the sound frequency, anywhere from 6000 to 50066. And yes, you can literally pass "off" and it kills the sound completely, which lowkey speeds up the emulation (free performance, we love that ✨). Now here's the tea: to keep extra sound artifacts from showing up and ruining the vibe, you want to pick a frequency that lines up evenly with either the STE/TT/Falcon sound DMA (6258, 12517, 250033, 50066 Hz) or your sound card's own frequencies (11025, 22050, 44100 or 6000...48000 Hz). Go check what your sound card actually supports, bestie, don't guess 💅
  • --sound-buffer-size <x> — this is SDL's sound buffer size, and it takes 10-100, or 0 if you just want the default buffer size. By default Hatari rocks an SDL buffer size of 1024 samples, which works out to roughly 20-30 ms of sound depending on the sound frequency you picked. BUT. Under some OS, or with a sound card that isn't fully supported, that default can cause a way bigger delay at lower frequency — we're talking nearly 0.5 sec 😭 In that case you can use this option to force the sound buffer size to a fixed number of milliseconds of sound (using 20 is often a good choice if you're dealing with this). Real talk tho: most users will not need this option 🫶
  • --sound-sync <bool> — okay so what this does is nudge the emulation rate by +100 or 0 or -100 micro-seconds on occasion. Why tho? To stop the sound buffer from overflowing (which = long latency and lost samples, tragic) or underflowing (which = short latency and repeated samples, also tragic). The emulation rate smoothly deviates by a maximum of 0.58% until it's synchronized, while the emulator keeps continuously generating every sound sample and the crystal controlled sound system consumes every sample. Balanced. Iconic. (on|off, and off is the default) 🎶
  • --ym-mixing <x> — pick your 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
    • "linear" just averages the 3 YM voices

🐛 DEBUG OPTIONS 🐛

the nerdy corner of the group chat and honestly? we stan 🎀

  • -W, --wincon — opens a console window (Windows only, sorry everyone else)
  • -D, --debug — toggles whether CPU exceptions invoke the debugger
  • --debug-except <flags> — specifies which exceptions invoke the debugger. Run --debug-except help to see the available (comma separated) exception flags 💀
  • --lilo <string> — boots m68k Linux using the kernel, ramdisk, and kernel arguments specified in the Hatari configuration file [LILO] section. The Hatari documentation folder contains an example "lilo.cfg" config file for exactly this. Whatever string you hand to --lilo gets appended to the kernel command line.
⚠️ NOTE: this is a Hatari (and Linux kernel) developer option to test Linux booting. Unless you know how your kernel is configured, and the state of specific kernel and Hatari features, don't expect m68k Linux to boot up successfully. fr fr, manage your expectations 🙈
  • --bios-intercept <bool> — enables/disables XBios command parsing. XBios(11) Dbmsg call can be used to invoke the Hatari debugger. XBios(20) printscreen calls also produce Hatari screenshots. XBios(255) lets Atari programs use Hatari debugger functionality, which allows stuff like invoking shortcuts and Hatari command line options. That last one is deprecated tho, because it gives way too much control to the emulated program — please use NatFeats and remote control APIs (--natfeats, --cmd-fifo, hconsole) instead of XBios 11 and 255, bestie, we're begging 🥺
  • --conout <device> — enables console (xconout vector functions) output redirection for the given <device> to the host terminal. Device 2 is for the (CON:) VT52 console, whose vector function catches EmuTOS panic messages and MiNT console output too, not just normal BIOS console output ✨
  • --disasm <x> — sets disassembly options. 'uae' and 'ext' select the disassembly engine to use, a bitmask sets disassembly output options, and 'help' lists them all out for you 📋
  • --natfeats <bool> — enables/disables (basic) Native Features support. EmuTOS uses it for debug output, and it's supported by the Aranym emulator too. For more info, peep the example code and readme.txt in tests/natfeats/ coming with Hatari sources 🦋
  • --trace <flags> — activates debug traces. Run --trace help to see the available (comma separated) tracing flags 👀
  • --trace-file <file> — saves trace output to <file> (default=stderr)
  • --msg-repeat — toggles whether successive repeats of identical log or trace messages get suppressed, so only their count shows up (default=suppress). FYI, disassembly, register and (multi-line) AES traces bypass this feature entirely 💅
  • --parse <file> — parses/executes debugger commands from <file>
  • --saveconfig — saves the Hatari configuration and exits. Hatari UI needs a Hatari configuration file to start, so this is how you create one automatically, no manual labor required ✨
  • --control-socket <path> — Hatari connects to the given local socket file and reads commands from it. Use this when the control process's life-time is longer than Hatari's, or when the control process needs a response from Hatari 📡
  • --cmd-fifo <path> — Hatari creates the indicated FIFO file and reads commands from it. Commands can be echoed to the FIFO file, and they're the same as with the control socket. Hatari outputs help for unrecognized commands and subcommands 🫶
  • --log-file <file> — saves log output to <file> (default=stderr)
  • --log-level <x> — sets the log output level (x = debug/todo/info/warn/error/fatal)
  • --alert-level <x> — shows a dialog for log messages above the given level
  • --run-vbls <x> — exits after X VBLs. Used with --benchmark mode 🏁
  • --benchmark — starts in benchmark mode (use it with --run-vbls). Same as --fast-forward mode, except it cannot be disabled at run-time, and FPS gets printed on emulation exit (and pausing) regardless of log level. This allows better measuring of emulation speed, in frames per second. Unless you're specifically measuring emulator audio and screen processing speed, disable them (--sound off / --disable-video on) so you have as little OS overhead as possible 🔥

🎮 INPUT HANDLING 🎮

Hatari provides special input handling for different purposes. Buckle up, bestie 💖

🕹️ Emulated Atari ST joystick

The joystick can be emulated either with the keyboard or with any real joystick supported by your kernel / SDL library. First joystick button acts as FIRE, second as SPACE key. no cap 🫡

🐭 Emulated Atari ST mouse

Middle button mouse click is interpreted as double click — this is especially useful in Fast Forward mode, iykyk 💅

Mouse scrollwheel will act as cursor up and down keys.

⌨️ Emulated Atari ST keyboard

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 the 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 👑

⚡ Keyboard shortcuts during emulation

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

🖥️ Keyboard shortcuts for the SDL GUI

There are multiple ways to interact with the SDL GUI. Pick your fighter ✨

TAB and cursor keys change the focus between UI elements. Home key moves focus to the first dialog item, End key to the last one. Initially the focus is on the default UI element, but focus changes are remembered between dialog invocations 🧠

Enter and Space invoke the focused item, ESC key invokes the dialog cancel option (if there is one).

Any UI element whose name has an underlined character can be invoked directly by pressing Alt + key with that character. Alt + arrow keys will act on dialog arrow buttons.

Main interactions:

  • 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 move the file list by one page, mouse wheel and Alt + cursor keys scroll it by one item. Enter on the focused file name selects it. Enter on the OK button accepts the selected file. ESC cancels the dialog/selection.
  • Alert dialogs — Enter accepts and ESC cancels the dialog.

👀 SEE ALSO 👀

The main program documentation, usually in /usr/share/doc/. Among other things it contains an extensive usage manual, software compatibility list and release notes. Go read it, it's giving ✨educated✨

The homepage of Hatari: https://www.hatari-emu.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) 🫶

🗂️ FILES AND DIRECTORIES 🗂️

okay bestie, this is the part where Hatari tells you where it keeps all its stuff. lowkey important if you wanna find your config, your snapshots, or where tf that TOS image is supposed to live 💅

  • /etc/hatari.cfg (or /usr/local/etc/hatari.cfg) — the global configuration file of Hatari. like, the system-wide one, the shared brain of the whole install ✨
  • ~/.config/hatari/ — the default directory for your personal Hatari files, aka your corner of the vibe 🌸 inside it lives:
    • hatari.cfg — the configuration file
    • hatari.nvram — the NVRAM content file
    • hatari.sav — the Hatari memory state snapshot file, which Hatari can load/save automatically when it starts/exits (autosave bestie behavior fr fr 😭)
    • hatari.prn — the printer output file,
  • /usr/share/hatari/ (or /usr/local/share/hatari/) — the global data directory of Hatari. the main character storage unit 👑
  • tos.img — the TOS ROM image 🎀 this one gets loaded from the data directory of Hatari unless you specify it on the command line or in the configuration file. so like, it has a home by default, but you can absolutely redirect it if you want. iykyk

✍️ AUTHOR ✍️

okay so this whole manual page? it was written by Marco Herrn <marco@mherrn.de> for the Debian project 🫶 and then later modified by Thomas Huth and Eero Tamminen so it would suit the latest version of Hatari. iconic collaborative energy, no cap 💖

and that's the whole page bestie!! 🦋 this was Hatari, version-dated 2020-11-27 (so you know exactly which flavor of the docs you just read), and the manpage reference for the whole thing is HATARI(1) ✨ go forth and emulate, you absolute legend 👑💅

📦 where this page comes from