Retro Game Launcher (RGL)

Retro Game Laucnher (RGL)

Retro Game Laucnher (RGL) is a front-end for managing & launching games from arcade emulators (such as MAME) and game ports (such as DOOM). RGL works on MS-Windows, Linux and Raspberry Pi. For MS-Windows and Linux you are own your own when it comes to installing and configuring game emulators. For Raspberry Pi I recommend RetroPie. For more information see RGL at yipton.net.


History

1.1
- Updates to support NES emulator
- Added python scripts (console & GUI) to create gameinfo.dat and history.dat for a given emulator by scraping thegamesdb.net (see scripts/infocreator)
- Fix broken raspberry pi build due to missing CMake scripts for sdl-gpu
- Fixed memory leak and improved stability when scrolling through game menus

1.0
Initial version

Installation Windows (binaries)

Three simple steps:
1. Unpack the windows binaries zip file, maintaining the directory structure
2. Install the runtime rgl\install_once\vcredist_x86.exe
3. Start rgl.exe

Installation Windows (source)

RGL can be built using the free Visual Studio 2015 version. For other (older) versions you are on your own. Support is only included for 32-bit builds. Create a directory for RGL's source code. This directory is referred to as <rgl-root-dir>.

Install source code

Unzip the <linux rgl tgz file> into directory <rgl-root-dir>. In case you don't know how to unzip a .tgz file, use WinRAR.

Install additional packages

Install Videolan and set environment variable VLC_PLUGIN_PATH to VLC's plugins directory.
On my machine that is:

VLC_PLUGIN_PATH=C:\Program Files (x86)\VideoLAN\VLC\plugins

Install cmake.

Building

From the command line:

cd <rgl-root-dir>
cmake . -Bbuild
start build\rgl.sln

Visual studio opens and you can build the RGL solution in the normal way.

Running from the command line

cd <rgl-root-dir>
exe/release/rgl.exe win32_config.rc

Passing win32_config.rc as a parameter is actually optional. In Windows, RGL automatically loads win32_config.rc if it can find one.

Running/debugging from Visual Studio

Make RGL the startup project:
- In the solution explorer, right click RGL
- select "Set as Startup Project"

Set the working directory for RGL
- right click RGL
- select Properties
- In the "Configuration:" dropdown select "All Configurations"
- In the Configuration Properties tree select "Configuration->Debugging"
- Set property "Working Directory" to "$(SolutionDir).." (note: there is no slash in the directory name)

If you want to run the demos then you need to do the same as for RGL: on the command line, run them from directory <rgl-root-dir> and from Visual Studio you need to set the working directory for the demo projects the same way as for RGL.

Installation Linux

Create a directory for RGL's source code. This directory is referred to as <rgl-root-dir>.

Install source code

cd <rgl-root-dir>
tar -xvzf <linux rgl tgz file>

Install additional packages

sudo apt-get install apt-get install libsdl2-dev libsdl2-image-dev libsdl2-ttf-dev libsdl2-gfx-dev libsdl2-mixer-dev
sudo apt-get install sudo apt-get install vlc libvlc-dev
sudo apt-get install cmake

Building

cd <rgl-root-dir>
cmake . -Bbuild
cd build; make

Running

cd <rgl-root-dir>
exe/rgl linux_config.rc

Passing linux_config.rc as a parameter is actually optional. On Linux, RGL automatically loads linux_config.rc if it can find one.

Installation Raspberry Pi

Running on Raspbrry pi is best done using RetroPie, which comes with a lot of pre-compiled emulators. Building from source is the same as for standard Linux.

Running

Run RGL with the pi_system.rc file

cd <rgl-root-dir>
exe/rgl pi_system.rc

RGL comes with three system.rc files because I run it on Windows, Linux and the Raspberry pi. If you don't pass a system.rc parameter to RGL on a Linux system (including raspberry pi), it will search for linux_system.rc by default.

System configuration

RGL uses 4 configuration files:
1. system.rc: system settings, including emulator configuration settings. You need to manually configure these settings and they are described in the table below.
2. theme.rc: the theme settings (fonts, wallpaper image files, etc). You need to manually configure these settings. Details are in the section on how to create your own themes.
3. joystick.rc: joystick configuration settings. You can configure the joystick from within RGL in the system menu so there is no need to manually modify this file.
3. config.rc: user configurable settings. You can configure them from within RGL in the system menu so there is no need to manually modify this file.

system.rc configuration

RGL comes with three system.rc files because I run RGL on Windows, Linux and the Raspberry pi. If you don't pass a system.rc parameter to RGL on a Linux system (including raspberry pi), it will search for linux_system.rc by default. On Windows RGL will use win32_system.rc by default.

ParameterDefault valueDescription
System directories
Font.Dirs., fontsList of font directories, relative to current directory
Theme.DirthemeLocation of theme directory, relative to current directory
Image.Dirs., imagesList of image directories, relative to current directory. This is used by RGL themes; they don not refer to game artwork
User.DiruserLocation of user directory. RGL stores all read/write files in here; including config.rc, recent.rc, favs.rc and all media cache files
Data.DirdataLocation of the emualtor data directory; see next section on Emulator configuration
Audio.Dirs., soundsLocation of directory where audio files are stored for RGL events. Store files with the same name as the event. Supported audio formats are wav and mp3. Supported events:
- intro: startup sound
- ok: sound when ok is pressed in dialogs
- cancel: sound when cancel or escape is pressed in dialogs
- scrollh: horizonal scrolling event
- scrollv: vertical scrolling event
- scrollend: event when end of a scrolling a list is reached
System renderer
RendererSDLEither SDL or SDLGPU. For raspberry pi, use SDL; Windows and Linux will benefit from using SDLGPU
EmulatorsAdd an entry for each emulator you wish to support. Replace EMU with a name for the emulator, such as MAME, GBA etc.
EMU.ExeNameLocation of the emulator's executable
EMU.IncludeAllRomsno There are 2 ways to configure the game list for a given emulator:
1. Using a gameinfo.dat file. This file explicitely lists all games, and, for each game all metadata such as the game's category, manufacturer, year of release, etc.
2. By letting RGL create a game entry for each ROM file located in the the emulator's ROM directory

