Difference between revisions of "RetroArch"

From ArchWiki
Jump to: navigation, search
m (Brought capitalization in line with the rest of the article)
 
(98 intermediate revisions by 28 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 {{aur|retroarch-git}} from the [[AUR]].
+
[[Install]] {{Pkg|retroarch}} or alternatively {{AUR|retroarch-git}} for the development version.
 +
{{Tip|[[Install]] {{Pkg|retroarch-assets-xmb}} to get the fonts and icons for the RetroArch GUI. You need to edit RetroArch's [[#Configuration]] to load them.}}
 +
 
 +
== Usage ==
 +
 
 +
RetroArch relies on separate libraries, called "cores", for most of its functionality. These can be downloaded per-user within RetroArch itself (via the [https://buildbot.libretro.com/ libretro Buildbot]) or you can [[install]] them system-wide via [https://www.archlinux.org/groups/x86_64/libretro/ Community] or [https://aur.archlinux.org/packages/?O=0&K=libretro AUR].
 +
 
 +
By default RetroArch is configured to load the per-user cores that it downloads. Change your [[#Configuration]] if you install them elsewhere.
 +
 
 +
The command to run a particular core is
 +
 
 +
$ retroarch --libretro ''/path/to/some_core_libretro.so'' ''/path/to/rom''
 +
 
 +
== Configuration ==
 +
 
 +
When you first run RetroArch it will create the user configuration file {{ic|~/.config/retroarch/retroarch.cfg}}. If you install any RetroArch components system-wide with [[pacman]], you should specify these in the global configuration file and include them in your user file. For example,
 +
 
 +
{{hc|/etc/retroarch.cfg|2=# for retroarch-assets-xmb
 +
assets_directory = "/usr/share/retroarch/assets"
 +
# for libretro-core-info
 +
libretro_info_path = "/usr/share/libretro/info"
 +
# for libretro cores
 +
libretro_directory = "/usr/lib/libretro"}}
 +
 
 +
{{hc|~/.config/retroarch/retroarch.cfg|2=#include "/etc/retroarch.cfg"}}
 +
 
 +
{{Note|RetroArch does not support multiple search paths for these components. For example, if you install cores with [[pacman]] '''and''' download cores using RetroArch's GUI, you cannot configure RetroArch to show all of them at once since they are installed in different directories.}}
 +
 
 +
If you want to override your configuration (for example when running certain cores) you can use the {{ic|--appendconfig ''/path/to/config''}} command line option.
 +
 
 +
== Tips and tricks ==
 +
 
 +
=== Disabling the ''Online Updater'' ===
 +
 
 +
If you prefer to install all RetroArch components with [[pacman]], you can disable RetroArch's built-in updater to prevent accidentally installing components the wrong way.
 +
 
 +
{{hc|~/.config/retroarch/retroarch.cfg|2=menu_show_core_updater = "false"}}
 +
 
 +
=== 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]}}
 +
 
 +
=== Filters and shaders ===
 +
 
 +
RetroArch can load [https://gitorious.org/bsnes/xml-shaders BSNES XML filters] and [https://github.com/libretro/common-shaders CG shaders]. These are set in {{ic|retroarch.cfg}} with {{ic|video_bsnes_shader}} and {{ic|video_cg_shader}} respectively. The shaders can also be obtained and updated directly inside RetroArch using the Online Updater.
 +
 
 +
{{Note|{{AUR|retroarch-git}} requires {{pkg|nvidia-cg-toolkit}} in order to use the ''cg shaders''.}}
 +
 
 +
=== 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}}.
  
A GTK+/Qt frontend, {{aur|retroarch-phoenix-git}}, is also available.
+
== Troubleshooting ==
  
== Usage ==
+
=== No cores found ===
 +
 
 +
By default RetroArch searches for cores in {{ic|~/.config/retroarch/cores}}, which is where the Online Updater installs them. Cores installed with [[pacman]] are placed in {{ic|/usr/lib/libretro}} and thus will not appear in RetroArch's GUI. You should choose one method of installing cores (pacman or the Online Updater) and change your [[#Configuration]] to match.
 +
 
 +
=== 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:
 +
 
 +
# udevadm control --reload-rules
 +
 
 +
If rebooting the system or replugging the devices are not options, permissions may be forced using:
  
'''RetroArch''' employs the use of separate ''emulator cores'' (or ''implementations'') available from both the [[AUR]] and the [http://github.com/libretro libretro] github.
+
# chmod 666 /dev/input/event*
  
Each package from the [[AUR]] will install an emulator core to {{ic|/usr/lib/libretro/[system].so}}, thus to use
+
=== Poor video performance ===
{{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
+
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}}.
  
{{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.}}
+
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.
  
This emulation core can also be defined in the {{ic|retroarch.cfg}}, thus obviating the need to specify it on the command line.
+
=== Audio issues with ALSA ===
  
{{hc|/etc/retroarch.cfg|2=
+
When using [[ALSA]] the {{ic|audio_out_rate}} must match the system's default output rate, usually {{ic|48000}}.
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 15:31, 22 September 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 retroarch or alternatively retroarch-gitAUR for the development version.

Tip: Install retroarch-assets-xmb to get the fonts and icons for the RetroArch GUI. You need to edit RetroArch's #Configuration to load them.

Usage

RetroArch relies on separate libraries, called "cores", for most of its functionality. These can be downloaded per-user within RetroArch itself (via the libretro Buildbot) or you can install them system-wide via Community or AUR.

By default RetroArch is configured to load the per-user cores that it downloads. Change your #Configuration if you install them elsewhere.

The command to run a particular core is

$ retroarch --libretro /path/to/some_core_libretro.so /path/to/rom

Configuration

When you first run RetroArch it will create the user configuration file ~/.config/retroarch/retroarch.cfg. If you install any RetroArch components system-wide with pacman, you should specify these in the global configuration file and include them in your user file. For example,

/etc/retroarch.cfg
# for retroarch-assets-xmb
assets_directory = "/usr/share/retroarch/assets"
# for libretro-core-info
libretro_info_path = "/usr/share/libretro/info"
# for libretro cores
libretro_directory = "/usr/lib/libretro"
~/.config/retroarch/retroarch.cfg
#include "/etc/retroarch.cfg"
Note: RetroArch does not support multiple search paths for these components. For example, if you install cores with pacman and download cores using RetroArch's GUI, you cannot configure RetroArch to show all of them at once since they are installed in different directories.

If you want to override your configuration (for example when running certain cores) you can use the --appendconfig /path/to/config command line option.

Tips and tricks

Disabling the Online Updater

If you prefer to install all RetroArch components with pacman, you can disable RetroArch's built-in updater to prevent accidentally installing components the wrong way.

~/.config/retroarch/retroarch.cfg
menu_show_core_updater = "false"

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]

Filters and shaders

RetroArch can load BSNES XML filters and CG shaders. These are set in retroarch.cfg with video_bsnes_shader and video_cg_shader respectively. The shaders can also be obtained and updated directly inside RetroArch using the Online Updater.

Note: retroarch-gitAUR requires nvidia-cg-toolkit in order to use the cg shaders.

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 searches for cores in ~/.config/retroarch/cores, which is where the Online Updater installs them. Cores installed with pacman are placed in /usr/lib/libretro and thus will not appear in RetroArch's GUI. You should choose one method of installing cores (pacman or the Online Updater) and change your #Configuration to match.

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.

Audio issues with ALSA

When using ALSA the audio_out_rate must match the system's default output rate, usually 48000.

Save data is lost whenever RetroArch crashes

See #Enabling SaveRAM Autosave Interval.

See also