Back to Unciv

Civilization-related JSON files

docs/Modders/Mod-file-structure/2-Civilization-related-JSON-files.md

4.20.442.7 KB
Original Source

Civilization-related JSON files

Beliefs.json

link to original

This file contains the beliefs that can be chosen for religions in your mod.

Each belief has the following structure:

AttributeTypeDefaultNotes
nameStringRequired
typeEnumRequiredType of belief. Value must be Pantheon, Founder, Follower or Enhancer
uniquesList of StringsemptyList of unique abilities this belief adds to cities following it
civilopediaTextListemptySee civilopediaText chapter

Buildings.json

link to original

This file contains all the buildings and wonders you want to use in your mod.

Each building has the following structure:

AttributeTypeDefaultNotes
nameStringRequired
costInteger-1Amount of production required to build the building. If -1, the buildingCost from requiredTech column is used
<stats>Float0Per-turn yield produced by the building
maintenanceInteger0Maintenance cost of the building
isWonderBooleanfalseWhether this building is a global wonder
isNationalWonderBooleanfalseWhether this building is a national wonder
requiredBuildingStringnoneA building that has to be built before this building can be built. Must be in Buildings.json
requiredTechStringnoneThe tech that should be researched before this building may be built. Must be in Techs.json
requiredResourceStringnoneThe resource that is consumed when building this building. Must be in TileResources.json
requiredNearbyImprovedResourcesList of StringsemptyThe building can only be built if any of the resources in this list are within the borders of this city and have been improved. Each resource must be in TileResources.json
replacesStringnoneThe name of a building that should be replaced by this building. Must be in Buildings.json
uniqueToStringnoneIf supplied, only the nation with this name can build this building. Must be in Nations.json
cityStrengthInteger0Strength bonus the city in which this building is built receives
cityHealthInteger0Health bonus the city in which this building is built receives
hurryCostModifierInteger0When this building is bought using gold or faith, the price is increased by this much percent
quoteStringnoneIf this building is a (national) wonder, this string will be shown on the completion popup
uniquesList of StringsemptyList of unique abilities this building has
replacementTextForUniquesStringnoneIf provided, this string will be shown instead of all of the uniques
percentStatBonusObjectnonePercentual bonus for stats provided by the building. Same format as specialized stats (numbers are in percent. i.e. [30] represents 30% bonus to a stat)
greatPersonPointsObjectnoneGreat person points by this building generated per turn. Valid keys are the names of units (Great Scientist, Warrior, etc.), valid values are Integers
specialistSlotsObjectnoneSpecialist slots provided by this building. Valid keys are the names of specialists (as defined in Specialists.json), valid values are Integers, the amount of slots provided for this specialist
civilopediaTextListemptySee civilopediaText chapter

Nations.json

Link to original

This file contains all the nations and city states, including Barbarians and Spectator.

Each nation has the following structure:

