Getting Started [Deprecated]

[slimy]

This guide takes you through the installation of VASSAL, up through loading and playing a game.

Note: Java comes bundled with Vassal on Windows and MacOS since Vassal v3.3. On these platforms, ignore any instructions about installing Java.

Installation

Navigate to the VASSAL home page and click on the “Get VASSAL for …” button. It should detect your operating system and download the latest version for you. If you need a different version of VASSAL for any reason follow this link: Look here for others..

Having got the file, what you do next will depend on your operating system.

Linux

Firstly I strongly recommend you create a VASSAL directory in your home directory.

cd ~
mkdir VASSAL

Then copy the downloaded file to this VASSAL directory. Here XXX represents the version number.

cp ~\Downloads\VASSAL-XXX-linux.tar.bz2 VASSAL

Now you will need to decompress the downloaded file.

cd VASSAL
bzip2 -d VASSAL-XXX-linux.tar.bz2
tar xvf VASSAL-XXX-linux.tar

Now to run VASSAL, you run the VASSAL.sh script in the VASSAL-XXX directory.

cd VASSAL-XXX
./VASSAL.sh

Mac

I need help here.

Windows

I need help here.

Adding your First Module

First you must start VASSAL. If you do not have any modules yet it may look something like this:

Now download a module. I strongly recommend you create a special directory for the module files and copy your modules there from your Downloads directory. This is in case you need to clear out your Downloads directory to save space. As an example I will pick Core Worlds.

Taking the Tour

Connecting to the Server

Loading a module/basic controls

Pbem - making a LOG file

Setting your Preferences

[cholmcc]

Hi,

Looks good.

Once you complete the above, perhaps make a new wiki page. Use pandoc to convert the Markdown to MediaWiki:

pandoc -f Markdown -t mediawiki input.md > output.wiki 

And then copy’n’paste into new Wiki page.

Yours,
Christian

[uckelman]

@cholmcc

Once you complete the above, perhaps make a new wiki page.

This is part of a project to move non-module pages from the wiki to be wiki posts here, and to edit and bring them up-to-date. Nothing is going back to the wiki; it’s going to be decommissioned when all the non-module pages are moved and the replacement game library frontend is ready.

[cholmcc]

@uckelman

This is part of a project to move non-module pages from the wiki to be wiki posts here, and to edit and bring them up-to-date

Great. You can use the inverse pandoc command to get a first draft. Open a wiki page in editor, copy the wiki code to a file, say input.wiki and do

pandoc -f mediawiki -t markdown input.wiki > output.md

That may speed things up a tad.

@slimy

Mac

I need help here.

Windows

I need help here.

The current instructions are good, but the screenshots could do with an update

@slimy

Now you will need to decompress the downloaded file.

cd VASSAL
bzip2 -d VASSAL-XXX-linux.tar.bz2
tar xvf VASSAL-XXX-linux.tar

Might I suggest

mkdir -p /opt/vassal
tar xvjf VASSAL-X.Y.Z-linux.tar.bz2 -C /opt/vassal
cd /opt/vassal/
ln -s VASSAL-X.Y.Z current

And edit ~/.profile to have

alias vassal=/opt/vassal/current/VASSAL.sh

(One time only). Upgrading is then

tar xvjf VASSAL-X.Y.Z+1-linux.tar.bz2 -C /opt/vassal
cd /opt/vassal/
rm current
ln -s VASSAL-X.Y.Z+1 current

And VASSAL can be executed by

vassal

You may also want to include pointers on how to set up Mime types and file associations (see other post or the VASSAL on Android guide, which you might want to link to too).

Yours,
Christian

[slimy]

Christian

Funnily enough my machine does not have a “/opt” directory so clearly your instructions are not generic enough.

On my system I do actually have a desktop icon set up but I had to convert the svg file to a png to get it to work, and I think that’s too much. If I can get that fixed in the distributed VASSAL file including instructions for that would be a good idea.

I guess suggesting users setup an alias in their profile would not be a bad idea though.

As for the Android setup page that needs migrating and if noone steps forward it is likely to be deleted. If you want to help I suggest you join the discord Vassal and navigate to #version_4.

[cholmcc]

@slimy

Funnily enough my machine does not have a “/opt” directory so clearly your instructions are not generic enough.

According to the Filesystem Hierarchy Standard, which most if not all Linux distros follow,

/opt is reserved for the installation of add-on application software packages.

It is therefore surprising that your machine does not have that directory. /opt is where for example Google Chrome, conda, and snaps are installed, typically. It is really the right place for VASSAL too. In any case the -p option for mkdir will make the directory.

