ARMSX

Android now uses the original PSX Lab backend with the existing Compose UI. See PSXLAB-BACKEND.md for build instructions, validation, save compatibility and current limitations. Historical platform documentation below also describes earlier engines and does not override those Android notes. ARMSX is a fork of psxe, rebuilt around a native FSUI donor shell and SDL2-hosted frontends for desktop, Android, iOS, UWP, web, and PSVita.

Local SwanStation dev integration

The Android dev Compose build now uses SwanStation with the normal dev frontend. This is not a public release; see SWANSTATION-DEV.md for source boundaries, unfinished features, build commands and verification results. Existing old-engine source edits are preserved but are not Android build inputs. The old-engine feature description below is not a SwanStation feature checklist.

Android Compose additions

Video settings include Native/2x/3x/4x HD presets, globally or for an individual game. These set internal 3D resolution rather than replacing textures or videos; they preserve the renderer and disable downsampling. Restart the game to apply.

The texture-pack browser downloads and installs a selected compatible pack automatically, with offline reuse. The catalogue is initially empty; only verified, redistribution-approved packs should be added. Selection uses the disc ID/region and never applies a pack globally.

CTR USA (SCUS-94426) has an experimental secondary-display companion. Launch the game on the top display of a dual-screen handheld such as Thor. The bottom shows a larger race map, eight vertical live racer positions with original portraits, and the timer/laps/Wumpa/items/boost display. Boot/menu/loading/results screens have an information panel. Adventure hubs have a read-only map/player marker; hub alignment and transitions still need broader live validation. Other games do not use this companion, and other CTR regions do not guess the USA memory layout.

Original pictures/fonts/maps come from the running user-supplied game; no game artwork is bundled or downloaded. With a populated bottom race panel, guarded temporary RAM drawing edits hide the original top race HUD. They do not change the ROM file, fruit collection or race mechanics, and are restored on pause, reset, shutdown, state save/load and rewind. Missing required artwork leaves the original HUD visible. Achievements are disabled for any session in which the drawing patch activates. Hub/menu displays do not activate it.

Main-library controller navigation now keeps highlighted covers visible without restartable scrolling animations, including partially clipped covers and recents/collection rows. Grid row steps account for cover size and safe-area padding. This does not change touch scrolling or emulation controls.

What It Supports

The Android Compose frontend includes an offline PS1 cheat catalogue under Cheats. Known serial/region matches load automatically; uncertain regions/revisions require confirmation in Browse cheat database. Select cheats by name, with optional search; no pasted codes are needed for covered games. Imported/custom groups and existing selections are preserved, and new database cheats start disabled. Back up your memory cards before using cheats. Some games and code types are not covered. Data is from Libretro under CC BY-SA 4.0; attribution/license files are bundled with the catalogue. Rebuild the assets with tools/update_ps1_cheats.py and the source commit recorded in ps1-cheats-NOTICE.txt.

ARMSX currently has the following emulator pieces wired up:

• CPU, DMA, GPU, SPU, MDEC, GTE, and timers
• CD-ROM loading
• memory cards
• BIOS selection and PS-X EXE boot
• screenshot capture
• logging controls
• VSync control
• fast forward
• protocol/file launch through armsx:///... on supported hosts
• the FSUI settings shell

Disc image support is:

• BIN/CUE
• single-track BIN
• ISO
• CHD, including mixed-mode metadata, pregaps/postgaps, audio byte order, and Q subchannel data
• ZIP archives containing a supported game image and its companion files

Not implemented yet:

• save states
• netplay
• texture packs

Accuracy and Acceleration

ARMSX has two portable CPU engines:

• cached is the default. It caches decoded instruction handlers, but still performs a real bus fetch and opcode check for every emulated instruction. Writes invalidate matching entries, including cached/uncached address aliases.
• interpreter is the reference path and remains selectable for diagnostics.

Neither engine emits native code, uses executable memory, or relies on host threading behavior. Select the engine in Settings, with --cpu-engine=cached|interpreter, or with ARMSX_CPU_ENGINE.

The GPU always uses the accurate software PlayStation rasterizer and keeps its 16-bit VRAM authoritative. Presentation has two SDL2 modes:

• SDL software, the default
• SDL accelerated, opt-in through Settings or ARMSX_GPU_BACKEND=sdl-accelerated