You can use the EMU.IncludeAllRoms setting to choose which method you use. For MAME I use method 1, because I've created a gameinfo.dat containing just the games supported by the MAME raspberry pi emualtor (advmame). For GBA I have created a gameinfo.dat by scraping info from thegamesdb.net. Since that it most likely not complete with regards to the GBA roms I have, I use the 2nd configuration method for GBA.
EMU.CommandLineCommandline string. The following parameter may be used, which will be substituted at run-time: %game%=game name; %romfile%=fullpath of romfile
EMU.RomFileExtensionzipString of the file extention for ROMS. For example, DOOM uses wad.
Emualtor ROM directory
EMU.RomDirectory.PathLocation of the directory containing rom files
EMU.RomDirectory.IgnoreLeading Some media collections I've downloaded (particularly GBA) look like this:
2427 - Megaman Battle Network 6 Cybeast Gregar (U).zip
In order to get the real name of the game, the prefix "2427 -" should be removed and also the "(U") postfix. That's what the leading and trailing char are for. In this case leading is '-' and trailing is '('
EMU.RomDirectory.IgnoreTrailingSee previous description
Emualtor media directoriesYou can define up to 10 media directories (MediaDirectory1 till MediaDirectory9) containing per-game artwork such as snapshot files, video files, marquees etc. For each MediaDirectory you define a logical name (such as dir_snaps), which is referred to from the theme.rc file.
EMU.MediaDirectoryMediaDirectory is the location of a directory and can be used as an alternative for configuring MediaDirectory1, MediaDirectory2 and MediaDirectory3.
In order to associate a game with its media files, internally, RGL will strip all non-alphanumeric characters from file names. What remains must match either a name in the according emulator's gameinfo.dat file or a ROM file name.

These directories are set to the following values:
EMU.MediaDirectory1.Path: EMU.MediaDirectory/snaps
EMU.MediaDirectory1.Name: dir_snaps
EMU.MediaDirectory2.Path: EMU.MediaDirectory/videosnaps
EMU.MediaDirectory2.Name: dir_videosnaps
EMU.MediaDirectory3.Path: EMU.MediaDirectory/marquees
EMU.MediaDirectory3.Name: dir_marquees
EMU.MediaDirectoryX.PathLocation of the directory containing media files
EMU.MediaDirectoryX.NameLogical name for this media directory
EMU.MediaDirectoryX.IgnoreLeadingSame behaviour as for EMU.RomDirectory.IgnoreLeading
EMU.MediaDirectoryX.IgnoreTrailingSame behaviour as for EMU.RomDirectory.IgnoreTrailing

RGL per-emulator configuration

For each emualtor, you can provide the following 3 configuration files:
1. gameinfo.dat: Describes per-game meta data
2. catmap.ini: Maps game categories
3. history.dat: Describes per-game historical data

The location of thes files is determined by 2 configuration items in system.rc. If for example you have configured the Game Boy Advance emulator in system.rc by using say GBA, then its emulator configuration files are stored in a sub-directory gba (lower-cased) of the Data.Dir directory as defined in system.rc.

Gameinfo.dat

This is a text file that provides per-game metadata. Each line in the file describes 1 game, according to this format:
name=description | clone | year | manufacturer | number of players | ignore | number of buttons | ignore | sim or alt | categories

An example is:
1941=1941 - Counter Attack (World)||1990|Capcom|2|joy8way|2|2|2P sim|Shooter / Flying Vertical

NameDefault valueDescription
nameShort name of the game. This must match the name of the rom file and artwork files. If you had set the emulator's EMU.IncludeAllRoms to yes, then RGL generates a name game from the rom file by stripping all non-alphanumeric characters from its name. The game's description will be the original ROM file name.
descriptionFull game name as is shown on screen by RGL
cloneIf this game is a clone, name of the original game
yearYear the game was released
manufacturerName of the manufacturer
number of players1Number of players
number of buttons0Number of buttons
sim-alt1PNumber of players (like 2P), followed by sim for simultaneous game play; alt for alternative game play
categoriesNoneList of categories seperated by slash. Currently, RGL only uses the first category name. All other categories are ignored

Catmap.ini

This is a text file that allows you to remap category names. Each line has the following format:
category = new category

Category is the name of the category you wish to remap. New category is the new category name.

An example is:
Misc.=Miscelaneous

History.dat

This is per-game history information according to Arcade history.
For MAME you can download one from Arcade history. For GBA I've written some scripts to scrape information from TheGamesDB.net


Create your own theme

Themes are stored in directory Theme.Dir as defined in system.rc. Every sub-directory is a theme and its name is the sub-directory name. When switching themes in RGL, the theme name is stored in config.rc.
In each theme sub-directory, file theme.rc describes the theme according to the definitions below.

NameTypeDefault valueDescription
Screen properties
Screen.WidthInteger800Screen width
Screen.HeightInteger600Screen height
Screen.FullScreenBooleanfalseRunning in full screen mode
Debug properties
Debug.ShowOutlineBooleanfalseWhen true shows a rectangle around UI objects
Debug.OutlineColorInteger0xFF0000 (red)Color in which debug outlines are drawn
Background image properties
BackgroundImageStringFilename of background image
Default text properties
DefaultFont.NameStringArimo-Regular.ttfFilename of font file
DefaultFont.SizeInteger24Font size
DefaultFont.OutlineInteger0Font outline size
DefaultFont.ColorInteger0xffffff (white)Font text color
DefaultBackgroundColorInteger0x969696 (light gray)Default background color of highlighted text
HighlightBackgroundColorInteger0xc0c0c0 (dark gray)Default background color of highlighted text
HighlightTextColorInteger0 (black)Default text color of highlighted text
Default window properties
DefaultWindow.Title.Font.NameStringDefaultFont.NameWindow title default font filename
DefaultWindow.Title.Font.SizeIntegerAutomatically calculatedWindow title default font size
DefaultWindow.Title.Font.OutlineInteger0Window title default font outline size
DefaultWindow.Title.Font.ColorInteger0xffffff (white)Window title default font text color
DefaultWindow.Title.BoldBooleanfalseWindow title default font bold property
DefaultWindow.Title.ItalicBooleanfalseWindow title default font italic property
DefaultWindow.Title.UnderlineBooleanfalseWindow title default font underlined property
DefaultWindow.Title.EclipseTextBooleanfalseWindow title if text is truncated with ... when too large
DefaultWindow.Title.HorizontalAlignmentleft|right|centercenterWindow title default horizontal alignment
DefaultWindow.Title.VerticalAlignmenttop|bottom|centercenterWindow title default vertical alignment
DefaultWindow.TitleHeightIntegerAutomatically calculatedWindow title default height
DefaultWindow.RoundedRect.RadiusXInteger25Window default horizontal rounded courner size
DefaultWindow.RoundedRect.RadiusYInteger25Window default vertical rounded courner size
DefaultWindow.RoundedRect.FrameColorInteger0Window default frame color
DefaultWindow.RoundedRect.FillColorIntegerDefaultBackgroundColorWindow default fill color
DefaultWindow.RoundedRect.FrameWidthInteger3Window default frame size
Default information window properties
InfoPrint.Font.NameStringDefaultFont.NameInformation window font filename
InfoPrint.Font.SizeIntegerDefaultFont.SizeInformation window font size
InfoPrint.Font.OutlineInteger0Information window font outline size
InfoPrint.Font.ColorInteger0xffffff (white)Information window font text color
InfoPrint.BoldBooleanfalseInformation window font bold property
InfoPrint.ItalicBooleanfalseInformation window font italic property
InfoPrint.UnderlineBooleanfalseInformation window font underlined property
InfoPrint.EclipseTextBooleanfalseInformation window if text is truncated with ... when too large
InfoPrint.HorizontalAlignmentleft|right|centercenterInformation window horizontal alignment
InfoPrint.VerticalAlignmenttop|bottom|centercenterInformation window vertical alignment
InfoPrint.TimeoutInteger3Information window time display time (in seconds) before automatically dismissing itself
InfoPrint.RoundedRect.RadiusXInteger0Information window horizontal rounded courner size
InfoPrint.RoundedRect.RadiusYInteger0Information window vertical rounded courner size
InfoPrint.RoundedRect.FrameColorInteger0Information window frame color
InfoPrint.RoundedRect.FillColorIntegerDefaultBackgroundColorInformation window fill color
InfoPrint.RoundedRect.FrameWidthInteger0Information window frame size
Default popup window properties
DefaultPopup.Text.Font.NameStringDefaultFont.NamePopup window default font filename
DefaultPopup.Text.Font.SizeIntegerAutomatically calculatedPopup window default font size
DefaultPopup.Text.Font.OutlineInteger0Popup window default font outline size
DefaultPopup.Text.Font.ColorInteger0xffffff (white)Popup window default font text color
DefaultPopup.Text.BoldBooleanfalsePopup window default font bold property
DefaultPopup.Text.ItalicBooleanfalsePopup window default font italic property
DefaultPopup.Text.UnderlineBooleanfalsePopup window default font underlined property
DefaultPopup.Text.EclipseTextBooleanfalsePopup window if text is truncated with ... when too large
DefaultPopup.Text.HorizontalAlignmentleft|right|centercenterPopup window default horizontal alignment
DefaultPopup.Text.VerticalAlignmenttop|bottom|centercenterPopup window default vertical alignment
DefaultPopup.RoundedRect.RadiusXInteger5Popup window default horizontal rounded courner size
DefaultPopup.RoundedRect.RadiusYInteger5Popup window default vertical rounded courner size
DefaultPopup.RoundedRect.FrameColorInteger0Popup window default frame color
DefaultPopup.RoundedRect.FillColorIntegerDefaultBackgroundColorPopup window default fill color
DefaultPopup.RoundedRect.FrameWidthInteger3Popup window default frame size
Default dialog properties
DefaultDialog.Margin.LeftInteger0Dialog default left margin
DefaultDialog.Margin.TopInteger0Dialog default top margin
DefaultDialog.Margin.RightInteger0Dialog default right margin
DefaultDialog.Margin.BottomInteger0Dialog default bottom margin
DefaultDialog.WidthIntegerAutomatically calculatedDialog default width
DefaultDialog.HeightIntegerAutomatically calculatedDialog default height
DefaultDialog.BackgroundMaskInteger0x808080a0Dialog default color mask when fading background behind dialog
Default control properties
Controls.FrameColorIntegerDefaultWindow.RoundedRect.FrameColorControl default frame color
Controls.FrameSizeInteger3Control default frame size
Controls.FillColorOnIntegerDefaultWindow.RoundedRect.FrameColorControl default fill color when enabled or on
Controls.FillColorOffIntegerDefaultWindow.RoundedRect.FillColorControl default fill color when disabled or off
Controls.ScrollbarThumbIntegerDefaultWindow.RoundedRect.FrameColorScrollbar thumb default fill color
Category text propertiesGame's category text control - updated when highlighting a different game
CategoryText.Rectx, y, width, height0, 0, 0, 0Default area
CategoryText.TextSimpleText<p align=center><font size=large>%cat% (%numitems%)SimpleText for when a game list is active
CategoryText.VerticalAligntop|center|bottomtopvertical alginment
CategoryText.SingleLineBooleantrueIf true, limits text to one line
CategoryText.EclipseTextBooleanfalseIf true, adds ... when text too long, otherwise truncates
CategoryText.SystemMenuTextSimpleText<p align=center><font size=large>Simpletext for when the system menu is active
2D menu properties
2DMenu.Rectx, y, width, height0, 0, 0, 02D Menu area
2DMenu.HorizontalAnimationBooleantrueIf true, horizontal scrolling animation is enabled
2DMenu.VerticalAnimationBooleantrueIf true, vertical scrolling animation is enabled
2DMenu.HorizontalAnimationDelayInteger (ms)10Delay inbetween each horizontal scrolling animation step
2DMenu.VerticalAnimationDelayInteger (ms)10Delay inbetween each vertical scrolling animation step
2DMenu.TextMenu.Font.NameStringDefaultFont.NameText item font name
2DMenu.TextMenu.Font.SizeIntegerDefaultFont.SizeText item font size
2DMenu.TextMenu.Font.OutlineIntegerDefaultFont.OutlineText item font outline size
2DMenu.TextMenu.Font.ColorIntegerDefaultFont.ColorText item font text color
2DMenu.TextMenu.Rectx, y, width, height0, 0, 0, 02D menu area for text items
2DMenu.TextMenu.Roundx0Draw the menu in a rounded curve, the higher the number, the more curved. Only used if 2DMenu.TextMenu.TextStyle=round
2DMenu.TextMenu.ItemsInteger9Number of text items in the list
2DMenu.TextMenu.TextStyleleft|center|rigt|roundleftList aligment
2DMenu.TextMenu.FontSizeSelectedInteger0Font size of the highlighted item (the middle item in the list)
2DMenu.TextMenu.FontSizeGradientFloat0.0Number that is subtracted from 2DMenu.TextMenu.Font.Size for each item further away from the highlighted item
2DMenu.TextMenu.FontColorGradientFloat0.0Number that is subtracted from 2DMenu.TextMenu.Font.Color for each item further away from the highlighted item
2DMenu.TextMenu.UseHighlightBooleanfalseIf true, draws a rounded rectangle (2DMenu.TextMenu.HighlightRect) around the highlighted area
2DMenu.TextMenu.HighlightRect.RadiusXInteger02Dmenu highlighted item rounded courner size
2DMenu.TextMenu.HighlightRect.RadiusYInteger02Dmenu highlighted item rounded courner size
2DMenu.TextMenu.HighlightRect.FrameColorInteger02Dmenu highlighted item frame color
2DMenu.TextMenu.HighlightRect.FillColorInteger02Dmenu highlighted item fill color
2DMenu.TextMenu.HighlightRect.FrameWidthInteger02Dmenu highlighted item frame size
Snapshot properties
Snap.Rectx, y, width, height0, 0, 0, 0Per-game snapshot display area
Snap.DirectoryStringLogical name of the directory where per-game snapshots image files are stored. For each emulator you configure this using EMU.MediaDirectory1.Name in system.rc.

Regardless if you specify a name, images are also searched for in the image directory list Image.Dirs as defined in system.rc. That is particularly convenient for he DefaultImage name.
Snap.FileNameStringAutomatically determinedFilename in the Snap.Directory used to display the image.
The following per-game parameter may be used, which will be substituted at run-time:
%name%: Game name
%category%: Game category
%year%: Game year of release
%man%: Game manufacturer
%playcon%: Game player control such as 1alt or 2sim
%buttons%: Game number of buttons
%game%: Game description
%players%: Game number of players
%clone%: Name of the game clone
%engine%: Game emulator name as defined in system.rc
Snap.DefaultImageStringFilename of the image that should be shown if the image configured for Snap.FileName doesn't exist
Snap.DrawModenormal|scalednormal normal: image is drawn top left of the .Rect area using the image's size
scaled: image is centered in .Rect area and scaled (maintaining aspect ratio) to fit the .Rect area
Video snapshot properties
VideoSnap.Rectx, y, width, height0, 0, 0, 0Video snapshot display area. The video is scaled (maintaining aspect ratio) to fit this area
VideoSnap.DirectoryStringLogical name of the directory where per-game video snapshot files are stored. For each emulator you configure this using EMU.MediaDirectory2.Name in system.rc
Per-game image propertiesYou can configure 9 per-game image areas Image1-Image9. The attributes are the same as for the snapshot properties (Snap as describe above
ImageN.Rect
ImageN.DirectorySee Snap, above
ImageN.FileNameSee Snap, above
ImageN.DefaultImageSee Snap, above
ImageN.DrawModeSee Snap, above
Per-game text propertiesYou can add up to 10 per-game text boxes: Text1-Text10
TextN.Rectx, y, width, height0, 0, 0, 0Per-game textbox display area
TextN.TextSimpleTextText displayed in the text box. The same per-game parameter as for Snap.Filename may be used, which will be substituted at run-time.

The text may be formatted in SimpleText formatting as described below.
TextN.VerticalAligntop|bottom|centertopVertical text alignment of the text in the textbox
TextN.SingleLineBooleantrueIf true, the textbox will only display 1 line, otherwise drawn in multiple lines if needed
TextN.EclipseTextBooleantrueIf true, single-text boxes will display ... if the text is too wide; otherwise it just gets truncated
Game info dialog properties
GameInfoDialog.WidthIntegerAutomatically calculatedWidth
GameInfoDialog.HeightIntegerAutomatically calculatedHeight
GameInfoDialog.FormatTitleSimpleText <p align=center><font size=xlarge><b> Info dialog formatting for the game title.

The text may be formatted in SimpleText formatting as described below.
GameInfoDialog.FormatHeadingSimpleText <p align=center><font size=large><b> Info dialog formatting for each section heading.

The text may be formatted in SimpleText formatting as described below.
GameInfoDialog.FormatBodySimpleText <p align=justified><font size=xxsmall> Info dialog formatting for the body text.

The text may be formatted in SimpleText formatting as described below.

SimpleText formatting

Some UI elements in RGL my be defined using the SimpleText format, which provides simple paragraph and character formatting directives.

Example:
<p align=center><font name=Arimo-Regular.ttf size=large color=0xff0000><u>Hello</u> <b>world</b>

Formatting syntax
SimpleText uses an XML/HTML-like style, for example <b>Hello</b> tags denote that "Hello" should be printed in bold. Unlike XML, the tags don't follow a strict <tag> </tag> symmetry. Instead, each <tag> is simply a formatting instruction; and it's merely convenient that tags like <b> (=bold on) have an opposite </b> (=bold off) tag.

Consider the following formatting:
<i><b><i>Hello</i></b> World</i> According to strict XML/HTML rules, both "Hello" and the entire "Hello World" would be in italic. In SimpleText, however, you should interpret the line above above as a series of formatting instructions:
italic on, bold on, italic on, Hello, italic off, bold off, World, italic off As a result, Hello is printed in both bold & italic; World will be printed without both bold and italic.

White spacing and word splitting
Just like HTML, all redundant spaces will be removed and end of lines will be ignored. Use <br> to force a line break. Also, simpletext prevents words to be split across lines.

Paragraph formatting
<p align=left|center|right|justified> Starts a new paragraph with the following rules:
- Text starts on a new line
- Character formatting is reset to defaults
- Text alignment according to the align parameter

Character formatting
<b>Bold on
</b>Bold off
<i>Italic on
</i>Italic off
<u>Undeline on
</u>Underline off
<s>Strike-through on
</s>Strike-through off
<br>Text continues on new line with same character formatting
<font name="fontname" size=fontsize color=textcolor> name:
- name of a supported font file, like courier.ttf; or
- default: reset to default font name
size:
- either a number like 8 or 32, or;
- xxlarge, xlarge, large, small, xsmall, xxsmall, or;
- default: reset to default font size
color:
- either a number like 0, 2; or
- hex number like 0xff or 0xffffff; or
- default: reset to default font color

Default character formatting:
Default font name, size and text color are according to RGL's theme "Default text properties", see above.