How to run VASSAL on Android

Background

A bit of background first.

Android is an operating system built on top of the Linux kernel.
Android apps are typically written in the Java programming language and executed in Android Run-Time environment (ART).
- This Android-specific run-time environment is not a real Java Runtime Environment (JRE), and regular Java apps, in particular Graphical User Interface (GUI) Java apps cannot be executed by ART.
VASSAL is a Java application, and uses the Java GUI services.
The VASSAL app is executed in a Java Run-time Environment (JRE).
- Java apps do not run directly on the metal, but are run through the JRE abstraction layer. This means a Java app, once build, can run on any system that can run the JRE.
- VASSAL requires a true JRE, and the ARE is not a real JRE, and VASSAL can therefore not be run directly on Android.

Thus, to run VASSAL on an Android device, we need to get a true JRE onto the device.

We will do that via the very powerful app Termux. Remember, Android runs on a Linux kernel, and we can therefore set up an environment which uses the Linux kernel and run regular Linux user-land applications and services there.

To get a Graphical User Interface (GUI), we need a few more things too. The GUI back-end of Linux is X (nothing to do with what was known as Twitter, even though that service has appropriate the X name and logo). Android does not provide the X service, but we can set that service up in our Termux environment. But that is only half the story. We also need to have an X client that can actually show the GUI to us, and allow us to interact with the applications running on the server. Fortunately for us, X implementations speak the Virtual Network Computing (VNC) language, and we can thus use any of the available VNC apps available for regular Android.

With these considerations clear, we can go onto the practical steps needed to get VASSAL running on an Android device.

Installation

Needed apps

For our set-up we need the following Android apps

VASSAL (obviously) for Linux
A VASSAL module to test things out.
Termux
A VNC client. I chose RealVNC, but any other VNC client should do.

Below we will go through the steps of setting these up.

Important

Command listed below must be typed into Termux exactly how they are written. Case matters, as in downloads and Downloads are not the same thing. For example, if the instructions tells you to write

pkg update
pkg upgrade

then two commands should be entered exactly as written above at the command prompt. That is first, type p k g [space] u p d a t e [enter] and then p k g [space] u p g r a d e [enter].

If you are reading this on your Android device, you can highlight the commands and copy them to your clipboard. In Termux you can then long-press anywhere and select Paste to paste in the command into the commmand prompt.

Install Termux

Follow the installation instructions on the Termux web-site.

Note There is a Termux app in the Google Play store - do not use that. Currently (2024 and for the past 3+ years), that app is not kept up to date.

If you install from GitHub, be sure to take the version appropriate for you device architecture. If you are unsure, or do not know what your device’s architecture is, take the termux-app_v*+github-debug_universal.apk app.

Whether you install from GitHub or F-Droid you will need to OK installation from “untrusted” sources. Please see this guide.

Once you have installed the Termux app, go a head and launch it as any other app on your device. You will be created by black screen with text on it. Take a minute to read the text. More information, including a “Getting Started” Guide is available at the Termux Wiki pages.

Give Termux access to Android file system

After these two commands have finish, we will set-up Termux to have access to the regular device file system

termux-setup-storage

This is kinda important so that we can use our regular Android browser to download VASSAL modules and they become available inside Termux environment.

Optionally, install Termux:Widget app

To able to launch VASSAL directly from the home screen of your device, you need to install the Termux:Widget Android app. Please follow the installation instructions. As for Termux, do not install the app from the Google Play store.

Install a VNC client

Pick any VNC client you like form the Google Play store (I chose RealVNC). Open up the app, and go past any introduction screens.

About choosing a VNC client

Your choice of VNC client largely determines your experience with VASSAL on your device. It is therefore worth a little effort to look around for the client that will best suit your needs. For VASSAL, you want the client to have a good mouse emulation and perhaps an improved on-screen keyboard. If the VNC client supports physical keyboard and mouse connected to the device (f.ex. via Bluetooth), then that is also attractive.

The Quick (but experimental) Way

This is an experimental way to get you set-up with VASSAL on an Android device. No Warranty!

Start up Termux
In the terminal type

wget https://obj.vassalengine.org/images/0/03/Setup-vassal-sh.txt -O setup-vassal.sh
chmod a+x setup-vassal.sh
bash setup-vassal.sh

Follow the on-screen instructions

The script Media:Setup-vassal-sh.txt basically does the step below. If you have problems with it, open a thread in the Technical Support & Bugs Forum.

