Humankind

Humankind

HUMANKIND™ is Amplitude Studios' magnum opus, a Historical Strategy game where YOU will re-write the entire narrative of humankind.

Learn more and find the game on Games2Gether, Steam, Epic Games Store, Stadia, Please read modding guidelines.

Creating a custom selectable culture for Humankind

This guide will walk you through creating a custom selectable culture for Humankind. It's aimed at people with no modding experience and contains detailed explanations of what steps to take and where and how to find the items discussed; there are also screenshots highlighting the same things.

12 comments

Posted by on (updated ago)


Creating a modded culture for Humankind

by uncle2fire

Note: I am in the process of rewriting parts of this guide, as well as expanding on a few parts of it.

This guide will walk you through the creation of a modded selectable culture for Humankind. It’s intended for people with very little or no experience with modding, so it’s very step-by-step. I’ll also include descriptions of what certain parts do, which will hopefully allow you to more easily identify where problems are if you are not seeing what you expected to see in the game after loading the mod at the end of the process.

Alongside the written steps, I will include screenshots of the mod tools so that hopefully it’s easy for you to follow along and avoid as many problems as possible. If you do run into any problems following the steps in this guide, check the end for common problems. Also feel free to leave a comment or contact me on reddit, mod.io, or Discord with any questions or if you need help with any part of the process.

This guide will show you how to create a relatively simple culture. There is a lot of room for more complexity with different aspects of the culture you create, but we’ll start with the simple and you can aim for more complex changes and effects once you’ve got the basics down.

In this guide, I will be creating a modded Akkadian culture for demonstration purposes. If you would like to see the finished culture, you can find it on mod.io here.

You can also find this guide as a Google doc here.

First steps

The first step to take is to download the mod tools on Steam. If you don’t have Humankind on Steam, modding tools may not be available to you.

To download the mod tools, open your Steam library’s tool list and download the tool. The developers have provided instructions on how to install and prepare the mod tools before you start modding, which includes downloading Unity. Those instructions can be found in this post by the developers on Steam.

This guide will assume that you’ve already finished installing and preparing the mod tools.


Creating a project

The first step in creating a culture is to create a new project. You can do this by opening the mod tools and clicking “next” through the pop-ups until prompted to name your project. Make sure that the project is being saved in C:\Users\yourname\Documents\Unity Projects.

Pick a name for your new project. You can name it whatever you want; the name will be what’s displayed if you eventually upload the mod to mod.io, and it can be changed later. It will make playtesting much easier if the name doesn’t have any spaces in it (this will be explained later). Once you’re comfortable, click “Create Project”.

Naming a project

It will take a little while for Unity to load and prepare the archives (where files from the game that you can edit are stored), but once it has, your screen should look something like this.

Initializing mod

Click the giant green “Initialize Mod” button. Here you can add your name to the author field and give a brief description of what your mod does. Congrats! Your mod is created. Now we move on to editing files.


Importing Assets

Mods are just edited versions of the game’s files, and to edit those files we need to import them from the archive. To do this, go to the “Data” tab and click “Import from Archive”. This will bring up a list of folders. You do NOT need to import all of the folders; we won’t be touching most of the files. The ones we do want to import are these (see below the list for notes):

Importing assets

  • Under the Civilizations folder, import the following folders:
    • CivilizationDefinition
    • CivilizationUIMappers
    • LegacyTrait
    • LegacyTraitDescriptor
    • LegacyTraitUIMappers
  • Under the Settlement folder, import the following folders:
    • ConstructibleEmblematicExtensionDefinition
    • ConstructibleEmblematicExtensionDescriptor
    • ConstructibleEmblematicExtensionUIMappers
  • Under the Unit folder, import the following folders*:
    • LandUnitDefinition
    • LandUnitDescriptor
    • LandUnitUIMappers
  • Under the UnitPresentation folder, import the following folders (note the the [NUMBER] is whichever era your new culture will be from: 1 is Ancient, 2 is Classical, etc.):
    • PresentationPawnDefinition_Era[NUMBER]
    • PresentationUnitDefinition_Era[NUMBER]

*These folders are for land units. If you intend to add an emblematic naval, transport, or air unit, you will instead need to import the files with “LandUnit” replaced by “NavalUnit”, “NavalTransport” or “AirUnit” respectively.

Note: these are the basic folders you will need. For more complicated parts of creating a culture, you will need to import other folders and files as well. Later in this guide I will cover one of those instances.

After importing these files, they should all appear in your project tab. From here you can move on to editing the files.

Imported assets


Editing Files

Editing the files requires some amount of jumping around between them because of references. The way that the game knows certain files are associated with each other is by references, and we can’t always add these in one file until we’ve created another file. You’ll see what I mean as we get into it, but that’s why it feels like we have to backtrack a few times.

Creating your culture

Step 1

The first thing to do is create a new FactionDefinition file, which will be the way the game knows that your new culture is selectable. To do this, open the CivilizationDefinition folder in the inspector (left click on “CivilizationDefinition” in the project tab).

If you left click on one of the files in this folder, you’ll see a lot of information about the culture it defines, like the era it’s selectable in and its affinity. On the second tab, “Presentation” you can see information about how the culture will appear in-game, like the visual appearance of units and buildings.

AvatarCostume invalid

