qtruffle

Standalone Flash player for EmuELEC – play .swf games fullscreen from EmulationStation with gamepad controls, powered by Ruffle running inside a kiosk-patched Qt WebEngine browser.

Features

• .swf files show up in EmulationStation like any other system
• Fullscreen kiosk mode – no browser UI, no address bar, no home screen
• Gamepad controls via gptokeyb: D-pad / left stick = arrow keys, right stick = mouse, A = click, Select+Start = quit
• Per-game controller mappings: place a <game>.gptk file next to the .swf
• Based on Ruffle 0.3.0 (web selfhosted, WASM) – good ActionScript 2/3 compatibility
• Also includes the full Qt Web Browser for regular web browsing (optional, added during setup)

Requirements

• EmuELEC 4.x on Amlogic aarch64 (tested on S922X / Mali-G31)
• Internet connection for the installer (~152 MB download)

Installation

Via EmuELEC Setup menu (recommended)

Copy install_ruffle.sh into your EmuELEC setup scripts directory and run it from the Setup section in EmulationStation. It downloads, installs and configures everything automatically, including an optional Qt Web Browser entry in your Ports list.

You also need to add a flash case to emuelecRunEmu.sh so the games launch through EmuELEC's standard emulator pipeline (this handles the clean return to the gamelist). Add it to the standalone case ${PLATFORM} block:

        "flash")
                if [ "${EMU}" = "ruffle" ]; then
            set_kill_keys "qtwebbrowser.aarch64"
            RUNTHIS='${TBASH} /storage/roms/ports_scripts/Flash-Ruffle.sh "${ROMNAME}"'
                fi
                ;;

Manual

Download the release archive, extract it on the device and run ./INSTALL.sh:

wget -O /tmp/qtruffle.tar.gz \
  https://github.com/worstcase-scenario/qtruffle/releases/latest/download/flash-ruffle-emuelec.tar.gz
mkdir -p /tmp/qtruffle && tar -xzf /tmp/qtruffle.tar.gz -C /tmp/qtruffle
cd /tmp/qtruffle && ./INSTALL.sh

Then put your .swf files in /storage/roms/flash and restart EmulationStation.

Disk usage

The port is a slimmed-down Qt WebEngine build (unused Qt/Chromium libraries and modules removed). It uses about 362 MB on disk from a ~152 MB download.

Controller mapping

The default flash.gptk maps:

Button	Action
D-pad / left stick	Arrow keys
Right stick	Mouse
A	Mouse click
B	Space
X	Ctrl
Y	Shift
L1 / R1	Z / X
L2 / R2	A / S
Select+Start	Quit

Place a <game>.gptk file next to your .swf to override the mapping for that game. See The Binding of Isaac - Wrath of the Lamb.gptk for an example.

Technical notes

The Qt Web Browser binary ships with the virtual keyboard input module hard-compiled in (QT_IM_MODULE=qtvirtualkeyboard), whose input filter intercepted arrow keys globally – making them unavailable to Flash games. A 19-byte binary patch (patch_binary.py) neutralizes this; qtwebbrowser.sh re-enables the keyboard for normal browser use via an environment variable.

A second binary patch redirects the QML entry point from the compiled-in resource (qrc:///qml/Main.qml) to the filesystem (file:./qml/Main.qml), allowing runtime QML edits without recompilation.

All QML changes (kiosk mode, URL load fix, focus handling) are documented in qml-kiosk.patch.

Building the distribution archive

make_dist.sh (run on the device) packs the patched port into the release .tar.gz, slimming it down and excluding private data (browser profile, logs, backups).

Credits

• Snowram – original Qt Web Browser aarch64 port for EmuELEC/PortMaster
• The Qt Project – Qt Web Browser application (GPL v3)
• Ruffle – Flash emulator (MIT / Apache 2.0)
• Qt Framework – Qt libraries (LGPL v3)

License

GPL v3 – see LICENSE for full details including all component licenses (Qt LGPL v3, Chromium BSD, Ruffle MIT/Apache 2.0).