View source for Game Emulation with RetroPie

RetroPie is an operating system and software package for emulating old-school game systems on a Raspberry Pi. This section contains some brief tutorials for problems that I solved, or just general knowledge that helped prevent problems.

Get RetroPie here: https://retropie.org.uk/

__TOC__

= ROM Files =

== ECM File Format ==

Sometimes ROM images come in a .ecm compressed format. For instance you might have a file <span class="C">Worms Armageddon.img.ecm</span>. If you can't play the ROM in .ecm format, there is a bit of code written by a guy named Neill Corlett that converts it to a .img. Check out his blog post here: http://www.stramaxon.com/2012/04/how-to-convert-ecm-file-to-bin.html.

In case his page disappears, I've included the source code here: [[Code: unecm]].

Here's how to use it (in Linux, but the basic idea is the same on any system):

# Download the code and save as filename <code class="c">unecm.c</code>.
# Compile it with your favorite C compiler, ensure the output file has execute permissions (it usually does by default), and run the compiled program with the .ecm filename as the first argument:
#:<syntaxhighlight lang="shell">
gcc -o unecm unecm.c
chmod +x unecm
./unecm "Worms Armageddon.img.ecm"
</syntaxhighlight>
# It will create the .img file (i.e. <span class="C">Worms Armageddon.img</span>). The game is now playable in just about any emulator. I have confirmed this code works every time I've used it.

== Multi-Track Images & Missing Music ==

Some games come with multiple files that represent the tracks of a CD/DVD image. They might look something like this:

<pre>
Remote Control Dandy (Japan).cue
Remote Control Dandy (Japan) (Track 1).bin
Remote Control Dandy (Japan) (Track 2).bin
Remote Control Dandy (Japan) (Track 3).bin
Remote Control Dandy (Japan) (Track 4).bin
Remote Control Dandy (Japan) (Track 5).bin
</pre>

This is often the case with games that stored music on separate tracks. In general, <b>Track 1 is the game itself</b>, and you can play it as long as you have that file. The caveat is when you play it you won't have any music. To play the music you need all the tracks, and the <i>.cue</i> file is what ties them together. The <i>.cue</i> file will look similar to this:

<pre>
FILE "Remote Control Dandy (Japan) (Track 1).bin" BINARY
  TRACK 01 MODE2/2352
    INDEX 01 00:00:00
FILE "Remote Control Dandy (Japan) (Track 2).bin" BINARY
  TRACK 02 AUDIO
    INDEX 00 00:00:00
    INDEX 01 00:02:00
FILE "Remote Control Dandy (Japan) (Track 3).bin" BINARY
  TRACK 03 AUDIO
    INDEX 00 00:00:00
    INDEX 01 00:02:00
FILE "Remote Control Dandy (Japan) (Track 4).bin" BINARY
  TRACK 04 AUDIO
    INDEX 00 00:00:00
    INDEX 01 00:02:00
FILE "Remote Control Dandy (Japan) (Track 5).bin" BINARY
  TRACK 05 AUDIO
    INDEX 00 00:00:00
    INDEX 01 00:02:00
</pre>

In EmulationStation, you can run the game from the <i>.cue</i> file and you will have access to the music tracks (<i>.cue</i> files show up in the game menu just like the <i>.bin</i> files. Obviously, it will be the one without a track number). The problem with this is that all 6 files show up in the game menu. It looks sloppy and sometimes it's confusing.

<b>There are two possible solutions:</b>
# Re-image the cue/bin files into a single disc image using a free imaging software, such as: <html><a href="http://winiso.com">WinISO</a>, <a href="http://magiciso.com">MagicISO</a>, or some other popular software.</html>
# Hide the <i>.bin</i> files from the game menu.

<b>Hiding the <i>.bin</i> files:</b>
# Make a backup of the file <code>/etc/emulationstation/es_systems.cfg</code>.
#:<syntaxhighlight>
cd /etc/emulationstation
cp es_systems.cfg es_systems.cfg.bak
</syntaxhighlight>
# Edit the <code>es_systems.cfg</code> file and locate the line <code><name>psx</name></code> where "psx" is the system you are wanting to change.
# A few line below that you will see the line <code><extension>.bin .cue .cbn .img .iso .m3u .mdf .pbp .toc .z .znx .CUE .CBN .IMG .ISO .M3U .MDF .PBP .TOC .Z .ZNX</extension></code>.
# Remove the ".bin" from that line and save the file.
# If any of your other games were <i>.bin</i> files they will no longer show up in the game menu. You can fix this by changing all their file extensions to <i>.img</i> which is an identical format. Be sure to do this with games that you add in the future.
#:<syntaxhighlight lang="shell">
cd ~/RetroPie/roms/psx
s=$IFS;IFS=`echo -en "\n\b"`
shopt -s nocaseglob
for x in *.bin;do mv -v "$x" "${x%.bin}.img";done
shopt -u nocaseglob
IFS=$s
</syntaxhighlight>

<b>Do I Always need the <i>.cue</i> file?</b>

