WinNative-Emu · maxjivi05 · Jul 28, 2026 · Jul 28, 2026 · Jul 29, 2026 · Jul 29, 2026
diff --git a/.gitattributes b/.gitattributes
@@ -3,3 +3,5 @@ app/src/main/assets/imagefs.tzst filter=lfs diff=lfs merge=lfs -text
 app/src/main/assets/imagefs.part*.tzst filter=lfs diff=lfs merge=lfs -text
 reference/tooling/jadx.zip filter=lfs diff=lfs merge=lfs -text
 reference/tooling/jadx/lib/jadx-1.5.3-all.jar filter=lfs diff=lfs merge=lfs -text
+
+app/src/main/jniLibs/arm64-v8a/*_libretro_android.so filter=lfs diff=lfs merge=lfs -text
diff --git a/.github/workflows/pr-ci.yml b/.github/workflows/pr-ci.yml
@@ -91,10 +91,15 @@ jobs:
     - name: Install Rust Android target
       run: rustup target add aarch64-linux-android
 
+    - name: Validate Gradle wrappers
+      uses: gradle/actions/wrapper-validation@v6
+      with:
+        allow-checksums: e2b82129ab64751fd40437007bd2f7f2afb3c6e41a9198e628650b22d5824a14
+
     - name: Set up Gradle
       uses: gradle/actions/setup-gradle@v6
       with:
-        validate-wrappers: true
+        validate-wrappers: false
         cache-cleanup: 'on-success'
         # PRs restore the Gradle cache read-only; only main pushes write it.
         cache-read-only: ${{ github.event_name == 'pull_request' }}

diff --git a/.github/workflows/tag-apk-artifacts.yml b/.github/workflows/tag-apk-artifacts.yml
@@ -84,10 +84,15 @@ jobs:
       - name: Install Rust Android target
         run: rustup target add aarch64-linux-android
 
+      - name: Validate Gradle wrappers
+        uses: gradle/actions/wrapper-validation@v6
+        with:
+          allow-checksums: e2b82129ab64751fd40437007bd2f7f2afb3c6e41a9198e628650b22d5824a14
+
       - name: Set up Gradle
         uses: gradle/actions/setup-gradle@v6
         with:
-          validate-wrappers: true
+          validate-wrappers: false
           cache-cleanup: 'on-success'
 
       - name: Decode keystore and build debug APK

diff --git a/.gitignore b/.gitignore
@@ -53,6 +53,12 @@ signing.properties
 References/
 *.hprof
 android_sysvshm/build64/
-
-# local build artifacts (FEX/Proton wcp)
-dist/
+
+# local build artifacts (FEX/Proton wcp)
+dist/
+
+/cores/*/
+!/cores/patches/
+
+/armsx2/emucore-src/
+/armsx2/emucore-out/
diff --git a/.gitmodules b/.gitmodules
@@ -5,3 +5,9 @@
 	path = app/src/main/cpp/vkbasalt
 	url = https://github.com/WinNative-Emu/vkBasalt.git
 	branch = Test
