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 game page was owned by the
-
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
(as of this writing - June 2025 - there is no link to this page).
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
andA-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
, orWEBP
.
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 haveGreatest 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. -
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.
Note: At the time of writing it is not possible to rename packages from your project, and you must ask an administrator to do that for you. You should therefore be cautious when entering your package name to avoid needless interventions.
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.
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 ✓ so 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 ✓ so 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: Currently, the game library back- or foreend does not accommodate setting or deducing the minimum required Vassal to use for a module. It is therefore recommended to put that information in Readme section of the project page.
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_
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.
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 rename a package. If you need to rename a package, you must contact the administrators.
- You cannot rename (re-version) a release. If you need to rename a release, you must contact the administrators
- 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.