Difference between revisions of "RetroArch"

From ArchWiki
Jump to: navigation, search
m (Installation: Linkify 'install' Help:Style#Package_management_instructions)
 
(86 intermediate revisions by 27 users not shown)
Line 1: Line 1:
 
[[Category:Gaming]]
 
[[Category:Gaming]]
[[Category:Emulators]]
+
[[Category:Emulation]]
[http://themaister.net/retroarch.html RetroArch] is a modular, command-line driven, multi-system emulator that is designed to be fast, lightweight, and portable. It has features few other emulators frontends have, such as real-time rewinding and game-aware shading based on the [http://github.com/libretro/libretro.github.com/wiki/Documentation-devs libretro API].
+
[[es:RetroArch]]
 +
[[ja:RetroArch]]
 +
{{Note|RetroArch is not affiliated with [[Arch Linux]].}}
 +
 
 +
[http://www.retroarch.com/ RetroArch] is the reference implementation of the libretro API. It is a modular front-end for video game system emulators, game engines, video games, media players and other applications that offers several uncommon technical features such as multi-pass shader support, real-time rewinding and video recording (using [[FFmpeg]]), it also features a gamepad-driven UI on top of a full-featured command-line interface.
  
 
== Installation ==
 
== Installation ==
 +
[[Install]] the {{Pkg|retroarch}} package or alternatively {{AUR|retroarch-git}} for the development version.
 +
{{Tip|Install the {{Pkg|retroarch-assets-xmb}} package to allow the default menu driver (XMB) to work properly. Additionally, install the {{Pkg|retroarch-autoconfig-udev}} package to enable RetroArch to automatically map buttons to joypads when they are plugged.}}
 +
 +
== Usage ==
 +
 +
RetroArch relies on separate libraries, called "cores", available from the [https://www.archlinux.org/packages/?q=libretro Community] repository, the [https://aur.archlinux.org/packages/?O=0&K=libretro AUR] and the [https://buildbot.libretro.com/ libretro Buildbot], for most of its functionalities.
 +
 +
Each libretro core package will install a library to {{ic|/usr/lib/libretro/}}. The syntax to choose one when executing ''retroarch'' is:
 +
 +
$ retroarch --libretro /usr/lib/libretro/''core''-libretro.so ''/path/to/rom''
 +
 +
A default core can be defined in the configuration, obviating the need to specify it on every run.
 +
 +
{{hc|~/.config/retroarch/retroarch.cfg|2=
 +
libretro_path = "/usr/lib/libretro/''core''-libretro.so"
 +
}}
 +
 +
== Configuration ==
 +
 +
RetroArch provides a very well commented skeleton configuration file located at {{ic|/etc/retroarch.cfg}}.
 +
 +
Copy the skeleton configuration file to your home directory
 +
 +
$ cp /etc/retroarch.cfg ~/.config/retroarch/retroarch.cfg
 +
 +
It supports split configuration files using the {{ic|#include "foo.cfg"}} directive within the main configuration file, {{ic|retroarch.cfg}}. This can be overridden using the {{ic|--appendconfig ''/path/to/config''}} parameter and is beneficial if different keybinds, video configurations or audio settings are required for the various cores.
 +
 +
{{Tip|RetroArch is capable of loading [https://gitorious.org/bsnes/xml-shaders bsnes xml filters] and [https://github.com/libretro/common-shaders cg shaders] that can be defined in {{ic|retroarch.cfg}} as {{ic|video_bsnes_shader}} and {{ic|video_cg_shader}} respectively.}}
 +
{{Note|
 +
* {{AUR|retroarch-git}} requires {{pkg|nvidia-cg-toolkit}} in order to use the ''cg shaders''.
 +
* When using [[ALSA]] it is necessary for the {{ic|audio_out_rate}} to be equal to the system's default output rate, usually {{ic|48000}}.
 +
}}
 +
 +
== Tips and tricks ==
 +
 +
=== Enabling the ''Online Updater'' ===
 +
 +
Recent versions of RetroArch have introduced a built-in menu for updating and downloading core files and various assets from the [https://buildbot.libretro.com/ libretro Buildbot]. To enable it, open {{ic|~/.config/retroarch/retroarch.cfg}} and set {{ic|menu_show_core_updater}} to {{ic|"true"}}.
  
Install {{aur|retroarch-git}} from the [[AUR]].
+
{{hc|~/.config/retroarch/retroarch.cfg|2=
 +
menu_show_core_updater = "true"
 +
}}
  
A GTK+/Qt frontend, {{aur|retroarch-phoenix-git}}, is also available.
+
{{hc|1=Online Updater|2=
 +
Core Updater
 +
Thumbnails Updater
 +
Content Downloader
 +
Update Core Info Files
 +
Update Assets
 +
Update Joypad Profiles
 +
Update Cheats
 +
Update Databases
 +
Update Overlays
 +
Update GLSL Shaders
 +
Update Slang Shaders
 +
}}
  
== Usage ==
+
These cores and assets are kept up to date and can be pulled from the updater any time there's an update.
 +
 
 +
=== Enabling ''SaveRAM Autosave Interval'' ===
 +
 
 +
By default, RetroArch only writes SRAM onto disk when it exits without error, which means that there's a risk of losing save data when using crash-prone cores. To change this behavior, open {{ic|~/.config/retroarch/retroarch.cfg}} and set {{ic|autosave_interval}} to ''n''.
 +
 
 +
{{hc|~/.config/retroarch/retroarch.cfg|2=
 +
autosave_interval = "600"
 +
}}
 +
 
 +
With the example above, RetroArch will write SRAM changes onto disk every 600 seconds.
 +
 
 +
{{Warning|Setting this value too low will cause all sorts of issue, most notably hardware degradation. See [https://github.com/libretro/RetroArch/issues/4901#issuecomment-300888019]}}
 +
 
 +
=== Reset settings to their default value ===
 +
 
 +
To reset a setting or keybind to its default value through the GUI, highlight it and press {{ic|Start}}. To remove a button from a keybind, highlight the keybind and press {{ic|Y}}.
 +
 
 +
== Troubleshooting ==
 +
 
 +
=== No cores found ===
 +
 
 +
By default RetroArch will attempt to find cores in {{ic|/usr/lib/libretro/}}. Cores downloaded using the built-in ''Online Updater'' will fail to save unless RetroArch is run as root (not recommended, as it may overwrite cores installed by [[pacman]] and also because it poses a security risk.[https://bugzilla.gnome.org//show_bug.cgi?id=772875#c5]) because users do not normally have permission to modify this directory. To use a user-owned directory instead, edit these lines:
 +
 
 +
{{hc|~/.config/retroarch/retroarch.cfg|2=
 +
libretro_directory = "~/.config/retroarch/cores"
 +
libretro_info_path = "~/.config/retroarch/cores/info"
 +
}}
 +
{{Note|1=Cores obtained from the [https://www.archlinux.org/packages/?q=libretro Community] repository or the [https://aur.archlinux.org/packages/?O=0&K=libretro AUR] will be installed to {{ic|/usr/lib/libretro/}} regardless of this setting, because of this, it's recommended to stick to one method of obtaining cores, use the default directory when obtaining cores from the Community repository or the AUR or a user-owned directory (such as {{ic|~/.config/retroarch/cores}}) when using the ''Online Updater''.}}
 +
 
 +
=== Input devices do not operate ===
 +
 
 +
You may encounter problems if running on a CLI or a display server other than [[Xorg]] or if you use the [[udev]] input driver, because {{ic|/dev/input}} nodes are limited to root-only access. Try adding your user to the "input" [[group]] then logging in again.
 +
 
 +
Alternatively, manually add a rule in {{ic|/etc/udev/rules.d/99-evdev.rules}}, with {{ic|1=KERNEL=="event*", NAME="input/%k", MODE="666"}} as its contents. Reload [[udev rules]] by running:
  
'''RetroArch''' employs the use of separate ''emulator cores'' (or ''implementations'') available from both the [[AUR]] and the [http://github.com/libretro libretro] github.
+
# udevadm control --reload-rules
  
Each package from the [[AUR]] will install an emulator core to {{ic|/usr/lib/libretro/[system].so}}, thus to use
+
If rebooting the system or replugging the devices are not options, permissions may be forced using:
{{ic|retroarch}} with your preferred system simply launch it with the {{ic|-L}} parameter. ''E.g.''
 
  
  retroarch -L /usr/lib/libretro/libretro-snes9x-next.so ~/path/to/game
+
  # chmod 666 /dev/input/event*
  
{{Tip|It is possible to run directly from {{ic|.zip}} files using the {{ic|retroarch-zip}} shell wrapper, however, keep in mind that this is not supported within the implementation.}}
+
=== Poor video performance ===
  
This emulation core can also be defined in the {{ic|retroarch.cfg}}, thus obviating the need to specify it on the command line.
+
If poor video performance is met, RetroArch may be run on a separate thread by setting {{ic|1=video_threaded = true}} in {{ic|~/.config/retroarch/retroarch.cfg}}.
  
{{hc|/etc/retroarch.cfg|2=
+
This is, however, a solution that should be not be used if tweaking RetroArch's video resolution/refresh rate fixes the problem, as it makes perfect V-Sync impossible, and slightly increases latency.
libretro_path = "/usr/lib/libretro/libretro-snes9x-next.so"}}
 
  
There are currently several emulation cores available including ''snes9x'', ''bsnes'', ''visual boy advance'' and ''final burn alpha''. See this [https://aur.archlinux.org/packages.php?K=libretro AUR search] for more.
+
=== Save data is lost whenever RetroArch crashes ===
  
== Configuration ==
+
See [[#Enabling SaveRAM Autosave Interval]].
RetroArch provides a skeleton configuration file located at {{ic|/etc/retroarch.cfg}} and is very well commented.  
 
  
It is capable of supporting split configuration files using the {{ic|#include "foo.cfg"}} directive within the main {{ic|retroarch.cfg}} file. Alternatively, extra configuration files can be appended on the command line which override the default settings in {{ic|retroarch.cfg}}. This can be achieved by using {{ic|--appendconfig /path/to/config}} and is beneficial if different keybinds, video configurations or audio settings are required for the various implementations.
+
== See also ==
  
{{Tip|{{ic|retroarch}} is capable of loading ''bsnes xml filters'' [https://gitorious.org/bsnes/xml-shaders] and ''cg shaders'' [https://github.com/libretro/common-shaders]. They can be defined in {{ic|retroarch.cfg}} as {{ic|video_bsnes_shader}} and {{ic|video_cg_shader}} respectively.
+
* [http://www.retroarch.com/ Official Website]
{{Note|{{aur|retroarch-git}} requires {{pkg|nvidia-cg-toolkit}} in order to use the ''cg shaders''.}}}}
+
* [https://github.com/libretro/RetroArch/wiki RetroArch wiki on GitHub]
{{Warning|When using the '''alsa''' driver make sure {{ic|audio_out_rate}} is ''equal'' to your system's default output rate. This is usually 48000.}}
+
* [https://github.com/libretro/libretro.github.com/wiki/Documentation-devs Documentation for developers]

Latest revision as of 13:08, 12 February 2018

Note: RetroArch is not affiliated with Arch Linux.

RetroArch is the reference implementation of the libretro API. It is a modular front-end for video game system emulators, game engines, video games, media players and other applications that offers several uncommon technical features such as multi-pass shader support, real-time rewinding and video recording (using FFmpeg), it also features a gamepad-driven UI on top of a full-featured command-line interface.

Installation

Install the retroarch package or alternatively retroarch-gitAUR for the development version.

Tip: Install the retroarch-assets-xmb package to allow the default menu driver (XMB) to work properly. Additionally, install the retroarch-autoconfig-udev package to enable RetroArch to automatically map buttons to joypads when they are plugged.

Usage

RetroArch relies on separate libraries, called "cores", available from the Community repository, the AUR and the libretro Buildbot, for most of its functionalities.

Each libretro core package will install a library to /usr/lib/libretro/. The syntax to choose one when executing retroarch is:

$ retroarch --libretro /usr/lib/libretro/core-libretro.so /path/to/rom

A default core can be defined in the configuration, obviating the need to specify it on every run.

~/.config/retroarch/retroarch.cfg
libretro_path = "/usr/lib/libretro/core-libretro.so"

Configuration

RetroArch provides a very well commented skeleton configuration file located at /etc/retroarch.cfg.

Copy the skeleton configuration file to your home directory

$ cp /etc/retroarch.cfg ~/.config/retroarch/retroarch.cfg

It supports split configuration files using the #include "foo.cfg" directive within the main configuration file, retroarch.cfg. This can be overridden using the --appendconfig /path/to/config parameter and is beneficial if different keybinds, video configurations or audio settings are required for the various cores.

Tip: RetroArch is capable of loading bsnes xml filters and cg shaders that can be defined in retroarch.cfg as video_bsnes_shader and video_cg_shader respectively.
Note:
  • retroarch-gitAUR requires nvidia-cg-toolkit in order to use the cg shaders.
  • When using ALSA it is necessary for the audio_out_rate to be equal to the system's default output rate, usually 48000.

Tips and tricks

Enabling the Online Updater

Recent versions of RetroArch have introduced a built-in menu for updating and downloading core files and various assets from the libretro Buildbot. To enable it, open ~/.config/retroarch/retroarch.cfg and set menu_show_core_updater to "true".

~/.config/retroarch/retroarch.cfg
menu_show_core_updater = "true"
Online Updater
Core Updater
Thumbnails Updater
Content Downloader
Update Core Info Files
Update Assets
Update Joypad Profiles
Update Cheats
Update Databases
Update Overlays
Update GLSL Shaders
Update Slang Shaders

These cores and assets are kept up to date and can be pulled from the updater any time there's an update.

Enabling SaveRAM Autosave Interval

By default, RetroArch only writes SRAM onto disk when it exits without error, which means that there's a risk of losing save data when using crash-prone cores. To change this behavior, open ~/.config/retroarch/retroarch.cfg and set autosave_interval to n.

~/.config/retroarch/retroarch.cfg
autosave_interval = "600"

With the example above, RetroArch will write SRAM changes onto disk every 600 seconds.

Warning: Setting this value too low will cause all sorts of issue, most notably hardware degradation. See [1]

Reset settings to their default value

To reset a setting or keybind to its default value through the GUI, highlight it and press Start. To remove a button from a keybind, highlight the keybind and press Y.

Troubleshooting

No cores found

By default RetroArch will attempt to find cores in /usr/lib/libretro/. Cores downloaded using the built-in Online Updater will fail to save unless RetroArch is run as root (not recommended, as it may overwrite cores installed by pacman and also because it poses a security risk.[2]) because users do not normally have permission to modify this directory. To use a user-owned directory instead, edit these lines:

~/.config/retroarch/retroarch.cfg
libretro_directory = "~/.config/retroarch/cores"
libretro_info_path = "~/.config/retroarch/cores/info"
Note: Cores obtained from the Community repository or the AUR will be installed to /usr/lib/libretro/ regardless of this setting, because of this, it's recommended to stick to one method of obtaining cores, use the default directory when obtaining cores from the Community repository or the AUR or a user-owned directory (such as ~/.config/retroarch/cores) when using the Online Updater.

Input devices do not operate

You may encounter problems if running on a CLI or a display server other than Xorg or if you use the udev input driver, because /dev/input nodes are limited to root-only access. Try adding your user to the "input" group then logging in again.

Alternatively, manually add a rule in /etc/udev/rules.d/99-evdev.rules, with KERNEL=="event*", NAME="input/%k", MODE="666" as its contents. Reload udev rules by running:

# udevadm control --reload-rules

If rebooting the system or replugging the devices are not options, permissions may be forced using:

# chmod 666 /dev/input/event*

Poor video performance

If poor video performance is met, RetroArch may be run on a separate thread by setting video_threaded = true in ~/.config/retroarch/retroarch.cfg.

This is, however, a solution that should be not be used if tweaking RetroArch's video resolution/refresh rate fixes the problem, as it makes perfect V-Sync impossible, and slightly increases latency.

Save data is lost whenever RetroArch crashes

See #Enabling SaveRAM Autosave Interval.

See also