@slimy

On my system I do actually have a desktop icon set up but I had to convert the svg file to a png to get it to work, and I think that’s too much. If I can get that fixed in the distributed VASSAL file including instructions for that would be a good idea.

See this post for an integration script and files. Ideally this would be part of the distribution. If a PNG is needed, which I don’t think is the case for most desktops, then it is easily made with

convert VASSAL.svg VASSAL.png

@slimy

I guess suggesting users setup an alias in their profile would not be a bad idea though.

The above integration script sort of takes care of that by making a symbolic link in /use/local/bin, ~/.local/bin, or <prefix>/bin.

@slimy

As for the Android setup page that needs migrating and if noone steps forward it is likely to be deleted. If you want to help I suggest you join the discord Vassal and navigate to #version_4.

I can do the Markdown of the VASSAL on Android page - that’s actually how I initially wrote it . Will be next week though. Where’s the best place to post it? Including images and files.

Yours,
Christian

[jrwatts]

@cholmcc

/opt is reserved for the installation of add-on application software packages.

It is therefore surprising that your machine does not have that directory. /opt is where for example Google Chrome, conda, and snaps are installed, typically. It is really the right place for VASSAL too. In any case the -p option for mkdir will make the directory.

On my (Kubuntu 22.04) system, /opt is only writeable by root, so I would need to use sudo to install VASSAL there; I just keep it in my home directory, instead (it’s a single-user system anyway, no need for it to be accessible to other users).

[slimy]

Christian,

Here is stub for the Android stuff: Android stuff . The advice is to copy in directly from the Wiki and then edit. Don’t try and edit the Wiki and copy that.

I have to agree with Jonathon. The point of /opt and /usr is to make it available to all users. Specifically the point of /opt is so that a Vendor does not need to know anything about the target system, which would make it a better option for VASSAL than /usr. But /opt probably won’t be in the PATH and as far as I can tell relies on some sort of desktop integration, which is far more fragile.

In any case /opt (and /usr) require root access to install. But if you need to use root to install neither should one be setting up aliases. It should work without the aliases.

What we have here is that Linux does not yet provide a seamless platform for vendors like VASSAL. I believe flatpak is Linux’s strategic solution to solving that problem, but I don’t see anyone stepping up to maintain VASSAL packages in flatpak and I certainly won’t.

In the meantime the solution I am proposing works well enough if someone knows how to use a command line. It does not require root access. It should always work. It supports multiple versions. It does not prevent aliasing or desktop integration.

[Grognard]

I chose to let the directory containing the latest version of Vassal I have downloaded reside in /opt on my computer running Linux Mint. I do this mostly because I don’t like junking up my home directory more than it already is with program files or config files other than what is already there by default.

One of the very few things I don’t like about Linux since I switched to it several months ago is the default placement of all those files and folders, largely hidden by default, and therefore out of sight and out of mind in a GUI file explorer unless I choose to view them. Maybe because of my experience running Windows for decades, but it just seems wrong having programs and/or config files- some of which like Steam or Thunderbird take up GBs of space- being stored in the same directory as personal user files in Desktop, Documents, Downloads, Music, Photos, Public, Templates and Videos directories.

You can download as many versions of Vassal as you want though and put them all pretty much anywhere on your Linux system and make a shortcut or create a key combo for convenience to launch any one of them.

[cholmcc]

@slimy

Here is stub for the Android stuff: Android stuff .

Thanks.

@slimy

The advice is to copy in directly from the Wiki and then edit. Don’t try and edit the Wiki and copy that.

Oh, I know how to do it. I’ll use pandoc to make an offline conversion and then adapt.

@slimy

I have to agree with Jonathon.

Sorry, but I missed what opinion Jonathan stated that you agree with.

One can argue,

@Grognard

I do this mostly because I don’t like junking up my home directory more than it already is with program files or config files other than what is already there by default.

is good practise. When it comes to permissions, one can simply make the main user group owner of /opt/vassal

sudo chown :users /opt/vassal
sudo chmod g+w /opt/vassal

@slimy

The point of /opt and /usr is to make it available to all users. Specifically the point of /opt is so that a Vendor does not need to know anything about the target system, which would make it a better option for VASSAL than /usr.

I don’t think that’s the point of /opt. It is certainly not the stated purpose in the FHS. Vendors do, however, tend to dump and awful lot of stuff into /opt, to not rely on specific library versions on the target system - much like Windows and MacOSX applications tend to bring in everything from a C library to GUI libraries. Thankfully that, almost, not the case for VASSAL (some Java packages that could be found on the system are embedded into the VASSAL jar).

