RFC - In-Game Map Uploads

[TheDog]

Round II

Here I am guessing how it could work, as I have never used Git for new maps;

I upload to Git my current game map Settlers: Age of Tribes it has 750 files, can I do this one upload?

I tell Git my map is based on a map called Age of Tribes, Git looks up the map and gets pointers to 216+216=432 files, the rest of the files are new, as most of the unit/flag png have been retouched by me although they look like alkexr pngs.

Scenario 1
Weeks later I have a change or too, but because Im human I don’t know what I have change, I upload all 750 files, I tell Git its based on Settlers: Age of Tribes, Git works out I have changed 3 files and stores them, the rest it already has.

Scenario 2
I upload a new game map I am working on Settlers: Fallen Empire, it has 1200 files.
To aid Git, I tell Git it is based on;
Settlers: Age of Tribes (for the unit Icons and Flags) and
alkxer’s game map Fallen Empire (for the map tiles)
Git stores 5 files as they are unique to this game map.

So could this work?
If so is it viable?
.

[LaFayette]

@Schulz, how maps are uploaded and stored is independent of their ranking and categorization. Unless a map violates the map requirements, I don't think we should be telling anyone no.

I think your points speak to additional features to build on top that allow for both better manaul and automated ranking and categorization of maps.

It also appears that it's been unclear that we have been in need of more map administrators for a very long time and there is an open invitation to join. The map admins would help the upload process and fix & categorize the existing maps. The maps are like a garden, we've a lot of weeds growing.

[LaFayette]

@TheDog

If you use a GUI tool like "Git for Windows", or "SourceTree", you can upload all 750 in one go. If you are using the web UI that git provides, then you'd need to do 100 at a time. Considering it's a one time cost, I suspect that will take you about 10 minutes and then however long it takes to physically do the upload (so probably an hour total). For what is mostly a one-time cost, that does not seem unreasonable.

BTW - 750 files! That's a mega-map!

I don't understand how you mean by telling Git the map is based on Age of Tribes. If you are in a different repository, all the files are independent of any other map. It's the engine that has a concept of 'mods', but those need to live in the same map repository.

Re: Scenario 1