+[submodule "libretrodroid/src/main/cpp/oboe"]
+	path = libretrodroid/src/main/cpp/oboe
+	url = https://github.com/google/oboe
+[submodule "libretrodroid/src/main/cpp/libretro/libretro-common"]
+	path = libretrodroid/src/main/cpp/libretro/libretro-common
+	url = https://github.com/libretro/libretro-common
diff --git a/EMULATOR_CREDITS.md b/EMULATOR_CREDITS.md
@@ -0,0 +1,67 @@
+# Emulator & Library Credits
+
+WinNative's retro-console features are built on open-source emulators and libraries.
+This project is distributed under the **GNU General Public License v3.0** (see [LICENSE](LICENSE)).
+In compliance with the GPL and the other licenses below, the corresponding source code
+for every GPL/copyleft component is available from the upstream projects linked here,
+and their copyright and license notices are preserved.
+
+## PlayStation 2
+
+PS2 games are recognized and imported into the library. PS2 emulation is built on
+**ARMSX2** (a GPL-3.0 fork of PCSX2) and is in active development.
+
+| Component | Role | License | Source |
+| --- | --- | --- | --- |
+| ARMSX2 | PS2 emulation + RetroAchievements | GPL-3.0 | https://github.com/ARMSX2/ARMSX2 |
+| PCSX2 | Upstream project ARMSX2 is derived from | GPL-3.0 | https://github.com/pcsx2/pcsx2 |
+
+## GameCube / Wii
+
+GameCube and Wii games are recognized and imported into the library. GC/Wii emulation is
+built on an embedded build of **Dolphin**, rendered on Vulkan and driven entirely by
+WinNative (Dolphin's own UI is stripped). Local and online multiplayer use Dolphin's own
+native NetPlay engine.
+
+| Component | Role | License | Source |
+| --- | --- | --- | --- |
+| Dolphin | GameCube/Wii emulation + NetPlay | GPL-2.0-or-later | https://github.com/dolphin-emu/dolphin |
+
+## Bundled libretro cores
+
+Each core is shipped as an unmodified `arm64-v8a` build and loaded through LibretroDroid.
+
+| System | Core | License | Source |
+| --- | --- | --- | --- |
+| Game Boy / Color | Gambatte | GPL-2.0 | https://github.com/libretro/gambatte-libretro |
+| Game Boy Advance | mGBA | MPL-2.0 | https://github.com/libretro/mgba |
+| Genesis / Master System / Game Gear | Genesis Plus GX | Genesis Plus GX License (non-commercial) | https://github.com/libretro/Genesis-Plus-GX |
+| NES | FCEUmm | GPL-2.0 | https://github.com/libretro/libretro-fceumm |
+| Nintendo 64 | ParaLLEl N64 | GPL-2.0 | https://github.com/libretro/parallel-n64 |
+| Nintendo 64 | Mupen64Plus-Next | GPL-2.0 | https://github.com/libretro/mupen64plus-libretro-nx |
+| PlayStation | Beetle PSX (mednafen_psx) | GPL-2.0 | https://github.com/libretro/beetle-psx-libretro |
+| SNES | Snes9x | Snes9x License (non-commercial) | https://github.com/libretro/snes9x |
+
+### Also evaluated for PlayStation
+
+| Component | License | Source |
+| --- | --- | --- |
+| SwanStation | GPL-3.0 | https://github.com/libretro/swanstation |
+
+## Frontend, achievements, and supporting libraries
+
+| Component | Role | License | Source |
+| --- | --- | --- | --- |
+| LibretroDroid | libretro frontend the retro backend is built on | GPL-3.0 | https://github.com/Swordfish90/LibretroDroid |
+| Oboe | Audio output | Apache-2.0 | https://github.com/google/oboe |
+| rcheevos | RetroAchievements client library | MIT | https://github.com/RetroAchievements/rcheevos |
+| Snapdragon Game Super Resolution (SGSR) | Upscaling shader | BSD-3-Clause | https://github.com/quic/snapdragon-gsr |
+| Winlator | Windows-on-Android base this project forks | GPL-3.0 | https://github.com/brunodev85/winlator |
+
+## Source availability
+
+WinNative is released under the GPL-3.0. As required by that license and by the GPL-2.0
+cores above, the complete corresponding source for every copyleft component is obtainable
+from the upstream repositories linked in this document, and the bundled license texts are
+retained in the source tree (for example `libretrodroid/src/main/cpp/rcheevos/LICENSE`,
+`libretrodroid/src/main/cpp/SGSR_LICENSE`, and the top-level `LICENSE`).
diff --git a/README.md b/README.md
@@ -1,60 +1,98 @@
-<p align="center">
-  <img src="logo.png" alt="WinNative" width="500">
-</p>
-<p align="center">
-    <a href="https://discord.gg/uhTkvGfakU">
-        <img src="https://img.shields.io/discord/1358831699814912141?color=5865F2&label=WinNative&logo=discord&logoColor=white"
-            alt="Discord">
-    </a>
-</p>
-
-## WinNative: A Community Built Windows Emulation App for Android
-
- **WinNative** is an advanced, high-performance Windows (x86_64) emulation environment for Android. It bridges the gap between desktop gaming and mobile by unifying the best technologies from **Winlator Bionic** and **Pluvia**.
-
-Designed for enthusiasts and power users, WinNative delivers the full Winlator experience while making it easy to connect your Steam, Epic, and GOG game libraries.
-
----
-
-### Installation
-
-1. **Download:** Get the latest APK from the [Releases](https://github.com/WinNative-Emu/WinNative/releases) section.
-2. **Variants:**
-   - `Ludashi`: Forces both Max GPU and CPU clocks on some devices. (Performance Mode trigger).
-   - `Vanilla`: Standard package name for side-loading with other forks.
-   -  `Antutu`: Forces Max GPU clocks on most devices. (antutu benchmark spoof)
-   -  `Pubg`: Standard pubg package name which allows some Game Booster advanced Features.
-3. **Setup:** Launch the app, allow the ImageFS to install, and start adding your games manually or sync your library. 
-
----
-
-### How to Build
-
-**Requirements:** Android Studio, JDK 17, NDK `27.3.13750724`, and CMake.
-
-1. **Clone the repository and update submodules** (Required):
-   ```bash
-   git clone https://github.com/MaxsTechReview/WinNative.git
-   cd WinNative
-   git submodule update --init --recursive
-   ```
-2. **Build via Android Studio:** Open the `WinNative` directory, let Gradle sync, then select **Build > Build APK(s)**.
-3. **Build via CLI:** Run `.\gradlew.bat assembleDebug` (Windows).
-
----
-
-### Contributing
-
-We welcome community contributions! Feel free to open a pull request for bug fixes, driver updates, UI improvements, or anything else you'd like to add.
-
-Please match the existing code style and ensure any AI-assisted code is thoroughly reviewed and tested before submission.
-
----
-
-### Credits & Acknowledgments
-
-- **Original Winlator** by [brunodev85](https://github.com/brunodev85/winlator)
-- **Winlator Bionic** by [Pipetto-crypto](https://github.com/Pipetto-crypto/winlator)
-- **Pluvia** features by the [Pluvia](https://github.com/oxters168/Pluvia) / [GameNative](https://github.com/utkarshdalal/GameNative) community
-- **Mesa/Turnip** contributions by the [Mesa3D](https://www.mesa3d.org/) team
-- **Goldberg Steam Emulator** by [Mr. Goldberg](https://gitlab.com/Mr_Goldberg/goldberg_emulator), maintained by [Detanup01](https://github.com/Detanup01/gbe_fork)
+<p align="center">
+  <img src="logo.png" alt="WinNative" width="500">
+</p>
+<p align="center">
+    <a href="https://discord.gg/uhTkvGfakU">
+        <img src="https://img.shields.io/discord/1358831699814912141?color=5865F2&label=WinNative&logo=discord&logoColor=white"
+            alt="Discord">
+    </a>
+</p>
+
+## WinNative: A Community Built Windows Emulation App for Android
+
+**WinNative** is an advanced, high-performance Windows (x86_64) emulation environment for Android. It bridges the gap between desktop gaming and mobile by unifying the best technologies from **Winlator Bionic** and **Pluvia**.
+
+Designed for enthusiasts and power users, WinNative delivers the full Winlator experience while making it easy to connect your Steam, Epic, and GOG game libraries.
+
+---
+
+### Installation
+
+1. **Download:** Get the latest APK from the [Releases](https://github.com/WinNative-Emu/WinNative/releases) section.
+2. **Variants:**
+   - `Ludashi`: Forces both Max GPU and CPU clocks on some devices. (Performance Mode trigger).
+   - `Vanilla`: Standard package name for side-loading with other forks.
+   -  `Antutu`: Forces Max GPU clocks on most devices. (antutu benchmark spoof)
+   -  `Pubg`: Standard pubg package name which allows some Game Booster advanced Features.
+3. **Setup:** Launch the app, allow the ImageFS to install, and start adding your games manually or sync your library. 
+
+---
+
+### How to Build
+
+**Requirements:** Android Studio, JDK 17, and [Git LFS](https://git-lfs.com). The NDK
+(`27.3.13750724`) and CMake are only needed if you build native cores from source (see below).
+
+1. **Clone with submodules and pull LFS objects** (Required):
+   ```bash
+   git clone --recursive https://github.com/MaxsTechReview/WinNative.git
+   cd WinNative
+   git lfs pull                          # fetches imagefs
+   git submodule update --init --recursive
+   ```
+2. **Build via Android Studio:** Open the `WinNative` directory, let Gradle sync, then select **Build > Build APK(s)**.
+3. **Build via CLI:** Run `./gradlew assembleStandardDebug` (or `.\gradlew.bat` on Windows).
+
+The APK carries no retro console cores. Each core is built from its own fork under the
+[WinNative-Emu](https://github.com/WinNative-Emu) org, and
+[Retro-Consoles](https://github.com/WinNative-Emu/Retro-Consoles) packs every core plus the
+Dolphin and ARMSX2 runtime data into one `retro-consoles.tzst`. The app downloads and
+verifies it on demand from **Settings > Retro > Download console cores**, so a core update
+no longer needs an app release. To change a core, change its fork and re-run the
+Retro-Consoles bundle workflow.
+
+---
+
+### Retro Console Support
+
+WinNative can also run classic console games alongside your PC library. Retro games live in the same Library and launch just like PC games, but run on an embedded libretro backend instead of Wine.
+
+Supported systems (bundled cores):
+
+| System | Core | ROM extensions |
+| --- | --- | --- |
+| NES | FCEUmm | `.nes` `.unf` `.unif` |
+| SNES | Snes9x | `.smc` `.sfc` `.swc` `.fig` |
+| Game Boy / Color | Gambatte | `.gb` `.gbc` |
+| Game Boy Advance | mGBA | `.gba` |
+| Genesis / Mega Drive, Master System, Game Gear | Genesis Plus GX | `.gen` `.md` `.smd` `.sms` `.gg` |
+| Nintendo 64 | Mupen64Plus-Next | `.n64` `.z64` `.v64` |
+| PlayStation | Beetle PSX | `.cue` `.chd` `.pbp` `.m3u` `.iso` |
+| PlayStation 2 | ARMSX2 (PCSX2 fork) | `.iso` `.chd` `.cso` `.bin` |
+
+Cores ship **prebuilt** (committed via Git LFS) and are used by default; they are built from
+source with the opt-in flags above (see `cores/` for the libretro cores and
+`armsx2/build-emucore.sh` / `dolphin/build-emucore.sh` for the PS2 and GameCube/Wii cores).
+PlayStation 2 online play is supported through the emulated DEV9 network adapter (see the
+in-game **Online** tab).
+
+**How to use:** In the Library, tap **Add Custom Game** and select a ROM instead of an `.exe`. WinNative detects the console and adds the game to your Library. Tap **Play** to launch it with on-screen touch controls and physical gamepad support; the in-game menu (Back button or on-screen **MENU**) offers save/load state, reset, and fast-forward. PlayStation and PlayStation 2 BIOS files can be imported from **Settings → Retro**.
+
+### Contributing
+
+We welcome community contributions! Feel free to open a pull request for bug fixes, driver updates, UI improvements, or anything else you'd like to add.
+
+Please match the existing code style and ensure any AI-assisted code is thoroughly reviewed and tested before submission.
+
+---
+
+### Credits & Acknowledgments
+
+- **Original Winlator** by [brunodev85](https://github.com/brunodev85/winlator)
+- **Winlator Bionic** by [Pipetto-crypto](https://github.com/Pipetto-crypto/winlator)
+- **Pluvia** features by the [Pluvia](https://github.com/oxters168/Pluvia) / [GameNative](https://github.com/utkarshdalal/GameNative) community
+- **Mesa/Turnip** contributions by the [Mesa3D](https://www.mesa3d.org/) team
+- **Goldberg Steam Emulator** by [Mr. Goldberg](https://gitlab.com/Mr_Goldberg/goldberg_emulator), maintained by [Detanup01](https://github.com/Detanup01/gbe_fork)
+- **LibretroDroid** by [Filippo Scognamiglio](https://github.com/Swordfish90/LibretroDroid) (GPL-3.0) — the embedded libretro host for retro console support
+- **libretro / RetroArch** and the individual core authors, built from source: [FCEUmm](https://github.com/libretro/libretro-fceumm), [Snes9x](https://github.com/libretro/snes9x), [Gambatte](https://github.com/libretro/gambatte-libretro), [mGBA](https://github.com/libretro/mgba), [Genesis Plus GX](https://github.com/libretro/Genesis-Plus-GX), [Mupen64Plus-Next](https://github.com/libretro/mupen64plus-libretro-nx), [Beetle PSX](https://github.com/libretro/beetle-psx-libretro)
+- **ARMSX2** by the [ARMSX2](https://github.com/ARMSX2/ARMSX2) team (GPL-3.0) — the PlayStation 2 core, a fork of **[PCSX2](https://github.com/pcsx2/pcsx2)** (GPL-3.0), built from source into `libemucore`. PS2 online play uses PCSX2's DEV9 network adapter
diff --git a/app/build.gradle b/app/build.gradle
@@ -209,7 +209,13 @@ android {
                     'src/main/feature',
                     'src/main/sharedmemory',
                     'src/main/runtime',
-                    'src/main/shared'
+                    'src/main/shared',
+                    // SDL2 and love-android glue, vendored for the 3D engine.
+                    // Their class names are a JNI contract with liblove.so and
+                    // cannot be renamed or repackaged, so they are kept apart
+                    // from WinNative's own sources with their upstream licence
+                    // headers intact. See EMULATOR_CREDITS.md.
+                    'src/main/engine'
             ]
         }
     }
@@ -285,6 +291,10 @@ dependencies {
     implementation libs.playServicesGamesV2
 
     implementation libs.workRuntimeKtx
+
+    implementation project(':libretrodroid')
+    implementation project(':armsx2')
+    implementation project(':dolphin')
 }
 
 spotless {

diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml
@@ -127,6 +127,38 @@
             android:screenOrientation="sensorLandscape"
             android:exported="false" />
 
+        <activity
+            android:name="com.winlator.cmod.feature.retro.RetroActivity"
+            android:theme="@style/AppThemeFullscreen"
+            android:launchMode="singleTask"
+            android:screenOrientation="sensorLandscape"
+            android:configChanges="keyboard|keyboardHidden|orientation|screenSize|screenLayout|smallestScreenSize|density|navigation"
+            android:exported="false" />
+
+        <!-- The 3D engine. Runs in its own process like the Dolphin host does,
+             so a crash in SDL or the Lua engine cannot take WinNative's UI
+             process down with it. -->
+        <activity
+            android:name="com.winlator.cmod.feature.retro.Gen1EngineActivity"
+            android:process=":engine3d"
+            android:theme="@android:style/Theme.NoTitleBar.Fullscreen"
+            android:launchMode="singleTop"
+            android:screenOrientation="sensorLandscape"
+            android:configChanges="keyboard|keyboardHidden|orientation|screenSize|screenLayout|smallestScreenSize|density|navigation|uiMode"
+            android:exported="false" />
+
+        <activity
+            android:name="com.winlator.cmod.feature.retro.RetroAchievementsActivity"
+            android:theme="@style/AppThemeTranslucent"
+            android:configChanges="keyboard|keyboardHidden|orientation|screenSize|screenLayout|smallestScreenSize|density|navigation"
+            android:exported="false" />
+
+        <activity
+            android:name="com.winlator.cmod.feature.retro.RetroCheatsActivity"
+            android:theme="@style/AppThemeTranslucent"
+            android:configChanges="keyboard|keyboardHidden|orientation|screenSize|screenLayout|smallestScreenSize|density|navigation"
+            android:exported="false" />
+
         <receiver
             android:name="com.winlator.cmod.feature.shortcuts.ShortcutBroadcastReceiver"
             android:exported="true">