Repository navigation
Android and RetroArch
The runtime needs the NDK; the app (the launcher, built with Tauri) also needs
the SDK, a JDK and Rust's aarch64-linux-android target.
git clone -b release-3.4.20 --depth 1 https://github.com/libsdl-org/SDL.git third_party/SDL
git clone -b n7.1.1 --depth 1 https://git.ffmpeg.org/ffmpeg.git third_party/ffmpeg # movies (optional)
tools/android/build_ffmpeg.sh third_party/ffmpeg third_party/ffmpeg-android
cmake -S . -B build-android -G Ninja -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK/build/cmake/android.toolchain.cmake \
-DANDROID_ABI=arm64-v8a -DANDROID_PLATFORM=android-33
cmake --build build-android --target x2app packs typex2_libretro
# the app: its game side comes from build-android/app (X2_APP_NATIVE to use another folder)
cd launcher && ANDROID_HOME=... NDK_HOME=$ANDROID_NDK npx tauri android build --apk --target aarch64 [--debug]-
Targets.
-
x2app: the app's game side, without games:libmain.so,libSDL3.soand SDL's Java activity, inbuild-android/app. -
packs: one game pack per game,build-android/packs/x2-<size>-<entry>.so. -
typex2_libretro: the core. Name it: the default target doesn't rebuild it. The build also keeps an unstrippedtypex2_libretro_android.so.symfor the profiler.
-
-
The Android project is
launcher/src-tauri/gen/android. Tauri rewrites itsapp/build.gradle.ktson every build, so the app's own Gradle settings live in the rootbuild.gradle.kts. -
Debug builds are
com.typex2.recomp.dev, installed next to the release app. Release builds are signed whenX2_KEYSTOREandX2_KEYSTORE_PASSWORDare set (CI).
-
Folders. Each game lives in its own folder named
<Game>.x2, for exampleROMs/arcade/The King of Fighters XIII.x2/game.exe. -
x2.env. A file in the game folder holdsKEY=VALUElines. These setX2_*switches, such as a pad layout orX2_FPS=1. The app writes it from each game's settings. -
Logs go to logcat with the tag
x2.
Type X2 (com.typex2.recomp) is the launcher, built for Android. It
carries no game code: each game's code comes as a game pack, built on a
computer.
-
Install the app from the releases page (
typex2-android.apk). On first start, allow "All files access": the app reads the ROMs folder and writes each game'sx2.env. Coming from a Type X2 app older than 0.2.0, uninstall it first: the new app is signed with the release key, and Android won't install it over the old one (saves and settings are in the game folders). - Make the packs on a computer: in the launcher, Export → Game packs for the Android app, with the games you own.
-
Send them: Export → Last exports → Send to device, with the device
connected (USB debugging on). Or copy the
x2-*.sofiles toTypeX2/packson the device's internal storage yourself. -
Open the app. It installs the packs, finds the games in ES-DE's ROMs
folder (
ROMs/arcade, or ES-DE's own ROM directory setting) and lists them. Games it can't play yet are listed too, as Not supported yet.
-
A game's page: Play, the FPS counter, the render scale, the on-screen
touch pad (automatic, always, never), the pad layout and extra
X2_*switches. The settings go into the game'sx2.env. -
From ES-DE a game starts straight away, with the same settings: ES-DE
launches the app's game activity (
es_find_rules.xml). -
How a game runs: in its own process, in SDL's activity.
libmainidentifies the game from its executable and loads its pack from the app's private storage, the only place besides the APK Android loads code from. - Updating a game after a runtime fix means sending a new pack, not reinstalling the app.
- Copy
typex2_libretro_android.sotoRetroArch/downloads/on shared storage, or let the launcher do it: Export → Last exports → Send to device, with the device connected (USB debugging on). - In RetroArch: Load Core → Install or Restore a Core, then pick the file. Android only loads cores from RetroArch's own data folder.
Settings and limits:
-
Video. The core and the app render with Vulkan 1.3 (most devices from
2022 on, with Android 13 or later). RetroArch switches to its
vulkandriver by itself while "Allow driver switching" (Settings → Drivers) is on, the default. Older devices use OpenGL ES instead: the app switches by itself when Vulkan 1.3 is missing; in RetroArch, set the video driver togland putX2_RENDERER=glin the game'sx2.env. Both renderers draw the same; OpenGL ES is usually slower on the same GPU. - Clock. RetroArch's frame loop clocks the game, so pause, fast-forward and slow motion work.
- Save states work within a run of the game, on the screen they were saved on (Save states). No rewind or run-ahead. Reset (Quick Menu → Restart) restarts the game, with Vulkan and with OpenGL.
- Switching games. Close a game (Quick Menu → Close Content) and load another, no restart needed. A closed game gives back almost all its memory; 1-3 MB stays until RetroArch quits. Launched from ES-DE, RetroArch quits when the game closes (as it does with Settings → User Interface → "Quit on Close Content").
-
Latency. One frame in flight: the game computes frame N+1 while
RetroArch shows frame N, as on the cabinet's driver.
X2_PIPELINE=0runs in lockstep (a frame less latency, drops when a frame's work exceeds 16.7 ms). -
Remaps. RetroArch's remaps work as with FinalBurn Neo: copy
remaps/FinalBurn Neo/FinalBurn Neo.rmptoremaps/Type X2/Type X2.rmp(withinput_libretro_device_p1/p2 = "1") to share one layout. Button layouts per game: Controls. -
Two buttons at once (Focus Attack, throws, KOF's AB / CD). Android hands an
app one controller event at a time, and with RetroArch's default
Settings → Input → Input Block Timeout of 0 a second button pressed in the
same instant reaches the core one or two frames later: SSF4 then sees MP and
MK as two separate presses. Set it to 2 ms (
input_block_timeout = "2"inretroarch.cfg). The standalone app reads both together without it.
- Copy the
<system>block oftools/es-de/android/es_systems.xmlintoES-DE/custom_systems/es_systems.xml. - Copy
es_find_rules.xmlintoES-DE/custom_systems/. - On each Type X2 game, set "Alternative emulator".
The block replaces the built-in Arcade system. It keeps the MAME / FBNeo commands and adds "Type X2 recomp (Standalone)" and "Type X2 (RetroArch)". MAME stays the default, which is why step 3 is needed.
Each change was measured on the test tablet, a Samsung Galaxy Tab A11
(8 GB / 128 GB, Mali-G57 MC2; see test devices),
with X2_AB, which runs
both variants in the same session because the games pick random stages.
| Change | Effect |
|---|---|
| One frame in flight (core) | Largest win: late frames in heavy scenes went from 37-59 per 60 to 7-9. |
| Alpha test only in shader variants that need it | Keeps early-Z: SSF4 fights 15.0 → 11.6 ms GPU per frame. |
| fp16 pixel shaders | 2.5-4 % in fights, ~10 % in light scenes. |
| RGB565 for opaque DXT1 without S3TC | Half the upload size and memory. |
Honour SetThreadPriority
|
HIGHEST / TIME_CRITICAL guest threads run on the big cores. |
| Deferred texture uploads past a per-frame budget | Fewer load pauses. |
BGRA8 uploaded unswapped, swizzled when sampled; UpdateTexture from the source |
BlazBlue's worst pause ~430 → ~230 ms. |
| Natives for hot routines (zlib, sprite RLE, fills) | Shorter loads. |
ThinLTO for generated code (X2_GEN_LTO, on for Android) |
Guest functions inline across the generated files. Climax's game thread on heavy stages: 15.3-17.5 → 10.8-13.2 ms a frame; SSF4 about 1.5 ms less. |
Per-site cache for indirect calls (X2_ICALL); imports dispatched before the code table |
Removes the 27 MB table lookup from virtual calls and from about a million import calls a second (Climax): x2_lookup 4.2 % of the game thread → gone. |
| Switch | Shows |
|---|---|
X2_PACELOG=1 |
Every 2 s: retro_run intervals, the slowest guest frame ("guest work max"), the slowest replay. |
X2_PROF=1 X2_PROF_OUT=<file>
|
A sampling profile per second and thread. Symbolise the offsets against the .sym file. |
X2_PROF_SLOW=<ms> |
With X2_PROF: what the game thread did in each frame slower than <ms>. |
X2_GPUTIME=1 / =2
|
GPU time per frame / per pass. |
X2_CSPROF=1 |
Lock contention. |
Measure only while the tablet is awake and unlocked: it throttles while
locked or dozing. Check with dumpsys window | grep isKeyguardShowing.
Status
Games
Guides
Development