VASL - How to update old VASL files to the current version

Status
Not open for further replies.

von Marwitz

Forum Guru
Joined
Nov 25, 2010
Messages
14,355
Reaction score
10,204
Location
Kraut Corner
Country
llUkraine
NOTE:

With the release of VASL v6.6.7 in November 2023, an auto-update fuction has been implemented into VASL, which will handle most of the things to update a VASL file from an older version automatically, which needed manual attention before v6.6.7.

Cheers go out for Doug Rimmer taking up the idea of programming this.

A new thread on updating VASL files from older versions can be found here:

Click this Link.


von Marwitz


VASL - How to update old VASL files to the current version

(A word ahead: This thread describes the process in painstaking detail and is intended to serve as a knowledge base. In practice, the time required to update the scenario described in the example should cost you merely something in between 5 to 10 minutes depending on the detail into which you go.)

The below instructions refer to the combination of VASSAL v3.4.12 and VASL v6.6.1 as of 10. January 2021.

However, the method described should work in general with other versions, too. At least since roughly VASSAL v3.4.10 an issue seems to have been resolved that formerly made the updating process more difficult.

The method described works with VASL files as old as v5.9.2 (at least this is the oldes VASL file I have tested it with, dating back to 2010).
In the following, I will provide a documented walk-through by example of a pre v6.2 VASL file.

Please note, that by this method you can quite quickly update an old VASL file - or your old archives. If you do so and send your updated files to the contact email provided at vasl.info, you might become part of a larger effort to create a collection of up to date pre-made setup files which will save many players a lot of time to create these themselves.

Disclaimer:
For copyright reasons, I strongly propose never to make publicly available or upload pre-made VASL files anywhere that would make the ownership of the scenario card unneccessary to play the given scenario. You should leave out VC, SSR, and pictures, for example. This is not legal advice nor would I be qualified to provide such. Whatever you do, you act under your own responsibility and - of course - should act responsible.



Walk-Through Instruction Example


For the walk-through example, I will use a the Scenario T2 'The Puma Prowls', the scenario card (not the VASL file) is available for free download from the MMP website here.

The original VASL file I will use for the Walk-Through has originally been created in November 2014 using VASL v6.1.

Step 1:

Find your scenario and load it into VASL.

16017

Your current VASL will most likely notify you of a 'Save Game Mismatch'. Press 'Yes' to open the file. Note that after the updating process, you will not be able to open the updated files with many old versions of VASL any more. If you want to retain your old original VASL file, you should save your new file under another file name.

16018

The old VASL file should now open. Sometimes it seems to take a considerable while, which seems to be the case especially if you had included links to external picture sources as part of HTML code in Draggable overlays. Formerly, pictures sometimes were a big issue as older versions of VASSAL crashed which made your old VASL files practically inaccessible.

The VASL controls window informs you of the (old) board versions you had used in creating the original VASL file and tells you which board versions (likely newer) you are currently using. It also informs you about Extensions that were installed when the original VASL file had been created. Normally, this should not be an issue. But if you had used an Extension for some special counters for example which you have not installed any more, then - of course - these counters will not show. Also note, that the 'Refresh Counters' updating process will - as far as I know - only work for counters inherent to the current version of VASL.

16019

Here is what the old VASL v6.1 file looks like:

Disclaimer:
As T2 'The Puma Prowls' is available for free download on the MMP website, in this particular case only I do show the VC, SSR, and picture. Normally, I strongly advise not to make such information available in publicly accessible VASL files for copyright reasons. See my Disclaimer above.


16020

Where older VASSAL versions might have crashed opening this v6.1 file due to the picture included, the current VASSAL version v3.4.12 can handle it. So far, so good.

You will note two things (red numbers 1 & 2 in the screenshot):
  1. In case you had opened this file with the old VASL v6.1, the offboard margin would have been half as wide and the boards would show closer to the Draggable overlay with the VC & SSR. Formerly, the margin used to be half as wide, since VASL v6.2.2. this has been doubled to allow more room for counter placement offboard.
  2. Any counters and Draggable Overlays are not moved, though, so they will be in scewed position in relation to the boards.
