emulator: Hatari
type: libretro
source: "https://github.com/libretro/hatari"
logo: "https://raw.githubusercontent.com/hatari/hatari/main/share/icons/hicolor/scalable/apps/hatari.svg"
profiled_date: "2026-03-18"
core_version: "1.8"
display_name: "Atari - ST/STE/TT/Falcon (Hatari)"
systems: [atari-st, atari-ste, atari-tt, atari-falcon]

# Hatari requires a TOS ROM image to boot. The default filename is tos.img,
# loaded from either system/ or system/hatari/tos/ (libretro core scans both).
# EmuTOS (open source replacement) is detected via 'ETOS' magic at offset 0x2c.
# Cartridge ROM is optional and loaded from szCartridgeImageFileName config.

# TOS version/machine compatibility (enforced in tos.c TOS_CheckSysConfig):
#   TOS 1.00-1.04  -> ST only, 68000
#   TOS 1.06/1.62  -> STE only
#   TOS 2.0x       -> ST/STE (patched for ST compatibility)
#   TOS 3.0x       -> TT only, 68030+
#   TOS 4.0x       -> Falcon only, 68020+
#   EmuTOS         -> all machine types (no version constraint)

# Libretro core search paths (libretro.c):
#   1. <system>/tos.img (legacy default)
#   2. <system>/hatari/tos/ directory (all .img/.rom/.tos files listed as options)
# Core option "hatari_tosimage" selects which TOS image to use.

files:
  # -- Primary TOS ROM (required) --
  # At minimum one TOS image must be present. The most commonly used
  # version is TOS 1.02, which is the default for Atari ST emulation.

  - name: "tos.img"
    path: "tos.img"
    required: true
    note: >
      TOS ROM image. Any valid version (1.00 through 4.04) or EmuTOS works.
      The core auto-detects version from the ROM header and adjusts machine type.
      Default location is system/tos.img, additional images go in system/hatari/tos/.
    source_ref: "src/tos.c:576-696, libretro/libretro.c:387-410"

  # -- Cartridge ROM (optional) --
  # External cartridge image, max 128 KB. Formats: .img, .rom, .stc
  # Cannot be used together with GEMDOS HD emulation or extended VDI resolution.

  - name: "cartridge ROM"
    path: null  # user-configured via szCartridgeImageFileName
    required: false
    max_size: 131076  # 0x20004 (.stc with 4-byte header) or 0x20000 (raw)
    note: >
      External cartridge image. Loaded to address 0xFA0000.
      STC format images (0x20004 bytes) have a 4-byte header that is stripped.
      Mutually exclusive with GEMDOS hard disk emulation and extended VDI.
    source_ref: "src/cart.c:53-88"

# Supported TOS versions (from patch table in tos.c):
#   0x100 - TOS 1.00 (ST, 68000 only, no VDI extensions)
#   0x102 - TOS 1.02 (ST, most common for gaming)
#   0x104 - TOS 1.04 (ST, adds autostart support)
#   0x106 - TOS 1.06 (STE only)
#   0x162 - TOS 1.62 (STE only)
#   0x205 - TOS 2.05 (STE native, patched for ST)
#   0x206 - TOS 2.06 (STE/ST)
#   0x306 - TOS 3.06 (TT, 68030+)
#   0x400 - TOS 4.00 (Falcon, 68020+)
#   0x401 - TOS 4.01 (Falcon)
#   0x402 - TOS 4.02 (Falcon)
#   0x404 - TOS 4.04 (Falcon)
#   0x492 - TOS 4.92 (RAM TOS variant)

# TOS ROM sizes (typical):
#   192 KB (0x30000) - TOS 1.0x (loaded at 0xFC0000)
#   256 KB (0x40000) - TOS 2.0x+ (loaded at 0xE00000)
#   Up to 1 MB       - maximum accepted by the loader

# File extensions scanned: .img, .rom, .tos

notes:
  emutos_note: >
    EmuTOS is a free open-source TOS replacement that works with all machine types.
    Hatari detects it via the 'ETOS' signature at ROM offset 0x2c and skips
    machine-type enforcement and ROM patches.
  gemdos_boot_note: >
    When using GEMDOS hard disk mode with .gem files, the core also loads
    system/hatari/BOOT.ST as a floppy image for bootstrapping.
  libretro_path_note: >
    The libretro core checks system/tos.img first for backward compatibility,
    then scans system/hatari/tos/ for additional TOS images exposed as core options.