mirrors/Unciv
1
0
Fork 0
mirror of https://github.com/yairm210/Unciv.git synced 2025-07-15 18:28:42 +07:00
Code Issues Packages Projects Releases Wiki Activity

Modders wiki updating (#10688)

Browse Source 
* xpForNewUnits is not used anymore

* Adding links to json files

* Redid some tables (TODO)

* Deprecate cannotBeBuiltWith

* Update 2-Civilization-related-JSON-files.md

Standardised uniques link and description
Miscellaneous changes to grammar to be consistent

* First round of amendment

Fixed up some links
Made grammar more consistent
Removed deprecated `effect` from ModOptions.json
Added CityStateTypes.json

* Second round of amendment
Made grammar more consistent
Changed `Optional` header to `Default`
Removed tabs from json code
Changed all stats to a `<stats>`

* Undid accidental replacement

* Undid accidental replacement

* Made list more consistent

* Rewrote policy branch and turns in eras.json

* Third round of amendment

Split stats
Fixed a couple of stuff idk tbh

* Added stats

* Added nationFilter

* Final amendment

* Adding markdown table format based on suggestion

* Fixed errors/suggestions based on reviews

changed building.cost default to be -1
added footnotes for improvements instead of list
removed faith from unit.hurryCostModifier
removed assosciation of nationFilter with civFilter
This commit is contained in:
Why-not-now
2023-12-29 04:06:40 +08:00
committed by GitHub
parent 278288442b
commit 54afc5c350
6 changed files with 666 additions and 525 deletions
Download Patch File Download Diff File Expand all files Collapse all files

204
docs/Modders/Mod-file-structure/3-Map-related-JSON-files.md
View File

@ -2,101 +2,107 @@
## Terrains.json
This file lists the base terrains, terrain features and natural wonders that can appear on the map.
[Link to original](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Vanilla/Terrains.json)
Each terrain entry can have the following properties:
This file contains the base terrains, terrain features and natural wonders that can appear on the map.
| Attribute | Type | Optional | Notes |
| --------- | ---- | -------- | ----- |
| name | String | Required | |
Each terrain entry has the following structure:
| Attribute | Type | Default | 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](#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](../uniques.md#terrain-uniques) |
| civilopediaText | List | Default empty | see [civilopediaText chapter](5-Miscellaneous-JSON-files.md#civilopedia-text) |
| 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: the base terrain is changed to this after placing the Natural Wonder |
| weight | Integer | 10 | Only for NaturalWonder: _relative_ weight of being picked by the map generator |
| [`<stats>`](#general-stat) | 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](5-Miscellaneous-JSON-files.md#rgb-colors-list) | Gold | RGB color for 'Default' tileset display |
| uniques | List of Strings | empty | List of [unique abilities](../uniques) this terrain has |
| civilopediaText | List | empty | See [civilopediaText chapter](5-Miscellaneous-JSON-files.md#civilopedia-text) |
## 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).
[Link to original](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Vanilla/TileImprovements.json)
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 can have the following properties:
Each improvement has the following structure:
| Attribute | Type | Optional | Notes |
| --------- | ---- | -------- | ----- |
| name | String | Required | |
| terrainsCanBeFoundOn | List | Default empty | [Terrains](#terrainsjson) 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](#stats) |
| turnsToBuild | Integer | | Number of turns a worker spends building this (ignored for 'create' actions) |
| uniques | List | Default empty | List of effects, [see here](../Unique-parameters.md#improvement-uniques) |
| 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](5-Miscellaneous-JSON-files.md#civilopedia-text) |
| 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](#terrainsjson) |
| techRequired | String | none | The name of the technology required to build this improvement |
| uniqueTo | String | none | The name of the nation this improvement is unique for |
| [`<stats>`](#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](../uniques) 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](5-Miscellaneous-JSON-files.md#civilopedia-text) |
- 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.
[^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](#tileresourcesjson) 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](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Vanilla/TileResources.json)
This file lists the resources that a map tile can have.
Note the predefined resource _types_ cannot be altered in json.
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 can have the following properties:
| Attribute | Type | Optional | Notes |
| --------- | ---- | -------- | ----- |
| name | String | Required | |
| resourceType | Enum | Default Bonus | Bonus, Luxury or Strategic |
| terrainsCanBeFoundOn | List | Default empty | [Terrains](#terrainsjson) that allow this resource |
| `<stats>` | Float | Optional | Per-turn bonus yield for the tile, see [Stats](#stats), can be repeated |
| improvement | String | Default empty | The improvement ([TileImprovements.json](#tileimprovementsjson)) for this resource |
| improvementStats | Object | Default empty | The additional yield when improved as sub-object with one or more [Stats](#stats) |
| revealedBy | String | Default empty | The technology name required to see, work and improve this resource |
| unique | String | Default empty | Effects, [see here](../Unique-parameters.md#resource-uniques) - at the moment only one unique may be added |
| civilopediaText | List | Default empty | see [civilopediaText chapter](5-Miscellaneous-JSON-files.md#civilopedia-text) |
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](#terrainsjson) |
| [`<stats>`](#stats) | Integer | 0 | Per-turn bonus yield for the tile |
| improvementStats | Object | none | The additional yield when improved, see [specialized stats](3-Map-related-JSON-files.md#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](#tileimprovementsjson) |
| improvement | String | none | The improvement required to obtain this resource. Must be in [TileImprovements.json](#tileimprovementsjson) (redundant due to `improvedBy`) |
| unique | List of Strings | empty | List of [unique abilities](../uniques) this resource has |
| civilopediaText | List | empty | See [civilopediaText chapter](5-Miscellaneous-JSON-files.md#civilopedia-text) |
## Ruins.json
[Link to original](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Vanilla/Ruins.json)
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.
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 properties:
Each of the objects in the file represents a single reward you can get from ruins. It has the following structure:
| 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](../Unique-parameters.md#one-time-effect-units) 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 |
| 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](../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 (may be outdated) |
| excludedDifficulties | List of Strings | empty | A list of all difficulties on which this reward may _not_ be awarded |
The exact algorithm for choosing a reward is the following:
[^E]: 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.
- 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.
<!-- (need to update) -->
| Unique | Parameters |
| ------ | ---------- |
@ -111,58 +117,72 @@ Some of the rewards ruins can give will have results that are not deterministic
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"
- "Only available after [amount] turns"
- "Hidden when religion is disabled"
- "Hidden after a great prophet has been earned"
## Tileset-specific json
## [Tileset-specific json](../Creating-a-custom-tileset.md)
[Link to original FantasyHex](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/TileSets/FantasyHex.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 | Default value | Notes |
| --------- | ---- | -------- | ----- |
| Attribute | Type | Default | Notes |
| --------- | ---- | ------- | ----- |
| [useColorAsBaseTerrain](../Creating-a-custom-tileset.md#useColorAsBaseTerrain) | Boolean | false | |
| [useSummaryImages](../Creating-a-custom-tileset.md#useSummaryImages) | Boolean | false | |
| [unexploredTileColor](../Creating-a-custom-tileset.md#unexploredTileColor) | Color | Dark Gray | `{"r":0.25,"g":0.25,"b":0.25,"a":1}` |
| [fogOfWarColor](../Creating-a-custom-tileset.md#fogOfWarColor) | Color | Black | `{"r":0,"g":0,"b":0,"a":1}` |
| [fallbackTileSet](../Creating-a-custom-tileset.md#fallbackTileSet) | String | "FantasyHex" | null to disable |
| [tileScale](../Creating-a-custom-tileset.md#tileScale) | Float | 1.0 | |
| [tileScales](../Creating-a-custom-tileset.md#tileScales) | Dictionary | empty | |
| [ruleVariants](../Creating-a-custom-tileset.md#ruleVariants) | Dictionary | empty | see below |
| [tileScale](../Creating-a-custom-tileset.md#tileScale) | Float | 1.0 | The scale of all tiles. Can be used to increase or decrease the size of every tile |
| [tileScales](../Creating-a-custom-tileset.md#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](../Creating-a-custom-tileset.md#ruleVariants) | Object | empty | [See here](#layering-images) |
### Layering images
ruleVariants control substitutions when layering images for a tile, they are list looking like:
```json
"ruleVariants": {
"Grassland+Forest": ["Grassland", "GrasslandForest"],
"Plains+Forest": ["Plains", "PlainsForest"],
"Plains+Jungle": ["Plains", "PlainsJungle"],
// . . .
}
"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*).
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.
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. They can be one of the following:
Terrains, features, resources and improvements may list yield statistics. The statistics can be one of the following:
- production
- food
- gold
- science
- culture
- happiness
- faith
- 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:
### 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:
```json
"gold": 2,
"improvement": "Quarry",
"improvementStats": { "gold": 1, "production": 1 },
"gold": 2,
"improvement": "Quarry",
```
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 😁.
### 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:
```json
"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 😁.