It’s been a few years since I made a proper PortMaster guide, and there have been lots of updates to the platform since then. PortMaster started as a way for the ArkOS developer to easily collect various PC port options on their OS, but it has now grown to its own platform independent of any particular OS. This guide will help you get started with PortMaster on your favorite handheld device.

Table of Contents

What is PortMaster?
Supported devices
Installation
Port installation process
Installation examples
Porting other games
Notes

Changelog

What is PortMaster?

In a nutshell, PortMaster is a program designed for Linux-based handheld devices that organizes and simplifies the installation process for hundreds of PC ports. In its most simple form, you open the app on your device, download the PC port (and maybe add some commercial data files if necessary) from its user menu, and then launch that new PC port on your handheld once it’s been installed. These games run natively on the device, as opposed to the typical emulation you expect on these types of handhelds.

If you want the latest information about this awesome tool, I would recommend checking the official PortMaster website, which is maintained by their fantastic development team and other enthusiasts. They also have an active discord server for help with troubleshooting or if you want to help develop for the platform. Also, if you have the means, please consider donating to the project as a show of thanks for all the wonderful gaming opportunities they provide to the community.

Disclaimer: PortMaster (and porting PC games in general) is an experimental and fun project, but not perfect. The team does their best to test and confirm that these ports will be universally compatible with the 30+ handhelds that work with the platform, but there will be hiccups from time to time. It’s a complicated process, as the games, runtime files, firmware options, and the PortMaster app itself are all under constant development and improvement, which can cause bugs from time to time. If a game is not launching as expected, I would recommend checking out the PortMaster discord server to see if there are any insights from the community.

Long story short, I would not recommend buying a PC game at full price solely to play it on PortMaster, since there is a small risk that the game will not work properly on your favorite device or operating system. But if you already own the game, or you also want to play it on PC, or maybe there’s a killer sale on Steam, then it’s probably worth trying!

Also, please keep in mind that PortMaster is developed with Linux-based handhelds in mind. Android-based devices (like those from Retroid) have all sorts of excellent features and perks, such as Play Store games, effortless sleep and streaming, and more — but PortMaster is not available on Android.

Supported devices

The list of devices that are supported by PortMaster is constantly growing, and thanks to development work from the custom firmware community, it is often a matter of days before a new device has PortMaster support. There is an official list of supported devices on the PortMaster website, but it is not up to date as of making this guide (like I said, the list is constantly growing!).

Instead of focusing on an individual list of supported devices, let’s organize it by operating systems that support the platform:

• ArkOS: the initial release of PortMaster was designed by the ArkOS developer, but since then it has expanded to other communities. Thankfully, PortMaster continues to work on ArkOS!
  • Supported devices: Anbernic RG351* and RG353** series, PowKiddy RGB30 and RK2023, R35S and similar handhelds, GameForce Chi, and other legacy devices like the PowKiddy RGB10, OGA, etc.
  • * The Anbernic RG351P and RG351M devices were dropped from ArkOS support prior to PortMaster’s inception, so you will need to use the WuMMLe versions of that OS to bring PortMaster onboard.
  • ** Not all Anbernic RG353 devices are supported by ArkOS, only the RG353M, RG353V, and RG3553VS (plus the RG503, which has the same chipset). The RG353P and RG353PS devices will still generally work with the RG353M build of ArkOS, but aren’t officially supported by the developer.

• AmberELEC: formerly known as 351ELEC, one of the lead PortMaster developers also works on the AmberELEC team and so they are synced very well. Development on this OS has slowed over the years, but it’s still a solid experience for the devices work with it. Also, if you install the latest pre-release version of the OS, it will expand support to other handhelds like the R36S.
  • Supported devices: Anbernic RG351P, RG351M, RG351V, RG351MP, and RG552; PowKiddy RGB20S, XU10, R35X, R36S, D007 Plus

