GearCity Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== The City Editor ======

GearCity implements two different types of maps. Ones with dots for cities and others that are masses of land, called territories. Both map styles have city.xml files to define the data for the dotCities and Territories respectively. To edit those files, you will use the City Editor.

The City.xml files are shipped with each map, however they can be overridden using the [[ModTools:make_a_mod_Editor|mod tools]]. As such when editing a city.xml file you will either want to [[ModTools:make_a_map_Editor|create a new map]] or [[ModTools:make_a_mod_Editor|create a mod]] to override the specific map your using as base. Otherwise you will lose the changes you made when the game updates.

For DotCity maps, the City.xml file plays an important roll in placing the dot on map. If the coordinates are incorrect, the dot will be placed on the wrong part of the map. The City.xml file also stores starting populations, per capitas, flags, growth rates, and many other important ratings to the game. We'll walk you through these ratings and what they do, and explain to you how the editor works. 



===== Mod Tools =====

To access the City Editor, you must open the Mod Tools. See [[ModTools:AccessingModTools|How to Open the Mod Tools]] if you do not know how to access the Mod Tools.

The City Editor is available on the left hand column of the Mod Tool's Main Menu. Click the button labeled “City Editor.” 

\\
\\

====== The Editor ======

We'll break down each part of the editor in the following segments:

\\
\\
===== Main Tab =====
{{ :modtools:cityeditor_overview1.png?400 |}}
  - Starts a new/blank city list.
  - Saves the existing list of cities to .xml file.
  - Loads a city.xml file into the list.
  - Returns to the previous editor or the Main Menu
  - Opens the [[ModTools:make_a_map_Editor|Map Data Tool]].
  - Opens the [[ModTools:turneventsEditor|Turn Events Editor]].
  - Opens the [[modtools:aieditor|AI Editor]]
  - Selected or new City's Information Data panel. See [[modtools:cityeditor#city_variables| City Variables]] for more details.
  - Current Cities Tab. This opens the list of cities currently loaded into the Editor.
  - Current Cities List. This lists the cities currently loaded into the Editor, and includes basic information about the cities. Clicking on a city from this list will fill #8 City Information Data panel with the city's information.
  - Clears the City Information Data panel for a new city to be added to the list.
  - Clones the selected city's information for use in a new city.
  - Removes selected city from the list of cities.
  - Adds a new city to the list or edits the selected city in the list.  
  * **A)** Opens the Interpolation tab. The Interpolation system will automatically adjust growth rates of a city based on the city data from an existing City.xml file designed for a later year. 
  * **B)** Opens the Auto Adjustments tab. This tab will allow you to select existing Turn Events, AI, and city.xml to be edited in case a city is removed or added to the city list.
\\
\\
===== Interpolation Tab =====
The Interpolation Tab allows us to load an existing city.xml file with future data. If you do this, then the editor will automatically calculate growth rates for you between the year of the current list you're working on and the year of the data you wish to interpolate to.

{{ :modtools:cityeditor_overview2.png?400 |}}
  - This is the filename of the current list if it has been saved to a City.xml file or loaded from an existing City.xml file.
  - This is the year of the current list you're working on.
  - This is where you select a City.XML file to interpolate the list data to.
  - This will clear out any loaded interpolation files and data.
  - This is the year of the loaded interpolated file and data.  
\\
\\
===== Auto Adjusters Tab =====
The Auto Adjuster tools will automatically alter the city ID's of TurnEvents.xml, AI.xml, and other City.xml files if you add or remove cities from the current list. This is helpful as it reduces the amount of work needed to re-ID entries in these other files should you wish to add or remove additional cities to a map.
\\
{{ :modtools:cityeditor_overview3.png?400 |}}
  - This enables the auto-adjustment of a Turn Events File. (A file must be selected.)
  - Allows you to select a Turn Events file for automatic adjustment of city ID's in case you add or remove a city.
  - Enabled the auto adjustment of the AI files in the list below.
  - List of AI files to have their HQ ID's automatically adjusted should you add or remove a city to the city lists.
  - Adds a new AI file to the adjustment list.
  - Removes the selected AI file from the adjustment list.
  - This enables the auto adjustment of other City.xml files listed below.
  - This is a list of City.xml files to be automatically adjusted if you add or remove a city from the current file.
  - This adds a new City.xml file to the auto-adjustment list.
  - This removes the selected City.xml file from the auto-adjustment list.



\\
\\

====== Files And How it Works ======
When the player starts a new game on a selected map, the MapDataForGame.xml file will tell the game which city.xml files are available and for what year. The game selects the file with the highest year that is less than or equal to the starting year the player selected.