The steps in detail

If the quick (but experimental) way above didn't work, you can follow the steps outlined below

Download VASSAL

Open your regular Android browser and go to

https://vassalengine.org

and select Download VASSAL. Be sure to take the Linux version.

This will put a file a la

VASSAL-3.7.9-linux.tar.bz2

in your normal Download folder (adjust the version number to the version you downloaded).

Unpack VASSAL

Previously, we made sure that we can see the regular Android file system in Termux, so we can unpack VASSAL into our Termux environment directly from the Android file system. In the command prompt execute

cd 
tar -xjvf /sdcard/Download/VASSAL-3.7.9-linux.tar.bz2

Adjust the version number to the version you downloaded. To see which files you have in your Android Download folder, do

ls /sdcard/Download/

After unpacking, you will now have the directory

VASSAL-3.7.9

in your Termux environment (adjust the version number to the version you got). Below, we will assume that we can find the most recent VASSAL version installed in VASSAL-current, so you should make a symbolic link from your unpacked VASSAL installation to that

ln -s VASSAL-3.7.9 VASSAL-current

Upgrade Termux packages

Termux has many add-on packages that can be installed inside Termux. Let us go a head and upgrade any of these that need upgrading:

pkg update 
pkg upgrade

Install the Java Runtime Environment in Termux

At the command prompt enter

pkg install openjdk-17-x which nano

After this, you have the JRE that we need for VASSAL installed, plus some utilities you need.

openjdk-17-x is the JRE version 17 (adjust for availability)
which is small to that finds commands
nano is a simple text editor

Actually, openjdk-17-x is the Java Development Kit (JDK), which includes a JRE. But it also has tools for developing Java applications. That is, you have installed a Java development environment on your device.

Get X in Termux

Please also refer to these guidelines for more information.

In the Termux command line type

pkg install x11-repo

to add a repository of X packages. Then do

pkg install tigervnc xfce4 netsurf

to install a VNC server (tigervnc), a full desktop environment (xfce4), and a simple web-browser (netsurf).

Environments

One of the powers of Linux and other open-source platforms, such as Android, is that you have the option to chose what environment you want. As described in the Termux GUI guide you have a variety of options to chose from, and each open can be configured in a variety of ways.

Set-up the graphical environment

In your Termux app do

mkdir -p ~/.vnc 
nano ~/.vnc/xstartup

The first command creates the directory .vnc in your home directory, and the second edits the (new) file xstartup in that directory using the editor nano. In nano put in the lines

#!/data/data/com.termux/files/usr/bin/sh
xfce4-session &

The lines must be typed exactly as shown above. Then type [ctrl]-x, followed by y and [return] to save the file and close nano. See also Media:Dot-vnc-xstartup.txt (remember to remove first, empty line, and make it executable). Finally, make the script executable

chmod a+x ~/.vnc/xstartup

Next, we will configure our VNC server. Do

nano ~/.vnc/config

to make a new configuration file for our VNC server. In nano type in the exact lines

# Configuration of tigervnc 
# See also https://tigervnc.org/
localhost
depth=24
geometry=2400x1080

and then [ctrl]-x followed by y, and then [enter] to save the file and quit nano. See also Media:Dot-vnc-config.txt.

Note that the argument to geometry defines the resolution of the graphical interface. You should adjust that to suit your device. Search the World-Wide-Web to find out which resolutions your device supports. If in doubt, fall back to something like 1024x768.

The localhost setting above means that only clients on the same device may connect to the server, thus limiting the risk of malicious "guests" to your device.

You can adjust menu settings of the VNC server in the ~/.vnc/config file. Please refer to the TigerVNC documentation for more.

Launch the graphical environment

In your Termux app, execute

vncserver :1

The first time you execute this command, you will be prompted to set a password. Please pick a password that you can remember, but do not be too lax about it (i.e., do not make a password like 123456), as up-to-no-good people can get full access to your device through the VNC server. Typically, VNC clients will allow you to store passwords for your connections, or can use some password wallet service to store them. Thus, you do not necessarily need to be able to remember this password indefinitely.

Change VNC password

If you want to change or reset the VNC password, do

vncpasswd

and set a new password.

Start the VNC client

Open the regular Android VNC client app you installed, skipping past any introductory screens.

Next, create a new connection. Here, you should use

Host: localhost
Number: 1 (see more below)
Password: The password you created above.

