map.yml - file

LaFayette

Picking up from this thread (#2527), I'm opening this thread for exclusive discussion of the 'map.yml' file.

Overview of map.yml file

The map.yml file will serve as an index file starting from 2.6 and all maps will be required to have one. The game engine will use the 'map.yml' file to know which game-XML-files are in a map folder. Any game-XML-file not listed in a map.yml fill not appear as available for selection and the engine will not be able to find it.

Migration from 2.5

To help migrate from 2.5 and avoid all players from re-downloading every map, the engine will one-time generate a map.yml for installed maps that are missing the file.

Documentation

There is further documentation here: https://github.com/triplea-game/triplea/blob/master/docs/map-making/reference/map-yml-file.md

Future Planned Additions

Still on the radar, and I think the only thing left so far is a planned addition for a game-notes file path.

Game notes file path

Below is a full example of what this would look like, this allows for the engine to find game notes without looking for them within the XML file (notice the lines with the arrows next to them):

map_name: Name of My Map
version: 1
games:
  - name: Game Name (1)
    xml_path: games/XmlGameFile.xml
    game_notes: games/XmlGameFile-notes.html   # <<
  - name: Game Name (2)
    xml_path: games/XmlGameFile2.xml   
    game_notes: games/XmlGameFile2-notes.html     # <<

Open questions

There are still open questions and the map.yml file may yet evolve.

(A) File Pathing or Game-File-Name

For example, currently the map.yml file specifies a path, eg:

xml_path: games/XmlGameFile.xml

On windows though, this will be generated as:

xml_path: games\XmlGameFile.xml

The latter will not work on non-windows OS and also does not cleanly translate to a URI. I think the former would work on windows because of how path the is translated. If it does, then perhaps we can have the auto-generation simply flip the direction of the slashes. Alternatively we could have the engine search for file by name and skip the pathing problem altogether, eg:

file_name: XmlGameFile.xml

(B) Player Count

The map.yml is intended so that an XML file won't need to be read at all when populating the 'select' games screen. One data item that is still needed is the 'player count' and that comes from XML by counting the number of factions. Having player count when it was 'easy' to include was a nice addition, though I don't know if it is critical.

The options are for player count:

remove the field from the 'select games, game description'
add to map.yml
continue parsing XML files for it

LaFayette

This was just updated to make specifying game files easier, instead of specifying the path to a game file you only need to know specify the name of the file.

Documentation was updated to reflect this:
https://github.com/triplea-game/triplea/blob/master/docs/map-making/reference/map-yml-file.md

Here is an example of the latest:
https://github.com/triplea-game/triplea/blob/master/docs/map-making/reference/map-yml-file.md#mapyml-contents

Any thoughts feedback are really welcome. If anyone would like to demothe map.yml files they can do so with the latest pre-release. Installing and launching it will unzip all downloaded maps and generate a map.yml file. I think the file has hit something of a stable variant. In the future adding more information like 'era' could very well happen. For now, baby-steps, first goal is to kill off the triplea_maps.yaml file.

TheDog

(B) PLAYER COUNT
On some maps the player count is not derived correctly eg.
Warcraft War Heroes is 35 - Actually there are 8 playable (4v4) and the rest are AI controlled.

My two maps Settlers: Age of Tribes & Settlers: Fallen Empire has one hidden "player" that just holds territories so they cannot be picked by the random start delegate. The number of actual players is 9 not 10 as displayed.

Options are;
a) Remove it
b) Calculate the true player count
c) Let the map owner have a player variable that is read and displayed

LaFayette

@thedog Interesting. Removing it I think is a reasonable option. I have not noticed that it is gone from the game-select UI.

LaFayette

I'm no longer convinced that the "download" version value is appropriate to have in the map.yml file. Perhaps if it were automatically tracked it would be better. The engine could do this and then any update to the map would be notified to users. Any feedback/thoughts on this?

beelee

@lafayette Don't see a down side. Only reason i don't update the yaml everytime I do a map update is so I don't spam out the Git PRs. I started putting a notification at game start stating game version and the date it was updated and telling players to make sure they all have the same version. Not perfect but hopefully helpful.

Idk, the bots not auto updating would still be a problem, but it would be anyway.

RogerCooper

@lafayette I agree, an automated system would be better.