Flatpak

• Emulator: Flatpak
• Folder: /userdata/roms/flatpak
• Accepted ROM formats: .flatpak

Unlike with most systems, Flatpaks aren't actually installed to its ROM folder at /userdata/roms/flatpak. No no, here only the shortcuts to them are stored. The actual Flatpaks themselves are installed to the SAVEs folder at /userdata/saves/flatpak.

On Batocera v31, if this is your first time using Flatpak on the system, you'll have to add the repository first. One of the most popular is the Flathub repo. To do that, first connect to your Batocera via SSH or use xterm ([F1] on system list → Applications) and run the following command (while connected to the internet):

flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

Batocera v32 and higher already have this set as the default repository.

In Batocera v32 and higher, you can then launch flatpak-config from the file manager ([F1] → Applications) to search for and install Flatpaks.

Two cursors on-screen?

There's a bug affecting v32 where two cursors are displayed. The one you're controlling is the white one. This has since been fixed.

This is also where you would upgrade your packages in the future.

First of all, you need to connect to Batocera through SSH.

Then, you need to add your Flatpak remote repo to the system. One of the most popular is the Flathub repo.

 flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

Once your repo is added, you can search for the software you want to install. In our example here, we are going to install Steam. So, let's search for it:

 flatpak search Steam

 Name               Description                               Application ID                   Version       Branch Remotes
 Steam              Manage and play games distributed by Ste? com.valvesoftware.Steam          1.0.0.70      stable flathub
 Boxtron            Compatibility tool to run DOS games on S? ?Steam.CompatibilityTool.Boxtron               stable flathub
 vkBasalt           A Vulkan post processing layer for Linux  ?software.Steam.Utility.vkBasalt 0.3.2.4       stable flathub
 protontricks       A simple wrapper that does winetricks th? ?ware.Steam.Utility.protontricks 1.5.2         stable flathu
 (...)

The piece of software we want to install, Valve's Steam client, is the first one. It can be installed with:

 flatpak install com.valvesoftware.Steam

 Looking for matches?
 Found similar ref(s) for ?com.valvesoftware.Steam? in remote ?flathub? (system).
 Use this remote? [Y/n]: Y
 Required runtime for com.valvesoftware.Steam/x86_64/stable (runtime/org.freedesktop.Platform/x86_64/20.08) found in remote flathub
 Do you want to install it? [Y/n]: Y
 
 com.valvesoftware.Steam permissions:
   ipc                              network                  pulseaudio               wayland
   x11                              devices                  bluetooth                devel
   multiarch                        per-app-dev-shm          file access [1]          dbus access [2]
   system dbus access [3]           tags [4]
  
  [1] xdg-music:ro, xdg-pictures:ro, xdg-run/app/com.discordapp.Discord:create
  [2] org.freedesktop.Notifications, org.freedesktop.PowerManagement, org.freedesktop.ScreenSaver,
      org.gnome.SettingsDaemon.MediaKeys, org.kde.StatusNotifierWatcher
  [3] org.freedesktop.UDisks2, org.freedesktop.UPower
  [4] proprietary
  
        ID                                             Branch          Op          Remote           Download
 1.     org.freedesktop.Platform.Compat.i386           20.08           i           flathub          < 152.6?MB
 2.     org.freedesktop.Platform.GL.default            20.08           i           flathub          < 106.4?MB
 3.     org.freedesktop.Platform.GL32.default          20.08           i           flathub          < 114.1?MB
 4.     org.freedesktop.Platform.Locale                20.08           i           flathub          < 322.2?MB
 5.     org.freedesktop.Platform.VAAPI.Intel           20.08           i           flathub           < 11.6?MB
 6.     org.freedesktop.Platform.openh264              2.0             i           flathub            < 1.5?MB
 7.     org.freedesktop.Platform                       20.08           i           flathub          < 268.1?MB
 8.     com.valvesoftware.Steam                        stable          i           flathub           < 13.5?MB
 
 Proceed with these changes to the system installation? [Y/n]
 
        ID                                             Branch          Op          Remote           Download
 1. [?] org.freedesktop.Platform.Compat.i386           20.08           i           flathub          140.4?MB / 152.6?MB
 2. [?] org.freedesktop.Platform.GL.default            20.08           i           flathub          105.8?MB / 106.4?MB
 3. [?] org.freedesktop.Platform.GL32.default          20.08           i           flathub          113.8?MB / 114.1?MB
 4. [?] org.freedesktop.Platform.Locale                20.08           i           flathub          140.6?MB / 322.2?MB
 5. [?] org.freedesktop.Platform.VAAPI.Intel           20.08           i           flathub           11.5?MB / 11.6?MB
 6. [?] org.freedesktop.Platform.openh264              2.0             i           flathub            1.5?MB / 1.5?MB
 7. [?] org.freedesktop.Platform                       20.08           i           flathub          222.5?MB / 268.1?MB
 8. [?] com.valvesoftware.Steam                        stable          i           flathub           12.3?MB / 13.5?MB
 
 Installation complete.

