About the versioning system
-
Requisites
For the automatic approach you need the Ozonex editor:
For the manual approach you need a text editor of any kind:
- Notepad
or - Visual Studio Code
The versioning system
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 presentThe 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.
Automatic approach
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:
- Increment the map_version variable inside the scenario file.
- Create a new folder with the proper extension corresponding to the incremented version.
- All textures inside the map folder are copied to the newly created folder.
- All strata texture paths to the map folder are updated to match the new location.
You can choose a version (and map name) of your liking via File -> Save as. This will:
- When you choose an extension yourself (such as .v0042) then the _map_version_variable inside the scenario file will be set to that version
- When you didn't choose an extension then the extension will be set to .v0001 and the _map_version_variable inside the scenario file will be set to 1.
- Create a new folder with the correct name and extension.
- All textures inside the map folder are copied to the newly created folder.
- All strata texture paths to the map folder are updated to match the new location.
A map may or may not start with the versioning system intact depending on what editor you used to initialize the map.
A map started in the Ozonex editor
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.
A map started with the GPG editor
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.
A map updated with the GPG editor
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.
Assets
When generating a new version of your map with the automatic approach not all assets are updated and / or moved accordingly:
- (1) Any script file that is not in the base directly is not moved to the new location.
- (2) Any path for water and environment assets that references a texture inside your map folder are not updated 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.
Manual approach
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:
- Renaming the map folder to the same name with the proper extension
- Renaming all the references inside script files of the old folder name to the new folder name
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.
Frequently Asked Questions (FAQ)
Fix .v0001 of a map
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:
- "Save as new version" (it create duplicate with higher version).
- Clear files from folder with v0001.
- "Save as" and select that folder with v0001
- Remove folder with v0002
Source
This article is based upon:
About you
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!
- Notepad
