Skip to content

FAQ

Jump to bottom
Dimitris Panokostas edited this page Oct 2, 2024 · 75 revisions

Frequently Asked Questions

Q: Where does Amiberry look for it's files on Linux? Can I change that?

A: Amiberry has traditionally behaved as a "Portable" app, meaning that it was designed to expect everything under the same directory. The startup path would determine where it would look for all the required sub-dirs and files (e.g. data, conf etc.). This has changed since versions 5.7.4 and 6.3.4. The data folder is now handled separately from the home folder, instead of expecting everything under the same path.

Amiberry is now installed system-wide and can be launched from anywhere. The empty directories that used to be included are now created on startup, usually under the user's HOME directory (see below for exceptions). Shared components are installed system wide.

Specifically, this is the logic that Amiberry follows on startup, to initialize the paths:

For the DATA directory (where the data folder and sub-dirs reside)

  • If an ENV variable named AMIBERRY_DATA_DIR is set, it will check if that contains the data folder, and if so, use it.
  • If there is no such ENV variable set, it will next look at the standard /usr/share/amiberry directory, for a data folder. If found, that will be used. This is also where the DEB package will install them.
  • If the above check also fails, it will then look for the XDG_DATA_HOME ENV variable and if set, use that.
  • Finally, if all the above checks failed, it will use the fallback method of expecting everything under the current directory + /data.

For the HOME directory (where user-configurable files and folders reside, like floppies, controllers, whdboot etc.)

  • If an ENV variable named AMIBERRY_HOME_DIR is set, it will be used as the home directory.
  • If the above doesn't exist, it will check for an ENV variable named XDG_DATA_HOME, and use that if it is found.
  • If the above doesn't exist, it will look for $HOME/.amiberry instead. If that exists, it will be used. This is the most common scenario.
  • Finally, in the unlikely case that all the above checks failed, it will use the fallback method of expecting it under the current directory (Portable mode).

For the CONFIG directory (where the application configs are saved, what used to be the conf directory)

  • If an ENV variable named AMIBERRY_CONFIG_DIR is found, it will be used.
  • Otherwise, if the ENV variable XDG_CONFIG_HOME is found, it will be used with a sub-directory amiberry created under it.
  • Otherwise, if HOME is found, it will be used with a sub-directory Amiberry/conf under it. Either this or the previous one will be the most common scenario, depending on the operating system.
  • In the unlikely scenario that all the above checks failed, it will use the fallback of expecting it under the current directory + /conf.

For the PLUGINS directory (where any extra plugin libraries are placed, like capsimage and libfloppybridge)

  • If an ENV variable named AMIBERRY_PLUGINS_DIR is found, it will be used.
  • Otherwise, if /usr/local/lib/amiberry/ is found, it will be used. This is useful if you compile and install it locally, using CMake.
  • Otherwise, if /usr/lib/amiberry/ is found, it will be used. This is the location the .DEB package will use, and the most common scenario.
  • Otherwise, if the ENV varialbe HOME is found, it will use that and create a sub-directory /Amiberry/plugins under it.
  • In the unlikely scenario that all the above checks failed, it will use the fallback of expecting it under the current directory + /plugins.

This standardizes the behavior as a normal Linux application, still allows the possibility to manually override the default locations if necessary.

Q: On Debian Bookworm, the performance when running in Full-Window is terrible. But it's much faster in Windowed mode. What is going on?

A: This is due to SDL2's choice of back-ends. The current versions seem to prefer X11, even when Wayland is used in the system (Bookworm is using Wayland by default). You can override this manually, by telling SDL2 to use a specific back-end, or change the order of priority it should use. Alternatively, you can switch to X11 instead of Wayland (read further to see how to do that).

First, test running Amiberry like this (from the terminal): SDL_VIDEODRIVER=wayland ./amiberry Does this fix the performance issue while in Full-Window modes? If so, you can make this change apply whenever you login, by doing the following:

  • Open a console, and type sudo nano /etc/profile.d/sdl2_fix.sh - provide the root password if requested.
  • In the text editor that opens, type the following:
#!/bin/bash
export SDL_VIDEODRIVER=kmsdrm,wayland,x11
  • Press Ctrl-X and then Enter (or Y), to save the changes to the file.
  • Log out and log back in, for the changes to take effect.