• ROCKNIX: formerly known as JELOS, this OS has a large range of supported devices, and some very robust Linux kernel foundation, making it streamlined and powerful.
  • Supported devices: Anbernic RG351 and RG353 series, RG-ARC, RG552, R35S and similar handhelds, PowKiddy RGB30 and X55 (among others), ODROID devices, and the GameForce Ace.

• UnofficialOS: this is a fork of JELOS that provides support to RK3326 and RK3566 devices. It no longer appears to be in active development, but PortMaster should still work on it for most games.
  • Supported devices: Anbernic RG351 and RG353 series

• The Retro Arena: this custom firmware (often stylized as TheRA) is based on Ubuntu and has various levels of support on a variety of handhelds. Many of their OS builds are in beta or unfinished states, so compatibility with PortMaster is relatively inconsistent. Your best bet is to consult their website and YouTube channel to see what projects they are currently working on.

• muOS: this OS is focused on Anbernic devices that use the H700 processor. There are some compatibility limitations with this chipset and PortMaster (many of which get better each day), and among the H700 OS options this one has the most compatibility with PortMaster.
  • Supported devices: Anbernic RG35XX Plus, RG35XX H, RG28XX, and RG35XX SP.

• KNULLI: this OS is a fork of Batocera focused on handheld devices, to include H700 chipset handheld with plans for more in the future.
  • Supported devices: Anbernic RG35XX Plus, RG35XX H, RG28XX, and RG35XX SP; TrimUI Smart Pro
  • By default, KNULLI uses an EXT4 file system for storage, which improves functionality with PortMaster. This is a Linux-readable file system, which means you can’t just plug your microSD card into a Windows/Mac computer to transfer files; instead, you will need to transfer files via a network connection (detailed in my RG35XX starter guide). If you are prioritizing PortMaster functionality on your KNULLI handheld, then keeping it at EXT4 is recommended; otherwise, it is possible to format the file system to exFAT for easier file transfers on Windows and Mac computers. More information on this subject is available in the Add Games and PortMaster sections of the KNULLI wiki.

• CrossMixOS: this is an enhanced version of the stock TrimUI Smart Pro OS, with baked-in PortMaster support.
  • Supported device: TrimUI Smart Pro
  • Note that the TrimUI Smart Pro is missing 32-bit drivers so many games (especially those with gmloaderr and box86 backends) will not run
  • Note you can also make PortMaster work on TrimUI Smart Pro’s stock OS using these tools
  • For commercial ports, their gamedata files will need to be placed in the Data > ports folder

One final note: while this guide is focused on handhelds, PortMaster is increasing support for TV boxes and SBCs within OS options like ROCKNIX. So be sure to check out the respective OS pages in case other devices you own are supported!

Installation

Note: PortMaster requires you to be connected to the Internet in order to work as intended, so be sure to connect to your local network before using it.

For most of the supported operating systems, they will already have PortMaster installed as part of the setup process. In general, you can navigate to the Ports section of that OS and find a link to the PortMaster app, and launch it from there. There are some exceptions: for example, in muOS, you can find PortMaster under their “Apps” section, and it’s in the “Tools” sections of ArkOS and ROCKNIX.

For KNULLI, you will need to run a built-in PortMaster install script the very first time. Head to Ports section on your device and choose “Install PortMaster”; once complete, it will restart EmulationStation, and under the Ports section you should now just see the PortMaster app.

If the OS doesn’t have PortMaster listed (for example if you updated from an older version of that OS), you can manually install PortMaster. There are two methods to this: you can add a custom installation script that will install PortMaster, or you can install the “full” version of this script which will include all of its runtimes (usually these are installed as needed when you install individual ports, so this just saves you that extra step later).