Now, the Flatpak package is installed, but you need to tell Batocera to show it up in the EmulationStation menu (under Ports):

 batocera-flatpak-update

 adding Steam
 updating permissions on files.

Let's say you've got yourself a fine and dandy Flatpak package in its physical folder form and you want to tell Batocera to just use that instead of searching for it in a repository. This is simple:

1. Move the folder containing your Flatpak package to roms/flatpak/
2. Then just run flatpak install <name of package>

So for example if I had emby-theater-snap_3.0.15_amd64, I would move it to roms/flatpak/emby-theater-snap_3.0.15_amd64 and then run:

flatpak install emby-theater-snap_3.0.15_amd64.snap

Updating Flatpak packages is simple: open flatpak-config and click Upgrade. All applicable packages will be updated to their latest version. You may be asked to reboot.

Alternatively, this can be done by running the following command via SSH:

flatpak update

Type in Y and hit [Enter].

A sometimes necessary evil.

You can use the same flatpak-config tool to remove them or run the command:

flatpak uninstall <name-of-package-here>

Don't worry about spelling the package's name precisely, Flatpak will search your system for matching results and ask you if it's the correct one to uninstall first.

So you've been using Flatpak packages for a while now, you may have noticed that some applications need to install “runtimes” and other libraries to function. It's safe to leave these packages, and even multiple versions of the same package even, on a system after you no longer need the package that initially installed it. However over time they can take up quite some space, especially if you've been installing and uninstalling games as you play through them.

So you could uninstall these packages one by one, but that would take an inordinate amount of time especially if you have to shift through which packages are really no longer required and which ones are. There's a simple command you can run instead to do all that for you:

flatpak uninstall --unused

Heroic Games Launcher is an open-source launcher available on Flathub which supports launching games from the Epic Games Store using Legendary and GOG Games. Unfortunately this launcher is not as fully integrated into Batocera as Steam is so some manual work is required.

Search for “Heroic Games Launcher” and install it.

To do so from SSH:

flatpak install com.heroicgameslauncher.hgl
batocera-flatpak-update

The Heroic Games Launcher Flatpak is bugged and will not launch correctly using the default flags. You must launch via SSH using the following command:

flatpak run com.heroicgameslauncher.hgl --no-sandbox

Heroic Games Launcher will offer two services to login to. Log in to the appropriate one (or select Manage Accounts):

Your games will appear in the Library split between Epic Games and GOG. It could take a while to download all games' information and boxart.

1. Go to Library
2. Select the game
3. Select Install

1. Select Wine Manager
2. Select the desired version of Wine to be downloaded. In order of recommendation: “Wine-GE”, “Wine-Lutris” and “Proton-GE”, the rest are older versions (some games do not work with the latest versions)

1. Go to Settings → Wine → Wine Version and select the desired version of Wine.

1. Go to Library
2. Select the downloaded Windows game
3. Go to Settings
4. Select the desired version of Wine to use for that game.

1. Go to Library
2. Select a downloaded game
3. Select PLAY NOW (Windows games require Wine to be set up first)
   • Heroic Games Launcher will say “Opening the Game…” and then eventually “Playing (STOP)”

     Games may take a while to initially launch as they need to compile shaders for your hardware.

4. If playing a Windows game, confirm the Wine installation dialogue box.
5. Game start!

1. Go to Library
2. Select an installed game
3. Select Tools at the top of the window
4. Select Uninstall

Other options can be found in Settings → Other.

GeForce NOW Electron is an unofficial open-source launcher available on Flathub which supports launching games for the GeForce NOW streaming service. Unfortunately this launcher is not as fully integrated into Batocera as Steam is so some manual work is required.

Search for “GeForce NOW Electron” and install it.

To do so from SSH:

