Skip to content

Home

Jump to bottom
The Bit Culture edited this page Aug 8, 2026 · 6 revisions

ASE — Atari System Emulator · User Manual

ASE is a cross-platform emulator of the Atari ST family of home computers — the ST F/FM, the Mega ST and the STE — for Windows, macOS and Linux.

ASE is provided for educational purposes, without any warranty, under the GNU General Public License v3. It makes no claim of accuracy — although a lot of love has gone into getting the tricky bits right.

Contents

1. What is emulated

Area Details
CPU Motorola 68000 (Moira core), with optional cycle-exact bus timing (memory wait states, E-clock synchronized ACIA access)
Models Atari STF/FM, Atari STF/FM + Blitter (Mega ST), Atari STE
Memory 512 KB, 1 MB, 2 MB or 4 MB, with real MMU bank behaviour (TOS cold-boot memory detection works unpatched)
Video Low and medium resolution on a colour monitor, ST 512-colour / STE 4096-colour palettes, full overscan border emulation (top/bottom/left/right border removal tricks), mid-line palette effects (Spectrum 512 pictures, raster splits), STE line width register
Sound YM2149 PSG (3 channels + noise + envelope), STE DMA sound with Microwire/LMC1992 volume and mixing
Blitter Full BLiTTER emulation on Mega ST and STE
Floppy WD1772 controller, drive A, .ST, .MSA and .STX (Pasti) images, also inside .ZIP archives. STX images run with real disk timing: copy-protection schemes that measure sector timing, fuzzy sectors or CRC errors work
Input IKBD keyboard/mouse/joystick protocol, host gamepad support
Other MFP 68901 timers and interrupts, ACIA, machine snapshots (save states), built-in debugger with memory editor

Not (yet) emulated: high resolution monochrome monitor, STE hardware fine scrolling (registers exist but pixels don't shift), real STE joypads, MIDI, printer and serial ports.

Some of the copy-protection tricks used by certain games are still not emulated, but with each new version, I’m improving compatibility.

Hard drive emulation is not available yet, but it will be one of my next goals.

2. Requirements and installation

TOS ROM image

ASE needs a TOS ROM image, which is not included (TOS is copyrighted by Atari). Configure its path the first time you run the emulator (see Quick start).

Model selected Compatible TOS ROM size
Atari STF/FM, STF/FM + Blitter TOS 1.00 – 1.04 192 KB
Atari STE TOS 1.06 – 2.06 256 KB

EmuTOS should work, but I have not tested it, and I cannot guarantee proper support for any version of EmuTOS, as the emulator focuses on compatibility with original software.

Installing on Windows

Unzip the release package anywhere and run ASE.exe. Nothing else is needed.

Installing on Linux

  1. Unzip the release package anywhere.

  2. Install SDL2 from your distribution. ASE does not bundle it, because a copy built against the wrong system libraries would break audio or the gamepads. The runtime package is enough — you do not need the -dev/-devel one:

    Distribution Command
    Debian, Ubuntu, Raspberry Pi OS, Mint sudo apt install libsdl2-2.0-0
    Fedora, RHEL sudo dnf install SDL2
    Arch, Manjaro sudo pacman -S sdl2
    openSUSE sudo zypper install libSDL2-2_0-0

    ASE looks for libSDL2.so, libSDL2-2.0.so.0 and libSDL2-2.0.so, in that order, so the plain runtime package (which only installs the versioned libSDL2-2.0.so.0) works. A copy of the library placed next to the executable wins over the system one, should you ever need to pin a specific version.

  3. Run it:

    ./ASE

If ASE exits at startup complaining about moira.so, the file itself is normally present: the message means one of its dependencies could not be loaded. ASE prints the system's own explanation, which names the missing piece.

Graphics session — the window is X11-based. Inside a Wayland session it runs through XWayland, which is installed by default on the usual desktops and needs no action from you. Only if you have forced SDL_VIDEODRIVER=wayland in your environment will ASE come up with no keyboard, mouse or gamepad at all: unset it, and ASE will select X11 by itself.

Video previews in the library are optional and use the system's libVLC (sudo apt install vlc, or your distribution's equivalent). Without it everything else still works and the screenshot is shown in place of the video.

Installing on macOS

ASE ships as a .dmg disk image. It requires macOS 11 Big Sur or later.

The app is distributed without an Apple developer signature and without notarization. Because of that, macOS blocks it the first time you open it and warns that it cannot verify whether it contains malicious software. This does not mean the app is damaged — you simply have to authorize it manually, once.

1. Install

  • Drag ASE.app into your Applications folder.
  • Eject the disk image and open ASE.app from Applications.

2. Authorize the app the first time

The steps depend on your macOS version.

macOS 15 Sequoia or later

  • Double-click ASE.app. A security warning appears: click Done or OK.
  • Open System Settings ▸ Privacy & Security.
  • Scroll down to the Security section. You will see a message saying that “ASE” was blocked because it is not from an identified developer.
  • Click Open Anyway and authenticate with Touch ID or your administrator password.
  • Confirm by clicking Open in the final dialog.

macOS 14 Sonoma or earlier

  • Right-click (or Control-click) ASE.app in your Applications folder.
  • Choose Open from the contextual menu.
  • Click Open again in the dialog that appears.

From then on you can launch ASE with a normal double-click. You only need to do this once — or again after installing a new version.

3. Alternative: Terminal

If you prefer to remove the quarantine attribute directly, open Terminal (Applications ▸ Utilities ▸ Terminal) and run:

xattr -dr com.apple.quarantine /Applications/ASE.app

After running the command, ASE.app opens with a double-click and no further warnings.

4. Command-line executable

The emulator binary is named ASE and lives inside the app bundle at:

/Applications/ASE.app/Contents/MacOS/ASE

You can launch it from Terminal to see the console output or to pass command-line options. If you copy the ASE binary somewhere else and macOS reports that it lacks execute permission, grant it with:

chmod +x ASE

5. Frequently asked questions

  • “The application is damaged and can’t be opened” — this is what macOS reports when the file still carries the quarantine attribute after being downloaded from the internet. Apply the xattr command from point 3.
  • Is it safe? — an Apple developer signature requires a paid yearly subscription. Its absence says nothing about what the app contains, only that Apple has not verified its origin. Download ASE only from its official site and, if you wish, verify the checksum published alongside the file.
  • Do I have to repeat this for every update? — yes. Each newly downloaded version is flagged again as having come from the internet.

Video previews in the library use the copy of VLC installed in Applications; ASE finds VLC.app on its own. Without it the screenshot is shown in place of the video.

3. Quick start

  1. You must have a dump of your own original TOS ROM from an Atari ST in order to run ASE.
  2. Open Emulation ▸ Configuration, pick your Atari model, memory size and select your TOS image file, then close the dialog.
  3. You can load a disk image in the same way you would insert a disk into your ST with File ▸ Open disk image (or just drag & drop an .st, .msa, .stx or .zip file onto the window).
  4. Click inside the emulator screen and press F12 (or click the middle mouse button) to capture the keyboard and mouse. Press it again to release them and get the menu back.

That's it! you are on an Atari ST.

4. The main window

┌───────────────────────────────────────────────┐
│ File   Emulation   Help                       │  ← menu (disabled while input is captured)
│                                               │
│                emulated screen                │
│                                               │
├───────────────────────────────────────────────┤
│ status messages               A: T12 S05 [led]│  ← status bar + drive activity
└───────────────────────────────────────────────┘
  • File — open/change/eject disk images, save/restore snapshots, open the game library and configure it, quit.
  • Emulation — configuration dialog, debugger, machine reset.
  • Help — about box.
  • The drive LED on the right of the status bar lights up while the floppy is being accessed. Next to it, the drive activity indicator shows which drive, track and sector is being read (A: T12 S05). Since floppy loading is silent, this is how you tell a long loader from a crashed one: if the numbers keep changing, it is still loading; when the drive goes idle the indicator disappears with the LED after a couple of seconds.
  • At startup ASE checks GitHub for a newer release. If there is one, a window comes up with the new version number and its publication date, and two ways out: Update, which opens the download page in your browser — the emulator keeps running, so you can install it whenever it suits you — or Continue, which goes straight to the machine. The emulation stays frozen until you answer. The notice is also printed in the console.
  • That window carries the same Check for updates switch as the “About” box (Help ▸ About), so you can turn the check off without hunting for it in the menus.

5. Floppy disks

Supported image formats

Format Notes
.ST Raw sector image. Geometry is deduced from the file size
.MSA Magic Shadow Archiver image (RLE compressed)
.STX Pasti image. Preserves copy protection: sector timing, fuzzy bits, CRC errors, raw tracks
.ZIP Archive containing any of the above. If the archive holds several images, ASE asks which one to insert; use File ▸ Change disk from ZIP to swap between them later (handy for multi-disk games)

Inserting disks — three ways:

  • File ▸ Open disk image
  • Drag & drop an image file onto the emulator window
  • --floppy=<path> on the command line (the path is also the one stored in the configuration file, so it is kept if you save the settings during the session)

After inserting, ASE offers to reboot: answer Yes if you want to boot from the disk, No to keep the current session (e.g. swapping to disk 2 mid-game).

⚠️ Writes are not persistent. Anything the emulated machine writes to a floppy (game saves, files saved from GEM) only modifies the in-memory copy of the disk; the image file on your PC is never touched. If you need to keep the state of a session, use a snapshot.

6. The game library

The game library turns a folder full of disk images into a browsable, cover-art catalogue. Instead of hunting for files with Open disk image, you open the library, pick a game and boot it. Box art, a screenshot, a short description and even a gameplay video are fetched automatically from ScreenScraper.fr.

Open the browser with File ▸ Library…; set everything up with File ▸ Configure Library….

Setting it up

File ▸ Configure Library… opens the library settings:

  • Library folder — the folder that holds your disk images (.st, .msa, .stx, .zip). ASE also stores the catalogue (Library.json) and the downloaded artwork (a Media sub-folder) here. Can also be set with --library-dir.
  • ScreenScraper user / password — your own free account at screenscraper.fr. Scraping needs one: the site meters how much each account may download per day. The password is stored obfuscated in the configuration file rather than in plain text — this is light protection, not real security, so don't reuse a sensitive password.
  • Download media — when on, the scraper also downloads box art, a title screen, a screenshot and a preview video for each game. Turn it off to fetch just the text metadata.
  • VLC path (Windows only) — the preview videos play through VLC. ASE does not bundle VLC (it is large); it reuses the copy already installed on your PC. Leave this empty to auto-detect a standard C:\Program Files\VideoLAN\VLC install, or point it at a custom location. Without VLC everything else still works — the screenshot is shown in place of the video. On macOS, ASE looks for VLC.app in Applications automatically; on Linux it uses the system's libVLC, so installing your distribution's vlc package is enough. That is why this field only appears on Windows.

Scraping (downloading metadata & artwork)

In the library configuration window click Download Metadata & Artwork. ASE scans every disk image in the library folder and, for each one, looks it up on ScreenScraper and saves the result. A progress window shows the current file; you can Cancel at any time.

Worth knowing:

  • It is incremental. Games already in the catalogue are skipped, so you can drop in a few new disks and re-scan without starting over. If ScreenScraper's daily quota runs out (or you cancel), whatever was downloaded so far is kept — just run it again later.
  • Menu / compilation disks are expanded. Disks from cracking groups (Automation, D-Bug, Pompey Pirates…) that bundle many games behind a menu are recognised by their name (e.g. AU061) and split into their individual titles in the catalogue, each with its own artwork.
  • Progress and any problems are written to a Scraper YYYYMMDD.log file in the library folder.

Recognised menu-disk names

For a menu / compilation disk to be expanded into its individual games, ASE has to know which cracking group it came from and which menu number it is — and it works that out purely from the file name. The name (extension aside) must consist of a group identifier followed by the menu number, and nothing else. For example, Pompey Pirates menu 61 is recognised as PP061.st, POMPEY061.st, Pompey Pirates 061.st or Pompey Pirates Menu 061.st.

Every group can be written in three ways: its two-letter code, its full name (optionally followed by the word Menu), and one or more alternative abbreviations. In the table, xxx is the menu number.

Cracking group Two-letter code Full name Other abbreviations
Automation AUxxx Automation xxx, Automation Menu xxx AUTOxxx
Cynix CYxxx Cynix xxx, Cynix Menu xxx —
D-Bug DBxxx D-Bug xxx, D-Bug Menu xxx DBUGxxx
Electric Mouse EMxxx Electric Mouse xxx, Electric Mouse Menu xxx EMOUSExxx
Flame of Finland FFxxx Flame of Finland xxx, Flame of Finland Menu xxx FOFxxx
Fuzion FZxxx Fuzion xxx, Fuzion Menu xxx —
Medway Boys MBxxx Medway Boys xxx, Medway Boys Menu xxx TMBxxx, MEDWAYxxx
Pompey Pirates PPxxx Pompey Pirates xxx, Pompey Pirates Menu xxx POMPEYxxx
Pompey Pirates (Krappy Compacts) PKxxx — (see note below) PPKxxx, PPKCxxx, KCxxx, KRAPPYxxx
Sewer Doc Disk SDxxx Sewer Doc Disk xxx, Sewer Doc Disk Menu xxx SEWERDOCxxx, SDDxxx
Spaced Out SOxxx Spaced Out xxx, Spaced Out Menu xxx SPACEDxxx, PSOUxxx
SuperGAU GGxxx SuperGAU xxx, SuperGAU Menu xxx SGxxx, SGAUxxx
Superior SUxxx Superior xxx, Superior Menu xxx —
T. E. R. Doc Disk TExxx T. E. R. Doc Disk xxx, T. E. R. Doc Disk Menu xxx TERDOCxxx, TERDDxxx
Vectronix VExxx Vectronix xxx, Vectronix Menu xxx VECTxxx

A few things worth knowing:

  • Case, spaces and separators don't matter. Upper/lower case, spaces, hyphens, dots and underscores are all ignored — so au061.st, AU 061.st, AU-061.st and A.U. 061.st are all the same name.
  • Anything in parentheses is ignored, which is where release info belongs: AU061 (v2).st, Automation Menu 061 (1990) (cracked).st and PP061 (Disk 1).st all match. Note that only (round brackets) are stripped — a [cr] or {1990} comment stays in the name and stops the match.
  • The word Disk is ignored anywhere in the name, so Automation Menu Disk 499.st works as well as Automation Menu 499.st.
  • Everything else in the name must be part of the identifier. The match is on the whole name, not just its beginning: AU061 Rev A.st is not recognised, while AU061 (Rev A).st is.
  • xxx is the menu number exactly as it is catalogued — keep any leading zeros (e.g. 061, not 61).
  • Multi-disk menus carry a trailing letter (A, B, C…): AU100A, AU100B. You can also spell the disk out as (Part A) / (Part B), or as (Disk 1 of 2) / (Disk 2 of 2) — disk 1 → A, disk 2 → B, and so on. So AU100A.st, Automation 100 (Part A).st and Automation Menu 100 (Disk 1 of 2).st all mean the same disk.
  • The word Menu only follows the full group name, never an abbreviation: Automation Menu 061 is recognised, AU Menu 061 is not (use AU061).
  • For the Krappy Compacts use PK or one of its abbreviations. They were released by Pompey Pirates, so writing the group out in full (Pompey Pirates 061) is ambiguous and can pull in the games of the ordinary Pompey Pirates menu with the same number.
  • This naming only matters for menu / compilation disks. An ordinary single-game image is scraped by its plain title and needs no special name.

Browsing and launching

File ▸ Library… opens the browser: a grid of covers (a 💾 icon stands in for games with no cover art).

  • Search — type in the box at the top to filter by title.
  • Move around — hover with the mouse, or use the arrow keys to highlight a game.
  • Details — hover a game and click Details… (or press Space) for a card with the description, a screenshot and a looping gameplay video.
  • Play — click a game (or press Enter on the highlighted one, or use Play in the details card / right-click ▸ Play). The library closes, the disk is inserted and ASE offers to reboot — exactly as if you had used Open disk image.

7. Keyboard, mouse and joysticks

Input capture

Key Action
F12 Capture / release the keyboard and mouse. While captured, the menu is hidden, the host cursor disappears and every key goes to the Atari
Middle mouse button Same as F12: click on the emulator screen to capture / release the keyboard and mouse
F11 Save a machine snapshot to the snapshots directory
Shift+F11 Save a PNG screenshot to the screenshots directory
F10 Step one instruction (inside the debugger)

Keyboard

