Handbook

Amiga Imager v0.94

Current handbook for Amiga Imager v0.94. This guide was checked against the shipped 0.94 / 260621 build and explains the new all-native build-engine baseline for the current release.

Download v0.94 Back to downloads
  • Verified against build 260621
  • English reference guide
  • Current for the v0.94 release
Back to downloads

What this handbook covers

This is the current public handbook for Amiga Imager v0.94. It focuses on the day-to-day build workflow, the main platform targets, current media-writing behavior, and what changed now that the all-native build engine is the normal path for standard builds.

What the app does

Amiga Imager is a native macOS app for building, managing, and writing bootable Amiga systems from one workflow.

  • PiStorm / Emu68 and Classic Amiga builds are written as .img files.
  • Emulator and MiSTer builds are written as .hdf files.
  • Finished images can be written directly to SD, CF, SSD, or USB media from the app.
  • Amiga File Manager lets you browse images and supported Amiga media directly on macOS.
  • Greaseweazle remains the current native floppy workflow on macOS.
  • v0.94 makes the native build engine the main release story across PiStorm, Classic, UAE, Amiberry, and MiSTer standard workflows.

Before you start

For a normal build you should have these items ready:

  • a Mac running macOS 14 Sonoma or later
  • a valid Kickstart ROM
  • matching AmigaOS installation media
  • a destination SD, CF, SSD, or USB device if you plan to write the image immediately
  • internet access for optional package downloads

Media expectations still depend on the AmigaOS version you select:

  • AmigaOS 3.1 / 3.1.4: ADF source folder
  • AmigaOS 3.2.x: ADF source folder or 3.2 CD ISO
  • AmigaOS 3.9: CD ISO plus Boing Bag 1 and Boing Bag 2

The main workflows

Build bootable image

This is still the main mode. Choose a target platform, provide your OS media and ROM, adjust optional software and hardware settings, review the Build Summary, then generate a ready-to-use disk image.

Build & Write to Card

When you want to go straight from settings to real media, use the direct write workflow. The app builds the image and writes it to the selected target without a separate export step, while avoiding unnecessary writes to empty space where possible.

Flash existing image

This mode writes an already built image to removable media. Choose the image file, choose the target disk, keep Only show external disks enabled if needed, then click Write to Disk.

How the current build workflow works

1. Choose the basic inputs

  • Select Target platform: PiStorm / Emu68, Classic Amiga, or Emulator / MiSTer.
  • Choose AmigaOS version. If possible, keep it on Auto and use Check Media to verify what the app found.
  • Provide an ADF source, an ISO, or both, depending on the OS version.
  • Select your Amiga ROM.
  • Choose the output image path or your direct-write target.

2. Decide whether to stay in Simple or switch to Advanced

Simple remains the fastest route and applies safe defaults for a first build. Advanced is where the full app lives: custom hardware choices, manual Roadshow or Picasso96 archives, transfer folders, custom packages by URL, WBDock selection, custom image sizing, and profile save/load.

3. Work through the build cards

The current cards are still centered on Input, Configuration, Optional Software, and Image & Build. The difference in v0.94 is less about visible UI changes and more about what happens under the hood when you actually start the build.

How the native engine works in v0.94

The important architectural change in v0.94 is that standard builds now run through the app's in-process Swift engine instead of relying on the older script-heavy path for the main work.

  • The app resolves the plan first - platform choice, image sizing, partition layout, packages, and required assets are all validated before the heavy work starts.
  • The native engine owns the mainstream build path - for standard PiStorm, Classic, UAE, Amiberry, and MiSTer workflows, image creation now runs inside the app process.
  • AmigaDiskKit does the low-level disk work - it now covers more of the real path for RDB, FFS, PFS3, ADF, LHA, and the PiStorm FAT32 boot volume workflow.
  • Fewer handoffs means clearer builds - there is less glue between shell scripts, external helpers, and the native UI, which makes verification easier and the architecture more predictable.
  • Fallback still exists where it makes sense - excluded or legacy edge cases can still stay on the older path, but the normal release story is now the native engine.

In practical terms, the current release candidate is the point where the native engine stops feeling like an experiment and starts feeling like the main product foundation.

Platform notes for v0.94

PiStorm / Emu68

  • Builds use an .img output file.
  • v0.94 continues the fully native PiStorm path, including RDB, FFS, PFS3, and the FAT32 boot-partition workflow.
  • FrameThrower, Wi-Fi, and current PiStorm-specific settings still live in the normal configuration flow.
  • The legacy disk-engine path remains useful only as a fallback or comparison tool.

Classic Amiga

  • Classic builds also use .img.
  • Current RTG and NIC choices remain available through the Advanced hardware selectors.
  • The important change in v0.94 is that Classic standard builds now sit on the same native build-engine baseline instead of feeling like a separate scripting path.

Emulator and MiSTer

  • Emulator and MiSTer builds use .hdf.
  • UAE and Amiberry are confirmed tested and working.
  • MiSTer is also confirmed with RTG support.
  • v0.94 keeps the emulator-family builds on the same native-engine foundation as the other supported targets.

Floppy workflows in the current release candidate

Greaseweazle remains the current native floppy path on macOS and the supported route for working with physical Amiga floppies today.

  • read real disks to .adf
  • write .adf files back to disk
  • browse floppy contents from the native macOS workflow

DrawBridge is now present as an experimental path alongside Greaseweazle. The important current caveat is that real-hardware validation is still needed for the DrawBridge command bytes and 2-bit cell mapping before physical reads should be treated as trustworthy.

Settings window (Cmd+,)

The current app still has separate settings panes for Build, Storage, PiStorm, Classic, and Debug.

  • Build: general build behavior, asset paths, exposure settings, and custom package definitions
  • Storage: image-size reduction presets so generated media fits real cards and disks more reliably
  • PiStorm: boot-bundle source, prerelease behavior, and other PiStorm-specific settings
  • Classic: Classic hardware helpers such as A314-related behavior
  • Debug: diagnostics and legacy comparison behavior for engine work

Troubleshooting

The build cannot start

The most common causes are still missing install media, missing Kickstart ROM, no output path, or incomplete AmigaOS 3.9 extras.

The build falls back to older behavior

If you are testing unusual media combinations or legacy paths, the app may still rely on fallback behavior for excluded cases. That does not mean the native engine is disabled for standard builds.

Writing to disk fails on macOS

Enable Full Disk Access for Amiga Imager in System Settings -> Privacy & Security -> Full Disk Access, then retry. Replugging the target device can also help.

A314 does not work

Make sure the network stack is set to Roadshow Demo or Roadshow Full. A314 is not supported with None.

A custom package does not install

Check the package name and direct download URL in Settings -> Build -> Custom Packages. The file should be a valid archive the current build pipeline can unpack, ideally an .lha package.

You need help diagnosing a problem

Use Export Log after the failure and keep the build-summary details. With the native engine, the log is even more useful because more of the real build path now runs inside one coherent system.