Once the game selects a City.xml file. It loads all the city data from that file into the database/save file for the game to use. After this and other files are moved to the database, the player is then presented the HQ selection map and continues on playing the game.

The City Data is refrenced in many parts of the game and is used by other external data files such as TurnEvents.xml and AI.xml files.

As the player progresses through the years, when he reaches the year for the other city.xml files in the map, the game will load those city.xml file's growth data into the database. Thus the growth values for cities change over the course of the years, as defined by later city.xml values. If proper interpolation is done, a game started in 1900 should end in 2020 with nearly the same data as every city.xml files. (Not including dynamic growth rates caused by AI and the player, and turn events, both static and random.)
\\
\\
====== City Variables ======

^Variable Name^Details^
|City ID| This is the identification number for the city. This number is used to reference the city in the game and in other files. The IDs must be in sequential order. The editor will automatically reorder IDs for you if you have the auto-adjustment system enabled.|
|City Name| This is the name of the city or territory.|
|City Country| This is the country the city belongs to. If making a territory based map, you may wish to name this to a sub region if the territory contains multiple countries. |
|Population| This is how many people live in the city or territory. The game uses this number to calculate how many people are interested in purchasing a vehicle that month.|
|Population Growth| This is the growth rate of the city or territory per year. This number can dynamically change based on player and AI input and random events. It can statically be changed with additional City.XML files at later years than the starting City.xml file.|
|Per Capita| This is the amount of money the typical household makes in the city or territory. Remember, many people make less than this, and a few make much more than this.|
|Economic Growth| The Economic Growth rate effects how fast the per capita rates rise. This number can dynamically change based on player and AI input and random events. It can statically be changed with additional City.XML files at later years than the starting City.xml file. |
|Resource Rate| This rate is how expensive materials are in this city or territory. 1 would be considered average, higher than 1 is more expensive, less than 1 is cheaper.  The rate only be changed with additional City.XML files at later years than the starting City.xml file.  |
|Fuel Rate| This is the price of fuel in the city or territory. This effects both the sales of fuel efficient vehicles and shipping costs to the city/territory. This rating is separate from the Global Gas Price Rate, but effects the same things.|
|Infrastructure Rate|This rating is for the roads, rails, ports and other infrastructure in the city or territory. Higher Infrastructure Ratings will result in cheaper factories, cheaper factory operation, and more vehicle sales. This rate is adjusted based using the Manufacturing Growth rate.|
|Skill Rate| This rate represents how skilled workers are in this city or territory. The higher the skill level is, the more vehicles produced per production line. It also lessens the effect a vehicle's manufacturing requirement have. This rate grows with the Manufacturing Growth rate. |
|Average Wages|This is the average month wages for workers in this city or territory. This rate increases with the economic growth rating. The editor will automatically calculate this rate based on the per capita amounts, but you are free to alter it.|
|Manufacturing Skill| This is how well designed for manufacturing the city or territory is. Higher Manufacturing skills will result in more production, cheaper prices, and cheaper cost to build factories.|
|Manufacturing Growth| This is how quickly the Manufacturing, Skill, and Infrastructure rates grow or shrink. This value is dynamically changed based on random events and AI or player input. It is statically changed by  with additional City.XML files at later years than the starting City.xml file.|
|Government/Conflict| This rating is the current stability of the city or territory. When the government is stable, sales and production will be at 100%. Limited Conflict sales and production will be at 50%. When the government is at War, sales will be stopped, and production will limited to only military contracts. Finally, when the government is at Total War, sales will be stopped, production will limited to only military contracts, and there is a chance your factory and branch will be destroyed. In the future we may implement a 5th status for communist/state controlled. But it is currently not implemented.|
|Tax Rate| This is the amount of taxes companies pay if their headquarter is located in this city or territory. This rate is a percentage, where the value 1 is 0% and and a value such as 1.35 is 35% tax rate.|
|Buyer Rate| This rate is a modifier to increase or decrease the amount of vehicle buyers in the city or territory. For example setting this value to 2 will double the amount of vehicle buyers in this city or territory. This is handy for historical purposes, for example, the United States buys more vehicles per capita than any other nation. Yet their cities have significantly less population than some Asian countries that have lower vehicle sales per capita. As such the buyer rate can increase US sales, even though it has fewer population.|
|Flag| The flag file is a .dds picture that must be no larger than 64x32 pixels in size. The flag file is displayed in the city information window. TurnEvents.xml file will handle changing the flag files after the initial flag is set with the Cities.xml file. The drop down box is populated with existing heading pictures added to the current city's list.|
|Heading Picture| This is the banner that appears at the top of the City Information window. This file must be .dds file and should be 256x64 pixels in size. The drop down box is populated with existing heading pictures added to the current city's list.|
|Coordinates| This is the world (GPS) coordinates for the city or territory. This effects vehicle shipping. If creating or editing a "DotCityMap" the world coordinates will place the city on the map. As such, these numbers need to be as accurate as possible.  |
|Region|This is the region or continent that the city or territory is located in. Regions effect awards, and premade districts. The regions are broken down as the following: 1) North America, 2) Europe, 3) South America, 4) Africa, 5) Asia, 6) Australia.| 
\\
\\
====== Helpers: Interpolation and Auto Adjusters ======
The City Editor offers a tool to help alter the current city list as well a tool to edit multiple other files if you add or remove a city in a map or mod.