@slimy

But /opt probably won’t be in the PATH and as far as I can tell relies on some sort of desktop integration, which is far more fragile.

No more fragile than some arbitrary sub-directory of $HOME. Users would need to add $HOME/VASSAL/VASSAL-X.Y.Z to their $PATH - just like for /opt/vassal/current - same difference. There’s no more need for desktop integration in either case.

Since VASSAL explicitly sets, and expect, the current working directory to the installation directory, it really doesn’t matter from which directory it is executed - you will need to provide full paths to the -l option anyway.

@slimy

In any case /opt (and /usr) require root access to install. But if you need to use root to install neither should one be setting up aliases. It should work without the aliases.

The script linked to in the previous reply does not set up an alias but a symbol link to the target bin directory. Again, you do not necessarily need privileged access if the ownership is setup once, as outlined above.

@slimy

What we have here is that Linux does not yet provide a seamless platform for vendors like VASSAL.

That is not correct. FHS is exactly addressing this through f.ex. /opt.

@slimy

I believe flatpak is Linux’s strategic solution to solving that problem, but I don’t see anyone stepping up to maintain VASSAL packages in flatpak and I certainly won’t.

Flatpack or Snap - these are all different solutions that have different merits and pitfalls. Ubuntu - and derivatives - switch to snap for many packages, including Firefox and the like. Debian did not and favours native packages.

VASSAL will have a hard time entering Debian with its current source base, as it uses many (more or less) obsolete external Java packages. The best option for that would be to build a package that goes into /opt with some wrapper and integration stuff in /usr - like Google Chrome does it.

@slimy

In the meantime the solution I am proposing works well enough if someone knows how to use a command line.

I would argue that if you know how to use a shell then you also know about sudo.

A few things:

cd # without argument goes home
mkdir VASSAL
tar xvjf Downloads/VASSAL-X.Y.Z.tar.bz2 -C VASSAL
rm Downloads/VASSAL-X.Y.Z.tar.bz2
(cd VASSAL && ln -s VASSAL-X.Y.Z current )
echo "alias vassal=$HOME/VASSAL/current/VASSAL.sh" >> .profile

Upgrade

tar xvjf Downloads/VASSAL-X.Y.Z+1.tar.bz2 -C VASSAL
(cd VASSAL && rm -f current && ln -s VASSAL-X.Y.Z+1 current)

In case of /opt

sudo mkdir -p /opt/vassal
sudo chown :`id -gn` /opt/vassal
sudo chmod g+w /opt/vassal
tar xvjf Downloads/VASSAL-X.Y.Z.tar.bz2 -C /opt/vassal
rm Downloads/VASSAL-X.Y.Z.tar.bz2
(cd /opt/vassal && ln -s VASSAL-X.Y.Z current )
echo "alias vassal=/opt/vassal/current/VASSAL.sh" >> .profile

Upgrade

tar xvjf Downloads/VASSAL-X.Y.Z+1.tar.bz2 -C /opt/vassal
(cd /opt/vassal && rm -f current && ln -s VASSAL-X.Y.Z+1 current)

@slimy

It does not require root access. It should always work. It supports multiple versions. It does not prevent aliasing or desktop integration

The only difference between installing in $HOME and /opt is literally the initial setup of permissions on /opt/vassal.

Perhaps it would be a good idea to have both options described in the documentation. Note that the script linked to previously works in both cases.

Yours,
Christian

[uckelman]

@jrwatts

On my (Kubuntu 22.04) system, /opt is only writeable by root, so I would need to use sudo to install VASSAL there; I just keep it in my home directory, instead (it’s a single-user system anyway, no need for it to be accessible to other users).

This is also what I would recommend. Users who want to install outside of their home directory will likely not need any guidance, so suggesting that everyone install to /opt is inviting a lot of needless questions.

[slimy]

Christian,

@cholmcc

@slimy

The advice is to copy in directly from the Wiki and then edit. Don’t try and edit the Wiki and copy that.

Oh, I know how to do it. I’ll use pandoc to make an offline conversion and then adapt.

I would strongly recommend you experiment with a sample before you put in any large amount of effort.

[cholmcc]

Hi Slimy

@slimy

I would strongly recommend you experiment with a sample before you put in any large amount of effort.

Thank you for the advice, though none is needed. As I said, I know how to do this. With some 25+ years of coding and open source experience, this kinda thing is trivial.

Yours,
Christian

[slimy]

I have realized that the source I am working off is massively out of date. And if I update it, I am just duplicating the user guide. So really this was just an experiment and I will delete it eventually.