If you prefer to switch to X11 instead, you can do that by going to raspi-config -> 6 Advanced Options -> Wayland -> W1 X11 Openbox window manager with X11 backend.

Q: I have a Competition Pro joystick, but the mapping doesn't seem to be correct. What can I do?

A: The below is only an issue with older versions of Amiberry. Amiberry v5.x or newer already includes the correct mapping in the controllers file. Starting with v4.x of Amiberry, we use SDL2's "gamecontrollerdb.txt" file for mappings of known controllers. It seems that the Competition Pro is re-using a gamepad USB ID, so it gets an incorrect mapping from that file. To fix the problem, you'll need to edit the file conf/gamecontrollerdb.txt with a text editor, and find the line starting with the following ID:

03000000790000001c18000011010000,PC Game Controller

Change that line with the following contents:

03000000790000001c18000011010000,Competition Pro Extra,a:b3,b:b1,back:b2,leftx:a0,lefty:a1,start:b0,platform:Linux,

Save the file and restart Amiberry. The mapping should now work properly for this joystick.

Q: Amiberry on a Pi4/Pi400 seems extraordinary slow. The Status Line shows it's only doing 30 FPS. What's wrong?

A: Is your connected monitor/TV a 4K one? If so, it may be forcing your Pi output to 4k@30Hz resolution. Amiberry uses VSync, so it will only show as many frames per second as the current refresh rate of your monitor. If that's set to 30, video and audio will be choppy and slower than expected. Normally you can change the resolution in /boot/config.txt and force it to a 1080p one. However, some SmartTVs seem to ignore that and force a 4K resolution again... If that's the case with you, you could try forcing the configuration to 1080p in /boot/config.txt by using these additional options:

[hdmi:0]
hdmi_max_pixel_freq=200000000
[hdmi:1]
hdmi_max_pixel_freq=200000000
hdmi_ignore_edid=0xa5000080

Q: When I type some letters on the keyboard, I get unexpected behavior (e.g. typing x also adds Return). What's wrong?

A: Don't use the "Keyboard as Joystick" option in the Input panel. The CD32 mapping uses some extra keyboard keys that will interfere with normal keyboard typing.

Q: Input latency seems increased, when running Amiberry under a full Desktop. What can I do?

A: Disable the Compositor to gain some more performance. On XCFE desktops for example, you can disable your compositor by opening the main Applications menu and clicking “Settings -> Window Manager Tweaks.” This will open a new window. Open the Compositor tab, and uncheck the option “Enable display compositing.”

Q: How can I launch CD32 games from .CUE/BIN CD images?

A: Launching CD32 games does not require any default config, and you shouldn't use the A1200 config with it either (it won't enable the CD32 specific bits). If you have .cue/bin files, then the best way to launch them would be:

  1. From the command line: use the -autoload parameter. E.g. ./amiberry -autoload /home/pi/RetroPie/roms/amiga/Alien Breed - Tower Assault_CD32.cue (use escape characters where necessary, to handle spaces)
  2. From the GUI: Select CD32 from Quickstart, select the .CUE file in the CD slot, click on Start. CD32 images don't need or use WHDLoad. If you have WHDLoad installed CD32 games however, you can also launch them using the -autoload option, in the same way as shown above. Only the file passed would probably be an .lha one, not a CD image. Keep in mind that WHDLoad games usually don't contain CD audio tracks, so you'll be missing those...

Q: I have thousands of Config files in my installation, and Amiberry takes a long time to display the GUI.

A: The default behavior is to scan the list of config files, open each one and get the Description in order to populate the list in the GUI. If you have many such files, the process can take a longer time than desired. To bypass this behavior, you can make a change in the conf/amiberry.conf file:

  • Open the file, and look for the line read_config_descriptions.
  • Change the value of that line to no and save the file again.
  • Restart the emulator for the changes to take effect.

Q: My game runs too fast, what can I do?

A: Run the Whdload versions and Switch on “wait for blitter” and this should fix the speed issue on many games.

Q: I've got a question about the WHDLoad booter...

A: Please refer to the specific FAQ for this: WHDLoad Booter F.A.Q