AttributeTypeDefaultNotes
nameStringRequired
leaderNameStringnoneOmit only for city states! If you want LeaderPortraits, the image file names must match exactly, including case
styleStringnoneModifier appended to pixel unit image names
cityStateTypeStringnoneDistinguishes major civilizations from city states (must be in CityStateTypes.json)
startBiasList of stringsemptyZero or more of: terrainFilter or "Avoid [terrainFilter]". 1
preferredVictoryTypeStringNeutralThe victory type major civilizations will pursue (need not be specified in VictoryTypes.json)
personalityStringnoneThe name of the personality specified in Personalities.json
favoredReligionStringnoneThe religion major civilization will choose if available when founding a religion. Must be in Religions.json
startIntroPart1StringnoneIntroductory blurb shown to Player on game start... 2
startIntroPart2Stringnone... second paragraph. NO "TBD"!!! Leave empty to skip that alert.
declaringWarStringnoneAnother greeting, voice hook supported 2
attackedStringnoneAnother greeting, voice hook supported 2
defeatedStringnoneAnother greeting, voice hook supported 2
denouncedStringnoneAnother greeting, voice hook supported 2
neutralDenouncingStringnoneGreeting shown in popup when a civ denounces another civ, voice hook supported 2
hateDenouncingStringnoneGreeting shown in popup when an AI denounces its enemy, voice hook supported 2
introductionStringnoneAnother greeting, voice hook supported 2
neutralHelloStringnoneAnother greeting, voice hook supported 2
hateHelloStringnoneAnother greeting, voice hook supported 2
tradeRequestStringnoneAnother greeting, voice hook supported 2
declaringFriendshipStringnoneAnother greeting, voice hook supported 2
neutralRejectingDemandStringnoneAnother greeting, the leader will say this after rejecting your demand, voice hook supported 2
hateRejectingDemandStringnoneAnother greeting, the leader will say this after rejecting your demand, voice hook supported 2
innerColorList of 3× IntegerblackRGB color for outer ring of nation icon
outerColorList of 3× IntegerRequiredRGB color for inner circle of nation icon
uniqueNameStringnoneDecorative name for the special characteristic of this nation
uniqueTextStringnoneReplacement text for "uniques". If empty, uniques are listed individually
uniquesListemptyList of unique abilities this civilisation has
citiesListemptyCity names used sequentially for newly founded cities. Required for major civilizations and city states
civilopediaTextListemptySee civilopediaText chapter

Personalities.json

Link to original

This file contains all Personalities for computer players.

Each personality has the following structure:

AttributeTypeDefaultNotes
nameStringRequired
preferredVictoryTypeStringNeutralThe victory type major civilizations will pursue (need not be specified in VictoryTypes.json)
<stats>, <behaviors>Float5Amount of focus on the stat the computer player will have. Typically ranges from 0 (no focus) to 10 (double focus)
prioritiesObjectnonePriorities for each policy branch 3
uniquesListemptyList of unique abilities this personality has
civilopediaTextListemptySee civilopediaText chapter

The object maps policy branches to priority values for the major civilization using the policy branches name and integers. Any branches not listed have a default value of 0

The code below is an example of a valid "priorities" definition.

"priorities": {
    "Tradition": 30,
    "Liberty": 20,
    "Honor": 10
}

Personality Behaviours

Personality Behaviours are not fully implemented yet and their names may change. Using them before they are ready might make the mod unplayable. The following is WIP - read on at you own peril!

There are 7 defining behaviours that influence an AI Civilization's behaviour. A higher value means they will behave more like the attribute.

  • Military: Determines how much does the civilization prioritizes building a military, but not necessarily using it. A higher value means more focus on military, a lower value means it is likely more peaceful.
  • Agressive: Determines how the civilization uses its units while at war and which buildings they prioritise. A higher value means the civilization is more aggressive, a lower value means it is more defensive.
  • War: Determines how likely the civilization is to declare war. A 0 means the civ won't declare war at all.
  • Commerce: Determines how open the civilization is to trade, value open borders, and liberate city-states. A higher value means more trading frequency even with civilizations they don't like.
  • Diplomacy: Determines how likely the civilization is to declare friendship, a defensive pact, peace treaty, or other diplomatic actions.
  • Loyal: Determines how much the civilization values a long-lasting alliance, how willing they are to join wars with them, and how much they despise other unreliable civilizations.
  • Expansion: Determines how focused the civilization is on founding or capturing new cities. A lower value means they might focus on culture more.
  • DenounceWillingness: Determines how eager the civilization is to denounce other civs.

CityStateTypes.json

Link to original

This optional file is used for defining the types of city states. These types determine the benefits major civilizations get when they befriend or ally the city state with influence. For base ruleset Mods, if the file is ommitted or contains an empty list, all types from the Vanilla ruleset are automatically added: Cultured, Maritime, Mercantile, Militaristic, Religious.

Each city state type has the following structure:

AttributeTypeDefaultNotes
nameStringRequired
friendBonusUniquesList of StringsemptyList of unique abilities granted to major civilizations when friends with this city state
allyBonusUniquesList of StringsemptyList of unique abilities granted to major civilizations when allied to city state
colorList of 3× Integer[255, 255, 255]RGB color of text in civilopedia

Policies.json

Link to original