• Head over to the PortMaster GitHub Releases page
  • Download the latest “Install.PortMaster.sh” or “Install.Full.PortMaster.sh” file onto your computer
  • Insert your device’s microSD card (if you are using a dual-card setup, it will be whatever card you use to store your ROM files)
  • Place the .sh file of your choice into the “Ports” section of your device’s microSD card (it will usually be listed in the same section as the rest of your ROMs folders, which can vary by OS).
  • Eject your SD card and place it in your device, then navigate to the Ports section of your OS and launch the “Install PortMaster” script.
  • Once complete, you should see PortMaster in the Ports section of your device; if not, try restarting the device and checking again.

That’s it, you should now be able to launch PortMaster! If it’s been a while since you last launched the app, it will likely have an update waiting for you, and will restart the app when ready.

Port installation process

Note: PortMaster requires you to be connected to the Internet in order to work as intended, so be sure to connect to your local network before using it.

When you open PortMaster on your device, you will be be greeted by their main menu:

• Featured Ports: these are recommended ports curated by the PortMaster team.
• All Ports: this is a full list of all ports available on the platform, all 500+ of them
• Ready to Run Ports: these are freeware, open-source, or games that PortMaster got express permission to distribute. These ports fully installed directly from the PortMaster interface, no commercial files required
• Manage Ports: this will allow you to reinstall or uninstall your current ports
• Options: here you can adjust the language, theme, and sound of the PortMaster app. This section also has a Runtime Manager app, that lets you install or reinstall runtime files to make sure your games are working properly
• Exit: this exits the app, of course! You can also just press the “B” button on your device while in the main menu to exit the app

Installing “Ready to Run” ports: this process is very simple, it’s just a matter of navigating through the Ready to Run Ports section, choose your game, and install it from there. Next, exit PortMaster and you should find it in your Ports section (if you don’t see it, you may need to refresh your games list or restart the device).

Installing commercial ports: Navigate to the “All Ports” section in PortMaster, choose the game, and install it. Note that this will only install the package/wrapper and any necessary runtime files for the game, not the game itself. After that, you will need to manually add the commercial files to your microSD card. For specifics, I recommend going to the PortMaster Games page on your computer, then find your game, and click the “Details” button for that game. This will show you instructions for where to put your commercial files, and whether you need to get the game from a specific store (like Steam vs Epic vs GOG).

Installing without WiFi: if you are using a device without network connectivity, you can still install ports. To start, make sure that you install (or update) PortMaster using the latest “Install.Full.PortMaster.sh” file explained in the Installation section above. After everything is installed and updated, you will find a PortMaster folder inside of your ROMs > ports folder on your device’s microSD card. Inside that PortMaster folder, you’ll see a folder named “autoinstall”. On your computer, browse the PortMaster Games section of their website, click on the game of your choice, then click the “Download” button to download that game’s zip file. Place the zip file in the PortMaster > autoinstall folder, and then next time you start PortMaster (even if not connected to the internet) the game will install into the appropriate location and be playable.

Because the installation process for commercial ports can vary, let’s go over a few examples that will demonstrate some of the main ways to install these games.

Installation examples

Here are some installation examples for various methods and operating systems:

Simple drag-and-drop (Windows): Half-Life

For a good chunk of games, you simply need to grab your game’s data files after installing it onto your Windows PC. Most PortMaster games will work with a Steam installation, but some others may specify if it needs to be from an alternative source like Epic, GOG, or Itch.io.

• Install Half-Life on your Windows PC via Steam.
• Within your Steam client’s “Library” section, right click on the game and select Manage > Browse Local File.
• Navigate to the “valve” directory, and drag this folder’s contents to the Ports > Half-Life > valve directory on your microSD card
• Eject the SD card, put it back into your device, then launch the game via your Ports section

Simple drag-and-drop (Mac): Balatro

Sometimes the simple drag-and-drop process will work on Mac without any issue. Balatro is an easy example.

• Install Balatro on your Mac via Steam.
• Within your Steam client’s “Library” section, right click on the game and select Manage > Browse Local File.
• In Finder, you will see an app called Balatro.app. Right-click on that, then select Show Package Contents > Contents > Resources
• Find the Balatro.love file, and drag this into the Ports > Balatro folder on your microSD card
• Eject the SD card, put it back into your device, then launch the game via your Ports section