With respect to the number: - The VNC server you started above is listening on port 5901.

Some VNC clients expects you to enter the full port number, in which case you must put 5901 as the number.
Other VNC clients (e.g., RealVNC) expects you to put the offset relative to the base port 5900, in which case you must put 1 as the number.

Now open the connection. You should see a Linux desktop. How you interact with the desktop depends on the VNC client. The VNC client app typically has a short introduction that allows you to get familiar with the interface.

Alternatively, you may start the VNC client from Termux with

termux-url-open vnc://localhost:5901

to launch your default VNC client.

Launch VASSAL

Now we are ready to actually launch VASSAL.

Go back to your VNC client which should still be running its connection to Termux. If not, then restart the connection from the VNC client app.

Click the Applications menu in the top-left corner and select Terminal Emulator. This will open up a terminal window with a command prompt, similar to what you have in the Termux app.

In that command prompt, type

cd VASSAL-current

to change directory into the VASSAL installation directory. Now type

./VASSAL.sh

to start VASSAL. Et voilá, you have VASSAL running on your Android device.

Use the VASSAL application to find your VASSAL modules and open them as you would on a computer.

Stopping the VNC server

Once you are done using VASSAL, you should stop the VNC server. In the Termux app execute

vncserver -kill :1

to stop the VNC server. The VNC client will be disconnected automatically and you can close that app too

Getting VASSAL modules

To get your favourite VASSAL module, visit

https://vassalengine.org/wiki/Category:Modules

with your regular Android Web-browser, and download the module to your Android Download folder. For example, I took a version of the Gettysburg (125th Anniversary Edition) module (1.2-ch), which gave me the file

GettysburgSmithsonian-1.2.vmod.zip

in my Android Download folder. Note that Google Chrome appends the .zip to the file name - it doesn’t actually put the file into a ZIP archive.

You should move the VASSAL modules to your Termux enviroment. Go back to the Termux app, and do for example

cd /sdcard/Downloads/ 
mv GettysburgSmithsonian-1.2.vmod.zip GettysburgSmithsonian-1.2.vmod

to remove the .zipfrom the file name. Here cd means "change directory" and mv means "move".

Then, go back “Home” in Termux

cd

and make a directory to hold your VASSAL modules, named for example VMods.

mkdir VMods

Here, mkdir means "make directory".

We can then move our module there to that we have all our modules in a meaningful place

mv /sdcard/Download/GettysburgSmithsonian-1.2.vmod VMods/

Restarting

First, open up your Termux app and run the command

vncserver :1

Then open your VNC client app and reconnect to host=localhost and number=1 and described above. Many VNC client apps lets you save connection settings and you should be able to use that setting to quickly get back.

Upgrading VASSAL

If you want or need to upgrade your VASSAL installation, you should essentially follow the relevant steps above. That is

From your regular Android browser, navigate to the VASSAL site and download the VASSAL version for Linux that you need - say VASSAL-3.7.10-linux.tar.bz2
Open your Termux app
Unpack the downloaded VASSAL archive

cd 
tar -xjvf /sdcard/Download/VASSAL-3.7.10-linux.tar.bz2

Remove the old current link

rm VASSAL-current

Make the newly unpacked installation the current one

ln -s VASSAL-3.7.10 VASSAL-current

You may want to delete the old (say 3.7.9) installation to free up some space

rm -rf VASSAL-3.7.9

Upgrade Termux packages

From time to time, you should upgrade the packages installed inside Termux. Do

pkg update 
pkg upgrade

More

Below are some tricks to get more out of your installation. If the quick (but experimental) way of setting up VASSAL worked for you, then these steps are more or less done already.

VNC Server script

You may want to make a small script to easily start and stop the VNC server. In the Termux app, do

nano vnc

to make the new file vnc and put in the exact lines below

#!/data/data/com.termux/files/usr/bin/sh
oper=start

while test $# -gt 0 ; do
    case $1 in
    start|stop) oper=$1 ;;
    --) break ;;
    *) echo "Usage: $0 [start|stop]"; exit 0;;
    esac
    shift
done
    
case $oper in
start)
    vncserver :1
    ;;
stop)     
    vncserver -kill :1
    ;;  
esac

and type [ctrl]-x followed by y and [enter] to save the file and exit nano.

We need to make the script executable, so do

chmod a+x vnc

You can now do

./vnc start

