Skip to content

Map-related JSON files

Terrains.json

Link to original

This file contains the base terrains, terrain features and natural wonders that can appear on the map.

Each terrain entry has the following structure:

Attribute Type Default Notes
name String Required [^A]
type Enum Required Land, Water, TerrainFeature, NaturalWonder [^B]
occursOn List of Strings none Only for terrain features and Natural Wonders: The baseTerrain it can be placed on
turnsInto String none Only for NaturalWonder: optional mandatory base terrain [^C]
weight Integer 10 Only for NaturalWonder: relative weight of being picked by the map generator
<stats> Float 0 Per-turn yield or bonus yield for the tile
overrideStats Boolean false If true, a feature's yields replace any yield from underlying terrain instead of adding to it
unbuildable Boolean false If true, nothing can be built here - not even resource improvements
impassable Boolean false No unit can enter unless it has a special unique
movementCost Integer 1 Base movement cost
defenceBonus Float 0 Combat bonus for units being attacked here
RGB List of 3× Integer Gold RGB color for 'Default' tileset display
uniques List of Strings empty List of unique abilities this terrain has
civilopediaText List empty See civilopediaText chapter

[^A]: Some names have special meanings. Grassland is used as fallback in some cases - e.g. Civilopedia prefers to displays a TerrainFeature on top of it, unless occursOn is not empty and does not contain it. River is hardcoded to be used to look up a Stats unique to determine the bonuses an actual River provides (remember, rivers live on the edges not as terrain). River should always be a TerrainFeature and have the same uniques the one in the vanilla rulesets has - if you change that, expect surprises. [^B]: A base ruleset mod is always expected to provide at least one Land and at least one Water terrain. We do not support Land-only or Water-only mods, even if they might be possible to pull off. [^C]: If set, the base terrain is changed to this after placing the Natural Wonder, and terrain features cleared. Otherwise, terrain features are reduced to only those present in occursOn.

TileImprovements.json

Link to original

This file lists the improvements that can be constructed or created on a map tile by a unit having the appropriate unique.

Note that improvements have two visual representations - icon and pixel graphic in the tileset. Omitting the icon results in a horribly ugly user interface, while omitting tileset graphics will just miss out on an optional visualization. If you provide a pixel graphic for FantasyHex, please be aware of the layering system and the ruleVariants in the tileset json. A single graphic may suffice if it has lots of transparency, as it will be drawn on top of all other terrain elements.

Each improvement has the following structure:

Attribute Type Default Notes
name String Required [^A]
terrainsCanBeBuiltOn List of Strings empty Terrains that this improvement can be built on [^B]. Removable terrain features will need to be removed before building an improvement [^C]. Must be in Terrains.json
techRequired String none The name of the technology required to build this improvement
replaces String none The name of a improvement that should be replaced by this improvement. Must be in TileImprovements.json
uniqueTo String none The name of the nation this improvement is unique for
<stats> Integer 0 Per-turn bonus yield for the tile
turnsToBuild Integer -1 Number of turns a worker spends building this. If -1, the improvement is unbuildable [^D]. If 0, the improvement is always built in one turn
uniques List of Strings empty List of unique abilities this improvement has
shortcutKey String none Keyboard binding. Currently, only a single character is allowed (no function keys or Ctrl combinations)
civilopediaText List empty See civilopediaText chapter

[^A]: Special improvements: Road, Railroad, Remove *, Cancel improvement order, City ruins, City center, Barbarian encampment - these have special meanings hardcoded to their names. [^B]: Improvements with an empty terrainsCanBeBuiltOn list and positive turnsToBuild value can only be built on resources with improvedBy or improvement that contains the corresponding improvement. [^C]: The removal of terrain features is optional if the feature is named in terrainsCanBeBuiltOn or the unique Does not need removal of [tileFilter] is used (e.g. Camp allowed by resource). [^D]: They can still be created with the UnitAction unique Can instantly construct a [improvementFilter] improvement.

TileResources.json

Link to original

This file lists the resources that a map tile can have.

Note the predefined resourceType enum cannot be altered in a json.

Note also that resources have two visual representations - icon and pixel graphic in the tileset. Omitting the icon results in a horribly ugly user interface, while omitting tileset graphics will miss out on a visualization on the map. If you provide a pixel graphic for FantasyHex, please be aware of the layering system and the ruleVariants in the tileset json. A single graphic may suffice if it has lots of transparency, as it will be drawn on top of terrain and features but below an improvement - if the single improvement graphic exists at all.

Each resource has the following structure:

Attribute Type Default Notes
name String Required
resourceType Enum Bonus Bonus, Luxury or Strategic
terrainsCanBeFoundOn List of Strings empty Terrains that this resource can be found on. Must be in Terrains.json
<stats> Integer 0 Per-turn bonus yield for the tile
improvementStats Object none The additional yield when improved, see specialized stats
revealedBy String none The technology name required to see, work and improve this resource
improvedBy List of strings empty The improvements required for obtaining this resource. Must be in TileImprovements.json
improvement String none The improvement required to obtain this resource. Must be in TileImprovements.json (redundant due to improvedBy)
unique List of Strings empty List of unique abilities this resource has
civilopediaText List empty See civilopediaText chapter