For games that require the Windows files specifically, you can still get them via Mac, by following the “Install Linux version via Steam (Mac)” section below but with the Windows version of the game instead.

Install Linux version via Steam (Windows): Shovel Knight – Treasure Trove

Sometimes, the port will require the Linux version of the game. It’s still possible to grab those files from a Windows PC, and it’s pretty easy once you get the hang of it. Let’s use Shovel Knight as our example.

• On your Windows PC, press WIN + R to bring up the Run command
• In the Run window, type steam://open/console and press ENTER
• This will open up Steam into a new tab called “Console”
• Head over to steamdb.info and search for the game (Shovel Knight: Treasure Trove in this example)
• Make note of the App ID of the game (250760), then click on the Depots section on the left and note the Linux file Depot ID (250764 as of making this guide; this number may change with future updates to the game)
• Back on the Steam Console tap, type download_depot 250760 250764 and press ENTER
• Wait a while for the game to download (it can take upwards of 20 minutes), then the console window will show you the location of the file depot
• Copy that location, then paste it into a Windows navigation bar to go directly to that folder
• Copy the folder contents (in this case it should be subfolders named 32, 64, and data) and drag them into the Ports > shovelknight > gamedata > shovelknight folder on your microSD card as specified in the PortMaster game page
• Eject the SD card, put it back into your device, then launch the game via your Ports section

Install Linux version via Steam (Mac): Undertale

Installing the Linux version of a game via Mac is also possible, and it’s pretty easy once you get the hang of it. This can also be used for ports that require the Windows version of the game when you are on a Mac. Let’s use Undertale as our example.

• On your Mac, open the Terminal app (it can be found in your Applications folder)
•  Exit out of Steam if you have it open, then type the following command /Applications/Steam.app/Contents/MacOS/steam_osx -console and press ENTER
• This will open up Steam into a new tab called “Console”
• Head over to steamdb.info and search for the game (Undertale in this example)
• Make note of the App ID of the game (391540), then click on the Depots section on the left and note the Linux file Depot ID (391544 as of making this guide; this number may change with future updates to the game)
• Back on the Steam Console tap, type download_depot 391540 391544 and press ENTER
• Wait a while for the game to download (it can take upwards of 20 minutes), then the console window will show you the location of the file depot
• Copy that location, then go to Finder > Go > Go to Folder and paste it in. You may get an error, if so you can navigate to /Users/(NameOfMac)/Library/Application Support/Steam/Steam.AppBundle/Steam/Contents/MacOS, then go to steamapps > content > app_391540 > depot_351544 and you will find your game data files
• Navigate to the assets folder, and drag this folder’s contents to the Ports > undertale > assets folder on your microSD card as specified in the PortMaster game page
• Eject the SD card, put it back into your device, then launch the game via your Ports section

Compatibility version (Windows or Mac): Stardew Valley

For games like Stardew Valley, you will need the compatibility (32-bit) version of the game.

• On your PC or Mac, open Steam and go to the Library section
• Right click on the game and select Properties
• Navigate to the Betas tab, then click on the drop-down menu and select “Compatibility”
• The game will update in Steam to download and install the required compatibility files
• Once updated, right-click on the game in your Library and select Manage > Browse Local Files
• Drag and drop these content files to the Ports > stardewvalley > gamedata folder on your SD card
• Eject the SD card, put it back into your device, then launch the game via your Ports section

DLC (Windows or Mac): TMNT Shredder’s Revenge

Some ports also support the DLC for that game, including TMNT Shredder’s Revenge. The process is mostly the same, other than an additional step of downloading the DLC files. Note that you will need to have purchased the DLC ahead of time.