to start the VNC server, and

./vnc stop

to stop the VNC server.

You can start the VNC client from within Termux with the command

termux-url-open vnc://localhost:5901

Desktop launcher

To make a Desktop launcher icon for VASSAL in the Termux GUI, do in your Termux app

cd ~/Desktop 
nano VASSAL.desktop

and enter the exact lines below

[Desktop Entry]
Type=Application
MimeType=application/x-vassal-module;application/x-vassal-log;application/x-vassal-save
Name=VASSAL
Exec=/data/data/com.termux/files/home/VASSAL-current/VASSAL.sh
Icon=/data/data/com.termux/files/home/VASSAL-current/VASSAL.svg
Actions=Run;Edit;

[Desktop Action Run]
Name=Run
Exec=/data/data/com.termux/files/home/VASSAL-current/VASSAL.sh -l %f
                                   
[Desktop Action Edit]
Name=Edit                                                     
Exec=/data/data/com.termux/files/home/VASSAL-current/VASSAL.sh -e %f

and type [ctrl]-x, followed by y and [enter] to save the file. See also Media:Desktop-VASSAL-desktop.txt (remember to make it executable). Now do

chmod a+x Desktop/vassal.desktop

to make the file executable. You can now double-click the Termux GUI Desktop VASSAL icon to launch VASSAL.

Associate `.vmod` and `.vlog` files with VASSAL

In your Termux app, do

mkdir ~/.local/share/mime/packages
nano ~/.local/share/mime/packages/application-x-vassal.xml

and enter the exact line

<?xml version="1.0"?>
<mime-info xmlns='http://www.freedesktop.org/standards/shared-mime-info'>
   <mime-type type="application/x-vassal-module">
     <comment>VASSAL module file</comment>
     <glob pattern="*.vmod"/>
   </mime-type>
   <mime-type type="application/x-vassal-log">
     <comment>VASSAL log file</comment>
     <glob pattern="*.vlog"/>
   </mime-type>
   <mime-type type="application/x-vassal-save">
     <comment>VASSAL save file</comment>
     <glob pattern="*.vsav"/>
   </mime-type>
</mime-info>

and type [ctrl]-x followed by y and [enter] to save the file and exit nano. See also Media:Dot-local-share-mime-packages-application-x-vassal-xml.txt (remove first, empty line).

Then copy the desktop file to ~/.local/share/applications

mkdir -p ~/.local/share/applications
cp ~/Desktop/VASSAL.desktop ~/.local/share/applications/

Now, update the Application and Mime type data base

update-desktop-database ~/.local/share/applications 
update-mime-database ~/.local/share/mime

Now, double-tapping a .vmod file in the Termux GUI file manager will open up that module in VASSAL.

Download modules in the Termux GUI

In the VNC client connection to your Termux environment, open a terminal as described above and type

netsurf

This will open a simple web-browser, which you can then direct to

https://vassalengine.org/wiki/Category:Modules

to find the module you want. By default, the modules are downloaded to your Termux home directory. You can move them to your VMods directory by typing in the terminal

mv ~/DDaySmithsonian-2.0.vmod ~/VMods/

for example.

Launch VASSAL from the Android home screen

For this to work, you need to install the Termux:Widget Android app. Please follow the installation instructions. As for Termux, do not install the app from the Google Play store.

Next, open up your Termux app and do

mkdir -p ~/.shortcuts

to make a directory for Termux home screen short cuts. We will make a short cut script named VASSAL in that directory. In the Termux app execute

nano ~/.shortcuts/VASSAL

to open the (new) file ~/.shortcuts/VASSAL in the nano editor. Type in the exact lines below

#!/data/data/com.termux/files/usr/bin/bash

xstart=$HOME/.vnc/xvassal
oper=start

read -n 1 -p "Do want to start? (Y/n) "
case x$REPLY in
  xy|xY|x) oper=start ;;
  *) oper=stop ;;
esac

case $oper in
start)
    echo "IMPORTANT: Enable Termux Wake-Lock through its notification"
    termux-wake-lock
    if test $? -ne 0 ; then 
        read -n 1 -p "Failed to aquire Wake-lock, exiting"
        exit 1
    fi

    vncserver \
        -xstartup $xstart \
        -autokill \
        -fg \
        :1 &

    vnc_pid=$!

    termux-open-url vnc://localhost:5901

    wait $vnc_pid

    termux-wake-unlock
    ;;
stop)
    echo "Stopping the VNC server"
    vncserver -clean -kill :1
    ;;
esac

Press [ctrl]-x, followed by y and [enter] to save the script and exit nano. See also Media:Dot-shortcuts-VASSAL.txt (remove first, empty line and remember to make it executable).

This script will be executed from the Termux widget, so we need to make it executable

chmod a+x ~/.shortcuts/VASSAL

Next, we will make a special X start-up script that will execute VASSAL in the GUI session. Do

nano ~/.vnc/xvassal

and put in the exact lines

#!/data/data/com.termux/files/usr/bin/bash

xfce4-session &
env bash $HOME/VASSAL-current/VASSAL.sh

followed by [ctrl]-x, followed by y and [enter] to save the script and exit nano. See also Media:Dot-vnc-xvassal.txt (remove first, empty line and remember to make it executable), this script will be executed by the VNC server, so we need to make it executable

chmod a+x ~/.vnc/xvassal

Now we need to add the widget to the Android home screen. Go back to the Android home screen and long-press the background. In the pop-up menu, select Widgets and scroll down to find Termux:Widget. Long press it, and drag to the Home screen.

You will see a small widget (default 2x2) with a list of Termux short-cuts - in particular the short cut VASSAL. You can click that to launch the VNC server and client in one go and have VASSAL running in the Termux GUI environment.

Screenshots

VASSAL running in the Termux GUI

Running my version of the Gettysburg (125th Anniversary Edition) module (1.2-ch).

Files for download

Below are downloadable versions of the scripts generated above. Remember to make them executable

chmod a+x file-name

replacing file-name with the actual file name.

Media:Dot-vnc-config.txt to be saved as ~/.vnc/config
Media:Dot-vnc-xstartup.txt to be saved as ~/.vnc/xstartup - remove first line
Media:Dot-vnc-xvassal.txt to be saved as ~/.vnc/xvassal - remove first line
Media:Dot-shortcuts-VASSAL.txt to be saved as ~/.shortcuts/VASSAL - remove first line
Media:Desktop-VASSAL-desktop.txt to be saved as ~/Desktop/VASSAL.desktop
Media:Setup-vassal-sh.txt to be saved as ~/setup-vassal.sh - remove first line

Note, in some of these files (those with remove first line), an additional extra blank line (possibly starting with #) was added at the top of the file. This is because MediaWiki does not allow uploads of shell scripts. Remove that line from the files for example using the editor nano.

Below are links to other files

Media:Dot-local-share-mime-packages-application-x-vassal-xml.txt to be saved as ~/.local/share/mime/packages/application-x-vassal.xml

Vassal-on-android

Contents

How to run VASSAL on Android

Background

Installation

Needed apps

Important

Install Termux

Give Termux access to Android file system

Optionally, install Termux:Widget app

Install a VNC client

About choosing a VNC client

The Quick (but experimental) Way

The steps in detail

Download VASSAL

Unpack VASSAL

Upgrade Termux packages

Install the Java Runtime Environment in Termux

Get X in Termux

Environments

Set-up the graphical environment

Launch the graphical environment

Change VNC password

Start the VNC client

Launch VASSAL

Stopping the VNC server

Getting VASSAL modules

Restarting

Upgrading VASSAL

Upgrade Termux packages

More

VNC Server script

Desktop launcher

Associate `.vmod` and `.vlog` files with VASSAL

Download modules in the Termux GUI

Launch VASSAL from the Android home screen

Screenshots

Files for download

Vassal-on-android

How to run VASSAL on Android

Background

Installation

Needed apps

Important

Install Termux

Give Termux access to Android file system

Optionally, install Termux:Widget app

Install a VNC client

About choosing a VNC client

The Quick (but experimental) Way

The steps in detail

Download VASSAL

Unpack VASSAL

Upgrade Termux packages

Install the Java Runtime Environment in Termux

Get X in Termux

Environments

Set-up the graphical environment

Launch the graphical environment

Change VNC password

Start the VNC client

Launch VASSAL

Stopping the VNC server

Getting VASSAL modules

Restarting

Upgrading VASSAL

Upgrade Termux packages

More

VNC Server script

Desktop launcher

Associate .vmod and .vlog files with VASSAL

Download modules in the Termux GUI

Launch VASSAL from the Android home screen

Screenshots

Files for download

Associate `.vmod` and `.vlog` files with VASSAL