How to upload modules to the Game Library

cholmcc · June 23, 2025, 7:58am

How to upload modules to the Game Library Service

Below are some instructions and help on how to create a project, add packages, add releases, and upload files to the Game Library (GL).

Click to read more about the …

Structure of the new GL

The structure of the GL is centred around projects .

A project is one page that contains some implementation of a Vassal module that covers a single game.

However, many projects may implement a Vassal module of the same game. One game, many projects.

For example, Afrika Korps has four distinct projects associated with it.
Users see projects when they search for a game, though they are listed by game name, and may see a multitude of projects with the same game name.
A project is under the auspice of one or more owners. These owners may add more owners or remove current owners (including themselves) as they see fit. Owners of a project have control over that project and do not need administrators to sanction changes to the project.
A single project may contain one or more packages. A package contains some set of versioned data (files) that somehow forms a meaningful set of files. For example, a package could be simply for the Vassal module, while another package contains player-aids and the like.
Or, a package could be a specific edition of a game, while another package holds another edition of the same game. How this is structured is up to the project owners.

For example, this project of Terraforming Mars has two packages - one corresponding to version 2, the other to version 3. Or this project of Panzerarmee Afrika has 3 packages corresponding to different colour themes. Other projects will have a separate package for auxiliary data, such as manuals or player-aides.

Most projects will only have one package—say Module, that contains the module and possible saves and logs.
Packages does not directly contain data (files). Instead, they contain releases. A release is a set of the files released together as a whole. A simple release may contain the module, while other releases may contain a collection of a module, scenarios (.vsav), extensions (.vext), and so on.

Releases are versioned according to the semantic versioning
convention. See also more below on versioning.

The files in a release are typically updated together.

Changes from the old module library

Since June 2025, Vassal has gotten a new library for modules. This service is very different from the older Wiki-based library in many respects.

In the older wiki-library there was a one-to-one correspondence between a page and a game. A page contained all modules of a game - One Game, one page.
- The game page was owned by the vassalengine.org administrators, and they were the only ones that could authorise new modules to be added to a page.
- Developers that uploaded modules to a game page had no special privileges compared to other users.
The new library is structured around projects where the older library was structured around pages.
- There is a one-to-many relationship between a game and projects - One game, many projects.
- This means, that a single game may have multiple projects associated with it, typically because there are multiple implementations of the game as a Vassal module.

Semantic Versioning

In general, when things are versioned, then the version number must follow the version format of semantic versioning. I.e., version numbers have the form

     <major>.<minor>.<patch>[-<prerelease][+<build>]

where <major>, <minor>, and <patch> are non-negative whole numbers. The parts <prerelease> and <build> are optional and consists of letters, digits, dots, and dashes, and should not be used for regular, full releases. The Semantic Versioning standard additionally describes the meaning of the parts of the release number, which are useful guidelines but we do not enforce.

About ownership

Anyone can create a new project, and will automatically become the owner of that project.

However, only existing owners can add things to an existing project. If you would like to add something to an existing project, you must contact the project owners to ask them if they will add your material or possibly add you as co-owner.

If you do not see a pencil icon anywhere on a page, then you are not an owner. If you do see it, then you are an owner.

Note: The vassalengine.org administrators will not add you as owner except under very special circumstances.

Please also refer to the top page. The design goals are outlined here. Please also refer to the section below on what is not possible at moment (June 2025).

How to create a project

Go to

vassalengine.org/library/new

(as of this writing—July 2025—there is no link to this page from within the library).

There, you will be presented with an input box. Type in the name of
your project.

The name of the project must only consist of ASCII letters (a-z
and A-Z), digits (0-9), and minuses (-) and underscores (_).
The name of the project must start with an ASCII letter.
The name of the project cannot be longer than 64 characters.

Note: the project name need not have any relation to the game name, though it is highly advisable.

For example, if your game title is The Greatest Game of All and your user name is janedoe, then a good name for the project could be
the_greatest_game_of_all_janedoe

When you hit the ✓ button, then the project is created, and you will be taken to the newly generated project page.

Note: Currently, it is not possible to remove or rename a project yourself, but you must ask one of the administrators to do that for you. You should therefore be cautious when entering your project name to avoid needless interventions.

Editing the Game information

Note: Only owners can change game information

At the newly created module page, e.g.,

