FS-UAE README

Note: Please note that the information in this file is probably slightly outdated. It should be update before the release of FS-UAE 4.0.

FS-UAE is an Amiga emulator for Windows, Linux and Mac OS X based on UAE/WinUAE, with a focus on emulating games.

Features include emulation of Amiga 500, 1200, 4000, CD32 and CDTV, perfectly smooth scrolling on 50Hz displays, support for floppy images in ADF and IPF formats, CD-ROM images in ISO or BIN/CUE format, mounting folders on your computer as Amiga hard drives, support for Picasso 96 drivers for high-color and high-resolution Workbench displays, and more...

A unique feature is support for cross-platform online play. You can now play Amiga games against (or with) friends over the Internet.

The emulator uses the latest Amiga emulation code from the WinUAE project and requires a moderately fast computer with accelerated graphics (OpenGL) to work. A game pad or joystick is recommended, but not required (FS-UAE can emulate a joystick using the cursor keys and right ctrl/alt keys).

The official home page of FS-UAE is https://fs-uae.net/

Thank you for your interest in FS-UAE :)

Important information

FS-UAE itself does not include a configuration UI, so you must either:

• Run FS-UAE via the configuration program FS-UAE Launcher.
• Create a configuration file before the emulator will be usable. This is fairly easy, please read on for more information.
• Run FS-UAE from a third-party configuration interface / frontend.

Please report any errors found in the documentation to [email protected].

Configuration file

You will also need to create a configuration file for FS-UAE. The important things you need to configure is what floppy disks to use, and where the Kickstart ROMs are stored. Documentation (and examples) is available here: https://fs-uae.net/documentation

You have several options for where to store the configuration file:

1. In the same directory as the FS-UAE executable, as Config.fs-uae. FS-UAE will always try to load this file first.
2. As a per-user configuration file: (My) Documents/FS-UAE/Configurations/Default.fs-uae
3. You can also store the file anywhere you want, and invoke FS-UAE with the config file as a parameter (fs-uae /path/to/config-file.fs-uae)
4. In graphical shells (Windows Explorer, Mac OS Finder), you can also select a configuration file, and then choose to open it in FS-UAE (you may need to browse to find the program), or you may also drag and drop a configuration file in top of the FS-UAE application/executable.

(you can see in the log file exactly what path FS-UAE tries to load the default configuration from on your system)

Kickstart

You will need Kickstart ROMs for the Amigas you want to emulate for best compatibility. One source for this is your real Amiga, but you can also purchase the Kickstart ROMs in file format from Cloanto - they are bundled with their Amiga Forever product. See [docs/kickstarts.md] for more information about kickstarts and the kickstart replacement included in FS-UAE.

Joysticks

If you have a recognized joystick connected, FS-UAE will automatically try to use this as the primary Amiga joystick. Otherwise, keyboard joystick emulation will be enabled, where the cursor keys and the right control (right alt on Mac) on your keyboard controls the joystick.

FS-UAE does not (currently) support two keyboard-emulated joysticks. If you want to use two Amiga joysticks, you need to have at least one real joystick or gamepad.

You can specify which joystick to use for each Amiga joystick port in the configuration file, and you can also change this during runtime from the FS-UAE menu.

If your joystick is not correctly configurated automatically by FS-UAE, you can create a configuration file for it, or use FS-UAE Launcher to do this for you with an easy-to-use GUI.

Emulator menu

While running the emulator, you press F12 to enter and exit the emulator menu. From here, you can load and save states, and swap floppy disks. On macOS, you can use Cmd+F12 instead (Or Fn+Cmd+F12).

With gamepads, you enter the menu either by using the dedicated "menu" button, if the gamepad has one, or you press and hold "start" and "selected" at the same time (or equivalent buttons). Use the same key/button to close the menu.

In the menu, you use the following keys for navigation:

• Cursor keys
• Enter (choose item, enter sub-menu)
• Back-space (leave sub-menu)

On the game pad, you can use either the hat or the primary analog stick for navigation. You choose items and enter sub-menus with the "primary" button on the game pad. This is generally the "south" button on the right side of the controller. The back button is the "east" button (Just like you would navigate on the Xbox).

Screenshots

Press the "Print Scrn" key on the keyboard to save a screenshot of the running game to the desktop. Alternatively, you can use F12+s if you don't have this key.

Keyboard shortcuts

See [docs/keyboard.md] for a complete list of shortcuts as well as instructions on how to configure shortcuts for additional actions. Here are some of the most important ones:

• F12 (or Cmd+F12) -Enter/exit GUI.
• Alt+Q / Cmd+Q or F12+g – quit FS-UAE.
• Alt+G / Cmd+G, F12+g or Middle mouse click – release input grab.
• Alt+Tab / Cmd+Tab – switch to another window and release input grab.
• Alt+Enter / Cmd+Enter or F12+g – toggle fullscreen mode.

Remember that on some computers, you also need to press the Fn key to use the F12 key.

Program arguments

<path>: Use a custom configuration file instead of Default.fs-uae

