Home

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.

Official repository 👉 https://github.com/thebitculture/ase
The Bit Culture on YouTube 👉 https://youtube.com/@thebitculture

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.

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.

2. Requirements

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

Native libraries

The release packages already include the two native libraries ASE uses: SDL2 (audio and game controllers) and moira (the 68000 core). If you build from source, they must be present in the application folder — see the repository's build instructions.

3. Quick start

Start ASE. On first run a default configuration file is created.
Open Emulation ▸ Configuration, pick your Atari model, memory size and select your TOS image file, then close the dialog. The emulator resets and boots into the GEM desktop.
Insert a disk with File ▸ Open disk image (or just drag & drop an .st, .msa, .stx or .zip file onto the window). When asked "Reboot?", answer Yes so TOS boots from the new disk.
Click inside the emulator screen and press F12 to capture the keyboard and mouse. Press F12 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 (hidden while input is captured)
│                                               │
│                emulated screen                │
│                                               │
├───────────────────────────────────────────────┤
│ status messages               A: T12 S05 [led]│  ← status bar + drive activity + LED
└───────────────────────────────────────────────┘

File — open/change/eject disk images, save/restore snapshots, 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 and prints a notice in the console if one exists.

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 (also remembered in the configuration file)

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. 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
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). 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 pausing without touching the keyboard)
Up — joystick up (jump in many platformers)

7. 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

Set everything to 0 for a clean, pixel-sharp picture.

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).

8. 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.

9. 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.

10. 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.

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.

11. Command-line options

ASE [options]

Option	Description
`--tos=<path>`	Use this TOS ROM (overrides the configured one)
`--floppy=<image>`	Start with a floppy image inserted in drive A
`--snapshot=<path>`	Restore a machine snapshot (`.snap`) on startup
`--snapshots-dir=<path>`	Directory where F11 saves machine snapshots
`--screenshots-dir=<path>`	Directory where Shift+F11 saves PNG screenshots
`--altconfig=<path>`	Load an alternative configuration file instead of the default one
`--maxspeed=true\|false`	Run as fast as the host allows instead of original ST speed
`--mouse-sensitivity=N`	Mouse sensitivity (e.g. `2.5`)
`--debug[=level]`	Console verbosity: `none`, `quiet`, `information`, `full` (bare `--debug` = full)
`--cycleexact[=true\|false]`	Cycle-exact bus timing (wait states). On by default
`--busphase=N`	Advanced: phase of the 4-cycle memory bus grid (0–3)
`--mfpwait=N`	Advanced: extra wait cycles for MFP register access
`--help`, `-h`	Show the options summary

12. 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
`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 = slightly faster but coarser timers
`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).

13. 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 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. Corrections and improvements are welcome via pull request.

Navigation Menu