Run the NetherSX2 PlayStation 2 emulator (based on AetherSX2 v1.5-4248) natively on ARM Linux, without Android. Currently supported: ROCKNIX on the Orange Pi 5.
This project is a loader: a small Linux program that loads the emulator core
(libemucore.so) from the NetherSX2 Android APK and runs it on Linux. It translates the
Android C library calls to Linux, replaces the Java parts of the Android app (settings, files,
network, controllers, video and audio), and adds its own in-game menu.
No emulator files are included in this repository. You provide your own NetherSX2 APK and the installer extracts what it needs from it on your device.
- What works
- Known limitations
- Supported devices
- What you need
- Installation, step by step
- Controls and in-game menu
- Where your files are
- RetroAchievements
- Updating
- Uninstalling
- Troubleshooting
- Building from source
- Planned updates
- Credits and legal
Tested on an Orange Pi 5 with ROCKNIX 20261001, with both GPU drivers (Panfrost and libmali):
- Games running at full speed (for example Burnout Revenge and Crash Nitro Kart).
- Very fast startup: a game opens almost immediately after you select it in EmulationStation, much faster than the other PS2 emulators we tried on ROCKNIX.
- Vulkan renderer (the default), with the same image as on Android.
- Internal resolution from 1x to 6x (in 0.25x steps up to 3x), anisotropic filtering, FXAA, widescreen patches.
- Fast forward (hold L2 + R2 by default), also during loading screens.
- Full in-game menu in the style of the ARMSX2 / AetherSX2 Big Picture interface: pause screen, every setting the emulator supports in 13 tabs, per-game settings, controller and hotkey remapping, input profiles, macros, and an English / Portuguese language option.
- Integration with EmulationStation: NetherSX2 appears as an emulator choice for the PlayStation 2 system, and ROCKNIX's CPU/GPU performance settings are still applied.
- RetroAchievements login taken from EmulationStation, with the emulator's own notifications (game summary and unlocks, with icons and badges) (see the limitation below).
- Memory card as a folder (one folder per game, the default) or as a classic 8 MB
.ps2file.
- RetroAchievements: the RetroAchievements server only accepts NetherSX2/AetherSX2 4248 in casual (softcore) mode. Every time a game starts you will see a "Warning: Casual Only" message: casual unlocks count, hardcore unlocks do not. This project will not try to hide or fake the emulator identity.
- OpenGL renderer: it starts, but the game image is black. Use Vulkan (the default).
- Only the APK version listed in What you need has been tested. Other NetherSX2/AetherSX2 builds may not work.
Only the Orange Pi 5 (Rockchip RK3588, Mali-G610 GPU) running ROCKNIX. It is the only device the author owns and can test on.
Other RK3588 devices may work, but they are not tested. Reports and pull requests are welcome, and working devices will be listed here with credit to whoever tested them.
-
An Orange Pi 5 with ROCKNIX installed and working (EmulationStation boots, controller works).
-
A computer on the same network (Windows, Linux or macOS) to copy files to the Orange Pi.
-
The NetherSX2 APK (Android app file), which you download yourself. Tested version:
- NetherSX2 v2.2n:
NetherSX2-v2.2n-4248.apk, 21 621 788 bytes, SHA-2562029e30dcc1ba1ecb8d73313f18b429b40e6044c7785c52af08b948ef94b3ddf
The online multiplayer added in v2.2n is not supported by this loader yet.
- NetherSX2 v2.2n:
-
A PlayStation 2 BIOS dumped from your own console (a 4 MB file, for example
SCPH-70012.binorscph39001.bin). -
Your PS2 games dumped from your own discs (
.iso,.chd,.cso, …).
The APK, the BIOS and the games are not provided by this project. Do not ask for them in the issues.
- Open the Releases page of this repository.
- Download the latest
nethersx2-rocknix.tar.gz.
The package contains only the loader (nethersx2), the scripts and this README. It does not
contain any file from the APK.
- Open the official NetherSX2 releases page: https://github.com/Trixarian/NetherSX2-patch/releases
- Find the NetherSX2 v2.2n release and download
NetherSX2-v2.2n-4248.apk(under Assets). Download it only from there: copies from other sites may be modified. - (Optional) Check that it is the tested file. Its SHA-256 should be the one listed in
What you need:
- Linux:
sha256sum NetherSX2-v2.2n-4248.apk - macOS:
shasum -a 256 NetherSX2-v2.2n-4248.apk - Windows (PowerShell):
Get-FileHash NetherSX2-v2.2n-4248.apk
- Linux:
You do not need to unzip the APK yourself. The installer does that on the Orange Pi.
The files are copied over your local network (SFTP), and the installer is run from a terminal (SSH).
- On the Orange Pi, open the EmulationStation main menu (Start).
- Go to Network Settings and check:
- IP Address: write it down (for example
192.168.1.50); you only need it if the network name below does not work. - Hostname: the network name of the Orange Pi (
RK3588by default). - Enable SSH: must be on.
- IP Address: write it down (for example
- Go back to the main menu and open System Settings → Security → Root Password. Write down the password shown there.
In the steps below the Orange Pi is reached by its hostname followed by .local, for example
rk3588.local. If you changed the hostname, use yours (for example mypi.local). If your
computer cannot find it, use the IP address instead (for example sftp://192.168.1.50 and
ssh root@192.168.1.50).
FileZilla is free and works on Windows, macOS and Linux.
- Install and open FileZilla (the FileZilla Client).
- In the Quickconnect bar at the top, fill in:
- Host:
sftp://rk3588.local - Username:
root - Password: the root password from Step 3
- Port:
22
- Host:
- Click Quickconnect. Accept the server key if FileZilla asks (only the first time).
- In the Remote site box on the right, type
/storageand press Enter. - Drag these two files from the left side (your computer) to the right side (
/storage):nethersx2-rocknix.tar.gz(from Step 1)- your NetherSX2 APK, for example
NetherSX2-v2.2n-4248.apk(from Step 2)
Keep FileZilla open: you will use it again for the BIOS and the games.
The installer runs on the Orange Pi, through a terminal connection (SSH).
-
Open a terminal on your computer:
- Windows: open PowerShell (Start menu → type
PowerShell). - macOS: open Terminal (Applications → Utilities).
- Linux: open your terminal app.
- Windows: open PowerShell (Start menu → type
-
Connect to the Orange Pi:
ssh root@rk3588.local
The first time, type
yesto accept the key. Then type the root password from Step 3 (nothing appears while you type it; this is normal) and press Enter. -
Run these commands, one at a time (use your APK's real file name in the third one):
cd /storage
tar xzf nethersx2-rocknix.tar.gz
mv NetherSX2-v2.2n-4248.apk nethersx2/
sh nethersx2/install.sh --defaultWhat each command does:
| Command | What it does |
|---|---|
cd /storage |
Goes to the folder where you copied the files. |
tar xzf nethersx2-rocknix.tar.gz |
Unpacks the release into the new folder /storage/nethersx2. |
mv NetherSX2-v2.2n-4248.apk nethersx2/ |
Moves your APK into that folder. |
sh nethersx2/install.sh --default |
Extracts the emulator files from the APK and adds NetherSX2 to EmulationStation as the default PS2 emulator. |
If everything went well, you will see:
Extracting emulator files from NetherSX2-v2.2n-4248.apk...
Emulator files extracted. The APK is no longer needed and can be deleted.
NetherSX2 added to the PS2 system (backup: /storage/.config/emulationstation/es_systems.cfg.bak-nethersx2).
Restart EmulationStation to apply (or reboot).
Prefer to keep another PS2 emulator as the default? Run
sh nethersx2/install.shwithout--default. NetherSX2 will still be available as an option in EmulationStation (see Step 9).
After this step you can delete the APK and the .tar.gz file:
rm /storage/nethersx2/*.apk /storage/nethersx2-rocknix.tar.gzType exit to close the connection.
In FileZilla, go to /storage/roms/bios on the right side and drag your BIOS file into it.
This is the normal ROCKNIX BIOS folder.
NetherSX2 finds any 4 MB BIOS file in that folder (and in its subfolders) automatically every time a game starts.
In FileZilla, go to /storage/roms/ps2 and drag your PS2 games into it. This is the same
folder used by the other PS2 emulators of ROCKNIX.
Then, on the Orange Pi, open Start → Game Settings → Update Gamelists and choose Yes, so the new games appear in the list.
Restart the Orange Pi, or restart only EmulationStation from its menu (Start → Quit → Restart EmulationStation).
- In EmulationStation, open PlayStation 2 and start a game.
- If you installed without
--default, choose NetherSX2 as the PS2 emulator first, in either of these ways:- Start → Game Settings → Per System Advanced Configuration → PlayStation 2 → Emulator → NetherSX2: nethersx2-sa
- or, in the PlayStation 2 game list, press Select (Options) → Advanced System Options → Emulator → NetherSX2: nethersx2-sa
- The first start writes the default settings (Vulkan renderer, fast forward on L2 + R2, etc.). Press the menu hotkey (L3 + R3 by default) at any time to open the in-game menu; the same hotkey closes it again.
After a ROCKNIX update, the PS2 entry in EmulationStation may be reset. Just run
sh /storage/nethersx2/install.sh --defaultagain (no APK needed this time) and restart EmulationStation (Step 8).
| Buttons (default) | Action |
|---|---|
| L3 + R3 (press both sticks) | Menu hotkey: opens the in-game menu. While the menu is open, the same hotkey closes it, and the next time the menu reopens exactly where you left it, which makes quick tweaks easy. This works with whatever combination you assign to Open Pause Menu. |
| L2 + R2 (hold) | Fast forward |
Both are only defaults: every hotkey can be changed in Settings → Hotkeys (see Remapping). If the menu hotkey is ever left unbound, L3 + R3 is restored at the next start, so you can never lock yourself out of the menu.
Button names use the PlayStation layout. On an Xbox-style controller, Cross is A, Circle is B, Square is X and Triangle is Y.
The game pauses while the menu is open. The look follows ARMSX2 / AetherSX2's Big Picture interface. The icons and controller glyphs come from the ARMSX2 package that ROCKNIX already includes (nothing extra to install).
Pause screen: Resume Game, Toggle Frame Limit, Load State, Save State, Save Slot (1 to 10), Game Properties (per-game settings), Achievements, Switch To Software Renderer, Settings, Reset and Close Game. The header shows the game, its serial / CRC, the clock (12 or 24 hours, as set in EmulationStation) and the play time.
Settings are split in tabs: Interface, BIOS, Emulation, Graphics, On-Screen Display, Audio, Memory Cards, Network & HDD, Folders, Achievements, Controllers, Hotkeys and Advanced. Each row has a short description; options that depend on another one are dimmed while it is off.
| Buttons | Action |
|---|---|
| D-pad up / down (or left stick) | Move between options. Up from the first row selects the tab bar. |
| D-pad left / right | Change the value (on the tab bar: change tab) |
| L1 / R1 | Change tab |
| Cross (A) | Select: opens the list of values, toggles a switch, runs an action |
| Square (X) | Clear a binding / go back to the global setting (per-game) |
| Circle (B) | Back (from Settings to the pause screen; from the pause screen to the game) |
| Start | Close the menu |
Changed settings are saved and applied when the menu closes.
Some highlights:
- Internal Resolution sits at the top of Graphics → Display, for quick changes.
- Performance Preset (On-Screen Display): Off, FPS, Detailed or Full information in the top-right corner.
- Hardcore mode (Achievements): can be turned off for the rest of the session (loading states is allowed again). As required by RetroAchievements, it only comes back on by restarting the game.
- Language (Interface): English (default) or Português.
Pause screen → Game Properties edits the settings of the running game only (tabs Summary, Emulation, Patches, Cheats, Graphics, On-Screen Display, Audio, Memory Cards and Advanced).
- Every option starts as Use Global Setting; switches have a third, grey "global" position. Change a value to override it for this game; Square (or Use Global Setting in the list) goes back to the global value.
- Summary shows the title, serial, CRC, region and path, lets you pick an input profile for the game, and has Copy Settings (copy the current global settings) and Clear Settings.
- Settings are stored in
/storage/.config/nethersx2/gamesettings/<SERIAL>_<CRC>.ini, the emulator's own per-game file.
In Settings → Controllers (buttons) and Settings → Hotkeys, select a row with Cross: a window counts down 5 seconds. Press the new button (or move a stick / trigger). To bind a combination, hold the buttons together; it is saved when you release them all. Pressing nothing leaves the binding unchanged; Square clears it.
Also in Controllers: controller type, Automatic Mapping (maps a port to a connected controller), multitap, stick inversion, deadzones, sensitivity, vibration, 16 macro buttons per port (trigger, buttons, frequency, pressure), and Load / Save Profile (input profiles, named with an on-screen keyboard). A profile can then be used by a single game from its Game Properties.
You choose where they are kept in the in-game menu (Save Folder in the Interface, Memory Cards and Folders tabs):
| Save folder | Memory cards | Save states |
|---|---|---|
roms/ps2 (default) |
/storage/roms/ps2 |
/storage/roms/savestates/ps2/nethersx2 |
roms/saves/ps2 |
/storage/roms/saves/ps2 |
/storage/roms/saves/ps2/sstates |
.config/nethersx2 |
/storage/.config/nethersx2/memcards |
/storage/.config/nethersx2/sstates |
- By default the memory cards are in the same folder as the AetherSX2 and ARMSX2 emulators
included in ROCKNIX, so your game saves are shared with them. Save states are kept in their
own
nethersx2subfolder: they only work with the emulator that created them, and ARMSX2 uses the same file names. - A memory card folder holds the folder card
saves.ps2(one folder per game save) and any classic card file (Mcd001.ps2, …). Your games inroms/ps2are never moved or changed. - A new choice takes effect the next time a game starts. Your existing memory cards and save states are then moved automatically to the new folder.
- If the same save exists in both folders, the identical copy is removed, the newest one is
kept and the older one is moved to
/storage/.config/nethersx2/save-backups/<date>/. Nothing is deleted. A message on screen tells you what was moved. - Choose Folder... lets you pick (or create) any other folder with the controller: memory
cards go in that folder, save states in its
sstatessubfolder. - The other data folders (BIOS, snapshots, cheats, texture replacements, covers, logs) can be changed in Settings → Folders, also with the folder browser. They take effect the next time a game starts.
| What | Where on the Orange Pi |
|---|---|
| Loader, scripts and files extracted from the APK | /storage/nethersx2 |
Settings (nethersx2.ini) and other emulator data |
/storage/.config/nethersx2 |
| BIOS (links to your BIOS files) | /storage/.config/nethersx2/bios |
| Log of the last run | /var/log/nethersx2.log (deleted when the device restarts) |
To sync your saves between devices (for example with Syncthing), sync the memory card and save
state folders above. Back up /storage/.config/nethersx2 to keep your settings.
NetherSX2 uses the RetroAchievements account you set up in EmulationStation (Start → Game Settings → RetroAchievements Settings): the username, the on/off switch and Hardcore Mode are read every time a game starts.
- When a game starts, a message shows the game title and your progress (achievements and points).
- New unlocks are shown on screen.
- In Hardcore mode, loading states is blocked (this is a RetroAchievements rule). The menu shows the option as locked.
Remember the limitation: the RetroAchievements server marks this emulator as unsupported, so achievements may not count.
- Download the new
nethersx2-rocknix.tar.gzand copy it to/storagewith FileZilla (Step 4). - Connect with
ssh root@rk3588.local(Step 5) and unpack it over the old install. Your extracted APK files, settings and saves are kept:
cd /storage
tar xzf nethersx2-rocknix.tar.gz
sh nethersx2/install.sh --default
rm nethersx2-rocknix.tar.gz- Restart EmulationStation (Step 8).
# put back the EmulationStation config saved by the last install.sh run
cp /storage/.config/emulationstation/es_systems.cfg.bak-nethersx2 /storage/.config/emulationstation/es_systems.cfg
# remove the loader
rm -rf /storage/nethersx2Then restart EmulationStation (Step 8).
Your settings and saves in /storage/.config/nethersx2 are not removed. Delete that folder
too only if you do not need them anymore.
The first thing to check is always the log of the last run:
cat /var/log/nethersx2.log| Problem | What to do |
|---|---|
The game closes right away and the log says no PS2 BIOS found |
Copy a 4 MB PS2 BIOS file into /storage/roms/bios (Step 6). |
install.sh says No APK found |
Copy your NetherSX2 .apk into /storage/nethersx2 and run it again. |
install.sh says the APK has no libemucore.so |
The file is not the NetherSX2 APK, or it is a version for another CPU. Download it again (Step 2). |
The log says NativeLibrary.initialize failed |
The APK files are missing or from an unsupported version. Run install.sh again with the tested APK. |
| NetherSX2 does not appear in EmulationStation | Run sh /storage/nethersx2/install.sh --default, then restart EmulationStation (Step 8). |
| Black game image | You are using the OpenGL renderer. Switch back to Vulkan (renderer 14 under [EmuCore/GS] in nethersx2.ini). |
| A game is slow | Lower the internal resolution in the menu, then try EE Cycle Rate / EE Cycle Skip. |
When reporting a problem, open an issue and include: the game, your settings (nethersx2.ini),
the log (/var/log/nethersx2.log), your ROCKNIX version, the GPU driver (Panfrost or libmali)
and your APK's SHA-256.
You only need this if you want to change the loader. Releases already contain the compiled program.
The loader is cross-compiled on a Linux PC (x86-64) for aarch64 with clang and lld, using a Debian bookworm arm64 sysroot (glibc 2.36).
# once: download the Debian arm64 sysroot (needs python3)
make sysroot
# build the loader -> build/nethersx2
make
# build the release package -> dist/nethersx2-rocknix.tar.gz (no APK files inside)
make distSource layout:
| File | Purpose |
|---|---|
src/elf_loader.c |
Loads the Android libemucore.so into memory |
src/bionic.c, src/bionic_setjmp.S |
Android C library (bionic) → Linux (glibc) translation |
src/jni.c, src/java.c |
Replacement for the Java side of the app (settings, files, network…) |
src/platform.c |
SDL2, Wayland, EGL, Vulkan, audio and controllers |
src/vkproxy.c |
Vulkan swapchain proxy (lets fast forward go past the display refresh rate) |
src/overlay.c |
Full-screen menu canvas (Wayland subsurface, SDL_ttf) |
src/menu.c, src/menu_pages.c |
In-game menu: engine (screens, popups, remapping) and page contents |
src/i18n.c |
Menu and on-screen message languages (English, Portuguese) |
src/saves.c |
Memory card / save state folders and moving saves between them |
src/affinity.c |
Places the emulator threads on the right CPU cores |
src/settings.c |
nethersx2.ini |
src/main.c |
Main flow, menu hotkey, RetroAchievements, memory cards |
tools/menu_preview.c |
make preview: renders the menu to images on the PC, for development |
scripts/ |
Installer, launcher and EmulationStation integration |
- Online multiplayer (the network adapter support added in NetherSX2 v2.2n).
- Batocera version of the loader.
- AetherSX2 by Tahlreth, and NetherSX2 by Trixarian and contributors: the emulator core this loader runs. This project is not affiliated with or endorsed by them.
- PCSX2, which AetherSX2 is based on.
- ROCKNIX team, for the distribution this runs on.
This repository contains only the loader's own code and scripts. It does not include and
will never distribute the NetherSX2/AetherSX2 APK or any file taken from it (libemucore.so,
assets, certificates), nor any PS2 BIOS or game. Use your own legally obtained copies.
The loader's code and scripts are free software, released under the
GNU General Public License v3.0 or later (see LICENSE). You can use, study,
change and share them; if you distribute a modified version, its source code must be available
under the same license.
Exception: src/include/jni.h is the standard JNI header from the Android
Open Source Project and keeps its original Apache License 2.0
(see LICENSES/Apache-2.0.txt).
This license covers only this project's files. NetherSX2/AetherSX2, its APK and everything extracted from it are not part of this project and are not covered by it.