• Follow the same instructions as above for installing the Linux version of a game (like Shovel Knight or Undertale above).
• The DepotID for this game will be download_depot 1361510 1361511
• Next, do the same for the DLC DepotID, which will be download_depot 1361510 2348930
• Go to the individual game data folders on your computer, then add their contents to the Ports > tmntsr > gamedata folder on your device’s microSD card
• Eject the SD card, put it back into your device, then launch the game via your Ports section

Port from an Android game: AM2R (Another Metroid 2 Remake)

Some ports, like AM2R, require the Android apk for the game. These apk files are generally available via the Internet or by using an APK extractor app if you already have the game installed on your Android device.

• Find the AM2R apk file online, there are various places to find it (although it can be a challenge due to various takedowns over the years).
• Once you have the file, rename it to am2r.apk and add it to the Ports > am2r > gamedata folder of your device’s microSD card
• Eject the SD card, put it back into your device, then launch the game via your Ports section

Port from a ROM file: Render96ex (Super Mario 64)

Some ports require a ROM file to build everything. Games like Ship of Harkinian (The Legend of Zelda: Ocarina of Time) have a more involved process, while others like Render96ex (Super Mario 64) are more straightforward; instructions are below.

• You will need the US version of Super Mario 64, its SH1 sum is 9bef1128717f958171a4afac3ed78ee2bb4e86ce
• Re-name your ROM file to baserom.us.z64
• Place the ROM file in the Ports > render96ex folder of your microSD card
• Eject the SD card, put it back into your device, then launch the game via your Ports section
• You’ll be prompted to compile resources (done automatically by the app) and install some optional add-ons, consult the Render96ex PortMaster page for additional details
• By default, this port only uses the analog stick to control Mario (and navigate the menus). D-pad-only devices will not be able to navigate the menu. Two solutions: if you are using an OS that lets you swap between d-pad and analog stick input (like muOS), then tap the POWER button to toggle to the analog stick and remap your buttons by pressing Start then R1 while in the menu; or, if you have a device that can run the same firmware and has an analog stick, load the game on that device then remap the buttons, and then put the card back into your d-pad-only device.

Note that as of making this guide, Render96ex background music is not working properly on muOS, so skip that additional add-on when first booting the game. The muOS team is aware of it and working on a fix.

Porting other games

The process of porting a game is rather complex due to the game’s engine, dependencies, OS compatibility, and more. Most games will generally require a Linux version to exist as well, which isn’t always possible. So just because a lightweight game might sound like an awesome fit for PortMaster, it doesn’t mean that a port of the game is actually feasible. A great example is Animal Well — it would be perfect on these handhelds, but it is a DirectX12 game that only runs on Windows.

If you want to suggest a port, check out the PortMaster Suggestions page. Here you can create an account and submit suggestions, and also vote on other suggestions. Before submitting, the PortMaster team recommends consulting their portability chart.

You can also filter the Suggestions page to include rejected claims, and then read about why porting them is not possible. Some good examples include Pokemon Infinite Fusion, Guacamelee, and Hades.

If you are a developer or hobbyist and want to try porting a game on your own, they have comprehensive tutorials and resources on their website to help you get started.

Notes

• If a game keeps crashing on you, there is a log.txt file generated in each port’s folder; you can reference that log (or share it on their discord) to see why the game isn’t working on your device/OS.
• PortMaster has a bunch of themes which can enhance your browsing experience, check them out! They also have a guide if you want to try making your own theme.
• For those wondering about the PC port of Celeste, that one is a little trickier, as it requires a more involved process. Here is my written guide on the subject — some of the references to devices and operating systems are outdated, but as long as you have a device with PortMaster installed, there’s a good chance this process will work on your handheld.

Changelog

24JUL2024
-added note about TrimUI Smart Pro CrossMix OS port gamedata location

13JUL2024
– added note about Android-based devices
– made a separate “porting other games” section

12JUL2024
– published guide
– added context for SM64 on muOS