This phenomenon you will only observe when opening VASL files older than v6.2.


To be continued in subsequent post...

von Marwitz
 
Last edited:

von Marwitz

Forum Guru
Joined
Nov 25, 2010
Messages
14,355
Reaction score
10,204
Location
Kraut Corner
Country
llUkraine
Step 1.1 (for pre v6.2 VASL files only):

Now you need to get rid of the offset positions of counters and Draggable overlays.
This can be done easily and quickly.

Click the 'Orange Soldier' Button in the VASL 'Main Map' window and select 'Convert pre-6.2 game'.

16021

The result looks like this:

16022
Counters and Draggable Overlays are now in correct positions relative to the boards again.

At this point, save the VASL file under a new name. I advise always using the VASL version as part of the file name as this makes things much easier for future reference, so I'll name this one as follows

T2 The Puma Prowls v661.vsav


Step 2 - Updating the counters to the current VASL version:

The good news:
You do not need to pull new counters manually but there is an automated fuction for this, too.

Even better: As opposed to previous times, extra information you assigned to the counters such as Leader names, Gun ID letters, does not get lost in the process any more.

Not yet perfect:
At least some of the information you might have put into Draggable Overlays still gets lost. You will see this in screeshots later.

In the 'VASL controls' window you will find the 'Tools' menu with a single function in it: 'Refresh counters'.

16023

If you have installed any Extensions for VASL, which is highly likely, this function does not work yet.
It only works if you have no Extensions installed, i.e. your Extensions folder is empty.

Rather than deleting the Extensions in your Extensions folder or copying them around, I advise to create a second, empty Extensions folder with a slightly different name solely for purposes of updating older VASL files. I'll provide my structure as an example - of course the naming of your folders might vary:

16024

You see the VASL v6.6.x directory which holds all stuff necessary for running the current VASL version:

The boards in 'Boards v6.6.x', while current VASL versions will download any missing boards in the newest version from vasl.info automatically if available there in case it does not find them in this folder.

The extensions in 'Extensions v6.6.x' contain my 'active' installed Extensions that will load when starting VASL.

The'-Extensions v6.6.x' folder - note the 'minus' - is empty and does not contain anything.

The 'Saved Games v6.6.x' holds my VASL files, which doesn't interest us here.


Now back to the 'Refresh counters'...
Before I can use that function, I do the follwing:
  1. Shut down VASL.
  2. Rename 'Extensions v6.6.x' to '+Extensions v6.6.x' - note the 'plus' added so that VASL temporarily does not find this folder any more.
  3. Rename '-Extensions v6.6.x' to 'Extensions v6.6.x' - with the effect that VASL will now find my empty Extensions folder.
  4. Restart VASL.
You will now observe, that VASL lists no Extensions loaded:

16026

Now you can reload the VASL-file which you are updating.


To be continued in subsequent post...

von Marwitz
 
Last edited:

von Marwitz

Forum Guru
Joined
Nov 25, 2010
Messages
14,355
Reaction score
10,204
Location
Kraut Corner
Country
llUkraine
Step 2 - continued:

Now, in the 'VASL controls' Window, select from the 'Tools' menu the 'Refresh counters' function:

16027

I always check the box 'Use couner names to identify unknown counters?' and then select the 'Test' option.

The Test will display the number of counters the function can and cannot update. Activating the checkbox before sometimes leads to more counters being able to be refreshed, i.e. updated.

In the example, all 54 counters can be refreshed to VASL v6.6.1 - great!
Now hit the 'Run' option. The result will show in the 'VASL controls' window:

16028

Now, save your VASL file again.

What if the Test indicates that not all counters can be refreshed?

