Skip to content

Instantly share code, notes, and snippets.

@markmals

markmals/Emulator.md

Last active October 10, 2023 16:36
Show Gist options
  • Save markmals/64172fcb0984bf1c19d72e6232787afc to your computer and use it in GitHub Desktop.
Save markmals/64172fcb0984bf1c19d72e6232787afc to your computer and use it in GitHub Desktop.
Download ZIP
Guides for setting up a Linux computer to play video games in emulators
Raw
Emulator.md

Emulator System

Guides for setting up a Linux computer to play video games in emulators.

Firmware

Software

Specs

To use all the emulators listed, you'll need a computer with these specifications:

Minimum Recommended
CPU Intel i5-4430 Intel i5-10400
GPU Intel HD Graphics 520 / NVIDIA GeForce GT 1030 2GB / AMD Radeon R7 240 2GB Intel UHD Graphics 630 / NVIDIA GeForce GTX 1650 4GB / AMD Radeon RX Vega 56 8GB
RAM 8GB 16GB

Ubuntu

Create a Bootable USB Drive

If you're on a Mac:

  1. Download the latest Ubuntu ISO
  2. Format the USB drive to MS-DOS FAT with a GUID partition map using Disk Utility
  3. Install Etcher: brew install --cask balenaetcher
  4. Flash the USB drive with the ISO using Etcher

Install

You'll want to connect to an ethernet port for hardwired internet access before installing.

Most computers will boot from USB automatically. Simply insert the USB flash drive and either power on your computer or restart it. As soon as your computer boots you’ll see the welcome window, prompting you to choose your language and either install or try the Ubuntu desktop.

If your computer doesn’t automatically boot from USB, try holding F12 when your computer first starts. With most machines, this will allow you to select the USB device from a system-specific boot menu.

When asked What apps would you like to install to start with? choose "Minimal installation". Below that, enable both "Download updates" and "Install third-party software". Then choose "Erase disk and install Ubuntu". Set up the rest of your information and the installation should complete in a few minutes.

Lakka

Lakka and Ubuntu should not be installed at the same time. If you want to use Lakka and Ubuntu, install Ubuntu and install RetroArch on Ubuntu instead, to get the same unified emulators and interface provided in Lakka. If you just want RetroArch and its interface, then Lakka is the OS for you.

Download the Lakka ISO image:

Create a bootable USB installer drive using the same instructions as for Ubuntu. You must format your hard/solid state drive(s) before booting from the Lakka installer USB drive.

To setup Lakka, boot from the flash drive, type installer, and hit return. The splash screen will appear shortly.

Choose Quick Install. The installer will list your hard drives. Select the one on which you wish to install Lakka.

At the end of this process, you will be asked to reboot. Choose Reboot and unplug your USB drive before it reboots.

The system will expand the file-systems and reboot after 30 seconds. This happens only on the first boot. The system will automatically reboot and the subsequent boots should be fast.

If everything went OK, you should now be able to navigate Lakka Menu GUI.

Switch JoyCons & Pro Controller

If your Kernel does not have the hid_nintendo driver, install it as a module from dkms-hid-nintendo:

git clone https://github.com/nicman23/dkms-hid-nintendo
cd dkms-hid-nintendo

sudo dkms add .
sudo dkms build nintendo -v 3.1
sudo dkms install nintendo -v 3.1

Install the joycond daemon:

sudo apt install libevdev-dev

git clone https://github.com/DanielOgorchock/joycond
cd joycond

cmake .
sudo make install
sudo systemctl enable --now joycond

When a controller is connected, the leds will blink waiting for you to press L+R to assign them. You can press SL+SR to use sideways joycons or L+R to merge two joycons as one device. You’ll also need to press L+R to assign a Switch Pro Controller when connected.

You can use your controllers with compatible Cemuhook UDP applications (such as Dolphin, Citra, Cemu, and Yuzu) for motion input.

Download and install joycond-cemuhook:

git clone https://github.com/joaorb64/joycond-cemuhook
cd joycond-cemuhook