===== Interpolation Years and Values =====
The Interpolation tool will automatically calculate population growth, economic growth, and manufacturing growth between the current city's list and a selected city.xml file. The selected city.xml file must be a later year than the current city's list otherwise the interpolation values will be incorrect.

To use the Interpolation tool:
  * Select the "Interpolation Years and Values" tab ({{ :modtools:cityeditor_overview1.png?linkonly |'A' in this picture}}).
  * Set the year for the current file you are working on  ({{ :modtools:cityeditor_overview2.png?linkonly |#2 in this picture}}).   
  * Select a City.xml file from a future year ({{ :modtools:cityeditor_overview2.png?linkonly |#3 in this picture}}). If you have multiple future City.xml files, select the one closest to the year you are working on.
  * Set the year of the selected City.xml file you opened to interpolate to.

If you do these 4 steps, then cities in your current city list will have the growth rates automatically calculated to the later city.xml's values. 
\\
\\
===== Automatic Adjusters =====

The other tool included with the city editor is the Automatic Adjuster. The Automatic Adjuster system will automatically change ID's in TurnEvents.xml files, HQ ID's in AI.xml files, and add or remove cities from City.xml files.

This greatly saves you time when adding or removing a city from a map or a mod. Without the Automatic Adjuster system you will have to manually edit every effected entry in TurnEvents, AI, and City xml files effected by the change.

==== Turn Events Automatic Adjust ====

Enabling the Turn Events Automatic Adjuster will automatically remove cityevents of removed cities. It will also re-ID the remaining city events that have incorrect ID's due to the adding or removing of cities from the current city list.  

The Turn Events Automatic Adjuster must be enabled and the file must be selected before any changes are made to the current city list. Otherwise it will not work.

To enable the Turn Events Automatic Adjuster:
  * Open the Auto Adjuster Tab ({{ :modtools:cityeditor_overview1.png?linkonly |'B' in this picture}}). 
  * Click the checkbox beside "Turn Events File"  ({{ :modtools:cityeditor_overview3.png?linkonly | #1 in this picture}}). 
  * Click the Turn Events file selector button ({{ :modtools:cityeditor_overview3.png?linkonly | #2 in this picture}}). 
  * Select the TurnEvents.xml file for this map or mod you wish to automatically adjust.


==== AI Automatic Adjust ====

The AI Automatic Adjuster will change the HQ ID's of AI companies if you add or remove a city from your current city lists. The AI Adjuster can edit multiple files at the same time.

If you remove a city, any AI companies with the same HQ-ID as the removed city will be changed to the City with the next ID. The remaining AI will have their HQ-ID's adjusted so that they remain in the same city as before the removal of a city. (If you remove a city, any ID's greater than the ID removed has to shifted down 1 value.)

Likewise, adding a city will cause AI Adjuster to adjust the HQ-IDs so the correct city is used as the value. 

 The AI Auto Adjuster must be enabled and files must be selected before any changes are made to the current city list. Otherwise it will not work. 

To Enable AI Auto Adjusters:
  * Open the Auto Adjuster Tab ({{ :modtools:cityeditor_overview1.png?linkonly |'B' in this picture}}). 
  * Click the checkbox beside "AI Files"  ({{ :modtools:cityeditor_overview3.png?linkonly | #3 in this picture}}). 
  * Click the "Add AI File" ({{ :modtools:cityeditor_overview3.png?linkonly | #5 in this picture}}). 
  * Select the AI File you wish to automatically adjust.
  * Repeat the last two steps until you have all the AI files you wish to adjust listed in the list box ({{ :modtools:cityeditor_overview3.png?linkonly | #4 in this picture}}). 

Do these steps, and they'll save you a boat load of time when making or editing your map or mod.
==== City Automatic Adjust ====

The City Automatic Adjuster will add or remove cities from the selected city.xml file based upon your actions taken to the current city list.

If you remove a city from the current list, the City Automatic Adjuster will remove the city from the selected files and re-ID the remaining cities.

If you add a city to the current list, it will add the same city, with the same data to the selected city.xml files.

The City Automatic Adjuster should be enabled and the files should be selected before altering the current city list if you wish the changes to take effect in the selected city files.

To enable the City Automatic Adjuster:
  * Open the Auto Adjuster Tab ({{ :modtools:cityeditor_overview1.png?linkonly |'B' in this picture}}). 
  * Click the checkbox beside "Other City Files"  ({{ :modtools:cityeditor_overview3.png?linkonly | #7 in this picture}}). 
  * Click the "Add City File" ({{ :modtools:cityeditor_overview3.png?linkonly | #9 in this picture}}). 
  * Select the City File you wish to automatically adjust.
  * Repeat the last two steps until you have all the City files you wish to adjust listed in the list box ({{ :modtools:cityeditor_overview3.png?linkonly | #8 in this picture}}). 

Now you may add or remove cities from the current city list, and the changes will be applied to these files. Thus saving you time from having to edit all these other files as well.

\\
\\
====== Examples ======

The following offers several examples of what you can do with the City Editor and the steps to take to perform these actions.

===== Opening Existing City File =====

Whether you're wanting to open an existing file to edit it or just look at the data, knowing how to open an existing City File is important. 

=== Opening File Made From Scratch ===
If you're creating a Map or a Mod from scratch and haven't generated the map or mod files, then the City.xml files will be anywhere you saved them. To load them into the editor simply click "Load City List" ({{ :modtools:cityeditor_overview1.png?linkonly | #3 in this picture}}). And then select the City.xml file you want to load. You can now continue on to editing, adding, or removing cities.   


=== Opening Existing File from a Map ===
It is recommended that you do not alter maps included with the default installation of the game. You should create your own map to edit, using the existing maps as a base. For more information on how to create your own map see [[modtools:make_a_map_editor|Creating a Map]]

To open an existing city.xml file from a map, you must know where the Maps folder for the game is located. See [[modtools:file_locations|File Locations]] for the location of the Maps folder. Next simply click "Load City List" ({{ :modtools:cityeditor_overview1.png?linkonly | #3 in this picture}}). Go to the Maps folder, select the folder for the map you wish to edit. Enter the "Scripts" folder. Then select the City.xml file you wish to edit. And you're done, you may continue to add, edit, or remove cities from the file. Be sure to save when you're finished!



=== Opening Existing File from a Mod ===

To open an existing city.xml file from a mod, you must know where the Mod folder for the game is located. See [[modtools:file_locations|File Locations]] for the location of the Mod folder. Next simply click "Load City List" ({{ :modtools:cityeditor_overview1.png?linkonly | #3 in this picture}}). Go to the Mods folder, select the folder for the mod you wish to edit. Enter the "Scripts" folder. Then select the City.xml file you wish to edit. And you're done, you may continue to add, edit, or remove cities from the file. Be sure to save when you're finished!

\\
\\
===== Editing A City =====

The most simple action one can take with the City Editor is to edit an existing city. Simply select the city from the Current City's list ({{ :modtools:cityeditor_overview1.png?linkonly |#10 in this picture}}). Edit the data you wish to change on the left ({{ :modtools:cityeditor_overview2.png?linkonly |#8 in this picture}}).   Then hit "Save" at the bottom left of the screen ({{ :modtools:cityeditor_overview1.png?linkonly |#14 in this picture}}).     

That's it! Click "Save City List" overwrite the file you wish to overwrite, and you've successfully edited and saved the new City.xml file.

**Please note, you may wish to enable Interpolation tools if you are editing an existing map or mod file's Population, Per Capita, or Manufacturing skills. Otherwise the growth rates between City.xml files will be incorrect. See the [[modtools:cityeditor#Interpolation_Years_and_Values| Interpolation Helper Tool]] for more details. **

\\
\\
\\
===== Adding A City =====

Whether adding a new city to an existing city.xml file used in a map or mod, or adding cities to a city.xml file created from scratch, the process is the same.

Be sure the City ID is unique value, otherwise you will be editing an existing city. To be sure, click the "New" button ({{ :modtools:cityeditor_overview1.png?linkonly | #11 in this picture}}).

Fill out the data on the left hand side. When you're ready to add the city, click the "Save" button ({{ :modtools:cityeditor_overview1.png?linkonly | #14 in this picture}}). There you go. You've added a city to the Current Cities list.  

**Please Note, if you're adding cities to an existing city.xml file that has other files that depend on it, you should use the Auto Adjusters to reduce your work load. See [[modtools:cityeditor#automatic_adjusters|Automatic Adjuster Helper]] for more details.**
\\
\\
===== Removing A City =====

\\
\\
====== Troubleshooting ======