PortMaster¶
PortMaster is a management software for installing and updating various ports for Linux-driven handheld video game systems. Ports are, in this case, video games which have been adapted from other systems and optimized to run natively on your handheld device. You will find more information about PortMaster on the PortMaster website.
Games¶
The PortMaster library is huge and contains almost 500 different games already. However, not all of those games will run on your respective device. Hence, when browsing the PortMaster library on your device, you will only find games which are compatible with your handheld.
The library is divided in two major categories:
- Ports which are "Ready to run" are ports of free games which you can install and immediately start playing.
- Ports with "Files needed" are ports of commercially released games. To be able to run these ports, you will have to provide essential files from the games you bought.
Some PortMaster games only run on drives which are formatted to ext4. For this reason, KNULLI formats the SHARE partition to ext4 by default. However, if you re-formatted the SHARE partition to exFAT or if you use a second SD card which is formatted to exFAT, some PortMaster games might not work on your device. You will find information on how to reformat your drive to ext4 in the Add Games section. Additionally, you will find a list of games with known issues below.
Installing PortMaster¶
After installing KNULLI for the first time, you will find the PortMaster install script (Install.PortMaster) in the Ports category. Running this script will install PortMaster on your KNULLI device and restart EmulationStation automatically. Now, you will find PortMaster in the Ports category instead of the install script.
If the PortMaster installer (Install.PortMaster) is missing from your Ports section, do not panic. This might happen, e.g., if you updated from a previous version without PortMaster or if you use an SD card which is already populated with games. In this case, you can find the installer in our Github repository. Download the file (Install.PortMaster.sh) and add it to roms/ports as you would add a game.
Managing games¶
PortMaster will automatically check for updates during launch and apply them, if necessary. Afterwards, you will find yourself in the main menu of PortMaster. Here, you can find ports to install or manage the ports on your device.
PortMaster requires an active internet connection to install and update ports.
- Featured Ports presents a hand-picked selection of ports, curated by the PortMaster team.
- All Ports contains a list of all ports which are compatible with your respective device, including ports which are ready-to-run and ports which require some additonal files.
- Ready To Run Ports contains a list of all free ready-to-run ports which you can install and immediately start playing.
- Manage Ports provides options to update, re-install, or uninstall the ports which are currently installed on your device.
There is also an Options section where you will find settings for PortMaster itself.
Installing ready-to-run games¶
To install a ready-to-run game, simply find it in the Ready To Run Ports section and install it by following the on-screen instructions. Once you are done installing your games, exit PortMaster from the PortMaster main menu. EmulationStation will restart automatically to apply the changes and detect the newly installed games. You will now find the game in the Ports category.
If the game does not show up, press Start and pick Game settings and Update gamelists to restart EmulationStation and detect new games. If that does not help, launch PortMaster, find the game in the Manage Ports section and reinstall it.
Installing games with files needed¶
To install a game with files needed, simply find it in the All Ports section and install it by following the on-screen instructions. Once you are done installing your games, exit PortMaster from the PortMaster main menu. EmulationStation will restart automatically to apply the changes and detect the newly installed games.
Now, you will have to take care of the files needed to be able to play the game. To do so, gain access to your roms/ports folder by one of the methods described in the Add Games section. In your roms/ports folder, you will find subfolders for all the ports you have installed via PortMaster. Find the subfolder which corresponds to the game you want to install.
The Games section of the PortMaster website will provide you with instructions which files you will need and where to put them. Additionally, you might find a readme file in the folder where the port is stored. Depending on the game, you might need a specific version to be compatible with the port. You will often find compatible versions of the games on GOG or Steam, however, you should read the instructions of the respective port carefully before buying the game to be sure that you found the right version of it.
After you added all the required files, the game should be ready to run. Simply go to the Ports category, find the game, and launch it!
During first launch, some ports will take some time to compress and/or compile and/or repackage files from the original game. Depending on the game, this may take several minutes, sometimes even longer. Do not panic if the first launch takes some time. Do not panic if you see a lot of command-line messages. Some games may even require several attempts to prepare all the necessary assets for playing the game on your handheld. Be patient.
If the game does not show up, press Start and pick Game settings and Update gamelists to restart EmulationStation and detect new games. If that does not help, launch PortMaster, find the game in the Manage Ports section and reinstall it.
Known issues with PortMaster games on exFAT-formatted partitions¶
As mentioned above and throughout this Wiki, many PortMaster games rely on symbolic links and very large swap files which are not supported by the exFAT file system. If you attempt to run PortMaster games from a partition which is formatted to exFAT, you might be lucky and have some games working perfectly fine. However, you will also run into games which will not work as expected.
For many games, symbolic links are implemented to put the savegames and configuration files in the right place. Without symbolic links, the files might end up as temporary files which will be deleted automatically once you quit the game. Hence, you will have to reconfigure and start over when you launch the game again.
The following list is by no means a complete list of all games which do not work. It is just a small collection of issues we are already aware of and can warn you about, issues you will run into when attempting to run these games from an exFAT-formatted SD card.
PortMaster compatibility chart¶
| Game | Runs on ext4 | Runs on exFAT | Game breaking issues on exFAT |
|---|---|---|---|
| Half-Life | None | ||
| Owlboy | Loses all settings/savegames when quit. | ||
| Stardew Valley | Loses all settings/savegames when quit. | ||
| TMNT: Shredder's Revenge | Loses all settings/savegames when quit. First-launch compile/compression fails due to swap-file size issues. |