Keys map to their Atari ST equivalents (letters follow the physical position, so the layout behaves like the original machine). Useful special mappings:

Host key Atari ST key
Home ClrHome
Insert / Delete Insert / Delete
Numpad . Help
Right Ctrl Control
AltGr Alternate

Mouse

Move the host mouse while input is captured (F12 or middle mouse button). Left/right buttons map to the ST mouse buttons. Adjust mouse sensitivity in the Configuration dialog (or --mouse-sensitivity=N).

Joystick on the numeric keypad

Joystick 1 is emulated with the numeric keypad by default:

        8 (up)
4 (left)  5 (down)  6 (right)        0 = fire

The keys can be changed in the configuration file (KeyJoy1Up, KeyJoy1Down, KeyJoy1Left, KeyJoy1Right, KeyJoy1Fire).

Gamepads

Any SDL-compatible game controller is detected automatically, including hot-plugging. The D-pad and left stick steer the joystick; the buttons (A, B, X, Y, LB, RB, LS, RS) can each be mapped in Emulation ▸ Configuration ▸ Joystick to one of:

  • Fire — joystick fire button
  • Space, Y, N, T — those Atari keys (handy for "press space", yes/no prompts or "trainer" without touching the keyboard)
  • Up — joystick up (jump in many platformers)

8. Configuration

Emulation ▸ Configuration has four tabs:

Setup

  • Atari model — STF/FM, STF/FM + Blitter, STE. Changing the model changes the available hardware (blitter, DMA sound, 4096-colour palette, MMU behaviour) and the TOS the machine needs.
  • Memory — 512 KB, 1 MB, 2 MB or 4 MB.
  • TOS image — path to the ROM file. ASE validates that the TOS version matches the selected model.

Changing any of these requires a machine reset; ASE asks for confirmation.

Display

ASE renders through an OpenGL CRT shader that can be tuned live with sliders:

Slider Effect
Curvature Barrel distortion of the tube
Vignette Darkened corners
Scanline Visible scanlines intensity
Aberration Chromatic aberration at the edges
Bloom Glow around bright areas
Mask Phosphor / shadow-mask pattern
Noise Analogue signal noise

If you’re not into the whole CRT emulation thing — or the GPU is struggling — flip the Disable all effects switch: ASE then draws the picture with a plain shader that does no post-processing at all, for a clean, pixel-sharp image. This is faster than sliding every effect down to 0, because at 0 the GPU still runs the full shader for every pixel; it just has nothing to show for it. It makes a real difference on modest hardware such as a Raspberry Pi.

The slider values are remembered while the switch is on (they are simply greyed out), so turning it back off restores your CRT look. The setting can also be passed on the command line as --no-effects and lives in the configuration file as DisableCrtEffects.

Joystick

Mouse sensitivity, the keyboard-joystick summary and the gamepad button mapping described above.

Directories

Default folders used by the emulator:

Directory Used for Default
Screenshots (Shift+F11) Where PNG screenshots are saved Screenshots folder next to the configuration file
Snapshots (F11) Where F11 / File ▸ Save snapshot write their .snap files Snapshots folder next to the configuration file
Disk images Starting folder of the Open disk image dialog none
TOS ROMs Starting folder of the Select TOS image dialog none

Leave the screenshots/snapshots fields empty to go back to the defaults. The first two can also be set from the command line (--screenshots-dir, --snapshots-dir).

9. Snapshots (save states)

A snapshot is a complete photograph of the running machine: CPU registers, RAM, TOS ROM, and the internal state of every chip (video, sound, timers, keyboard, floppy controller, blitter…). Restoring one puts the machine back at that exact instant — including which ST model and how much memory it had, no matter what is currently configured.

Saving: three ways:

  • Press F11 at any moment — no questions asked: the state is written to a timestamped .snap file in the snapshots directory (see Configuration ▸ Directories). The emulation pauses for the instant it takes to write the file.
  • File ▸ Save snapshot in the main window — same as F11.
  • Emulation ▸ Debug ▸ Memory tab ▸ Save snapshot… — lets you pick the file name and location, e.g. to snapshot a precise instruction while stepping.

Restoring: three ways:

  • File ▸ Restore snapshot in the main window
  • ASE --snapshot=<path> on the command line — the emulator powers on directly into the saved state
  • Snapshots also remember which disk images were inserted and re-insert them automatically if the files still exist at the same paths