The most important thing to notice here is that under the “Presentation” tab, there’s a big yellow notice that the AvatarCostumeAffinity is missing or invalid. This governs which clothes your avatar wears while playing as this culture, and for every default culture, the mod tools do not recognize their clothing as valid. This is a total lie, and the clothes will appear normally in-game despite this error. Why this is important is that it is not possible to create a new FactionDefinition file with any clothes (avatars in-game will not appear in culture-specific clothes). To get around this, instead of creating a new FactionDefinition file, we’ll just duplicate a pre-made file and then edit all the particulars to fit with our new culture instead of the default one.

Long story short: you’ll want to pick the culture whose clothes match best with the culture you’re creating. For my Akkadian culture, because the Akkadians and the Assyrians are historically culturally related, I’m going to pick to duplicate the Assyrian file and edit from there. To do this, right click on the file you want to duplicate and pick the “Duplicate 1 Element” option.

You can pick a culture from any era for this; the one you copy does not need to be from the same era as your new culture (though more modern cultures will have anachronistic clothes for an ancient or classical culture).

Once you’ve created your duplicate file, rename it by replacing the name of the default culture with the name of your new one. It should have the format Civilization_Era[NUMBER]_[CULTURE].

In this file, you can edit a lot of different things:

  • Under the Definition tab:
    • Era: be sure this option matches the era of your new culture (1 for Ancient, 2 for Classical, 3 for Medieval, 4 for Early Modern, 5 for Industrial, and 6 for Contemporary)
    • Make sure that your new culture is marked as Major, Exclusive, and Upgradable
    • Pick your affinity (some of the names are slightly different from in-game, but they’re easy to figure out)
    • Legacy Trait (we’ll come back to this later)
    • Settlement names: these will be the names of cities founded while playing this culture. Default cultures all have 10 names, but you can add more or fewer. The cities will be founded in the order you put in here.
    • Army, Squadron, Militia, and Siege Engine names (I will usually not edit these)
  • Under the Presentation tab:
    • Building visual affinities: what your culture’s buildings will look like (if the culture you copied the file from is culturally close to your new culture, you can leave these as they are, or you can change them to fit with a culture from a different part of the world). This will also govern how your Main Plaza and Emblematic District appear in-game. So you may want to consider picking a visual affinity for a culture whose emblematic district looks most similar to the one you plan to add (currently it is not possible to import 3D assets, so you will need to have your emblematic district appear in-game as one of the pre-existing emblematic districts.
    • Unit visual affinities: same as above, but for your culture’s units
    • Faction constructible variation: the regional style of your culture’s unit cards (what icon you will see in-game when building or selecting your units)
      • 1: Central and South America
      • 2: Native North America
      • 3: South Asia and the Middle East
      • 4: East Asia (except Japan) and the Huns
      • 5: Southeast Asia and the Mongols
      • 6: Sub-Saharan Africa
      • 7: Japan
      • 8: Europe and “Western” cultures in the Contemporary Era
    • Skin and hair color references: these change the skin and hair color of your units; you can look at the files of other cultures to see what options they use to get an idea of which might work best for your culture.
    • Landmark Name Affinity References: don’t touch this

You can feel free to edit these however you like. Because the Akkadians are so similar to the Assyrians in visual affinities and I want my modded Akkadians to also have the Expansionist affinity, I’m just going to edit the city names to be more specific to the Akkadian Empire. Then, because the Assyrian Dunnu looks nothing like the emblematic district I want to add later, I will change the building visual affinity in Era 1 to the Babylonians instead.

Faction definition

Step 2

The next step will be to create a new CivilizationUIMapper file. UIMapper files, which we’ll see several of, govern how your culture and the changes you make appear in the in-game UI. Things like the culture’s name, the art on the selection screen and building icons, the names of your culture’s legacy trait, EQ and EU, and descriptions and quotes you want to add. The CivilizationUIMapper file determines how the game will display your culture’s name, quote, and selection screen art.

Again, because importing outside assets is not possible right now, we can just copy another culture’s CivilizationUIMapper file and edit it from there. To do this, just duplicate another culture’s file, the same as before, and rename it to your culture. This file includes the art that will be shown on the culture selection screen for your new culture, so duplicate the file of a culture that has art that best matches your new culture. I’m again going to copy the Assyrian file, because the art fits well.

After duplicating the file, rename it to match exactly the name of the file you made in step one.

The text boxes in this file that you can edit are:

  • Title: the name of your culture that will appear in-game
  • Description: a description of your culture (does NOT appear in-game)
  • Images: various sizes for the culture’s art; I wouldn’t change any of this
  • Symbol: leave this alone
  • Leader title and description: leave blank
  • Quote: whichever quote you’d like to be visible on the culture selection screen
  • Adjective: the adjective for your culture
  • UI Constructible Culture: this doesn’t work how you might expect
    • all cultures from the Ancient Era plus the Achaemenid Persians have the tag Culture_Era1_Mesopotamian
    • all cultures from the Classical Era have the tag Culture_Era2_GrecoRoman, except for the Achaemenid Persians
    • all cultures from the Medieval Era and later have the tag Culture_Era3_Romanesque

Faction uimapper

Legacy Trait

Step 1

The next step is to create your culture’s legacy trait. We’ll start by creating a Descriptor file in the LegacyTraitDescriptor folder. To do this, open the LegacyTraitDescriptor file, right click inside the inspector box and pick the “Add” option. “Descriptor” should be the only file option to add.

Rename this file in the format of the other files in this folder: Effect_LegacyTrait_Era[NUMBER]_[CULTURE].

Legacy trait descriptor

In this file, choose MajorEmpire from the Starting Type drop-down. Then add an effect by clicking the little plus symbol icon. This effect is what will create your culture’s legacy trait.

There are about ten million different legacy traits you could come up with with these tools, some much simpler to add than others, but the one I’d like to add to my Akkadian culture is a reduction of unit upkeep cost.

The first step in creating an effect is to determine the path of the effect. Basically, what will this effect be affecting? Cities? Units? The empire as a whole? These are all options in the drop down list when you click the little plus sign.

Legacy trait descriptor path

If your legacy trait will affect cities, districts, or something else, you’ll have to pick a path for that. You may have to stack paths to get to the destination you want. For example, if you want your legacy trait to affect districts, there is no MajorEmpire.Districts path, instead you have to choose the path MajorEmpire.Cities.Districts (there are also other paths you can take to get to districts). You can experiment with finding new paths by clicking the little plus sign repeatedly and looking through the options it gives you. The trait I want for the Akkadians affects units, so I choose the path MajorEmpire.Units.

After picking your path, click the plus sign next to “Property Effects”. This is where you’ll define what the effect actually is. For each Target and Source (determined by the first and last steps in your chosen path) there’s a list of possible property effects. You can see this list by opening the property list right above the “Help” bubble. Some of these are easily understood (FoodProduced, for example) but some are much less clear (what does PopulationConsumption mean, for example?).

Legacy trait descriptor property

The best way to learn about what these effects do is to look at the legacy traits for the other cultures and see what exactly their effects are defined as. You can use this to figure out how to define the effect you want. For example, if you want to know how to increase the Food yield per Farmer, you can look at how the Celtic legacy trait is defined (which adds 2 Food per Farmer) and copy its definition.

My Akkadian effect is relatively simple; I just choose the property UnitUpkeep. Then we have the choice of an operator (add/subtract/multiply/etc.). I want to give the Akkadians a -20% upkeep cost on their units, so I’ll pick the Percent operator and enter a value of -0.2. If I instead wanted to subtract a specific amount from the upkeep, I could use the Subtract operator and pick a number to subtract from the upkeep cost.

Legacy trait descriptor finished

There are ways to give much more complicated legacy trait effects, but I won’t cover that in this guide. This should be enough to create most simple legacy traits, but feel free to experiment with different paths and properties to get different effects.


Step 2

Now we’ll create a FactionTrait file to allow your new legacy trait to apply to a culture in-game. To do this, open the LegacyTrait folder and right click to create a new FactionTrait file. Rename it to follow the format LegacyTrait_Era[NUMBER]_[CULTURE].

In this new file, create a simulation event effect. Choose PluginEditorTypes>Amplitude.Mercury.Data.Simulation>SimulationEventEffect_ApplyDescriptor from the drop-down list.

Legacy trait definition

In the Descriptor field, choose the legacy trait effect you just created, Effect_LegacyTrait_Era[NUMBER]_[CULTURE].

In the commands section, create a command called SpawnUnit and then create two arguments. These arguments should be two unit descriptors. You can copy/paste these from the FactionTrait file of another culture in the same era, because they differ in each era. If you are planning to create an emblematic unit that replaces one of these units for your culture, then leave these arguments blank for now. We’ll come back to fill them in after we’ve created our emblematic unit.

Legacy trait definition simulation event effect

Note: You might notice in this folder that Ancient and Classical era cultures all have a second file called LegacyTrait_Era[NUMBER]_[CULTURE]_EmblematicUnit. These files aren’t referenced anywhere and my playtesting shows that they aren’t needed for a culture to work, so you can ignore them.


Step 3

Now we’ll create the UIMapper file for our legacy trait, so that it appears correctly in the UI in-game. To do this, open the LegacyTraitUIMappers folder. To make this easier, you can simply duplicate an existing UIMapper file from a culture with the same affinity as your new culture (this will ensure the icon for the legacy trait matches your culture’s affinity). My Akkadians are expansionists, like the Assyrians, so I’ll just duplicate the Assyrian UIMapper file here and then edit it for the Akkadians. It’s important that this file have the same name as the FactionTrait file you created earlier: LegacyTrait_Era[NUMBER]_[CULTURE].

Legacy trait uimapper

You can edit a few text boxes in this file:

  • Title: the name of your legacy trait
  • Description: a description of your legacy trait (does NOT appear in-game)
  • Images, color, and symbol: these will be copied from the default culture (which will give your culture the same affinity symbol as the default culture)


Step 4

The final step for your culture’s legacy trait is to return to your culture’s FactionDefinition file from earlier (in the CivilizationDefinition folder) and replace the reference to the default culture’s legacy trait with a reference to your own. You can do this under the Legacy Trait References drop-down.

Legacy trait replacing reference

Emblematic District

Step 1

Now we’ll create an emblematic district for your culture. To start, open the ConstructibleEmblematicExtensionDescriptor folder and right-click to create a Descriptor file. Rename this file to match the format of the others: Effect_Extension_Era[NUMBER]_[CULTURE].

This file should look very familiar, because it works the same way as creating the effect of your legacy trait. You start by picking the District option from the drop-down for the Starting Type, then create an effect.

Emblematic district descriptor

Once again you’ll choose the path you want for the effect. For the most part, the paths used by emblematic districts are either just District or District.Settlement. Respectively, these will add an effect to the district itself and to the city/outpost for the territory in which it is built.

Emblematic district descriptor path

To see an example of this, we can look at how the effect of the Egyptian Pyramid is defined.

Egyptian pyramid descriptor

The Egyptian Pyramid has two effects (3 IndustryProduced; 1 CultureProduced) on the path District. This means that the district itself will generate +3 Industry and +1 Influence. The second path defined is District.Settlement, with the effect 1 IndustryWorkplaceNumberOfSlots. This means that the district will provide +1 Worker slot to the city/outpost in the territory in which it is built.

For my Akkadians, I’d like their emblematic district to provide influence, faith, and stability, to support their expansionist affinity. So I choose the path District and the property effects CultureProduced, FaithProduced, and PublicOrderProduced.

Emblematic district descriptor apply effect on

Notice the line that says “Apply Effect On”. Some effects can only be applied to certain pathing elements. For example, Farmer/Worker/Trader/Scientist slots are something that apply to settlements (cities and outposts) and not districts, whereas the effects I added (CultureProduced, FaithProduced, and PublicOrderProduced) can be applied on districts themselves. To apply an effect like adding a Farmer slot to your new emblematic district, you’ll need to ensure that Settlement is the option selected for “Apply Effect On”. You’ll notice, however, that Settlement isn’t an option here (both “Source” and “Target” are District). This is because my path is only District. To have Settlement as an option, I’ll need to create a second path.

With the path District.Settlement, I can choose the option “Target (Settlement)” and create the property effect 1 FoodWorkplaceNumberOfSlots, which will provide the settlement (city/outpost) in the territory in which the district is built with +1 Farmer slot. I don’t want my district to provide a farmer slot, but this is how you can add slots to your district if you want to give your district slots.

Emblematic district adding slots


Notice that when you add additional path elements, the “target” and “source” tags change. To be sure that your property effects work as you want them to, be careful with which of these (target vs. source) is selected.

The final Descriptor file for my new district:

Emblematic district finished

Step 2

Now we’ll create another Descriptor file for your district, this time to define the adjacency bonuses. Add a second Descriptor file in the ConstructibleEmblematicExtensionDescriptor folder, this time with the name Effect_Extension_Era[NUMBER]_[CULTURE]_Synergy00.

Like before, choose the Starting Type “District”. Because we’re now interested in adjacencies rather than the district itself, when you create an effect, define the path District.Neighbours, then choose the “Source (District)” option for Apply Effect On. Now we’ll do something we didn’t do in Step 1: create a validation.

Emblematic district validation


Leave the default first drop-down as “Neighbours”. In the second drop-down list, you can pick whichever synergy element you’d like. For the most part, you’ll be interested in the tags with “base” in their names. For example, Effect_Extension_Base_Industry, which will provide an adjacency bonus per adjacent Makers Quarter. Replace “Industry” in that tag with Food/Money/Science to grant bonuses for adjacent Farmers/Market/Research Quarters. While there are many tags that you can put in this field, not all of them are supported in the UI in-game, so be sure to playtest to see if they appear correctly in-game. I want my Akkadian district to receive an adjacency bonus from rivers, so I’ve selected the GameEffect_Exploitation_River option from the drop-down list.

From here, like in Step 1, create and define whatever property effect you’d like your district to receive from its adjacencies. For my Akkadian district, I want it to receive bonus influence and stability from adjacent river tiles.

Finally, in the box Serializable Category, type “District_Synergy”.

Emblematic district descriptor synergies

Step 3

Now we’ll complete the ExtensionDistrictDefinition file so that our new district’s effects will be connected to a buildable district in-game. To do this, open the ConstructibleEmblematicExtensionDefinition folder and create a new ExtensionDistrictDefinition file. Name the file Extension_Era[NUMBER]_[CULTURE].

Emblematic district definition

In this new file, there are SO MANY things you can edit:

  • Under the Definition tab:
    • Category: what type of district is this?
    • Level: leave at 0
    • Unicity: how many of these can be built? Usually you want One Per Territory
    • Constructible Visual Affinity: pick DistrictVisualAffinity_Emblematic
    • Prototype: pick Extension_Prototype_Emblematic
    • Own Descriptor References: here you’ll want to add several elements:
      • What should the district “count as”? If you want the district to count as a Farmers Quarter, for example, you’ll add the reference Effect_Extension_Base_Food.
      • Add references to the two Extension descriptors we created in Steps 1 and 2; these should be Effect_Extension_Era[NUMBER]_[CULTURE] and Effect_Extension_Era[NUMBER]_[CULTURE]_Synergy00
      • Does the district have a -10 Stability cost? If yes, add the tag Tag_Extension_PublicOrderLoss
      • Does the district provide influence? If yes, add the tag Tag_Extension_Cultural
      • Does the district provide faith? If yes, add the tag Tag_Extension_Religious
    • For the most part, you’ll want to leave the next elements as their default values
    • Exploitation Rule Reference: should the district exploit its own/neighboring tiles? And if so, which yield should it exploit? You can pick from the drop-down list
    • For the most part, you’ll want to leave the next elements as their default values
    • Serializable Replace Terrain With: Change to “None”

Emblematic district definition definition tab

  • Under the Construction tab:
    • These first few elements are best left as the defaults
    • Production cost: choose “Production” from the drop-down list
      • Constant: -1
      • RPN Definition Reference: ProductionCost_Extension_Emblematic_Era[NUMBER]
    • Leave the rest of the elements blank

Emblematic district definition construction tab

  • Under the Prerequisites tab:
    • Resource Access/Supremacy: should a player need a specific resource to build the district? If not, leave as default
    • Era Prerequisite: Equal to None
    • Faction Prerequisite:
      • Operator: Any
      • Faction Name: the file name of your culture’s FactionDefiniton file, with the name Civilization_Era[NUMBER]_[CULTURE]
    • Settlement Status Prerequisite: Unless you want the district to be buildable in unattached territories, leave Camp Constraint as Not Available and change City Constraint to Available
    • You can leave the next few elements blank
    • Under the Own Tile tab:
      • Over a District Prerequisite: check both boxes and add the Serializable Tag “Tag_Extension_Base”
      • Point of Interest Prerequisite: choose No Resource Deposit (this will prevent the district from being built on top of a resource deposit) and check the box
      • River prerequisite: choose “No Constraint” (unless you want to force the EQ to be built only on rivers) and check the box
      • Terrain prerequisite: check the “Hide in UI” box, then add the Serializable Terrain Type Name “TerrainType_CityTerrain” to the list
        • If your district is meant to be built on water, you can remove the default prohibitions
      • Biome Prerequisite: leave as default
      • Cliff Prerequisite: leave as default and check box
      • Mountain Prerequisite: leave as default
      • Tile Visibility Prerequisite: leave as default
    • Under the Neighbouring Tiles tab:
      • Neighbour Operator: either pick “Any Tile” (for standard placement) or “No Prerequisite” (for free placement)
      • Leave the rest as default (unless you want to require the district to be built next to a river)
    • Under the Borough tab: leave as default

Emblematic district definition prerequisites tab 1

Emblematic district definition prerequisites tab 2

  • Under the AI tab: this is where you can tell the AI how much to prioritize the district and for what purpose
    • Add at least one Gain Value (by clicking on the text box). What does this district produce? How much should the AI prioritize building the district for this purpose?
    • District Type: Pick what type of district the district is. If it produces food/industry/money/science, it’s a FIMS district
    • Has Public Order Cost: does the district have a -10 Stability cost? If yes, check the box.
    • Base Synergy District: does the district receive bonuses from adjacency to other districts? If yes, select which district(s) provide(s) bonuses from adjacency.
      • Weight: how much should the AI focus on putting the district next to these districts? 3=heavy weight; 2=medium weight; 1=low weight
    • Synergy River: does the district receive bonuses from adjacency to rivers? If yes, enter a value as above for the weight
    • Target Synergy District Type: what type of district(s) should the AI put the district next to? You can pick more than one.

Emblematic district definition ai tab

Step 4

Now we’ll create a ConstructibleUIMapper file for the new district, so all the effects will be correctly displayed in the UI in-game. To do this, open the ConstructibleEmblematicExtensionUIMappers folder. Again, to make this easier, you can duplicate the default file of another culture; the images included in this file will determine the icon for the district on the culture selection screen and in the build menu for your cities, so pick a culture whose emblematic district at least slightly resembles yours.

For my Akkadians, their emblematic district is the Ziggurat. Ziggurats sadly don’t look much like most of the default emblematic districts, but I think the Babylonian Astronomy House is the best fit, so I duplicated the Babylonian ConstructibleUIMapper file and I’ll edit it to fit with the Akkadians better.

Rename the file to exactly match the ExtensionDistrictDefinition file we made earlier; it should be Extension_Era[NUMBER]_[CULTURE].

Emblematic district uimapper

You can edit a few text boxes in this file:

  • Title: the name of the district
  • Description: a description of the district (DOES appear in-game)
  • Leave the other elements as they are



Emblematic Unit

Note: these are instructions for creating a land unit. If your EU isn’t a land unit, the steps are the same, but in different folders and with different element names. For the most part, I expect you can just replace “Land” in these instructions with “Naval” or “Air” and successfully create a naval or air EU.

Step 1

Now we’ll create an emblematic unit for your culture. To do this, open the LandUnitDescriptor folder and create a new Descriptor file. Rename this file to match the format of the others: Effect_LandUnit_Era[NUMBER]_[CULTURE]_[UNITNAME].

By now I hope this type of file looks very familiar. As Starting Type select Unit, then leave the path as-is. You’ll need two property effects (you can add more, but these two are essential to your unit functioning):

  • LandLeaderPriority: the first property effect should be this one, with an “add” operator and a value equal to another EU of similar purpose in the era. To do this, you can either check in the files of a default culture’s EU, or duplicate one of the default files to start with and then just not change the value here.
  • LandCombatStrength: the second property effect should be this one, with an “add” operator and a value equal to the combat strength of the unit.

Any other property effects you add will be additive off a base, rather than determinant of the final value. That is, while you have to “add” the entire value of the combat strength in the property effect, if you want your EU to have +1 movement over the base for its family (more on families in the next step), you just need to “add” 1, not your intended final value for movement.

Emblematic unit descriptor

Step 2

Now we’ll create a LandUnitDefinition file for our EU so that the effects we just created will be connected to a buildable unit. To do this, open the LandUnitDefinition folder and create a new LandUnitDefinition file. Rename this file LandUnit_Era[NUMBER]_[CULTURE]_[UNITNAME].

Things to edit in this file:

  • Under the Definition tab:
  • Category: Military
  • Serializable Family: pick the unit family that your EU belongs to from the drop-down list. You can check the Humankind wiki to see examples of unit families for different units. Some simple families include Melee, Ranged, Anti-Cavalry, Cavalry, Scouts, and Scout Cavalry. Scroll through the list and see which fits best with your EU.
    • Important note: this unit will replace any generic unit with the same family in your era’s culture. You can see in the screenshot below that I have chosen the family “melee” for my Akkadian EU; this means that my Akkadian EU will replace the generic melee unit in this era (the Warriors)
  • Level: enter a value equal to a unit from the same era as your EU with a similar purpose and similar combat strength. You can see other units’ levels in their respective files.
  • Unicity: Any
  • Constructible Visual Affinity: None
  • Unit Class: select the class of your EU from the drop-down list. What type of unit is the EU? This is NOT the same as family, though there is some overlap. Check out files of other units with similar functions to see what their classes are.
  • Unit Specialty: select the specialty of your EU from the drop-down list. You can check the Humankind wiki to see what different specialties do.
  • Own Descriptor References: You’ll need 4 references here:
    • The effect we created in Step 1: Effect_LandUnit_Era[NUMBER]_[CULTURE]_[UNITNAME]
    • Effect_Unit_Era[NUMBER]
    • Effect_Unit_Emblematic
    • Effect_Unit_Era[NUMBER]_Tier[1 or 2 or 3]
      • This determines the upkeep of the EU. 1=low upkeep, 2=medium upkeep; 3=high upkeep
    • Anything about movement: don’t touch this
    • Visual Affinity Reference Era: the era that your EU is from

Emblematic unit definition definition tab

  • Under the Construction tab:
    • Uncheck “Can Be Bought Out With Population”
    • Production Cost:
      • Type: Production
      • Constant: -1
      • RPN Definition Reference: ProductionCost_Unit_Era[NUMBER]_[low or medium or high]
        • This determines the production cost of the unit against a base for the era
    • Money and Influence Cost: leave as default
    • Population Instant Cost: how much population does the EU cost when building? (Note: not for buying out, but for building normally)

Emblematic unit definition construction tab

  • Under the Prerequisite tab:
    • Resource Access Prerequisites: does the EU require a strategic resource? If yes:
      • Horses=Resource01
      • Copper=Resource02
      • Iron=Resource03
      • Coal=Resource04
      • Saltpetre=Resource05
      • Oil=Resource06
      • Aluminum=Resource07
      • Uranium=Resource08
    • Resource Supremacy Prerequisite: does the EU require having the majority of a strategic resource?
    • Era Prerequisite: Greater or Equal to None
    • Faction Prerequisite:
      • Operator: Any in Factions History
      • Faction Names: Civilization_Era[NUMBER]_[CULTURE]
    • Settlement Status Prerequisite: leave Camp Constraint as Not Available but switch City Constraint to Available
    • Leave the rest of the elements as default

Emblematic unit definition prerequisites tab

  • Under the AI tab: this is where you tell the AI what kind of unit the EU is. Leave all elements as default except the Unit Type at the bottom; select whichever traits apply to the EU

Emblematic unit definition ai tab

Step 3

Now we’ll complete the ConstructibleUIMapper file for the EU. To do this, open the LandUnitUIMappers folder. In order for the EU to have art in the selection screen and the build menu, you’ll need to take art from a default unit. You should find a unit that looks similar to the EU you’re adding; for my Akkadian Axemen, they fit well with the default warrior appearance, so I duplicated the LandUnit_Era1_Common_Warriors file. Rename your file LandUnit_Era[NUMBER]_[CULTURE]_[UNITNAME].

What to edit in this file:

  • Title: the name of the EU
  • Description: a description of the EU (DOES appear in-game)
  • Images, Color, and Symbol: leave as duplicated
  • Sort Priority: value shared between all emblematic units in an era, so copy the value from another file or leave as duplicated if you copied the file of an emblematic unit in the same era as your EU
  • Constructible Traits: leave blank

Emblematic unit uimapper

Step 4 (conditional)

This step is only necessary if your EU replaces a unit that is referenced in your culture’s FactionTrait file (in the LegacyTrait folder) under the Commands>Arguments section (we covered this in the Legacy Trait section, Step 2).

If your EU does replace one (or both) of these units, then replace the tags for these units with the tag for your EU, which should be LandUnit_Era[NUMBER]_[CULTURE]_[UNITNAME].

Legacy trait definition emblematic unit


Unit Appearance

Now we’ll define how your culture’s units will behave and appear in-game.


Step 1

To start this, we’ll go into the PresentationUnitDefinition_Era[NUMBER] folder to create a PresentationUnitDefinition file. This file will govern how your unit behaves in-game (as in, how it moves).

Because programming behaviors is hard, the best thing to do is to pick a unit that moves and behaves very similarly to your EU to copy the behavior file from. For my Akkadian Axemen, I once again think they fit best with the Warriors, so I’ll duplicate the PresentationUnitDefinition_Era1_Common_Warriors_Default and rename the new file with the format PresentationUnitDefinition_Era[NUMBER]_[CULTURE]_[UNITNAME].

In this file, edit the Unit Definition Reference to refer to your EU, which should have the file name LandUnit_Era[NUMBER]_[CULTURE]_[UNITNAME]. Then DO NOT edit anything else in this file. Editing some of these values can make your EU glitch out in-game.

Emblematic unit presentation definition

Step 2

Now we’ll define how exactly your culture’s units (not just the EU but also all the generic units) appear in-game (as in, their 3D models). This step will overwrite the unit visual affinity you set in the FactionDefinition file in step 1 of the Creating Your Culture section.

If you look in the PresentationPawnDefinition_Era[NUMBER] folder, you’ll see that every culture in the era has its own unique 3D model for each unit they can build. Because at this time, importing 3D assets into the mod tools isn’t possible (and it would be a ton of work if it were), we’ll make life much easier for ourselves by once again copying another culture’s units.

You’ll want to pick a culture with similar aesthetics to your new culture. Duplicate each of the files for the default culture (except their EU) you’ve picked and rename them to fit the format of the others. For generic units, you won’t need to change anything in the name but the culture name. For example, I duplicated the Assyrian unit files, including the file Era1_Assyria_Common_Archers_01, and changed its name to Era1_Akkadians_Common_Archers_01.

You can also duplicate the files of different cultures for different units, if you want to.

For all the generic (non-EU) units, you don’t need to edit their files in any way after renaming them. For your EU, you will need to pick a pre-existing unit that looks like it. It could be another culture’s EU, or it could be a generic unit. For my Akkadian Axemen, I once again (unsurprisingly) picked the Warriors as the best stand-in visually.

For the unit you’ve picked to copy the appearance of for your EU, do the same as above: duplicate the file and rename it. But this time, rename it to Era[NUMBER]_[CULTURE]_[UNITNAME]_01.

Emblematic unit presentation pawn definition

In this file, edit ONLY the Presentation Unit Definition. Editing other parts of this file can result in major texture issues in-game (read: your units might end up bright pink).

  • Presentation Unit Definition: change to reference your EU, which should have the name PresentationLandUnit_Era[NUMBER]_[CULTURE]_[UNITNAME]


Technology

The last thing we’ll cover in this guide is how to connect your culture’s emblematic unit and/or emblematic district to a technology. You can skip this step if you want both the district and the EU to unlock immediately upon entering an era.

To connect a district or unit to a technology, we’ll need to import another file or two from the archive. We only need to import the file for the technology we’re interested in editing, so we’ll need to know specifically which technology we want to edit. While I want the Akkadian emblematic district to be unlocked immediately, I’d like for the Akkadian EU to be unlocked with the same technology as the warrior unit it replaces; that technology is City Defense. To see which units and districts unlock with which technologies, you can look them up on the Humankind wiki.

Open the file import window again and this time open the TechnologyDefinition folder (inside the Technology folder). You’ll see that sadly, the technology files aren’t named but are given an era and a number. Conveniently, the technologies are listed in exactly this order on the Humankind wiki’s technology page. I want City Defense, which is an Ancient Era technology and is fourth on the list, so Era1_04.

Importing technology file


Import the file and open it in the inspector. You’ll see a list of SimulationEventEffects, which represent all the things the technology unlocks. We’ll create a new SimulationEventEffect (PluginEditorTypes>Amplitude.Mercury.Data.Simulation>SimulationEventEffect_UnlockConstructible).

Leave the Target ID as MajorEmpire, and create a new constructible reference, picking your culture’s EU from the list. Then add a Gain Value to tell the AI what this constructible is for; mine is for a military unit and I’ll rate it as important.

Technology new constructible

Playtesting

Now it’s time for the big moment! You’re going to test your mod to see if all is working as you planned. To do this, go to the Export tab and click “Build and Run”. This will compile your mod and then launch the game with your mod active (Note: if the name of your mod has a space in it, the game will launch but then freeze before loading the main menu. You’ll need to click “build”, then start the game through Steam and manually apply your mod from the in-game mods menu). Once the game loads, just choose to start a new game with whatever settings you want.

Build and run

As you play, you should keep an eye on a few things to make sure they’re working.

  • Can you select your new culture when you get to their era?
  • Is there art for the background of the selection screen, and for the emblematic district and unit icons when choosing your culture?
  • Are the effects of the legacy trait and the emblematic district correct? Is the emblematic unit’s info correct?
  • When playing as your culture, can you construct both your emblematic district and your emblematic unit?
  • Do your units look normal (or are they bright pink)?
  • Do the effects you defined actually work?

Once your mod is working as you want it to, just complete the required text boxes in the export tab, with a summary, description, and image for your mod, then upload it to the server to publish it on mod.io.

I can’t wait to see what you make!




Common Problems

My culture doesn’t appear when I get to the culture selection screen for their era.

This is probably a problem in your FactionDefinition file, in the Civilizations>CivilizationDefinition folders. Make sure you have the right Era Reference selected and that “Is Hidden” isn’t checked.


My culture’s Legacy Trait/Emblematic District/Emblematic Unit don’t appear on the selection screen.

This is a problem in the UIMapper file for the LT/ED/EU. Return to the file and double check with the instructions that you didn’t miss a step.


My culture’s Legacy Trait/Emblematic District effect didn’t translate into words (usually bright pink elements that sound like computer code).

Sadly, some property effects in the files for these apparently don’t have set translations into normal words. If the effect works as you intended and the only problem is the bright pink UI description, there may not be anything you can do to change it. You can ignore it, try to go back to the property effect editor to find another way to get the same effect, or (what I do because I can’t stand the bright pink in the description) create a different property effect.


My culture's Legacy Trait/Emblematic District effect isn't working.

It could be that you've forgotten to add a reference somewhere; without these references in all the right places, the game won't know to connect the different parts of your culture to the playable culture once the game starts. Go back to each Definition file to check that all your references are where they're supposed to be and are the correct reference (and not, for example, a reference to your emblematic district in the Definition file for your Legacy Trait). The other possibility, especially with more complex paths and property effects, is that they just aren't working. This could be because the path you have doesn't work, or your defined operator and and source/target reference in the property effect are too complicated. It could also be that the effect doesn't work the way you expected. Often the best way to fix these issues is, sadly, to re-design the effect. I highly recommend playing around with paths and effects to get a better idea of how they work and how they interact.


My avatar is wearing the wrong clothes.

You’ll need to check your FactionDefinition file, in the Civilizations>CivilizationDefinition folders to be sure you have an option selected for Avatar Costume Visual Affinity. If you don’t, copy and paste one from another culture whose clothes you like better.


I can’t build my Emblematic District when playtesting.

There is probably an issue in your ExtensionDistrictDefinition file, in the ConstructibleEmblematicExtensionDefinition folder. In particular make sure that your faction prerequisite is correctly set, and that under the Prerequisites>Own Tile tabs, under the Over A District Prerequisite heading, you’ve added the Serializable Tag Tag_Extension_Base.


Building my Emblematic Unit causes the endless turn pending bug.

There is probably an issue in your LandUnitDefinition file. Make sure that you have the Visual Affinity Era Reference correctly set, and that you have all four Descriptor References (both under the Definition tab).


My units are all bright pink.

Check the Unit Visual Affinity Reference field in each unit’s PresentationPawnDefinition file; it should be set to default culture.


When playing my mod, the build menus in cities all have words replaced with “UIMapperMissing” (or something similar).

This is an issue that usually happens when you change which mods are applied without restarting the game. Try restarting the game, reapplying the mod, then starting the game again and this issue should go away.


When trying to “Run” my mod from the editor, the game freezes.

You probably have an unrecognized character (like a space) in your mod’s name. Just click “Build” and then manually start the game and apply your mod.


Other problems or questions? Struggling with following the directions or trying to get a complicated effect to work?

Let me know! I’m happy to help. You can contact me on reddit, mod.io, and Discord. My name on all of them is uncle2fire. You can also leave any comments on this document that you’d like.


Happy Creating!

12 comments

Join the community or sign in with your gaming account to join the conversation:

Enchanteur
Enchanteur @enchanteur

So much work on this guide, and so usefull. It help me a lot about creating new assets and use references. I was sure it was something like that, like previous Amplitude games. But not easy to find how to do on this mod tool. Many many thanks.

Salterius
Salterius @salterius

For 2D assets, Drop them in the Resources folder and you can use them for mods.

Enchanteur
Enchanteur @enchanteur

It's too late for many mods now. But whenever someone add something new, it's better to prefix the name in a unique way.
For example Era1_Accadians, add your name, like that Era1_AccadiansUncle, or Era1_UncleAccadians.
If anyone else create also an Accadians culture Era1, and bad luck, same name, the mods will conflict.

TrOpicDr3am
TrOpicDr3am @tropicdr3am

Nice, now I can learn how to make the factions I want added :D

FreeThinker
FreeThinker @dfdsfsdfdsf

How to make a new unit upgradable to another unit?

Uncle2fire
Uncle2fire @uncle2fire

Sorry I didn't see this earlier!

This is done with the UnitFamily line of the unit's Definition file. All units of the same family will upgrade to either 1) any available unit of the same family and a higher level, or 2) any available unit of the defined upgrade family of a higher level.

If you open the UnitFamily folder, you can see which families upgrade into which others. For example, Scouts are of the unit family "Scouts"; this unit family upgrades into the unit family "Light Cavalry", of which the Horsemen is a member. So Scouts will upgrade into Horsemen. However, the Harappan EU, the Runners, are also of the unit family "Scouts", but of a higher level than the generic Scouts, so generic Scouts will upgrade into Runners if you're playing as the Harappans.

Enchanteur
Enchanteur @enchanteur

Hi, how to add custom pics ? We can do that now, but your guide isn't updated.
If you can provide this into the tutorial.... Thaaaaaaaaanks!!!

Uncle2fire
Uncle2fire @uncle2fire

I'm planning to update the guide soon, but for now, to add art, import it to the project (Assets>Import New Asset) and put it in the Resources folder. Then add a reference to it in the UIMapper file for the unit/district/culture/etc. you want it to represent in-game. That's it :)