Ruins.json

Link to original

This optional file contains the possible rewards ancient ruins give. If omitted, the default file for the game is used, even in baseRuleSet mods.

Each of the objects in the file represents a single reward you can get from ruins. It has the following structure:

Attribute Type Default Notes
name String Required Name of the ruins. Never shown to the user, but they have to be distinct
notification String Required Notification added to the user when this reward is chosen. If omitted, an empty notification is shown. Some notifications may have parameters, refer to the table below.
weight Integer (≥0) 1 Relative weight this reward is chosen next [^E]
uniques List of Strings empty List of unique abilities that will trigger when entering the ruins. If more than 1 unique is added, the notification will be shown multiple times due to a bug (may be outdated)
excludedDifficulties List of Strings empty A list of all difficulties on which this reward may not be awarded

[^E]: The exact algorithm for choosing a reward is the following:

  • Create a list of all possible rewards. Each reward's frequency in the list corresponds to its weight, a reward with weight one will appear once, a reward with weight two will appear twice, etc.
  • Shuffle this list
  • Try give rewards starting from the top of the list. If any of the uniques of the rewards is valid in this context, reward it and stop trying more rewards.

Notifications

Some of the rewards ruins can give will have results that are not deterministic when writing it in the JSON, so creating a good notification for it would be impossible. An example for this would be the "Gain [50]-[100] [Gold]" unique, which will give a random amount of gold. For this reason, we allow some notifications to have parameters, in which values will be filled, such as "You found [goldAmount] gold in the ruins!". All the uniques which have this property can be found below.

Unique Parameters
Free [] found in the ruins The name of the unit will be filled in the notification, including unique units of the nation
[] population in a random city The name of the city to which the population is added will be filled in the notification
Gain []-[] [] The exact amount of the stat gained will be filled in the notification
[] free random reasearchable Tech(s) from the [] The notification must have placeholders equal to the number of techs granted this way. Each of the names of these free techs will be filled in the notification
Gain enough Faith for a Pantheon The amount of faith gained is filled in the notification
Gain enough Faith for []% of a Great Prophet The amount of faith gained is filled in the notification

Specific uniques

A few uniques can be added to ancient ruin effects to modify when they can be earned. These are:

  • "Only available after [amount] turns"
  • "Only available "
  • "Hidden after a great prophet has been earned"

Tileset-specific json

Link to original FantasyHex

A mod can define new Tilesets or add to existing ones, namely FantasyHex. There is one json file per Tileset, named same as the Tileset, and placed in a subfolder named "TileSets" relative to the other json files. This is called TileSetConfig and has the following structure:

Attribute Type Default Notes
useColorAsBaseTerrain Boolean false
useSummaryImages Boolean false
unexploredTileColor Color Dark Gray {"r":0.25,"g":0.25,"b":0.25,"a":1}
fogOfWarColor Color Black {"r":0,"g":0,"b":0,"a":1}
fallbackTileSet String "FantasyHex" null to disable
tileScale Float 1.0 The scale of all tiles. Can be used to increase or decrease the size of every tile
tileScales Object empty Used by the "Minimal" tileset to scale all its tiles except the base terrain down. Overrides tileScale value for specified terrain
ruleVariants Object empty See here

Layering images

ruleVariants control substitutions when layering images for a tile, they are list looking like:

"ruleVariants": {
    "Grassland+Forest": ["Grassland", "GrasslandForest"],
    "Plains+Forest": ["Plains", "PlainsForest"],
    "Plains+Jungle": ["Plains", "PlainsJungle"],
    // . . .
}

Each line means "if the tile content is this... then combine the following png images". The key part follows a specific order and must match in its entirety, meaning "Plains+Forest" is not valid for "Plains+Forest+Deer", and when it matches no other image layering is done except roads and units (I think - WIP).

When TileSetConfig's for the same Tileset are combined, for the first three properties the last mod wins, while ruleVariants are merged, meaning only an entry with the same key overwrites an earlier entry. (TODO)

Stats

Terrains, features, resources and improvements may list yield statistics. The statistics can be one of the following:

  • production
  • food
  • gold
  • science
  • culture
  • happiness
  • faith

General stat

If an object carries general stat(s), it contains any combination (or none) of the above stats, each mapping to a corresponding number [^1]. For Example:

"gold": 2,
"improvement": "Quarry",

Specialized stats

For specialized stats, they might come as sub-object in a named field. The sub-object contains any combination (or none) of the above stats, each mapping to a corresponding number [^1]. For Example:

"improvement": "Quarry",
"improvementStats": { "gold": 1, "production": 1 },

[^1]: The values are usually integers, though the underlying code supports floating point. The effects are, however, insufficiently tested and therefore -so far- using fractional stats is unsupported. Go ahead and thoroughly test that in a mod and help out with feedback 😁.