pip3 install -r requirements.txt
python3 joycond-cemuhook.py

Enable cemuhook motion input in your emulator of choice.

Xbox Core Controller

Make sure you have installed dkms, linux headers and a bluetooth implementation (e.g. bluez) and their dependencies:

sudo apt-get install dkms linux-headers-`uname -r`

Clone and install xpadneo:

git clone https://github.com/atar-axis/xpadneo.git
cd xpadneo
sudo ./install.sh

Connect with Bluetooth:

sudo bluetoothctl
scan on

Wait until all available devices are listed, push the connect button on upper side of the gamepad, and hold it down until the light starts flashing fast.

Wait for the gamepad to show up in bluetoothctl, remember the MAC address (e.g. C8:3F:26:XX:XX:XX).

pair <MAC>
trust <MAC>
connect <MAC>

You'll know that everything works when you feel the gamepad rumble.

Use sudo ./configure.sh to configure the driver.

Genesis

Coming soon...

Dreamcast

Coming soon...

NES

Coming soon...

SNES

Coming soon...

N64

Install Mupen64Plus: sudo apt install mupen64plus-qt

GameBoy, GameBoy Color, & GameBoy Advance

Install VisualBoyAdvance: sudo snap install visualboyadvance-m --beta

DS

Install DeSmuME:

sudo add-apt-repository ppa:random-stuff/ppa
sudo apt update
sudo apt install desmume

GameCube & Wii

Install Dolphin: sudo snap install dolphin-emulator

3DS

Install Citra: sudo snap install citra-emu

Dumping Game Cartridges

You need a physical 3DS console in order to perform the following process and play games in Citra.

Dumping a cartridge does not dump DLC and updates for that cartridge. Those are stored on the SD card. See Dumping Installed Titles for more information.

  1. Set up GodMode9, a multipurpose tool which can do NAND and cartridge functions
    1. Download the latest release
    2. Copy GodMode9.firm from the GodMode9 .zip to a /luma/payloads/ folder on your 3DS SD card
    3. Copy the gm9 folder from the GodMode9 .zip to the root of your 3DS SD card
  2. Put the SD card into the 3DS
  3. From the root GodMode9 menu, navigate to [C:] GAMECART
  4. Select [TitleID].trim.3ds, then select NCSD image options..., then select Decrypt file (0:/gm9out)
  5. Once this process completes, the game will be a .3ds file inside /gm9/out/ and is immediately usable with Citra.

Dumping Installed Titles, Updates, & DLC

Import Data from Your 3DS SD Card with threeSD

threeSD is a tool for your computer to help import data from your 3DS for Citra more conveniently. Note that you’ll still need a hacked 3DS with GodMode9 to obtain your keys so that threeSD can decrypt the data on your SD card.

Download the latest version of the app. For Linux, you need to install Qt libraries: sudo apt install libqt5gui5

On Your 3DS

You will need to execute a GodMode9 script to dump a few files that are necessary for threeSD to properly decrypt data on your SD card. Some system files will also be copied so that they can be imported later if necessary. Please make sure you have at least 500MB of free space on your SD card before you run the script.

  1. Put the SD card in your computer.
  2. Extract the threeSD release archive and copy dist/threeSDumper.gm9 to the folder gm9/scripts on your SD card.
  3. Insert the SD card into your 3DS.
  4. Boot your device while holding (START) to launch the Luma3DS chainloader menu. Boot into GodMode9 by pressing (A).
  5. Press the HOME button to bring up GodMode9's menu, and use the D-Pad to select Scripts.... Press (A) to enter.
  6. Using the D-Pad, select threeSDumper from the scripts list. If you do not see the dumper, recheck if you have done Step 2 correctly.
  7. Press (A) to execute the script. When prompted, press (A) again to confirm.
  8. Wait for up to a few minutes. When prompted that the files have been dumped, press (A) to exit the script.
  9. Hold down the Right shoulder button and press (START) to power off your 3DS.

On Your Computer