If a game only has one <i>.bin</i> file, you might not need the <i>.cue</i> file. Sometimes the <i>.cue</i> file references multiple tracks in a single <i>.bin</i> file, like this:
<pre>
FILE "Street Fighter Alpha 3 [SLUS-00821].bin" BINARY
  TRACK 01 MODE2/2352
    INDEX 01 00:00:00
  TRACK 02 MODE2/2352
    INDEX 01 45:46:17
</pre>
In these cases, the <i>.cue</i> file is necessary to access that second track. In other cases where the <i>.cue</i> file only references the beginning of the <i>.bin</i> file, it may not be necessary to keep it. It might look like this:
<pre>
FILE "Crash Bash [SCUS-94570].bin" BINARY
  TRACK 01 MODE2/2352
    INDEX 01 00:00:00
</pre>
Either way, the <i>.cue</i> file is so small, you may as well keep it. If you use the <b><i>hiding the .bin files</i></b> method that I talked about earlier, you can keep the <i>.cue</i> files and clean up your game menu. It may seem like a lot of work to rename a bunch of files, but it would be more work to go through every game and make sure every music track is working.

<b>I still see <i>.bin</i> files!</b>

Sometimes the gamelist doesn't update correctly. Simply move all the <i>.bin</i> files to another location, update the gamelist, and move them back. In my experiences, there won't be any problems updating the gamelist fom that point on. Here's how to do it:
<syntaxhighlight>
cd ~/RetroPie/roms/psx
mkdir temp
shopt -s nocaseglob
mv *.bin -- temp/
shopt -u nocaseglob
rm ~/.emulationstation/gamelists/psx/gamelist.xml
sudo killall emulationstation
emulationstation &
mv temp/* .
rmdir temp
</syntaxhighlight>

<b>What if I change file names?</b>

For multi-track games, if you change the names of the individual <i>.bin</i> files, you need to edit the <i>.cue</i> file in a text editor so that it has the correct filenames.

== What's With These File Formats?: IMG, BIN, CUE, CCD, SUB ==

<table class="nice" style="width:800px">
<tr>
<th style="width:120px">
<b>File Extension</b>
</th>
<th style="width:400px">
<b>Description</b>
</th>
<th style="width:150px">
<b>Necessity</b>
</th>
</tr>


<tr>
<td>
.img
</td>
<td>
Contains data from the disc. This file contains the actual game data. It is identical the the <i>.bin</i> format.
</td>
<td>
Necessary to play or burn.
</td>
</tr>


<tr>
<td>
.bin
</td>
<td>
Contains data from the disc. This file contains the actual game data. It is identical the the <i>.img</i> format. Additionally, multi-track images will usually be <i>.bin</i> files. Track 1 is usually the only one necessary to play the game, although the other tracks may contain other data such as music. In this case, a <i>.cue</i> file is necessary to index the associated files.
</td>
<td>
Necessary to play or burn.
</td>
</tr>


<tr>
<td>
.cue
</td>
<td>
Indexes the tracks of a disc. If a <i>.cue</i> file accompanies only a single <i>.bin</i> or <i>.img</i> file, then the <i>.cue</i> file <b>may not be necessary to play or burn.</b> If a <i>.cue</i> file accompanies multiple <i>.bin</i> files for separate tracks (or references multiple tracks within a single <i>.bin</i> file), then the <i>.cue</i> file is <b>necessary to access multiple tracks while playing or burning.</b> Without the <i>.cue</i> file, the game will likely play (from track 1) but might not play music. If the cue file is lost, it is easy to generate (via software) or write it manually.
</td>
<td>
Sometimes not necessary to play or burn. If it references multiple tracks it may be necessary.
</td>
</tr>


<tr>
<td>
.ccd
</td>
<td>
Contains information about how the disc image was created. It is generated by the software <html><a href="https://www.redfox.bz/clonecd.html">CloneCD</a></html>. The information can be used by CloneCD to recreate the exact configurations that created the disc image. This may be useful if the disc had Digital Rights Management (DRM) protection. I have personally experienced times when <b>this file was necessary for the game to run correctly.</b>
</td>
<td>
Sometimes necessary to play or burn.
</td>
</tr>


<tr>
<td>
.sub
</td>
<td>
Contains subchannel data. It is generated by the software <html><a href="https://www.redfox.bz/clonecd.html">CloneCD</a></html>. Some forms of DRM protection make use of subchannel data tricks. CloneCD attempts to copy the disc image as close to the original as possible by saving subchannel data in the <i>.sub</i> file. I have personally experienced times when <b>this file was necessary for the game to run correctly.</b>
</td>
<td>
Sometimes necessary to play or burn.
</td>
</tr>
</table>

= Playstation =

== Playstation Memory Cards ==

=== File Association ===

Many game emulators save game data in .srm files. This is the native in-game <b><i>save data</i></b> (like the data that a Nintendo 64 game would normally save on the cartridge) and not <b><i>save state</i></b> data which is the emulator simply taking a snapshot of the game's RAM.

Many times .srm files are saved in the same folder as the ROM and has the same name. So the ROM file <span class="c">Grandia [CD1].img</span> will have a save file <span class="c">Grandia [CD1].srm</span> and they are paired by name. If you changed the name of either file, they won't be recognized as belonging to one another. This means that once you switch to CD2, you will have to change the name of the .srm file to <span class="c">Grandia [CD2].srm</span> so that you can load your game.

=== File Formats === 

There are many save data formats. The .srm files are a generic format for any game system. They simply store the raw data that the original system would have expected to pull from its native storage media. The Playstation stored data on memory cards using flash RAM, so the .srm file for a Playstation game will contain an image of a fully formatted memory card filesystem.

The PCSXR emulator saves data in .mcr format. <b>The .srm and .mcr formats are interchangeable.</b> Simply change the file extension, and you can use the .mcr file where an .srm file is needed. Also, because PCSXR uses the .mcr files as full cards (Mcd001.mcr is memory card slot 1, Mcd002.mcr is memory card slot 2) you will also need to change the file name to match the ROM name (i.e. <span class="c">Grandia [CD1].srm</span>). 

The Mcd001.mcr file could potentially contain save data for several games, and that's fine. The same .mcr file can be copied to two locations (<span class="c">Grandia [CD1].srm</span> and <span class="c">Tekken 3.srm</span>) and they will each act as the save file for their respective game.

The .mcs format is a <b>single save</b> file that would be saved on a memory card (not the entire filesystem). This would let you swap game saves from one memory card to another.

<table class="nice top">
<tr>
<th>Whole Card Formats</th>
<th>Single Save Formats</th>
</tr><tr>
<td>
* srm
* mcr
* gme
* bin
* mcd
* mem
* vgs
* mc
* ddf
* ps
* psm
* mci
* VM1
</td>
<td>
* mcs
* psx
* ps1
* mcb
* mcx
* pda
</td>
</tr>
</table>

There is a great tool for managing Playstation memory card data called MemcardRex (http://shendosoft.blogspot.com/2014/01/memcardrex-18-released.html). It can convert between all of the formats (except srm, but you can save as mcr and change the extension). It can also extract and insert individual save files from card images. This is good for consolidating or organizing save files.

=== Extracting Data from a Physical Card ===

There is an awesome Arduino project by Shendo (http://shendohardware.blogspot.com/2013/06/memcarduino.html).

=== Auto Saving to Memory Card ===

In the current version of RetroPie, the Playstation emulator does not write to the .srm file immediately. If you save your game and exit the emulator, you might be disappointed to find that your game was <b>not</b> saved, even though the in-game memory manager said it was.

The solution is to modify the autosave interval for the Playstation emulator.

Edit the file <code>/opt/retropie/configs/psx/retroarch.cfg</code> and add or change the line:
<pre>
autosave_interval = 2 
</pre>

This sets the autosave interval to 2 seconds. This is enough in most cases.

== Playstation BIOS ==

All BIOS files are placed in <span class="C">~/RetroPie/bios</span>. They are automatically detected. It's that simple. I use "scph1001.bin". Let me <html><a target="_blank" href="https://www.google.com/search?q=scph1001.bin">Google that for you</a></html>.

== Playstation Controllers ==

=== Analog Disables D-pad ===

Playstation controllers with analog sticks generally don't like it when you use the option <code>input_player1_analog_dpad_mode = "1"</code> or <code>input_player1_analog_dpad_mode = "2"</code> (at least mine doesn't, it's a RetroLink brand). Make sure the option is "0" for the relevant player (player1 if your controller is in the first player slot). I came across a situation when playing PSX (PS1) games where if I enabled the analog sticks using the button on the controller it would disable the d-pad. <b>So the lesson is: don't set the "analog d-pad mode!" Set up the controller using the configuration tool in Emulationstation and let it be!</b>

== Swapping Discs ==

Some Playstation games come on multiple discs that need to be swapped at certain points in the game. Usually the game will display a screen that says "Insert Disc 2" and waits for you to swap discs. With a real Playstation you would simply open the lid, swap discs, and close the lid. With an emulator it's not so obvious how to do it. Here's how to do it in RetroPie:

# While the game is running, enter the <b>RetgroArch menu</b> (select + retropad X [depends on your controller configuration]).
# Select <b>Quick Menu</b>.
# Select <b>Disk Control</b>.
# Select <b>Disk Cycle Tray Status</b>. This will eject to current disc.
# Select <b>Disk Image Append</b>.
# Navigate to the location of your Playstation ROMs (ie. <code>/home/pi/RetroPie/roms/psx</code>).
# Choose the image file for disc 2.
# Disc 2 is now loaded. You should be able to continue the game. For subsequent sessions, you can start your game from disc 2.

I have yet to find our whether it will create a new .srm file with the name of disc 2. Normally when you load a game it looks for an .srm file with the same name (ie. if you run <code>Grandia (Disc 1).img</code> it will load save files from <code>Grandia (Disc 1).srm</code>). The question is: will it create a new file after the first time you save your game on disc 2? I still need to investigate this.

= Nintendo 64 =

== Optimization ==

<big><b>Cooling</b></big>

Emulating Nintendo 64 will almost certainly require extra cooling for the processor. At the very least you should be using a heatsink for passive cooling. You may get better performance with a small fan. If you plan to overclock, I highly recommend using a fan.

<big><b>Force CPU Performance Mode</b></big>

The quick way is to execute this command:
<pre>
echo "performance" |sudo tee /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor
</pre>

The long way is to follow this process:

# In Emulationstation, go to the RetroPie configuration menu.
# Select <code>Setup / Configuration (to be used post install)</code>.
# Select <code>Configure the 'runcommand' - Launch script</code>.
# Select <code>CPU configuration</code>.
# Select <code>Force performance</code>.


<big><b>Using The Right Emulator</b></big>

It seems the best performing emulators are mupen64plus-GLideN64 and mupen64plus-gles2n64 depending on the game.

# In Emulationstation, go to the Nintnedo 64 menu and select any game.
# Run the game. After a second or so, when the gray RetroArch window pops up, quickly press the A button on your controller.
# Select <code>Select default emulator for n64 ()</code> and choose <code>mupen64plus-GLideN64</code>.
# You can also select <code>Select default video mode for mupen64plus-GLideN64</code> and choose a lower resolution video mode. I usually stick with aspect ratios of 4:3. I chose <b>DMT-4</b>. Keep in mind that the NTSC and PAL options don't work with HDMI.

<big><b>Testing</b></big>

Just a note: I found that <b>Goldeneye 007</b> is one of the best games for testing. The opening sequence of the game is the perfect montage of various 2D and 3D renderings, transparency, and music that almost seems like it was designed for benchmarking.

== Configurations for Specific Games ==

There isn't a one-size-fits-all configuration for every game. Generally, you can find a good configuration for a game by going through the aforementioned process of configuring RetroArch during game launch. To make it use a particular emulator for that particular game, select, choose <code>2  Select emulator for rom ()</code>. This doesn't affect the configurations for other games. Also play around with <code>Select video mode for EMULATOR + rom ()</code> to select different video modes.

Here are some exact setups that I found worked for individual games:

<table class="nice top" style="width: 800px;">
<tr><th colspan=3>RetroArch Configurations</th></tr>

<tr>
<th>Game</th>
<th>Emulator</th>
<th>Video Mode</th>
</tr>

<tr>
<td>Goldeneye 007</td>
<td>mupen64plus-GLideN64</td>
<td>DMT-4</td>
</tr>

<tr>
<td>Harvest Moon 64</td>
<td>mupen64plus-GLideN64</td>
<td>DMT-4</td>
</tr>

<tr>
<td>Starfox 64</td>
<td>mupen64plus-GLideN64</td>
<td>DMT-4</td>
</tr>

<tr>
<td>Pokemon Snap</td>
<td>mupen64plus-GLideN64</td>
<td>DMT-4</td>
</tr>

<tr>
<td>Body Harvest</td>
<td>mupen64plus-GLideN64</td>
<td>DMT-4</td>
</tr>

<tr>
<td>Conker's Bad Fur Day</td>
<td>mupen64plus-GLideN64</td>
<td>DMT-4</td>
</tr>

<tr>
<td>Castlevania</td>
<td>mupen64plus-GLideN64</td>
<td>DMT-4</td>
</tr>

<tr>
<td>Castlevania - Legacy of Darkness</td>
<td>mupen64plus-gles2n64</td>
<td>CEA-1</td>
</tr>


<tr>
<td>The Legend of Zelda - Ocarina of Time</td>
<td>mupen64plus-gles2n64</td>
<td>CEA-1</td>
</tr>

<tr>
<td>The Legend of Zelda - Majora's Mask</td>
<td>mupen64plus-gles2n64</td>
<td>CEA-1</td>
</tr>

<tr>
<td>Super Mario 64</td>
<td>mupen64plus-gles2n64</td>
<td>CEA-1</td>
</tr>

<tr>
<td>Banjo-Kazooie</td>
<td>mupen64plus-gles2n64</td>
<td>CEA-1</td>
</tr>

<tr>
<td>Clay Fighter 63 1-3</td>
<td>mupen64plus-gles2rice</td>
<td>CEA-1</td>
</tr>

<tr>
<td>Conker's Bad Fur Day</td>
<td>mupen64plus-gles2rice</td>
<td>CEA-1</td>
</tr>

<tr>
<td>Perfect Dark</td>
<td>mupen64plus-gles2rice</td>
<td>CEA-1</td>
</tr>

</table>

== Control Mappings ==

I use a cheap, generic USB N64 controller. I don't know if it's the controller's fault, but I have yet to find an N64 emulator that has the correct control mappings by default, so it took a bit of work to find the correct configuration.

<big><b>Identifying The Device</b></big>

First we need to identify the device name. <b>Unplug</b> your controller, open a terminal, and run these commands:
<pre>
cd /dev/input
ls
</pre>

You should see files similar to these:
<pre>
by-id  by-path  event0  event1  event2  mice  mouse0
</pre>

Now plug the controller in and run the <code>ls</code> command again. You should see a new file pop up:
<pre>
by-id  by-path  event0  event1  event2  js0  mice  mouse0
</pre>

My device name is clearly <b>js0</b>. Now we can run a great utility called <code>jstest</code>:
<pre>
jstest /dev/input/js0
</pre>

This will display the current state of all the buttons on the controller:
<pre>
Driver version is 2.1.0.
Joystick (Generic   USB  Joystick  ) has 6 axes (X, Y, Z, Rz, Hat0X, Hat0Y)
and 12 buttons (Trigger, ThumbBtn, ThumbBtn2, TopBtn, TopBtn2, PinkieBtn, BaseBtn, BaseBtn2, BaseBtn3, BaseBtn4, BaseBtn5, BaseBtn6).
Testing ... (interrupt to exit)
Axes:  0:     0  1:     0  2:     0  3:     0  4:     0  5:     0 Buttons:  0:off  1:off  2:off  3:off  4:off  5:off  6:off  7:off  8:off  9:off 10:off 11:off 
</pre>

Notice the line that identifies the joystick name. Mine is called <b>Generic USB Joystick</b>. This is important to remember.

<big><b>Identify The Buttons</b></big>

While running the <code>jstest</code> utility, press buttons on your controller to identify each button number. For instance, when I press the A button, the jstest output shows button 6 is <b>on</b>.
<pre>
Axes:  0:     0  1:     0  2:     0  3:     0  4:     0  5:     0 Buttons:  0:off  1:off  2:off  3:off  4:off  5:off  6:on  7:off  8:off  9:off 10:off 11:off 
</pre>

<big><b>Setup Controller</b></big>

This does not effect the controls for Emulationstation, only game controls while running the emulator.

Before you proceed with this step, make sure you have run the N64 emulator at least once with this controller.

Backup the file <code>/opt/retropie/configs/n64/InputAutoCfg.ini</code>:
<pre>
cd /opt/retropie/configs/n64
cp InputAutoCfg.ini InputAutoCfg.ini.bak
</pre>

Now edit the file and locate the name of your controller to setup the controls according to your notes. Mine ended up looking like this:
<syntaxhighlight lang="cfg">
; Generic   USB  Joystick  _START 
[Generic   USB  Joystick  ]
plugged = True
plugin = 2
mouse = False
AnalogDeadzone = 4096,4096
AnalogPeak = 32768,32768
Mempak switch =
Rumblepak switch =
A Button = button(6)
B Button = button(8)
L Trig = button(4)
R Trig = button(5)
Start = button(9)
Z Trig = button(7)
DPad U = hat(0 Up)
DPad D = hat(0 Down)
DPad L = hat(0 Left)
DPad R = hat(0 Right)
C Button U = button(0)
C Button D = button(2)
C Button L = button(3)
C Button R = button(1)
X Axis = axis(0-,0+)
Y Axis = axis(1-,1+)
; Generic   USB  Joystick  _END 
</syntaxhighlight>

<big><b>Prevent Overwriting Config</b></big>

Even though this config file does not define the controls for Emulationstation, whenever you reconfigure a controller in Emulationstation it overwrites your custom configs, so I like to make a second backup and write protect the file:
<pre>
cd /opt/retropie/configs/n64
cp InputAutoCfg.ini InputAutoCfg.ini.bak2
chmod -w InputAutoCfg.ini
chown root:root InputAutoCfg.ini
</pre>

== Setup Hotkey for Exiting ROM ==

For some reason, Mupen64 doesn't come with the ROM exit hotkey, so we have to set it up:

# Edit the file <code>/opt/retropie/configs/all/autoconf.cfg</code> and modify the line <code>mupen64plus_hotkeys = 1</code> to <code>0</code>.
# Assuming your device is <code>js0</code> (see jstest command in previous sections), edit the file <code>/opt/retropie/emulators/mupen64plus/bin/mupen64plus.sh</code> and modify the line <code>Joy Mapping Stop = "J0B"</code> to something like <code>J0B6/B7</code> where <code>J0</code> is your device and <code>B6/B7</code> is a button combo of button 6 and button 7. If you only want to use a single button, it would look like <code>J0B6</code>.

== Control Config for Emulationstation ==

I still need to revise this, but this is my current config for using a 64 controller in Emulationstation.

<table class="nice top" style="width: 800px;">
<tr>
<th colspan="2">In Emulationstation</th>
<th>Physical Controller</th>
</tr>

<tr>
<th>Name</th>
<th>Input</th>
<th>Input Reference</th>
</tr>

<tr><td>D-PAD UP</td>
<td>AXIS 1-</td>
<td>JOYSTICK UP</td></tr>

<tr><td>D-PAD DOWN</td>
<td>AXIS 1+</td>
<td>JOYSTICK DOWN</td></tr>

<tr><td>D-PAD LEFT</td>
<td>AXIS 0-</td>
<td>JOYSTICK LEFT</td></tr>

<tr><td>D-PAD RIGHT</td>
<td>AXIS 0+</td>
<td>JOYSTICK RIGHT</td></tr>

<tr><td>START</td>
<td>BUTTON 9</td>
<td>START BUTTON</td></tr>

<tr><td>SELECT</td>
<td>BUTTON 1</td>
<td>C RIGHT</td></tr>

<tr><td>A</td>
<td>BUTTON 6</td>
<td>A BUTTON</td></tr>

<tr><td>B</td>
<td>BUTTON 8</td>
<td>B BUTTON</td></tr>

<tr><td>X</td>
<td>BUTTON 0</td>
<td>C UP</td></tr>

<tr><td>Y</td>
<td>BUTTON 3</td>
<td>C LEFT</td></tr>

<tr><td>LEFT BOTTOM</td>
<td>BUTTON 7</td>
<td>Z TRIGGER</td></tr>

<tr><td>RIGHT BOTTOM</td>
<td>BUTTON 5</td>
<td>RIGHT BUMPER</td></tr>

<tr><td>LEFT TOP</td>
<td>-NOT DEFINED-</td>
<td> </td></tr>

<tr><td>RIGHT TOP</td>
<td>-NOT DEFINED-</td>
<td> </td></tr>

<tr><td>LEFT THUMB</td>
<td>-NOT DEFINED-</td>
<td> </td></tr>

<tr><td>RIGHT THUMB</td>
<td>-NOT DEFINED-</td>
<td> </td></tr>

<tr><td>LEFT ANALOG UP</td>
<td>-NOT DEFINED-</td>
<td> </td></tr>

<tr><td>LEFT ANALOG DOWN</td>
<td>-NOT DEFINED-</td>
<td> </td></tr>

<tr><td>LEFT ANALOG LEFT</td>
<td>-NOT DEFINED-</td>
<td> </td></tr>

<tr><td>LEFT ANALOG RIGHT</td>
<td>-NOT DEFINED-</td>
<td> </td></tr>

<tr><td>RIGHT ANALOG UP</td>
<td>-NOT DEFINED-</td>
<td> </td></tr>

<tr><td>RIGHT ANALOG DOWN</td>
<td>-NOT DEFINED-</td>
<td> </td></tr>

<tr><td>RIGHT ANALOG LEFT</td>
<td>-NOT DEFINED-</td>
<td> </td></tr>

<tr><td>RIGHT ANALOG RIGHT</td>
<td>-NOT DEFINED-</td>
<td> </td></tr>
</table>

Config file: <span class="c">/opt/retropie/configs/all/emulationstation/es_input.cfg</span>
<syntaxhighlight lang="xml">
  <inputConfig type="joystick" deviceName="Generic   USB  Joystick  ">
    <input name="pagedown" type="button" id="5" value="1"/>
    <input name="start" type="button" id="9" value="1"/>
    <input name="pageup" type="button" id="7" value="1"/>
    <input name="up" type="axis" id="1" value="-1"/>
    <input name="a" type="button" id="6" value="1"/>
    <input name="b" type="button" id="8" value="1"/>
    <input name="down" type="axis" id="1" value="1"/>
    <input name="right" type="axis" id="0" value="1"/>
    <input name="left" type="axis" id="0" value="-1"/>
    <input name="select" type="button" id="1" value="1"/>
  </inputConfig>
</syntaxhighlight>

= DOSBox =

== Organizing ==

This section is about how I decided to organize files and directories for DOSBox. It's not necessary to do it this way, but later sections might make more sense if you understand my system.

The default location for PC games (DOSBox and RPix86) is <code>/home/pi/RetroPie/roms/pc</code>. It usually contains these files:
<pre>
+Start DOSBox.sh
+Start rpix86.sh
BOOTDISK.BAT
BOOTDISK.SYS
</pre>

By default, this folder is also mounted in DOSBox as the C drive, but you still start out in the Z drive and need to change to the C drive using the <code>c:</code> command (the mount command is in the script <code>+Start DOSBox.sh</code>).

[UNFINISHED]

== DOSBox Manuals ==

* https://www.dosbox.com/DOSBoxManual.html
* https://www.dosbox.com/wiki/Dosbox.conf
* https://www.mankier.com/1/dosbox

== Disabling Mouse Movement ==

One of the problems with using mouse aiming in some games is the fact that you can't disable player movement (walking) via mouse movement on the vertical axis. A game like Doom does not have vertical mouse aiming, but maybe you want to aim horizontally with the mouse. You then find that moving your mouse vertically makes you walk forward and backward. You could get used to this, but it's just awful. Your aim is off, you might walk off a ledge, and it just feels "drifty." It's sloppy.

There's a utility that disables the vertical axis called <b>novert</b>. You can get it [https://www.doomworld.com/idgames/utils/misc/novert here]. In case that link disappears, I've provided it here:

<table class="nice">
<tr>
<th>Filename</th>
<th>Description</th>
<th>Size</th>
<th>Modified</th>
<th>Link</th>
</tr>

<tr>
<td name="file">
novert.zip
</td>
<td name="desc">Novert utility for DOS.</td>
<td name="size">816B</td>
<td name="modf">6/22/2003</td>
<td name="link">
<html><a href="https://beardedmaker.com/wiki/images/files/retropie/novert.zip">
Download
</a></html>
</td>
</tr>
</table>

== Unix-like Shell Commands ==

I spend most of my computer time on a Linux command line, so for the sake of comfort I decided to create some utilities in DOSBox that roughly emulate the behavior of common shell commands. I included some aliases that I often make on Linux.

I created a directory called <code>C:\UTIL</code> to store my utilities.

In the main DOSBox configuration file, under the <code>[autoexec]</code> section, I redefined the path variable:
<pre>
[autoexec]
# Lines in this section will be run at startup.
# You can put your MOUNT lines here.

PATH=Z:\;C:\UTIL
</pre>

Each file I put in <code>UTIL</code> will be a script or executable that I rename to be Unix-like.

<b>LS.BAT</b>
<pre>
:: Emulates the 'ls' command. Takes '-l' as argument for long listing.
@echo off

if "%1" == "-l" goto longlist
dir/w %1 %2 %3
goto end

:longlist
dir/p %2 %3 %4

:end
</pre>

<b>CLEAR.BAT</b>
<pre>
:: Emulates the 'clear' command.
@echo off
cls
</pre>

<b>C.BAT</b>
<pre>
:: Alias for 'clear'.
@echo off
cls
</pre>

<b>EDIT.EXE</b>

This one is not a Unix-like command, but it can be renamed to anything you want.

I downloaded MSEDIT from here: http://www.ibiblio.org/pub/micro/pc-stuff/freedos/files/distributions/1.2/repos/pkg-html/msedit.html

Unzip the file and find <code>MSEDIT.EXE</code> under <code>BIN</code>. <i>md5sum for MSEDIT.EXE: 71e1b774d91c604d24314779928a99e4</i>

Copy the file to <code>UTIL</code> and rename it to EDIT.EXE. You now have the traditional DOS command EDIT.

<b>VI.EXE</b>

I would recommend just copying EDIT.EXE to VI.EXE. There is, however, a way to install vim in DOSBox.

Go to http://www.vim.org/download.php#pc and read the section on installing the <b>16 bit DOS executable</b>.

The file v<i>im71d16.zip</i> has the installation files you need, but the <i>README_dos.txt</i> (which you may want to read) can be found in the file <i>vim70rt.zip</i>. You can download it from the same webpage under <b>Runtime files</b> in the <b>OS/2</b> section.

<b>VIM.EXE</b>

I would recommend just copying EDIT.EXE to VIM.EXE. <i>(See VI.EXE for alternatives)</i>

<b>NANO.EXE</b>

I would recommend just copying EDIT.EXE to NANO.EXE. <i>The Nano binaries for DOS are no longer maintained.</i>
<br/><br/>

== Custom Game-Specific Configurations ==

<span class="red">[ Will post these as I develop them. ]</span>

= Security =

== Password Protect Samba Shares ==

=== Configuring Password Protection ===

RetroPie comes with several Samba shares enabled by default. These shares provide anyone on the network with unprotected access to files, including ROMs and configurations. You may want to restrict access to these shares.

You need to edit the file <span class="c">/etc/samba/smb.conf</span>.

You can edit this file in the RetroPie configuration tool or from the shell using your favorite text editor (nano, vi, vim).

At the end of the <span class="c">smb.conf</span> file you will see the configurations for each share, which look a bit like this:

<pre>
[share name]
parameter1 = this
parameter2 = that
[other share]
parameter1 = this
parameter2 = that
</pre>

You need to change it to not allow guests and add the 'pi' user (or whatever user you want) to the users list. Your configs should look something like this:

<pre>
[roms]
comment = roms
path = "/home/pi/RetroPie/roms"
writeable = yes
guest ok = no
create mask = 0644
directory mask = 0755
force user = pi
users = pi

[bios]
comment = bios
path = "/home/pi/RetroPie/BIOS"
writeable = yes
guest ok = no
create mask = 0644
directory mask = 0755
force user = pi
users = pi

[configs]
comment = configs
path = "/opt/retropie/configs"
writeable = yes
guest ok = no
create mask = 0644
directory mask = 0755
force user = pi
users = pi

[splashscreens]
comment = splashscreens
path = "/home/pi/RetroPie/splashscreens"
writeable = yes
guest ok = no
create mask = 0644
directory mask = 0755
force user = pi
users = pi
</pre>

Save and close the file. Now you need to add the user to the Samba user database:

<syntaxhighlight lang="shell">
sudo smbpasswd -a pi
</syntaxhighlight>

It will ask you to enter/confirm a new password for the user. If you are using a different username, replace 'pi' with the username of your choice.

Now you need to restart the samba service (next section).

=== Restarting Samba Server ===

I made this it's own section to make it easier to find in the table of contents. Some people aren't familiar with systemd and might try the traditional <code>service samba restart</code> and get the error: <code class="C"><b>unit samba.service is masked</b></code>. Systemd is the new init system in a lot of Linux distros. It's been widely adopted so it's a good idea to learn about it [https://www.digitalocean.com/community/tutorials/systemd-essentials-working-with-services-units-and-the-journal].

<b>There are two ways to manage services in systemd (samba as an example):</b>

Use the systemctl utility: 
<syntaxhighlight lang="shell">
sudo systemctl restart samba.service
</syntaxhighlight>

Or restart the services themselves:
<syntaxhighlight lang="shell">
sudo service nmbd restart
sudo service smbd restart
</syntaxhighlight>

This is only confusing for services with masked names. Back in the day (like yesterday), the name "samba" was used with the "service" utility as sort of an alias for two services: nmbd and smbd (NETBIOS and SMB). This has changed.

= General Performance =

== Power Requirements ==

Performance is severely affected by inadequate power. When the Raspberry Pi is not receiving enough power, there will be a small rainbow colored square in the top right corner of the screen. The Raspberry Pi 2 requires between 1.2 Amps and 2.5 Amps depending on the number of additional devices that draw power (game controllers, wi-fi adapters, bluetooth adapters, etc.) [https://www.raspberrypi.org/help/faqs/]. I personally use a 3 Amp power supply and I can run Playstation and Nintendo 64 games with very few performance problems.

== Faster Boot Time: Disable DHCP Timeout ==

When RetroPie boots up, it tries to obtain an IP address from the network using DHCP. If there is no network connection, it delays the boot time significantly (10-15 seconds!) as it waits for a response from a DHCP server that doesn't exist. There's no need for it to waste your time like that.

What we want is to run DHCP after EmulationStation. Log into the RetroPie and type:
<pre>
sudo systemctl disable dhcpcd.service
</pre>

Now edit the file <code>/etc/rc.local</code>. You will see this line:
<pre>
exit 0
</pre>

Add the following command right above it to make it look like this:
<pre>
/sbin/dhcpcd -b || exit 1
exit 0
</pre>

Now restart your system. The bootup is significantly faster and it will still automatically obtain an IP address when there is a network connection.

= Appearance =

== Font Size in Game List ==

If you are using RetroPie for a portable game machine, it may be difficult to read the font in Emulationstation on a tiny screen. You can change the font size to suit your needs.

Edit the file <code>/etc/emulationstation/themes/carbon/carbon.xml</code> and look for the tag <b><code><textlist name="gamelist"></code></b>. This tag may exist under multiple sections. Find the one that pertains to the view that you use (i.e. basic or detailed view).

Inside the <b>gamelist</b> tag look for a <b><code><fontSize></code></b> tag. Mine is <b>0.038</b> by default. For a 640x480 screen, I found that <b>0.05</b> was a good font size.

Be sure to restart Emulationstation after making the change.

== Hiding Unused Emulators ==

If you don't want Emulationstation to display certain emulators, simply move their ROM folders to another location. The ROM folders are located in <span class="c">~/RetroPie/roms</span>. I usually create a subfolder in there called <span class="c">OTHER</span>.

<syntaxhighlight lang="shell">
cd ~/RetroPie/roms
mkdir OTHER
mv atari2600 OTHER/
</syntaxhighlight>

Restart Emulationstation when you are done.

= MAME (mame4all) =

== Input (Controls) ==

=== Multiple Buttons for One Input ===

When configuring input settings for the <b>mame4all</b> emulator, it took me a while to realize how to configure more than one button for a single input.

Notice here where it says <b><code>P1 Button 1  LCTRL or Mouse 1 Button 1</code></b>

[[File:MameMenu004.gif|frameless]]

It's saying that <b><code>P1 Button 1</code></b> is mapped to two buttons:
* Left Control
* Mouse 1 Button 1

<b>Here are the important things to know:</b>

* To set multiple keys, just hit <b>Enter</b> on your keyboard (or the <b>UI select button</b> configured on your joypad) and enter the first key you want to set. Now hit <b>Enter</b> again and hit the second key and <b>HOLD IT</b> (sometimes not necessary, but it works).
* You can also do key combos, by the way.
* You can continue to map more buttons to the same input, but what if you want to start over? Just move your cursor away (up one or down one) then move back to it. Now you can hit <b>Enter</b> and set a new key.
* When the key mappings are too long to display, it will show an ellipses (...). When you move the cursor over it, it will display the key mappings in a box.
*To unset a key mapping, hit <b>Enter</b> and press <b>Escape</b>. The key mapping now says "None." If you actually want to map the input to the Escape key, you can just hit <b>Enter</b> again and press <b>Escape</b>, and this time it will actually map it.

= RetroArch =

== Change/Remove Keybindings ==

I occasionally found the default RetroArch keybindings somewhat annoying. The keybinding to reset the ROM on most controllers is <i>Select + B</i> which is not a common key combination but I found myself accidentally resetting the ROM on certain games. I also wanted to permanently disable save state, as it's often impossible to resist the urge to cheat.

I created this script to alter both of these keybindings in all configured controllers.

<syntaxhighlight lang="shell">
#!/bin/bash

cd /opt/retropie/configs/all/retroarch-joypads || exit 1

for file in *.cfg;do
	sed -i.bak 's/input_save_state_btn\ \=\ \".\"/input_save_state_btn\ \=\ \"nul\"/g' "$file"
	sed -i.bak 's/input_reset_btn\ \=\ \".\"/input_reset_btn\ \=\ \"nul\"/g' "$file"
done
</syntaxhighlight>

Please note that this script may not work as expected in future versions of RetroArch. This script saves a backup of each file to <code>[filename].bak</code>.