Differences

This shows you the differences between two versions of the page.

--- systems:ports [2022/03/31 01:04] – [Simple itch.io game example: Skatebird] typo, amend tip atari
+++ systems:ports [2026/02/25 08:23] (current) – [Vulkan dependent game example: "Teenage Mutant Ninja Turtles: Shredder's Revenge" (Linux patched version)] , script should be called TMNT respectedprophet
@@ Line 1: / Line 1: @@
 <WRAP group>
 <WRAP round box twothirds column>
-{{ https://raw.githubusercontent.com/fabricecaruso/es-theme-carbon/master/art/logos/ports.svg?nolink&300 }}
+{{ https://raw.githubusercontent.com/fabricecaruso/es-theme-carbon/master/art/logos/ports.svg?nolink&380 }}
 ====== Ports (native to Linux) ======
@@ Line 55: / Line 55: @@
 </file>
-Refresh the game list, and then launch your game. Most 3D games will spend some time generating shader caches when first booting up, so be patient at least on the first launch. For sanity's sake, you can check that your system has not frozen by moving your mouse around (if you have one connected). Shader compilation should not take longer than five minutes at most.
+Save this script to the ''roms/ports'' folder, refresh the game list, and then launch the game. Most 3D games will spend some time generating shader caches when first booting up, so be patient at least on the first launch. For sanity's sake, you can check that your system has not frozen by moving your mouse around (if you have one connected). Shader compilation should not take longer than five minutes at most.
+<WRAP center round important>
+If using the [[:disk_image_compression#squashfs|SquashFS]] compression, this script file must be named ''run.sh'' and included in the root folder of the game's data itself in the ''.squashfs'' archive.
+</WRAP>
 If you'd like to see the actual files, you can install some native Linux ports in the [[:content_downloader|content downloader]]. Read below for some setup examples:
@@ Line 63: / Line 67: @@
 </WRAP>
-==== Simple itch.io game example: Skatebird ====
+==== Self-contained itch.io game example: Skatebird ====
 [[https://glassbottommeg.itch.io/skatebird|Skatebird]] can be purchased and downloaded from its itch.io page. Make sure it's the "Linux" version!
@@ Line 79: / Line 83: @@
 The ''unclutter-remote -s'' and ''unclutter-remote -h'' commands are to **s**how and **h**ide the mouse cursor respectively. It's a good idea to first show it when setting up the game, in case it's needed.
 </WRAP>
-  - Back in Batocera, hit ''[F1]'' and navigate to ''roms/ports/.data'', right-click the ''Skatebird.sh'' file, go to **Properties** and make it executable by "Anyone".\\ {{:systems:executable_permission_bit.png|}}
-  - Press ''[Ctrl]'' + ''[Q]'' to exit back to Batocera.
   - Press ''[START]'' -> **GAME SETTINGS** -> **REFRESH GAMELISTS**.
-  - Navigate to the Ports system, then launch "Skatebird".
+  - Navigate to the "Ports" system, then launch "Skatebird".
 <WRAP center round important>
@@ Line 92: / Line 94: @@
 As already mentioned above, the ''/userdata/roms/ports/.data'' folder is where you want to place your game's main folder which contains the according native Linux game. The following example will show how you can make the popular game [[http://www.celestegame.com/|Celeste]] running on Batocera.
-First of all, you will have to buy/download the native Linux version of //Celeste//, which will give you a single package file, e.g. ''celeste-linux.zip''.
+First of all, you will have to buy/download the native Linux version of Celeste, which will give you a single package file, e.g. ''celeste-linux.zip''. After successfully downloading, copy the file over from your local computer to your Batocera system (for example via [[:winscp|WinSCP]]) to the following path: ''/tmp/celeste-linux.zip''.
-After successfully downloading, copy the file over from your local computer to your Batocera system (for example via [[:winscp|WinSCP]]) to the following path: ''/tmp/celeste-linux.zip''.
 Now [[:access_the_batocera_via_ssh|SSH]] into your Batocera system and execute the following command to extact the package file's content to the correct path:
 <code>unzip -d /userdata/roms/ports/Celeste /tmp/celeste-linux.zip</code>
 <WRAP center round tip>
-In most cases, depending on where you've downloaded your //Celeste// game sources, //Celeste// is well "prepared" for running it as a native Linux game. In other words: The downloaded game package should contain all files/dependencies without the hassle of having to search/add manually any external files/dependencies. Unfortunately, as already mentioned above, this definitely is not the case for all native Linux games!
+In most cases, depending on where you've downloaded your Celeste game sources, the game is well "prepared" for running it as a native Linux game. In other words: the downloaded game package should contain all files/dependencies without the hassle of having to search/add manually any external files/dependencies. Unfortunately, as already mentioned above, this definitely is not the case for all native Linux games!
 </WRAP>
@@ Line 107: / Line 109: @@
 {{:systems:celeste_example_01.png?800|}}
-For //Celeste//, in his case, the correct executable file to start the game is ''/userdata/roms/ports/Celeste/Celeste'' as marked in the screenshot above. Now to make the game show up as //Celeste// in your Batocera GUI's //Ports// section, you would have to have a file called ''/userdata/roms/ports/Celeste/Celeste.sh''. You could indeed rename the game's main executable file from ''/userdata/roms/ports/Celeste/Celeste'' to ''/userdata/roms/ports/Celeste/Celeste.sh'' and adjust it afterwards, but a better, more flexible and more reliable way would be to leave the source files untouched and create a separate executable file which will call the main executable file. To do so, just run the following command:
+For Celeste, in his case, the correct executable file to start the game is ''/userdata/roms/ports/Celeste/Celeste'' as marked in the screenshot above. Now to make the game show up as "Celeste" in your Batocera GUI's "Ports" section, you would have to have a file called ''/userdata/roms/ports/Celeste/Celeste.sh''. You could indeed rename the game's main executable file from ''/userdata/roms/ports/Celeste/Celeste'' to ''/userdata/roms/ports/Celeste/Celeste.sh'' and adjust it afterwards, but a better, more flexible and more reliable way would be to leave the source files untouched and create a separate executable file which will call the main executable file. To do so, just run the following command:
 <code>nano /userdata/roms/ports/Celeste/Celeste.sh</code>
@@ Line 120: / Line 122: @@
 Save the file and quit the editor.
-As you may have mentioned on the screenshot above, none of the executable files are marked as executable yet, which will be required to run //Celeste// sucessfully. So let's do this by executing:
+As you may have mentioned on the screenshot above, none of the executable files are marked as executable yet, which will be required to run "Celeste" sucessfully. So let's do this by executing:
 <code>chmod +x /userdata/roms/ports/Celeste/Celeste.sh /userdata/roms/ports/Celeste/Celeste /userdata/roms/ports/Celeste/Celeste.bin*</code>
@@ Line 127: / Line 129: @@
 </WRAP>
-Now update the gamelist via the Batocera GUI and the game should show up in the //Ports// section. That's it, start the game from there and have fun! :-D
+Now update the gamelist via the Batocera GUI and the game should show up in the "Ports" section. That's it, start the game from there and have fun! :-D
+==== Vulkan dependent game example: "Teenage Mutant Ninja Turtles: Shredder's Revenge" (Linux patched version) ====
+Some games are dependent on the Vulkan graphics API which can get enabled by command line when starting the game's executable as shown in the following example game's startup script.
+<WRAP center round tip>
+Note that a game is dependent on Vulkan, the graphics card needs to support it. In other words: If a graphics card doesn't supports the Vulkan API natively, it won't be possible to run the game. There's no way to emulate graphics cards with Vulkan API support (yet) if the game is meant to run directly on a bare-metal computer environment. It //might// work in a virtual computer environment with a virtual GPU (vGPU) but is barely supported by any hypervisor. Only VMware hypervisors are [[https://en.wikipedia.org/wiki/GPU_virtualization|supporting Vulkan for their virtual GPUs (vGPUS)]] these days, which might change for other hypervisor vendors in the future. But to [[:run_batocera_in_vm|run Batocera in a VM]] is not suggested anyway.
+</WRAP>
+<code bash TMNT.sh>
+#!/bin/bash
+export LC_ALL=C
+export MONO_IOMAP=all
+# Move to the game directory
+cd "$(dirname "$(realpath "$0")")" || exit
+# Run the game
+chmod +x ./TMNT.bin.x86_64
+exec ./TMNT.bin.x86_64 /gldevice:Vulkan "$@"
+exit 0
+</code>
+Make the script executable:
+<code>chmod +x /userdata/roms/ports/TMNTSR/TMNT.sh</code>
+Update the gamelist and start the game via the ES its "Ports" section.
+==== Library-dependent game: Final Fight LNS Ultimate ====
+Final Fight LNS Ultimate is a game which is dependent on the libvpx library package that is not included with Batocera by default. This can be provided alongside the game.
+Copy the contents of the game's data to the ''roms/ports/Final Fight LNS Ultimate/'' folder, then create a new subfolder named ''LIBS'' at ''Final Fight LNS Ultimate/LIBS''. Download the libvpx as appropriate to your achitecture and place it in that folder.
+Back in the ''Final Fight LNS Ultimate/'' folder, save the following script file:
+<file bash Final Fight LNS Ultimate.sh>
+#!/bin/bash
+# Only applied to version FFLNSU V03, for V04 comment those export lines!
+export LC_ALL=C
+export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:./LIBS/
+# Move to the game directory
+cd "$(dirname "$(realpath "$0")")/" || exit
+# Run the game
+chmod +x "Final Fight LNS Ultimate" #For version V04, use Final Fight LNS Ultimate.AppImage instead
+exec "./Final Fight LNS Ultimate" "$@" #For version V04, use Final Fight LNS Ultimate.AppImage instead
+</file>
+**Note:** For Final Final LNS Ultimate (V04), use the same script, but point to the Final Fight LNS Ultimate.AppImage and remove the lines about LIBS.
+The final file structure should look like this (your installation may have more or less, but overall structure should be similar):
+<code>
+roms/
+└─ ports/
+   └─ Final Fight LNS Ultimate/
+      ├─ LIBS/
+      │  └─ libvpx.so.5 >> (For V03 only, not needed for V04)
+      ├─ Logs/
+      ├─ Paks/
+      │  └─ Final Fight LNS.pak (Game file, V03 or V04)
+      ├─ reshade-shaders (from Shaders package - optional)
+      │  ├─ Shaders
+      │  └─ Textures
+      ├─ Saves/
+      ├─ ScreenShots/
+      ├─ 1920.ini (from Shaders package - optional)
+      ├─ CAMBIOS - Final Fight LNS Utimate V03/V04.txt
+      ├─ Final Fight LNS Ultimate >> (Final Fight LNS Ultimate.AppImage for V04 instead - game launcher)
+      ├─ Instrucciones.txt (from Shaders package - optional)
+      ├─ Legal.txt
+      ├─ opengl32.dll (from Shaders package - optional)
+      ├─ ReShadeGUI.ini (from Shaders package - optional)
+      ├─ ReShade.ini (from Shaders package - optional)
+      └─ Final Fight LNS Ultimate.sh
+</code>
+Update gamelists and launch!
+==== Old 32-bit game ====
+For games which require 32-bit libraries and can't find them on their own:
+<file bash run.sh>
+#!/bin/sh
+cd "$(dirname "$(readlink -f "$0")")"
+unclutter-remote -h
+export LD_LIBRARY_PATH=/lib32
+export LIBGL_DRIVERS_PATH=/lib32/dri
+export SPA_PLUGIN_DIR="/lib32/spa-0.2:/usr/lib/spa-0.2"
+export PIPEWIRE_MODULE_DIR="/lib32/pipewire-0.3:/usr/lib/pipewire-0.3"
+exec ./start.sh
+</file>
+==== Old Game Maker Studio game: Maldita Castilla ====
+Games written in older versions of Game Maker Studio will depend on a collection of 32-bit libraries not included with Batocera. (If the game's executable is just named ''runner'', that's a good sign that you have a GMS game... though some developers will rename it.)
+More broadly, if the ''file'' command on a more general-purpose Linux setup says that the game executable is an ''ELF 32-bit LSB executable, Intel 80386'', then these instructions will likely get it working, though they may be overkill.
+[[https://namethattech.wordpress.com/2020/09/04/from-gamemaker-to-ubuntu-14-16-18-and-beyond/|This blog post]] details how to build the required library bundle and includes a mention that, if you trust the author, you can just grab the ''lib'' folder and adapt the wrapper script from their [[https://juanitogan.itch.io/river-raid-squadron|River Raid Squadron]] game on Itch.io.
+(If both of those links die, you can just build the libraries the error messages complain about one-by-one until the game works.)
+If you place the ''lib'' folder inside the game folder, a suitable SH file will look something like this:
+<file sh Maldita Castilla.sh>
+#!/bin/sh
+DIR="$(dirname "$(readlink -f "$0")")"
+cd "${DIR}/.data/MalditaCastilla"
+unclutter-remote -h
+export LD_LIBRARY_PATH=./lib:/lib32
+export LIBGL_DRIVERS_PATH=/lib32/dri
+export SPA_PLUGIN_DIR="/lib32/spa-0.2:/usr/lib/spa-0.2"
+export PIPEWIRE_MODULE_DIR="/lib32/pipewire-0.3:/usr/lib/pipewire-0.3"
+./runner
+</file>
+===== Installing the Java runtime environment =====
+Some games may require the Java runtime environment. Ordinarily, this would just be installed from the operating system's package manager, however Batocera has no repository which includes or maintains the JRE. However, there are portable packages that allow for JRE to run in a portable form.
+Download the JRE appropriate to your system from [[https://github.com/alinke/pixelcade-jre/]] (as of writing, x86_64, x86, aarch32 and aarch64 have packages) and extract it to the ''system/java'' folder.
+Either the executable can be pointed toward this location (if it has the appropriate arguments), or run the following SSH command to allow ''java'' to be run as if it were installed like a regular component:
+<code bash>
+export PATH=/userdata/system/java/usr/bin:$PATH
+batocera-save-overlay
+</code>
+This will be required to be run every update.
+In case the latest version of JRE is required (or your exact platform isn't available from the prepared packages above), refer to the manual method:
+--> Manual method (click to expand)#
+Instructions taken and modified from https://docs.azul.com/core/zulu-openjdk/install/rpm-based-linux#install-from-binary-tar-gz-file
+  - Go to https://www.azul.com/downloads/?package=jdk
+  - Scroll down and download the latest ''.tar.gz'' package available for the appropriate platform
+  - Extract the ''.tar.gz'' file to anywhere on your userdata (from SSH, run ''tar -xvf <zulu_package>.tar.gz'' to extract it)
+  - Run ''<zulu_package>/bin/java -version'' to check that it was extracted successfully
+  - Add the file to ''/usr/bin'' directory to use the ''java'' command from anywhere: ''export PATH=<installation_folder>/usr/bin:$PATH'' and run ''batocera-save-overlay'' to keep the changes permanent (until next upgrade)
+If you’d like a single line command that does all of this automatically:
+  * **For aarch64:** ''%%curl -kLo - https://cdn.azul.com/zulu-embedded/bin/zulu8.58.0.13-ca-jdk8.0.312-linux_aarch64.tar.gz | gunzip -c | tar -x --strip-components=1 && batocera-save-overlay%%''
+<--
 ===== A note about integrated ports =====
-Batocera-integrated ports (recognized as their own unique system, but are grouped under the "Ports" system in EmulationStation along with native Linux Ports by default) usually contain an ''_info.txt'' file in their folder explaining how to install them and sometimes have their own page in [[:systems#port|system overview page]] under the "Port" header.
+Batocera-integrated ports (recognized as their own unique system, but are grouped under the "Ports" system in EmulationStation along with native Linux ports by default) usually contain an ''_info.txt'' file in their folder explaining how to install them and sometimes have their own page in [[:systems#port|system overview page]] under the "Port" header.
 ===== Troubleshooting =====
@@ Line 139: / Line 293: @@
 Native Linux games not running on Batocera can have many different reasons. The simplest solution is usually revealed in the error log located at ''system/logs/es_launch_stderr.log'' or ''system/logs/es_launch_stdout.log'' For testing purposes, you can use Batocera's file manager (''[F1]'' on the system list) to navigate to the ''roms/ports'' folder and launch the game (simply double-click it as you normally would) to see if any error messages pop up.
-If no meaningful error message comes from that, you can instead use [[:access_the_batocera_via_ssh|the terminal/SSH in]] and try running the commands to launch the game there, this might help you see if there are any error messages being printed to the console. Don't forget to run ''/etc/init.d/S31emulationstation stop'' to kill EmulationStation and ''%%batocera-es-swissknife --restart%%'' to bring it back to life! You may also need to pre-emptively run ''export DISPLAY=:0.0'' to get the game to be able to "see" your screen. For example:
+<WRAP center round help>
+You may need to enable the executable bit for the game in question when launching outside of ES. To do so:
+  - Back in Batocera, hit ''[F1]'' and navigate to ''roms/ports/.data'', right-click the ''Skatebird.sh'' file, go to **Properties** and make it executable by "Anyone".\\ {{:systems:executable_permission_bit.png|}}
+  - Press ''[Ctrl]'' + ''[Q]'' to exit back to Batocera.
+</WRAP>
+If no meaningful error message comes from that, you can instead use [[:access_the_batocera_via_ssh|the terminal/SSH in]] and try running the commands to launch the game there (pre-emptively run ''export DISPLAY=:0.0'' to get the game to be able to "see" your screen), this might help you see if there are any error messages being printed to the console. It's advised to be sitting in the file manager instead of EmulationStation to avoid video display issues.
+<WRAP center round info>
+Alternatively, run ''/etc/init.d/S31emulationstation stop'' to kill EmulationStation and ''%%batocera-es-swissknife --restart%%'' to bring it back to life!
+</WRAP>
+For example:
 <code>
 export DISPLAY=:0.0
 cd "/userdata/roms/ports/Celeste"
-./Celeste.sh
+/bin/sh Celeste.sh
 </code>
@@ Line 168: / Line 334: @@
 export LD_LIBRARY_PATH=/usr/lib32
 </code>
+An example SH file for a game requiring library packages stored in a subfolder of the game would look like:
+<file sh game.sh>
+#!/bin/bash
+export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:./LIBS/
+exec "./game launcher" "$@"
+</file>
 Batocera's libraries are stored in ''/usr/lib/'', some games may also be hard-coding their paths and try searching in ''/lib'' for instance, necessitating changing the path told to the game to be inside of ''/usr'' instead.
+==== Other Known Bugs in Old Humble Bundle Linux Releases ====
+  * Some games (eg. Wizorb) will crash on startup if more than four joystick devices are present. (eg. If you have two dual-port controller adapters with one controller plugged into each, plus an X-Box 360 controller, and the adapters always make their ports visible to the host whether or not a controller is actually connected.)
+  * Some games (eg. Jamestown) which include both 32-bit and 64-bit executables will require you specifically use the 32-bit version as the 64-bit binary crashes with no known fix.
+  * If your game is XNA-based and you're getting a crash with the following error on startup, add an ''export TERM=vt100'' line to the SH file. <code>
+System.TypeInitializationException: The type initializer for 'System.Console' threw an exception. ---> System.TypeInitializationException: The type initializer for 'System.ConsoleDriver' threw an exception. ---> System.Exception: Magic number is wrong: 542</code> The terminal type database's format got extended at some point and that error means that your game is too old to understand the extended-format entries that your terminal emulator is using to announce its capabilities.
 ==== I'm stuck and I can't quit the game! ====