FS-UAE Amiga Emulator

Documentation

Paths and directories

By default, FS-UAE creates a number of directories in Documents/FS-UAE to store the files used by FS-UAE: CD-ROMs, Configurations, Controllers, Flash Memory, Floppies, Floppy Overlays, Hard Drives, Kickstarts, Logs, Save States.

In addition, if you use FS-UAE Launcher, it will create some directories of its own. The following directories can be used by FS-UAE and/or the Launcher if found in Documents/FS-UAE: Covers, Screenshots, Titles, Themes.

See "Specifying Paths in Configuration Files" in Configuration Files instead if you are looking for information about the different ways of referring to directories and files in FS-UAE.

Base directory

By default, FS-UAE creates its directories under Documents/FS-UAE. For Linux users: If your Documents directory is not configured according to the XDG user dir spec, $HOME/FS-UAE will be used as a fallback.

From FS-UAE 3.1.57 and onwards, $HOME/FS-UAE will automatically be used if it exists.

You can override this by putting the path to the desired base directory in a special config file. The config file will be read by both FS-UAE and FS-UAE Launcher if it exists:

Windows: <LOCALAPPDATA>/FS-UAE/base-dir
OS X: ~/Library/Preferences/fs-uae/base-dir
Linux/other: ~/.config/fs-uae/base-dir

This file must be a simple text file with (only) the full path to the desired base directory.

Note: For windows users, the most common location of this config file C:\Users\[username]\AppData\Local\FS-UAE\base-dir. Also make sure that when you create this file, that it isn't created as base-dir.txt (which won't) work - a common problem if you use Notepad or similar. It is a good idea to, temporarily or permanently, change Explorer settings to show file extension for all files.

Alternatively, you can starting FS-UAE and/or FS-UAE Launcher with --base-dir=/path/to/desired/dir.

A final option to avoid all this is to simply use the portable version of FS-UAE. With a portable setup, both the application and data files are placed together in the same directory, and you can move this directory around at will, even between computers.

Media directories

The following directories are created as default locations to hold your Amiga media:

  • CD-ROMs
  • Floppies
  • Hard Drives

The location and names of these directories can be overridden with the following options in config files: cdroms_dir, floppies_dir, hard_drives_dir.

You do not have to store your Amiga files here, but when media are located in one of these directories (or a sub-directory), you can refer to contained files without using full paths. For example a floppy image file called Lotus2.adf stored in the Floppies directory can be inserted into the first floppy drive with this option:

floppy_drive_0 = Lotus2.adf

If the file is located outside the Floppies directory, you must instead use an absolute path or one of the other ways to specify paths.

Referring to directories

Paths in configuration files can be specified as either:

  • Relative paths
  • Absolute paths
  • Paths beginning with special variables

Note: On Windows, you must either use forward slashes in paths in configuration files, or you must use double backslashes. Example: C:/Amiga/Files and C:\\Amiga\\Files are both correct, but C:\Amiga\Files is not!

Relative paths will be looked up relative to either the current directory, or (more often) relative to a relevant default directory. For example, relative floppy image paths will be looked up relative to the Floppies directory.

Absolute paths are paths beginning with a drive letter (Windows), or a slash (Linux, Mac OS X, FreeBSD).

To avoid having to use absolute paths, and to make configuration files more portable, you can prefix paths with some special variables (Note: these are not environment variables, though $HOME looks like one):

  • $CONFIG – The directory containing the loaded configuration file.
  • $APP – On Mac OS X, the directory containing the currently running FS-UAE.app, on other platforms, it is he same as $EXE. This means that $APP should normally be preferred over EXE for portability.
  • $EXE – The directory containing the currently running FS-UAE executable.
  • $HOME – The user's home directory.
  • $DOCUMENTS – The user’s documents directory.
  • $BASE – The FS-UAE base directory, usually Documents/FS-UAE, or the root of the portable directory if using the portable version.

FIXME: CONFIG, APP, EXE should perhaps be renamed to CONFIGDIR, APPDIR, EXEDIR instead. Also, is EXE/EXEDIR really needed? Path to the exe inside the app bundle isn't often useful (only in same cases with bundled configs) inside the app, so maybe make a special name for that instead.

Take note that if you are specifying these prefixes as command line arguments, you must take care to avoid the shell replacing them with environment variables. Either escape the $ with \$ or use single quotes around the path to prevent environment variable expansion.

Covers, screenshots and titles for FS-UAE Launcher

See the FS-UAE Launcher page for information about the structure of the following directories:

  • Covers (front covers of game boxes)
  • Screenshots
  • Titles (Screenshot of the game title screen)

Note: Paths for covers (etc) are subject to change for FS-UAE Launcher 4.0.