Good to know:

  • Snapshots include the TOS ROM, so they restore correctly even on a machine configured with a different TOS.
  • The floppy image contents are not stored — only their paths. Keep the disk files around (and unchanged) for a faithful restore.
  • Because floppy writes are memory-only, a snapshot is the reliable way to preserve game saves between sessions.
  • Avoid saving in the middle of a floppy load of a copy-protected (STX) game; the in-flight transfer is completed instantly at save time, which a timing-sensitive protection could notice.

10. Screenshots

Press Shift+F11 to save the current picture as a PNG file, named with a timestamp, in the screenshots directory (default: a Screenshots folder next to the configuration file — change it in Emulation ▸ Configuration ▸ Directories or with --screenshots-dir). The emulation pauses for the instant it takes to write the file, so the capture is exactly the frame you were seeing. The status bar confirms the file name after each capture.

  • The image is the clean emulator output — the CRT shader effects (curvature, scanlines, bloom…) are not applied.
  • The capture follows the ShowBorders setting: with borders on you get the full overscan picture (920×548), with borders off the classic display area (640×400). Scanlines are doubled so the PNG keeps the same aspect ratio as the screen.

11. The debugger

Emulation ▸ Debug opens the debugger and pauses the emulation (it resumes when the window closes). Two tabs:

CPU tab

  • Disassembly listing with the current instruction highlighted.
  • Step (F10) executes one instruction. Back to PC re-centres the listing on the program counter.
  • Go — type a hexadecimal address (with or without $) to disassemble anywhere.
  • Registers — every register (PC, SP, A0–A6, D0–D7) is editable: type a hex value and press Enter. Editing PC correctly refills the CPU prefetch queue.
  • SR flags — checkboxes for T, S, the interrupt mask and X/N/Z/V/C.
  • Breakpoint / Run until breakpoint / Clear breakpoints — see Breakpoints below.

Breakpoints

Breakpoints let you stop the emulated CPU right before a chosen instruction executes, so you can inspect registers and memory at exactly that point. Everything happens from the CPU tab:

  • Set one — click an instruction in the disassembly listing to select it, then click Breakpoint. The line turns red. Click Breakpoint again on the same line to remove it. You can arm as many breakpoints as you want at the same time, anywhere in RAM or ROM.
  • Breakpoints are always active the moment they're set — you don't need to press anything to "start" them. Run until breakpoint (only enabled while at least one breakpoint exists) just closes the Debug window and resumes the machine at full speed; the emulator keeps watching for the armed addresses while you play normally.
  • When a breakpoint is reached, ASE automatically pauses the machine and reopens the Debug window, with the CPU tab centred on the program counter — highlighted in blue — sitting on the guarded instruction, which has not executed yet. From there you can look at registers/memory, Step (F10) through it one instruction at a time, or click Run until breakpoint again to continue (it fires again only the next time execution reaches that same instruction).
  • Clear breakpoints removes every breakpoint at once.
  • Breakpoints are not saved in snapshots and are cleared by a machine reset (Emulation ▸ Reset), so they need to be set again after either.

Memory tab

A full hex editor over the ST address space (RAM, ROM and hardware registers):