If you're using 'Git for Windows' or what not, it will tell you what you've saved on the file system. When editting XML, you can create checkpoints where you can go back and restore in case something gets messed up. This is actually a much better way to develop maps than saving a backup of XML every few changes (because you don't have to do so much manual saving, and git will tell you what has changed between checkpoints and allow you to restore to any checkpoint).

But fundamentally, if you re-upload everything, the files that are the same should just show no difference. I'll be a bit surprised if you don't know exactly what changed. You also should be able to upload any changes after you made them. If you're working on images for example, you can retouch a few, upload those, and then rinse-wash and repeat. Nothing says you have to do it in a big-bang.

Settlers: Fallen Empire, it has 1200 files.

Again, one time cost to upload it all into a new repository. Though, that is a lot of map files, where is that coming from? The engine does have limits, it is possible to that could have really poor performance or not be playable. Warcraft hero's taxes the engine and is barely playable. A map that is even larger might not have hope.

[LaFayette]

I think we need to refocus this conversation, but good input so far and please continue and consider this topic deeply. I do want to be sure we build the right thing. If we don't, then various problems we want solved will simply remain.

Main Questions so Far

• Is Github repository upload actually that complicated, or is it that there is a small learning curve that is hard to approach?

• Github repository allows anyone to change a single file or many - is this something we value? In other words, is a targeted single file upload valuable, or are we okay with any change requiring that the whole map be downloaded, extracted, changed, re-zipped, and then re-uploaded.

• How valuable is multiple person collaboration? If everything is done by one person who is the original map author, and we are okay passing zip files around via google drive, it's okay. Likely permissions to update a map will be restricted to map-admins and the original uploader. It seems like not being able to 'pass-a-map' forward would be a problem and adds a lot of scope to what would have to be built for map uploads. At some point we are building something so similar to a github repository that one wonders if we would be better to just focus on making the upload process easier to follow.

[TheDog]

Github repository is probably not the tool for the job, it might have a small learning curve, but I am still not persuaded to use it, it requires another tool to upload a game, a quick search of the games I have and the smallest is 450 files.
Github is just an obstacle that I dont want to over come as it offers nothing that I want to use, however the restore points for an xml might of tempted me, but no, I will stick with my many backups and comments in my xml files.
.

As mentioned I would like to just upload 3 files, as 400+ files takes too long.
But the process is
zip, upload
change, zip, upload
But, there is is no download, extract as only one person will be doing the changes.
.

As for collaboration I would ask outside of Github for help, email back and forth, share on Google Drive , so no need for Github. Game maps tend to be by one person, that's another reason why Github does not suit one person as its really designed for collaboration.
.
.
ps. the Fallen Empire has 416 base and 416 relief tiles, yes its a big map, it was design by alkexr, but never finished, the rest of the files I need to tidy up, but it runs well as a single player.

[LaFayette]

Github repository is probably not the tool for the job, it might have a small learning curve, but I am still not persuaded to use it

I'm not trying to pursuade you to use it. If you want your maps uploaded, it's what you have had to do. Maps have always been stored in source control (previously sourceforge). The biggest difference is the work is now self-service (relatively easy) and development does not manage it so closely. This frees everyone up.

• If the 100 file limit is a bottleneck then you can use a desktop GUI that makes it easy to do the needed git commands locally and then push all files at once.

• Github enables collaboration, but I use it personally for solo projects as well and am aware of many other examples. The email'ing, sharing via google drive, it all could be removed by commiting to the repository instead.

• I think the solo led collaboration is common but it's not always the case. The really popular maps have many people working on them, particularly over the years (think long term). For example we've had maps where the unit images were upgraded.

• There are more benefits to having github repositories, for example all XML is available at a web link, makes it really easy to see how other maps were built and examine them without downloading and exracting. It also makes it easier for admins to go in and correct issues, and if used would allow map makers to link to their XML and have others look at it easily.

[LaFayette]

I'm starting to lean towards the thought that storing map zips in database only would be a mistake. The repositories provide a lot of value from different perspectives:

• all files available at a web link.
• an automatic history of changes available at web links, this is critical for an editorial review of maps to verify what has changed
• automatic packaging of files
• capability to do bulk updates.
• capability to do bulk searches. Having all maps checked out locally, it's some easy commands to search all XMLs in existence.
• capability to do bulk file adds.

Diving into some of those details, we have built an in-code test that downloads nearly every XML that exists and verifies that the map parser is able to read them without any errors. If we mess up the map parser somehow in an obscure way we've a good chance of finding that. Every time we change code, we run this test automatically as a requirement for that change to be accepted.

The file history is automatic and really critical for editorial review. If we were to have zip files only, then the already nearly non-existent map-admin team would then be slammed with having to open every new zip file uploaded and fully verify the entire map rather than having a web link tell them exactly what changed.

With all maps checked out, it's possible and has been done to bulk change every XML that we have to apply corrections. Similarly being able to search all files has let us find features which are not used, or find features that are heavily used or lightly used, get statistics on which images are duplicated the most and least, and generally it's provided useful insights that would not be possible if we had to download from scatch every zip and extract.

File adds is where repository does shine. Consider adding a standard config file to every map. That is a very likely scenario coming up as we break up and distribute the index 'triplea_maps.yaml' file to each map (which then avoids needing to have the single centralized index file). So for example, we add this config file to every map: If every map is in database and uploaded as a zip, we need to coordinate with every single map maker such that they add the file or download the latest zip and merge. If we fail and a map maker uploads a zip without the config file then they'll inadvertently remove it. Checking every map consistently keeps the config file will become non-trivial and painful and a source for troubleshooting and error. Overall, a messy scenario that incurs more work than we are doing today.

Getting to the point, github repositories provides: file storage, version tracking, access control, web hosting & automatic packaging. That's quite a lot to be getting for free and would be an enormous amount to build ourselves from scratch. Perhaps making bulk uploads easier with good step-by-step instructions is a lot of what we are missing.

[RogerCooper]

@LaFayette You need to verify for missing images. My experience is that is the number one problem with maps, including 2 in the current repository.

[Schulz]

I had easier time learning to create a map from scratch than understanding Github sufficienly in spite of Frostion's guidance. After that it is easy to manage and of course very valuable if map user can achieve to do it.

Would Bitbucket be better alternative?

I think nobody should be able to in charge of any project other than the original creator besides fixing bugs.

[RogerCooper]

@RogerCooper I found another non-working map in repository, "Caravan Plain".

[LaFayette]

@RogerCooper A map validator is a highly requested feature. I've also been thinking it might make sense to automatically do hue shifting from existing images to fill in missing images rather than the hue shift be controlled by configuration (just make it automatic).

[LaFayette]

@Schulz What exactly did you find difficult in Github? To me the web UI is as easy as it could almost be. It is almost literally click a button, drag and drop files, then click another button to submit the changes. Hence, I'm very interested to know where the complexities are.

No, BitBucket would not be a better alternative and it has none of the web UI features, you would have to 100% use a Git client that you install on your computer and then BB has other issues. We are not migrating hosting system.

[ff03k64]

@RogerCooper Do you have a link? Maps are what I am using to try to learn TripleA some more.

[LaFayette]

I think this thread is really getting off-focus. The question is if we want to invest 3 months of TripleA development time to replace how uploads are done and bring it in-game. I think intrinsically it is a good feature to have in-game, but the cost is significant and particularly for something where there is a very decent UI someone else has built that we can use free of the maintenance overhead that would come from a custom creation.

Preventing broken maps from staying in non-experimental categories is a problem no matter where those maps are hosted or how they are uploaded. Ensuring maps are followed-up on, that map makers don't half-complete maps is another similar problem that is neither made worse nor solved based on how maps are uploaded (though, if we did get more uploads, it would put pressure on that problem, but the solutions to that are independent of how we do map uploads).

Re-iterating - Main Questions so Far

• Is Github repository upload actually that complicated, or is it that there is a small learning curve that is hard to approach?

• What is difficult about repository upload exactly? Where do we need to streamline instructions if we were to keep using it, or alternatively if we were to build custom software, what is difficult about upload that we would need to solve in a custom way to make easy?

[ff03k64]

Going back to your original post, anything that makes it easier is obviously better, but you do have to weigh that against the amount of work it takes to do it. I would rather that energy be spent on improving the AI for instance.

@LaFayette said in RFC - In-Game Map Uploads:

Question (1) - Do we want in-game map uploads?

What all would be involved in in-game uploads? Would that use the map maker? would it basically just be copying an already existing map, making your changes (like in edit mode) and then reupping it?
I could see that as possible being a relatively simple thing that just makes a new XML with different various things such as intial unit placements. Hopefully not too involved, but also not allowing for really impressive new maps like Frostion has been making.

@LaFayette said in RFC - In-Game Map Uploads:

Question (3) - how should access control work?

You definitely need to have access for map admins for the official repository. There are too many maps that need periodic tweaks to leave it to people that might be gone a month after uploading their map.

@LaFayette said in RFC - In-Game Map Uploads:

Question (4) - should we keep github repositories and automate the map.yaml file?

What exactly does this file do in the engine? I presume it tells the local engine which maps are available and also which maps have new versions since you downloaded them originally.
If that is what it is, it seems to me (admittedly not a huge programmer) that it shouldn't be particularly difficult to do, but also doesn't seem like it does a huge amount. So lower effort, but lower reward.

Personally, I think Github repos work pretty good. I can see ways that in game could be better, like for someone that just wants to change the XML (alliances, initial placements, initial territory owners, etc.), I think using edit mode to be able to make said XML could be very useful. If you want to go beyond that to use the engine as a GitHub front end, you are bloating the engine for functionality that can be found in other programs.

[TheDog]

For the cost of 3 months to streamline uploading, I would like the time to be spent improving the AI, if it was I would;

• Learn how to upload my maps.

• Upload other peoples maps for a year and try and encourage others to up load their own using the current method.

LaFayette you listed the benefits below, this is what convinced me we should keep the map uploads in Github, basically as is.
all files available at a web link.
an automatic history of changes available at web links, this is critical for an editorial review of maps to verify what has changed
automatic packaging of files
capability to do bulk updates.
capability to do bulk searches. Having all maps checked out locally, it's some easy commands to search all XMLs in existence.
capability to do bulk file adds.
.

[beelee]

@TheDog said in RFC - In-Game Map Uploads:

... * Upload other peoples maps for a year and try and encourage others to up load their own using the current method.
...

I struggled hard with git. I still do, but I did figure out how to add a map with the help of others.

sourceforge you had to have someone upload your map. You have to have someone to do the yaml PR now as well, although my guess is that is less work than the sourceforge way, and it just notifies people that the map has been updated or added. Well, I don't think it notifies one when a new map is added but ...

At any rate, once your map has been uploaded, you can update it by yourself. It just won't tell users there is an update.

Have a thread for people who can't update/need help with their maps and those that know how, if they feel like it, can help teach how or just do it.

I thought triplea was trying to "decouple" a lot of maps, so until that gets sorted ... i guess someone still needs to decide what can and can't be.

[alkexr]

@LaFayette said in RFC - In-Game Map Uploads:

What is difficult about repository upload exactly?

I can share my first experience I had with GitHub a couple of years ago. I tried desperately to find a GitHub turorial, googling "GitHub tutorial for dummies", but turns out I was more of a dummy than anyone dared guess. Some questions I couldn't find an answer to were:

• What is even a "repository"?
• What is this "commit" thing? Why can't I just change the files and call it a day?
• What is "pull" and "push"? What is the difference?
• If I have already committed changes, why is there still a need to push? Or pull?
• Etc.

See, the problem was that I had a mental model about repositories and stuff, but it was the wrong model. I tried to think of a repository as something like a folder. Multiple branches - multiple folders! Add a file to a folder - why isn't that file in the "same" folder online? If I merge a branch - how does it know which folder to keep and which to discard?

[RogerCooper]

@LaFayette said in RFC - In-Game Map Uploads:

@RogerCooper A map validator is a highly requested feature. I've also been thinking it might make sense to automatically do hue shifting from existing images to fill in missing images rather than the hue shift be controlled by configuration (just make it automatic).

Some mods such as "The Grand War" use flags rather than hue shifts anyhow.

[LaFayette]

@ff03k64 thanks for the feedback, responding to the questions you asked:

What all would be involved in in-game uploads?

• The map uplaod process would be brougth in game, I think the map maker would gain a new button "upload maps"
• After clicking 'upload maps', you would be prompted to log in to the lobby (this then assigns your name so the backend knows who you are)
• You would select the map folder or zip to be uploaded
• Triplea would confirm the upload details and then you click okay and it would upload it.
• New map uploads would go into a moderation queue of some sort and have to be approved to be available for general download. This moderation would only be a content check and would not be checking that the map is playable or otherwise
• The map becomes available for download, probably from a default 'Experimental' category and we later deal with category promotion in some other way.

What exactly does this file [map.yaml] do in the engine? I presume it tells the local engine which maps are available and also which maps have new versions since you downloaded them originally.

Pretty much. When you click 'download maps', the game engine downloads this file and the data from this file is used to generate the map download selection. The engine uses the data from this file to know which version you are downloading and can later detect if there are new versions available or if you have the latest version or one that is missing altogether. The preview image and the map description you see in the download maps window comes from the 'map.yaml' file.

Hence, until the 'map.yaml' file is updated (actually called 'triplea_maps.yaml', but that is a detail), until that file is updated, game engines do not see the map as yet available for download.

I think using edit mode to be able to make said XML could be very useful.

The dream I think is for the front-end to be all encompassing for map making. I would like to even bring in the map making tools to be part of starting a game, so instead of an 'edit' mode there would be a 'map making' mode.

Though, using edit mode to change a map, be able to re-export that back to disk and then upload it is certainly the idea. The latter step, to upload, is arguably the most questionable because we don't necessarily have to build it (uploading is a generic problem, there are alternatives compared to us building a custom solution).