AnarchistGamers/Unciv
1
0
Fork 0
mirror of https://github.com/yairm210/Unciv.git synced 2025-08-03 12:37:42 -04:00
Code Issues Packages Projects Releases Wiki Activity

@will-ca: Repo wiki resync. — Requires #5854. (#6024) 

https://github.com/yairm210/Unciv/pull/6024
will-ca 2022-01-24 15:18:16 +00:00
parent 73475b37b2
commit 7f8447c3b4
41 changed files with 2856 additions and 149 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Audiovisual-Mods.md

@ -1,5 +1,5 @@
# Audiovisual Mods
- [The 'Permanent audiovisual mod' feature](#permanent-audiovisual-mod)
- [The 'Permanent audiovisual mod' feature](#permanent-audiovisual-mods)
- [Mods can override built-in graphics](#override-built-in-graphics)
- [Mods can supply additional tilesets - see separate page](./Creating-a-custom-tileset)
- [Mods can supply additional graphics not included in the base game](#supply-additional-graphics)

44
Audiovisual-Mods.mde Normal file

@ -0,0 +1,44 @@
# Audiovisual Mods
- [The 'Permanent audiovisual mod' feature](#permanent-audiovisual-mods)
- [Mods can override built-in graphics](#override-built-in-graphics)
- [Mods can supply additional tilesets - see separate page](./Creating-a-custom-tileset)
- [Mods can supply additional graphics not included in the base game](#supply-additional-graphics)
- [Mods can override built-in sounds](#override-built-in-sounds)
- [Mods can supply additional music tracks](#supply-additional-music)
## Permanent audiovisual mods
The following chapters describe possibilities that will work while a mod is ***active***. It is either selected for the current game (during new game creation, cannot be changed after that for saved games), meaning all its rules and resources will be used. _Or_ it is marked as 'Permanent audiovisual mod' in the mod manager (you must select it in the 'installed' column to get the checkbox). In that case only graphics and audio will be active, the rule changes will be ignored (if it contains any) unless the first way is _also_ used.
## Override built-in graphics
If a mod supplies an image with the same name and path as one included in the base game (and its [atlas](./Mods#more-on-images-and-the-texture-atlas) is up to date), and the mod is active, the mod's graphics will be used instead of the built-in one.
For example, if you include a file named "Images/OtherIcons/Link.png" in your mod, you will be overriding the little chain links icon denoting linked lines in Civilopedia.
Please note, as for adding items, your graphics should keep the size and color choices of the original, or the result may be surprising, e.g. when the game tries to tint such an image.
## Supply additional graphics
Currently there are two kinds where the game has display capability but does not supply graphics itself, as described in the next paragraphs:
### Adding Wonder Splash Screens
You can add wonder images to mods and they'll be displayed instead of the standard icon when a wonder is finished. The image needs to be a .png and 2:1 ratio so for example 200x100 px.
Add the images to `/Images/WonderImages/`. They need to be named according to the name field in `Buildings.json`, so for example "Temple of Artemis.png" or "Stonehenge.png"
Remember, to be compatible with mobile devices, a fresh atlas needs to be generated including these.
### Adding Leader Portraits
The base game comes without Leader Portraits, but is able to display them in greetings, Civilopedia, diplomacy screens, or the nation picker. A mod can supply these, by adding their images to `/Images/LeaderIcons/`. The file name must correspond exactly with the leader name of a nation as defined in Nations.json, or they will be ignored.
These work best if they are square, between 100x100 and 256x256 pixels, and include some transparent border within that area.
For example, [here](https://github.com/yairm210/Unciv-leader-portrait-mod-example) is mod showing how to add leader portraits, which can complement the base game.
## Override built-in sounds
This works like graphics, except no atlas is involved. E.g. you include a sounds/Click.mp3, it will play instead of the normal click sound. These files must stay short and small. A sound larger than 1MB when uncompressed may break or not play at all on mobile devices. Unciv tries to standardize on 24kHz sample rate, joint stereo, low-bitrate VBR (-128kbps) mp3. Only mp3 and ogg formats will be recognized (but an existing mp3 can be overridden with an ogg file).
## Supply additional music
Sound files (mp3 or ogg) in a mod /music folder will be recognized and used when the mod is active. Tracks will play randomly from all available tracks (with a little bias to avoid close repetition of tracks). There is no overriding - a "thatched-villagers.mp3" in a mod will play in addition to and with the same likelihood as the file that the base game offers to download for you. There is no hard technical limit on bitrate or length, but large bandwidth requirements may lead to stuttering (The end of a "next turn", right before the world map is updated, and with very large maps, is the most likely to cause this).

30
Building-locally-without-Android-Studio.mde Normal file

@ -0,0 +1,30 @@
If you also have JDK 11 installed, you can compile Unciv on your own by cloning (or downloading and unzipping) the project, opening a terminal in the Unciv folder and run the following commands:
### Windows
Running: `gradlew desktop:run`
Building: `gradlew desktop:dist`
### Linux/Mac OS
Running: `./gradlew desktop:run`
Building: `./gradlew desktop:dist`
If the terminal returns `Permission denied` or `Command not found` on Mac/Linux, run `chmod +x ./gradlew` first. *This is a one-time procedure.*
If you get an error that Android SDK folder wasn't found, firstly install it by doing in terminal:
`sudo apt update && sudo apt install android-sdk` (Debian, Ubuntu, Mint etc.)
After that you should put its folder to the file `local.properties` by adding this line:
`sdk.dir = /path/to/android/sdk` which can be `/usr/lib/android-sdk` or something other.
If during the first launch it throws an error that the JDK version is wrong try [this JDK installation](https://www.azul.com/downloads/zulu-community/?package=jdk).
Gradle may take up to several minutes to download files. Be patient.
After building, the output .JAR file should be in /desktop/build/libs/Unciv.jar
For actual development, you'll probably need to download Android Studio and build it yourself - see Contributing :)

68
Civilization-related-JSON-files.md

@ -1,15 +1,17 @@
* [Beliefs.json](#beliefsjson)
* [Buildings.json](#buildingsjson)
* [Nations.json](#nationsjson)
* [Policies.json](#policiesjson)
* [Quests.json](#questsjson)
* [Religions.json](#religionsjson)
* [Specialists.json](#specialistsjson)
* [Techs.json](#techsjson)
- [Beliefs.json](#beliefsjson)
- [Buildings.json](#buildingsjson)
- [Nations.json](#nationsjson)
- [Policies.json](#policiesjson)
- [Quests.json](#questsjson)
- [Religions.json](#religionsjson)
- [Specialists.json](#specialistsjson)
- [Techs.json](#techsjson)
- [Column structure](#column-structure)
- [Tech structure](#tech-structure)
## Beliefs.json
[link to original](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Vanilla/Beliefs.json)
[link to original](https://github.com/${GITHUB_REPOSITORY}/tree/master/android/assets/jsons/Civ%20V%20-%20Gods%20&%20Kings/Beliefs.json)
This file contains the beliefs that can be chosen for religions in your mod.
@ -18,12 +20,12 @@ Each belief can have the following attributes:
| --------- | ---- | --------------- | ----- |
| name | String | Required | Name of the belief |
| type | String | Required | The type of the belief. Valid values are: "Pantheon", "Follower", "Founder" and "Enhancer". |
| uniques | List of Strings | defaults to none | The unique abilities this belief adds to cities following it. May be chosen from the list of building uniques [here](https://github.com/yairm210/Unciv/wiki/Uniques#buildings-only), as well as the general uniques on that page |
| civilopediaText | List | Default empty | see [civilopediaText chapter](#civilopedia-text) |
| uniques | List of Strings | defaults to none | The unique abilities this belief adds to cities following it. May be chosen from the list of building uniques [here](./Uniques#buildings-only), as well as the general uniques on that page |
| civilopediaText | List | Default empty | see [civilopediaText chapter](./Miscellaneous-JSON-files#civilopedia-text) |
## Buildings.json
[link to original](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Vanilla/Buildings.json)
[link to original](https://github.com/${GITHUB_REPOSITORY}/tree/master/android/assets/jsons/Civ%20V%20-%20Vanilla/Buildings.json)
This file should contain all the buildings and wonders you want to use in your mod.
@ -42,12 +44,12 @@ Each building can have the following attributes:
| maintenance | Integer (≥0) | defaults to 0 | Maintenance cost of the building |
| isWonder | Boolean | defaults to false | Whether this building is a global wonder |
| isNationalWonder | Boolean | defaults to false | Whether this building is a national wonder |
| requiredBuilding | String | defaults to none | A building that has to be built before this building can be built. Must be in [Buildings.json](Buildings.json) |
| cannotBeBuiltWith | String | defaults to none | The building [cannotBeBuiltWith] and this building cannot exist in the same city together. Should be in [Buildings.json](Buildings.json) |
| requiredBuilding | String | defaults to none | A building that has to be built before this building can be built. Must be in [Buildings.json](https://github.com/${GITHUB_REPOSITORY}/tree/master/android/assets/jsons/Civ%20V%20-%20Gods%20&%20Kings/Buildings.json) |
| cannotBeBuiltWith | String | defaults to none | The building [cannotBeBuiltWith] and this building cannot exist in the same city together. Should be in [Buildings.json](https://github.com/${GITHUB_REPOSITORY}/tree/master/android/assets/jsons/Civ%20V%20-%20Gods%20&%20Kings/Buildings.json) |
| providesFreeBuilding | String | defaults to none | When the building is built, [providesFreeBuilding] is also automatically added to the city |
| requiredTech | String | defaults to none | The tech that should be researched before this building may be built. Must be in [Techs.json](#techsjson) |
| requiredResource | String | defaults to none | The resource that is consumed when building this building. Must be in [TileResources.json](#tileresourcesjson) |
| requiredNearbyImprovedResources | List of Strings | defaults to none | The 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](#tileresourcesjson) |
| requiredResource | String | defaults to none | The resource that is consumed when building this building. Must be in [TileResources.json](./Map-related-JSON-files#tileresourcesjson) |
| requiredNearbyImprovedResources | List of Strings | defaults to none | The 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](./Map-related-JSON-files#tileresourcesjson) |
| replaces | String | defaults to none | The name of a building that should be replaced by this building. Must be in [Buildings.json](#buildingsjson) |
| uniqueTo | String | defaults to none | If supplied, only the nation with this name can build this building. Must be in [Nations.json](#nationsjson) |
| xpForNewUnits | Integer | defaults to 0 | XP granted automatically to units built in this city |
@ -55,16 +57,16 @@ Each building can have the following attributes:
| cityHealth | Integer | defaults to 0 | Health bonus the city in which this building is built receives |
| hurryCostModifier | Integer | defaults to 0 | When this building is bought using gold or faith, the price is increased by this much percent |
| quote | String | defaults to none | If this building is a (national) wonder, this string will be shown on the completion popup |
| uniques | List of Strings | defaults to none | List of unique abilities this building has. Most of these can be found [here](../Uniques#buildings-only) |
| uniques | List of Strings | defaults to none | List of unique abilities this building has. Most of these can be found [here](./Uniques#buildings-only) |
| replacementTextForUniques | String | defaults to none | If provided, this string will be shown instead of all of the uniques |
| percentStatBonus | Object | defaults to none | Percentual bonus for stats provided by the building. Valid keys are the names of stats (production, gold, science, etc.), valid values are Integers (≥0) |
| greatPersonPoints | Object | defaults to none | How many great person points for each type will be generated per turn. Valid keys are the names of great people (Great Scientist, Great Engineer, etc. .), valid values are Integers (≥0) |
| specialistSlots | Object | defaults to none | Specialist slots provided by this building. Valid keys are the names of specialists (as defined in [Specialists.json](Specialists.json)), valid values are Integers, the amount of slots provided for this specialist |
| civilopediaText | List | Default empty | see [civilopediaText chapter](#civilopedia-text) |
| specialistSlots | Object | defaults to none | Specialist slots provided by this building. Valid keys are the names of specialists (as defined in [Specialists.json](https://github.com/${GITHUB_REPOSITORY}/tree/master/android/assets/jsons/Civ%20V%20-%20Gods%20&%20Kings/Specialists.json)), valid values are Integers, the amount of slots provided for this specialist |
| civilopediaText | List | Default empty | see [civilopediaText chapter](./Miscellaneous-JSON-files#civilopedia-text) |
## Nations.json
[Link to original](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Vanilla/Nations.json)
[Link to original](https://github.com/${GITHUB_REPOSITORY}/tree/master/android/assets/jsons/Civ%20V%20-%20Vanilla/Nations.json)
This file contains all the nations and city states, including Barbarians and Spectator.
@ -90,13 +92,13 @@ This file contains all the nations and city states, including Barbarians and Spe
| outerColor | 3x Integer | Required | R, G, B for inner circle of nation icon |
| uniqueName | String | Default empty | Decorative name for the special characteristic of this Nation |
| uniqueText | String | Default empty | Replacement text for "uniques". If empty, uniques are listed individually. |
| uniques | List | Default empty | Properties of the civilization - see [here](../Uniques#general-uniques) |
| uniques | List | Default empty | Properties of the civilization - see [here](./Uniques#general-uniques) |
| cities | List | Default empty | City names used sequentially for newly founded cities. |
| civilopediaText | List | Default empty | see [civilopediaText chapter](#civilopedia-text) |
| civilopediaText | List | Default empty | see [civilopediaText chapter](./Miscellaneous-JSON-files#civilopedia-text) |
## Policies.json
[Link to original](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Vanilla/Policies.json)
[Link to original](https://github.com/${GITHUB_REPOSITORY}/tree/master/android/assets/jsons/Civ%20V%20-%20Vanilla/Policies.json)
This file lists the available social policies that can be "bought" with culture.
@ -106,8 +108,8 @@ Each policy branch can have the following properties:
| Attribute | Type | Optional? | Notes |
|-----------|------|-----------|-------|
| name | String | Required | |
| era | String | Required | Unlocking era as defined in [Eras.json](#erasjson) |
| uniques | List | Default empty | List of effects, [see here](../Uniques#general-uniques) |
| era | String | Required | Unlocking era as defined in [Eras.json](./Miscellaneous-JSON-files#erasjson) |
| uniques | List | Default empty | List of effects, [see here](./Uniques#general-uniques) |
| policies | List | Default empty | List of member policies |
Each member policy can have the following properties:
@ -117,11 +119,11 @@ Each member policy can have the following properties:
| row | Integer | Required | Placement in UI, each unit approximately half the icon size |
| column | Integer | Required | Placement in UI, each unit approximately half the icon size |
| requires | List | Default empty | List of prerequisite policy names |
| uniques | List | Default empty | List of effects, [see here](../Uniques#general-uniques) |
| uniques | List | Default empty | List of effects, [see here](./Uniques#general-uniques) |
## Quests.json
[Link to original](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Vanilla/Quests.json)
[Link to original](https://github.com/${GITHUB_REPOSITORY}/tree/master/android/assets/jsons/Civ%20V%20-%20Vanilla/Quests.json)
This file contains the Quests that may be given to major Civilizations by City States.
@ -136,13 +138,13 @@ This file contains the Quests that may be given to major Civilizations by City S
## Religions.json
[Link to original](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Vanilla/Religions.json)
[Link to original](https://github.com/${GITHUB_REPOSITORY}/tree/master/android/assets/jsons/Civ%20V%20-%20Gods%20&%20Kings/Religions.json)
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](#beliefsjson).
## Specialists.json
[Link to original](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Vanilla/Specialists.json)
[Link to original](https://github.com/${GITHUB_REPOSITORY}/tree/master/android/assets/jsons/Civ%20V%20-%20Vanilla/Specialists.json)
This file should contain a list of all possible specialists that you want in your mod.
@ -161,7 +163,7 @@ Each specialist can have the following attributes:
## Techs.json
[Link to original](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Vanilla/Techs.json)
[Link to original](https://github.com/${GITHUB_REPOSITORY}/tree/master/android/assets/jsons/Civ%20V%20-%20Vanilla/Techs.json)
This file contains all the technologies. It is organized into an outer list of 'columns' which in turn contain one or more tech each.
@ -169,7 +171,7 @@ This file contains all the technologies. It is organized into an outer list of '
| Attribute | Type | Optional? | Notes |
|-----------|------|-----------|-------|
| columnNumber | Integer | Required | Horizontal placement in the Tech Tree. |
| era | String | Required | References [Eras.json](#erasjson). |
| era | String | Required | References [Eras.json](./Miscellaneous-JSON-files#erasjson). |
| techCost | Integer | Required | Default cost of the techs in this column. |
| buildingCost | Integer | Required | Default cost of buildings requiring this tech. |
| wonderCost | Integer | Required | Default cost of wonders requiring this tech. |
@ -183,5 +185,5 @@ This file contains all the technologies. It is organized into an outer list of '
| cost | Integer | Defaults to column techCost | The amount of science required to research this tech. |
| prerequisites | List | Default empty | A list of the names of techs that are prerequisites of this tech. Only direct prerequisites are necessary. |
| quote | String | Default empty | A nice story presented to the player when they research this tech. |
| uniques | List | Default empty | Properties granted by the tech - see [here](../Uniques#general-uniques). |
| civilopediaText | List | Default empty | see [civilopediaText chapter](#civilopedia-text). |
| uniques | List | Default empty | Properties granted by the tech - see [here](./Uniques#general-uniques). |
| civilopediaText | List | Default empty | see [civilopediaText chapter](./Miscellaneous-JSON-files#civilopedia-text). |

189
Civilization-related-JSON-files.mde Normal file

@ -0,0 +1,189 @@
- [Beliefs.json](#beliefsjson)
- [Buildings.json](#buildingsjson)
- [Nations.json](#nationsjson)
- [Policies.json](#policiesjson)
- [Quests.json](#questsjson)
- [Religions.json](#religionsjson)
- [Specialists.json](#specialistsjson)
- [Techs.json](#techsjson)
- [Column structure](#column-structure)
- [Tech structure](#tech-structure)
## Beliefs.json
[link to original](/android/assets/jsons/Civ%20V%20-%20Gods%20&%20Kings/Beliefs.json)
This file contains the beliefs that can be chosen for religions in your mod.
Each belief can have the following attributes:
| attribute | Type | Optional or not | notes |
| --------- | ---- | --------------- | ----- |
| name | String | Required | Name of the belief |
| type | String | Required | The type of the belief. Valid values are: "Pantheon", "Follower", "Founder" and "Enhancer". |
| uniques | List of Strings | defaults to none | The unique abilities this belief adds to cities following it. May be chosen from the list of building uniques [here](./Uniques#buildings-only), as well as the general uniques on that page |
| civilopediaText | List | Default empty | see [civilopediaText chapter](./Miscellaneous-JSON-files#civilopedia-text) |
## Buildings.json
[link to original](/android/assets/jsons/Civ%20V%20-%20Vanilla/Buildings.json)
This file should contain all the buildings and wonders you want to use in your mod.
Each building can have the following attributes:
| attribute | Type | Optional or not | notes |
| --------- | ---- | --------------- | ----- |
| name | String | required | Name of the building |
| cost | Integer (≥0) | defaults to 0 | Amount of production required to build the building |
| food | Integer | defaults to 0 | Food produced by the building |
| production | Integer | defaults to 0 | Production produced by the building |
| gold | Integer | defaults to 0 | etc. |
| happiness | Integer | defaults to 0 | |
| culture | Integer | defaults to 0 | |
| science | Integer | defaults to 0 | |
| faith | Integer | defaults to 0 | |
| maintenance | Integer (≥0) | defaults to 0 | Maintenance cost of the building |
| isWonder | Boolean | defaults to false | Whether this building is a global wonder |
| isNationalWonder | Boolean | defaults to false | Whether this building is a national wonder |
| requiredBuilding | String | defaults to none | A building that has to be built before this building can be built. Must be in [Buildings.json](/android/assets/jsons/Civ%20V%20-%20Gods%20&%20Kings/Buildings.json) |
| cannotBeBuiltWith | String | defaults to none | The building [cannotBeBuiltWith] and this building cannot exist in the same city together. Should be in [Buildings.json](/android/assets/jsons/Civ%20V%20-%20Gods%20&%20Kings/Buildings.json) |
| providesFreeBuilding | String | defaults to none | When the building is built, [providesFreeBuilding] is also automatically added to the city |
| requiredTech | String | defaults to none | The tech that should be researched before this building may be built. Must be in [Techs.json](#techsjson) |
| requiredResource | String | defaults to none | The resource that is consumed when building this building. Must be in [TileResources.json](./Map-related-JSON-files#tileresourcesjson) |
| requiredNearbyImprovedResources | List of Strings | defaults to none | The 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](./Map-related-JSON-files#tileresourcesjson) |
| replaces | String | defaults to none | The name of a building that should be replaced by this building. Must be in [Buildings.json](#buildingsjson) |
| uniqueTo | String | defaults to none | If supplied, only the nation with this name can build this building. Must be in [Nations.json](#nationsjson) |
| xpForNewUnits | Integer | defaults to 0 | XP granted automatically to units built in this city |
| cityStrength | Integer | defaults to 0 | Strength bonus the city in which this building is built receives |
| cityHealth | Integer | defaults to 0 | Health bonus the city in which this building is built receives |
| hurryCostModifier | Integer | defaults to 0 | When this building is bought using gold or faith, the price is increased by this much percent |
| quote | String | defaults to none | If this building is a (national) wonder, this string will be shown on the completion popup |
| uniques | List of Strings | defaults to none | List of unique abilities this building has. Most of these can be found [here](./Uniques#buildings-only) |
| replacementTextForUniques | String | defaults to none | If provided, this string will be shown instead of all of the uniques |
| percentStatBonus | Object | defaults to none | Percentual bonus for stats provided by the building. Valid keys are the names of stats (production, gold, science, etc.), valid values are Integers (≥0) |
| greatPersonPoints | Object | defaults to none | How many great person points for each type will be generated per turn. Valid keys are the names of great people (Great Scientist, Great Engineer, etc. .), valid values are Integers (≥0) |
| specialistSlots | Object | defaults to none | Specialist slots provided by this building. Valid keys are the names of specialists (as defined in [Specialists.json](/android/assets/jsons/Civ%20V%20-%20Gods%20&%20Kings/Specialists.json)), valid values are Integers, the amount of slots provided for this specialist |
| civilopediaText | List | Default empty | see [civilopediaText chapter](./Miscellaneous-JSON-files#civilopedia-text) |
## Nations.json
[Link to original](/android/assets/jsons/Civ%20V%20-%20Vanilla/Nations.json)
This file contains all the nations and city states, including Barbarians and Spectator.
| Attribute | Type | Optional? | Notes |
|-----------|------|-----------|-------|
| name | String | Required | |
| leaderName | String | Default empty | Omit only for city states! If you want LeaderPortraits, the image file names must match exactly, including case. |
| style | String | Default empty | Modifier appended to pixel unit image names |
| adjective | String | Default empty | Currently unused |
| cityStateType | Enum | Default absent | Distinguishes Major Civilizations from City States (Cultured, Maritime, Mercantile, Militaristic) |
| startBias | List | Default empty | Zero or more of: terrainFilter or "Avoid [terrainFilter]". Two or more will be logically "and"-ed, and if the filters result in no choices, the entire attribute is ignored (e.g. `"startBias": ["Snow","Tundra"]` will _never_ work). |
| preferredVictoryType | Enum | Default Neutral | Neutral, Cultural, Diplomatic, Domination or Scientific |
| startIntroPart1 | String | Default empty | Introductory blurb shown to Player on game start... |
| startIntroPart2 | String | Default empty | ... second paragraph. ***NO*** "TBD"!!! Leave empty to skip that alert. |
| declaringWar | String | Default empty | another greeting |
| attacked | String | Default empty | another greeting |
| defeated | String | Default empty | another greeting |
| introduction | String | Default empty | another greeting |
| neutralHello | String | Default empty | another greeting |
| hateHello | String | Default empty | another greeting |
| tradeRequest | String | Default empty | another greeting |
| innerColor | 3x Integer | Default black | R, G, B for outer ring of nation icon |
| outerColor | 3x Integer | Required | R, G, B for inner circle of nation icon |
| uniqueName | String | Default empty | Decorative name for the special characteristic of this Nation |
| uniqueText | String | Default empty | Replacement text for "uniques". If empty, uniques are listed individually. |
| uniques | List | Default empty | Properties of the civilization - see [here](./Uniques#general-uniques) |
| cities | List | Default empty | City names used sequentially for newly founded cities. |
| civilopediaText | List | Default empty | see [civilopediaText chapter](./Miscellaneous-JSON-files#civilopedia-text) |
## Policies.json
[Link to original](/android/assets/jsons/Civ%20V%20-%20Vanilla/Policies.json)
This file lists 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' has an entry on the member level which _must_ be named as branch name + " Complete", case sensitive.
Each policy branch can have the following properties:
| Attribute | Type | Optional? | Notes |
|-----------|------|-----------|-------|
| name | String | Required | |
| era | String | Required | Unlocking era as defined in [Eras.json](./Miscellaneous-JSON-files#erasjson) |
| uniques | List | Default empty | List of effects, [see here](./Uniques#general-uniques) |
| policies | List | Default empty | List of member policies |
Each member policy can have the following properties:
| Attribute | Type | Optional? | Notes |
|-----------|------|-----------|-------|
| name | String | Required | |
| row | Integer | Required | Placement in UI, each unit approximately half the icon size |
| column | Integer | Required | Placement in UI, each unit approximately half the icon size |
| requires | List | Default empty | List of prerequisite policy names |
| uniques | List | Default empty | List of effects, [see here](./Uniques#general-uniques) |
## Quests.json
[Link to original](/android/assets/jsons/Civ%20V%20-%20Vanilla/Quests.json)
This file contains the Quests that may be given to major Civilizations by City States.
| Attribute | Type | Optional? | Notes |
|-----------|------|-----------|-------|
| name | String | Required | Unique identifier name of the quest, it is also shown |
| description | String | Required | Description of the quest shown to players |
| type | Enum | Default Individual | Individual or Global |
| influece | Float | Default 40 | Influence reward gained on quest completion |
| duration | Integer | Default 0 | Maximum number of turns to complete the quest, 0 if there's no turn limit |
| minimumCivs | Integer | Default 1 | Minimum number of Civs needed to start the quest. It is meaningful only for type = Global |
## Religions.json
[Link to original](/android/assets/jsons/Civ%20V%20-%20Gods%20&%20Kings/Religions.json)
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](#beliefsjson).
## Specialists.json
[Link to original](/android/assets/jsons/Civ%20V%20-%20Vanilla/Specialists.json)
This file should contain a list of all possible specialists that you want in your mod.
Each specialist can have the following attributes:
| attribute | type | optional or not | notes |
| --------- | ---- | --------------- | ----- |
| name | String | required | Name of the specialist |
| food | Integer | defaults to 0 | Amount of food produced by this specialist |
| production | Integer | defaults to 0 | Amount of production produced by this specialist |
| gold | Integer | defaults to 0 | etc. |
| culture | Integer | defaults to 0 | |
| science | Integer | defaults to 0 |
| faith | Integer | defaults to 0 |
| color | List of 3 Integers | required | Color of the image for this specialist |
| greatPersonPoints | Object | defaults to none | Great person points generated by this specialist. Valid keys are the names of the great person(Great Scientist, Great Merachant, etc.), valid values are Integers (≥0) |
## Techs.json
[Link to original](/android/assets/jsons/Civ%20V%20-%20Vanilla/Techs.json)
This file contains all the technologies. It is organized into an outer list of 'columns' which in turn contain one or more tech each.
#### Column structure
| Attribute | Type | Optional? | Notes |
|-----------|------|-----------|-------|
| columnNumber | Integer | Required | Horizontal placement in the Tech Tree. |
| era | String | Required | References [Eras.json](./Miscellaneous-JSON-files#erasjson). |
| techCost | Integer | Required | Default cost of the techs in this column. |
| buildingCost | Integer | Required | Default cost of buildings requiring this tech. |
| wonderCost | Integer | Required | Default cost of wonders requiring this tech. |
| techs | List of Techs | Required | List of techs as follows - pay attention to the nesting of {} and []. |
#### Tech structure
| Attribute | Type | Optional? | Notes |
|-----------|------|-----------|-------|
| name | String | Required | The name of this Technology. |
| row | Integer | Defaults to 0 | Vertical placement in the Tech Tree, must be unique per column. |
| cost | Integer | Defaults to column techCost | The amount of science required to research this tech. |
| prerequisites | List | Default empty | A list of the names of techs that are prerequisites of this tech. Only direct prerequisites are necessary. |
| quote | String | Default empty | A nice story presented to the player when they research this tech. |
| uniques | List | Default empty | Properties granted by the tech - see [here](./Uniques#general-uniques). |
| civilopediaText | List | Default empty | see [civilopediaText chapter](./Miscellaneous-JSON-files#civilopedia-text). |

15
Coding-standards.mde Normal file

@ -0,0 +1,15 @@
As an open-source project, there will be a lot of eyes on our code.
The main purpose of having a coding standard is for the code to be as immediately readable as possible to as many potential contributors, and hence most of it focuses on defaulting to coding structures that exist in other similar languages (Java, C#) when possible.
## Don't use `.let{}` and `?:`
Kotlin is made greater for being strict with nullability. Don't let this fact confuse people new to it. These can be simply replaced by `if(x!=null)` which is much more readable. They all probably compile to the same bytecode anyway, so when in doubt - readability.
## `for(item in list)` and not `list.forEach{}`
For loops go waaaay back, forEach doesn't. As an added bonus, I'm pretty sure that because forEach accepts a function parameter, then when debugging it won't automatically step into these lines, unlike for.
## Avoid premature abstraction
There's no need to create an interface if there is only one implementation of that interface. Doing so obfuscates the actual code that's running and increases the Time To Relevant Code. If abstraction becomes necessary later, we can always do it later.

6
Creating-a-custom-tileset.md

@ -1,12 +1,12 @@
# How to make Unciv use your custom tileset
### You should read the [Mods](https://github.com/yairm210/Unciv/wiki/Mods) page first before proceeding
### You should read the [Mods](./Mods) page first before proceeding
In order to add a tileset mod (yes, tilesets are just another type of mod), all you need to do is add your images under Images/Tilesets/MyCoolTilesetExample and enable the mod as a permanent visual mod - the game will recognize the tileset, and allow you to pick it in the options menu.
Let's look at the example "Grassland+Jungle+Dyes+Trading post" to learn how the game decides which images it should use for this tile:
1. When there is a rule variant entry in the [tileset config](https://github.com/yairm210/Unciv/wiki/Creating-a-custom-tileset/tileset-config) for this tile we will use the entry.
1. When there is a rule variant entry in the [tileset config](#tileset-config) for this tile we will use the entry.
2. Else if there is an image called "Grassland+Jungle+Dyes+Trading post" we will use it instead.
@ -60,4 +60,4 @@ A dictionary mapping string to string[]. Default value: empty
The ruleVariants are the most powerful part of the tileset config.
With this, you can define, for a specific tile, which images and in which order these images should be used.
An example is given in the code above. For the tile "Grassland+Jungle+Dyes+Trading post" we then use the images "Grassland", "JungleForGrasslandBack", "Dyes+Trading post" and "JungleForGrasslandFront" in that order.
An example is given in the code above. For the tile "Grassland+Jungle+Dyes+Trading post" we then use the images "Grassland", "JungleForGrasslandBack", "Dyes+Trading post" and "JungleForGrasslandFront" in that order.

63
Creating-a-custom-tileset.mde Normal file

@ -0,0 +1,63 @@
# How to make Unciv use your custom tileset
### You should read the [Mods](./Mods) page first before proceeding
In order to add a tileset mod (yes, tilesets are just another type of mod), all you need to do is add your images under Images/Tilesets/MyCoolTilesetExample and enable the mod as a permanent visual mod - the game will recognize the tileset, and allow you to pick it in the options menu.
Let's look at the example "Grassland+Jungle+Dyes+Trading post" to learn how the game decides which images it should use for this tile:
1. When there is a rule variant entry in the [tileset config](#tileset-config) for this tile we will use the entry.
2. Else if there is an image called "Grassland+Jungle+Dyes+Trading post" we will use it instead.
3. Otherwise, we will check if there is an image called "Grassland+Jungle" (BaseTerrain+Terrainfeatures) and "Dyes+Trading post" (Resource+Improvement) and use the remainings of it. Let's say you made an image called "Grassland+Jungle" but none called "Dyes+Trading post". In the end, we will then use the images "Grassland+Jungle", "Dyes" and "Trading post".
All these images can also use era-dependant variants if you want to change the appearance of, let's say, "Trading post" throughout the game. Just create images and add the suffix "-[era name]".
E.g. "Trading post-Classical era", "Trading post-Industrial era", etc.
It is advised to use the layered approach (1 and 3) often because it comes with a few advantages. Mainly:
- Decreased filesize (on disk, for downloads)
- Easier support for new terrains, improvements, resources, and for changing existing tiles
You should keep in mind that the default rendering order is:
BaseTerrain, TerrainFeatures, Resource, Improvement.
## Tileset config
This is where tileset configs shine.
You can use these to alter the way Unicv renders tiles.
To create a config for your tileset you just need to create a new .json file under Jsons/Tilesets/. Just create a .txt file and rename it to MyCoolTilesetExample.json. You only have to add things if you want to change them. Else the default values will be used.
This is an example of such a config file that I will explain below:
```
"useColorAsBaseTerrain": "false",
"unexploredTileColor": {"r":1,"g":1,"b":1,"a":1},
"fogOfWarColor": {"r":1,"g":0,"b":0,"a":1},
"ruleVariants": {
"Grassland+Forest": ["Grassland","ForestForGrassland"],
"Grassland+Jungle+Dyes+Trading post": ["Grassland","JungleForGrasslandBack","Dyes+Trading post","JungleForGrasslandFront"]
}
```
### useColorAsBaseTerrain
A boolean value ("true" or "false"). Default value: "true"
If true all tiles will be colored in their corresponding base terrain color. This is how the "Default" tileset works.
### unexploredTileColor
A color defined with normalized RGBA values. Default value: "{"r":0.24705882, "g":0.24705882, "b":0.24705882, "a":1}" (DarkGray)
Defines the color of the unexplored tiles.
### fogOfWarColor
A color defined with normalized RGBA values. Default value: "{"r":0, "g":0, "b":0, "a":1}" (Black)
Defines the color of the fog of war. The color gets approximated by 60% to allow the colors of the images below to shine through.
### ruleVariants
A dictionary mapping string to string[]. Default value: empty
The ruleVariants are the most powerful part of the tileset config.
With this, you can define, for a specific tile, which images and in which order these images should be used.
An example is given in the code above. For the tile "Grassland+Jungle+Dyes+Trading post" we then use the images "Grassland", "JungleForGrasslandBack", "Dyes+Trading post" and "JungleForGrasslandFront" in that order.

137
Force-rating-calculation.mde Normal file

@ -0,0 +1,137 @@
# Force rating
Since the question has come up several times, here is a summary of how Force ratings are calculated.
## Base Unit Force Evaluation
First the base unit gets a force evaluation.
If the unit has a ranged attack, the starting force is the ranged strength ^ 1.45. Otherwise the starting force is strength ^ 1.5.
This is multiplied by the unit's movement ^ 0.3. Nukes get +4000.
Then this is multiplied by a bunch of modifiers:
* 0.5 if ranged naval
* 0.5 if self-destructs when attacking
* Half the city attack bonus (So +25% if the unit has +50% when attacking cities)
* A Quarter of attack bonuses vs things other than cities
* Half the bonus "when attacking"
* Half the bonus "when defending"
* +25% if paradrop able
* -20% if needs to set up to attack
* Half the bonus from certain terrain
* +20% bonus per extra attack per turn
## Individual Unit Force Evaluation
Each individual unit has a Force equal to the Base Unit Force,
* multiplied by (number of times promoted +1) ^ 0.3.
* multiplied by current health as a percentage.
## Civ Force Ranking
The civs Force Ranking is based on the sum of all their units' Force Evaluation (cities are not counted).
Only half the Force of naval units is counted.
This is multiplied by a gold modifier equal to the square root of current gold, as a percentage.
The gold multiplier is constrained to be between 1 and 2, so the max multiplier is 2 which is reached at 10000 gold.
## Show Me Some Numbers
* `Scout 13`
* `Archer 19`
* `Slinger 19`
* `Dromon 23`
* `Warrior 27`
* `Maori Warrior 27`
* `Brute 27`
* `Bowman 29`
* `Jaguar 36`
* `Catapult 39`
* `Composite Bowman 39`
* `Galleass 41`
* `Chariot Archer 42`
* `War Elephant 44`
* `War Chariot 45`
* `Horse Archer 45`
* `Trireme 46`
* `Spearman 49`
* `Ballista 55`
* `Persian Immortal 56`
* `Horseman 62`
* `Hoplite 63`
* `Swordsman 64`
* `Chu-Ko-Nu 66`
* `Quinquereme 69`
* `African Forest Elephant 72`
* `Battering Ram 80`
* `Cataphract 80`
* `Crossbowman 81`
* `Longbowman 81`
* `Companion Cavalry 84`
* `Legion 86`
* `Mohawk Warrior 86`
* `Pikeman 87`
* `Landsknecht 87`
* `Trebuchet 88`
* `Keshik 89`
* `Frigate 100`
* `Hwach'a 110`
* `Longswordsman 118`
* `Camel Archer 124`
* `Samurai 126`
* `Berserker 133`
* `Knight 134`
* `Conquistador 134`
* `Mandekalu Cavalry 134`
* `Caravel 134`
* `Ship of the Line 139`
* `Musketman 144`
* `Cannon 151`
* `Minuteman 154`
* `Janissary 162`
* `Gatling Gun 169`
* `Musketeer 182`
* `Tercio 182`
* `Naresuan's Elephant 194`
* `Lancer 204`
* `Hakkapeliitta 204`
* `Sipahi 218`
* `Privateer 222`
* `Rifleman 243`
* `Carolean 243`
* `Sea Beggar 244`
* `Artillery 245`
* `Battleship 269`
* `Great War Bomber 290`
* `Cavalry 300`
* `Hussar 320`
* `Triplane 325`
* `Turtle Ship 327`
* `Cossack 337`
* `Norwegian Ski Infantry 345`
* `Guided Missile 378`
* `Carrier 408`
* `Submarine 420`
* `Bomber 425`
* `Great War Infantry 434`
* `Machine Gun 465`
* `Fighter 470`
* `Foreign Legion 477`
* `Ironclad 486`
* `Zero 508`
* `Anti-Tank Gun 542`
* `B17 551`
* `Marine 645`
* `Landship 703`
* `Infantry 720`
* `Nuclear Submarine 735`
* `Stealth Bomber 771`
* `Paratrooper 806`
* `Anti-Aircraft Gun 819`
* `Destroyer 870`
* `Missile Cruiser 888`
* `Rocket Artillery 930`
* `Tank 948`
* `Jet Fighter 988`
* `Helicopter Gunship 992`
* `Mechanized Infantry 1186`
* `Panzer 1223`
* `Mobile SAM 1376`
* `Modern Armor 1620`
* `Giant Death Robot 2977`
* `Atomic Bomb 4714`
* `Nuclear Missile 7906`

16
From-code-to-deployment.md

@ -18,10 +18,10 @@ The process has two major parts, one is "Getting your code in the main repositor
When I'm ready to release a new version I:
* Comment "merge translations" in one of the open PRs tagged as 'mergeable translation' to trigger the translation branch creation, add a "summary" comment to trigger summary generation, merge the PR and delete the branch (so next version translation branch starts fresh)
* From my workstation - pull the latest changes and run the [translation generation](https://github.com/yairm210/Unciv/wiki/Translating#translation-generation---for-developers)
* From my workstation - pull the latest changes and run the [translation generation](./Translating#translation-generation---for-developers)
* Change the versionCode and versionName in the Android build.gradle so that Google Play and F-droid can recognize that it's a different release
* Add an entry in the changelog.md done, WITHOUT hashtags, and less than 500 characters (that's the limit for Google play entries). The formatting needs to be exact or the text sent to Discord, the Github release etc. won't be complete.
* Add a tag to the commit of the version. When the [Github action](https://github.com/yairm210/Unciv/actions/workflows/buildAndDeploy.yml) sees that we've added a tag, it will run a build, and this time (because of the configuration we put in the [yml file](https://github.com/yairm210/Unciv/blob/master/.github/workflows/buildAndDeploy.yml) file), it will:
* Add a tag to the commit of the version. When the [Github action](https://github.com/yairm210/Unciv/actions/workflows/buildAndDeploy.yml) sees that we've added a tag, it will run a build, and this time (because of the configuration we put in the [yml file](https://github.com/${GITHUB_REPOSITORY}/tree/master/.github/workflows/buildAndDeploy.yml) file), it will:
* Pack a .jar file, which will work for every operating system with Java
* Use Linux and Windows JDKs to create standalone zips for 32 and 64 bit systems, because we can't rely on the fact that users will have a JRE
* Download [Butler](https://itch.io/docs/butler/installing.html) and use it to [push](https://itch.io/docs/butler/pushing.html) the new versions to the [itch.io page](https://yairm210.itch.io/unciv)
@ -34,10 +34,10 @@ When I'm ready to release a new version I:
## About Google Play publishing
We start at a 10% rollout, after a day with no major problems go to 30%, and after another day to 100%. If you were counting that means that most players will get the new version after 2+ days.
If there were problems, we halt the current rollout, fix the problems, and release a patch version, which starts at 10% again.
Dear future me - the automation was extremely annoying guesswork to set up, so the facts you need to know are:
+We start at a 10% rollout, after a day with no major problems go to 30%, and after another day to 100%. If you were counting that means that most players will get the new version after 2+ days.
+
+If there were problems, we halt the current rollout, fix the problems, and release a patch version, which starts at 10% again.
+
+Dear future me - the automation was extremely annoying guesswork to set up, so the facts you need to know are:
- There is a user at the [Google Cloud Platform Account Manager](https://console.cloud.google.com/iam-admin/iam) called Unciv_Upload_Account. There is an access key to this account, in json, stored as the Github secret GOOGLE_PLAY_SERVICE_ACCOUNT_JSON.
- This user was granted ADMIN permissions to the Google Play (after much trial and error since nothing else seemed to work) under User > Users and Permissions. Under Manage > Account permissions, you can see that it has Admin.
- This user was granted ADMIN permissions to the Google Play (after much trial and error since nothing else seemed to work) under User > Users and Permissions. Under Manage > Account permissions, you can see that it has Admin.

43
From-code-to-deployment.mde Normal file

@ -0,0 +1,43 @@
# From code to deployment
So, your code works! You've solved all the bugs and now you just need to get it out to everyone!
So, how does THAT work?
The process has two major parts, one is "Getting your code in the main repository" and the other is "Deploying versions" - as a developer, you'll be taking an active part in the first process, but the second process is on me =)
## Getting your code in the main repo
* First off, push your changes with Git to your own branch at https://github.com/YourUsername/Unciv.git. I hope you've been doing this during development too, but that's none of my business \*sips tea\*
* Issue a pull request from https://github.com/YourUsername/Unciv - from the Pull Requests is the simplest
* The Travis build will check that your proposed change builds properly and passes all tests
* I'll go over your pull request and will ask questions and request changes - this is not only for code quality and standard, it's mostly so you can learn how the repo works for the next change you make =)
* When everything looks good, I'll merge your code in and it'll enter the next release!
## Deploying versions
When I'm ready to release a new version I:
* Comment "merge translations" in one of the open PRs tagged as 'mergeable translation' to trigger the translation branch creation, add a "summary" comment to trigger summary generation, merge the PR and delete the branch (so next version translation branch starts fresh)
* From my workstation - pull the latest changes and run the [translation generation](./Translating#translation-generation---for-developers)
* Change the versionCode and versionName in the Android build.gradle so that Google Play and F-droid can recognize that it's a different release
* Add an entry in the changelog.md done, WITHOUT hashtags, and less than 500 characters (that's the limit for Google play entries). The formatting needs to be exact or the text sent to Discord, the Github release etc. won't be complete.
* Add a tag to the commit of the version. When the [Github action](https://github.com/yairm210/Unciv/actions/workflows/buildAndDeploy.yml) sees that we've added a tag, it will run a build, and this time (because of the configuration we put in the [yml file](/.github/workflows/buildAndDeploy.yml) file), it will:
* Pack a .jar file, which will work for every operating system with Java
* Use Linux and Windows JDKs to create standalone zips for 32 and 64 bit systems, because we can't rely on the fact that users will have a JRE
* Download [Butler](https://itch.io/docs/butler/installing.html) and use it to [push](https://itch.io/docs/butler/pushing.html) the new versions to the [itch.io page](https://yairm210.itch.io/unciv)
* Read the changelog.md file to get the changes for the latest version
* Upload all of these files to a new release on Github, with the release notes, which will get added to the [Releases](https://github.com/yairm210/Unciv/releases) page
* Send an announcement on the Discord server of the version release and release notes via webhook
* Pack, Sign, and Upload a new APK to the Google Play Console at 10% rollout
* The F-Droid bot checks periodically if we added a new tag. When it recognizes that we did, it will update the [yaml file here](https://gitlab.com/fdroid/fdroiddata/blob/master/metadata/com.unciv.app.yml)
* When the bot next runs and sees that there's a version it doesn't have a release for, it will attempt to build the new release. The log of the build will be added [here](https://f-droid.org/wiki/page/com.unciv.app/lastbuild) (redirects to the latest build), and the new release will eventually be available [here](https://f-droid.org/en/packages/com.unciv.app/)
## About Google Play publishing
+We start at a 10% rollout, after a day with no major problems go to 30%, and after another day to 100%. If you were counting that means that most players will get the new version after 2+ days.
+
+If there were problems, we halt the current rollout, fix the problems, and release a patch version, which starts at 10% again.
+
+Dear future me - the automation was extremely annoying guesswork to set up, so the facts you need to know are:
- There is a user at the [Google Cloud Platform Account Manager](https://console.cloud.google.com/iam-admin/iam) called Unciv_Upload_Account. There is an access key to this account, in json, stored as the Github secret GOOGLE_PLAY_SERVICE_ACCOUNT_JSON.
- This user was granted ADMIN permissions to the Google Play (after much trial and error since nothing else seemed to work) under User > Users and Permissions. Under Manage > Account permissions, you can see that it has Admin.

2
Getting-Started.md

@ -26,4 +26,4 @@ Unciv uses Gradle to specify dependencies and how to run. In the background, the
Congratulations! Unciv should now be running on your computer! Now we can start changing some code, and later we'll see how your changes make it into the main repository!
Now would be a good time to get to know the project in general at [the Project Structure overview!](https://github.com/yairm210/Unciv/wiki/Project-structure-and-major-classes)
Now would be a good time to get to know the project in general at [the Project Structure overview!](./Project-structure-and-major-classes)

29
Getting-Started.mde Normal file

@ -0,0 +1,29 @@
This is a guide to editing, building, running and deploying Unciv from code
So first things first - the initial "No assumptions" setup to have Unciv run from-code on your computer!
* Install Android Studio - it's free and awesome! Be aware that it's a long download!
* Install Git, it's the way for us to work together on this project. UI is optional, Android Studio has good Git tools built in :)
* Getting the code
* Create a Github account, if you don't already have one
* Fork the repo (click the "Fork" button on the top-right corner of https://github.com/yairm210/Unciv) - this will create a "copy" of the code on your account, at https://github.com/YourUsername/Unciv
* Clone your fork with git - the location will be https://github.com/YourUsername/Unciv.git, visible from the green "Clone or download" button at https://github.com/YourUsername/Unciv
* Load the project in Android Studio, Gradle will attempt the initial sync. If this is your first time with Android Studio, this may require you to accept the Android Build-tools licenses, which works differently on every device, so search for your OS-specific solution.
* A new install may not be able to do the initial sync - this comes in the form of `Unable to find method ''void org.apache.commons.compress.archivers.zip.ZipFile.<init>(java.nio.channels.SeekableByteChannel)''` errors when you try to sync. If you have this problem go into File > Settings > Appearance & Behavior > System Settings > Android SDK
* Click "SDK Tools"
* Select "Show Package Details" in the bottom right
* Choose version 30.0.2 under "Android SDK Build-Tools 31"
* Click "Apply"
* In Android Studio, Run > Edit configurations.
* Click "+" to add a new configuration
* Choose "Application"
* Set the module to `Unciv.desktop`, main class to `com.unciv.app.desktop.DesktopLauncher` and `<repo_folder>\android\assets\` as the Working directory, OK to close the window
* If you get a `../../docs/uniques.md (No such file or directory)` error that means you forgot to set the working directory!
* Select the Desktop configuration and click the green arrow button to run!
* I also recommend going to Settings > Version Control > Commit and turning off 'Before commit - perform code analysis'
Unciv uses Gradle to specify dependencies and how to run. In the background, the Gradle gnomes will be off fetching the packages (a one-time effort) and, once that's done, will build the project!
Congratulations! Unciv should now be running on your computer! Now we can start changing some code, and later we'll see how your changes make it into the main repository!
Now would be a good time to get to know the project in general at [the Project Structure overview!](./Project-structure-and-major-classes)

6
Home.md

@ -1,7 +1,7 @@
Welcome to the Unciv wiki!
If you're a developer, you'll probably want to start at the [Getting Started](/yairm210/Unciv/wiki/Getting-Started) page!
If you're a developer, you'll probably want to start at the [Getting Started](./Getting-Started) page!
If you're a translator, head over to [Translating!](/yairm210/Unciv/wiki/Translating)
If you're a translator, head over to [Translating!](./Translating)
If you're a modder, [start here](/yairm210/Unciv/wiki/Mods).
If you're a modder, [start here](./Mods).

7
Home.mde Normal file

@ -0,0 +1,7 @@
Welcome to the Unciv wiki!
If you're a developer, you'll probably want to start at the [Getting Started](./Getting-Started) page!
If you're a translator, head over to [Translating!](./Translating)
If you're a modder, [start here](./Mods).

4
Installing-on-macOS.md

@ -12,6 +12,6 @@ _(Sadly UnCiv dose not auto update when installing it using this method on macOS
## Installing from source
For instructions on how to install UnCiv from source see [Building locally without Android Studio](https://github.com/yairm210/Unciv/wiki/Building-locally-without-Android-Studio). It is not recommended to use this method as it achieves the same result as the first method whilst being much more complicated and prone to errors along the way.
For instructions on how to install UnCiv from source see [Building locally without Android Studio](./Building-locally-without-Android-Studio). It is not recommended to use this method as it achieves the same result as the first method whilst being much more complicated and prone to errors along the way.
_(Sadly UnCiv dose not auto update when installing it using this method on macOS so you will need to follow these steps every time you want to update the game.)_
_(Sadly UnCiv dose not auto update when installing it using this method on macOS so you will need to follow these steps every time you want to update the game.)_

17
Installing-on-macOS.mde Normal file

@ -0,0 +1,17 @@
There is currently two ways to install UnCiv on macOS. It is recommended that you use the first method as the second one is overly complicated and the end result will be the same. Both installation methods require that you have Java 8 installed on your mac.
## Installing using JAR
1. If you don't already have Java 8 installed on your mac make sure you download it from the [official website](https://java.com/en/download/). Once you have downloaded the file open it and follow the instructions on screen.
2. Now that you have Java 8 installed it's time to download the latest UnCiv JAR. This can be done from the [releases](https://github.com/yairm210/UnCiv/releases) screen here on Github. Download the file called Unciv.jar.
3. After downloading Unciv.jar open Finder on your mac and go to the location where you chose to save the file. Right-click or Control-click the file and chose Open.
4. You will now be prompted with a window saying something similar to `macOS cannot verify the developer of "Unciv.jar". Are you sure you want to open it?` Press the Open button.
5. Congratulations, you have now installed UnCiv. You may want to add a shortcut to the desktop to be able to open the game more easily.
_(Sadly UnCiv dose not auto update when installing it using this method on macOS so you will need to download the latest Unciv.jar from Github every time you want to update the game.)_
## Installing from source
For instructions on how to install UnCiv from source see [Building locally without Android Studio](./Building-locally-without-Android-Studio). It is not recommended to use this method as it achieves the same result as the first method whilst being much more complicated and prone to errors along the way.
_(Sadly UnCiv dose not auto update when installing it using this method on macOS so you will need to follow these steps every time you want to update the game.)_

60
JSON-files-for-mods.md

@ -5,32 +5,32 @@ The JSON files that make up mods can have many different fields, and as not all
# Table of Contents
* [General Overview of JSON files](#general-overview-of-json-files)
* [Civilization-related JSON files](Civilization-related-JSON-files)
* [Beliefs.json](Civilization-related-JSON-files#beliefsjson)
* [Buildings.json](Civilization-related-JSON-files#buildingsjson)
* [Nations.json](Civilization-related-JSON-files#nationsjson)
* [Policies.json](Civilization-related-JSON-files#policiesjson)
* [Quests.json](Civilization-related-JSON-files#questsjson)
* [Religions.json](Civilization-related-JSON-files#religionsjson)
* [Specialists.json](Civilization-related-JSON-files#specialistsjson)
* [Techs.json](Civilization-related-JSON-files#techsjson)
* [Map-related JSON files](Map-related-JSON-files)
* [Terrains.json](Map-related-JSON-files#terrainsjson)
* [TileResources.json](Map-related-JSON-files#tileresourcesjson)
* [TileImprovements.json](Map-related-JSON-files#tileimprovementsjson)
* [Ruins.json](Map-related-JSON-files#ruinsjson)
* [Tileset-specific json](Map-related-JSON-files#tileset-specific-json)
* [Unit-related JSON files](Unit-related-JSON-files)
* [Units.json](Unit-related-JSON-files#unitsjson)
* [UnitPromotions.json](Unit-related-JSON-files#unitpromotionsjson)
* [UnitTypes.json](Unit-related-JSON-files#unittypesjson)
* [Miscellaneous JSON files](Miscellaneous-JSON-files)
* [Difficulties.json](Miscellaneous-JSON-files#difficultiesjson)
* [Eras.json](Miscellaneous-JSON-files#erasjson)
* [ModOptions.json](Miscellaneous-JSON-files#modoptionsjson)
* [Stats](Map-related-JSON-files#stats)
* [Sounds](Unit-related-JSON-files#sounds)
* [Civilopedia text](Miscellaneous-JSON-files#civilopedia-text)
* [Civilization-related JSON files](Civilization-related-JSON-files.md)
* [Beliefs.json](Civilization-related-JSON-files.md#beliefsjson)
* [Buildings.json](Civilization-related-JSON-files.md#buildingsjson)
* [Nations.json](Civilization-related-JSON-files.md#nationsjson)
* [Policies.json](Civilization-related-JSON-files.md#policiesjson)
* [Quests.json](Civilization-related-JSON-files.md#questsjson)
* [Religions.json](Civilization-related-JSON-files.md#religionsjson)
* [Specialists.json](Civilization-related-JSON-files.md#specialistsjson)
* [Techs.json](Civilization-related-JSON-files.md#techsjson)
* [Map-related JSON files](Map-related-JSON-files.md)
* [Terrains.json](Map-related-JSON-files.md#terrainsjson)
* [TileResources.json](Map-related-JSON-files.md#tileresourcesjson)
* [TileImprovements.json](Map-related-JSON-files.md#tileimprovementsjson)
* [Ruins.json](Map-related-JSON-files.md#ruinsjson)
* [Tileset-specific json](Map-related-JSON-files.md#tileset-specific-json)
* [Unit-related JSON files](Unit-related-JSON-files.md)
* [Units.json](Unit-related-JSON-files.md#unitsjson)
* [UnitPromotions.json](Unit-related-JSON-files.md#unitpromotionsjson)
* [UnitTypes.json](Unit-related-JSON-files.md#unittypesjson)
* [Miscellaneous JSON files](Miscellaneous-JSON-files.md)
* [Difficulties.json](Miscellaneous-JSON-files.md#difficultiesjson)
* [Eras.json](Miscellaneous-JSON-files.md#erasjson)
* [ModOptions.json](Miscellaneous-JSON-files.md#modoptionsjson)
* [Stats](Map-related-JSON-files.md#stats)
* [Sounds](Unit-related-JSON-files.md#sounds)
* [Civilopedia text](Miscellaneous-JSON-files.md#civilopedia-text)
# General Overview of JSON files
@ -82,7 +82,7 @@ Many parts of Unciv are moddable, and for each there is a seperate json file. Th
The individual files are described on separate pages:
* [Civilization-related JSON files](Civilization-related-JSON-files)
* [Map-related JSON files](Map-related-JSON-files)
* [Unit-related JSON files](Unit-related-JSON-files)
* [Miscellaneous JSON files](Miscellaneous-JSON-files)
* [Civilization-related JSON files](Civilization-related-JSON-files.md)
* [Map-related JSON files](Map-related-JSON-files.md)
* [Unit-related JSON files](Unit-related-JSON-files.md)
* [Miscellaneous JSON files](Miscellaneous-JSON-files.md)

88
JSON-files-for-mods.mde Normal file

@ -0,0 +1,88 @@
These pages are a work in progress. Information they contain may be incomplete.
The JSON files that make up mods can have many different fields, and as not all are used in the base game, this wiki page will contain the full information of each. It will also give a short explanation of the syntax of JSON files.
# Table of Contents
* [General Overview of JSON files](#general-overview-of-json-files)
* [Civilization-related JSON files](Civilization-related-JSON-files.md)
* [Beliefs.json](Civilization-related-JSON-files.md#beliefsjson)
* [Buildings.json](Civilization-related-JSON-files.md#buildingsjson)
* [Nations.json](Civilization-related-JSON-files.md#nationsjson)
* [Policies.json](Civilization-related-JSON-files.md#policiesjson)
* [Quests.json](Civilization-related-JSON-files.md#questsjson)
* [Religions.json](Civilization-related-JSON-files.md#religionsjson)
* [Specialists.json](Civilization-related-JSON-files.md#specialistsjson)
* [Techs.json](Civilization-related-JSON-files.md#techsjson)
* [Map-related JSON files](Map-related-JSON-files.md)
* [Terrains.json](Map-related-JSON-files.md#terrainsjson)
* [TileResources.json](Map-related-JSON-files.md#tileresourcesjson)
* [TileImprovements.json](Map-related-JSON-files.md#tileimprovementsjson)
* [Ruins.json](Map-related-JSON-files.md#ruinsjson)
* [Tileset-specific json](Map-related-JSON-files.md#tileset-specific-json)
* [Unit-related JSON files](Unit-related-JSON-files.md)
* [Units.json](Unit-related-JSON-files.md#unitsjson)
* [UnitPromotions.json](Unit-related-JSON-files.md#unitpromotionsjson)
* [UnitTypes.json](Unit-related-JSON-files.md#unittypesjson)
* [Miscellaneous JSON files](Miscellaneous-JSON-files.md)
* [Difficulties.json](Miscellaneous-JSON-files.md#difficultiesjson)
* [Eras.json](Miscellaneous-JSON-files.md#erasjson)
* [ModOptions.json](Miscellaneous-JSON-files.md#modoptionsjson)
* [Stats](Map-related-JSON-files.md#stats)
* [Sounds](Unit-related-JSON-files.md#sounds)
* [Civilopedia text](Miscellaneous-JSON-files.md#civilopedia-text)
# General Overview of JSON files
Resources: [json.org](https://www.json.org/), [ISO standard](https://standards.iso.org/ittf/PubliclyAvailableStandards/c071616_ISO_IEC_21778_2017.zip)
Almost all Unciv JSON files start with a "[" and end with a "]". In between these are different objects of the type you are describing, each of which is contained between a "{" and a "}". For example, a very simple units.json may look like:
```
[
{
"name": "Warrior",
"cost": 16
},
{
"name": "Spearman",
"cost": 24,
"promotions": ["Shock I", "Drill I"]
}
]
```
This file contains two unit objects, one for a warrior and one for a spearman. These objects have different attributes, in this case "name", "cost" and "promotions". All these attributes have a certain type, a String (text) for "name", an Integer for "cost" and a List of Strings for "promotions".
There are different types of attributes:
| type | notes |
| --------- | ----- |
| String | A word or sentence. Should be between double quotes (") |
| Integer | A number. Can be both positive or negative. Should **not** be between quotes |
| Boolean | A value that can either be 'true' or 'false'. Should **not** be between quotes |
| List of [type] | If multiple values could apply (such as with the promotions above), they should be put inside a list. Each element of the list should be written like a normal attribute, seperated by comma's, and enclosed between square braces. E.g.: ["Shock I", "Shock II"] or [1, 2, 3]. |
| Object | The most complicated type of attribute. An object is comprised of multiple attributes, each of which again has a type. These attributes have a key (the part before the ":") and a value (the part behind it). For an example, see below. |
Example of a Buildings.json adding a new "Cultural Library" building which gives +50% science and +50% culture:
```
[
{
"name": "Cultural Library"
"percentStatBonus" : {"science": 50, "culture": 50}
}
]
```
The keys in this example are "science" and "culture", and both have the value "50".
In some sense you can see from these types that JSON files themselves are actually a list of objects, each describing a single building, unit or something else.
# Information on JSON files used in the game
Many parts of Unciv are moddable, and for each there is a seperate json file. There is a json file for buildings, for units, for promotions units can have, for technologies, etc. The different new buildings or units you define can also have lots of different attributes, though not all are required. Below are tables documenting all the different attributes everything can have. Only the attributes which are noted to be 'required' must be provided. All others have a default value that will be used when it is omitted.
The individual files are described on separate pages:
* [Civilization-related JSON files](Civilization-related-JSON-files.md)
* [Map-related JSON files](Map-related-JSON-files.md)
* [Unit-related JSON files](Unit-related-JSON-files.md)
* [Miscellaneous JSON files](Miscellaneous-JSON-files.md)

28
Making-a-new-Civilization.md

@ -10,18 +10,20 @@ Each civ has some basic information - what the civ name is, the leader's name, c
In addition, each civ has flavor text when declaring war, intoduction etc.
All of these need to be filled in in [Nations.json](/android/assets/jsons/Nations.json)
All of these need to be filled in in [Nations.json](https://github.com/${GITHUB_REPOSITORY}/tree/master/android/assets/jsons/Civ%20V%20-%20Gods%20&%20Kings/Nations.json)
Adding your Civ and leader names in the [Nations translation file](/android/assets/jsons/Translations/Diplomacy%2CTrade%2CNations.json)
Adding your Civ and leader names in the [Nations translation file](https://github.com/${GITHUB_REPOSITORY}/tree/master/android/assets/jsons/Translations/Diplomacy%2CTrade%2CNations.json)
will notify translators that they should translate them =)
[comment]: <> (TODO: Broken link. Obsolete?)
## Get your Civ icon
Each civ has an icon, like the wreath for Rome, for instant identification.
All of these icons are white on a transparent background, and are 100x100 pixels - see [icon considerations](#icon-considerations) for details
You'll need to put your icon in the [NationIcons folder](/android/Images/NationIcons).
You'll need to put your icon in the [NationIcons folder](https://github.com/${GITHUB_REPOSITORY}/tree/master/android/Images/NationIcons).
Same as with the nation name and leader name, the unique ability should also be put in the Nations translation file for bonus points =)
@ -32,26 +34,30 @@ But apart from the flavor, they are boring gameplay-wise, so now we need to add
## Adding unique units
Units in general are added in the [Units.json](/android/assets/jsons/Units.json) file, with an icon in the
[UnitIcons](/android/Images/UnitIcons) folder.
Units in general are added in the [Units.json](https://github.com/${GITHUB_REPOSITORY}/tree/master/android/assets/jsons/Civ%20V%20-%20Gods%20&%20Kings/Units.json) file, with an icon in the
[UnitIcons](https://github.com/${GITHUB_REPOSITORY}/tree/master/android/Images.Construction/UnitIcons) folder.
The icon must be 200x200 pixels, white on transparent background - see [icon considerations](#icon-considerations) for details
Remember that these are unique units, so search for an existing unique unit to see how they replace their regular counterparts!
Again, [translation file](/android/assets/jsons/Translations/Units%2CPromotions.json) for bonus points!
Again, [translation file](https://github.com/${GITHUB_REPOSITORY}/tree/master/android/assets/jsons/Translations/Units%2CPromotions.json) for bonus points!
[comment]: <> (TODO: Broken link. Obsolete? AFAIK translation's only via `template.properties` &#40;and automatic stuff from JSONs&#41; nowadays.)
## Adding unique buildings
Same as the units - info is in the [Buildings.json](/android/assets/jsons/Buildings.json) file
and icons in the [BuildingIcons](/android/Images/BuildingIcons) folder,
Same as the units - info is in the [Buildings.json](https://github.com/${GITHUB_REPOSITORY}/tree/master/android/assets/jsons/Civ%20V%20-%20Gods%20&%20Kings/Buildings.json) file
and icons in the [BuildingIcons](https://github.com/${GITHUB_REPOSITORY}/tree/master/android/Images.Construction/BuildingIcons) folder,
same rules for the icons apply (200x200 pixels, icon considerations)
Again, [translation file](/android/assets/jsons/Translations/Buildings.json) for bonus points!
Again, [translation file](https://github.com/${GITHUB_REPOSITORY}/tree/master/android/assets/jsons/Translations/Buildings.json) for bonus points!
[comment]: <> (TODO: Broken link. Obsolete? AFAIK translation's only via `template.properties` &#40;and automatic stuff from JSONs&#41; nowadays.)
## Civ Unique
Check out our [list of uniques](../wiki/uniques) to see all the cool special effects you can add to your civilization!
Check out our [list of uniques](./Uniques) to see all the cool special effects you can add to your civilization!
## Icon considerations
@ -61,4 +67,4 @@ Icons directly from the base game belong to Firaxis, so I'm not sure we're legal
One source I use constantly is [The Noun Project](https://thenounproject.com) - everything there is Creative Commons or open, so they can all be used!
Credits for icons should go in the [Credits](Credits.md) page
Credits for icons should go in the [Credits](https://github.com/${GITHUB_REPOSITORY}/tree/master/docs/Credits.md) page

70
Making-a-new-Civilization.mde Normal file

@ -0,0 +1,70 @@
# Making a new Civilization
So you want to add your favorite civilization?
There are a few steps required, so we'll walk you through them!
## Fill in your Nation info
Each civ has some basic information - what the civ name is, the leader's name, colors and city names.
In addition, each civ has flavor text when declaring war, intoduction etc.
All of these need to be filled in in [Nations.json](/android/assets/jsons/Civ%20V%20-%20Gods%20&%20Kings/Nations.json)
Adding your Civ and leader names in the [Nations translation file](/android/assets/jsons/Translations/Diplomacy%2CTrade%2CNations.json)
will notify translators that they should translate them =)
[comment]: <> (TODO: Broken link. Obsolete?)
## Get your Civ icon
Each civ has an icon, like the wreath for Rome, for instant identification.
All of these icons are white on a transparent background, and are 100x100 pixels - see [icon considerations](#icon-considerations) for details
You'll need to put your icon in the [NationIcons folder](/android/Images/NationIcons).
Same as with the nation name and leader name, the unique ability should also be put in the Nations translation file for bonus points =)
Congrats, your Civ is now fully playable!
But apart from the flavor, they are boring gameplay-wise, so now we need to add unique abilities!
## Adding unique units
Units in general are added in the [Units.json](/android/assets/jsons/Civ%20V%20-%20Gods%20&%20Kings/Units.json) file, with an icon in the
[UnitIcons](/android/Images.Construction/UnitIcons) folder.
The icon must be 200x200 pixels, white on transparent background - see [icon considerations](#icon-considerations) for details
Remember that these are unique units, so search for an existing unique unit to see how they replace their regular counterparts!
Again, [translation file](/android/assets/jsons/Translations/Units%2CPromotions.json) for bonus points!
[comment]: <> (TODO: Broken link. Obsolete? AFAIK translation's only via `template.properties` &#40;and automatic stuff from JSONs&#41; nowadays.)
## Adding unique buildings
Same as the units - info is in the [Buildings.json](/android/assets/jsons/Civ%20V%20-%20Gods%20&%20Kings/Buildings.json) file
and icons in the [BuildingIcons](/android/Images.Construction/BuildingIcons) folder,
same rules for the icons apply (200x200 pixels, icon considerations)
Again, [translation file](/android/assets/jsons/Translations/Buildings.json) for bonus points!
[comment]: <> (TODO: Broken link. Obsolete? AFAIK translation's only via `template.properties` &#40;and automatic stuff from JSONs&#41; nowadays.)
## Civ Unique
Check out our [list of uniques](./Uniques) to see all the cool special effects you can add to your civilization!
## Icon considerations
ALL icons must be legally acceptable, meaning they either come from from open sources or you act according to their licence (for Creative Commons, for instance, you have to specify the source and the creator).
Icons directly from the base game belong to Firaxis, so I'm not sure we're legally allowed to use them - please use other sources!
One source I use constantly is [The Noun Project](https://thenounproject.com) - everything there is Creative Commons or open, so they can all be used!
Credits for icons should go in the [Credits](/docs/Credits.md) page

16
Map-related-JSON-files.md

@ -23,8 +23,8 @@ Each terrain entry can have the following properties:
| 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#terrain-uniques) |
| civilopediaText | List | Default empty | see [civilopediaText chapter](Miscellaneous-JSON-files#civilopedia-text) |
| uniques | List | Default empty | List of effects, [see here](Uniques.md#terrain-uniques) |
| civilopediaText | List | Default empty | see [civilopediaText chapter](Miscellaneous-JSON-files.md#civilopedia-text) |
Note that many Natural Wonders have hardcoded routines for their placement and are recognized by name (e.g. Great Barrier Reef being more than one tile).
@ -43,9 +43,9 @@ Each improvement can have the following properties:
| 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](Uniques#improvement-uniques) |
| uniques | List | Default empty | List of effects, [see here](Uniques.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](Miscellaneous-JSON-files#civilopedia-text) |
| civilopediaText | List | Default empty | see [civilopediaText chapter](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.
@ -70,12 +70,12 @@ Each resource can have the following properties:
| 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](Uniques#resource-uniques) - at the moment only one unique may be added |
| civilopediaText | List | Default empty | see [civilopediaText chapter](Miscellaneous-JSON-files#civilopedia-text) |
| unique | String | Default empty | Effects, [see here](Uniques.md#resource-uniques) - at the moment only one unique may be added |
| civilopediaText | List | Default empty | see [civilopediaText chapter](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)
[Link to original](https://github.com/${GITHUB_REPOSITORY}/tree/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.
@ -86,7 +86,7 @@ Each of the objects in the file represents a single reward you can get from ruin
| 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](Uniques#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. |
| uniques | List of Strings | defaults to none | [uniques]Uniques#one-time-effect) or [uniques](Uniques.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 |

156
Map-related-JSON-files.mde Normal file

@ -0,0 +1,156 @@
* [Terrains.json](#terrainsjson)
* [TileResources.json](#tileresourcesjson)
* [TileImprovements.json](#tileimprovementsjson)
* [Ruins.json](#ruinsjson)
* [Tileset-specific json](#tileset-specific-json)
## 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](#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](Miscellaneous-JSON-files.md#civilopedia-text) |
Note that many Natural Wonders have hardcoded routines for their placement and are recognized by name (e.g. Great Barrier Reef being more than one tile).
## 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](#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](Uniques.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](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.
## 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](#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](Uniques.md#resource-uniques) - at the moment only one unique may be added |
| civilopediaText | List | Default empty | see [civilopediaText chapter](Miscellaneous-JSON-files.md#civilopedia-text) |
## Ruins.json
[Link to original](/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.
Each of the objects in the file represents a single reward you can get from ruins. It has the following properties:
| attribute | Type | optional or not | 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](Uniques.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 |
* 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:
```json
"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:
```json
"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 😁.

22
Miscellaneous-JSON-files.md

@ -6,7 +6,7 @@
## Difficulties.json
[Link to original](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Vanilla/Difficulties.json)
[Link to original](https://github.com/${GITHUB_REPOSITORY}/tree/master/android/assets/jsons/Civ%20V%20-%20Vanilla/Difficulties.json)
This file defines the difficulty levels a player can choose when starting a new game.
@ -22,7 +22,7 @@ Each difficulty level can have the following attributes:
| policyCostModifier | Float | Default 1 |
| unhappinessModifier | Float | Default 1 |
| barbarianBonus | Float | Default 0 |
| playerBonusStartingUnits | List of Units | Default empty | Can also be 'Era Starting Unit', maps to `startingMilitaryUnit` of the Eras file. All other units must be in [Units.json](/yairm210/Unciv/wiki/Unit-related-JSON-files#unitsjson)] |
| playerBonusStartingUnits | List of Units | Default empty | Can also be 'Era Starting Unit', maps to `startingMilitaryUnit` of the Eras file. All other units must be in [Units.json](./Unit-related-JSON-files#unitsjson)] |
| aiCityGrowthModifier | Float | Default 1 |
| aiUnitCostModifier | Float | Default 1 |
| aiBuildingCostModifier | Float | Default 1 |
@ -39,7 +39,7 @@ Each difficulty level can have the following attributes:
## Eras.json
[Link to original](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Vanilla/Eras.json)
[Link to original](https://github.com/${GITHUB_REPOSITORY}/tree/master/android/assets/jsons/Civ%20V%20-%20Vanilla/Eras.json)
This file should contain all the era's you want to use in your mod.
@ -51,11 +51,11 @@ Each era can have the following attributes:
| iconRGB | List of 3 Integers | defaults to [255,255,255] | RGB color that icons for technologies of this era should have in the Tech screen |
| unitBaseBuyCost | Integer (≥0) | defaults to 200 | Base cost of buying units with Faith, Food, Science or Culture when no other cost is provided |
| startingSettlerCount | Integer (≥0) | defaults to 1 | Amount of settler units that should be spawned when starting a game in this era |
| startingSettlerUnit | String | defaults to "Settler" | Name of the unit that should be used for the previous field. Must be in [Units.json](/yairm210/Unciv/wiki/Unit-related-JSON-files#unitsjson) |
| startingSettlerUnit | String | defaults to "Settler" | Name of the unit that should be used for the previous field. Must be in [Units.json](./Unit-related-JSON-files#unitsjson) |
| startingWokerCount | Integer (≥0) | defaults to 0 | Amount of worker units that should be spawned when starting a game in this era |
| startingWorkerUnit | String | defaults to "Worker" | Name of the unit that should be used for the previous field. Must be in [Units.json](/yairm210/Unciv/wiki/Unit-related-JSON-files#unitsjson) |
| startingWorkerUnit | String | defaults to "Worker" | Name of the unit that should be used for the previous field. Must be in [Units.json](./Unit-related-JSON-files#unitsjson) |
| startingMilitaryUnitCount | Integer (≥0) | defaults to 1 | Amount of military units that should be spawned when starting a game in this era |
| startingMilitaryUnit | String | defaults to "Warrior" | Name of the unit that should be used for the previous field. Must be in [Units.json](/yairm210/Unciv/wiki/Unit-related-JSON-files#unitsjson)|
| startingMilitaryUnit | String | defaults to "Warrior" | Name of the unit that should be used for the previous field. Must be in [Units.json](./Unit-related-JSON-files#unitsjson)|
| startingGold | Integer (≥0) | defaults to 0 | Amount of gold each civ should receive when starting a game in this era |
| startingCulture | Integer (≥0) | defaults to 0 | Amount of culture each civ should receive when starting a game in this era |
| settlerPopulation | Integer (>0) | defaults to 1 | Default amount of population each city should have when settled when starting a game in this era |
@ -73,11 +73,11 @@ The file can have the following attributes, including the values Unciv sets (no
|-----------|------|-----------|-------|
| isBaseRuleset | Boolean | false | Differentiates mods that change the vanilla ruleset or replace it |
| maxXPfromBarbarians | Integer | 30 | ...as the name says... |
| uniques | List | empty | Mod-wide specials, [see here](/yairm210/Unciv/wiki/Uniques/#modoptions-uniques) |
| techsToRemove | List | empty | List of [Technologies](/yairm210/Unciv/wiki/Civilization-related-JSON-files#techsjson) to remove (isBaseRuleset=false only) |
| buildingsToRemove | List | empty | List of [Buildings or Wonders](/yairm210/Unciv/wiki/Civilization-related-JSON-files#buildingsjson) to remove (isBaseRuleset=false only) |
| unitsToRemove | List | empty | List of [Units](/yairm210/Unciv/wiki/Unit-related-JSON-files#unitsjson) to remove (isBaseRuleset=false only) |
| nationsToRemove | List | empty | List of [Nations](/yairm210/Unciv/wiki/Civilization-related-JSON-files#nationsjson) to remove (isBaseRuleset=false only) |
| uniques | List | empty | Mod-wide specials, [see here](./Uniques#modoptions-uniques) |
| techsToRemove | List | empty | List of [Technologies](./Civilization-related-JSON-files#techsjson) to remove (isBaseRuleset=false only) |
| buildingsToRemove | List | empty | List of [Buildings or Wonders](./Civilization-related-JSON-files#buildingsjson) to remove (isBaseRuleset=false only) |
| unitsToRemove | List | empty | List of [Units](./Unit-related-JSON-files#unitsjson) to remove (isBaseRuleset=false only) |
| nationsToRemove | List | empty | List of [Nations](./Civilization-related-JSON-files#nationsjson) to remove (isBaseRuleset=false only) |
| lastUpdated | String | empty | Set automatically after download - Last repository update, not necessarily last content change |
| modUrl | String | empty | Set automatically after download - URL of repository |
| author | String | empty | Set automatically after download - Owner of repository |

116
Miscellaneous-JSON-files.mde Normal file

@ -0,0 +1,116 @@
* [Difficulties.json](#difficultiesjson)
* [Eras.json](#erasjson)
* [ModOptions.json](#modoptionsjson)
* [Generic Civilopedia Text](#civilopedia-text)
## Difficulties.json
[Link to original](/android/assets/jsons/Civ%20V%20-%20Vanilla/Difficulties.json)
This file defines the difficulty levels a player can choose when starting a new game.
Each difficulty level can have the following attributes:
| Attribute | Type | Mandatory | Notes |
| --------- | ---- | ------- | ----- |
| name | String | Required | Name of the difficulty level |
| baseHappiness | Integer | Default 0 |
| extraHappinessPerLuxury | Float | Default 0 |
| researchCostModifier | Float | Default 1 |
| unitCostModifier | Float | Default 1 |
| buildingCostModifier | Float | Default 1 |
| policyCostModifier | Float | Default 1 |
| unhappinessModifier | Float | Default 1 |
| barbarianBonus | Float | Default 0 |
| playerBonusStartingUnits | List of Units | Default empty | Can also be 'Era Starting Unit', maps to `startingMilitaryUnit` of the Eras file. All other units must be in [Units.json](./Unit-related-JSON-files#unitsjson)] |
| aiCityGrowthModifier | Float | Default 1 |
| aiUnitCostModifier | Float | Default 1 |
| aiBuildingCostModifier | Float | Default 1 |
| aiWonderCostModifier | Float | Default 1 |
| aiBuildingMaintenanceModifier | Float | Default 1 |
| aiUnitMaintenanceModifier | Float | Default 1 |
| aiFreeTechs | List of Techs | Default empty |
| aiMajorCivBonusStartingUnits | List of Units | Default empty | See above |
| aiCityStateBonusStartingUnits | List of Units | Default empty | See above |
| aiUnhappinessModifier | Float | Default 1 |
| aisExchangeTechs | Boolean | | Unimplemented |
| turnBarbariansCanEnterPlayerTiles | Integer | Default 0 |
| clearBarbarianCampReward | Integer | Default 25 |
## Eras.json
[Link to original](/android/assets/jsons/Civ%20V%20-%20Vanilla/Eras.json)
This file should contain all the era's you want to use in your mod.
Each era can have the following attributes:
| attribute | Type | optional or not | notes |
| --------- | ---- | --------------- | ----- |
| name | String | required | Name of the era |
| researchAgreementCost | Integer (≥0) | defaults to 300 | Cost of research agreements were the most technologically advanced civ is in this era |
| iconRGB | List of 3 Integers | defaults to [255,255,255] | RGB color that icons for technologies of this era should have in the Tech screen |
| unitBaseBuyCost | Integer (≥0) | defaults to 200 | Base cost of buying units with Faith, Food, Science or Culture when no other cost is provided |
| startingSettlerCount | Integer (≥0) | defaults to 1 | Amount of settler units that should be spawned when starting a game in this era |
| startingSettlerUnit | String | defaults to "Settler" | Name of the unit that should be used for the previous field. Must be in [Units.json](./Unit-related-JSON-files#unitsjson) |
| startingWokerCount | Integer (≥0) | defaults to 0 | Amount of worker units that should be spawned when starting a game in this era |
| startingWorkerUnit | String | defaults to "Worker" | Name of the unit that should be used for the previous field. Must be in [Units.json](./Unit-related-JSON-files#unitsjson) |
| startingMilitaryUnitCount | Integer (≥0) | defaults to 1 | Amount of military units that should be spawned when starting a game in this era |
| startingMilitaryUnit | String | defaults to "Warrior" | Name of the unit that should be used for the previous field. Must be in [Units.json](./Unit-related-JSON-files#unitsjson)|
| startingGold | Integer (≥0) | defaults to 0 | Amount of gold each civ should receive when starting a game in this era |
| startingCulture | Integer (≥0) | defaults to 0 | Amount of culture each civ should receive when starting a game in this era |
| settlerPopulation | Integer (>0) | defaults to 1 | Default amount of population each city should have when settled when starting a game in this era |
| settlerBuildings | List of Strings | defaults to none | Buildings that should automatically be built whenever a city is settled when starting a game in this era |
| startingObsoleteWonders | List of Strings | defaults to none | Wonders (and technically buildings) that should be impossible to built when starting a game in this era. Used in the base game to remove all wonders older than 2 era's |
## 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
The file can have the following attributes, including the values Unciv sets (no point in a mod author setting those):
| Attribute | Type | Defaults | Notes |
|-----------|------|-----------|-------|
| isBaseRuleset | Boolean | false | Differentiates mods that change the vanilla ruleset or replace it |
| maxXPfromBarbarians | Integer | 30 | ...as the name says... |
| uniques | List | empty | Mod-wide specials, [see here](./Uniques#modoptions-uniques) |
| techsToRemove | List | empty | List of [Technologies](./Civilization-related-JSON-files#techsjson) to remove (isBaseRuleset=false only) |
| buildingsToRemove | List | empty | List of [Buildings or Wonders](./Civilization-related-JSON-files#buildingsjson) to remove (isBaseRuleset=false only) |
| unitsToRemove | List | empty | List of [Units](./Unit-related-JSON-files#unitsjson) to remove (isBaseRuleset=false only) |
| nationsToRemove | List | empty | List of [Nations](./Civilization-related-JSON-files#nationsjson) to remove (isBaseRuleset=false only) |
| lastUpdated | String | empty | Set automatically after download - Last repository update, not necessarily last content change |
| modUrl | String | empty | Set automatically after download - URL of repository |
| author | String | empty | Set automatically after download - Owner of repository |
| modSize | Integer | empty | Set automatically after download - kB in entire repository, not sum of default branch files |
## 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:
```json
"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:
|attribute|type|description|
|---------|----|-----------|
|`text`|String|Text to display.|
|`link`|String|Create link and icon, format: Category/Name or _external_ link ('http://','https://','mailto:').|
|`icon`|String|Show icon without linking, format: Category/Name.|
|`extraImage`|String|Display an Image instead of text. Can be a path found in a texture atlas or or the name of a png or jpg in the ExtraImages folder.|
|`imageSize`|Float|Width in world units of the [extraImage], height is calculated preserving aspect ratio. Defaults to available width.|
|`header`|Integer|Header level. 1 means double text size and decreases from there.|
|`size`|Integer|Text size, default is 18. Use `size` or `header` but not both.|
|`indent`|Integer|Indent level. 0 means text will follow icons, 1 aligns to the right of all icons, each further step is 30 units.|
|`padding`|Float|Vertical padding between rows, defaults to 5 units.|
|`color`|String|Sets text color, accepts names or 6/3-digit web colors (e.g. #FFA040).|
|`separator`|Boolean|Renders a separator line instead of text. Can be combined only with `color` and `size` (line width, default 2).|
|`starred`|Boolean|Decorates text with a star icon - if set, it receives the `color` instead of the text.|
|`centered`|Boolean|Centers the line (and turns off automatic wrap).|
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.

10
Mods.md

@ -35,8 +35,8 @@ Mods need to conform to github repo naming rules, but best stay simple and use o
Mods are located in a `/mods` directory, on Desktop that should be next to your .jar file.
Mods typically have 2 subfolders:
- jsons - here you should put files that alter the data of game objects, the order of the files is as in [the base json files](https://github.com/yairm210/Unciv/tree/master/android/assets/jsons). More information on these can be found [here](/yairm210/Unciv/wiki/JSON-files-for-mods)
- Images - here you should put game images, as in [the base image files](https://github.com/yairm210/Unciv/tree/master/android/Images). Please read the [atlas chapter](#more-on-images-and-the-texture-atlas) for important details.
- jsons - here you should put files that alter the data of game objects, the order of the files is as in [the base json files](https://github.com/${GITHUB_REPOSITORY}/tree/master/android/assets/jsons). More information on these can be found [here](./JSON-files-for-mods)
- Images - here you should put game images, as in [the base image files](https://github.com/${GITHUB_REPOSITORY}/tree/master/android/Images). Please read the [atlas chapter](#more-on-images-and-the-texture-atlas) for important details.
In order to remove objects from the game, you'll need to create a ModOptions file in the `/jsons` subfolder - there's an example [here](https://github.com/yairm210/Unciv-mod-example/blob/master/Removing%20Things/jsons/ModOptions.json)
@ -44,7 +44,7 @@ In a base ruleset mod, ALL the original objects are removed - this is done by ad
For an example, you can refer to [the example mod](https://github.com/yairm210/Unciv-mod-example) - just download the Example-Aliens-Mod and put it in a `/mods` folder next to the jar, run Unciv, start a new game, and you'll be able to enable the mod, which will allow to you pick Aliens as a playable civilization!
If you want to add a new civilization as a mod, you should check out [the Civ making instructions](https://github.com/yairm210/Unciv/wiki/Making-a-new-Civilization) to see what's required, or see the example Aliens mod =)
If you want to add a new civilization as a mod, you should check out [the Civ making instructions](./Making-a-new-Civilization) to see what's required, or see the example Aliens mod =)
### More on Images and the texture atlas
Images are combined (at runtime) into texture images with an 'atlas', so if you see "game.atlas" and "game.png" files being generated, now you know what for. Most mods will need only one pair of those, the base game has around four.
@ -108,6 +108,6 @@ When loading a mod, it needs to be in its own folder in `/mods` - this is how yo
Existing mods can be found [here](https://github.com/topics/unciv-mod)!
A list of uniques and how to use them can be found [here](uniques)!
A list of uniques and how to use them can be found [here](./Uniques)!
Some images don't exist at all in the base game, but can be added in mods. For more info, see [Audiovisual Mods](./Audiovisual-Mods).
Some images don't exist at all in the base game, but can be added in mods. For more info, see [Audiovisual Mods](./Audiovisual-Mods).

113
Mods.mde Normal file

@ -0,0 +1,113 @@
## What's this about?
Everyone has that thing they wish could be in the game.
Unfortunately, the game only understands code, so mods are our way to give a degree of freedom to those of us who don't code.
Mods can *add, replace and remove* basic game definitions, such as units, nations, buildings, improvements, resources and terrains.
Games loaded with these mods will function according to the mod definition.
The game only knows how to recognize existing definitions, so you can't add *new* unique abilities to nations/units/buildings/etc, only play around with existing ones
There are two kinds of mods:
- Extension mods - these add new nations/units/buildings/resources to a base ruleset - can be either to the default ruleset, or to a base ruleset mod. Easy to do and probably the better place to get started.
- Base Ruleset mods - these replace the entire existing ruleset - tech tree, units, policies, nations etc - to give an entirely different experience than the base game. These generally require quite a bit of work, but give a whole new experience, and so are the most popular.
Creating and editing mods from your phone is NOT RECOMMENDED - it's *much easier* using a desktop device!
## Audiovisual Mods
I addition to changing the rules - or even without doing so, mods can override existing graphics or sounds, or add music tracks. The game also has the ability to display graphics that are not included in the base game at all, such as leader portrait or wonder splash images, that must be provided by mods. For details, see [Audiovisual Mods](./Audiovisual-Mods).
Custom tilesets are closely related, see [Creating a custom tileset](./Creating-a-custom-tileset).
Such mods are candidates for the "Permanent audiovisual mod" switch available on the Mod Management Screen. Note that this feature includes graphics or sounds from the selected mod in _all_ games, even those started before installing the mod. In case of a mod bringing both changed rules and audiovisuals, the 'permanent' feature will include only the media on all games, to use the rules you will still need to select the mod for a new game.
## Mod names
Mods need to conform to github repo naming rules, but best stay simple and use only letters, digits, and dashes `-`. Dashes are _automatically_ converted to spaces for display and use within Unciv. Many punctuation or extended unicode characters _might_ work, but at best potential users won't find them attractive, at worst we'll refuse support when you run into problems :smiling_imp:
## Mod components
Mods are located in a `/mods` directory, on Desktop that should be next to your .jar file.
Mods typically have 2 subfolders:
- jsons - here you should put files that alter the data of game objects, the order of the files is as in [the base json files](/android/assets/jsons). More information on these can be found [here](./JSON-files-for-mods)
- Images - here you should put game images, as in [the base image files](/android/Images). Please read the [atlas chapter](#more-on-images-and-the-texture-atlas) for important details.
In order to remove objects from the game, you'll need to create a ModOptions file in the `/jsons` subfolder - there's an example [here](https://github.com/yairm210/Unciv-mod-example/blob/master/Removing%20Things/jsons/ModOptions.json)
In a base ruleset mod, ALL the original objects are removed - this is done by adding a `"isBaseRuleset":true` configuration to your modOptions file, [like so](https://github.com/k4zoo/Civilization-6-Mod/blob/master/jsons/ModOptions.json)
For an example, you can refer to [the example mod](https://github.com/yairm210/Unciv-mod-example) - just download the Example-Aliens-Mod and put it in a `/mods` folder next to the jar, run Unciv, start a new game, and you'll be able to enable the mod, which will allow to you pick Aliens as a playable civilization!
If you want to add a new civilization as a mod, you should check out [the Civ making instructions](./Making-a-new-Civilization) to see what's required, or see the example Aliens mod =)
### More on Images and the texture atlas
Images are combined (at runtime) into texture images with an 'atlas', so if you see "game.atlas" and "game.png" files being generated, now you know what for. Most mods will need only one pair of those, the base game has around four.
When the game runs from a packaged distribution (android, jar), the texture+atlas files alone are relevant, so you need to include them in your repository and keep them up to date. Actually omitting the original images would work for these uses, but we still recommend including them, so developers running from source can access them.
If your mod has lots of images (or large ones), the textures might 'spill' into additional texture ".png" files - 2048x2048 is the limit for a single texture pack. This is not good for performance, which is why the base game controls which kinds of images go together into one texture(+atlas). This works for mods, too: Create not only one Images folder, but several, the additional ones named "Images.xyz", where xyz will become the filename of the additional texture file (So don't use both Images and Images.game - those will clash). Look at the Unciv base game to get a better idea how that works. To minimize texture swaps, try to group them by the situation where in the game they are needed. You can distibute by folder, but having the same subfolders under several "Images.xyz" and distributing the images between them will also work.
### Adding maps to mods
You can also add maps to mods, so they'll be available to players who download your mod.
A mod can also be maps-only, if all you want to do is share your maps.
When you've finished making your map in the Map Editor, save it, and it will be in the `/maps` folder of your game.
Copy it to a `/maps` folder in your *mod*, and you're done!
## Getting your mod out there
In order to make your mod downloadable by anyone, you need to create a Github repository (instructions [here](https://docs.github.com/en/github/getting-started-with-github/create-a-repo))
The Images and jsons folders need to be in the root directory of the repo - see [here](https://github.com/yairm210/Unciv-IV-mod) for example.
You can then manually download the mod from within the Mod Manager in Unciv:
- From Unciv's main screen, click "Mods"
- Click "Download mod from URL", and enter the location of your Github page
- The game will automatically download and extract your mod, and it'll be ready to use!
Once you've tested that your mod CAN be downloaded, and that it works well once downloaded, you're ready for the final stage - GETTING IT TO THE USERS AUTOMATICALLY.
In order to do this, all you need to do is:
- Go to your Github page
- Click the gear icon next to the About (top-right part of the page)
- In 'Topics', add "unciv-mod"
When you open your app, it will query Github's [list of repos with that topic](https://github.com/topics/unciv-mod), and now YOUR repo will appear there!
## I have the mod, now what?
The primary use of mods is to add them when starting a new game, or configuring a map. This will mean that both the ruleset of the mod, and the images, will be in use for that specific game/map.
For mods which are primarily visual or audio, there is a second use - through the mod manager, you can enable them as **permanent audiovisual mods**. This means that the images, sounds (or upcoming: music) from the mod will replace the original media everywhere in the game.
## Mod location for manual loading of mods
In general, you should never be manually-loading your mods - not only is this clunky, it's also more error-prone. Unless you have a very specific use-case, you probably shouldn't be doing this.
In Android, they should go into the `Android/data/com.unciv.app/files/mods` directory.
In Chromebook, go to "Play files", should be on the sidebar on the left side of the window under "My files".
Click the 3 vertical dots on the top right-hand corner of the window below the "X".
If the option "Show all Play folders" does not have a check next to it click it. You should see some new files that appear on your screen.
*Now* navigate to `Android/data/com.unciv.app/files/mods`
When loading a mod, it needs to be in its own folder in `/mods` - this is how you will work when you're editing your mod.
## Other
Existing mods can be found [here](https://github.com/topics/unciv-mod)!
A list of uniques and how to use them can be found [here](./Uniques)!
Some images don't exist at all in the base game, but can be added in mods. For more info, see [Audiovisual Mods](./Audiovisual-Mods).

10
Project-structure-and-major-classes.md

@ -2,14 +2,14 @@
Since LibGDX, and therefore Unciv, are built for multi-platform support, the project structure is built accordingly.
99% of the code is in the [Core](https://github.com/yairm210/Unciv/tree/master/core/src/com/unciv) project, which contains all the platform-independant code.
99% of the code is in the [Core](https://github.com/${GITHUB_REPOSITORY}/tree/master/core/src/com/unciv) project, which contains all the platform-independant code.
The [Desktop](https://github.com/yairm210/Unciv/tree/master/desktop) and [Android](https://github.com/yairm210/Unciv/tree/master/android) folders contain platform-specific things, and the Android folder also contains the game Images and the all-important Assets, which are required for running from Desktop as well, so we bundle them up into the .jar file when releasing.
The [Desktop](https://github.com/${GITHUB_REPOSITORY}/tree/master/desktop) and [Android](https://github.com/${GITHUB_REPOSITORY}/tree/master/android) folders contain platform-specific things, and the Android folder also contains the game Images and the all-important Assets, which are required for running from Desktop as well, so we bundle them up into the .jar file when releasing.
The [Test](https://github.com/yairm210/Unciv/tree/master/tests/src/de/tomgrill/gdxtesting/examples) folder contains tests that can be run manually via gradle with `./gradlew tests:test`, and are run automatically by Travis for every push.
The [Test](https://github.com/${GITHUB_REPOSITORY}/tree/master/tests/src/com/unciv) folder contains tests that can be run manually via gradle with `./gradlew tests:test`, and are run automatically by Travis for every push.
# Translations
Before we get to the Classes, a word on Languages. Unciv is playable in several handfuls of languages, and there's magic to support that. Whenever you include a new string in code you will need to give it a quick evaluation - will users see it, and if so, what do I need to do to support its translations. Sometimes you may not need to do anything, sometimes you will add a line to the [translation templates](../blob/master/android/assets/jsons/translations/template.properties), and sometimes you will adapt the string formatting to support the translations. For details, see [the 'Translation generation - for developers' chapter](./Translating#translation-generation---for-developers).
Before we get to the Classes, a word on Languages. Unciv is playable in several handfuls of languages, and there's magic to support that. Whenever you include a new string in code you will need to give it a quick evaluation - will users see it, and if so, what do I need to do to support its translations. Sometimes you may not need to do anything, sometimes you will add a line to the [translation templates](https://github.com/${GITHUB_REPOSITORY}/tree/master/android/assets/jsons/translations/template.properties), and sometimes you will adapt the string formatting to support the translations. For details, see [the 'Translation generation - for developers' chapter](./Translating#translation-generation---for-developers).
# Major classes
@ -176,4 +176,4 @@ The first is multithreading and thread safety, and the second is multiplayer rep
The first point is pretty basic. The NextTurn needs to happen in a separate thread so that the user can still have a responsive game when it's off doing stuff. Stuff in the GameInfo changes on NextTurn, so if you're rendering that same GameInfo, this could cause conflicts. Also, after NextTurn we generally autosave, and if stuff changes in the state while we're trying to serialize it to put it in the save file, that's Not Fun. A single clone solves both of these problems at once.
The second point is less obvious. If we use our mutable state, changing stuff in place, then what happens when we're playing in Multiplayer? Multiplayer is based upon the fact that you can receive an entire game state and go from there, and in fact the move to multiplayer was what made the whole "clone" thing necessary (on the way it also solved the aforementioned threading problems)
The second point is less obvious. If we use our mutable state, changing stuff in place, then what happens when we're playing in Multiplayer? Multiplayer is based upon the fact that you can receive an entire game state and go from there, and in fact the move to multiplayer was what made the whole "clone" thing necessary (on the way it also solved the aforementioned threading problems)

179
Project-structure-and-major-classes.mde Normal file

@ -0,0 +1,179 @@
# Project structure
Since LibGDX, and therefore Unciv, are built for multi-platform support, the project structure is built accordingly.
99% of the code is in the [Core](/core/src/com/unciv) project, which contains all the platform-independant code.
The [Desktop](/desktop) and [Android](/android) folders contain platform-specific things, and the Android folder also contains the game Images and the all-important Assets, which are required for running from Desktop as well, so we bundle them up into the .jar file when releasing.
The [Test](/tests/src/com/unciv) folder contains tests that can be run manually via gradle with `./gradlew tests:test`, and are run automatically by Travis for every push.
# Translations
Before we get to the Classes, a word on Languages. Unciv is playable in several handfuls of languages, and there's magic to support that. Whenever you include a new string in code you will need to give it a quick evaluation - will users see it, and if so, what do I need to do to support its translations. Sometimes you may not need to do anything, sometimes you will add a line to the [translation templates](/android/assets/jsons/translations/template.properties), and sometimes you will adapt the string formatting to support the translations. For details, see [the 'Translation generation - for developers' chapter](./Translating#translation-generation---for-developers).
# Major classes
Civ, and therefore Unciv, is a game with endless interconnectivity - everything affects everything else.
In order to have some semblance of order, we'll go over the main classes in the order in which they are serialized.
So yes, you can - for instance - get the center tile of a city, a TileInfo, directly from CityInfo. But delving into all the connections would only harm the point of this overview, that's what the actual code is for ;)
The Game State:
* GameInfo
* CivilizationInfo
* CityInfo
* TileMap
* TileInfo
* MapUnit
* RuleSet (unique in that it is not part of the game state)
The UI:
* MainMenuScreen
* NewGameScreen
* WorldScreen
* CityScreen
* MapEditorScreen
* Picker Screens - TechPickerScreen, PolicyPickerScreen, ImprovementPickerScreen, PromotionPickerScreen
# Game State
## The Game - `GameInfo`
First off, let's clarify: When we say "The Game", we mean the *state* of the game (what turn it is, who the players are, what each one has etc) and not the *UI* of the game.
That is, The Game is the *currently played* game, not *Unciv*.
The game contains three major parts:
- The list of the players, or civilizations - `List<CivilizationInfo>`
- The map upon which the game is played - `TileMap`
- The ruleset by which the game is played - `RuleSet`. This includes what technologies, buildings, units etc. are available, and IS NOT serialized and deserialized, but comes straight from the game files - more on that later.
- Parameters unique to this game - difficulty, game speed, victory conditions, etc.
When we save the game, or load the game, we're actually serializing and deserializing this class, which means that the this class is the root of the entire game state.
Most objects in the "state tree" have a transient reference to their parent, meaning the tree can be traversed in-code in all directions, and frequently is.
## A Civilization - `CivilizationInfo`
This represents one of the players of the game, and NOT a specific nation - meaning, not France, but rather "Player X who is France in this game". In another game, there will be another France.
As one of the focal points of the game, it contains a lot of important information, the most important of which are:
- The list of cities the civilization has - `List<CityInfo>`
- Which nation this is - references a certain Nation (part of the ruleset)
- Various Managers for the different aspects of the civilization - `PolicyManager`, `GoldenAgeManager`, `GreatPersonManager`, `TechManager`, `VictoryManager`, `DiplomacyManager`
## A City - `CityInfo`
This contains the information about a specific city.
Beyond basic information like name, location on map etc, the most important classes it contains are:
- Calculating the yield of the city - `CityStats`
- Managers for the various aspects - `PopulationManager`, `CityConstructions`, `CityExpansionManager`
- The tiles controlled and worked by the city - only their locations are permanently saved in the CityInfo, the actual information is in the TileInfo in the TileMap
## The map - `TileMap`
This contains mostly helper functions and acts as a wrapper for the list of tiles it contains
## A tile - `TileInfo`
Each tile is comprised of several layers, and so has information for each.
Tiles have, primarily:
- A base terrain - Grassland, Hills, Desert etc. References a certain `Terrain` (part of the ruleset)
- An optional terrain feature - Forest, Jungle, Oasis etc. References a certain `Terrain` (part of the ruleset)
- An optional resource - Iron, Dye, Wheat etc. References a certain `TileResource` (part of the ruleset)
- An improvement built on the tile, if any. References a certain `TileImprovement` (part of the ruleset)
- The units that are currently in the tile - `MapUnit`
## A unit on the map - `MapUnit`
Unlike buildings, Unit in Unciv has two meanings. One is a *Type* of unit (like Spearman), and one is a specific instance of a unit (say, a Babylonian Spearman, at a certain position, with X health).
`MapUnit` is a specific instance of a unit, whereas `BaseUnit` is the type of unit.
Main information:
- A name - references a specific `BaseUnit`
- Health and Movement
- Promotion status - `UnitPromotions`
## Ruleset
So far so good - but what of everything that makes Civ, Civ? The units, the buildings, the nations, the improvements etc?
Since these things remain the same for every game, these are not saved on a per-game basis, but rather are saved in json files in Unciv's asset folder.
Each class in the game state that saves one of these will reference it by name, and when the game is running it will check the Ruleset to find the relevant information for that object.
The various objects are:
- `Technology` - referenced mainly in `CivilizationInfo.TechManager`
- `Nations` - referenced mainly in `CivilizationInfo`
- `Policy` - referenced mainly in `CivilizationInfo.PolicyManager` (seeing a pattern here?)
- `Building` - referenced mainly in `CityInfo.ConstructionManager`
- `BaseUnit` - referenced mainly in `MapUnit`
- `Promotion` - referenced mainly in `MapUnit`
- `Terrain` - referenced mainly in `TileInfo`
- `TileResource` - referenced mainly in `TileInfo`
- `TileImprovement` - referenced mainly in `TileInfo`
There are also Translations in the Ruleset, but they technically have nothing to do with the game state but rather with the UI display.
The information for all of these is in json files in `android\assets\jsons`
# UI
`UncivGame` is the 'base' class for the UI, from which everything starts, but it itself doesn't do much.
When we change a screen, we're changing a value in UncivGame, the interesting stuff happens in the screens themselves.
## The main menu - `MainMenuScreen`
This is what the user sees when first entering the game. It acts as a hub to loading games, adding mods, options etc, without loading an actual game upfront - this allows us to differentiate between "User can't enter game" and "User can't load game" problems
## Starting a new game - `NewGameScreen`
This is basically a giant setting screen for GameOptions and MapOptions classes, divided into:
* GameOptionsTable - game speed, mods, etc
* MapOptionsTable - either from preexisting map file or generated, in which case: size, map generation type, etc.
* PlayerPickerTable - What civs are in the game and who controls them
## The World Screen - `WorldScreen`
90% of the game is spent on this screen, so naturally it's the fullest, with the most things happening.
This is the main hub of the game, with all other screens being opened from it, and closing back to reveal it.
Most notable are:
* The map itself - a `TileMapHolder` - with each of the rendered tiles being a `TileGroup`
* The information panels - `WorldScreenTopBar` for stats and resources, `UnitTable` for the currently selected unit, `TileInfoTable` or the currently selected tile, `BattleTable` for battle simulation, and `NotificationsScroll` for the notifications
* The minimap - `MinimapHolder`
* Buttons linking to other screens - to the `TechPickerScreen`, `EmpireOverviewScreen`, and `PolicyPickerScreen`
* The almighty Next Turn button
## The city screen - `CityScreen`
The second-most important screen.
Notable parts:
* the City Stats table - should definitely be its own class come to think of it
* The construction list and current construction (bottom left) - `ConstructionsTable`
* Existing buildings, specialists and stats drilldown - `CityInfoTable`
# Others
A few words need to be said about the NextTurn process, but there isn't really a good place for it so I'll put it here.
We clone the GameInfo and use a "new" GameInfo for each turn because of 2 reasons.
The first is multithreading and thread safety, and the second is multiplayer reproducibility.
The first point is pretty basic. The NextTurn needs to happen in a separate thread so that the user can still have a responsive game when it's off doing stuff. Stuff in the GameInfo changes on NextTurn, so if you're rendering that same GameInfo, this could cause conflicts. Also, after NextTurn we generally autosave, and if stuff changes in the state while we're trying to serialize it to put it in the save file, that's Not Fun. A single clone solves both of these problems at once.
The second point is less obvious. If we use our mutable state, changing stuff in place, then what happens when we're playing in Multiplayer? Multiplayer is based upon the fact that you can receive an entire game state and go from there, and in fact the move to multiplayer was what made the whole "clone" thing necessary (on the way it also solved the aforementioned threading problems)

25
Regions.mde Normal file

@ -0,0 +1,25 @@
# Regions
## The Concept
During the generation of a random map (only; not pre-made maps) the map is split into a number of regions equal to the number of major civs. Each region gets classified according to its prevalent terrain, or if unable to be classified is called a "hybrid" region.
The region type corresponds to the start bias of the civs as they are distributed.
The region type also determines start placement and what luxuries will appear in the region.
<details><summary>Example</summary>
![](https://user-images.githubusercontent.com/63475501/140308518-ad5a2f50-d5f1-4467-a296-3a67f6d0b007.png)
</details>
## How to define region behavior in your mod
The game will work without any extra json definitions, but if you want the region system to work well when generating maps for your mod, these are the relevant uniques to define.
### Terrains.json
"Always Fertility [amount] for Map Generation", "[amount] to Fertility for Map Generation" - these determine how good a terrain is for purposes of dividing land up fairly. The numbers are arbitrary but should reflect the relative value of the terrains.
"A Region is formed with at least [amount]% [simpleTerrain] tiles, with priority [amount]",
"A Region is formed with at least [amount]% [simpleTerrain] tiles and [simpleTerrain] tiles, with priority [amount]" - these determine the rules for when a region is classified as eg a "desert" region. Terrains are evaluated in ascending priority order, so in the base ruleset tundra regions are checked first.
"A Region can not contain more [simpleTerrain] tiles than [simpleTerrain] tiles" - a useful compliment to the sum-of-two-terrains criterium above, if both terrains are in and of themselves terrain types. So in the base ruleset a large enough sum of jungle and forest allows a region to be classified as jungle, but only if there is more jungle than forest.
"Base Terrain on this tile is not counted for Region determination" - for terrain features that are unremovable or otherwise dominate the tile. Used for Hills in the base ruleset.
A region not fulfilling any criteria is classified as "Hybrid"
"Considered [terrainQuality] when determining start locations" - where "terrainQuality" is one of "Food", "Production", "Desirable", "Undesirable". Usually used together with the "<in [regionType] Regions>" or "<in all except [regionType] Regions>" to determine what terrain is attractive when determining start locations. Note: if there are none of these for a terrain, the game will use the base stats of the terrain to guess a quality, but if there are any, the game will assume that they are complete.

4
Translating.md

@ -77,6 +77,6 @@ Leading spaces on a translation line or more than one space between the text and
Translation templates can use placeholders, and there's two varieties: `[]` and `{}`. Square ones take precedence over curly ones, and nesting works only with a single level of curly nested inside one level of square. I both cases the symbols themselves (`[]{}`) are removed by the translation engine.
Square brackets `[]` mean the outer and inner components are both translated individually. The outer template will use alias names inside the brackets - example: Your code outputs "Everyone gains [5000] gold!", then the translation template should be "Everyone gains [amount] gold! = ". The translation engine would translate the "Everyone gains [] gold!" and "5000" individually and reassemble them - of course, the number is simply passed through. But in other cases that could be e.g. a Unit name that would be translated, and you could trust that translations for units are already handled just fine. Note that [uniques](https://github.com/yairm210/Unciv/wiki/Uniques) often use the feature, but it is in no way limited to them. It it makes life easier for translators, use it.
Square brackets `[]` mean the outer and inner components are both translated individually. The outer template will use alias names inside the brackets - example: Your code outputs "Everyone gains [5000] gold!", then the translation template should be "Everyone gains [amount] gold! = ". The translation engine would translate the "Everyone gains [] gold!" and "5000" individually and reassemble them - of course, the number is simply passed through. But in other cases that could be e.g. a Unit name that would be translated, and you could trust that translations for units are already handled just fine. Note that [uniques](./Uniques) often use the feature, but it is in no way limited to them. It it makes life easier for translators, use it.
Curly brackets `{}` are simpler - the contents within the brackets are translated individually, while the outer parts are passed through verbatim. Example: `"+$amount${Fonts.gold} {Gold}".toLabel()` - note the first `${}` is a kotlin template while the second pair becomes part of the string. It tells the translation engine to ignore the numbers and the symbol but to translate the single word "Gold".
Curly brackets `{}` are simpler - the contents within the brackets are translated individually, while the outer parts are passed through verbatim. Example: `"+$amount${Fonts.gold} {Gold}".toLabel()` - note the first `${}` is a kotlin template while the second pair becomes part of the string. It tells the translation engine to ignore the numbers and the symbol but to translate the single word "Gold".

82
Translating.mde Normal file

@ -0,0 +1,82 @@
## Starting out
The translation files are at https://github.com/yairm210/Unciv/tree/master/android/assets/jsons/translations
If you're adding a new language, you'll need to create a new file ('Create a new file' to the right of the folder name in the UI), and copy into it the contents of template.properties
If you're adding stuff to an existing language, simply start editing the file!
You don't need to download anything, all translation work can be done on the Github website :)
When you feel that you're ready to add your translation to the game, you'll need to create a merge request, which takes your changes and puts them into the main version of the game - it's pretty straightforward once you do it
## Pitfalls
- If a translation template (the stuff to the left of "` = `") contains square brackets, you will have to include each of them _verbatim_ in your translation, but you can move them. Upper/lower case is relevant! e.g. `All [personFilter] are cool` can be translated as `Tous les [personFilter] sont cool`, but ***not*** as `Tous les [personnages] sont cool`, and neither as `Nous sommes vraiment cool`. Failing this is the main cause of your PR's showing up with red "x"es and "checks failed".
- Blanks: Watch out for blanks at the start of a line or two of them before the equals sign. If you got such a line - those blanks are part of the translation key and must not be deleted on the left side, and you should probably also include them in your translation (unless your language doesn't need spaces to separate things).
- Changes in the templates: When we find a typo in the english texts and fix it, or marginally change a wording, the template changes. Often the old template will not be automatically fixed in the existing translations, because it's a lot of work _and_ in most cases the developers cannot be sure the translation is still correct. For you, that might look like your translations are simply disappearing with an update. In such a case, you have the option to use github's history to look up old versions, copy the old translation, place it where the new template now says "requires translation" - and proofread and adapt it to the new english version. The history link for each file is in the top right area and has a nice round clock icon.
## Wait, what just happened?
Like most open-source projects, Unciv is developed at Github, so if you don't have a user you'll first have to create one. The way Github works is the following:
1. You create a 'fork' repo, i.e. copy, of Unciv that belongs to your user (myUser/Unciv)
2. You make changes to your copy. These changes are called a 'commit'.
3. You make a pull request, which is basically asking for the changes you made on myUser/Unciv to be merged into the main repo (yairm210/Unciv)
When you ask to 'edit' a file in yairm210/Unciv, these stages happen *automatically* - but it's important to understand what's happening behind the scenes do you understand where the changes actually are!
## Why not use a crowdsourcing translation website like <...>?
1. Testing. Currently, translations undergo a number of tests for verification. This allows some language changes to be accepted and others not, and it's all in the same platform with the same tests. External translation tools don't allow for this.
2. History and revisions. This is what Git was made for, and nothing like it exists in the world. I'm not exaggerating.
3. Release cycle. We release versions weekly. If we need to take information from an external website every time, and for many that I've checked - you need to download the info as a csv or something and convert it. Every extra step hurts.
4. Discussions. Most crowdsourcing translation websites don't allow for discussions and corrections on translations. Github does.
5. Mass changes. If we're changing the source of the translation but want to keep the various destinations (say, we change "Gold from trade routes +[amount]%" to "+[amount]% Gold from trade routes"), if all the translation files are in Git we can do that in 1 minute. If it's external, this varies greatly.
## Other notes
Make sure that you make the changes in the 'master' branch in your repo!
Each untranslated phrase will have a "requires translation" line before it, so you can quickly find them. You don't need to remove them yourself if you don't want to - they will be automatically removed the next time we rebuild the file.
Do as much as you're comfortable with - it's a big game with a lot of named objects, so don't feel pressured into doing everything =)
Note that Right-to-Left languages such as Arabic and Hebrew are not supported by the framework :/
# Translation generation - for developers
## The automatic template generation
Before releasing every version, we regenerate the translation files.
Sometimes, new strings (names, uniques, etc) are added in the json files. In order to not have to add every single one to the translation files manually, we have a class - TranslationFileWriter - that, for every language:
- Goes over the template.properties and copies translation lines
- For every json file in the jsons folder
- Selects all string values - both in objects, and in arrays in objects
- Generates a 'key = value' line
This means that every text that ISN'T in the jsons needs to be added manually to the template.properties in order to be translated!
That also means if you've been adding new json structures you (or someone) should check TranslationFileWriter and see if it is able to cope with them.
## Rules for templates added manually
Building a new UI and doing something like `popup.add("Hello world".toLabel())` is a typical case: This is not contained in json data, so you'll have to add the template to `template.properties` yourself. For this example, adding `Hello world = ` somewhere in a line of its own could suffice.
Note the space at the end - it's absolutely required, and see to it your editor does not destroy your work. If you want to make sure, use Android Studio for git integration, but edit the file in an external editor, then run the unit tests locally before pushing. (to do: add link for instructions how to do that)
Leading spaces on a translation line or more than one space between the text and the `=` would mean these spaces are a _key part of the string to be translated_. That can work, but be warned: translators often overlook that those spaces are a required part of _both_ template _and_ translation, so if you _can_ do without, then doing without is safer.
Translation templates can use placeholders, and there's two varieties: `[]` and `{}`. Square ones take precedence over curly ones, and nesting works only with a single level of curly nested inside one level of square. I both cases the symbols themselves (`[]{}`) are removed by the translation engine.
Square brackets `[]` mean the outer and inner components are both translated individually. The outer template will use alias names inside the brackets - example: Your code outputs "Everyone gains [5000] gold!", then the translation template should be "Everyone gains [amount] gold! = ". The translation engine would translate the "Everyone gains [] gold!" and "5000" individually and reassemble them - of course, the number is simply passed through. But in other cases that could be e.g. a Unit name that would be translated, and you could trust that translations for units are already handled just fine. Note that [uniques](./Uniques) often use the feature, but it is in no way limited to them. It it makes life easier for translators, use it.
Curly brackets `{}` are simpler - the contents within the brackets are translated individually, while the outer parts are passed through verbatim. Example: `"+$amount${Fonts.gold} {Gold}".toLabel()` - note the first `${}` is a kotlin template while the second pair becomes part of the string. It tells the translation engine to ignore the numbers and the symbol but to translate the single word "Gold".

4
Translations,-mods,-and-modding-freedom-in-Open-Source.md

@ -93,7 +93,7 @@ stats can accept any list of stats, e.g. '-2 Gold, +1 Science', '+3 Culture', et
tileFilter can accept any number of tile parameters (base terrain e.g. 'Plains', terrain type eg. 'Land'/'Water', terrain features e.g. 'Forest', improvements e.g. 'Mine', resources e.g. 'Iron'.
cityFilter can accept 'in this city', 'in all cities', 'in capital', 'in coastal cities', etc.
There are also filters for units, all acceptable values are documented [here](https://github.com/yairm210/Unciv/wiki/Uniques).
There are also filters for units, all acceptable values are documented [here](./Uniques).
## Unique management with Enums
@ -134,4 +134,4 @@ We already have a map of what uniques can be put on what objects - it won't take
Once we build the full inventory of the uniques, instead of the wiki page that needs to be updated manually we'll be able to generate a list of all acceptable uniques and their parameters directly from the source of truth. Put that in a webpage, add hover-links for each parameter type, generate and upload to github.io every version, and watch the magic happen.
We'll also be able to notify modders if they use "unknown" uniques.
We'll also be able to notify modders if they use "unknown" uniques.

137
Translations,-mods,-and-modding-freedom-in-Open-Source.mde Normal file

@ -0,0 +1,137 @@
Unciv is, at its core, a remake of Civ V, meaning mechanics-wise there's almost by definition not much place for innovation.
In terms of UI, there's nothing here that hasn't been done dozens of times, with far greater polish.
However, there is one area where Unciv is groundbreaking: in its accessibility of translations, the possibility space of its mods, and the relationship between them.
# Translations
## The translation process
So let's start with translation. Surely this is a solved problem, right? Source text + language = translated text, and this information needs to be in a file so the game can read it. What makes us different from, for example, Firaxis?
There are a couple of things, but the most significant is that this is an open-source game, and thus the *translations* are open-source as well.
This means translators are both amateurs and not *obligated* to translate, so if translating is difficult, they simply won't.
Amateurs can make mistakes, which is why it's vital that mistakes are easy to spot. That means that formats like "translation key" - e.g. `DIPLOMACY_GREETING = Siamo lieti di fare la vostra conoscenza.` are much less effective than `A pleasure to meet you. = Siamo lieti di fare la vostra conoscenza.` This format lends itself both the easier translation (it's immediately obvious what needs to be translated) and actual collaboration.
A common suggestion that we get (by people with little familiarity with the project) is to "use a website for translation". This is not bad advice for a small open source game, but there are multiple disadvantages that (for now) no translation website provides enough advantage to outweigh:
1. **Testing**. Currently, translations undergo a number of tests for verification - more on that later! This allows some language changes to be accepted and others not, and it's all in the same platform with the same tests. External translation tools don't allow for this.
2. **History and revisions**. This is what Git was made for, and nothing like it exists in the world. By itself this would not
3. **Release cycle**. We release versions semiweekly, and if we needed to upload changes to the translation website for every in-game change, and download them for every release, that's extra work. For some websites this is automate-able - for most it is not.
4. **Discussions**. Most crowdsourcing translation websites don't allow for discussions and corrections on translations. Github makes every translation collaborative work.
5. **Mass changes**. If we're changing the source of the translation but want to keep the various destinations (say, we change "Gold from trade routes +[amount]%" to "+[amount]% Gold from trade routes"), if all the translation files are in Git we can do that in 1 minute. If it's external, this varies greatly.
Here are some ways that we managed to go wrong:
- Putting all languages into the same file ("one big translation dictionary") - when multiple people edit this file for different languages, they can conflict with each other. Separate to different files for simpler management.
- Using json - json is great for machines, but less so for humans, who can easily make mistakes. Json format is surprisingly finnicky, miss a closing " and the whole file is now unreadable.
The format we decided to go for is one file per language, delimited by " = " for visual separation, in a .properties file. Lines starting in # are considered comments, so we can add comments for translators.
## Building the translation files
As stated, Unciv releases versions semiweekly, and very often these changes include new objects or new UI elements. How do we keep all translation files up to date?
In Unciv, all object data is stored in json format. This allows us to iterate on all objects, regardless of type, and extract the various text fields (strings or lists of strings). We avoid duplication by saving all translation texts we've already added, and use the *existing* translations to populate the "value" for each translation "key" we found in the json files.
Since we rebuild the entire translation file every time, there's currently no way for translators to retain their own comments for future translators.
But on the other hand, since for each line that we add we already know if it's translated or not, this allows us to add a `# Requires translation` line before every non-translated line, which helps translators for languages that are almost fully translated to easily locate the new or changed terms for translation with ctrl+f (and of course this marking will disappear the next time we rebuild the file).
Since there are UI texts that are not part of any specific object (like "Start new game"), we have a separate template.properties file for texts to translate that are not in the json files. Unlike adding objects, where the developer doesn't need to address the translation files at all since it's all linked, when adding UI elements with new texts devs need to remember to add the texts to template.properties file.
## Translation placeholders
This is all well and good for specific text-to-text translations, but what about translating "A Temple has been built in Rome"? The same template could potentially be any building name, or any city name!
We do this with placeholders, which looks something like this: `[construction] has been built in [cityName] = [cityName] ha costruito [construction]`.
As you can see, the *placement* of the parameters can change between languages, so we have to name all parameters.
This also means that there can be explicitly *wrong* translations - if any parameter that appears in the source does not appear in the translated version, we won't be able to display this in-game! This is one of the translation tests that we mentioned earlier - when a translator opens a PR, the game undergoes build & test via the Github Actions, and will notify on failures. Finding the text that warns of the failure within the action output is currently mostly done by devs, but I hope to be able to automate this too someday.
To translate a text like "[Temple] has been built in [Rome]", therefore, we need to:
- Find the relevant translation (we do this by erasing all text between square brackets in input and finding the relevant translation text)
- Map placeholder names to input text (construction = Temple, cityName = Rome)
- Replace placeholders in translation with TRANSLATED input text (in `[cityName] ha costruito [construction]`, replace "[cityName]" with translation of "Rome", and "[construction]" with translation of "Temple")
## Translating mod data
The translation generation reads information from "a ruleset", i.e. the set of jsons defining the game's objects.
Every mod is also a ruleset, either replacing or adding to the base ruleset defined in the game.
This means that the same translation generation that we do for the base game can also be applied to mods, and so each modder can decide (from within the game) to generate translation files for his mod, and since mods are uploaded to Github to be widely available as part of the mod release methodology, translators will be able to translate those files the exact same way that they translate Unciv's base ruleset.
# Uniques
## Moddable unique effects
Every object in Unciv can include "uniques" - a list of strings, each granting a unique effect that is not applicable for every object of its type.
For example, the Palace building has the unique "Indicates the capital city", and the settler has the unique "Founds a new city".
This allows us to share effects between multiple units, and to avoid hardcoding and allow modders to add *any* effect to *any* object.
Here too we encounter the problem of "generic" uniques - how can we have these effects grant a building, some stats, etc, using the same unique for all objects? Why, with placeholders of course! For example, one building has "Requires a [Library] in all cities", where "Library" can be replaced with any other building for similar effects. We can then extract the parameters from the unique at runtime, to know how to resolve the unique's effects.
Since the translation template is the same as the unique template, these uniques are instantly translatable as well!
We do have a slight problem, though - since translation texts come directly from the json files, and the json files have "Requires a [Library] in all cities", how do we tell the translators not to directly translate "Library" but the take the parameter name verbatim?
Well, 95% of translation parameters fit nicely into a certain type - units, buildings, techs, terrains etc. So we can search for an object with than name, and since we find a Library building, we can put "Requires a [buildingName] in all cities = " as our translation line.
## Filters
As time went on, we noticed that many of our "uniques" weren't so unique after all. Many were the same but with slightly different conditions. One affects all cities, one only coastal cities, and one only the city the building is built in. One affects Mounted units, one affects wounded units, one affects all water units, etc. We started compiling these conditions into "filters", which limited the number of uniques while expanding their range considerably.
Take the following example unique for a building: "[+1 Food] from [Deer] tiles [in this city]".
In its "placeholder" form, this is "[stats] from [tileFilter] tiles [cityFilter]".
stats can accept any list of stats, e.g. '-2 Gold, +1 Science', '+3 Culture', etc.
tileFilter can accept any number of tile parameters (base terrain e.g. 'Plains', terrain type eg. 'Land'/'Water', terrain features e.g. 'Forest', improvements e.g. 'Mine', resources e.g. 'Iron'.
cityFilter can accept 'in this city', 'in all cities', 'in capital', 'in coastal cities', etc.
There are also filters for units, all acceptable values are documented [here](./Uniques).
## Unique management with Enums
The further along we go, the more generic the uniques become, and the more of them there are.
Older uniques become new ones, by being merged or made more generic, and the older ones are deprecated. Deprecation notices are put on Discord, but a one-time message is easy to miss, and if you come back after a while you don't know what's changed.
Modders discover during gameplay that the values they put for uniques were incorrect.
All these problems are solved with a single solution - since all uniques are defined by their text, we can create an enum with ALL existing uniques, which lets us:
- Find all usages of a unique in the IDE instantly
- Mark deprecated uniques as such using `@Deprecated("as of <versionNumber">)` for devs (and modders!)
- Compare uniques using enum values, which is faster
What's more, with a little bit of autodetection magic, we can determine the *type* of the parameter using its text.
Using the above example, "[stats] from [tileFilter] tiles [cityFilter]", we can tell by the names of the parameters what each one is supposed to be,.
We can then check at loading time for each unique, if its parameter values matches the parameter type it's supposed to have, which lets us catch incorrect parameters.
The "autodetection" of parameter types for translations can also be fed from here, leading to much more accurate translation texts - instead of detecting from an example (e.g. "Requires a [Library] in all cities" from the json), we now use a dev-inputted value like "Requires a [buildingName] in all cities". This allows us to accept multiple types, like for e.g. "Requires [buildingName/techName/policyName]".
Deprecated values can be detected due to the `@Deprecated` annotation, and can be displayed to the modders when loading the mod, together with the correct replacement.
## Conditionals
Beyond the existing filters for units, buildings, tiles etc, there are some conditions that are global. For example, uniques that take effect when the empire is happy; when a tech has been researched; when the empire is at war; etc.
Rather than being 'build in' to specific uniques, these conditions can be seen as extensions of existing uniques and thus globally relevant.
For example, instead of "[+1 Production] [in all cities] when empire is happy", we can extract the conditional to "[+1 Production] [in all cities] <when empire is happy>". This does two things:
A. Turns the 'extra' unique back into a regular "[stats] [cityFilter]" unique
B. Turns the conditional into an extra piece that can be added onto any other unique
Conditionals have a lot of nuance, especially regarding translation and ordering, so work in that field is more gradual.
## What's next?
We have yet to fully map all existing uniques and convert all textual references in the code to Enum usages, and have yet to extract all conditionals from their uniques.
We already have a map of what uniques can be put on what objects - it won't take much to add that check as well and warn against uniques that are put on the wrong sorts of objects.
Once we build the full inventory of the uniques, instead of the wiki page that needs to be updated manually we'll be able to generate a list of all acceptable uniques and their parameters directly from the source of truth. Put that in a webpage, add hover-links for each parameter type, generate and upload to github.io every version, and watch the magic happen.
We'll also be able to notify modders if they use "unknown" uniques.

20
Uniques.md

@ -47,7 +47,7 @@ As seen in the above example, in order to provide flexibility and generalization
### Generated Documentation
This part of the wiki is human-edited and partially out of date. However, we now have automatically generated documentation, complete for all Uniques that have been updated to the new UniqueType system. It is part of the main source tree and [can be found here.](/yairm210/Unciv/blob/master/docs/uniques.md). This version should always be up-to-date with the uniques and conditionals currently supported in the game.
This part of the wiki is human-edited and partially out of date. However, we now have automatically generated documentation, complete for all Uniques that have been updated to the new UniqueType system. It is part of the main source tree and [can be found here.](https://github.com/${GITHUB_REPOSITORY}/tree/master/docs/uniques.md). This version should always be up-to-date with the uniques and conditionals currently supported in the game.
### Unique locations
@ -920,19 +920,19 @@ Some of the terrain uniques have gameplay effect, others are used only for map g
"Rare feature"
"Always Fertility [amount] for Map Generation" - see [Regions](https://github.com/yairm210/Unciv/wiki/Regions)
"Always Fertility [amount] for Map Generation" - see [Regions](./Regions)
"[amount] to Fertility for Map Generation" - see [Regions](https://github.com/yairm210/Unciv/wiki/Regions)
"[amount] to Fertility for Map Generation" - see [Regions](./Regions)
"A Region is formed with at least [amount]% [simpleTerrain] tiles, with priority [amount]" - see [Regions](https://github.com/yairm210/Unciv/wiki/Regions)
"A Region is formed with at least [amount]% [simpleTerrain] tiles, with priority [amount]" - see [Regions](./Regions)
"A Region is formed with at least [amount]% [simpleTerrain] tiles and [simpleTerrain] tiles, with priority [amount]" - see [Regions](https://github.com/yairm210/Unciv/wiki/Regions)
"A Region is formed with at least [amount]% [simpleTerrain] tiles and [simpleTerrain] tiles, with priority [amount]" - see [Regions](./Regions)
"A Region can not contain more [simpleTerrain] tiles than [simpleTerrain] tiles" - see [Regions](https://github.com/yairm210/Unciv/wiki/Regions)
"A Region can not contain more [simpleTerrain] tiles than [simpleTerrain] tiles" - see [Regions](./Regions)
"Base Terrain on this tile is not counted for Region determination" - see [Regions](https://github.com/yairm210/Unciv/wiki/Regions)
"Base Terrain on this tile is not counted for Region determination" - see [Regions](./Regions)
"Considered [terrainQuality] when determining start locations" - see [Regions](https://github.com/yairm210/Unciv/wiki/Regions)
"Considered [terrainQuality] when determining start locations" - see [Regions](./Regions)
# Resource Uniques
@ -945,7 +945,7 @@ Some of the terrain uniques have gameplay effect, others are used only for map g
# ModOptions Uniques
These are valid only in a [ModOptions.json](/yairm210/Unciv/wiki/Miscellaneous-JSON-files#modoptionsjson) file.
These are valid only in a [ModOptions.json](./Miscellaneous-JSON-files#modoptionsjson) file.
|unique|comment|
|------|-------|
@ -1058,4 +1058,4 @@ These uniques have been recently deprecated. While they are still supported, the
"+[amount]% Strength in [tileFilter]" - Replaced with "[amount]% Strength \<in [tileFilter] tiles>"
"[stats] once [techName] is discovered" - Replace with "[stats] \<after discovering [techname]>"
"[stats] once [techName] is discovered" - Replace with "[stats] \<after discovering [techname]>"

1061
Uniques.mde Normal file

File diff suppressed because it is too large Load Diff

28
Unit-related-JSON-files.md

@ -5,7 +5,7 @@
## Units.json
[Link to original](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Vanilla/Units.json)
[Link to original](https://github.com/${GITHUB_REPOSITORY}/tree/master/android/assets/jsons/Civ%20V%20-%20Vanilla/Units.json)
This file should contain a list of all the units, both military and civilian, that you want to use in your mod.
@ -13,29 +13,29 @@ Each unit can have the following attributes:
| attribute | Type | optional or not | notes |
| --------- | ---- | -------- | ----- |
| name | String | required | The name of the units (required) |
| unitType | String | required | The type of the unit. Must be in [UnitTypes.json](UnitTypes.json) |
| unitType | String | required | The type of the unit. Must be in [UnitTypes.json](https://github.com/${GITHUB_REPOSITORY}/tree/master/android/assets/jsons/Civ%20V%20-%20Gods%20&%20Kings/UnitTypes.json) |
| cost | Integer (≥0) | defaults to 0 | The amount of production required to build this unit |
| movement | Integer (≥0) | defaults to 0 | The amount of movement points the unit has by default |
| strength | Integer (≥0) | defaults to 0 | The melee attack and defensive strength of the unit. If this and rangedStrength are ommited or 0, the unit will be a civilian |
| rangedStrength | Integer (≥0) | defaults to 0 | The ranged attack strength of the unit. If omitted, the unit cannot ranged attack |
| range | Integer (≥0) | defaults to 2 | The default range from which ranged attacks can be preformed |
| interceptRange | Integer (≥0) | defaults to 0 | Air units attacking within in this range will be intercepted |
| requiredTech | String | defaults to none | The tech required to build this unit. Must be in [Techs.json](#techsjson) |
| obsoleteTech | String | defaults to none | After researching this tech, the unit can no longer be build. Must be in [Techs.json](#techsjson) |
| requiredResource | String | defaults to none | Resource that is consumed by building this unit. Must be in [TileResources.json](#tilereousrcesjson) |
| requiredTech | String | defaults to none | The tech required to build this unit. Must be in [Techs.json](./Civilization-related-JSON-files#techsjson) |
| obsoleteTech | String | defaults to none | After researching this tech, the unit can no longer be build. Must be in [Techs.json](./Civilization-related-JSON-files#techsjson) |
| requiredResource | String | defaults to none | Resource that is consumed by building this unit. Must be in [TileResources.json](./Map-related-JSON-files#tileresourcesjson) |
| upgradesTo | String | defaults to none | Unit that this unit can upgrade to when it is available. Must be in [Units.json](#unitsjson) |
| replaces | String | defaults to none | If this unit is unique to a nation, this is the unit it replaces. Must be in [Units.json](#unitsjson) |
| uniqueTo | String | defaults to none | The nation that this unit is unique to. Must be in [Nations.json](#nationsjson) |
| uniqueTo | String | defaults to none | The nation that this unit is unique to. Must be in [Nations.json](./Civilization-related-JSON-files#nationsjson) |
| hurryCostModifier | Integer | defaults to 0 | If this unit is bought for gold/faith, it's price is increased by so much percent |
| promotions | List of Strings | defaults to none | A list of all the promotions the unit automatically receives upon being built. Each promotion must be in [UnitPromotions.json](#unitpromotionsjson) |
| uniques | List of Strings | defaults to none | A list of the unique abilities this unit has. A list of almost all uniques can be found [here](https://github.com/yairm210/Unciv/wiki/Uniques#unit-uniques) |
| uniques | List of Strings | defaults to none | A list of the unique abilities this unit has. A list of almost all uniques can be found [here](./Uniques#unit-uniques) |
| replacementTextForUniques | String | defaults to none | If provided, this will be displayed instead of the list of uniques. Can be used for better formatting. |
| attackSound | String | defaults to none | The sound that is to be played when this unit attacks. For possible values, see [sounds](#Sounds)
| civilopediaText | List | Default empty | see [civilopediaText chapter](#civilopedia-text) |
| civilopediaText | List | Default empty | see [civilopediaText chapter](./Miscellaneous-JSON-files#civilopedia-text) |
## UnitPromotions.json
[Link to original](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Vanilla/UnitPromotions.json)
[Link to original](https://github.com/${GITHUB_REPOSITORY}/tree/master/android/assets/jsons/Civ%20V%20-%20Vanilla/UnitPromotions.json)
This file lists the available unit promotions.
@ -50,12 +50,12 @@ Each promotion can have the following properties:
| prerequisites | List | Default empty | Prerequisite promotions |
| effect | String | Default empty | Deprecated, use uniques instead |
| unitTypes | List | Default empty | The unit types for which this promotion applies as specified in [UnitTypes.json](#unittypesjson) |
| uniques | List | Default empty | List of effects, [see here](https://github.com/yairm210/Unciv/wiki/Uniques#unit-uniques) |
| civilopediaText | List | Default empty | see [civilopediaText chapter](#civilopedia-text) |
| uniques | List | Default empty | List of effects, [see here](./Uniques#unit-uniques) |
| civilopediaText | List | Default empty | see [civilopediaText chapter](./Miscellaneous-JSON-files#civilopedia-text) |
## UnitTypes.json
[Link to original](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Vanilla/UnitTypes.json)
[Link to original](https://github.com/${GITHUB_REPOSITORY}/tree/master/android/assets/jsons/Civ%20V%20-%20Vanilla/UnitTypes.json)
This optional file is used for defining new types of units. The names of these can be used in unitFilters, and these types determine what domain the unit moves in: over land, over water or through the air. If the file is ommitted, the following are automatically added:
Civilian, Melee, Ranged, Scout, Mounted, Armor, Siege, WaterCivilian, WaterMelee, WaterRanged, WaterSubmarine, WaterAircraftCarrier, Fighter, Bomber, AtomicBomber, and Missile.
@ -64,11 +64,11 @@ Civilian, Melee, Ranged, Scout, Mounted, Armor, Siege, WaterCivilian, WaterMelee
| --------- | ---- | -------- | ----- |
| name | String | required | The name of the unit type |
| movementType | String | required | The domain through which the unit moves. Allowed values: "Water", "Land", "Air" |
| uniques | List of String | defaults to none | A list of the unique abilities every unit of this type has. A list of almost all uniques can be found [here](https://github.com/yairm210/Unciv/wiki/Uniques#unit-uniques) |
| uniques | List of String | defaults to none | A list of the unique abilities every unit of this type has. A list of almost all uniques can be found [here](./Uniques#unit-uniques) |
## Sounds
Standard values are below. The sounds themselves can be found [here](https://github.com/yairm210/Unciv/tree/master/android/assets/sounds).
Standard values are below. The sounds themselves can be found [here](https://github.com/${GITHUB_REPOSITORY}/tree/master/android/assets/sounds).
- _arrow, artillery, bombard, bombing, cannon, chimes, choir, click, coin, construction, elephant, fortify, gdrAttack, horse, jetgun, machinegun, metalhit, missile, nonmetalhit, nuke, paper, policy, promote, setup, shipguns, shot, slider, swap, tankshot, throw, torpedo, upgrade, whoosh_.

75
Unit-related-JSON-files.mde Normal file

@ -0,0 +1,75 @@
* [Units.json](#unitsjson)
* [UnitPromotions.json](#unitpromotionsjson)
* [UnitTypes.json](#unittypesjson)
## Units.json
[Link to original](/android/assets/jsons/Civ%20V%20-%20Vanilla/Units.json)
This file should contain a list of all the units, both military and civilian, that you want to use in your mod.
Each unit can have the following attributes:
| attribute | Type | optional or not | notes |
| --------- | ---- | -------- | ----- |
| name | String | required | The name of the units (required) |
| unitType | String | required | The type of the unit. Must be in [UnitTypes.json](/android/assets/jsons/Civ%20V%20-%20Gods%20&%20Kings/UnitTypes.json) |
| cost | Integer (≥0) | defaults to 0 | The amount of production required to build this unit |
| movement | Integer (≥0) | defaults to 0 | The amount of movement points the unit has by default |
| strength | Integer (≥0) | defaults to 0 | The melee attack and defensive strength of the unit. If this and rangedStrength are ommited or 0, the unit will be a civilian |
| rangedStrength | Integer (≥0) | defaults to 0 | The ranged attack strength of the unit. If omitted, the unit cannot ranged attack |
| range | Integer (≥0) | defaults to 2 | The default range from which ranged attacks can be preformed |
| interceptRange | Integer (≥0) | defaults to 0 | Air units attacking within in this range will be intercepted |
| requiredTech | String | defaults to none | The tech required to build this unit. Must be in [Techs.json](./Civilization-related-JSON-files#techsjson) |
| obsoleteTech | String | defaults to none | After researching this tech, the unit can no longer be build. Must be in [Techs.json](./Civilization-related-JSON-files#techsjson) |
| requiredResource | String | defaults to none | Resource that is consumed by building this unit. Must be in [TileResources.json](./Map-related-JSON-files#tileresourcesjson) |
| upgradesTo | String | defaults to none | Unit that this unit can upgrade to when it is available. Must be in [Units.json](#unitsjson) |
| replaces | String | defaults to none | If this unit is unique to a nation, this is the unit it replaces. Must be in [Units.json](#unitsjson) |
| uniqueTo | String | defaults to none | The nation that this unit is unique to. Must be in [Nations.json](./Civilization-related-JSON-files#nationsjson) |
| hurryCostModifier | Integer | defaults to 0 | If this unit is bought for gold/faith, it's price is increased by so much percent |
| promotions | List of Strings | defaults to none | A list of all the promotions the unit automatically receives upon being built. Each promotion must be in [UnitPromotions.json](#unitpromotionsjson) |
| uniques | List of Strings | defaults to none | A list of the unique abilities this unit has. A list of almost all uniques can be found [here](./Uniques#unit-uniques) |
| replacementTextForUniques | String | defaults to none | If provided, this will be displayed instead of the list of uniques. Can be used for better formatting. |
| attackSound | String | defaults to none | The sound that is to be played when this unit attacks. For possible values, see [sounds](#Sounds)
| civilopediaText | List | Default empty | see [civilopediaText chapter](./Miscellaneous-JSON-files#civilopedia-text) |
## UnitPromotions.json
[Link to original](/android/assets/jsons/Civ%20V%20-%20Vanilla/UnitPromotions.json)
This file lists the available unit promotions.
Each promotion must have an icon, except progressions ending in " I", " II", " III" (no IV V VI allowed) are rendered by looking up an icon without those suffixes and adding stars.
Remember, promotions can be "bought" with XP, but also granted by the unit type, buildings, wonders and such. They are preserved when a unit upgrades, therefore special properties of nation unique units that can be inherited when they upgrade should be in a promotion, not uniques/stats in the units json (example: Slinger withdraw).
Each promotion can have the following properties:
| Attribute | Type | Optional? | Notes |
|-----------|------|-----------|-------|
| name | String | Required | See above for "I, II, III" progressions |
| prerequisites | List | Default empty | Prerequisite promotions |
| effect | String | Default empty | Deprecated, use uniques instead |
| unitTypes | List | Default empty | The unit types for which this promotion applies as specified in [UnitTypes.json](#unittypesjson) |
| uniques | List | Default empty | List of effects, [see here](./Uniques#unit-uniques) |
| civilopediaText | List | Default empty | see [civilopediaText chapter](./Miscellaneous-JSON-files#civilopedia-text) |
## UnitTypes.json
[Link to original](/android/assets/jsons/Civ%20V%20-%20Vanilla/UnitTypes.json)
This optional file is used for defining new types of units. The names of these can be used in unitFilters, and these types determine what domain the unit moves in: over land, over water or through the air. If the file is ommitted, the following are automatically added:
Civilian, Melee, Ranged, Scout, Mounted, Armor, Siege, WaterCivilian, WaterMelee, WaterRanged, WaterSubmarine, WaterAircraftCarrier, Fighter, Bomber, AtomicBomber, and Missile.
| attribute | Type | optional or not | notes |
| --------- | ---- | -------- | ----- |
| name | String | required | The name of the unit type |
| movementType | String | required | The domain through which the unit moves. Allowed values: "Water", "Land", "Air" |
| uniques | List of String | defaults to none | A list of the unique abilities every unit of this type has. A list of almost all uniques can be found [here](./Uniques#unit-uniques) |
## Sounds
Standard values are below. The sounds themselves can be found [here](/android/assets/sounds).
- _arrow, artillery, bombard, bombing, cannon, chimes, choir, click, coin, construction, elephant, fortify, gdrAttack, horse, jetgun, machinegun, metalhit, missile, nonmetalhit, nuke, paper, policy, promote, setup, shipguns, shot, slider, swap, tankshot, throw, torpedo, upgrade, whoosh_.
Mods can add their own sounds, as long as any new value in attackSound has a corresponding sound file in the mod's sound folder, using one of the formats mp3, ogg or wav (file name extension must match codec used). Remember, names are case sensitive. Small sizes strongly recommended, Unciv's own sounds use 24kHz joint stereo 8-bit VBR at about 50-100kBps.

1
_Footer.md Normal file

@ -0,0 +1 @@
*To edit this wiki, open a pull request against the files under [/docs/wiki](https://github.com/${GITHUB_REPOSITORY}/tree/master/docs/wiki) in the main Unciv repository.*

1
_Footer.mde Normal file

@ -0,0 +1 @@
*To edit this wiki, open a pull request against the files under [/docs/wiki](/docs/wiki) in the main Unciv repository.*

21
_Sidebar.mde Normal file

@ -0,0 +1,21 @@
# [Home](.)
# [Installing on macOS](./Installing-on-macOS)
# [Translating](./Translating)
# Modding
* [Mods](./Mods)
* [Making a new Civilization](./Making-a-new-Civilization)
* [Creating a custom tileset](./Creating-a-custom-tileset)
* [JSON files for mods](./JSON-files-for-mods)
* [Uniques](./Uniques)
* [Images and texture atlas](./Mods#more-on-images-and-the-texture-atlas)
* [Audiovisual Mods](./Audiovisual-Mods)
# Development
* [Getting Started](./Getting-Started)
* [Coding standards](./Coding-standards)
* [Project structure and major classes](./Project-structure-and-major-classes)
* [Building locally without Android Studio](./Building-locally-without-Android-Studio)
* [From code to deployment](./From-code-to-deployment)