1FS-UAE README 2============= 3 4FS-UAE is an Amiga emulator for Windows, Linux and Mac OS X based on 5UAE/WinUAE, with a focus on emulating games. 6 7Features include emulation of Amiga 500, 1200, 4000, CD32 and CDTV, 8perfectly smooth scrolling on 50Hz displays, support for floppy images in 9ADF and IPF formats, CD-ROM images in ISO or BIN/CUE format, mounting folders 10on your computer as Amiga hard drives, support for Picasso 96 drivers for 11high-color and high-resolution Workbench displays, and more... 12 13A unique feature is support for cross-platform online play. You can now play 14Amiga games against (or with) friends over the Internet. 15 16The emulator uses the latest Amiga emulation code from the WinUAE project 17and requires a moderately fast computer with accelerated graphics (OpenGL) 18to work. A game pad or joystick is recommended, but not required (FS-UAE 19can emulate a joystick using the cursor keys and right ctrl/alt keys). 20 21The official home page of FS-UAE is: 22http://fs-uae.net/ 23 24Thank you for your interest in FS-UAE :) 25 26 27IMPORTANT INFORMATION 28===================== 29FS-UAE itself does not include a configuration UI, so you must either: 30* Run FS-UAE via the configuration program FS-UAE Launcher. 31* Create a configuration file before the emulator will be usable. This is 32 fairly easy, please read on for more information. 33* Run FS-UAE from a third-party configuration interface / frontend. 34 35Please report any errors found in the documentation to frode@fs-uae.net. 36 37 38CONFIGURATION FILE 39================== 40You will also need to create a configuration file for FS-UAE. The important 41things you need to configure is what floppy disks to use, and where the 42Kickstart ROMs are stored. Documentation (and examples) is available here: 43http://fs-uae.net/documentation 44 45You have several options for where to store the configuration file: 46 471. In the same directory as the FS-UAE executable, as Config.fs-uae. FS-UAE 48will always try to load this file first. 49 502. As a per-user configuration file: 51(My) Documents/FS-UAE/Configurations/Default.fs-uae 52 533. You can also store the file anywhere you want, and invoke FS-UAE with 54the config file as a parameter (fs-uae /path/to/config-file.fs-uae) 55 564. In graphical shells (Windows Explorer, Mac OS Finder), you can also 57select a configuration file, and then choose to open it in FS-UAE (you 58may need to browse to find the program), or you may also drag and drop 59a configuration file in top of the FS-UAE application/executable. 60 61(you can see in the log file exactly what path FS-UAE tries to load the 62default configuration from on your system) 63 64 65KICKSTART 66========= 67You will need Kickstart ROMs for the Amigas you want to emulate. One source 68for this is your real Amiga, but you can also purchase the Kickstart ROMs 69in file format from Cloanto - they are bundled with their Amiga Forever 70product. 71 72 73JOYSTICKS 74========= 75If you have a recognized joystick connected, FS-UAE will automatically try 76to use this as the primary Amiga joystick. Otherwise, keyboard joystick 77emulation will be enabled, where the cursor keys and the right control (right 78alt on Mac) on your keyboard controls the joystick. 79 80FS-UAE does not (currently) support two keyboard-emulated joysticks. If you 81want to use two Amiga joysticks, you need to have at least one real joystick 82or gamepad. 83 84You can specify which joystick to use for each Amiga joystick port in the 85configuration file, and you can also change this during runtime from the 86FS-UAE menu. 87Information about supported controllers here: 88http://fs-uae.net/controllers 89 90If your joystick is not recognized by FS-UAE (you can see this in the log 91file), you can create a configuration file for it. See 92http://fs-uae.net/custom-controller-configuration 93 94If you create a configuration file, I would appreciate it if you would 95send a copy to frode@fs-uae.net with the producer and model name of 96the joystick/gamepad (for inclusing in future versions of FS-UAE). 97 98 99EMULATOR MENU 100============= 101While running the emulator, you press F12 to enter and exit the emulator menu. 102From here, you can load and save states, and swap floppy disks. On Mac OS X, 103you can use Cmd+F12 instead (Possibly even Fn+Cmd+F12). 104 105With gamepads, you enter the menu either by using the dedicated "menu" button, 106if the gamepad has one, or you press and hold "start" and "selected" at the 107same time (or equivalent buttons). 108 109You use the same key/button to dismiss the menu. 110 111By default, the emulator will continue to run whilst the menu is being displayed. 112If you would like to change this so that it's automatically paused when you enter 113the menu and resumes when you exit then you should add the option 114`menu_auto_pause = 1`. 115 116In the menu, you use the following keys for navigation: 117Cursor keys 118Enter (choose item, enter sub-menu) 119Back-space (leave sub-menu) 120 121On the game pad, you can use either the hat or the primary analog stick 122for navigation. You choose items and enter sub-menus with the "primary" 123button on the game pad. This is generally the "south" button on the right 124side of the controller. The back button is the "east" button (Just like 125you would navigate on the Xbox). 126 127 128SCREENSHOTS 129=========== 130Press the "Print Scrn" key on the keyboard to save a screenshot of the 131running game to the desktop. Alternatively, you can use F12+s if you don't 132have this key. 133 134 135KEYBOARD SHORTCUTS 136================== 137F12 (or Cmd+F12) -Enter/exit GUI. 138F12+G or Middle mouse click – release input grab. 139Alt+Tab (or Cmd+Tab) – switch to another window / release input grab. 140F12+F (or Alt+Enter / Cmd+Enter) – toggle fullscreen mode. 141F11 (or Cmd+F11) – cycle through zoom settings. 142Shift + F11 – zoom out a bit (pad the viewport on all sides). 143 144 145PROGRAM ARGUMENTS 146================= 147<path> Use a custom configuration file instead of Default.fs-uae 148 149You can also specify any configuration option with --key=value 150(e.g --floppy-drive-0=/path/to/adf) 151 152Some options commonly used as program arguments: 153 154--fullscreen Start in fullscreen mode instead of windowed mode 155--stdout Also log to stdout (not on Windows) 156 157 158LOG FILE AND REPORTING PROBLEMS 159=============================== 160A log file is stored as (My) Documents/FS-UAE/Logs/FS-UAE.log 161 162When reporting a problem, you should include this log file with you error 163report. 164 165 166FLOPPY DISKS 167============ 168New data is always saved to overlay ADF files (.sdf). As an example, if you 169have floppy.adf insert into df0 and the Amiga writes to df0, the data is 170written to floppy.sdf instead of modifying floppy.adf itself. You need both 171floppy.adf and floppy.sdf to represent the entire modified disk. The save 172files are created on demand (when data is written to a drive). 173 174The floppy file overlays are by default save in the directory 175(My) Documents/FS-UAE/Floppy Overlays 176 177The GUI does not allow you to browse for files on the file system. Disks 178can be inserted at startup time (specified in the configuration file), and 179FS-UAE maintains a list of available floppy images to insert (also specified 180in the configuration file). See example.conf for more information. 181 182 183SUPPORTED AMIGA MODELS 184====================== 185The following Amiga models are supported: 186- A1000 - Amiga 1000 187- A500 - Amiga 500 (Default) 188- A500+ - Amiga 500+ 189- A600 - Amiga 600 190- A1200 - Amiga 1200 191- A1200/020 Amiga 1200 with full 68020 CPU 192- A4000/040 Amiga 4000 with 68040 CPU 193- CD32 - Amiga CD32 194- CDTV - Commodore CDTV 195 196The default configurations corresponds to the quickstarts in WinUAE for 197these systems, on the most compatible setting (cycle-exact mode). 198 199 200DISPLAY REFRESH RATE AND RESOLUTION 201=================================== 202For really smooth scrolling in games, your display MUST run at the same 203refresh rate as the Amiga: 50Hz (PAL). Many monitors and TVs with 1920x1080 204resolution supports this refresh rate. If FS-UAE detects that you display is 205running at 50Hz, vsync will automatically be enabled for perfect scrolling. 206 207FS-UAE will (not yet) on its own change your refresh rate to 50Hz -you 208must do this yourself before starting FS-UAE. 209 210If you run your display with another refresh rate, the emulator will still 211work just fine, but scrolling will be somewhat jerky -it varies with games 212whether this is very noticable or not. 213 214Note: On Mac OS X, FS-UAE does not currently detect the refresh rate, 215which means that full vsync will not be enabled. If you are running at 21650Hz, you can force vsync with --video-sync=full 217 218FS-UAE will use whatever full-screen resolution you desktop is using, and 219will assume that you have square pixels. The Amiga image will be scaled 220to fit the display, and you can choose whether to stretch to fill the entire 221screen, or scale up while maintaining the original aspect ratio. 222 223 224SUPPORTED HOST OPERATING SYSTEM 225=============================== 226- Linux 227- Windows XP or newer 228- Mac OS X 10.6 or newer 229- FreeBSD (Other Unices will probably also work just fine) 230 231 232DEBUGGING SUPPORT 233================= 234FS-UAE does not include a graphical debugger for debugging Amiga programs. It 235is possible to use the internal UAE debugger from the console. 236 237For debugging FS-UAE itself, a native debugger can be used if you compile 238FS-UAE yourself. Other debug information can be retrieved from the log file. 239 240There is debug overlay to debug video, audio and vsync issues. You can toggle 241the display of this with CTRL+F10. 242 243FS-UAE automatically crops the Amiga video output. Sometimes this does not 244work perfectly. You can override this behaviour in the configuration file. 245Also, you can press CTRL+F11 when running to visually see the entire amiga 246output with the crop rectangle. 247 248 249KNOWN ISSUES / TODO 250=================== 251Amiga mouse must currently be emulated with a native mouse device. A nice 252feature would be to be able to emulate the mouse with gamepads - analogue 253controls for instance. 254 255An on-screen keyboard, controllable with a game pad / joystick would also 256be nice, and is planned for a future version. 257 258Floppy list UI does not support scrolling, so if you have many floppy images 259in the floppy list, some may be obscured. 260 261 262COPYRIGHT AND CREDITS 263===================== 264FS-UAE is Copyright (c) 2011-2019, Frode Solheim 265Large portions are copyrighted by other individuals. 266 267FS-UAE is based on the fantastic work of the original UAE authors, the authors 268of WinUAE, contributions from external contributors as well as some code 269from E-UAE and P-UAE. See http://fs-uae.net/contributions for an 270updated list of people having contributed patches, translations and donations. 271 272UAE was created by Bernd Schmidt, with the help of a host of volunteer 273contributors (see the UAE distribution for full credits). 274 275WinUAE has been developed and maintained by Mathias Ortmann and Toni Wilen. 276Toni Wilen has developed WinUAE for the last years and is the current 277maintainer. E-UAE was developed by Richard Drummond (no longer maintained), 278and P-UAE is developed by Mustafa "GnoStiC" TUFAN (no longer maintained). 279 280http://www.winuae.net/ 281http://www.rcdrummond.net/uae/ 282http://www.softpres.org/ 283 284libfsemu is Copyright (c) 2011-2019, Frode Solheim 285 286IPF decoder library is Copyright (c) 2001-2011 by István Fábián with 287additional work by Christian Sauer. 288