Games

Here is some useful information about how Games works. For developer documentation, see the Contribute page.

Installing Games

Flatpak (recommended)

Games is available via Flatpak. The stable Flatpak version is the recommended way of getting Games.

Software should open the .flatpakref file, if this does not work, you can just run one of the following commands to install Games:

Stable version:

flatpak install https://flathub.org/repo/appstream/org.gnome.Games.flatpakref

Nightly version:

flatpak install https://nightly.gnome.org/repo/appstream/org.gnome.GamesDevel.flatpakref

Distributions

Alternatively, your software distribution may offer you packages for Games. Note that contrary to the flatpak version, distro packages may not support every platforms out-of-the-box; see the Packaged Libretro cores section below for more info.

Your games collection

Supported platforms

Every platform supported by Games is listed in the Features page.

To see which platform your current games setup can run, open the "Platforms" tab in the Preferences window. If a platform is greyed out, make sure of the following:

• you're running the latest version of Games

• you have installed the needed extension core (see the Features page to know which platform needs one)

• if you're not running the Flatpak version of Games, make sure the platform is correctly packaged in your distro.

Adding games

In order for Games to automatically discover your games, they have to be located in a searchable place. If your games don't show up, follow these steps:

• open the GNOME Settings app and click on "Search"
• click on the "Search locations" button
• open the "Other" tab and add the directories where Games is allowed to search for your games (for example, in a "Games" directory located in your home directory)
• you may need to restart your GNOME session after that in order to apply the changes (click on the "⏻" button in the top bar, "Shut down/Close session", then "Close session")

If your games are not automatically detected or if the auto-detection didn't work, you can use the "Add game files…" button to select game files to add manually.

Please note that — except if stated otherwise (e.g. MAME) — ROM files need to be unzipped for Games to list them.

Some unzipped Mega Drive ROMs come with the *.md extension, which may cause issues with your files manager and Markdown files; in that case, you can safely rename the Mega Drive ROMs extension to *.gen.

If your PlayStation games are splitted into multiple *.bin files without a cue sheet, you can generate one on this website. (see the libretro core documentation for more info)

Adding cover art manually

If your game is represented by a file, you can use the image of your choice as the game's cover by putting it alongside the game's file and by giving it a similar filename, as demonstrated in the screenshots below:

Alternatively, you could name the file cover.* or folder.*.

Running games

Retro games

Games is relying on Libretro cores to make retro games work.

Currently, the Flatpak releases of Games come bundled with functional Libretro cores, hand-picked for their good accuracy, their reasonable system requirements, their free license and their independence from proprietary (and forbidden to share) firmware files. Some cores which do not meet those requirements are still available though Flatpak extensions. The bundled cores and the existing extensions are listed in the Features page.

Packaged Libretro cores

If you don't use the Flatpak version and depending on your software distribution you may need to install Libretro cores separately. Check your distribution for more information.

Games supports only Libretro cores shipping a Libretro Core Descriptor file. The cores and their descriptors are looked for in $(libdir)/libretro directory and in paths defined in the LIBRETRO_PLUGIN_PATH environment variable. If you're encoutering issues with missing core descriptor files, please see this Ubuntu bug report for more info.

Core extensions

Some cores that cannot be bundled with the official Flatpak releases of Games (such as non-free cores) are available as Flatpak extensions; those are listed on our design page.

In order to install these, run the following commands:

PicoDrive:

flatpak install flathub org.gnome.Games.LibretroPlugin.PicoDrive

Firmware configuration

In most of the situations, no external firmware (BIOS) file should be required to play retro games. Some Libretro cores can or must use an external firmware; see the Features page to know which.

Your firmware files for a specific platform will be looked for in a specific directory depending of the version of Games you're using:

• Flatpak version: ~/.var/app/org.gnome.Games/config/gnome-games/platforms/[PLATFORM]/system, where [PLATFORM] is the corresponding platform as defined under "Known Platforms" (i.e. "TurboGrafxCD").

• Other versions: ~/.config/gnome-games/platforms/[PLATFORM]/system

The files must match the ones described by the core's descriptor. Check the cores listed in the supported platforms list and read the corresponding libretro docs page to know which firmware files are needed and how to name them.

LÖVE

Games using the LÖVE framework require LÖVE to be installed on your machine. As usual, check if your distribution supports LÖVE (the official LÖVE website provides PPAs for Ubuntu).

Gamepad handling

Controllers are automatically assigned to players following this scheme:

• when a gamepad is plugged in, it is assigned to the first player with no gamepad;
• when a gamepad is plugged out, the player which had it have no gamepad instead and any other player keep its controller;
• the keyboard is assigned to the first player with no controller after reassigning the gamepads.

Gamepad button layouts

Gamepad layouts are provided by the SDL_GameControllerDB project.

You can manually set up your own custom layout in Games.

Testing

To help ensuring that the Libretro cores we ship in the Flatpak version are of good quality, Games run reference tests powered by the retro-gtk based retro-reftest program. If you want to write such tests to improve Games or to run automated tests on your Libretro core, please read the Retro Reference Test Case Specification.

Logo

Visit the logo page to get the logos.