Everything that can be modded (jobs, education, items, activities, preferences, etc) has a unique ID. We can create new items by adding new IDs, or edit the details of existing items by referencing their existing IDs.

In this guide I'll go through the steps for creating a Health Inspector job (new ID) at the City Hall (existing ID) as an example. This is the mod created from this guide: https://steamproxy.com/sharedfiles/filedetails/?id=3166247988

Open the modsLocal folder in the game directory and create a new folder where all the mod contents will be stored. Inside this new folder, the contents should follow the same structure as the base game.

• Create a data folder
  
• Create modName.txt with one line that has the name of your mod
  
• Create modDesc.txt with a description
  
• Create modImage.png containing the primary image for uploading to the workshop
  
• (Optional) Create modInfo.txt with one line for the load priority of this mod. Lower priority number means it loads first. If you don't create this file it will default to priority 0. Currently only used so mods that overhaul city policies don't overwrite mods that alter existing city policies.
  
• (Optional) Create modType.txt with one line for the category this mod will be displayed under in-game (valid categories are modTypeGeneral, modTypeCities, modTypeCountry, modTypeGameplay, modTypeHousehold). If you don't create this file it will default to the General Mods tab.

It should look something like this:



In the data folder, create /jobs/healthInspector.xml (or whatever you want to call the xml, doesn't matter). We are going to add our new Health Inspector job in this file. You can look in data/jobs/baseJobs.xml for a template, or copy an existing similar job's data to edit. The data/idmap.txt file should also help with quickly referencing existing IDs.

• First, pick a unique ID between 1,000,000 and 2,000,000,000 for this job. If you use a random number generator it's very unlikely you will choose the same numbers as another modder. I'm going to use 1470556346.
  
• Edit all the other values as you see fit. Someone who loves Hygiene (ID 10085) and gets a kick out of having a little Authority (ID 10075) would enjoy this job so I'm going to put those in the action preferences.

Next, we add the job to the City Hall (ID 50541). In the data folder, create /sites/townHallOverride.xml (or whatever name). Since the City Hall is an existing object, we want to use the same ID and only add the new job while leaving everything else intact.

Note you always need to set active="1" to make sure the game doesn't ignore your new entry. It should look like this:


Side note: You can use replace="1" to delete any existing elements so only your modded version shows up. If you wanted to remove all existing jobs from the Town Hall and only have your Health Inspector job, this is how it's done:

Start the game.

• In the Options menu, make sure Enable Dev Mode is ticked
  
• Enter the Mod Menu and look for your mod. If the previous steps worked you should see the new mod listed as a local mod.
  
• Click on the Create New Mods button (plus sign)
  
• Enter the folder name containing your mod and click Load From File
  
• Click Get New ID. This will create a modSteamID.txt file in your mod's folder
  
• Click Submit Item. Wait for the result and if successful, you should see your mod in the Steam Workshop.

If you want to update this mod in the future, click Load From File which will automatically fill in the existing ID using modSteamID.txt. Then Submit Item to update the existing item.

• If you are looking for further help, you can ask in the Steam forums or in the mod discussion channel on the Discord https://discord.gg/GYZCqe3FpP
  
• When starting/loading a game, mods are applied in the following order:
  1. Language mods
  2. Steam workshop mods + Local mods with modType.txt set to modTypeCities
  3. City mods
  4. Steam workshop mods + Local mods with modType.txt set to any other type. Load order is based on modInfo.txt priorities
  
• ID 3000 in data\misc\defaultData.xml is a special object to allow modifying all sorts of gameplay variables like start conditions, legal working age, etc.
  
• If your mod requires more than one new ID, it's probably good to choose a range of numbers close to each other, e.g 1470556300 - 1470556400. If it's ever needed in the future, we can set up a system of "claimed" ID ranges so other modders know not to use those numbers.
  
• The data/idmap.txt file and internal xml data is regenerated every time you start / load a game. So you don't have to restart the whole app while testing changes, just reload an existing save.
  
• However, images are only loaded when the app is started so if you modify / add images then the whole app needs to be restarted.
  
• The idmap.txt also has some built-in warnings for common mistakes. They will appear at the top of the file, for example:
  

  WARNING: actionStudy not self-referencing 45121 5435
  1101 (Tag) Food
  ....

  
  
• You can also override existing image files with a mod. For example, if you wanted a custom cursor then create a file [YOUR_MOD_FOLDER]/art/ui/UICursor.png and this will replace the existing UICursor.png when your mod is loaded.
  
• The modOutput folder contains files showing what an xml looks like internally when a non-language mod is applied. It can be helpful in debugging issues when your mod isn't doing what you expected. The files themselves have no impact on the game, they are only here to help debugging.
  
• There are various data/stats***.txt files generated every time you start / load a game that you might find helpful. I use them as info dumps to quickly see if something is wrong (e.g businesses in statsFirm.txt are all balanced around an Income / Expense ratio of ~130%).
  
• To enable the debug menu, go to Options and tick the Enable Dev Mode checkbox. The debug menu button will then be visible (see screenshot below) and allow you to do things like spawn free money, add status effects, fast forward time, etc. It can be useful when testing your mod.