Skip to content

Map-related JSON files

Terrains.json

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

Each terrain entry can have the following properties:

Attribute Type Optional Notes
name String Required
type Enum Required Land, Water, TerrainFeature, NaturalWonder
occursOn List Default none Only for terrain features and Natural Wonders: The baseTerrain it can be placed on
turnsInto String Default none Only for Natural Wonders: After placing the Natural Wonder its base terrain is changed to this
weight Integer Default 10 Only for Natural Wonders: relative weight it will be picked by the map generator
<stats> Float Optional Per-turn yield or bonus yield for the tile, see Stats
overrideStats Boolean Default false If on, a feature's yields replace any yield from underlying terrain instead of adding to it
unbuildable Boolean Default false If true, nothing can be built here - not even resource improvements
impassable Boolean Default false no unit can enter unless it has a special unique
movementCost Integer Default 1 base movement cost
defenceBonus Float Default 0 combat bonus for units being attacked here
RGB List Integer * 3 Default 'Gold' RGB color for 'Default' tileset display
uniques List Default empty List of effects, see here
civilopediaText List Default empty see civilopediaText chapter

TileImprovements.json

This file lists the improvements that can be constructed or created on a map tile by a unit (any 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 can have the following properties:

Attribute Type Optional Notes
name String Required
terrainsCanBeFoundOn List Default empty Terrains that allow this resource
techRequired String Default none The name of the technology required to build this improvement
uniqueTo String Default none The name of the nation this improvement is unique for
<stats> Float Optional Per-turn bonus yield for the tile, see Stats
turnsToBuild Integer Number of turns a worker spends building this (ignored for 'create' actions)
uniques List Default empty List of effects, see here
shortcutKey String Default none Keyboard binding. At the moment a single character (no function keys or Ctrl combinations)
civilopediaText List Default empty see civilopediaText chapter
  • Tiles with no terrains, but positive turns to build, can be built only when the tile has a resource that names this improvement or special uniques are used. (TODO: missing something?)
  • Tiles with no terrains, and no turns to build, are like great improvements - they're placeable. That means a unit could exist with a 'Can create [this]' unique, and that the improvement will not show in a worker's improvement picker dialog.
  • Removable Terrain features will need to be removed before building an improvement - unless the feature is named in terrainsCanBeFoundOn or the unique "Does not need removal of [terrainFeature]" is used (e.g. Camp allowed by resource).
  • Special improvements: Road, Railroad, Remove *, Cancel improvement order, City ruins, City center, Barbarian encampment - these have special meanings hardcoded to their names.

TileResources.json

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

Note the predefined resource types cannot be altered in 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 can have the following properties:

Attribute Type Optional Notes
name String Required
resourceType String Default Bonus Bonus, Luxury or Strategic
terrainsCanBeFoundOn List Default empty Terrains that allow this resource
<stats> Float Optional Per-turn bonus yield for the tile, see Stats, can be repeated
improvement String Default empty The improvement (TileImprovements.json) for this resource
improvementStats Object Default empty The additional yield when improved as sub-object with one or more Stats
revealedBy String Default empty The technology name required to see, work and improve this resource
unique String Default empty Effects, see here - at the moment only one unique may be added
civilopediaText List Default empty see civilopediaText chapter

Ruins.json

Link to original

This file contains the possible rewards ancient ruins give. It is not required, 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 properties:

Attribute Type Optional 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) defaults to 1 Weight this reward should have. Higher weights result in a higher chance of it being chosen*
uniques List of Strings defaults to none [uniques]Uniques#one-time-effect) or uniques 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.
excludedDifficulties List of Strings defaults to None A list of all difficulties on which this reward may not be awarded

The exact algorithm for choosing a reward is the following:

  • Create a list of all possible rewards, with rewards with a higher weight appearing multiple times. 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"
  • "Hidden when religion is disabled"
  • "Hidden after a great prophet has been earned"

Tileset-specific json

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 Optional Notes
useColorAsBaseTerrain Boolean Default true ? WIP
unexploredTileColor Color Default Dark Gray {"r":0.25,"g":0.25,"b":0.25,"a":1}
fogOfWarColor Color Default Black {"r":0,"g":0,"b":0,"a":1}
ruleVariants List Default empty see below

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.

Stats

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

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

If an object carries general stats, any combination (or none) of these can be specified. For specialized stats, they might come as sub-object in a named field. Example:

        "gold": 2,
        "improvement": "Quarry",
        "improvementStats": { "gold": 1, "production": 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 😁.