gmlauncher is an Open Source game launcher written in C++ not only, but especially for custom build Arcade cabinets. What it basically does, is it reads a structure of menus and their menu entries from an XML-file and displays it. When a menu entry is triggered, it can do several kinds of things, e.g. switch to another menu or execute a specified command (to launch a game, for example). It uses SDL2 for rendering and LibXml2 for loading the menu structure and is available under the GPLv3 license.

This is what it can look like with the default theme:

My Arcade setup

I developed gmlauncher for an Arcade cabinet I've built with a friend in 2012. I used an old desktop PC from 2003 or so on which I installed Debian wheezy, which runs pretty fast considering the old hardware! On the right, you can see a photo of it running gmlauncher.

When Debian boots, slim (the login manager) automatically logs in the player user and starts a very simple configured fvwm2 session, which then, also automatically, starts gmlauncher.

The launcher can then be controlled by one of the built-in joysticks and a button, so no mouse or keyboard is necessary to start a game.


How to use gmlauncher

I do not provide any binaries for gmlauncher, so you will have to compile it yourself. The reason for this is that all the settings, except for the menu structure, are done directly in the code. In the following, I will describe how to make all the settings, compile the program and create some menus.

I have only tested these steps on Linux. If you want to use it on other OSes, it might work similarly.

Getting the source code and compiling

gmlauncher is hosted on this git repo:

To get a local copy of the source code, type (git has to be installed first):

This will download the latest code from the git repo to a new folder called "gmlauncher".

Before compiling, you will have to install the libraries SDL2, SDL2_image (with support for png and jpeg), SDL2_ttf and LibXml2, cmake and g++. Then, you should be able to compile gmlauncher like this:

If everything worked, you should now have an executable called "gmlauncher". Otherwise, the output of cmake or make should give you information about what went wrong.

Test if gmlauncher works

To test it, go back to the source directory (important, as the test theme images are also located there) and create a very basic menu structure file:

<?xml version="1.0" encoding="UTF-8"?>
<gmlauncher-menu-structure main-menu="main">
    <menu name="main" type="list">
        <entry text="Quit" action="quit" />

Save this as "menu_structure.xml" and run the executable from the same directory. Then, run the program from this directory:

If everything went well, you should see a menu with one entry to quit the program.

Configuring gmlauncher

As you might have noticed, by default, gmlauncher is not very flexible regarding the locations and names of the files it loads. Like I have written above, I will now describe how to adjust the settings inside the code.

The most important file for you will probably be include/settings.h. In this file, most important settings are done using defines. By default, it looks like this:

#ifndef _SETTINGS_H
#define _SETTINGS_H
// set to true or false
#define FULLSCREEN_ENABLED      false
// resolution
#define SCREEN_WIDTH            1024
#define SCREEN_HEIGHT           768
// defines the xml-file from where the menu structure will be loaded
#define MENU_STRUCTURE_FILE     "menu_structure.xml"
// defines where the fonts and images of the theme are
#define THEME_FOLDER            "themes/test"
// defines from where the thumbnails will be loaded
#define THUMBNAILS_FOLDER       "thumbnails"
// Key bindings
#define INPUT_KEY_UP            SDL_SCANCODE_UP

The meanings defines are either self explaining or described in the comment above. For defining Keyboard Buttons, use the SDL_Scancodes. Here's a list of all possible values:

I recommend to move the files to some global directory like /usr/share/gmlauncher. and set the defines to the absolute paths. This way, you can launch gmlauncher from anywhere on your filesystem after you installed it later.

When changing the resolution, keep in mind, that the default theme is optimized only for 1024x768. If you want to use any other resolution, you will have to use another backgound image with the desired resolution and also make some changes in src/theme.cpp in order to make it look decent. Take a look at CTheme:Load(void). Pretty much all the the positions, distances, etc. are set there.

After changing the code, of course, you will have to recompile it by calling make this inside the build directory.

Installing gmlauncher

When you are satisfied with your configuration, you can install gmlauncher, if you want, by running this in the build directory:

If you want to manually set the install prefix for cmake, re-run cmake before like this, for example (you could have also done this instead of the simple "cmake .." before):

As I've written before, if you want to install gmlaucher, I recommend to move all the files, inluding the theme, to a global directory, as only the executable is copied by the install.

Creating a Menu Structure

Now it's time to define the menu structure. This is an example that uses all possible features:

<?xml version="1.0" encoding="UTF-8"?>
<gmlauncher-menu-structure main-menu="main">
    <menu name="main" type="list">
        <entry text="Start Game" action="menu" menu="games" />
        <entry text="Quit" action="quit" />
        <entry text="Run something and quit" action="quit"
            command="executed_before_quiting" />
    <menu name="games" type="thumbs">
        <entry text="E.T. the Extra-Terrestrial" action="command"
            thumbnail="et.png" />

This should be pretty much self-explaining.