Moonlight Embedded

Moonlight is an open source game streaming host that lets you stream games from a PC with an supported GPU to your Batocera box. It's a game streaming software similar to Steam Link, a piece of hardware that was discontinued in 2018 and that now lives as an Android/iPhone app.

Batocera uses Moonlight Embedded which also works on x86_64 & embedded ARM devices like the Raspberry Pi.

The Moonlight protocol changes regularly, and you need to have a client version compatible with the Sushine Streaming Server

Moonlight is designed to stream games and applications from your PC accessible via LAN or VPN. It will not work with Cloud-streaming services like GeForce Now.

This system scrapes metadata for the “moonlight” group and loads the moonlight set from the currently selected theme, if available.

  • Emulator: moonlight
  • Folder: /userdata/roms/moonlight
  • Accepted ROM formats: .moonlight

These are the PC side prerequisites to enable Moonlight to fetch and stream your games:

It is recommended you get acquainted with the Sunshine User manual for the best experience -

If you are facing any issue, also take a look at the first topics inside Setup Guide at Moonlight wiki. They are focused on the installation at the PC site of this setup.

You need to install the Sunshine server on your gaming PC. This is the PC that will render the game assets and do all the heavy lifting. It will also compress the resulting video of the game played into a low-latency H.264 or HEVC video stream that will be sent to the Batocera Moonlight client. The Batocera Moonlight client only displays this content on the screen, and intercepts the controller actions to send them back to the Sunshine server.

  1. Download the Sunshine server corresponding to your gaming PC (they have Windows versions, both installer and portable, but also Linux packages for popular desktop Linux distributions, as well as Flatpak and Appimage versions).
  2. Launch Sunshine. Once the server is launched, you will see a message asking you to connect to a local URL to finish the configuration. Typically a URL like https://localhost:47990 – don't forget to enable a security extension on your web browser if requested.
  3. choose a username (by default sunshine) and a password. This will be required to login into the UI.

Moonlight requires a bit of manual configuration. In order to do that, you need to connect to your Batocera with SSH.

First, make sure your PC with Sunshine is up and running and on the same local network as your Batocera machine.

On Batocera box run:

# batocera-moonlight list
Searching for server...
Connect to
Generating certificate...done
You must pair with the PC first

This command correctly discovered my PC running Sunshine with its IP address, but tells me I need to pair with it. If you don't get an IP address, check you're on the same LAN or VLAN as the streaming server or you have inter-VLAN routing enabled. Although WAN connections are possible, it is not recommended.

Now let's pair with it:

# batocera-moonlight pair
Connect to
Please enter the following PIN on the target PC: 1234

The PIN 1234 is an example, you'll get a different PIN in your setup. You have to enter this PIN in the Sunshine Server PIN menu option of your server PC, once you are logged into the Sunshine configuration webpage.

Once the PIN is entered on you PC you should see Succesfully paired on your Batocera terminal.

You can check that the connection is successful by typing moonlight list again in your Batocera terminal, you should now see the list of games installed on your PC.

We now need to build the list of games we want to reference. In order to do so, enter the command:

# batocera-moonlight init
Fetching games ...
Game found: [game 1]
Game found: [game 2]
Scraping games ...
Scraping [game 1]
Scraping [game 2]

For each of the supported game installed on your PC this script has now created /userdata/roms/moonlight/*.moonlight files, a gamelist.xml and might have scraped some metadata into /userdata/roms/moonlight/downloaded_images/ as well.

It also generated a list with all games available in /userdata/system/configs/moonlight/gamelist.txt.

You can also relaunch a new game scraping with the command batocera-moonlight scrape.

Depending on your hardware configuration, you might want to tune the resolution, framerate or bitrate of the game streams. These and other Moonlight settings can be configured within Batocera from v34 by going to Advanced System Options. If you would like to enter alternate options not available through Advanced System Options you can save a file named “moonlight.conf” in the Moonlight configuration directory located at /userdata/system/configs/moonlight/. An example of a moonlight.conf file can be found here. If a moonlight.conf file is present then settings set in Advanced System Options will not be applied.

If you use an Odroid Go Advance, make sure you set the Preferred AV Decoder to “SDL” in Advance System Settings or add the line platform = sdl in the moonlight.conf configuration file, otherwise you'll have a screen rotated by 90 degrees.

Gamepad shortcuts:

  • Start+Select+L1+R1 - Quit session
  • Start - Open settings UI (when not streaming)
  • Start (press and hold) - Toggle mouse mode

Keyboard shortcuts:

  • Ctrl+Alt+Shift+Q - Quit session
  • Ctrl+Alt+Shift+X - Toggle windowed/full-screen
  • Ctrl+Alt+Shift+Z - Toggle mouse mode
  • Ctrl+Alt+Shift+S - Toggle performance stats overlay

If you encounter the following error:

Traceback (most recent call last):
  File "<string>", line 1, in <module>
KeyError: ''

it can be safely ignored. It just means that Batocera couldn't get some data from theGamesDB, so there will be some metadata missing in your gamelist.xml. Your games are still likely to be listed, though.

For further troubleshooting, refer to the generic support pages.

  • systems/moonlight.txt
  • Last modified: 5 months ago
  • by dmanlfc