https://vassalengine.org/library/projects/the_greatest_game_of_all_janedoe

you will see that the game title is set to the same as the project name. To edit the game information, click the pencil icon next to the project name.

In the form that opens up, you can set

Cover - the cover image that will be shown at the top of the project page. Click the image placeholder to upload a new image. Note:
- Images should not be too big (preferably no bigger than 200px × 200px) so as not to take up too much space on the page.
- Images can be of the formats PNG, GIF, JPEG, SVG, AVIF, or WEBP.
  The cover image can be removed by pressing the × in the top-left corner of the image.
Title - the title of the game - e.g., The Greatest Game of All.
Title sort key - the title of the game, with English articles moved to the end. E.g., The Greatest Game of All should have Greatest Game of All, The as its title sort key. The title sort key is used for alphabetizing projects in the catalog and in search results.

Note: The title sort key is now automatically generated from the game title, and cannot be manually edited. If the generated sort key is inappropriate, please contact an admin to have it fixed.
Publisher - the publisher of the edition of the game your module is for.
Year - the year the game was published.
Minimum and Maximum Players - put in the least and greatest number of players of the game. Leaving one or the other empty is allowed.
Minimum and Maximum Length - put estimates of the least and most amount of time—in minutes—that it will take to play the game.

Rather than ‘length’, this should probably be ‘duration’ or similar.
Description - give a short description of the game and the module implementation of the game. This text will be shown as a lead under the game title and project name when users search for games.

You may wish to consult BoardGameGeek for details which are not stated with the game it self, for example the playing-time, and so on.

When you are happy with your edits, press ✓ to save your changes.

Note: At the time of writing it is not possible to add tags - e.g., era, theatre, scale - or other meta-information to the game header.

Adding or removing owners

Note: Only owners can change ownership.

On the project page, e.g.,

https://vassalengine.org/library/projects/the_greatest_game_of_all_janedoe

press the pencil icon next to the heading Project.

You will be shown an input box where you can add other users as co-owners of the project. The box has limited auto-completion on user names.

When you are happy with your edits, press ✓ to save your changes.

Note: You can remove yourself as one of the owners. If you do that you will not be able to make further edits to the project. If you did so by mistake, you will need to contact one of the other owners, or if that is not possible, the site administrators for them to add you back as owner.

Create a package

Note: Only owners can create packages.

Before creating packages in your project, consider how you want to structure the project page.

Considerations on packages

Most of the time, projects will only have one package—say Module—and different releases of the module will be uploaded to that package.

Other projects will have more packages. For example if one is implementing multiple editions of the same game, then it could have packages 1st Edition, 2nd Edition, and so on. Or if one has specific tournament version of the module, then one could have packages Module and Tournament Module.

Another common structure is to have a package for the module - say Module, and then a package for auxiliary or player-aid information—say, Player Aides.

Finally, if a module has many extensions, saves, or logs, then it may make sense to have one or more packages for these.

On the project page, e.g.,

https://vassalengine.org/library/projects/the_greatest_game_of_all_janedoe

press the + next to and Packages to add a package.

You will be presented with an input field to enter your package name in. The name of the package can be any text you like, but should be descriptive of the intended content of the package. For most projects you will only need a single package called something like Module.

Note that packages are not meant to capture different revisions of the module. That is what releases are for. That is, do not make a package called 1.2.3 and another called 1.2.4 to upload version 1.2.3 and 1.2.4, respectively, of the module. Instead, you make a single package—say Module—and in that package you add releases 1.2.3 and 1.2.4.

When you are happy with your edits, press ✓ to save your changes.

Removing an empty package

If a package is empty—i.e., contains no releases—then an owner is able to remove the package by clicking the trash icon next to the package name.

Packages that are not empty cannot be removed until all releases are removed from the package. See also below

Note: No confirmation is required when deleting an empty package.

Editing a package

An owner of a project may change the name of packages and the sorting order of the packages.

Press the pencil icon next to package name, and enter a new package name. If you want to sort the packages of your project differently, you can specify a numeric sort key. Lower numbers sorts before higher numbers.

Press ✓ to save your changes.

Adding a Release to package

Note: Only owners can create releases.

On the project page, e.g.,

https://vassalengine.org/library/projects/the_greatest_game_of_all_janedoe

click the + next to and your package name to create a release.

Note: A release can also be thought of as new version of a package.

You will get a prompt where you can enter a release number.

Release numbers must follow the semantic versioning conventions, as outlined above - i.e., must consist of three numbers separated by a dot .: <major>.<minor>.<patch>, possibly followed by pre-release or build tags.
Do not prefix your release number by any string such as release, version, v, or the like.
Modules uploaded to a release must have a version number matching that of the release.
The input box will try to check the release number as you type.

When you are happy with your edits, press ✓ to save your changes.

Removing an empty release

If a release is empty—i.e., contains no modules or other files—then an owner is able to remove the release by clicking the trash icon next to the release number.

Releases that are not empty cannot be removed until all modules and files are removed from the package.

Note: No confirmation is required when deleting an empty package.
Note: Currently, you cannot remove modules and other files from a release yourself. You must contact the administrators and ask for help to do so.

Adding a Module to a release

Note: Only owners can add module to a release,

On the project page, e.g.,

https://vassalengine.org/library/projects/the_greatest_game_of_all_janedoe

you will have a green rectangle with rounded corners that contain the (latest) release you have added to a package. Press the + next to that to add a module to the release.

You will get an input box where you can select a module file (.vmod) from your local machine to upload.

The name of the file can be anything, but note that
- Spaces will be replaced by underscores.
- It is recommended that the release number is the last part of the file name before the .vmod ending.
  
  For example, suppose you’ve made release 1.2.3 of The Greatest Game of All in the package Module. Then a good file name will be something like TheGreatestGameOfAll-1.2.3.vmod

The internal version set in the module must match the release number under which the module file is uploaded. The internal version of the module can be set through the regular Vassal editor in the Module Properties.

When you are happy with your edits, press ✓ to save your changes.

Note: At the time of writing, you cannot remove uploaded files yourself, and you must contact an administrator to ask them to remove files. You should therefore be cautious when uploading files to your package to avoid needless interventions.

Note: The minimum required version of Vassal is deduced from modules on upload. If the required version listed is incorrect, please contact an admin to correct it.

Adding other information to a release

Note: Only owners can add data to a release.

On the project page, e.g.,

https://vassalengine.org/library/projects/the_greatest_game_of_all_janedoe

you will have a green rectangle with rounded corners that contain the (latest) release you have added to a package. Press the + next to that to add other files to the release.

You will get an input box where you can select a file from your local machine to upload.

The name of the file can be anything, but note that
- Spaces will be replaced by underscores.
- It is recommended that the release number is the last part of the file name before the “extension” or final part of the file name.
  
  For example, suppose you’ve made release 1.2.3 of The Greatest Game of All in the package Module. Then a good file name of a zip archive containing player aids will be something like TheGreatestGameOfAll-PlayerAids-1.2.3.zip

When you are happy with your edits, press ✓ to save your changes.

Note: At the time of writing, you cannot remove uploaded files your self, and you must contact an administrator to ask them to remove files. You should therefore be cautious when uploading files to your package to avoid needless interventions.

Adding a longer text to your project

Note: Only owners can edit the longer text.

At the newly created module page, e.g.,

https://vassalengine.org/library/projects/the_greatest_game_of_all_janedoe

click the pencil icon next to and the heading Readme.

You will be presented with a text editor in which you can enter a longer text describing your project. The text should be formatted as MarkDown.

Markdown flavour

The Game Library uses markdown-it to render the MarkDown text into HTML and display it to the user. markdown-it adheres to the CommonMark variant of MarkDown. See here for a quick overview of formatting marks. Also, see here for the full specification. GitHub MarkDown Flavour tables are also supported.

Note: Images must be uploaded to the GL backend for them to be rendered. External images will not be rendered.
Note: HTML tags are not supported, though HTML entities generally are.

In particular, your text can be structured with headings by prefixing the heading title by one or more # marks. A typical structure of a project description will be

## Overview 

Description of what this module is---which game, edition, etc. plus
features of the module, e.g., 

- Battle markers 
- Turn track

### Changelog 

A list of short text that highlights the most important changes in a
module, e.g., 

- 1.2.4
  - Fixes the German counters 
  - Fixes slight mis-alignment of the card grid 
- 1.2.3 
  - Fix some messages 
- 1.2.0 
  - New features
  - Note, saves and logs generated with pre 1.2.0 may _not_ be
    compatible with this release 
    
### Other projects of _The Greatest Game of All_ 

### Copyright and License

This module is © of Christian Holm Christensen and is licensed under the [Creative Commons Attribution-ShareAlike 4.0 International](https://creativecommons.org/licenses/by-sa/4.0/) license.


A list of links to other projects (implementations) of this game, so
that users can more easily choose what they prefer.

When you are happy with your edits, press ✓ to save your changes.

Note: At the time of writing, it is not possible to link to external images or attach images to the text.

Adding a Gallery to the project

This is currently not possible. Contact the administrators for help on this.

Copyright and License of module and other materials

Copyright and licensing are sensitive topics, and somewhat difficult to deal with. However, as a module developer, maintainer, or uploader, you will be liable for your actions in these respect. You should therefore pay some attention to these topics, even if you think they are annoying. If in doubt, seek legal advice.
These comments do not constitute legal advice.

The default assumption of the Vassal module library is that modules and other uploaded materials are licensed under the Creative Commons Attribution-ShareAlike 4.0 international (CC-BY-SA) license .

The CC-BY-SA license allows you to

Share — copy and redistribute the material in any medium or format for any purpose, even commercially.
Adapt — remix, transform, and build upon the material for any purpose, even commercially.

under the conditions

Attribution — You must give appropriate credit , provide a link to the license, and indicate if changes were made . You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
ShareAlike — If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.

If these terms are not acceptable to you, or any other relevant copyright holder, you must explicitly declare under which conditions (license) you make the module or any materials available. This can be done in the README section of the project page.

For example, your module may contain original graphics and text not made by you, the module developer, maintainer, or uploader. In that case, you do not have copyright over those parts of the module, and you must make sure you have the appropriate permissions to use those elements in your module. This can be in the form of a license granted by the copyright holders, or via an email or the like that gives you permission to use the copyrighted materials.

If you are licensed or otherwise have permission to use some copyrighted materials, it does not necessarily extend to third party (users or other developers). You should make any such conditions explicit in your project page. This includes under which conditions users may use the module or materials.

Say you have developed the module The Greatest Game of All (the Game), originally published by The Biggest Publisher of All (the Publisher), and you have obtained permission from the the publisher to use the copyrighted graphics and text. You should then also make sure that the Publisher allows you to distribute your module, including their copyrighted materials, through the Vassal library, possibly with the prevision that user are required to have a physical copy of the game.
The license granted to you does not extend to another developer that wants make a derived module - say The Greatest Game of All - Tournament Edition. You should check with the Publisher if the license can be extended to third-party (users and developers).

Note that only original and artistic expressions can be copyrighted - game mechanics and similar cannot. This thread over on BoardGameGeek is worth a read. That means, if you do not include any copyrighted (by other party) materials in your module - graphics or original text, you are most likely free to license your module in any way you see fit.

It is worth noting that trademarks must be respected. For example, if you want to make a module that is Star Wars themed, you can most likely not use trademarks such as Jedi, Ewok, Leia, Han Solo, and so on, without the explicit consent from the trademark holders, nor will you be able to say that the game is Star Wars-like as you will be using a trademark to promote (whether for monetary gains or not) your un-licensed product.

What is not possible at the moment

You cannot remove a project. If you need to remove a project, you must contact the administrators.
You cannot edit the project name.
You cannot add yourself as owner of a project. You should contact the current project owners, for example via forum private message, and ask kindly to be added as a users. Owners are not required in any way to add new owners.
You cannot add tags—e.g., era, theatre, scale—to the game information.
You cannot add images to the project page, except as additional information, and they will not be rendered on the page.
You cannot remove a non-empty release. To remove a non-empty release you must first contact the administrators to remove all modules and other files from the release before you can remove the release.
You cannot remove, replace, or rename a file (module or otherwise) from release. If you need to remove a file, you must contact the administrators.
You cannot assign a least-required Vassal version number to a file (module or otherwise).
You cannot add images to the Readme section.
You cannot add other users as players of a module. Only users themselves can add themselves to the player list.

When these things become possible, this page will be updated to reflect such changes.

jrwatts · June 23, 2025, 9:25am

Are you certain about the internal version number of extensions having to match the release number? That goes against my current naming conventions and working habits; if I fix a minor bug in the module that didn’t affect the extension, there’s no point in making a new extension release, and vice-versa.

(FYI, I made some minor edits to the initial post, cleaning up some typos and adding some slight clarification–e.g., you can’t rename projects & packages, in addition to not being able to delete them).

uckelman · June 23, 2025, 10:00am

That’s not correct. I’ve removed it.

cholmcc · June 23, 2025, 11:02am

First Joel and Jonathan, thank you for the edits - always good to get a few more eyes on things

Just so we’re clear, I believe when you upload a file ending in .vmod, the internal version number is checked against the release to which it is uploaded - see line 328 of prod_core.rs, so I believe the main text above is correct (module version is checked).

What is not clear to me, is if the full version - including <prerelease> and <build> is compared, or only the <major>.<minor>.<patch> parts are compared.

It is true, as you can see from the above cited code, that only .vmod files are checked, but I sincerely hope that in the not too distant future that other Vassal files will also be checked.

BTW, I still think you should amend the code so that you check the file content to see if it is a Vassal file, and if so, compare the versions - see this post.

Also

which I agree with, but I think it is important to give a comprehensive overview. But as I suggested, I think editing the .svelte files on the front-end to give users the information there and then can help a lot

Oh, and in line 371 of GameSection perhaps add the paragraph

<p>
  Game box images can be  PNG, GIF, JPEG, SVG, AVIF, or WEBP.
  Images shold be no bigger than 200px &times; 200px, to not take up too
  much space on the page. 
</p>

For example, in line 147 of PackageSection, you could add

<p>Release numbers <i>must</i> follow the conventions of 
  <a href="https://semver.org">Semantic Versioning</a> - i.e., be of the form 
  <i>Major</i>.<i>Minor</i>.<i>Patch</i> (and optional pre-release or build 
  information attached), where <i>Major</i>. <i>Minor</i>, and <i>Patch</i> 
  are whole, non-negative, numbers.
</p>
<p>
Examples of valid release versions are 
</p>
<pre>
1.2.3
10.20.30-alpha
6.4.0-rc1
5.3.8+french
</pre>

And in line 91 of PackagesSection, you add

<p>Package names are free-form strings, and structures the project into sub-parts.  
  A typical package name would be <code>Module</code></p>

And in line 123 of NewProjectPage something a la

<p>Project names consist solely of the letters <code>a,b,...,z</code>, 
  <code>A,B,...,Z</code>, digits <code>0,1,...,9</code>, dashes and underscores
  <code>-_</code>, and can be no longer than 64 characters.  Note that the project 
  name <i>must</i> start with a letter and <i>cannot</i> contain spaces, punctuation, 
  or other special characters.  
<p>Examples of good project names are 
<pre>
...
</pre>

And, of course, in line 177 of ReleaseSection

{#if !uploading}
<p>
  Remember that the version number of the module set <i>inside</i> the   
  module <i>must</i> be a valid <a href="https://semver.org">Semantic Version</a>,
  e.g., <code>1.2.3</code>.  The file name <i>should</i> contain the version number 
  too, but is not required to.  Also file name of should preferably not contain 
  spaces, punctuation, or special characters other than those in the version number,
  and as allowed by <a href="https://semver.org">Semantic Version</a> format.
</p>
<p>
  To set the version number in the module, open the module in the editor and 
  double click the top-level element.
</p>
{/if}

I think such hints right in the interface can really help people a lot, and it is an easy fix that can quickly be added to the front-end code.

Oh, and

I cannot see from your edits where there were any mistakes or errors - rather your edits was change of formulations of spelling errors.

Also, why did you remove the stuff about when to change version numbers? I am fairly certain that people are confused about that, and I think it would be quite helpful - in particular because you enforce semver so heavily, to give people some idea of how to handle that. Saying you “leave it up to the module developers” is a cop-out, because then you should not enforce any versioning what so ever. There are clearly expectations that you would like to see followed, and I think they should be spelled out. If you do not, you will eventually create more work for yourself.

Yours,
Christian

uckelman · June 23, 2025, 11:30am

We aren’t enforcing semver. We’re enforcing that version numbers follow the semver version number specification. The description of the meaning of versions in semver isn’t relevant and will only confuse people.

The only expectation I have here is that version numbers follow the semver pattern. That’s already required and explained.

uckelman · June 23, 2025, 11:32am

Indeed. I can do only one thing at a time, and I’m focusing for now on reducing the size of the problem backlog.

cholmcc · June 23, 2025, 12:31pm

In the interest of not bothering you too much - given your backlog - perhaps you could answer all the questions I posed:

You do still check the version number in .vmod files against the release it is uploaded against, correct?
Will you, at some point in the future, also check the version number set in saves, logs, and extensions, against the release number it is uploaded against?
Will you, again when time permits, add the suggested guidance text to the .svelte pages?

But you are enforcing semver - quite explicitly. That raises the question among uploaders how am I expected to treat those, given that the enforcement is strong.

That’s exactly why I put it in the context of Vassal modules. The idea was really to help people understand the expectation specifically in that context and not in general. Remember, while it may be obvious to you and I how to use semver, it is certainly not for all.

Yours,
Christian

uckelman · June 23, 2025, 12:42pm

This is exactly why I have not answered all of your questions—answering questions is part of the backlog.

Yes.

No, because it can’t be done reliably. Module version numbers in saves, logs, and extensions represent the module version they were saved with. That need not be the same as the release they’re part of, as saves, logs, and extensions may be compatible with multiple module versions.

I don’t know at present.

uckelman · June 23, 2025, 12:43pm

I don’t understand why you’re saying we’re enforcing semver. Please explain your reason for thinking this.

cholmcc · June 23, 2025, 12:59pm

I take it you will also answer the other questions? Thanks.

Well, you enforce that uploaders must give a specific format for version numbers. That, in and off it self, indicates that the parts of the release numbers has specific semantic (it’s in the name for … sake) - i.e., that major, minor, and patch (not to mention prerelease or build) are to be understood in a specific fashion.

It is not that you check the code to see if it follows the guidelines of semver - which isn’t terribly easy to do without a relatively large test-suite or some sort of machine-learning - it is the meaning that is imbued on major, minor, and patch. If you do not tell people how to deal with those, then they become meaningless and you might as well have no requirements on version numbers.

Don’t get me wrong - I think the idea of signaling compatibility through a release number is a really good idea. But for it to be useful, you have to get people to actually use it, which means you should tell them how to use it. Just witness the confusion around packages and releases - without an explanation, people started to use packages as if they are releases, and vice versa. Or people understand projects like the old wiki pages - i.e., not specific to particular owners by in principle open to all. if you tell them what the intentions are, then they are much more likely to follow them. This I know from more than 20 years of experience, working with very pig-headed and stubborn “developers”.

Yours,
Christian

cholmcc · June 23, 2025, 1:07pm

A save, log, or extensions made with version X.Y.Z is typically not compatible with X-1.0.0 or earlier (assuming people actually use semver). And a save, log, or extension made with X.Y.Z may work with X.Y+1.0 (again, assuming use of semver) but there’s likely to be things that are missing or working sub-optimally. Hence, I think it will make sense to also verify save, log, and extensions against release numbers - maybe not the full release number, but at least against major and minor.

Otherwise, what is really the point of the version numbers and enforcement of releases in the game library? Tying modules, saves, logs, and extensions together via the release numbers make sense to tell users: These are expected to work together. If there’s no check, then users have no guaranty of anything.

It sort of goes back to telling people how to use semver so that problems can be prevented - to everyone’s benefit.

Yours,
Christian

uckelman · June 23, 2025, 1:32pm

This is the point where we are not agreeing. I make no claim that the parts of the format have meaning for modules beyond how they contribute to sort order.

cholmcc · June 23, 2025, 1:41pm

Then why not just a serial number or a date? Clearly you chose something else. If all you care about is sorting why insist on a elaborate versioning scheme such as semver? That really doesn’t make sense at all - it’s a lot of work for no gain.

I think you are imbuing the release numbers with more meaning than simply sorting - and I would agree with that - but then that meaning should be apparent to all.

Yours,
Christian

uckelman · June 23, 2025, 1:46pm

You are seeing something here I do not. I do not consider the semver format elaborate, nor am I suggesting anyone must use the components as the semver standard advises.

It’s the versioning scheme that pretty much everything has settled on. At this point, not using it would be weird.

cholmcc · June 23, 2025, 3:53pm

I think we can agree on that semver is a complication relative to a simple serial number.

I think there’s no reason to introduce complexity unless there’s a specific need for it. And I do not think “because that’s what every one does” is a valid argument for introducing unneeded complexity.

In fact, prior to GLS most modules used a versioning schema of major.minor, and it seemed that this was what most Vassal developers were comfortable with. In that sense, it was the most complexity that was needed and there was no reason to add extra complexity.

Given the database schema you have with files sub servant to releases, and the sorting goes by releases, then it seems even less obvious that the modules should contain the same release number, unless that release number actually carries some meaning. In fact, the Vassal code explicitly assigns a semver-like meaning to that version number when it opens a save, log, or extensions together with a module.

Again, I’m not arguing to drop semver - on the contrary - I’m arguing that it should be used properly to make life easier for everyone involved.

Given that semver is now a reality for the Vassal GLS, why not take advantage of it? Let’s try to build a practise where developers tell their users which module is needed for what extension, and so on. VASL does that to a large extent already. Given enough clear and concise information, I’m fairly certain we can get people onboard with using semver as it is intended.

Yours,
Christian

uckelman · June 23, 2025, 10:55pm

No, really, this is not a correct generalization. The variety of versioning systems in use in the old module library was astonishing. I had to provide version information for over 900 files because they were so screwy that they couldn’t be parsed sensibly.

I reject that assertion. It does not. You might get a warning about a file having been written by an earlier version of Vassal. That’s not the same thing as the module version number, which has always been treated by Vassal as an arbitrary string.

I have zero desire to spend time explaining the semantic part of semver to people who can’t agree on whether 1.0a sorts before or after 1.0. I thought the association of our versioning scheme with semver would be helpful, but at this point I regret ever mentioning it as being related. People should think of the major, minor, and patch version numbers as meaning “large”, “medium” and “small”.

cholmcc · June 24, 2025, 1:12pm

I just ran a test, for the heck of it, and I found that the majority of existing version numbers in .vmods could be classified easily as major.minor:

  198 ( 1.8%): major
 8414 (75.7%): major-minor
  670 ( 6.0%): major-minor-more
 1333 (12.0%): major-minor-patch
  183 ( 1.6%): major-minor-patch-more
  115 ( 1.0%): major-more
  204 ( 1.8%): other
11117          Total

In fact, little less than 2% had a version number that wasn’t easily (with simple regular expressions) classified as a numeric version number, and the vast majority (75%) could very easily be recognised as major.minor, so I think the “generalisation” was very much justified.

First off, you don’t really have to explain that - you’ve chosen a convention, and that’s that.

However, if you don’t people a little background, then you will more than likely get questions as to why 1.2.3-alpha sorts before 1.2.3. Hence my elaboration on what semver should mean for Vassal modules.

Not sure I know what association between what and what you are referring to.

All the more reason to spell out in a bit more detail what this means. Saying “what ever you want it to be” just creates more confusion and more questions for you. Really, the point is to give enough information that people can apply the principles themselves and not seek answers again and again, thus bothering you and others.

So please, allow me to put in some words in the above on how one can think of the semver versioning scheme in the context of Vassal modules.

Yours,
Christian

uckelman · June 24, 2025, 1:23pm

How did you do that?

cholmcc · June 24, 2025, 1:47pm

Remember when you were working on porting the old wiki pages to the new GL? And remember that I did some developments to try to help out with that? (there were other posts by me on this, but I couldn’t find them quickly). Well, I essentially downloaded all modules - automatised of course - and extracted the meta-data from the files using my pywargame Python module.

I still have the resulting database on file, so it was a simple question of querying the database and then check the version numbers to see if they could easily be deduced from that data.

I used regular expression for this. For example, a match on

^ *(v|ver|version|) *\.?[0-9]+\.[0-9]+\.[0-9]+$

maps to the classification major-minor-patch, and similar, and then I just apply that mapping to all version numbers, and count up the number of occurrences of each classification. Pretty simple I think.

Oh, and BTW, I’ve made a set of JSON and markdown files for the 37 projects that still need splitting. The idea is then that one can define the splitting in the JSON files, and then use the data there to make the new projects. If you want them, I can send them to you.

Yours,
Christian

uckelman · July 10, 2025, 9:56pm

It’s possible to rename packages now. The docs should be updated to reflect that.

Flags are being processed now, so it’s also worth pointing out flagging as a way of reporting problems.