Installation - mdeguzis/RetroRig GitHub Wiki

Table of Contents

Supported Platforms/Distros

Support is started to expand to a few non-Ubuntu / Debian derivatives, so be sure to check this list often to see if your platform or distribution is supported. If it is not, you will receive a brief message when you start the setup script. Requests for platform/distribution support can be made via an issues ticket. Please note all distributions below are x86_64 (64 bit)

  • Ubuntu 14.04 LTS (recommended)
  • Ubuntu 14.10 (Currently experiencing issues)
  • Linux Mint 17
  • Deepin 2014

Supported Consoles

The console listing below is included the default installation set of RetroRig. I realize that, over time, the list may get long enough that scrolling the systems in ROM Collection Browser will get annoying. In that light, an options menu will eventually surface for "Add Additional Emulators to RCB." I imagine this will be a checklist, where you can select what else to add. The current list below should reflect what I feel are a good spread of systems for most users, or by request. I am going to try and keep the list to 12 entries, with that number and set of consoles up for debate (please submit an issue ticket).

Not every system below is included on every Linux platform/distribution RetroRig supports. Some may function better on one distribution, or worse on another, depending on how it was packaged or compiled. If you see a system missing that you want, you can either submit an Issues ticket, or contact me via LibreGeek.org. Every bit helps, especially with quirky emulators.

For all other emulator information please see the Emulator Resource Page wiki entry. You will find emulators under review, as well as a lot of other information.

Supported Gamepads

  • Xbox 360 Controller (wireless)
  • Xbox 360 Controller (wired)
  • Playstation 3 Sixaxis (Bluetooth)
  • Playstation 3 Sixaxis (Wired)

Please refer to the Gamepads section of the wiki for supported and unsupported controller documentation, including button mappings and layouts for the emulators. Please take note that some emulators are not supported under certain gamepads due to button limitations or restrictions!

Pre-requisites

The preferred method for typical users, is to install RetroRig from the package provided. There are no pre-requisites if you install via a compiled package, such as the retrorig-setup package from the Ubuntu PPA we have. If, however, you use the direct github installation method, it is required you have at the minimum, dialog installed to use the installer. Figlet (to display the welcome banner) is optional, and not a hard-dependency.

Installation

Warning!

RetroRig implements a separated ".xbmc" configuration folder, however, we do not have separated xbmc itself. RetroRig will upgrade XBMC to the latest Helix (Now called Kodi). It is paramount to check in advance, if all your regular xbmc plugins, skins, etc. still work under Helix.

Typical Method: Pre built package

There are two ways you can approach this. You can either add our repository (noted below), or download the direct package "retrorig-setup" from the same area.

sudo add-apt-repository ppa:mdeguzis/retrorig
sudo apt-get update
sudo apt-get install retrorig-setup
sudo retrorig-setup

Alternate Method: Github

To clone this repo via the CLI:

git clone https://github.com/ProfessorKaos64/RetroRig

To install:

cd RetroRig
sudo ./retrorig-setup.sh

You can also download a zip file or by other means on the github page. Be aware that you can also peform a git checkout beta after cloning the repository to install/update to the beta. Please backup your .retrorig/ and ~/RetroRig/ directories beforehand please!

Ascinema video tutorials

You can also view some video tutorials on certain installation, troubleshooting, and how-to procedures. This is a new piece that should help out folks. Please see the Video Walkthroughs wiki page.

Post install

Post-install, there should be:

  • An icon launcher on the Unity Bar (Ubuntu only)
  • A desktop shortcut
  • The ability to launch RetroRig by typing "retrorig" in a Terminal Window
  • The ability to find RetroRig in the Unity dash search menu (Ubuntu only)

Updating

The retrorig_setup.sh script also currently contains mechanisms to upgrade Ubuntu, update the emulator binaries, update our patched XBMC version, and also a way to pull the latest files from github. It is a good idea to load your ROMs ahead of time. If you do not, SSH accessed can be enabled in the settings menu, or you can simply use your graphical folder browser to transfer them in the respective folder under $HOME/RetroRig/ROMs.

sudo access is needed for updates, installs, and folder creation. If you wish, you can review the script code beforehand to see what sudo does.You can also choose to just copy configuration filesfrom each folder if you wish to just steal some notes on how to setup the emulators. Please reference the issues area on Github for current issues, or the release-roadmap for upcoming items.

Loading ROMs

Please place your ROMs into the applicable console system folder in:

RetroRig/ROMs

The RetroRig folder will be wherever you ran the install script. Most folks will use the default setup location of their home folder, but it should be located in your $HOME directory. When you start RetroRig for the first time, Rom Collection Browser will ask you to import your ROMs. You can choose to import for just one system or all of them. If you wish the import to be as fast as possible and don't need game scrapers, you can choose to turn them off at before importing. See the Rom Collection Browser wiki page for more.

BIOS Files:

A short note from PK:
I will not provide any BIOS/ROM files for systems that require them. It is far too much a legal gray area I will not step into. Please to not request or report games not launching with the systems noted below if you have not placed your BIOS files in the right locations.

Please Note:
The following consoles/emulators require BIOS files to function:

  • Neo-Geo CDZ (MESS)
  • Neo-Geo AES (MESS)
  • PS1/PSX (Mednafen)
  • PS2 (PCSX2)
  • Atari Lynx (Mednafen)
  • Various MAME titles (MAME)

In order to use these emulators, you must place the required zip file containing the necessary files into the RetroRig/BIOS/[emulator] folder, or within the ROMs directory for that system. Both paths can be used interchangeably. For example, for Neo-Geo CDZ, place the zip file "neocdz.zip" into the Retrorig/BIOS/MESS folder. You can use the "BIOS checker" feature of the settings menu to verify any available ROM sets.

Please refer to the given emulators wiki page under Individual Components for more. Also, see the external documentation wiki section for help on naming the zip files, and caveats to watch out for.

MESS BIOS Files:

You may run mess [system_name] -verify on the command line to do the same as what the BIOS checker does internally for MESS. For example, for Neo-Geo CDZ, run mess neocdz -verify Take note that MESS uses a single dash mark, unlike most common Unix/Linux commands, which use two dash marks (with a single dash to separate words).

For example, if you want to know which BIOS files a required MESS console needs, simple try to run the game. See the MESS wiki page for details on launching games with MESS under RetroRig.

Using VirtualBox

Warning!
VirtualBox support exists, (to an extent), but can behave erratcially with emulator speed/framerates and is not advised. I do hope to corrrect some of that in due time, but right now, it is more of an "extra" or a "test bed."

Using an Xbox controller (wired or wireless) is not without a few caveats with software such as VirtualBox. With a guest OS, your PC will be sharing your USB controller. All that is needed from the host, is sharing the USB host connection. The init scripts and configurations will still work after the filter is properly addded (see USB section below).

Suggested VM Settings

Below are the suggested settings for running RetroRig under a virtual machine guest OS. If you experience any issues, be sure to submit an issue on the main github project page for RetroRig.

General
  • Name: Ubuntu
  • Type: Linux
  • Version: Ubuntu (64 bit)
System

Motherboard:

  • Base Memory: 2048 MB minimum
  • Chipset: PIIX3
  • Pointing device: USB Tablet
  • Extended Features: Enable I/O APIC, Hardware Clock in UTC Time

Processor:

  • Processor(s): 1 or more

Acceleration:

  • Enable VT-x/AMD-V
  • Enable Nested Paging
Display

Video:

  • Video Memory: 64 MB (recommended)
  • Monitor Count: 1
  • Extended Features: Enabled 2D Acceleration (recommended)
  • Extended Features: Enabled 3D Acceleration (optional)
Storage
  • Controller Type: SATA
  • Disk size: 40 GB (minimum reccomended)
USB

alt text

  • Before beginning, make sure the Xbox controller, or wireless hub is connected to your host system
  • You do not need to load xboxdrv or configure the gamepad, the host OS will detect the USB controller
  • RetroRigs installation contains the necessary configuration files
  • Ensure "Enable USB Controller" is selected
  • Ensure "Enable USB 2.0 (EHCI) Controller" is selected
  • Make sure You add your connected controller on your host OS to the "USB Device Filters" section. The name will appear something like:
Microsoft Corporation Controller [0114]
Shared folders
  • It may be useful to share a folder here if you store your ROMs on the host OS.

About the Branches/Plaforms

I make daily changes to this project, so if you notice something wrong, please submit an issue. There are several branches, noted below. The best thing to do is check the branches pull down menu on the main github page, or the github page stub here.

  • master - main repository, documents, readme (stable)
  • Beta - upcoming changes being tested, code fixes, enhancements, and more (unstable)

You can use and play around with the other branches by "checking out" another branch like so

git checkout beta

You can check which branch you are on with:

git status

The beta branch is mainly for development purposes, and should be considered "unstable."

When you "checkout" a new branch, the files in the source folder of RetroRig literally change instantly (or near instantly). It is a good idea to quit any work in progress, or text editors beforehand, but some will let you reload the contents just fine. As far as contributing goes, you can always submit a pull request on the GitHub page or learn more about contributing from GitHub themselves here. A cheat sheet can be found at this PDF link.

RetroRig on VirtualBox may be a bit unstable and some emulators don't work quite right. I may have to adjust, note down certain video driver needs (despite using guest-additions). There is also some quirks with using a controller which is shared over from the host OS (that was fixed with a workaround).

You can refer Issue #18 for the current set of problems and potential fixes. Please see the wiki for more