Introduction
Sometimes, Vassal may error out on some exception, or similar, and in that case, it can be useful to run Vassal through a debugger. Running an application in a debugger allows one to query the state of the application and thus pin down the problem that caused the error.
Important: Running an application in a debugger is not for the faint-of-heart. Only attempt this if you are willing to put in the work yourself, or you already have experience with such as task.
Requirements
Java Developement Kit (JDK)
You will need a full Java Development Kit (JDK) to run the Java debugger jdb.
Windows
Vassal comes with its own Java Runtime Environment (JRE) - but not a full JDK - on Windows. You therefore need to download and install a JDK, if you do not have one already.
You should pick a JDK that corresponds to the JRE shipped with Vassal (see the relevant information in the errorLog). For example, to get the JDK corresponding to the Temurin JRE 26, go to Temurin download page and select the appropriate version.
Follow the installation instructions to set up the JDK.
MacOS
Vassal comes with its own Java Runtime Environment (JRE) - but not a full JDK - on Windows. You therefore need to download and install a JDK, if you do not have one already.
You should pick a JDK that corresponds to the JRE shipped with Vassal (see the relevant information in the errorLog). For example, to get the JDK corresponding to the Temurin JRE 26, go to Temurin download page and select the appropriate version.
Follow the installation instructions to set up the JDK.
Linux
Chances are you already have a full JDK installed. If not, see below
Debian and derivatives
$ sudo apt install default-jdk
Redhat and derivatives
One of
$ sudo dnf install java-latest-openjdk
$ sudo yum install java-latest-openjdk
Arch Linux and derivatives
$ sudo pacman -S --needed jre-openjdk
Gentoo and derivatives
$ sudo emerge --ask --oneshot virtual/jre
Other distributions
Please refer to your distribution’s documentation.
Vassal source code
The best way to get the Vassal source code is to clone it from Github. To do that, you will need the application Git. Then, do
$ git clone https://github.com/vassalengine/vassal.git
$ cd vassal
$ git checkout 3.7.26
to point the sources at the 3.7.26 release (adjust for the release of Vassal that you use).
An alternative, is to download the source from the Vassal release assets (Source code .zip or .tar.gz) and unpack them somewhere.
Assumptions
Suppose you find there’s some problem that pops up when you use the module Module.vmod. Now, also assume that you downloaded the Vassal sources to a directory a la
| OS | Vassal source directory |
|---|---|
|
C:\Users\user\Documents\vassal |
|
/home/user/Documents/vassal |
|
/home/user/Documents/vassal |
Also assume that you have Vassal installed as
| OS | Vassal installation directory |
|---|---|
|
C:\Program Files\VASSAL |
|
/Applications/VASSAL.app |
|
/usr/share/vassal |
Launch Vassal in the debugger
When you run Vassal normally, it starts the Module Manger. When you from that module manager start or edit a module, then Vassal will spawn another process and execute a different entry point (VASSAL.launch.Player or VASSAL.launch.Editor, respectively). That process that we are most likely interested in, is the child process, so we need to by-pass the module manger and go straight at the child process.
Windows
Open a command prompt (cmd or PowerShell), and run
$ jdb -sourcepath C:\Users\user\Documents\vassal\vassal-app\src/main\java -cp C:\Program Files\VASSAL\lib\Vengine.jar VASSAL.launch.Player --load Module.vmod
MacOS
Launch a Terminal and do
$ jdb -sourcepath /home/user/Documents/vassal/vassal-app/src/main/java -cp /Applications/VASSAL.app/Contents/Resources/Java/Vengine.jar VASSAL.launch.Player --load Module.vmod
Linux
Open some terminal and do
$ VASSAL.sh --debug --source /home/user/Documents/vassal/vassal-app/src/main/java --load Module.vmod
Set-up break points and run Vassal
The will start the debugger, but Vassal isn’t running yet. If you found, when looking in the errorLog that the exception java.lang.FooException was thrown - for example, then you can make sure you will catch that in the debugger with
jdb$ catch all java.long.FooException
If you want to set a break-point in some method - say VASSAL.counters.FreeRotator.draw, then you can do
jdb$ stop at VASSAL.counters.FreeRotator.draw
To start Vassal, do
jdb$ run
Once the application is up and running, do the interactions that will trigger the problem. The debugger should break at that point and pause the application. Use the help command in jdb to get information about what you can do. For example print, list, and so on.
See also the Oracle (short) jdb manual and countless other resources on the World-Wide-Web.