New map.yml system?

Frostion

I have been away for a few months. It seems that @LaFayette / DanVanAtta, @RogerCooper and probably others have been very busy lately , so I just wanted to be updated in regards to any new standards or new ways for mapmakers to handle map files.

Question A
This description directory just contains the same picture as the “preview.png” (but with an old custom name). The picture was formerly linked to in the master yaml file as a screenshot to the map. Can/should mapmakers delete these “description” directories if there is nothing else inside them?

Question B
Is the "map" dir + description.html + preview.png the new basic files and file structure that the map makers must create before we try to get the map published? Or is some files generated automatically?

Question C
Some map files structures have a README.md file besides description.html + preview.png. Is this file actually used for something else than to be deisplayed at github? or is it OK to delete the readme file?

Question D
I can see that our local map directories (aka “downloadedMaps” dir) now have a yml file. With content that looks something like this:

map_name: age_of_tribes
games:
- {xml_path: map\games\Age_of_Tribes_Classical.xml, name: 'Age of Tribes: Classical'}
- {xml_path: map\games\Age_of_Tribes_Cold_War.xml, name: 'Age of Tribes: Cold War'}
- {xml_path: map\games\Age_of_Tribes_Modern.xml, name: 'Age of Tribes: Modern'}
- {xml_path: map\games\Age_of_Tribes_Primeval.xml, name: 'Age of Tribes: Primeval'}
- {xml_path: map\games\Age_of_Tribes_Renaissance.xml, name: 'Age of Tribes: Renaissance'}
version: 0

Is this file generated automatically? Can this file have settings and info in it? Other than stating/listing the map XMLs? Any future plans for having map settings in this file? Must the mapmaker edit the "version"?

LaFayette

Here is the reference documentation covering the new map.yml file, it should answer most questions (if not, please consider editting it to add more information or ask here if anything is unclear):

https://github.com/triplea-game/triplea/blob/master/docs/map-making/reference/map-yml-file.md

These three forum threads are the discussion threads behind the map.yml file development:

One question I have, how can we avoid having a 5th thread about the map.yml file? Where should the authoritative discussion thread live and how can we ensure that location becomes well known? Is this a matter of merging the 'map-development' category into this category perhaps??

To respond directly to the questions:

A) The image file referenced by
triplea_maps.yaml is the important one. Any previous preview images that had a custom name in the description folder are unlikely unused. Maps were bulk updated to have their existing preview image placed into a standard location (top-level) with standard name (preview.png) as the 2.6 engine will rely on this. Some maps were re-using the image used in game-notes, it was therefore not safe to delete the previous preview image that was used, so it is very likely that the contents of the description directory are now unused.

B) In short, yes.

'description.html' is the description content that would have previously been added to triplea_maps.yaml. Instead of adding the description there, in 2.6 that information will be read from a description.html file location in the map repository. Map makers in 2.6 will no longer need to update triplea_maps.yaml to update their map description, they should instead modify the description.html file. Likewise, when publishing a map, to have a description visible on the map-download screen, a file named description.html in the map repository will be needed. Similar comments for the preview.png file.

Or is some files generated automatically?

description.html and preview.png are not generated automatically. For existing maps, I wrote a script to splice the triplea_maps.yaml file and dump the description contents into each repository into a description.html file and did a bulk download of every preview image and saved it into each map repository as preview.png. Those were one-time migration efforts, new maps will need to create those files. While 2.5 is being supported, there will be duplicative effort to maintain a description in triplea_maps.yaml that matches the description.html file.

C) The README.md files are IIRC legacy from when we first created map repositories. The readme file is arguably a good thing to have to describe how the map is put together and mention any other documentation for the map-maker and others. It is otherwise unused and not necessary.

D)

is this (map.yml) file generated automatically?

The 2.6 engine generates map.yml files automatically for already downloaded maps that do not have it. In the future it is expected that any map will already have this file. Therefore after an initial auto-generated, there should no longer need to be auto-generations as either all maps will come with a map.yml file or it will already have been auto-generated. The auto-generated serves two purposes: 1) it'll be used to backfill and populate all map repositories with a map.yml, 2) it avoids players from having to re-download all maps in order to get a map copy that already contains a map.yml file.

Can this file have settings and info in it?

Current future expectation is the games nodes will be updated to have an optional a game-notes file reference. That would be used as a primary location to find game-notes with the game-xml being a fallback location. There are a number of intents for the map.yml file:

allow for game notes to be specified outside of a game-XML file
avoid the need to specify the game name within XML
avoid the need to specify map name within XML
remove all map folder naming constraints, with 'map.yml' files, the engine will no longer look at map folder names and match that name against the content of a XML file, instead it will read the map name directly from the map.yml file.
make the location of XML-files deterministic to find, rather than the engine assuming any XML file is a game-XML file, the locations to the game XMLs is instead explicitly specified
remove the need for a triplea_maps.yaml file entirely, in 2.6 it is expected that file will no longer be read by the game engine and would be 100% legacy.

One caveat, 2.6 is still under development and the contents of a map.yml could still change. I strongly urge further feedback on this sooner while it can still be easily modified. I am strongly tempted to remove the xml_path to instead be file_name and have the engine simply search for a file with the given name rather than it be a file path. I think that will maybe make it simpler.

Any future plans for having map settings in this file?

The map.properties file could be merged into it, though I think the purpose is starting to get a bit mixed. The 'map.yml' file is essentially an index file, it tells the engine which game files are available within a maps folder and provides meta information used in download about a map.

Must the mapmaker edit the "version"?

This is the version that value that exists today in triplea_maps.yaml. It is not used for anything other than to notify users when they have an older version of a map and should update it. Incrementing this version will trigger a pop-up for anyone with a map installed that they have an out-of-date version.

RogerCooper

Does the order of the lines in the map.yml file matter? I have been converting files I have on my computer to the new format (once done I want to add to the repository), and I have been having odd problems where some scenarios will not appear on the selection screen while other scenarios in the same folder do appear.

For example in this map.yml

map_name: AA50-BuildCaps
games:
- {xml_path: AA50-BuildCaps\games\AA50-41-Maintenance.xml, name: AA50-41-Maintenance}
- {xml_path: AA50-BuildCaps\games\WW2v3-1941-BuildCaps.xml, name: AA50-41-Build Caps}
- {xml_path: AA50-BuildCaps\games\WW2v3-1942-BuildCaps.xml, name: AA50-42-Build Caps}
version: 0

The first xml file does not appear on the scenario lists, but other 2 do? I have been working DanVanAtta on this with a GitHub issue, but we have not been able to resolve the problem.

LaFayette

@RogerCooper - No, ordering does not matter