fs-uae: A C++ repository from puckipedia

# 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 frode@fs-uae.net.

## 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/
puckipedia/fs-uae