flatpak install flathub io.github.hmlendea.geforcenow-electron
batocera-flatpak-update

The GeForce NOW Electron Flatpak is bugged and will not launch correctly using the default flags. You must launch via SSH using the following command:

flatpak run io.github.hmlendea.geforcenow-electron --no-sandbox

GeForce NOW Electron offers many ways to log in, but the only one that works for now is the E-mail and password login. Make sure to log in using the regular GeForce NOW with only your E-mail and password.

1. So, create a ABYA account with your E-mail and password.
2. And log in to GeForce NOW Electron with an ABYA account with the E-mail and password options.

To play games on GeForce NOW, you can syn your Steam, Epic Store and Ubisoft stores.

1. Goes to Settings and sync your accounts
2. Select the game into Library and select to PLAY it.
   1. PAID plans: You will play as soon as possible.
   2. FREE plans: you will be waiting in a line to be able to play the game and for a couple of minutes when ready (around 20 minutes) [So, do not quit game until time ends, otherwise the game's session will shutdown before that!]. Also do not schedule a game you don't have on your library, e.g. The Witcher 3 has it's versions for Steam, Gog and Epic Store, if you have it on Steam but opens the Epic Store version, you can't play the game! This way, you will have to finish your game section, and open the correct version and wait again in line.
3. After you get access to the GeforceNOW virtual machine, you will be pop up with the game's store application, log in into, download the game, and play, just as a regular Steam, Epic Store or Ubisoft softwares.
4. It supports Gamepad, even if the tools indicate it have no controller connected to it (just make sure the game you selected has support, or play it with a mouse/keyboard plug-in).

Here are some lists of freely distributed Linux games!

Here are the default controls used in Flatpak games shown on a Batocera Retropad:

Obviously, applications designed for a mouse and keyboard interface will probably only work when those are connected.

Try one of the following:

• Update your game list: Main Menu → Game Settings → Update Gamelists.
• Flatpaks currently do not work on a NAS, if you are using a NAS try switching to internal storage.
• The application may need to not be run in the sandbox. From SSH, run flatpak run <name-of-package> --no-sandbox to test for this.

  This can be launched directly from ES by using an SH script in the ports system.

  For example, to launch the Heroic Games launcher without sandbox, save the following file to roms/ports and then update the gamelist:

  heroicgameslauncher.sh

  flatpak run com.heroicgameslauncher.hgl --no-sandbox

• SSH into Batocera and run the following: batocera-flatpak-update
• If you are on an older Batocera version (like v31 or lower) it might be a permissions issue.
  1. Press [F1] on your keyboard to enter into File Manager
  2. Ensure you are in the Share folder (left in the sidebar)
  3. Navigate to the saves folder
  4. Select everything by pressing [Ctrl] + [A]
  5. Right-click and go to Properties
  6. Click on the “Permissions” tab
  7. Click on “View Content:” and choose “Anyone”
  8. Click on “Change Content:” and choose “Anyone”
  9. Click on “Access content:” and choose “Anyone”
  10. Click on “OK”
  11. Reboot and try it
• If trying to run a Flatpak of a Windows game via a Flatpak of Wine (yes, it is complicated and there are many things that can go wrong), search the game on the ProtonDB and see what other users have said they've had to do to make it work. You may need to utilize custom launch commands to get a game working.

• If using a Nvidia GPU, make sure your official Nvidia graphics drivers are enabled and functional.
  • Sometimes, Flatpak will “forget” that you have drivers and will need to “redownload” them (you'll find Steam is suddenly lagging in its menus). Run flatpak update in the SSH and if it starts downloading org.freedesktop.Platform.GL.nvidia-###-##-## then that is what happened.
• Try reinstalling the game and ensure all of its dependencies are sorted out, with no errors.
• PC games in general (especially ones that were ported from home consoles to PC) can be buggy. Check out the PCGamingWiki for general tips, settings configurations, launch commands and patches you can apply to fix the game (just keep in mind it's focused on Windows, not Linux (and thus, not Batocera) so a lot of external programs/patches won't be compatible).

Unfortunately some games are just garbage at supporting certain controllers. Refer to the PCGamingWiki for general tips, but if you're still struggling to get your controller recognized by the game, see if it would be possible to get the game running from Steam. Once that's done, it should be possible to use Steam to configure the controls, allowing you to use any controller that would be compatible with Steam instead.

For further troubleshooting, refer to the generic support pages.