First, put your SD card in your computer.

If you use Citra Installer or Flatpak (Recommended): Directly open threeSD from the release archive.

If you directly download Citra release ZIPs: Copy the threeSD executable to the same folder as your citra-qt executable and open it from there.

For all users:

  1. Your SD card should be listed as an auto-detected configuration. If not, recheck if your SD card is properly recognized as a disk and whether the folders threeSD and Nintendo 3DS exist in your SD card root.
  2. Press OK. Wait for a while until the contents are loaded. You should now see a list of importable contents on your SD card. Select the ones you'd like to import.
    • You can switch between Title View, which organizes contents by title name, or Group View, which organizes contents by their type.
    • System Data and System Archive contain important data that may be necessary for your imported games to run. Be sure to include them in your selection.
  3. Press OK. Your contents are now being imported. Go out to get a coffee or two - it will finish faster than you'd expect! When completed, the importable contents list will automatically be reloaded.

You can now enjoy your games with Citra, at high resolutions, with custom controllers and cheats, and even custom textures.

AES Keys

Users can provide some additional crypto keys to enable some advanced features in Citra.

Create a file at ~/.local/share/citra-emu/sysdata/aes_keys.txt:

generator=1FF9E9AAC5FE0408024591DC5D52768A
slot0x03KeyX=647C9FFB4E494E54454E444F0D0AEE88
slot0x18KeyX=82E9C9BEBFB8BDB875ECC0A07D474374
slot0x19KeyX=F5367FCE73142E66ED13917914B7F2EF
slot0x1AKeyX=EABA984C9CB766D4A3A7E974E2E713A3
slot0x1BKeyX=45AD04953992C7C893724A9A7BCE6182
slot0x1CKeyX=C3830F8156E3543B723F0BC046741E8F
slot0x1DKeyX=D6B38BC759417596D619D6029D13E0D8
slot0x1EKeyX=BB623A97DDD793D757C4104B8D9FB969
slot0x1FKeyX=4C28EC6EFFA3C23646078BBA350C7995
slot0x25KeyX=CEE7D8AB30C00DAE850EF5E382AC5AF3
slot0x2CKeyX=B98E95CECA3E4D171F76A94DE934C053
slot0x2DKeyX=B98E95CECA3E4D171F76A94DE934C053
slot0x2EKeyX=B98E95CECA3E4D171F76A94DE934C053
slot0x2FKeyX=B98E95CECA3E4D171F76A94DE934C053
slot0x30KeyX=C66E23128F289133F04CDB877A3749F2
slot0x31KeyX=C66E23128F289133F04CDB877A3749F2
slot0x32KeyX=C66E23128F289133F04CDB877A3749F2
slot0x33KeyX=C66E23128F289133F04CDB877A3749F2
slot0x34KeyX=6FBB01F872CAF9C01834EEC04065EE53
slot0x35KeyX=6FBB01F872CAF9C01834EEC04065EE53
slot0x36KeyX=6FBB01F872CAF9C01834EEC04065EE53
slot0x37KeyX=6FBB01F872CAF9C01834EEC04065EE53
slot0x38KeyX=B529221CDDB5DB5A1BF26EFF2041E875
slot0x3AKeyX=B529221CDDB5DB5A1BF26EFF2041E875
slot0x3BKeyX=B529221CDDB5DB5A1BF26EFF2041E875
slot0x03KeyY=76DCB90AD3C44DBD1DDD2D200500A0E1
slot0x06KeyY=24B05AAAAC0B099252030C02D1040317
slot0x07KeyY=E9ACC5ABD4AD3F0660C83C8934882F3F
slot0x2EKeyY=7462553F9E5A7904B8647CCA736DA1F5
slot0x2FKeyY=C369BAA21E188A88A9AA94E5506A9F16
slot0x31KeyY=7462553F9E5A7904B8647CCA736DA1F5
slot0x0DKeyN=E7C9FF9D4F5B6F4DC5E2F50E856F0AB2
slot0x15KeyN=2AF3BBD32CD59C06FD4ABE58651987AD
slot0x16KeyN=2AF3BBD32CD59C06FD4ABE58651987AD
slot0x19KeyN=5DDD4739037BC6A870E620B70F673504
slot0x1AKeyN=5DDD4739037BC6A870E620B70F673504
slot0x1BKeyN=5DDD4739037BC6A870E620B70F673504
slot0x1CKeyN=59F4399C2F95A4128A1FE49D4DB686DD
slot0x1DKeyN=59F4399C2F95A4128A1FE49D4DB686DD
slot0x1EKeyN=59F4399C2F95A4128A1FE49D4DB686DD
slot0x1FKeyN=59F4399C2F95A4128A1FE49D4DB686DD
slot0x24KeyN=BBE8B4E09D0937816B234D8EB3CD3CA2
slot0x2DKeyN=3ED6F5CF2CC37C54655000B7C8B52E0D
slot0x2EKeyN=3ED6F5CF2CC37C54655000B7C8B52E0D
slot0x2FKeyN=3ED6F5CF2CC37C54655000B7C8B52E0D
slot0x31KeyN=59FC817E6446EA6190347B20E9BDCE52
slot0x32KeyN=B87E64018B190FFE048A8124C6454196
slot0x36KeyN=28C0D59B736657BCDF50FF174979958A
slot0x37KeyN=28C0D59B736657BCDF50FF174979958A
slot0x38KeyN=6E78A3BE9BDDDA09BFD569483F24FCE0
slot0x3BKeyN=6E78A3BE9BDDDA09BFD569483F24FCE0