Some options commonly used as program arguments:

--fullscreen: Start in fullscreen mode instead of windowed mode --stdout: Also log to stdout (not on Windows)

You can also specify any configuration option with --option=value. Underscores in the option name can be replaced with hyphens (e.g --floppy-drive-0=/path/to/adf).

Log file and bug reports

A log file is stored as Documents/FS-UAE/Cache/Logs/FS-UAE.log.

When reporting a problem, you should include this log file with you error report.

Floppy disks

New data is always saved to overlay ADF files (.sdf). As an example, if you have floppy.adf insert into df0 and the Amiga writes to df0, the data is written to floppy.sdf instead of modifying floppy.adf itself. You need both floppy.adf and floppy.sdf to represent the entire modified disk. The save files are created on demand (when data is written to a drive).

The floppy file overlays are by default save in the directory (My) Documents/FS-UAE/Floppy Overlays

The GUI does not allow you to browse for files on the file system. Disks can be inserted at startup time (specified in the configuration file), and FS-UAE maintains a list of available floppy images to insert (also specified in the configuration file). See example.conf for more information.

Supported Amiga models

The following Amiga models are supported:

• A1000 - Amiga 1000
• A500 - Amiga 500 (Default)
• A500+ - Amiga 500+
• A600 - Amiga 600
• A1200 - Amiga 1200
• A1200/020 Amiga 1200 with full 68020 CPU
• A4000/040 Amiga 4000 with 68040 CPU
• CD32 - Amiga CD32
• CDTV - Commodore CDTV

The default configurations corresponds to the quickstarts in WinUAE for these systems, on the most compatible setting (cycle-exact mode).

Display refresh rate and resolution

For really smooth scrolling in games, your display MUST run at the same refresh rate as the Amiga: 50Hz (PAL). Many monitors and TVs with 1920x1080 resolution supports this refresh rate. If FS-UAE detects that you display is running at 50Hz, vsync will automatically be enabled for perfect scrolling.

FS-UAE will (not yet) on its own change your refresh rate to 50Hz -you must do this yourself before starting FS-UAE.

If you run your display with another refresh rate, the emulator will still work just fine, but scrolling will be somewhat jerky -it varies with games whether this is very noticable or not.

Note: On Mac OS X, FS-UAE does not currently detect the refresh rate, which means that full vsync will not be enabled. If you are running at 50Hz, you can force vsync with --video-sync=full

FS-UAE will use whatever full-screen resolution you desktop is using, and will assume that you have square pixels. The Amiga image will be scaled to fit the display, and you can choose whether to stretch to fill the entire screen, or scale up while maintaining the original aspect ratio.

Supported host operating systems

FS-UAE can be compiled for the following operating systems:

• Linux
• Windows XP or newer
• Mac OS X 10.6 or newer
• FreeBSD (Other Unices will probably also work just fine)

See docs/compiling.md for building instructions.

The official FS-UAE binaries may require newer versions of these operating systems.

Debugging support

FS-UAE does not include a graphical debugger for debugging Amiga programs. It is possible to use the internal UAE debugger from the console.

For debugging FS-UAE itself, a native debugger can be used if you compile FS-UAE yourself. Other debug information can be retrieved from the log file.

There is debug overlay to debug video, audio and vsync issues. You can toggle the display of this with CTRL+F10.

FS-UAE automatically crops the Amiga video output. Sometimes this does not work perfectly. You can override this behaviour in the configuration file. Also, you can press CTRL+F11 when running to visually see the entire amiga output with the crop rectangle.

Known issues

Amiga mouse must currently be emulated with a native mouse device. A nice feature would be to be able to emulate the mouse with gamepads - analogue controls for instance.

An on-screen keyboard, controllable with a game pad / joystick would also be nice, and is planned for a future version.

Floppy list UI does not support scrolling, so if you have many floppy images in the floppy list, some may be obscured.

Copyright and credits

FS-UAE is Copyright (c) 2011-2021, Frode Solheim Large portions are copyrighted by other individuals.

FS-UAE is based on the fantastic work of the original UAE authors, the authors of WinUAE, contributions from external contributors as well as some code from E-UAE (and maybe P-UAE). See https://fs-uae.net/contributions for an updated list of people having contributed patches, translations and donations.

UAE was created by Bernd Schmidt, with the help of a host of volunteer contributors (see the UAE distribution for full credits).

WinUAE has been developed and maintained by Mathias Ortmann and Toni Wilen. Toni Wilen has developed WinUAE for the last years and is the current maintainer. E-UAE was developed by Richard Drummond (no longer maintained), and P-UAE was developed by Mustafa "GnoStiC" TUFAN (no longer maintained).

The libfsemu library is Copyright (c) 2011-2019, Frode Solheim

The IPF decoder library is Copyright (c) 2001-2011 by István Fábián with additional work by Christian Sauer.

Some relevant links:

• http://www.winuae.net/
• http://www.rcdrummond.net/uae/
• http://www.softpres.org/