Q: Audio is noticeable distorted when playing back with USB audio device instead of 3.5mm audio jack

A: Check if you're using a GPIO kernel module, which imposes some latency. Normally there shouldn't be any difference in audio latency from Amiberry, regardless if you're using the 3.5mm audio jack, HDMI-out, or a USB audio card.

Q: I want to troubleshoot something. Can I enable logging in Amiberry?

A: Logging can be enabled from the GUI (Paths panel) or by changing a value in the conf/amiberry.conf file:

  • Open the file, and look for the line write_logfile.
  • Change the value of that line to yes and save the file again.
  • Restart the emulator for the changes to take effect. A new file named amiberry_log.txt will be created in the same location the emulator was started from. Additionally, the WHDLoad booter will also save log information in the whdboot/save-data/Debugs path. Note: Make sure that the user running the emulator has permissions to create the file!

Q: Can I enable Scanlines by default for all games?

A: Yes, with v2.24 onwards a new feature was added, you can make a change in the conf/amiberry.conf file:

  • Open the file, and look for the line scanlines_by_default.
  • Change the value of that line to yes and save the file again.
  • Restart the emulator for the changes to take effect. Note: Scanlines requires that Line Doubling is also enabled, which will cause a performance hit, since double the amount of lines will have to be drawn on-screen. Also, if your vertical resolution is not enough to display scanlines, this option will have no effect (it will revert back to no scanlines automatically).

Q: Are HDFs with multiple partitions and custom Filesystems (e.g. PFS) supported?

A: Yes, you can use HDFs with RDB and multiple partitions, even if they were formatted using PFS. If you use a custom filesystem without RDB mode HDFs, just remember to place the Filesystem handler you're using (e.g. FastFileSystem or pfs3aio) in the kickstarts directory, along with your Kickstart ROMs. Then add your HDF as normal, and Amiberry will automaticall look for it there and attempt to mount the partitions during startup.

Q: When the emulator starts up, I get a few warning messages (MESA-LOADER: failed to retrieve device information) on the console. Is this a problem?

A: This is due to a known bug in libdrm (https://bugs.launchpad.net/raspbian/+bug/1656930). It's harmless and you can ignore it.

**Q: Mac OS App is "damaged" or it says it is not compatible. Why? **

A: The binary is not broken, but Apple OS does not allow apps that don't come from a "recognized developer" to be run if you download it with a browser. You can whitelist the app manually, however. Open a console and run xattr -rd com.apple.quarantine Amiberry.app.

**Q: What is KMSDRM and should I use it? **

A: KMSDRM makes it possible to run Amiberry in console, without running X11 or Wayland. It might squeeze a little bit of extra performance. That said, the performance gain from running in KMSDRM is neglectable for most use cases. You'll probably wont see the difference unless you're running a benchmark or do rendering on the emulated Amiga.

Q: When I use Amiberry in KMS the mouse doesn't work. Why? (Raspberry PI OS)

A: There are several issues with the version of SDL2 shipped with Debian Bullseye / Raspberry Pi OS. You have install your own, or upgrade to the latest Raspberry Pi OS (Bookworm) which doesn't have this issue.

Q: How do I use Amiberry in KMSDRM (console) or Why is KMSDRM so slow?

A: The SDL that is distributed in Debian Buster (2.0.9) doesn't support KMSDRM, and the one in Bullseye (2.0.14) has some bugs that have been fixed in the latest upstream version of SDL (2.0.18 and later), so in order to fix that you have to install that manually. How to do that is out of scope for this FAQ. If you run Manjaro or Arch Linux, KMSDRM is supported out of the box, no need for additional hacks. The latest Raspberry Pi OS (Bookworm) also works, since it includes a newer version of SDL2.

Q: Which KMS driver should I use?

A: Amiberry works with all versions, but keep in mind the following when making your decision:

  • KMS is the new default in newer distros, including the offical RPI-OS one (starting with Bullseye)

Q: Sound doesn't work with KMS (Raspberry Pi OS)

A: But it works when using the fkms driver, right? Install pulseaudio and reboot.

Getting Started

Loading Amiga Programs

Amiberry GUI

Inputs & Controls

Clone this wiki locally