You might have to experiment with various sizes, and if you don't use the same dimensions as the in-game art there can be stretching or distortions in the imported art. You can check the dimensions of in-game art by opening the reference in the UIMapper file and looking at the preview of the art. I would recommend uploading PNG files, and using transparencies.

Enchanteur
Enchanteur @enchanteur

Hi, I'm a bit late to answer. Since then, I found it by chance. I can say when size is 360x360, it's better to use rather something like 720x720 and set high quality. Else the game blur a lot the picture. I have some small issues with custom pics in city view (you can see that in DeepSea). I rebuild the exa or square with a graphic tool because I don't know to do the textures the game use. It's still ok.
I struggle to find a way to use 3d models now. For example, I would like to use Norse EQ for my fishing village, but with a green hex on the map. Look like I can't do that. I even don't know how to reuse the EQ model, because with can just set the visual on "emblematic quarter" without to say what one.

ET
ethansemails @ethansemails

this is so cool! I do have one question, how can I see what the building visuals are before I choose them?

ET
ethansemails @ethansemails

I've had a few problems making a mod. The first was that my emblematic unit does not do any attack and I cannot figure out why? my emblematic quarter also does not physically appear in the game and I cannot figure that out either. My culture doesn't have a photo when you get to evolve too. Any ideas on why this may be?

Uncle2fire
Uncle2fire @uncle2fire

I'll send you a message and hopefully we can work out all the problems you're having!