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 ART 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. 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 your set-up you 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 as 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 greeted 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, you must set-up Termux to have access to the regular device file system
pkg update
pkg upgrade
pkg install -y termux-tools wget openssl
termux-setup-storage
In the pop-up dialog shown, select Allow. This is kinda important so that you can use your 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://gitlab.com/wargames_tex/vassal_my_contrib/-/raw/master/android/setup-vassal.sh -O setup-vassal.sh bash setup-vassal.sh -
Follow the on-screen instructions
The script setup-vassal.sh basically does the steps 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 did not 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, you made sure that you can see the regular Android file system in Termux, so you can unpack VASSAL into your 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 you 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
More on how to upgrade VASSAL below.
Upgrade Termux Packages
Termux has many add-on packages that can be installed inside Termux. Go ahead 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 will have the JRE, that you need for VASSAL, installed, plus some utilities you will need.
openjdk-17-xis the JRE version 17 (adjust for availability)whichis small to that finds commandsnanois 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 ~/.vnc/xstartup. 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 ~/.vnc/config.
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 (though the it is set up to only allow connections from the device itself). 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
5901as 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 put1as 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.
Additional (optional) Set-up
These steps are done automatically by the quick method of installation, and is not needed if that method was used.
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;
Categories=Game
[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 ~Desktop/VASSAL.desktop. 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"/>
<icon name="application-x-vassal"/>
</mime-type>
<mime-type type="application/x-vassal-log">
<comment>VASSAL log file</comment>
<glob pattern="*.vlog"/>
<icon name="application-x-vassal"/>
</mime-type>
<mime-type type="application/x-vassal-save">
<comment>VASSAL save file</comment>
<glob pattern="*.vsav"/>
<icon name="application-x-vassal"/>
</mime-type>
</mime-info>
and type [ctrl]-x followed by y and [enter] to save the file and exit nano. See also ~/.dot/local/share/mime/packages/application-x-vassal.xml.
Then copy the desktop file to ~/.local/share/applications
mkdir -p ~/.local/share/applications
cp ~/Desktop/VASSAL.desktop ~/.local/share/applications/
And copy the icon to ~/.local/share/icons/hicolor/scalable
mkdir -p ~/.local/share/icons/hicolor/scalable/mimetypes
cp ~/VASSAL-current/VASSAL.svg ~/.local/share/icons/hicolor/scalable/mimetypes/application-x-vassal.svg
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.
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 ~/.shortcuts/VASSAL.
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 ~/.dot/vnc/xvassal, this script will be executed by the VNC server, so we need to make it executable
chmod a+x ~/.vnc/xvassal
See more below on adding the widget to the home screen
Adding a Widget to the Home Screen
If you installed Termux:Widget and either used the quick method or did everything in the manual method, then you can add a Termux widget to the home screen from which you can launch VASSAL.
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.
Running VASSAL
If you installed the home-screen widget, then you should be able to launch VASSAL by clicking the VASSAL entry in that widget.
Otherwise, you can start VASSAL by opening up the Termux app and type
~/.shortcuts/VASSAL
If you didn’t make that script, you can manually start the VNC server
vncserver :1
then start the VNC client
termux-url-open vnc://localhost:5901
In the desktop environment either click the Desktop icon or open a terminal
- Select the Applications menu in the top-left corner of your screen
- Select Terminal Emulator
In the terminal run
./VASSAL-current/VASSAL.sh
VASSAL running in the Termux GUI
Running my version of the Gettysburg (125th Anniversary Edition) module (1.2-ch).
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 environment. 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, as well as the downloaded archive
rm -rf VASSAL-3.7.9 rm -f VASSAL-3.7.10-linux.tar.bz2
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
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.
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.
Below are links to other files