The accelerated mode uploads only changed VRAM scanlines to an SDL texture. It does not replace PS1 rasterization with host triangles, so switching presentation modes does not change emulated GPU results. If an accelerated SDL renderer is unavailable, ARMSX falls back to SDL software rendering.

Supported Targets

• Desktop: macOS, Linux, Windows
• Mobile and alternate hosts: Android, iOS, UWP, WebAssembly, PSVita
• CI also builds Linux x64, x32, arm64, arm32 and Windows x64/x32 packages

Desktop and Android are the main day-to-day targets. The other ports are present and buildable, but they are more platform-specific and may lag behind the desktop path.

CI Runners

The Gitea workflow matches whatever label your act runner advertises. If that label is a docker-mode label like ubuntu-latest:docker://..., Gitea will keep creating per-job bridge networks and can eventually hit Docker address pool exhaustion.

To run the jobs directly on the runner container or host, change the runner labels to host mode, for example ubuntu-latest:host or linux_amd64:host, then restart act_runner. If the runner is started from a Docker image, remove the /var/run/docker.sock mount when you want host mode.

Running

On desktop, launch the emulator directly:

./bin/armsx --bios=/path/to/bios.bin --cdrom=/path/to/game.cue

You can also launch a file with the protocol handler on supported hosts:

armsx:///absolute/path/to/game.cue

The app opens an FSUI shell where you can choose BIOS files, start discs, change settings, take screenshots, and toggle fast forward or VSync.

Settings are stored under SDL's pref path, usually SDL_GetPrefPath("nanodata", "armsx"), in settings.toml.

On WebAssembly, Start File, Start Disc, and Open Game Folder use the browser's permission-gated file and directory pickers. Selected files are copied into the Emscripten virtual filesystem for the current session. Directory access falls back to a multi-file directory input where the File System Access API is unavailable. USB mass-storage drives are intentionally handled through these file pickers; WebUSB does not expose protected mass-storage-class devices as a general filesystem.

Building

Linux Desktop

Install SDL2 development packages, then run:

./build.sh

macOS

Install SDL2 and dylibbundler:

brew install sdl2 dylibbundler

Then build a bundle:

./build.sh macosapp

Windows

Install a MinGW toolchain and SDL2, then run:

./build-deps.ps1
./build-win64.ps1
./build-win32.ps1

Android

Set ANDROID_NDK_ROOT to an NDK 27+ install and build:

./build.sh android

iOS

Use the bundled SDL2 xcframework and run:

./build.sh ios

UWP

Build the native runtime or solution from Windows:

./build-uwp-native.sh x64 Debug
./build-uwp-native.sh x86 Release
./build-uwp-all.ps1

WebAssembly

Requires Emscripten:

./build.sh wasm

Serve the generated bin/wasm directory over HTTP(S); browser file APIs are not available from a raw file:// URL.

PSVita

Requires VITASDK:

./build.sh psvita

Configuration

settings.toml is generated on first run. CLI flags always override file settings for the current session. Some internal fields still use historical psxe_* names for compatibility.

The generated defaults are:

[cpu]
execution_mode = "cached"

[gpu]
backend = "software"

Legacy renderer names such as hardware are accepted when reading old settings and normalize to sdl-accelerated when saved.

Validation

Run the deterministic source and subsystem matrix:

python3 tests/run_validation.py

The cases cover source invariants, cached/reference CPU differential execution and self-modifying code, GPU VRAM parity, CHD layout/subchannel logic, ZIP extraction and traversal rejection, and browser file-selection rules. make disc-probe IMAGE=/path/to/game.cue performs a read-only disc-open and sector-read smoke test.

make test-sdl-runtime is an optional headed host check that creates an accelerated SDL2 renderer, uploads a BGR555 texture, and presents it. It is intentionally not part of the deterministic matrix because graphical CI runners may not have a display or accelerated SDL driver.

License

ARMSX-specific material owned by Moon is proprietary and all rights are reserved. No use, copying, modification, redistribution, publication, commercial exploitation, or creation of derivative works is permitted without Moon's prior express written permission.

This proprietary license applies only to material Moon owns or is authorized to license. Upstream psxe code, contributor-owned portions, bundled frameworks, and third-party dependencies retain their existing licenses. See LICENSE and LICENSES/UPSTREAM-MIT.txt.

Acknowledgements

ARMSX uses:

• argparse.c
• log.c
• tomlc99
• SDL2
• FSUI donor / ImGui
• libchdr