This file contains all the available social policies that can be "bought" with culture.

They are organized in 'branches', each branch has an 'opener', one or more 'member' policies, and a 'finisher'. Therefore this file is organized using two levels - branch and member policy.

The properties of the 'opener' are defined with the branch level, while the 'finisher' is an entry on the member level which must be named as branch name + " Complete", case sensitive. For example, the finisher of a policy branch "Tradition" will have the name "Tradition Complete".

Branch structure

Each policy branch has the following structure:

AttributeTypeDefaultNotes
nameStringRequired
eraStringRequiredUnlocking era as defined in Eras.json
prioritiesObjectnonePriorities for each victory type, see here
uniquesListemptyList of unique abilities this policy branch grants upon adopting it
civilopediaTextListemptySee civilopediaText chapter
policiesListemptyList of member policies and branch 'finisher' - pay attention to the nesting of {} and []

Member policy structure

AttributeTypeDefaultNotes
nameStringRequired
rowIntegerRequiredPlacement in UI, each unit approximately half the icon size
columnIntegerRequiredPlacement in UI, each unit approximately half the icon size
requiresListemptyList of prerequisite policy names
uniquesListemptyList of unique abilities this policy member grants upon adopting it
civilopediaTextListemptySee civilopediaText chapter

Branch finisher structure

AttributeTypeDefaultNotes
nameStringRequired
uniquesListemptyList of unique abilities this finisher grants upon adopting all the policy members in the branch
civilopediaTextListemptySee civilopediaText chapter

Branch priorities

The "priorities" object defines the priority major civilizations' AI give to a policy branch. The AI chooses the policy branch with the highest sum of the peferred victory type listed here and the number flisted in the personality's priority. If two or more candidate branches have the same priority, the AI chooses a random branch among the candidates.

The object maps victory types to priority values for the major civilization using strings and integers. If the preferred victory type is not specified, the default priority value is set to 0.

The code below is an example of a valid "priorities" definition.

json
"priorities": {
"Neutral": 0,
"Cultural": 10,
"Diplomatic": 0,
"Domination": 0,
"Scientific": 10
}

Quests.json

Link to original

This file contains the quests that may be given to major civilizations by city states.

Each quest has the following structure:

AttributeTypeDefaultNotes
nameStringRequiredDefines criteria of quest, see below
descriptionStringRequiredDescription of the quest shown to players. Can add extra information based on name, see below
typeEnumIndividualIndividual or Global
influenceFloat40Influence reward gained on quest completion
durationInteger0Maximum number of turns to complete the quest. If 0, there is no turn limit
minimumCivsInteger1Minimum number of Civs needed to start the quest. It is meaningful only for type = Global
weightForCityStateTypeObjectnoneRelative weight multiplier to this quest for each city state type or city state personality (Friendly, Neutral, Hostile, Irrational), see below

Quest name

The name of the quest defines the criteria for the quest. If they are not defined in the predefined enum, they will have no behavior. In the description, square brackets [] in the description of the quest is replaced with extra information (except for Invest). The list of predefined quest names are as follows:

NameCriteriaAdditional info
RouteConnect the city state to the major civilization's capital using roads or railways
Clear Barbarian CampDestroy the target barbarian camp
Construct WonderConstruct the target wondertarget wonder
Connect ResourceConnect the target resource to the major civilization's trade networktarget tileResource
Acquire Great PersonAcquire the target great persontarget greatPerson
Conquer City StateDefeat the target city statetarget cityState
Find PlayerMeet the target major civilizationtarget civName
Find Natural WonderFind the target natural wondertarget naturalWonder
Give GoldDonate gold to the city state (amount does not matter)civName "bully" for city state
Pledge to ProtectPledge to protect city statecivName "bully" for city state
Contest CultureBe the major civilization with the highest increase to culture during the durationmajor civilization's cultureGrowth
Contest FaithBe the major civilization with the highest increase to faith during the durationmajor civilization's faithGrowth
Contest TechnologyBe the major civilization with the most technologies researched during the durationmajor civilization's techsResearched
InvestDonating gold yield extra Influence based on value providedIMPORTANT: value in square brackets is the extra influence in percent. i.e. [50] means 50%
Bully City StateDemand tribute from the target city statetarget city state
Denounce CivilizationDenounce the major civilization which "bullied" the city statecivName "bully" for city state
Spread ReligionSpread major civilization's religion to the city statemajor civilization's religionName

Quest weight

The "weightForCityStateType" object determines the quest's weight multiplier. When a city state initiates a quest, the initial weight is 1, and it is multiplied by values based on city state type and personality (Friendly, Neutral, Hostile, Irrational). The AI then randomly selects a quest based on the final weighted values.

The object maps city state type and personality to the weight multipliers for the city state using strings to floats. If the preferred victory type is not found, the default multiplier is 1.

The code below is an example of a valid "weightForCityStateType" definition. In this case, a friendly militaristic city state will be 0.4 (0.2 × 2) times as likely to pick this quest than a quest with weight 1.

json
"weightForCityStateType": {
"Hostile": 2,
"Friendly": 0.2,
"Militaristic": 2
}

Religions.json

Link to original

This is just a list of Strings specifying all predefined religion names. Corresponding icons must exist, that's all to it. After all, they're just containers for beliefs.

Specialists.json

Link to original

This file should contain a list of all possible specialists that citizens can be assigned to.

Each specialist has the following structure:

AttributeTypeDefaultNotes
nameStringRequired
<stats>Float0Per-turn yield produced by the specialist
colorList of 3× IntegerRequiredColor of the image for this specialist
greatPersonPointsObjectnoneGreat person points generated by this specialist per turn. Valid keys are the names of units (Great Scientist, Warrior, etc.), valid values are Integers

Techs.json

Link to original

This file contains all the technologies that can be researched with science. It is organized into an outer list of 'columns', which in turn contains one or more tech each.

Column structure

Each tech column has the following structure:

AttributeTypeDefaultNotes
columnNumberIntegerRequiredHorizontal placement in the Tech Tree
eraStringRequiredDetermines era reached after researching any technologies in this column. Must be in Eras.json
techCostInteger0Default cost of the techs in this column
buildingCostIntegerRequiredDefault cost of buildings requiring this tech
wonderCostIntegerRequiredDefault cost of wonders requiring this tech
techsListRequiredList of techs - pay attention to the nesting of {} and []

Tech structure

AttributeTypeDefaultNotes
nameStringRequired
rowInteger0Vertical placement in the Tech Tree, must be unique per column
costIntegerColumn techCostThe amount of science required to research this tech
prerequisitesList of StringsemptyA list of the names of techs that are prerequisites of this tech. Only direct prerequisites are necessary
quoteStringnoneA nice story presented to the player when they research this tech
uniquesList of StringsemptyList of unique abilities this technology grants
civilopediaTextListemptySee civilopediaText chapter

Footnotes

  1. A "Coast" preference (unless combined with "Avoid") is translated to a complex test for coastal land tiles, tiles next to Lakes, river tiles or near-river tiles, and such civs are processed first. Other startBias entries are ignored in that case. Other positive (no "Avoid") startBias are processed next. Multiple positive preferences are treated equally, but get no "fallback". Single positive startBias can get a "fallback" region if there is no (or no more) region with that primary type: any leftover region with as much of the specified terrain as possible will do. Multiple "Avoid" entries are treated equally (and reduce chance for success - if no region is left avoiding all specified types that civ gets a random one). When combining preferred terrain with "Avoid", the latter takes precedence, and preferred terrain only has minor weight when choosing between regions that are not of a type to avoid. These notes are only valid when playing on generated maps, loaded maps from map editor get no " regions" and startBias is processed differently (but you can expect single-entry startBias to work best).

  2. See Supply Leader Voices 2 3 4 5 6 7 8 9 10 11 12 13 14

  3. Similar to policy priorites The "priorities" object defines the priority major civilizations' AI give to a policy branch. The AI chooses the policy branch with the highest number for their preferred victory type. If two or more candidate branches have the same priority, the AI chooses a random branch among the candidates.