Wii U

Cemu game compatability

Install Cemu

Install Wine, if not yet installed:

sudo dpkg --add-architecture i386
wget -nc https://dl.winehq.org/wine-builds/winehq.key
sudo apt-key add winehq.key
sudo add-apt-repository 'deb https://dl.winehq.org/wine-builds/ubuntu/ groovy main'
sudo apt update
sudo apt install --install-recommends winehq-stable

Adjust your Wine settings by running winecfg in Terminal. Set your Windows version to 10 and add dbghelp.dll in the Libraries tab.

Install the Microsoft Visual C++ 2017 redistributable using WineTricks:

sudo apt install winetricks
bash winetricks vcrun2017

Download Cemu from their website and extract it. Download Cemuhook, a debug helper that adds more options, and extract it to the same folder as Cemu.

Run winecfg again and add dbghelp.dll in the Libraries tab.

Download graphics packs (which improve performance) and extract them to ~/cemu/graphicPacks/.

Open Cemu: vblank_mode=0 mesa_glthread=true wine Cemu.exe

Downloading & Decrypting Games

  1. Install Python: sudo apt install python3
  2. Clone the wiiu-things toolkit: git clone https://github.com/devpytech/wiiu-things.git; cd wiiu-things
  3. Go to the Wii U Brew Title Database and find the title ID for your game under the correct region. Do this for all two or three listings in a region; these are the DLC, update, and main game.
  4. Download a game, using its title ID: python3 wiiu_cdndownload.py {titleID}
  5. Download a ticket file from https://titlekeys.ovh/ticket/{titleID}.tik. Put this ticket file in the game's directory, alongside the *.app and *.h3 files.
  6. Add this key (d7b00402659ba2abd2cb0db27fa2b656) to the wiiu_decrypt.py file on line #21.
  7. Run this script to decrypt the downloaded game:
cd {titleID}
python3 ../wiiu_decrypt.py
  1. Extract the files for emulation, from the same folder: python3 ../wiiu_extract.py

Playing Games

Open Cemu (and maybe set an alias for this command in bash or as an task bar icon): vblank_mode=0 mesa_glthread=true wine Cemu.exe

In the menu bar, choose File → Install Update/DLC and select Meta/Meta.xml for each of the directories starting with 0005000C and 0005000E. Once finished, choose File → Load and select 00050000-x/code/*.rpx.

Switch

Install Yuzu: sudo snap install yuzu

Game compatability

Open Yuzu and click File → Open yuzu folder. Create a folder named "keys" in the Yuzu folder and copy this prod.keys file into it.

In the Yuzu settings, go to Emulation → Configure → Graphics → Select OpenGL and set it to Vulkan.

PlayStation

Install PCSX-Reloaded: sudo apt install pcsxr

Game compatability

You can find PSX BIOSes here.

PlayStation 2

Install PCSX2:

sudo dpkg --add-architecture i386
sudo add-apt-repository ppa:gregory-hainaut/pcsx2.official.ppa
sudo apt update
sudo apt install pcsx2

You must also download the BIOS for a PlayStation 2 console.

Most users running on a modern PC will be able to continue normally through the emulator's configuration plugin selection without changing any settings. If you try to continue with setup and you get a warning that the GS plugin failed to load or was incompatible, see the PCSX2 configuration guide.

PCSX2 will now ask you to provide your PS2's BIOS dump. Use the "Open in Explorer" button to open the BIOS folder, and drop your BIOS files inside. Then use the "Refresh List" button to show your BIOS in the list. Click it, then hit Finish.

PlayStation 3

Install RPCS3: sudo snap install rpcs3-emu

Game compatability

The PlayStation 3 system software is required because it is utilized to load system files for the emulator such as the PlayStation 3's proprietary system libraries. You can download it from Sony's website.

Once downloaded, you must install the firmware using RPCS3's built in firmware installer found under File → Install Firmware.

PSP

Install PPSSPP: sudo snap install ppsspp-emu

Xbox

Install xemu:

sudo add-apt-repository ppa:mborgerson/xemu
sudo apt update
sudo apt install xemu

Game compatability

In order to run xemu, you must have a copy of the stuff that a real Xbox needs when it turns on:

  1. The MCPX Boot ROM image
  2. The flash ROM image (aka BIOS)
  3. A properly-formatted hard disk drive image
  4. Game disc image(s)

MCPX Boot ROM Image

MD5 (mcpx_1.0.bin) = d49c52a4102f6df7bcf8d0617ac475ed

If your MCPX dump has an MD5 of 196a5f59a13382c185636e691d6c323d, you dumped it badly and it's a couple of bytes off. It should start with 0x33 0xC0 and end with 0x02 0xEE.

Flash ROM Image (aka BIOS/Kernel)

Xbox compatible BIOS. Just like a real Xbox, running an unmodified retail BIOS will not allow booting unofficial software.

People have reported most success using the modified retail "COMPLEX 4627" BIOS.

You can find BIOS images here.

Hard Disk Drive Image

Option 1: Use a pre-built Xbox HDD image (recommended)

You can use a pre-built 8G Xbox HDD image, free of any copyrighted content, and only containing a dummy dashboard. You can download this image from here!

Note: By design, this particular drive image does not contain the official Xbox dashboard, but instead contains only a dummy dashboard. Because of this, you may see an error message when starting xemu with an unmodified retail BIOS image due to the system failing to find a properly signed dashboard.

If you would like to change your dashboard (perhaps to the official retail dashboard, or any alternative dashboard), or copy additional files over to the Xbox HDD, you can start xemu, using a modified BIOS image, and a disc containing an alternative dashboard. Then you can either install that dashboard, or connect to xemu using FTP to transfer your desired dashboard files to the HDD.

Option 2: Image your real Xbox HDD

This is the most authentic way to do it. Unlock your drive, connect it to a computer, and dd the entire contents of the drive straight to a file. This file can be used as-is with xemu.

Option 3: Build a new HDD image from scratch

You can also create an Xbox hard-disk image using XboxHDM. Directions on how to do this can be found here.

Game Disc Images

xemu requires game discs to be in the form of ".iso" disc images. You can find Xbox disc images at the Internet Archive.

Windows (VirtualBox)

Coming soon...

Windows (Wine)

Coming soon...

RetroArch

Install: sudo snap install retroarch

ROMs

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment