For the automatic approach you need the Ozonex editor:
For the manual approach you need a text editor of any kind:
The vault from FAF uses a versioning system to allow maps to be updated. This comes in two parts: a map version variable in the %map-name%_scenario.lua file and the entire map being in a folder with an extension that adheres to the version inside the scenario file.
An example inside Visual Studio Code where you can see that the folder of the map matches the map version described in the scenario file
An example inside the maps folder where we can see that multiple versions of a map can be present
The versioning system was introduced to allow maps to be updated without breaking backwards compatibility. A key example of this is replays: without the versioning system all replays that uses a different version of the map would breakdown. Another key example is playing a (custom) game with other people: without the versioning system it would always be unclear if maps are really the same version.
The goal of this article is to describe good practices with regard to this system for you, as a map developer.
The Ozonex editor automates the majority of the work with regard to maps.
You can update a map via File -> Save as a new version. This will:
You can choose a version (and map name) of your liking via File -> Save as. This will:
A map may or may not start with the versioning system intact depending on what editor you used to initialize the map.
When you initialize your map through the Ozonex editor then your versioning system is already up and ready. The map starts off with its map_version variable set to 1 and the folder starts off with an extension of .v0001.
When you initialize your map through the GPG editor then the work is all yours. You can quickly fix everything by opening the map in the Ozonex editor and navigate to File -> Save as new version to automatically setup the versioning correctly.
When you save a map with the GPG editor the map_version in the scenario file is lost. You can fix this again by manually adding it or by opening and saving the map with the Ozonex editor.
When generating a new version of your map with the automatic approach not all assets are updated and / or moved accordingly:
For (1) you need to manually move these files. All references to other files require a manual update too. With regard to (2) you need to open up the map in the old GPG editor and set the paths to the new folder manually.
This section will be slightly cryptic as there is little reason to use it anymore. The Ozonex editor will do all the hard work for you in the majority of the cases. For completeness I am adding this section in regardless.
All you have to do is update the map_version variable inside the scenario file. When uploading the map the renaming is done by the faf services. This includes:
Take note that the paths of, as an example, custom strata textures are not updated by the service. Therefore if your map uses custom textures that are located inside the folder then the reference will be broken. This is a key reason to not use this approach as it requires you to be more careful. Therefore the manual approach is not advised.
The only real reason to use the manual approach is for maps with tons of scripts inside them. A key example here are survival maps.
If you have map with version 1, never uploaded to vault and it's somehow broken, and you want to repair it without changing folder name, then:
This article is based upon:
If you have interesting sources, approaches, opinions or ideas that aren't listed yet but may be valuable to the article: feel free to leave a message down below or contact me on Discord. The idea is to create a bunch of resources to share our knowledge surrounding various fields of development in Supreme Commander.
If you've used this resource for one of your maps feel free to make a post below: I'd love to know about it!