This can have several reasons:
  1. The function can only refresh unconcealed counters and Draggable Overlays that are a) unconcealed b) HIP / concealed but owned by you. That means if you wanted to update an old defensive setup sent to you by an opponent where some of his counters are concealed/HIP, these counters owned by him cannot be refreshed by you. However, if you have updated everything you can and then send the file to your opponent, then he can refresh the concealed/HIP overlays/counters owned by him.
  2. The function cannot refresh counters that might have been part of Extensions. Let's say, you have an 'Omaha' Extension installed in your original file and placed a Battleship counter which is part of that Extension in your original file, the current VASL v6.6.1 will display that Battleship counter if you have that Extension loaded and if that Extension still works with the current VASL version. Of course, the functionality of the Battleship counter is limited to what is bestowed on it by the Extension. During the time when you have loaded the file without the Extension, the Battleship counter might not be shown or shown incorrectly. It will be shown again, when you have reactivated the Extension.
As a bottom line, while it is possible to address the first case as described, the function will never work for the second case as far as 'refreshing' is concerned. As long as the Extension is compatible with the current VASL version, though, the former can of course be used within its limitations.


Step 3 - Review the results of the 'Refresh' and manually amend the imperfections:

16032

Now let's have a look at the result (detail only).
We note the following imperfections to the automatic process:
  1. Draggable Overlays: When updating from VASL versions v5.9.3 upwards, the content of a Draggable Overlay is 'remembered'. However, if you previously cleared '1st Line' and/or '2nd Line' of the Draggable Overlay to be empty, it is automatically filled with the default content of 'Label' for the 1st Line and 'Line 2' for the 2nd Line. In many cases, you will have cleared the 2nd Line, so this issues is likely to arise. This is a minor nuisance, at it does require you to mark all Draggable Overlays and manually delete the automatically 'refilled' default content to previously cleared Draggable Overlay lines. Luckily, this won't take you more than a minute to do in a normal tournament sized scenario. I think that for VASL files of versions v5.9.2 downwards, the content of both lines of Draggable Overlays is lost, but am not completely sure.
  2. The weather counters, i.e. Wind, EC, Gusts, Compass, etc. originally were unlabelled. They do have a default-label since VASL v6.6 I believe and can me manually removed again since VASL v6.6.1. Unfortunately, the Refresh function adds the (now) default labels to those counters that you need to get rid of manually if so desired.
  3. In the Turn Track, the 'End' counter and the red 'Half Turn' marker need to be manually repositioned. For some reason, they appear in the wrong 'layer' with after the 'Refresh' process the 'End' counter showing below the Turn Number, while the red triangle 'Half Turn' marker showing above it. It should be the other way around, but it ain't.
Luckily, these are the only issues I have found so far, so the manual corrections can usually be done very quickly.

Further manual adaptations in special cases might be necessary for pre VASL v6.2 files:

You see in the example two Draggable Overlays. One containing HTML code with an embedded link to an external picture source causing the Puma to be displayed. The second one containing HTML code with the VC and SSR. Both information in my example rest in the '1st Line' of the Draggable Overlays. They are still optimized for the pre-v6.2 margin and not for the v6.2 upwards double margin. This is not an issue of the 'Refresh' function but rather of the embedded HTML code in those draggable overlays. By example of the Puma Draggable Overlay, I will show how to fix this.

This is the content of the Draggable Overlay which is copied/pasted into it from a textfile for reasons of easier editing:

16034

Marked in red, you will note the values for WIDTH and HEIGHT being '200' matching the old pre-v6.2 VASL offboard margin. You need to manually change these values for WIDTH and HEIGHT to '400' to match the current v6.2 & later versions VASL margin.

For the VC & SSR Text it is very similar:

16036

Here you need to double the value for the width from 150px (maked red) to 300px in the Draggable Overaly.

This is the result (detail) after manually fixing the issues described above:

16037


Now, save the VASL file again.
Close VASL.
Reset the names of your Extension folders as they had been originally.
Reopen VASL
Reload the VASL file.

To be continued in subsquent post...

von Marwitz
 
Last edited:

von Marwitz

Forum Guru
Joined
Nov 25, 2010
Messages
14,355
Reaction score
10,204
Location
Kraut Corner
Country
llUkraine
Step 4 - Finishing Touches:

Although you are more or less done after Step 3, being German and not able to help myself, I will add a Step 4 for the Finishing Touches.

16038

  1. This first point I would advise anyone to add to their VASL setup files as it will help you and others later: Provide the VASSAL and VASL versions with which you have created the VASL file along with the date of creation. When opening the file, anyone will be able to see with which versions it will work and what might need to be updated in the future.
  2. While I am at it, I update to the current ROAR rating.
  3. While back in the days I used a Draggable Overlay to keep track of Victory Points, there now is an Extension that makes this a bit easier as it provides counters that adjust the score by pressing the plus or minus on them.
  4. I have moved the Turn Track, scenario title, weather information a bit upwards to take advantage of the wider offboard margin available since VASL v6.2.
  5. Step 4 often allows for the Orders of Battle being both placed above the playing area, which looks nicer. So I did this here.
Well, this is it.

Note, that my description goes into extreme detail. In practice, most the VASL files will be v6.2 and later, making some steps unneccessary. Furthermore, you might not be as fanatic as I am about VASL setups, so you might omit some of the points detailed in Step 4.

In practice, for this scenario, the entire update process including the updating of ROAR data etc. would have taken me something around 10 minutes.


The Vision:

Wouldn't it be cool if there were a place where you can just download all pre-made VASL files for just any scenario in versions running with current VASSAL/VASL?

Hell yes, because it would save you time setting this stuff up yourself and provide you more time to actually play!

Some people argue that they do not want pre-made setups as to make them familiar with the scenario and to avoid mistakes that a pre-made setup might contain. I would counter-argue that it costs you less time to check a pre-made VASL setup for any mistakes than to create one yourself - with the chance of making mistakes yourself in doing so. All this does not prevent making yourself familiar with the scenario. And often people who create pre-made VASL files put more effort into it to produce a higher quality than you might have cared to do.

Sceptics continue to argue that pre-made VASL files might be out-dated and you don't know with which version of VASSAL/VASL they were created and which issues they might hold. I would answer that good pre-made setups should contain version information and creation date. Furthermore, the update process which I undertook to describe in painstaking detail, will in practice most often be quicker than to create a new VASL file from scrap. So you can draw from work and time put by previous people into it, update their older file and still be quicker than if you did everything yourself.

Each to his own, of course, but just sayin'...


How to make it happen?

Well, the Updating process has been described in detail above.

But how and where to make your efforts available to the community?

Disclaimer:
Respect copy-right! Do not make publicly available VASL files that render the original scenario cards unneccessary.
If you don't respect copy-right, websites that host those files might get into trouble if copy-right holders address them. As a consequence they would probably remove all pre-made VASL files to be on the safe side even if most of them do not infringe copy-right. This would be contrary to the original intention of being a service to the ASL community and indirectly as well to the copy-right holders/original publishers of the scenarios.
Once more, I recommend to leave out Victory Condiditons, Special Scenario Rules, and pictures in pre-made VASL files which you intend to make publicly available. This is not official legal advice, which I am not qualified to provide.



VASL.info website


One known repository for pre-made VASL files is the vasl.info website. A list of existing pre-made setups can be found under this link. I understand the way to get your pre-made VASL file onto that list is to delete VC, SSR & pictures before sending it via email to Sam Tyson.

16039

Unfortunately, the listed pre-made VASL files do not allow to see with which versions of VASSAL/VASL they have been created, but I believe (as of January 2021) that most of them will work with current VASSAL/VASL versions even if not updated. These files could also be taken as a basis to update them to current VASSAL/VASL versions.


ASL Scenario Archive website

The second repository for publicly available pre-made VASL files (and also log-files) is the ASL Scenaro Archive website.
This website has IMHO grown into the most useful ASL resource after GameSquad forum and it is getting better being fed with more and more information by the day.

Opposed to vasl.info, the ASL Scenario Archive allows you to directly upload VASL files and VASL logfiles (as well as other file types). This means that you are even more directly responsible for what you upload with regard to potential copy-right infringements.

Dave Ramsey, who owns the ASL Scenario Archive website has not actively promoted the possibility to upload VASL files because I believe he has some concerns that it might get flooded with low quality stuff.

So, if you upload there, upload quality stuff only and avoid shoddy things.
To be useful, I'd recommend you include the VASL version with which a VASL file has been created in the uploaded filename (e.g. T2 The Puma Prowls v661.vsav)


To be able to upload files to the ASL Scenario Archive, you need to register and create a user-account.
That done, you can use the 'Search' or 'Advanced Search' function of the website to find the scenario for which you wish to upload a pre-made VASL file.

For our example, find the page for T2 The Puma Prowls (works if you are logged into the site with your account).

To check if VASL setup files (or others) exist for this scenario, scroll down on the page and check the 'User Files' tab.

16041

The filename you select should include the VASL version with which you have created your pre-made VASL file (here v6.6.1). The description tells you, dependend on the 'Type' of uploaded file you have selected when uploading, what to expect.



16040

It is possible for you to deleted user files which were uploaded by you (by clicking on the red x behind your file(s))

As far as I know, so far there are hardly any pre-made VASL files to be found in the ASL Scenario Archive at this time.


Final Remarks:

Well, I hope I have done something to document how to update existing pre-made VASL files and pointed out that is can be quickly done in practice.

I have hopefully made people aware to respect copy-right.

And I have given tips how and where you can make pre-made VASL setups available to the ASL community.

Maybe I have enticed one or the other to update their 'collection' of VASL files and to make it available to the community so that possibly at some time a whole lot of these will be accessible for interested players.


von Marwitz
 
Last edited:

DougRim

Forum Guru
Joined
Apr 23, 2012
Messages
1,957
Reaction score
2,234
Location
Ottawa
Country
llCanada
Because I am sometimes not very bright, I have entirely missed this thread since it was first posted in January. <Smack up the side of the head>.

In the last view days, I have stumbled across much of the same information as von Marwitz has presented here. In my somewhat irregular testing, going back to games created in 2011, I have not found a game that cannot be converted by the methods von Marwitz describes (except games which rely on unit counters from extensions).

The key of course is that when opening a game and updating the counters using Refresh Counters, you absolutely cannot have any extensions loaded. Once the Refresh is done, re-opening the game with the extensions loaded will restore missing overlays etc. If while opening a game without your usual extensions you get a "Bad Data in module" or "Missing Data in module" message, you can ignore it. Once you reload the extensions the message should not appear.

The only comment I would make about von Marwitz's processes is that I personally found it easier to remove the extensions in the following manner.

  1. Open any game or start a new game in VASSAL/VASL. Go File->Preferences->Extensions.
  2. In this window, click on the Select button a navigate to a folder that contains no extensions.
19227
Any directory will do so long as it has no extensions.

3. Click OK. Exit VASL and VASSAL.

  1. Open the game you want to update. No extensions will load. Make the changes as per von Marwitz's posts. Save game.
  2. Go File->Preferences->Extensions
  3. In this window, click on Select again and navigate to the folder with you extensions.
  4. Click OK. Exit VASL and VASSAL.
  5. Open the game you updated with your extensions restored.
It is really 6 of one, half-dozen of the other. I prefer this because it avoids renaming folders which I have a tendency to screw up.

It would be great to hear if people are able to get this to work on their games or what problems they encounter.

Doug
 

von Marwitz

Forum Guru
Joined
Nov 25, 2010
Messages
14,355
Reaction score
10,204
Location
Kraut Corner
Country
llUkraine
Because I am sometimes not very bright, I have entirely missed this thread since it was first posted in January. <Smack up the side of the head>.

In the last view days, I have stumbled across much of the same information as von Marwitz has presented here. In my somewhat irregular testing, going back to games created in 2011, I have not found a game that cannot be converted by the methods von Marwitz describes (except games which rely on unit counters from extensions).

The key of course is that when opening a game and updating the counters using Refresh Counters, you absolutely cannot have any extensions loaded. Once the Refresh is done, re-opening the game with the extensions loaded will restore missing overlays etc. If while opening a game without your usual extensions you get a "Bad Data in module" or "Missing Data in module" message, you can ignore it. Once you reload the extensions the message should not appear.

The only comment I would make about von Marwitz's processes is that I personally found it easier to remove the extensions in the following manner.

  1. Open any game or start a new game in VASSAL/VASL. Go File->Preferences->Extensions.
  2. In this window, click on the Select button a navigate to a folder that contains no extensions.
View attachment 19227
Any directory will do so long as it has no extensions.

3. Click OK. Exit VASL and VASSAL.

  1. Open the game you want to update. No extensions will load. Make the changes as per von Marwitz's posts. Save game.
  2. Go File->Preferences->Extensions
  3. In this window, click on Select again and navigate to the folder with you extensions.
  4. Click OK. Exit VASL and VASSAL.
  5. Open the game you updated with your extensions restored.
It is really 6 of one, half-dozen of the other. I prefer this because it avoids renaming folders which I have a tendency to screw up.

It would be great to hear if people are able to get this to work on their games or what problems they encounter.

Doug
Doug,

this should be the thread you were looking for when you intend to tweak an "update"-function for VASL. I linked this in the 'VASL 6.6.4 Official Release' thread.

Cheers,
von Marwitz
 

DougRim

Forum Guru
Joined
Apr 23, 2012
Messages
1,957
Reaction score
2,234
Location
Ottawa
Country
llCanada
@von Marwitz

Now that VASL 6.6.7 is released, containing the Game Updater/Converter functionality (Mark 1), might I be so bold as to suggest an update to this thread. Enough things have changed that it risks creating a bit of confusion with the new process.

Given that it is pinned to the top of the VASL Thread (and I like that it is), players looking for help are likely to come here first.

Since there is so much good information here clearly expressed, I would not suggest to simply append even more information to the end of this thread. I would suggest editing the existing posts to keep the flow and structure of the thread while referencing the new tools available.

Happy to collaborate with you on this. It is however, your thread and I leave you to proceed as you prefer/think best.
 

von Marwitz

Forum Guru
Joined
Nov 25, 2010
Messages
14,355
Reaction score
10,204
Location
Kraut Corner
Country
llUkraine
@von Marwitz

Now that VASL 6.6.7 is released, containing the Game Updater/Converter functionality (Mark 1), might I be so bold as to suggest an update to this thread. Enough things have changed that it risks creating a bit of confusion with the new process.

Given that it is pinned to the top of the VASL Thread (and I like that it is), players looking for help are likely to come here first.

Since there is so much good information here clearly expressed, I would not suggest to simply append even more information to the end of this thread. I would suggest editing the existing posts to keep the flow and structure of the thread while referencing the new tools available.

Happy to collaborate with you on this. It is however, your thread and I leave you to proceed as you prefer/think best.
This seems a very reasonable proposal.

My suggestion:
  • You open a new thread on this topic for v6.6.7.
  • Then post a link to the new thread at the end of this thread.
  • I will update the opening post with a link to the new thread (done except for the link).
  • Finally, we ask a moderator to close this thread.
von Marwitz
 

DougRim

Forum Guru
Joined
Apr 23, 2012
Messages
1,957
Reaction score
2,234
Location
Ottawa
Country
llCanada
My suggestion:
  • You open a new thread on this topic for v6.6.7.
  • Then post a link to the new thread at the end of this thread.
  • I will update the opening post with a link to the new thread (done except for the link).
  • Finally, we ask a moderator to close this thread.
von Marwitz
Will do.
 

von Marwitz

Forum Guru
Joined
Nov 25, 2010
Messages
14,355
Reaction score
10,204
Location
Kraut Corner
Country
llUkraine
Please do.

I inserted a link to your new thread into the opening post of this one.

von Marwitz
 
Status
Not open for further replies.
Top