The Ultimate "How to add city names to YnAMP mod" Guide
Get started: All you need to start hammering in city names
You need: YnAMP source code
First of all, please create an account on gitHub
. (If you just want to download the source code for now, you don't need an account) Don't worry if you have no experience in gitHub, this manual will cover all steps you need. You can take the tour when you log-in thou, if you want to.
Fork the project to your own account and download the zip file. See the picture in the spoiler:
Extract the zip file into your civ6 mods directory, which should be here: "Documents\My Games\Sid Meier's Civilization VI\Mods\"
You need: A text editor
Basically every text editor will do, but you might wanna get something that is capable of showing you XML data in a easy to read manner. I use Notepad++
, it's freeware and has some nice easy-to-use features like tabs, that come in very handy. The picture in the spoiler shows you the difference in using a plain text editor vs. Notepad++
You need: The map and the text file
Open the xml file that contains the map you want to add cities to (for example: "Maps\PlayEuropeAgain\CityMap.xml
"). Also, open the file "GamePlay\GamePlayText.xml
". The first one is where your map coordinates will go to specify a location for a city name. The later one is the file that contains the actual name itself. Don't worry, you will get the whole picture soon, just keep reading.
You need: Ingame display of map coords and reveal the whole map (if you don't use Worldbuilder)
Open the file "AppOptions.txt
", you can find it in the civ6 main directory. Edit the lines "EnableDebugMenu 1" and "EnableDebugPlotInfo 1". Save the file. See the image in the spoiler for clarification.
Start Civ6 and activate the mod
Start your civ6 game (if it was running while you were editing the AppOptions, you have to restart the game). Activate the "Yet not Another Map Pack" mod (and also I advise you to deactivate any other mods!). Start a game with the YnAMP-map you want to add cities to or alternatively use the Worldbuilder to load the map.
Reading coordinates and reveal whole map
To read the coordinates of a tile, hover over the tile and check the tooltip. In the bottom you will see the coords something like "Plot #:1234 @(25,94
), vis:1" (see spoiler pic below). The relevant part are the red digits in the brackets. These are the X and Y coords of the map. For your orientation: The grid starts in the bottom left corner with (0,0). Be aware, the X-axis is not a straigt line, the coords are moving up in a zick-zag. Check the X-coords of a few tiles above and below each other to get the idea.
To reveal the whole map, activate the debug console by pressing ` (tilde) on an english keyboard. It might be a different key on other languages. For german keyboard, press "ö". Type "reveal all" command into the console. Press enter, the map will be revealed. You can close the console if you like by pressing the console key again.
We are ready to go: Adding city names to a specific map tile
If you found a spot on the map where you say it's a good place for a specific city, write down the coords.
In the map xml file, dublicate the "Replace" line (see the spoiler pic) and change the X, Y and "CityLocaleName" values to the city that you want to add. There is no mandatory order, but you might find it handy to order it by the Y-axis.
As you can see, you don't write in the city name directly, instead you use a tag, here for example "LOC_CITY_NAME_PARIS". Please use always this naming and do not use special characters in this tag. Also do not use "-", make it a "_" instead (also for spaces!). Example: "New Dö
me" --> "LOC_CITY_NAME_NEW_
Now go to the "GamePlayText.xml
" file. Here scroll down the "<en_US>" section. You will find lots of city names here and suddenly a </LocalizedText> tag. Add your city names before this tag. Just dublicate a line above and replace the "Tag" with the tag you already wrote in the map file and the "Text" with the accurate city name ("-" and special characters are allowed in the "Text" attribute). See the spoiler pic for clarification:
If you want to check your changes, restart the game. The files won't be updated neither real-time nor if you just reload the map. Restart the game.
Give it a try
You can already go and try this stuff. However, if you want to participate further, please read the other chapters of this manual, as there are some things to be aware of that gives you a good understanding of how the naming works and how you prevent two Parises for example, or how you place your cities along rivers.
Become an expert: Mindful name placing, advanced placing techniques and troubleshooting
To make it clear from the beginning: There is no ultimate "right" way
of deciding where to place a city name and where to place a different city name in relation to the first one. But there are rule of thumbs that I would like to emphesize on. Those are open for discussion and may change at some point. In the end, it all comes down to your own judgement. For now, those rule of thumbs gave me a good approach to specifiy tiles.
A tile can spread its name to adjacent tiles
There are basically two types of naming tiles. Those, which will give the city name only when you found the city EXACTLY on this tile (called "0 range tiles"), and those, which will give the city name even if they are only adjacent to the tile (called "1 range tiles"). See the pic in the spoiler. The red tile is a "0 range tile", you will get the city name only, if you found the citiy there. The blue tile spreads its name to every tile around it. No matter where in the blue dotted area you found the city, it will get the name of the blue tile.
1 range tiles are useful for bigger cities or for areas with much space. That gives the player more possible tiles to found a specific city and gives you as modder a quicker way of "floating" an area with one name.
In the code, 0 range tiles have a Area="0" attribute at the end of their tag, while 1 range tiles have no such attribute, as it is the default value for name tiles. Check the map xmls and you will find both of these types.
0 range tiles have the highest priority. Means that when you have a 0 range tile and an overlapping 1 range tile to its right, the founding city will get the 0 range name, even though there is also a 1 range name available. This is especially handy when you have 2 overlapping 1 range tiles, or if you want to have all tiles around a 1 range to be "Big City" but then there is a river for example and you want to be sure that "Big City" is not on the other side of this river (because it isn't there in real life aswell). Check the following spoiler pic:
The 1 range tiles give you (and the player) comfort for placing big cities and the 0 range tile gives you the detailed specification you need to, to make city placements as close to the real world as possible.
Which cities should be placed on the map?
As you can imagine, one civ map tile may correspond to a huge real world area with several cities in it. So how to decide which city to go for? Quick answer: Go with your guts. Long answer: You might want to align your guts by thinking about the following (i warned you, now comes a long answer!) :
Is this city of any importance?
Lets say Dunquerke (Dünkirchen). Pretty small town at the french coast, right? But... wasn't there something about WWII... you may want to do some research or just rely on your history knowledge. And so you might wanna give this city a tile. However, giving it a 1 range tile might be overkill, because then the player will found a Dunquerke that is completly not on the coast. So a 0 range tile (Area="0") is most likely sufficient here. By the way, the "guts" stuff is pretty important here. We do not expect a history degree or a deep cultural knowledge or perfect cartography skills. If it doesn't please the community, it will let us know. So don't agonize too much over a tile
Take landscape into consideration.
This is especially true for islands and coasts. See the following spoiler pic of Sicily.
I gave Palermo two 0 range tiles so a player may found the city west or east to the river. However, I kinda don't think that Palermo should also be on the southern coast of Sicily. About the cyan tile to the left: Well, as I said, just go with your guts.
Take rivers into consideration.
Here an example of Frankfurt/Germany and the area around it. Since I am a german myself and lived in several citites along the Rhine river, I claim myself of having some understanding of this area. In the spoiler pic below you see the Rhine river/Main river convergence on the civ map, as well as a Google Map of this area (i emphesized the important stuff on it):
Converting this into name tiles, I ended up with the following spoiler pic:
As you can see, a player will have PLENTY of tiles where he can found "Frankfurt", he is not tied to one or two specific tiles, but to also adress some of the realism and local importance of cities there is no Frankfurt on the west side of the Rhine river (this is where "Mainz" is, a city that goes back to the Romans). Also, at the exact convergense of the two rivers, this is where Mainz and Wiesbaden are. Wiesbaden is a provice capital of the provice Frankfurt is part of actually
). And to the north, it would be very weird to found a city adjacent to the Rhine river that would be called "Frankfurt" because Frankfurt ist definetly not near it. Also, if you look closely at the former picture with Google Maps, you will see that there is als "Hanau" ... well, it's a really small city. Yes, I could place it, but then it would be 1 less tile for Frankfurt. And my guts tell me to give it to Frankfurt, so a player have 4 places along the Main river, where he can found Frankfurt and even a 5th one on the hills (if they really want to...)
Take Gameplay into consideration.
The detailed approach shown above might work for the "Play Europe Again" map, but on a world map, the landscape might be less detailed. And so, you might want to go for more "known" and "important" cities. On an other map, there might be no "Wiesbaden" (because it takes away a valuable "Frankfurt" tile) and no "Mainz" because Cologne and Strasbourg might be the only cities that have space.
Keeping track of your work
Mapping all the names of a country (or even a continent) can get messy very fast. You have to deal with a lot of tiles. When you only have ingame view and a mere endless amount of code rows, you might gonna lose yourself. So think about something to help you dealing with coords and namings. How you want to do this is really up to you. In the spoiler pic is an example of what I did in the first days of my work. You might not see or understand much of the pic, and I won't go into detail for it. But for me, it was sufficent to keep tracking of my progress and to check placings later ingame during tests.
That being said, depends on how this project evolve, we might gonna get special maps in this manual for people to download and point out which part of a map they want to name.
Also, announce your work, so we are not ending up having four people working on Egypt simlutaneously. See the next chapter "Be part of the party" for more details.
You might encounter some weird things when you test your code ingame. Here are some issues I ran into during test and how to deal with them.
City name ingame is "LOC_CITY_NAME_XY":
If you end up having cities being founded with names for example "LOC_CITY_NAME_PARIS" instead of just "Paris", there are two possibilies for that.
First, you might have not added the real name into the GamePlayText.xml. For every city that you declare in your map xml, there has to be a corresponding entry with the real name in the GamePlayText.xml. Check this example:
Code in your map xml:
<Replace MapName="PlayEuropeAgain" X="47" Y="24" CityLocaleName="LOC_CITY_NAME_PARIS" Area="0" />
Than this code MUST BE in your GamePlayText.xml:
<Replace Tag="LOC_CITY_NAME_PARIS" Text="Paris" Language="en_US" />
If you miss on the second part, your city will be founded as "LOC_CITY_NAME_PARIS".
An other reason for the game not resolving the name tag is that there is a typo in your GamePlayText.xml code. Now the tricky thing about it is that the typo might not be in the line with the city. See the following spoiler pic where there is a typo several lines ahead of Paris.
Searching for those typos can take a while. Just stay focused and you will find it eventually.
Founded city has a city name from the "name pool" instead of the specific name of this tile:
All cities founded on tiles that haven't being named will get their name from the civilizations name pool (the names that you get in standard games when founding citites). So you either just founded a city on a tile you didn't code at all or you might have declare the wrong coordinates for this tile. Check the X/Y-coords of the city with the ingame tooltip and then check your code if this tile was really declared correctly (also check for typos).
Now you should have a good idea of what to be aware of when you code your city names. If you have any questions or something is still unclear to you, feel free to post in this thread. I will answer you asap. Read the final chapter of this manual to know how to get your work into the mod.
Be part of the party: Announcing your task, discussing and providing your changes to the mod
Spread the work and define the scope
Be reassured that mapping all those tiles of a huge map (even if you can count out water and mountains) is still a lot and lot of work! So noone expects you to sit down and work through the whole map. Best way to cut down the effort is to work on a special part of the map. Like for example the iberian peninsula, the british isles, the Balkans etc.
Do the part you want to do.
Just make sure that it hasn't been coded already (we don't need 5 people working on France over and over again). If your part of the map has already been coded, join the conversation and discuss the changes you feel more suitable. Then you can go to code an update instead of a complete new naming set. Especially if you are from the area of the world you want to code/discuss let us know, an insight from a local is better then just looking up Google Maps and hoping for the best when placing the names
Announce your work before starting it.
Just give us a short post in the forum on what part you are working on. Check the "Project status" post (next after this) to see which parts are being worked on and which parts you can contribute to.
A small scale update is totally ok.
Again, it's not about doing the most codelines. It's more about giving an enrichment to the mod. So you are from Denmark and there are only 20 tiles where you can place city names on? No problem -- let your danish way of life inspire you and give the map the best city name allocation for denmark as possible (this is hard, you really have to think about EVERY tile). Quality is definetly over quantity!
Less Caesar, more Plato.
No one of us is without error and no one of us holds the ultimate truth (there is no such thing). Let people know why you think this and that is a more fitting approach than the current one. Take their thoughts into consideration for your work aswell. This might require some more talk in the beginning, but in the end, we will end up with a way more interesting map then when we just follow one strict dogma. Like giving total geographical correctness over gameplay issues. That might just end in people disliking our placements becase they can't found the cities they know and end up with weird names they never heard of and that wasn't their intention at all when founding the city.
Commit your changes on gitHub
Yes, it's finally there: The part where you get your changes into the mod! (In case they please Gedemon
I assume that you did a smoke test on your code? Means that you at least started one game after coding and just spammed out cities to check if you get the city names you decleared. If not, please do it first. But after that, it's time for your code to get on the journey into the mod.
Upload your code changes on gitHub:
Make sure that you open YOUR OWN repository on gitHub. Check the following spoiler pic to see when you have the correct repository open. If you need to find your repository on gitHub, go to your gitHub account. You will find a link there.
You can easily drag&drop your changed files into the repository, but beware that you put it into the right directory! See the spoiler pic, it shows you the exact location your files has to go to.
Write a comment about your changes.
Don't leave this part empty please. The more people are working on a project, the more important it is that some can see directly what this change is about. So please fill in some bulletpoints. See the spoiler pic for an example.
Create a pull request to Gedemons source code.
After uploading the files and commenting the changes, your gitHub repository will show an entry, something like "xy commited on gitHub xyz". Check the spoiler pic, its marked as the underlined passage there. When you see this, click on "New pull request" (the framed button in the same pic).
The following page should look something like the the next spoiler pic. Click on "Create pull request".
The pull request will be commented with the same text that you used earlier to comment your file changes.
You will be notified.
When your changes have been merged into the master repository, you will get a notification via mail. From this moment on, your changes are in the code available to everyone to download it from gitHub and with the next mod release, to everyone who is using the mod!
Delete YOUR repository before working further on the mod
Now, if you want to work on the mod again, like doing an other country, please wait first to get the notification about your merge. Delete YOUR repository on gitHub (see the following spoiler pic) and then start from the beginning of this tutorial again, where it tells you to fork the source code.
(yes, there are other ways dear gitHub experts, but for this manual and for this special usage, i'd like to make it easier for people not getting their code base messy, ok?
That's all folks!
If you have any further questions, suggestions, discussions etc. feel free to post your thoughts in this thread. Also check the next post about project status to get an overview on this project.
Moderator Action: Edited by Gedemon
Added link to a few useful functions to use with the Firetuner in Worldbuilder mode: