Miscellaneous JSON files

Difficulties.json

Link to original

This optional file defines the difficulty levels a player can choose when starting a new game.

Base ruleset Mods can omit the file or supply an empty list, even though at least one difficulty is mandatory, in which case they inherit the ones from the Vanilla ruleset.

Each difficulty level has the following structure:

Eras.json

Link to original

This file should contain all the era's you want to use in your mod.

Each era can have the following attributes:

Speeds.json

Link to original

This optional file should contain all the speeds you want to use in your mod.

Base ruleset Mods can omit the file or supply an empty list, even though at least one game speed is mandatory, in which case they inherit the ones from the Vanilla ruleset.

Each speed can have the following attributes:

Time interval per turn

The "turns" attribute defines the number of years passing between turns. The attribute consists of a list of objects, each having 2 required attributes: "yearsPerTurn" (Float) and "untilTurn" (Integer)

For each row, "yearsPerTurn" is applied up to the "untilTurn"-1 to "untilTurn" step. The last "untilTurn" in the list is ignored for year calculation, that is, if a game passes that turn number, years continue to increment by the "yearsPerTurn" of the last entry. However, this is used when starting a game in a later Era: Era.startPercent is relative to the last "untilTurn".

The code below is an example of a valid "turns" definition and it specifies that the first 50 turns of a game last for 60 years each, then the next 30 turns (and any played after the 80th) last for 40 years each.

"turns": [
    {"yearsPerTurn": 60, "untilTurn":  50},
    {"yearsPerTurn": 40, "untilTurn":  80}
]

Events.json

Events allow users to choose between options of triggers to activate.

You can use text and/or civilopediaText, if both are present both are shown (but why would you?)

Event choices are comprised of:

Here, civilopediaText is shown outside the active Button, before the triggeredUniques.

ModOptions.json

This file is a little different:

• Does not exist in Vanilla ruleset
• Is entirely optional but will be created after downloading a mod

Note that this file controls declarative mod compatibility (Work in progress) - e.g. there's uniques to say your Mod should only or never be used as 'Permanent audiovisual mod'. Incompatibility filtering works so far between extension and base mods, but feel free to document known extension-to-extension incompatibilities using the same Unique now. Stay tuned!

The file can have the following attributes, not including the values Unciv sets automatically:

The values normally set automatically from github metadata are:

To clarify: When your Mod is distributed via github, including these in the Mod repo has no effect. However, when a Mod is distributed without a github repository, these values can and should be set by the author in the distributed ModOptions.json.

ModConstants

Stored in ModOptions.constants, this is a collection of constants used internally in Unciv. This is the only structure that is merged field by field from mods, not overwritten, so you can change XP from Barbarians in one mod and city distance in another. In case of conflicts, there is no guarantee which mod wins, only that default values are ignored.

Legend:

UnitUpgradeCost

These values are not merged individually, only the entire sub-structure is.

The formula for the gold cost of a unit upgrade is (rounded down to a multiple of roundTo): ( max((base + perProduction * (new_unit_cost - old_unit_cost)), 0) * (1 + eraNumber * eraMultiplier) * civModifier ) ^ exponent With civModifier being the multiplicative aggregate of "[relativeAmount]% Gold cost of upgrading" uniques that apply.

GlobalUniques.json

link to original

GlobalUniques defines uniques that apply globally. e.g. Vanilla rulesets define the effects of Unhappiness here.

Base ruleset Mods can omit the file, in which case they inherit the ones from the Vanilla ruleset. Alternatively, they can supply a file with an empty object ({}), meaning that no global Uniques exist for that Mod.

It has the following structure:

When extension rulesets define GlobalUniques, all uniques are merged. At the moment there is no way to change/remove uniques set by a base mod.

Tutorials.json

link to original

Note a Base Ruleset mod can define a "welcome page" here by adding a "Tutorial" with a name equal to the name of the mod! As an exception to the general rule, this file in a Base Ruleset mod will not replace the default, but add to it like extension mods do. Also, place it under <mod>/jsons/ normally even if the original is found one level above the vanilla jsons.

Each tutorial has the following structure:

If an entry contains both steps and civilopediaText attributes, the civilopediaText is shown first. Tutorials shown as Popup can show an show an external image (not part of the texture atlases) if there is an image unter ExtraImages (directly under assets or the Mod folder) having the same name. This is searched for, meaning the mod defining the Tutorial is irrelevant, mods can override builtin ExtraImages, and case sensitivity depends on the OS.

VictoryTypes.json

link to original

These files contain which victories this mod provides, and what milestones must be reached for someone to win a victory. Most of the file contains of strings that are shown to the user in the victory screen, with the rest being the requirements for winning.

Base ruleset Mods can omit the file or supply an empty list, even though at least one victory type is mandatory, in which case they inherit the ones from the Vanilla ruleset.

Each victory have the following structure:

Milestones

Currently the following milestones are supported:

Civilopedia text

Any 'thing' defined in json and listed in the Civilopedia can supply extra text, specifically for the Civilopedia. This can be used to explain special considerations better when the automatically generated display is insufficient, or for 'flavour', background stories and the like. Such text can be formatted and linked to other Civilopedia entries, within limits.

An example of the format is:

"civilopediaText": [
    { "text": "Ancient ruins provide a one-time random bonus when explored" },
    { "separator": true },
    {
        "text": "This line is red and links to the Scout including icons",
        "link": "Unit/Scout",
        "color": "red"
    },
    {
        "text": "A big fat header sporting a golden star",
        "header": 1,
        "starred": true,
        "color": "#ffeb7f"
    },
],

List of attributes - note not all combinations are valid:

The lines from json will 'surround' the automatically generated lines such that the latter are inserted just above the first json line carrying a link, if any. If no json lines have links, they will be inserted between the automatic title and the automatic info. This method may, however, change in the future.

Note: text now also supports inline color markup. Insert «color» to start coloring text, «» to stop. color can be a name or 6/8-digit hex notation like #ffa040 (different from the color attribute notation only by not allowing 3-digit codes, but allowing the alpha channel). Effectively, the «» markers are replaced with [] after translation and then passed to gdx markup language.

Note: Using an ExtraImages folder in a mod was not working until version 4.11.5

RGB colors list

Certain objects can be specified to have its own unique color. The colors are defined by a list of 3× Integer in this order: red, green, blue. The range of color is from [0, 0, 0] (black) to [255, 255, 255] (white).

Note: The default of some objects are gdx color classes. The values of the constants are as follows: