How to Integrate VASSAL into the Linux Desktop

Introduction

Most Linux desktops (Gnome, KDE, etc.) adhere to the Filesystem Hierarchy Standard (FHS), which dictates were information should be found. That means that we can use a common approach to integrate VASSAL into most Linux desktop.

Linux desktops categorises files based on mime-types and applications are declared as Desktop applications that act on these mime-types. That means, that for VASSAL modules (.vmod), saves (.vsav), and logs (.vlog), we need to define VASSAL mime-types and associate the a VASSAL desktop application with these types.

More on the shared mime information can be found here

Below, we will assume that your VASSAL installation is in /opt/vassal/current (which could be a symlink to f.ex., /opt/vassal/3.7.12 for example).

The semi-automatic way

Change directory to your VASSAL installation directory

cd /opt/vassal/current

Download the integration script and make it executable

wget "https://gitlab.com/wargames_tex/vassal_my_contrib/-/raw/master/common/integration.sh?ref_type=heads&inline=false" -O integration.sh
chmod a+x integration.sh 

Run the integration script

./integration.sh 

Voila, that should be it.

By default, the Desktop integration is set up for the current user only. If you want to make the Desktop integration system wide, i.e., for all users, then run

./integration.sh -s 

If you cannot write to the VASSAL installation directory, you can specify that directory with the option -v, e.g.,

./integration.sh -v /opt/vassal/current 

There are many more options for the integration script. Run

./integration.sh -h 

to see them all

Step-by-step instructions

If you’d rather do the integration by hand, then you can follow the steps below.

We will assume that VASSAL is installed in /opt/vassal/current, so we define the environment variable VASSAL_DIR to point there

export VASSAL_DIR=/opt/vassal/current

Replace the value with what is appropriate for your system. We only need that variable while we do the integration. Later on it needn’t be set.

Also, we will assume the Desktop integration is done for a single user. That means all integration files should live under ~/.local'. We set the variable prefix` to point there

export prefix=${HOME}/.local 

If we are to do the integration system wide, then we should set prefix to /usr. In that case, we need super user privileges in the following (sudo). We only need that variable while we do the integration. Later on it needn’t be set.

Create desktop icon

  • Create the directory to store the icon in

      mkdir -p ${prefix}/share/icons/hicolor/scalable/mimetypes
    
  • Copy the VASSAL SVG icon image there

      cp $VASSAL_DIR/VASSAL.svg ${prefix}/share/icons/hicolor/scalable/mimetypes/application-x-vassal.svg 
    

Create mime data

  • Create the directory to store the mime data in

      mkdir -p ${prefix}/share/mime/packages
    
  • Change directory to that directory

      cd ${prefix}/share/mime/packages
    
  • Create the file application-x-vassal.xml with the content

      cat <<EOF > application-x-vassal.xml
      <?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"/>
          <generic-icon name="application-x-vassal"/>
          <sub-class-of type="application/zip"/>
        </mime-type>
        <mime-type type="application/x-vassal-log">
          <comment>VASSAL log file</comment>
          <glob pattern="*.vlog"/>
          <generic-icon name="application-x-vassal"/>
          <sub-class-of type="application/zip"/>
        </mime-type>
        <mime-type type="application/x-vassal-save">
          <comment>VASSAL save file</comment>
          <glob pattern="*.vsav"/>
          <generic-icon name="application-x-vassal"/>
          <sub-class-of type="application/zip"/>
        </mime-type>
      </mime-info>
      EOF
    
  • Update the mime database

    update-mime-database ${prefix}/share/mime
    

Create Desktop application

  • Create the directory to store the desktop entry in

      mkdir -p ${prefix}/share/applications
    
  • Change directory to that directory

      cd ${prefix}/share/applications
    
  • Create the desktop entry

      cat <<EOF > application-x-vassal.desktop
      [Desktop Entry]
      Type=Application
      MimeType=application/x-vassal-module;application/x-vassal-log;application/x-vassal-save
      Name=VASSAL
      Exec=${VASSAL_DIR}/VASSAL.sh
      Icon=application-x-vassal
      Actions=Run;Edit;
      Categories=Games
      
      [Desktop Action Run]
      Name=Run
      Exec=${VASSAL_DIR}/VASSAL.sh -l %f
                                         
      [Desktop Action Edit]
      Name=Edit
      Exec=${VASSAL_DIR}/VASSAL.sh -e %f
      EOF
    
  • Update the application database

      update-desktop-database ${prefix}/share/applications 
    

(Optionally) Add a launcher to the Desktop

  • Copy desktop entry to desktop directory

      cp ${prefix}/share/applications/application-x-vassal.desktop ~/Desktop 
    

Summary

After having done the above, you can now double-click any VASSAL file to open that file in VASSAL.

N.B.: If you open a save (.vsav) or log (.vlog), then VASSAL must know the corresponding module. Thus, you should have opened the corresponding module, at least once, in VASSAL before trying to open a save or log file from that module.

You do not need to do this integration if you upgrade VASSAL as long as the installation directory stays the same. This is why it is a good idea to unpack VASSAL in some directory and then have a symbolic link, with a fixed name a la current, point to the currently used version of VASSAL.

N.B.: The above sets up the VASSAL file types to be sub-classes of the ZIP file type, which means you should be able to easily extract or browse the content of the files with your default ZIP application.

3 Likes

Excellent post Christan,

Good to see this guidance on how to streamline the use of Vassal on Linux.

That installer at least should be part of the package.

Got a feeling there are going to be a lot new faces coming over from other platforms if things continue the way they are. :frowning:

Cheers,
Reg.

Great info. I use Vassal daily on Linux Mint. I do however fear that this level of detail might seem daunting for some new Linux users. By all means, use this guide if you feel comfortable. Just wanted to add my two cents that Vassal works great in Linux even if the mime types are not fully integrated like this.

I easily added Vassal to my start menu using the Edit menu option in the Cinnamon desktop GUI and simply open game files or log files from within Vassal once the app is open. I didn’t even consider double-clicking files to open them with Vassal.

1 Like

Upstream (@uckelman) developers are more than welcome to take the integration.sh script and distribute it in the Linux tar-ball.

Not entirely sure what you are referring to - perhaps my ignorance. Do you mean VASSAL users migrating from Windoze or MacOuze to Linux, or …?

I hope you, and others, noticed that I gave two ways to do this

The first method is arguably as simple as it gets.

So true

The method above has the advantage that it is agnostic to the exact desktop environment that you use (as long as it adheres to the freedesktop.org guidelines - which is almost all. Heck, it might even work on ChromeOS.

I tend to open modules etc. from the command line :slight_smile:

/opt/vassal/current/VASSAL.sh -l `pwd`/PanzerarmeeAfrika-ch-1.1.0.vmod

(a little annoying that you have to use pwd here, but that’s because VASSAL.sh changes directory to it’s parent directory so that the Java app can find stuff).

Guess we’re all different in that way :slight_smile:

Yours,
Christian

2 Likes

Yes…

The most daunting thing for a new Linux user is being presented with five pages of shell commands to do the simplest things which used to be done for them…

We should make the transition as easy as possible and programs easy to use before they move on to the advanced stuff.

Reg.