[Experimental] [Guide] How to run Java/Flash Games on the Raspberry Pi 3!

SuperFromND

Yep, you read the title right! In this guide, I'm going to explain how to run both Java games and Flash games on a Raspberry Pi 3 running RetroPie. Before we begin, let's just run through some questions...

Questions and Answers

Why are you writing this guide?
There's been a few threads about running Flash and Java games on this forum already, but most of them are outdated by a rather sizable amount of time, as well as being fairly vague in terms of how to run these types of games for yourself. I hope that writing this guide will help solve that problem.

Could this process be streamlined?
Probably. I'd imagine someone could create a script to be added to the Experimental section of RetroPie-Setup.

Can I use a gamepad?
Neither Gnash nor Java support gamepads natively, but hypothetically it could be possible to run joy2key and solve this issue.

What kind of performance can I expect?
It varies quite a lot depending on the games you want to play, when they were made, how optimized the code is, etc. Some games run at very much playable speed, others struggle at sub-1FPS speeds. Of course, considering the specs on the Pi 3 and the poor performance of Java and Flash games in general, it's to be expected.

If you need a more precise expectation, scroll down to the Compatibility List at the bottom of this post.

Requirements

A Raspberry Pi 3 running Retropie (preferrably with at least a gigabyte or two of free space)
A terminal program (I'd recommend WinSCP)
A USB keyboard (I'd recommend one with a built-in trackpad)
Basic knowledge of how to use a command line
Basic knowledge of how to edit an XML file

A small disclaimer

Keep in mind that none of this is officially supported (at least as of May 7th, 2018) by the RetroPie team. Neither the RetroPie team nor myself are responsible if you end up damaging your Pi or microSD card from trying to follow these steps. Always backup your Pi's microSD card before attempting any kind of experimental installation.

Step One: Installing the Programs

To run Java and Flash games, you're going to need two seperate programs to run them. For Flash games we will install a program called Gnash, and for Java games we will install the Oracle Java 8 runtime.

Start up your Pi and wait until EmulationStation appears, then close it either through the menu or by pressing F4 on your keyboard. You'll be brought to a command line, which is where we can install programs from. Run the command sudo apt-get update, to ensure that both Gnash and OpenJDK8 are available for installing.

To install Gnash (which is used for Flash games), run sudo apt-get install gnash.
To install the Oracle Java 8 runtime (which is used for Java games), run sudo apt-get install oracle-java8-jdk.

Both of these will take a little bit to install, so now would be a great time to drop your games onto your Pi.
While we're here, I might as well mention that both Java and Flash games can take up quite a bit of space, especially ones made after 2007 or so. I'd recommend double-checking your files to ensure you can fit everything.

Step Two: No Power Greater than X

As the title of this step might indicate, we're now going to initialize X to run these two programs. What is X, you may ask? You don't really need to know a whole lot about X for this, but as Wikipedia explains, it's essentially a GUI framework that's been in use on Unix systems for decades. For our case, both Gnash and Java require X to draw their graphics to the screen, so initalizing it is necessary. To install X, simply run the command sudo apt-get install xinit.

Step 3: Emulation Station

Now that we have everything that's necessary to run Flash and Java, let's now add a secton or two to Emulation Station for us to launch games.

Step 3A: Flash

First up: Flash. All of this is going to be done from WinSCP.
Navigate to the directory /opt/retropie/configs and press Ctrl-D to create a new directory. Name this new directory flash. Navigate into the new directory and press Shift-Ctrl-E to create a new file, and name it emulators.cfg. Copy-paste the following into this new file, and then press Ctrl-S to save it:

gnash = "sudo xinit -e 'gnash %ROM% -j 640 -k 480 --hide-menubar' -- :0"
default = "gnash"

This command is what starts Gnash.

Next, navigate to /etc/emulationstation and open the file es_systems.cfg. Copy-paste this into it, then press Ctrl-S to save the file:

  <system>
    <name>flash</name>
    <fullname>Adobe Flash</fullname>
    <path>/home/pi/RetroPie/roms/flash</path>
    <extension>.swf</extension>
    <command>/opt/retropie/supplementary/runcommand/runcommand.sh 0 _SYS_ flash %ROM%</command>
    <platform>flash</platform>
    <theme>flash</theme>
  </system>

This will tell EmulationStation to add a Flash section. Now for one last tweak: run emulationstation (or restart EmulationStation if it's already running), look for your Flash section, and select a game. Keep pressing A until you get the emulator configuration menu. Scroll down to Configure video mode for this emulator, select it, then select CEA-2. Doing this will stretch Gnash to fill the entire screen.

Step 3B: Java

The steps for Java are mostly the same, so I won't repeat myself, but here's the basic rundown:

Navigate to /opt/retropie/configs/ and create a directory named java
Navigate to that directory and create a file called emulators.cfg, with this as the contents:

java = "sudo xinit -e 'java -jar %ROM%' -- :0"
default = "java"

Navigate to /etc/emulationstation, open es_systems.cfg, and paste this into it:

  <system>
    <name>java</name>
    <fullname>Oracle Java</fullname>
    <path>/home/pi/RetroPie/roms/java</path>
    <extension>.jar</extension>
    <command>/opt/retropie/supplementary/runcommand/runcommand.sh 0 _SYS_ java %ROM%</command>
    <platform>java</platform>
    <theme>java</theme>
  </system>

Start a game and set video mode to CEA-2

And you're done!

Yep, that's it! You should now have Java and Flash games running on your RetroPie setup. Hopefully, it was worth the little bit of work it took to set it all up. Before I close this guide, I should note a few things, as well as give you a better idea of the type of performance to expect from this:

Caveats

Gnash only fully supports features up to SWF 7, with only partial support for SWF 8 and 9. Anything from SWF 10 and later is unimplemented. This means that collision issues and graphical issues are present in any game made past 2007 or so.
The "Open" option in Gnash does not work at all.
Gnash shows overscan artifacts on many games.
Sound is not present on Java.
Java cannot be stretched to an arbitrary resolution, meaning that most games will not fill the screen properly.

Compatiability List

Obviously, this list isn't all-encompassing considering the sheer number of games out there, but here's what I've tested so you can get a good idea of what does and doesn't run well:

Flash

Amberial

Runs at about 5fps, has severe layering issues. Definetly not playable.

Bloons

Does not get past the initial loading screen. Not playable.

Bow Man

Works perfectly!

Duck Life

Performance-wise works perfectly, but collision detection does not work at all in races.

Fancy Pants Adventure

Floor collision does not work on black scribbles, thus making it impossible to progess past the title screen.

Monkey go Happy 2

Playable, but outlines are missing which can make it fairly difficult to see certain items.

Monolith's Mario World

Runs at about 16fps idle, 5fps when moving. Ground isn't rendered, but functions correctly. Some visual effects are missing, and transitions are slow. Playable, but sluggish.

Pac-Xon

Performance-wise works perfectly, but you can't grab any power-ups.

Paper Mario World

Runs at about 20FPS, some collision weirdness. Grabbing a mushroom crashes Gnash, for some reason.

Portal: The Flash Edition

Game runs at about 15fps, even with all the effects and image quality turned to their lowest levels. A collision bug makes it impossible to play any further than the first chamber.

Red Ball

Flickers between a loading screen, a screen stating that the site does not support this game, the title screen, and the level select screen. Definetly not playable.

Riddle School 1

Transitions are slow, but otherwise runs perfectly.

Shape Switcher

Wasn't able to get past the loading screen using the Fupa version, and the Andkon version couldn't get past the main menu. Probably not particularly intensive, given the simple nature of the game.

Shopping Cart Hero

Runs at about 15fps. I'll consider it playable.

Super Mario 63

Runs at sub-1FPS. Definetly not playable.

Super Mario Flash

Flickers between the title screen, game over screen, and some other screens. Definetly not playable.

Sushi Cat

Flickers in between various screens, and slows down Gnash to a crawl. Definetly not playable.

The Impossible Game Lite

Works perfectly.

The World's Hardest Game

Playable, but the fade-in at the beginning causes some slowdown, plus it's impossible to complete Level 4 due to a collision bug.

This is The Only Level

Playable, but some levels experience slowdown. (particularly the Armor Games logo, and stages 28 and 30).

Yellow

Flickers in between various screens, and slows down Gnash to a crawl. Definetly not playable.

You Are a Pirate/LOL, Limewire

Works perfectly.

Java

Do note that on all games, no sound is present whatsoever.

FreeJ2ME

Runs just as well as on an actual PC. Can't really comment on performance, since FreeJ2ME is an experimental emulator to begin with.

Metagun

Runs at about 20FPS, though some major slowdown is present when blood is shown on screen.

Minecraft 4K

Runs at sub-1FPS, definetly not playable.

Update/Addendum (May 7th, 2018)

I just realized after installing RetroPie 4.4 fresh that this guide was WAY off in terms of what needs to be done from a stock setup. I've edited the guide quite a lot to (hopefully) correct these errors.

lilbud

@supercatfooz The Middle School version of me who wasted time in class playing these games thanks you.

Especially Duck Life, This is the only level and the worlds hardest game. So many hours of math class wasted playing those games.

SuperFromND

Update #1: Command Line Craziness!

After a bit of tinkering, I came up with an emulators.cfg file for Gnash, which can boot any game selected from EmulationStation as well as close X automatically!

This is the emulators.cfg file:

gnash = "sudo xinit -e 'gnash %ROM% -j 1280 -k 720 --hide-menubar' -- :0"
default = "gnash"

Let's walk through this command step-by-step since it's a little long.

xinitsimply starts X. It has a few differences from startx, mainly the fact that it's more flexible due to being lower-level. (in fact, startx is actually just a fancy wrapper for xinit).
-eis the execute parameter. It will run a command as soon as X is able to handle it.
gnash %ROM% runs Gnash with whatever SWF file you selected.
-j and -k are width and height parameters respectively. You're going to have to set these to whatever resolution your monitor is. If you don't know what your monitor's resolution is, you can find that out by running xrandr -d :0 while X is open.
--hide-menubar simply hides the menu bar at the top of the screen. This does mean you can only quit Gnash using Ctrl-Q or a killall gnash command, however it's completely optional so removing it won't affect anything. Edit: Turns out you can right click on Gnash to exit as well.
-- tells xinit that all the parameters for the command have been declared, and that it can now start looking for arguments to pass to X.
:0 tells X to draw stuff to display 0, which is the display your Pi is connected to by default.

Also, since we now have access to EmulationStation, and I know a lot of you are using Rookervik's aweosme Pixel theme, I went out of my way to create some custom art specifically for Flash:

You can add these yourself by cloning any folder in /etc/emulationstation/themes/pixel/ to /etc/emulationstation/themes/pixel/flash, and then replacing logo.png ang console.png with their respective images.

So what's the catch?

Unfortunately, xinit brings one pretty minor problem: you now have to manually configure the resolution of Gnash, since xinit does not automatically maximize programs, and because --fullscreen on Gnash doesn't play nicely with xinit. Thankfully, since the resolution is just two parameters in the emulators.cfg file (those two params are -j and -k, for width and height respectively), this means you only have to configure them once.

Oh, and I should mention: with a small modification, this emulators.cfg file can easily be modified to take Java games instead:

java = "sudo xinit -e 'java -jar %ROM%' -- :0"
default = "java"

However, Java doesn't have a "close window" hotkey built-in, so you can only close Java using a killall java command. On the plus side, Java does automatically draw to the center of the screen instead of the top-left, so you can at least not worry about setting resolution.

Addendum (May 2nd, 2018)

I just found out that you can get a full-screen Gnash with this setup by setting -j and -k to 640x480, and then setting the video mode to CEA-1 in the emulator config screen, reached by pressing A after selecting a game in EmulationStation.

If you want a higher resolution, just go into the emulator config screen, select the video mode with the resolution you want, and set -j and -k to the corresponding resolution.

SuperFromND

Update #2: Setup Script Silliness

I've managed to simplify the installation process by quite a lot: there's now a setup script!
Here's the entire script file:

#!/usr/bin/env bash

# This file is part of The RetroPie Project
# 
# The RetroPie Project is the legal property of its developers, whose names are
# too numerous to list here. Please refer to the COPYRIGHT.md file distributed with this source.
# 
# See the LICENSE.md file at the top-level directory of this distribution and 
# at https://raw.githubusercontent.com/RetroPie/RetroPie-Setup/master/LICENSE.md
#

rp_module_id="gnash"
rp_module_desc="gnash - Adobe Flash SWF Player"
rp_module_help="ROM Extensions: .swf\n\nCopy your Flash games to $romdir/flash\n\nTo change resolution, open emulators.cfg and add parameters -j and -k with width and height values.\n\nSetting video mode to CEA-1 in runcommand and setting -j and -k to 640x480 yields best performance at the cost of image quality."
rp_module_licence="GPL3 https://github.com/strk/gnash/blob/master/COPYING"
rp_module_section="exp"
rp_module_flags="!mali !kms"

function depends_gnash() {
	getDepends xinit xorg
	sudo chmod ug+s /usr/lib/xorg/Xorg #Fixes sudo permissions bug for X
}

function install_bin_gnash() {
	aptInstall gnash
}

function configure_gnash() {
	mkRomDir "flash"
	addEmulator 1 "$md_id" "flash" "xinit -e 'gnash --hwaccel vaapi --hide-menubar %ROM%'"
	addSystem "flash"
}

Simply copy the above into a shell script in /home/pi/RetroPie-Setup/scriptmodules/emulators, save it as gnash.sh, and run it through RetroPie Setup. Writing shell scripts isn't exactly my forte, so testers for this script would be highly appreciated!

herb_fargus

@supercatfooz last I tested gnash ran flash games like poo. Has something changed?

SuperFromND

@herb_fargus Not that I'm aware of, though for me it runs older games well enough to be playable; it's only newer games that run like trash, which is to be expected since Gnash doesn't support anything past SWF 9 right now.

Though it could just be because I'm running this at 480p instead of native res?

notthesame

i know its a old fourm on java but can this run on pi4? i want to play a few games i played back in late 2000s, also just to be sure if i can still do this today, thanks

LucasFebatis

Thank you very much for the friendly guide, I'm a beginner game developer and I'm looking to put my own Java Games in Retropie, I just need to see this issue of sound and performance

notthesame

@LucasFebatis I haven't tired it but I'm am soon, I wanted to play a few games back then, this is gonna be cool.