000000: 60 2E 30 39 00 04 00 06  46 FC 27 00 4E F9 00 FC |`.09....F.'.N...|
Action How
Move around Arrow keys, PageUp/PageDown, Home/End, mouse wheel, click on a byte
Jump to an address Type it in the address box and press Enter ($ optional)
Go to start / end of memory Ctrl+Home / Ctrl+End
Edit as hex Click a byte in the hex columns and type hex digits
Edit as text Click a character in the ASCII column and type; each character writes one byte
Switch hex ↔ ASCII editing Tab

Only RAM is writable; ROM and the I/O area are read-only in the editor (and reads never trigger hardware side effects, so it is always safe to browse). The status line shows the address and value under the cursor.

Save snapshot… lives on this tab — see Snapshots.

12. Command-line options

ASE [options]

ASE --help (or -h) prints the same list, grouped as below, and exits without starting the machine. An unrecognised option does the same, naming the offending one first — a typo never becomes a silent misconfiguration.

Options written [=true|false] also work bare, in which case they mean true (--no-effects = --no-effects=true). Those written =true|false need the value spelled out: a bare --maxspeed changes nothing.

Machine

Option Description
--tos=<path> TOS ROM image (192 KB for ST/Mega, 256 KB for STE), overriding the configured one
--altconfig=<path> Load this configuration file instead of the default one
--maxspeed=true|false Run as fast as the host allows instead of at original ST speed

Media and directories

Option Description
--floppy=<path> Start with a disk image (.st/.msa/.stx/.zip) in drive A
--snapshot=<path> Restore a machine snapshot (.snap) on startup
--library-dir=<path> Folder of the game library (disk images + Library.json)
--snapshots-dir=<path> Where F11 saves machine snapshots
--screenshots-dir=<path> Where Shift+F11 saves PNG screenshots

Display and input

Option Description
--no-effects[=true|false] Bypass the CRT shader and draw with a plain one — faster on weak GPUs
--mouse-sensitivity=N Mouse sensitivity, e.g. 2.5 (default: 2)

Timing (advanced)

Option Description
--cycleexact[=true|false] Cycle-exact bus wait states (default: on)
--busphase=N Phase of the 4-cycle MMU bus grid, 0–3 (default: 0)
--mfpwait=N Extra wait cycles per MFP register access (default: 4)

Diagnostics

Option Description
--debug[=level] Console verbosity: none, quiet, information, full (bare --debug = full)
--profile[=N] Print a per-frame timing breakdown every N frames (default: 50)
--help, -h Show the options summary and exit

Worth knowing:

  • Arguments are applied in the order you write them, and --altconfig replaces the whole configuration loaded so far. Put it first: anything set before it is lost.
  • Command-line values override the configuration file for that session only. They end up written to disk only if you save settings from one of the emulator's dialogs while it is running.
  • --snapshot is a launch-only argument and is never persisted.

12.1 Measuring performance (--profile)

If the emulator stutters, --profile tells you whether the machine is short of CPU or the picture simply is not being presented evenly. It prints one line with the averages over the last N frames (--profile=N, default 50 — about one line per second):

[Profile] 50 frames | work 6.16/20.0 ms (31%, max 6.88) | cpu 4.55 video 1.46 input 0.12 publish 0.00 other 0.03 | idle 13.79 | late 0 | GL 0.09 ms (tex 0.11 on 50/143), 143.4 fps
Field Meaning
work What emulating one frame costs, against the 20 ms budget of a 50 Hz PAL frame, with the percentage and the worst frame of the batch
cpu The 68000 and the chips it drives (MFP, PSG, FDC, blitter…)
video Resolving each scanline and drawing it into the framebuffer
input Draining the SDL event queue (keyboard, mouse, gamepad)
publish Handing the finished frame to the renderer (a buffer swap, so it reads as 0.00)
other Everything else in the frame loop
idle What was left of the 20 ms after the work was done
late Frames of the batch that went over budget — the direct measure of dropped frames
GL CPU time per presented frame, of which tex is the texture upload, and the rate at which frames reach the screen. on 50/143 means 50 of the 143 drawn frames carried a new emulated frame; the rest redraw the texture as it is, so tex is the cost of one real upload

Reading it:

  • work near 20 ms, idle near zero, late climbing — the host cannot keep up. The split tells you where the time goes.
  • Plenty of idle but the picture still stutters — the emulation is fine and the problem is presentation. Note that 50 Hz emulation on a 60 Hz screen judders by construction, however much headroom there is.
  • cpu takes most of work and there is nothing left — this is the one knob with real reach: CpuSyncSliceCycles in the configuration file. Raising it from the default 4 to 16 cut cpu by about 15% on my machine, and 64 by about 30%. The cost is coarser timer interrupts, so start at 16 and go back to 4 if a demo or game that depends on fine timing misbehaves.
  • GL frame rate well below the rest — the CRT effects are too much for the GPU. The cheapest fix is the Disable all effects switch (or --no-effects), which bypasses the shader entirely; turning individual sliders down helps far less, since the shader runs whole regardless of the values. The GPU works asynchronously, so an expensive shader shows up as a lower frame rate, not as a longer render time.

Measuring is not free: while enabled the profiler reads the clock about 60,000 times per second (well under 1% even on a Raspberry Pi), and that cost is included in the numbers it prints. With the option absent no clock is read at all.

13. The configuration file

Settings persist in a JSON file:

Platform Location
Windows %APPDATA%\ASE\config.json
macOS / Linux ~/.config/ASE/config.json

Everything in the Configuration dialog is stored there, plus a few options that have no UI yet:

Key Default Meaning
MaxSpeed false Uncapped emulation speed
ShowBorders true Show the screen borders (overscan area) around the 320×200 display. Set to false to crop to the classic picture
DisableCrtEffects false Bypass the CRT shader (plain blit). Same as the Disable all effects switch and --no-effects
CycleExactBus true Cycle-exact memory wait states. Needed by demos and games with cycle-counted raster code (e.g. Spectrum 512 pictures); costs a little performance
CpuSyncSliceCycles 4 CPU/peripheral interleave granularity in cycles. 4 = maximum compatibility, higher = faster but coarser timers (16 ≈ 15% less CPU time, 64 ≈ 30%). The first thing to try on a slow host
SampleRate 44100 Audio output sample rate
KeyJoy1Up/Down/Left/Right/Fire numpad 8/5/4/6/0 SDL scancodes for the keyboard joystick
DebugMode none Console verbosity (same values as --debug)

The file is plain JSON — edit it with the emulator closed, or use --altconfig to keep several machine setups side by side (e.g. one for ST games, one for STE demos).

⚠️ Saving settings always writes the default config.json, even in a session started with --altconfig: the alternative file is read, never written. To change one of those setups, edit its file directly.

14. Troubleshooting

"TOS file … not found" and the emulator exits — the configured TOS path is wrong. Fix it in Emulation ▸ Configuration or pass --tos=<path>.

Black screen / machine doesn't boot after changing model — the TOS version must match the model: 1.00–1.04 for STF/Mega, 1.06–2.06 for STE. ASE validates this when you select the file, but a stale path in the config can slip through.

Keys or mouse "don't work" — you probably haven't captured input: press F12. Conversely, if your menu disappeared, press F12 to release capture.

The game doesn't see the joystick — many games read the joystick only after switching the IKBD to joystick mode. Use the numeric keypad (or a gamepad) and make sure input is captured. Remember that in mouse mode the fire button doubles as the right mouse button — that is how the real hardware behaves.

A game/demo shows glitched rasters or drifting colour bars — make sure CycleExactBus is on (it is by default) and CpuSyncSliceCycles is 4.

I saved a game to disk but the file is gone next session — floppy writes are never written back to the image file. Save a snapshot instead.

"Could not restore snapshot" — the .snap file is corrupt or from an incompatible version. If the snapshot references disk images that were moved, the machine state still restores, but re-insert the disk manually before it is accessed.

Multi-disk game asks for disk 2 — if the disks came in one ZIP, use File ▸ Change disk from ZIP; otherwise insert the second image and answer No to the reboot question.

The screen has been black for a while — is it still loading? — watch the status bar: while the floppy is being read, the drive LED is lit and the activity indicator next to it (A: T12 S05) keeps changing track/sector. If it stops changing and the LED goes off, the program is no longer reading the disk.

On macOS: “ASE is damaged and can’t be opened”, or “Apple could not verify…” — the app has no Apple developer signature, so macOS quarantines it on download. Authorize it once as described in Installing on macOS, or remove the quarantine attribute with xattr -dr com.apple.quarantine /Applications/ASE.app.

On Linux ASE exits saying SDL2 (or libSDL2.so) was not found — SDL2 is not bundled on Linux. Install your distribution's runtime package (libsdl2-2.0-0, SDL2, sdl2…), see Installing on Linux.

On Linux nothing responds — no keyboard, no mouse, no gamepad — ASE needs the X11 video driver (through XWayland inside a Wayland session). Check that you have not forced SDL_VIDEODRIVER=wayland in your environment: an explicit value always wins over the one ASE selects.

On macOS the file dialogs show every file type — this is intentional: macOS refuses to enable files whose extension has no registered type (.st, .msa, .stx, .snap would show up greyed out and unselectable if filtered), so ASE disables the extension filter there. Just pick the right file.

Manual for ASE 1.x — The Bit Culture.

Clone this wiki locally