parallel-gx2/README.md

# ParaLLEl GX2

Cemu (Wii U emulator) as a libretro core for RetroArch, `parallel_gx2_libretro`.

Version: **2.6-372-g29f2f1fa**, upstream Cemu as merged (`29f2f1fa`, 15 Oct 2026).

## Getting the core

Through RetroArch: **Online Updater → Core Downloader → Nintendo - Wii U (ParaLLEl GX2)**. The libretro buildbot builds the `libretro` branch nightly for Windows x64, Linux x64 and arm64, macOS x64 and arm64, and Android arm64-v8a and x86_64, so the downloadable core is always the current tree. The CI also builds iOS, tvOS and webOS. There are no releases here on purpose: one more place to download from is one more place to be out of date.

Build it yourself for anything else, or to test a change.

## Build

A static Makefile builds the core and everything it uses: the libraries are
submodules built with it, and the network layer is libretro-common's (HTTP
and TLS, with no libcurl, OpenSSL or mbedTLS), so nothing but a C++20
compiler and, on Linux, the system's GL and X11 headers is needed.

```bash
# Ubuntu/Debian: the headers the OpenGL and Vulkan surfaces are declared with
sudo apt install -y g++ make libgl-dev libegl-dev libx11-dev libxrender-dev libx11-xcb-dev

# Clone with submodules - the libraries and the community graphic packs live
# in them. On an existing clone: git submodule update --init --recursive
git clone --recursive https://github.com/libretro/parallel-gx2.git
cd parallel-gx2

make -j$(nproc)
# Result: parallel_gx2_libretro.so
```

The same Makefile builds the other targets: `make` under MSYS2 MinGW64 (or
with `CC`/`CXX` set to a MinGW-w64 cross compiler) for Windows,
`platform=osx` with `arch=arm64` or `arch=x86_64` for macOS,
`platform=ios-arm64` and `platform=tvos-arm64` (Metal only),
`platform=android-arm64` and `platform=android-x86_64` with `NDK_ROOT` set,
and a webOS SDK compiler as `CC`/`CXX` for webOS. `DEBUG=1` builds without
optimisation, `SANITIZER=address` with a sanitizer.

## Install

```bash
cp parallel_gx2_libretro.so ~/.config/retroarch/cores/
cp parallel_gx2_libretro.info ~/.config/retroarch/info/
```

## Setup

Everything the core reads lives under `Cemu/` in RetroArch's system directory (`<system>`), except the emulated NAND, which is in the save directory.

- **Keys:** `keys.txt` in `<system>/Cemu/`. Encrypted `.wud`/`.wux` images and NUS titles need it; a disc image's key can also be kept beside it, with the same name and the extension `.key` (`game.wux`, `game.key`), 16 bytes or 32 hex digits.
- **Games:** `.wua`, `.wud`, `.wux`, `.iso`, `.rpx`, `.elf`, or `title.tmd` of an unpacked NUS title.
- **Updates and DLC:** put them in `<system>/Cemu/titles/`, one folder per update or DLC, either as downloaded (`.app`/`.h3` next to `title.tmd` and `title.tik`) or unpacked (`code`/`content`/`meta`). They are found by title id and used without being copied.
- **Graphic packs:** the community packs are built into the core and unpacked to `<system>/Cemu/graphicPacks/` when content loads. They are refreshed whenever the core is a newer build, so don't edit them there: your own packs, and changed copies of the built-in ones, go in `<system>/Cemu/customGraphicPacks/`. A pack there at the same path as a built-in one (the folder with its `rules.txt`) replaces it, and survives core updates. Each pack the loaded game has shows up under **Graphic Packs** in the core options, with an Enabled switch and its presets. Changes take effect the next time the game is loaded.
- **Shared fonts:** `CafeStd.ttf`, `CafeCn.ttf`, `CafeKr.ttf` and `CafeTw.ttf` in `<system>/Cemu/resources/sharedFonts/`. Games need them for Japanese and other CJK text.
- **NAND (mlc01):** `<save>/Cemu/mlc01/`, created with the default folders on first start, as standalone Cemu does.
- **Account names:** System > Rename Active Account opens a name entry over the game: with a pad, Up and Down change the last character, Right adds one, Left removes one, Start accepts and Select cancels; a keyboard types the name (Enter accepts, Escape cancels). A core option cannot hold free text, so the accounts also take their names from `<system>/Cemu/account_name.txt`. The core writes the file itself the first time a title starts, with one line per account, `<id> = <name>`; change a name there (up to the console's ten characters) and the account has it the next time a title starts. The file is written again at each start and whenever an account is made or removed in **System**, so it always lists the accounts there are.
- **Logs:** `<system>/Cemu/log.txt`. Its first lines name the build it came from, so please attach it, with the RetroArch log, to bug reports.

## Controls

Port 1 is the Wii U GamePad by default; ports 2-4 start with nothing plugged in. Pick a device type per port in **Quick Menu → Controls → Port N Controls → Device Type**:

| Port | Device types |
|---|---|
| 1 | Wii U GamePad, Wii U GamePad + Wii Remote, Wii U GamePad + Wii Remote (sideways), Wii U Pro Controller |
| 2-4 | None, Wii Remote, Wii Remote (sideways), Wii U Pro Controller, Classic Controller |

- **Touch screen:** the mouse or a touchscreen acts as the GamePad's touch screen. In the layouts that show both screens, only touches on the GamePad's part count. A mouse gets an arrow cursor over the GamePad picture while it moves.
- **Motion:** **Controller → GamePad Motion** (off by default) gives the GamePad's gyroscope and accelerometer from the sensors RetroArch reads on port 1: a phone's or tablet's own, or a controller's. The log says "GamePad Motion: on" when RetroArch has them. On Linux with the **udev** controller driver, a DualSense or DualShock 4 has its sensors on a second input device ("... Motion Sensors") that a user cannot read by default; a rule such as `SUBSYSTEM=="input", KERNEL=="event*", ATTRS{name}=="*Motion Sensors", TAG+="uaccess"` in `/etc/udev/rules.d/`, then `sudo udevadm control --reload && sudo udevadm trigger`, makes it readable. RetroArch's SDL driver hands the sensors over with swapped axes, so aiming is skewed there; use udev.
- **Rumble:** the GamePad, Wii Remote and Pro Controller motors go to the frontend's rumble, scaled by **Controller → Rumble Strength** (100% by default).
- **Stick dead zone:** **Controller → Stick Dead Zone (Player 1)** for the GamePad or the controller on port 1, and **(Players 2-4)** for the rest; 25% by default, as in standalone Cemu.
- **Screens:** **Controller → Number of Screen Layouts** and **Layout 1-5** choose which layouts to cycle through (Default Screen, GamePad Screen, Side by Side, Top Bottom, Picture in Picture). **Next Screen Layout** picks the button combination that switches between them.
- **Portals:** Skylanders, Disney Infinity and LEGO Dimensions portals are emulated: the option for each (Emulate Skylanders Portal of Power, Emulate Infinity Base, Emulate Dimensions Toy Pad) is at the bottom of the core options, shown only while one of its games is loaded.

## Status (2026-10-23)

Games boot and run on Vulkan and on OpenGL, with sound, controllers, both screens and graphic packs. The core is synced with upstream Cemu (see below), and its options are translated through libretro's Crowdin.

Known issues:

- **Some games crash or misrender**, as in standalone Cemu, and some only in the core. Reports with `log.txt` and the RetroArch log are welcome on the issue tracker.
- **No save states.** Cemu cannot serialize its state, so `retro_serialize_size` returns 0.
- **The core stays loaded between games.** RetroArch unloads it, but the library itself stays in memory (on Linux on purpose, see `-z nodelete` below). Any state Cemu keeps for the whole process can leak from one game into the next. The known cases (DLC list, graphic pack module list, controller callbacks) are fixed.
- **OpenGL on Wayland renders black.** Use Vulkan there; OpenGL works on X11 (GLX).

Planned: output above 60 fps for games with high frame rate packs. The Cheats graphic packs have their own category, and games, updates and DLC are installed from the core options (Title Manager).

## Architecture

- Vulkan renders on the frontend's device (`RETRO_HW_CONTEXT_VULKAN` with the context negotiation interface) and hands RetroArch each finished image. OpenGL uses a 4.5 Core Profile HW context, plus a shared context for Cemu's GPU thread (GLX on X11, EGL elsewhere).
- The Vulkan device belongs to the frontend, so the core asks it for the extensions and features standalone Cemu enables, and the renderer then uses only what was actually enabled. An extension the GPU advertises is not necessarily enabled on a device RetroArch created, and `vkGetDeviceProcAddr` then returns null.
- `cache_context = true` keeps the Vulkan context across fullscreen toggles and video driver reinits, the present path asks the frontend for its render interface every frame, and the GPU thread parks at a command boundary while the frontend rebuilds its driver.
- Audio goes through `LibretroAudioAPI`, a lock-free ring buffer paced by the frames the frontend asks for.
- Input: libretro joypads drive VPAD (GamePad) and WPAD/KPAD (Wii Remote, Pro Controller, Classic Controller); pointer input is the GamePad touch screen.
- When the emulated process exits, `CafePPCProcessExit` only records it; `RETRO_ENVIRONMENT_SHUTDOWN` goes out from `retro_run`, because the callback fires on the emulated PPC thread.
- RetroArch calls the core's Vulkan `destroy_device` after `dlclose`, so on Linux the core is linked with `-z nodelete`.
- The standalone's GUI, input and audio backends are removed, and `.upstream-excluded` keeps them from coming back with an upstream merge.

### Key files

- `src/libretro/CemuLibretro.cpp` - the libretro core: `retro_*` exports, GL/Vulkan context negotiation, input, video pipeline
- `src/libretro/libretro_core_options.h` - core option definitions (translations in `libretro_core_options_intl.h`, generated from Crowdin)
- `src/audio/LibretroAudioAPI.{h,cpp}` - audio backend
- `src/libretro/LibretroWindowSystem.cpp` - WindowSystem without wxWidgets
- `src/Cafe/OS/libs/vpad/vpad.cpp`, `src/Cafe/OS/libs/padscore/padscore.cpp` - GamePad and Wii Remote/Pro Controller input

## Syncing with upstream Cemu

Upstream is [cemu-project/Cemu](https://github.com/cemu-project/Cemu) and its
branch is `main`, not `master`:

```sh
git remote add cemuup https://github.com/cemu-project/Cemu.git   # once
git fetch cemuup main
git merge cemuup/main
```

Last sync: upstream `29f2f1fa` (merged 23 Oct 2026). The core reports its version as `git describe --tags --match v2.6 cemuup/main` (`2.6-372-g29f2f1fa`), set in `retro_get_system_info` and `parallel_gx2_libretro.info`; update both, and the version at the top of this README, on every sync.

The fork has no `main` of its own: upstream is merged straight into `libretro`,
the only long-lived branch here.

What tends to break on a sync, none of which the conflict resolution shows:

- **Source lists.** The core builds from the Makefile, not upstream's CMake
  (which `.upstream-excluded` removes on every merge): a source file upstream
  adds or removes has to be added to or removed from `Makefile.common` by
  hand. Every unit of the core is compiled with `precompiled.h` force-included,
  as upstream's `cemu_use_precompiled_header()` does.
- **Boost and the network libraries.** The core has no Boost: the parts the
  emulator uses are small headers in `dependencies/boost-compat`, and
  `dependencies/curl-compat` carries libcurl's API over libretro-common's
  HTTP and TLS. Upstream code that reaches for another Boost header, or a
  libcurl or OpenSSL call these do not have yet, fails to build until they do.
- **Copied functions drifting.** The libretro `VulkanRenderer` constructor is a
  copy of upstream's adapted for the shared device; upstream keeps changing the
  original underneath it.
- **Extension gating.** See Architecture above - upstream adds calls guarded by
  device extension flags, and those flags cannot be trusted on a device the
  frontend created.
- **File access.** Upstream code that opens files with `FileStream` has to go
  through `VFSFileStream` here, otherwise the frontend's VFS (and Android SAF)
  is bypassed.

Debugging a crash on aarch64: `backtrace()` cannot unwind past the signal frame,
so the posix handler also records `fault/pc/lr/sp` into `<system>/Cemu/log.txt`.
Convert `lr` with the module base from that log's `parallel_gx2_libretro.so(+0xOFFSET)
[0xABSOLUTE]` line and run `addr2line -Cfie parallel_gx2_libretro.so <offset>`.