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

Update wiki - fix oversights, clarify what is optional in base ruleset mods, new features (#13522)

Browse Source 
* Modder wiki: Fix personalities breaking up rendering, open them up and lint

* Modder wiki: Fix incomplete table of contents (oops, the link for the later "Add a table" commit is in here)

* Modder wiki: Emphasize and explain more basic Json rules - @SpacedOutChicken's "but modders may copy examples verbatim without knowing quotes meant to be part of literals must be escaped"

* Modder wiki: Add a table documenting base ruleset fallbacks / what can be empty

* Modder wiki: Add documentation for PR #13513

* Modder wiki: Add or clarify fallbacks used for base ruleset Mods

* Clear up question marks - the template mod works with no objects of those types

* Remove duplicate Personalities paragraph

* Revert "Remove duplicate Personalities paragraph"

This reverts commit d785b546af1537a1e3add56a4ff83a9b178d404d.

* Revert more Personality changes, leaving only the file link

* Minor fixes
This commit is contained in:
SomeTroglodyte 2025-06-26 22:43:38 +02:00 committed by GitHub
parent 89f6b6fe8b
commit 4ac0400c2e
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
8 changed files with 103 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
android/assets/jsons/Civ V - Gods & Kings/Personalities.json
View File

@ -4,7 +4,7 @@
Here is a template to show what values should be filled in.
Use the description at http://civdata.com/, and adjust the numbers accordingly.
Even then, its up to personal interpretation.
To generate lines with multiple parameters I used the funciton: (FirstParam + (SeccondParam - 5) / 2)
To generate lines with multiple parameters I used the function: (FirstParam + (SecondParam - 5) / 2)
Note: BNW leaders are included for now.
{
"name": "Template",

23
docs/Modders/Images-and-Audio.md
View File

@ -321,22 +321,13 @@ Also note that voices for City-State leaders work only for those messages a City
## Modding Easter eggs
Here's a list of special dates (or date ranges) Unciv will recognize:
|-----|
| AprilFoolsDay |
| DiaDeLosMuertos |
| Diwali |
| Easter |
| Friday13th |
| LunarNewYear |
| Passover |
| PrideDay |
| Qingming |
| Samhain |
| StarWarsDay |
| TowelDay |
| UncivBirthday |
| Xmas |
| YuleGoat |
| name | | | |
|-----------------|--------------|-------------|---------------|
| AprilFoolsDay | Friday13th | Qingming | UncivBirthday |
| DiaDeLosMuertos | LunarNewYear | Samhain | Xmas |
| Diwali | Passover | StarWarsDay | YuleGoat |
| Easter | PrideDay | TowelDay | |
... When these are or what they mean - look it up, if in doubt in our sources (😈).

42
docs/Modders/Mod-file-structure/1-Overview.md
View File

@ -10,6 +10,7 @@ The JSON files that make up mods can have many different fields, and as not all
- [Civilization-related JSON files](2-Civilization-related-JSON-files.md)
- [Beliefs.json](2-Civilization-related-JSON-files.md#beliefsjson)
- [Buildings.json](2-Civilization-related-JSON-files.md#buildingsjson)
- [CityStateTypes.json](2-Civilization-related-JSON-files.md#citystatetypesjson)
- [Nations.json](2-Civilization-related-JSON-files.md#nationsjson)
- [Policies.json](2-Civilization-related-JSON-files.md#policiesjson)
- [Quests.json](2-Civilization-related-JSON-files.md#questsjson)
@ -31,14 +32,16 @@ The JSON files that make up mods can have many different fields, and as not all
- [Eras.json](5-Miscellaneous-JSON-files.md#erasjson)
- [ModOptions.json](5-Miscellaneous-JSON-files.md#modoptionsjson)
- [GlobalUniques.json](5-Miscellaneous-JSON-files.md#globaluniquesjson)
- [Speeds.json](5-Miscellaneous-JSON-files.md#speedsjson)
- [Tutorials.json](5-Miscellaneous-JSON-files.md#tutorialsjson)
- [VictoryTypes.json](5-Miscellaneous-JSON-files.md#victorytypesjson)
- [Stats](3-Map-related-JSON-files.md#stats)
- [Sounds](../Images-and-Audio.md#sounds)
- [Civilopedia text](5-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)
**Recommended reading**: [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:
@ -62,8 +65,9 @@ There are different types of attributes:
| type | notes |
|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| String | A word or sentence. Should be between double quotes (") |
| String | A word or sentence. Should be between double quotes (") and escape double quotes meant to be part of the text: `\"` |
| Integer | A number. Can be both positive or negative. Should **not** be between quotes |
| Float | A number that can have decimal places. Remember to use `.` as the Json standard needs, not your local culture's decimal symbol. Scientific notation would work, though |
| 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, separated by commas, 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. |
@ -83,6 +87,40 @@ The keys in this example are "science" and "culture", and both have the value "5
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.
## Requirements for Base Rulesets
Base ruleset mods must be "complete" by themselves, but that does not mean they must include all possible json files nor define content in all of them. Here's a breakdown (WIP, possibly inaccurate):
| File | Empty allowed? | Default/fallback |
|---------------------------------------------------------------------------|----------------|--------------------------|
| [Beliefs](2-Civilization-related-JSON-files.md#beliefsjson) | yes | none |
| [Buildings](2-Civilization-related-JSON-files.md#buildingsjson) | no | none |
| [CityStateTypes](2-Civilization-related-JSON-files.md#citystatetypesjson) | no | vanilla |
| [Difficulties](5-Miscellaneous-JSON-files.md#difficultiesjson) | no | vanilla |
| [Eras](5-Miscellaneous-JSON-files.md#erasjson) | no | none |
| [GlobalUniques](5-Miscellaneous-JSON-files.md#globaluniquesjson) | yes | vanilla |
| [ModOptions](5-Miscellaneous-JSON-files.md#modoptionsjson) | yes | generated on download |
| [Nations](2-Civilization-related-JSON-files.md#nationsjson) | no | none |
| [Policies](2-Civilization-related-JSON-files.md#policiesjson) | yes | none |
| [Quests](2-Civilization-related-JSON-files.md#questsjson) | yes | none |
| [Religions](2-Civilization-related-JSON-files.md#religionsjson) | yes | none |
| [Ruins](3-Map-related-JSON-files.md#ruinsjson) | yes | vanilla |
| [Specialists](2-Civilization-related-JSON-files.md#specialistsjson) | yes | none |
| [Speeds](5-Miscellaneous-JSON-files.md#speedsjson) | no | vanilla |
| [Techs](2-Civilization-related-JSON-files.md#techsjson) | yes | none |
| [Terrains](3-Map-related-JSON-files.md#terrainsjson) | no | none |
| [TileImprovements](3-Map-related-JSON-files.md#tileimprovementsjson) | yes | none |
| [TileResources](3-Map-related-JSON-files.md#tileresourcesjson) | yes | none |
| [Tutorials](5-Miscellaneous-JSON-files.md#tutorialsjson) | yes | builtin always displayed |
| [UnitPromotions](4-Unit-related-JSON-files.md#unitpromotionsjson) | yes | none |
| [Units](4-Unit-related-JSON-files.md#unitsjson) | no | none |
| [UnitTypes](4-Unit-related-JSON-files.md#unittypesjson) | no | vanilla |
| [VictoryTypes](5-Miscellaneous-JSON-files.md#victorytypesjson) | no | vanilla |
* Mod loading never fails due to missing files, they default to empty at first. Then the fallbacks mentioned above are applied for base rulesets only. Inconsistencies after that step would be reported by the Mod checker.
* GlobalUniques has a fallback used when the file is missing. Therefore, a mod can intentionally define there are none by including one with empty content (`{}`).
* Ruins has a fallback used when the file is missing. Therefore, a mod can intentionally define there are none by including one with empty content (`[]`).
## Uniques
"Uniques" are a label used by Unciv for extensible and customizable effects. Nearly every "ruleset object" allows a set of them, as a List with the name "uniques".

36
docs/Modders/Mod-file-structure/2-Civilization-related-JSON-files.md
View File

@ -99,10 +99,13 @@ only has minor weight when choosing between regions that are not of a type to av
These notes are __only__ valid when playing on generated maps, loaded maps from map editor get no "
regions" and startBias is processed differently (but you can expect single-entry startBias to work
best).
[^V]: See [Supply Leader Voices](../../Images-and-Audio.md#supply-leader-voices)
[^V]: See [Supply Leader Voices](../Images-and-Audio.md#supply-leader-voices)
## Personalities.json
[Link to original](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Gods%20%26%20Kings/Personalities.json)
This file contains all Personalities for computer players.
Each personality has the following structure:
@ -136,33 +139,26 @@ The code below is an example of a valid "priorities" definition.
### Personality Behaviours
Personality Behaviours are not implemented yet and their names may change. Using them before they
are ready might make the mod unplayable.
[//]: # (There are 6 defining behaviours that influnce an AI Civilization's behaviour. A higher
value means they will behave more like the attribute.)
Personality Behaviours **are not fully implemented yet** and their names may change. Using them before they
are ready might make the mod unplayable. ***The following is WIP - read on at you own peril!***
There are 7 defining behaviours that influence an AI Civilization's behaviour. A higher value means they will behave more like the attribute.
# (- Military: Determines how much does the civilization prioritizes building a military, but not necessarily using it. A higher value means more focus on military, a lower value means it is likely more peaceful.)
- Military: Determines how much does the civilization prioritizes building a military, but not necessarily using it. A higher value means more focus on military, a lower value means it is likely more peaceful.
- Agressive: Determines how the civilization uses its units while at war and which buildings they prioritise. A higher value means the civilization is more aggressive, a lower value means it is more defensive.
- War: Determines how likely the civilization is to declare war. A 0 means the civ won't declare war at all.
- Commerce: Determines how open the civilization is to trade, value open borders, and liberate city-states. A higher value means more trading frequency even with civilizations they don't like.
- Diplomacy: Determines how likely the civilization is to declare friendship, a defensive pact, peace treaty, or other diplomatic actions.
- Loyal: Determines how much the civilization values a long-lasting alliance, how willing they are to join wars with them, and how much they despise other unreliable civilizations.
- Expansion: Determines how focused the civilization is on founding or capturing new cities. A lower value means they might focus on culture more.
# (- Agressive: Determines how the civilization uses it's units while at war and which buildings they prioritise. A higher value means the civilization is more aggressive, a lower value means it is more defensive.)
# (- War: Determines how likely the civilization is to declare war. A 0 means the civ won't declare war at all)
# (- Commerce: Determines how open the civilization is to trade, value open borders, and liberate city-states. A higher value means more trading frequency even with civilizations they don't like.)
# (- Diplomacy: Determines how likely the civilization is to declare friendship, a defensive pact, peace treaty, or other diplomatic actions.)
# (- Loyal: Determines how much the civilization values a long-lasting alliance, how willing they are to join wars with them, and how much they despise other unreliable civilizations.)
# (- Expansion: Determines how focused the civilization is on founding or capturing new cities. A lower value means they might focus on culture more.)
## CityStateTypes.json
[Link to original](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Gods%20%26%20Kings/CityStateTypes.json)
This optional file is used for defining new types of city states. These types determine the benefits
major civilizations gets when they befriend or ally the city state with influence. If the file is
ommitted, the following are automatically added:
This optional file is used for defining the types of city states. These types determine the benefits major civilizations get when they befriend or ally the city state with influence.
For base ruleset Mods, if the file is ommitted or contains an empty list, [all types from the Vanilla ruleset](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Vanilla/CityStateTypes.json) are automatically added:
Cultured, Maritime, Mercantile, Militaristic, Religious.
Each city state type has the following structure:

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

@ -88,7 +88,9 @@ Each resource has the following structure:
[Link to original](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Vanilla/Ruins.json)
This optional file contains the possible rewards ancient ruins give. If omitted, the default file for the game is used, even in baseRuleSet mods.
This optional file contains the possible rewards ancient ruins give.
Base ruleset Mods can omit the file, in which case they inherit the ones from the Vanilla ruleset. They can, however, provide a file with an empty list (`[]`) to avoid that. In this case there should be no improvements with the ["Provides a random bonus when entered" Unique](../uniques.md#improvement-uniques). Conversely, if there are such improvements, the Mod checker will flag an empty Ruins file as error.
Each of the objects in the file represents a single reward you can get from ruins. It has the following structure:

3
docs/Modders/Mod-file-structure/4-Unit-related-JSON-files.md
View File

@ -60,7 +60,8 @@ Each promotion has the following structure:
[Link to original](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Gods%20%26%20Kings/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 omitted, the following are automatically added:
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.
For base ruleset Mods, if the file is omitted or contains an empty list, [all types from the Vanilla ruleset](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Vanilla/UnitTypes.json) are automatically added:
Civilian, Melee, Ranged, Scout, Mounted, Armor, Siege, WaterCivilian, WaterMelee, WaterRanged, WaterSubmarine, WaterAircraftCarrier, Fighter, Bomber, AtomicBomber, and Missile.
Each unit type has the following structure:

54
docs/Modders/Mod-file-structure/5-Miscellaneous-JSON-files.md
View File

@ -4,7 +4,9 @@
[Link to original](https://github.com/yairm210/Unciv/tree/master/android/assets/jsons/Civ%20V%20-%20Gods%20&%20Kings/Difficulties.json)
This file defines the difficulty levels a player can choose when starting a new game.
This optional file defines the difficulty levels a player can choose when starting a new game.
Base ruleset Mods can omit the file or supply an empty list, even though at least one difficulty is mandatory, in which case they inherit [the ones from the Vanilla ruleset](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Vanilla/Difficulties.json).
Each difficulty level has the following structure:
@ -36,6 +38,7 @@ Each difficulty level has the following structure:
| aiUnhappinessModifier | Float | 1 | |
| turnBarbariansCanEnterPlayerTiles | Integer | 0 | |
| clearBarbarianCampReward | Integer | 25 | |
| uniques | List of Strings | empty | Will be treated as part of GlobalUniques when this difficulty is chosen |
## Eras.json
@ -72,29 +75,33 @@ Each era can have the following attributes:
[Link to original](https://github.com/yairm210/Unciv/tree/master/android/assets/jsons/Civ%20V%20-%20Gods%20&%20Kings/Speeds.json)
This file should contain all the speeds you want to use in your mod.
This optional file should contain all the speeds you want to use in your mod.
Base ruleset Mods can omit the file or supply an empty list, even though at least one game speed is mandatory, in which case they inherit [the ones from the Vanilla ruleset](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Vanilla/Speeds.json).
Each speed can have the following attributes:
| Attribute | Type | Default | Notes |
|---------------------------------|--------------|------------------|-------------------------------------------------------------------------------------------------------------|
| name | String | Required | Name of the speed |
| modifier | Float (≥0) | 1.0 | Overall game speed modifier |
| productionCostModifier | Float (≥0) | `modifier` value | Scales production cost of units and buildings |
| goldCostModifier | Float (≥0) | `modifier` value | Scales gold costs |
| scienceCostModifier | Float (≥0) | `modifier` value | Scales science costs |
| cultureCostModifier | Float (≥0) | `modifier` value | Scales culture costs |
| faithCostModifier | Float (≥0) | `modifier` value | Scales faith costs |
| improvementBuildLengthModifier | Float (≥0) | `modifier` value | Scales the time it takes for a worker to build tile improvements |
| barbarianModifier | Float (≥0) | `modifier` value | Scales the time between barbarian spawns |
| goldGiftModifier | Float (≥0) | `modifier` value | Scales the influence gained from gifting gold to city-states |
| cityStateTributeScalingInterval | Float (≥0) | 6.5 | The number of turns it takes for the amount of gold a player demands from city-states to increase by 5 gold |
| goldenAgeLengthModifier | Float (≥0) | `modifier` value | Scales the length of golden ages |
| religiousPressureAdjacentCity | Integer (≥0) | 6 | Defines how much religious pressure a city exerts on nearby cities |
| peaceDealDuration | Integer (≥0) | 10 | The number of turns a peace deal lasts |
| dealDuration | Integer (≥0) | 30 | The number of turns a non-peace deal (research agreement, open borders, etc.) lasts |
| startYear | Float | -4000 | The start year of the game (negative is BC/BCE) |
| turns | List | Required | List of time interval per turn, [see below](#time-interval-per-turn) |
| Attribute | Type | Default | Notes |
|---------------------------------|-----------------|------------------|-------------------------------------------------------------------------------------------------------------|
| name | String | Required | Name of the speed |
| modifier | Float (≥0) | 1.0 | Overall game speed modifier |
| productionCostModifier | Float (≥0) | `modifier` value | Scales production cost of units and buildings |
| goldCostModifier | Float (≥0) | `modifier` value | Scales gold costs |
| scienceCostModifier | Float (≥0) | `modifier` value | Scales science costs |
| cultureCostModifier | Float (≥0) | `modifier` value | Scales culture costs |
| faithCostModifier | Float (≥0) | `modifier` value | Scales faith costs |
| improvementBuildLengthModifier | Float (≥0) | `modifier` value | Scales the time it takes for a worker to build tile improvements |
| barbarianModifier | Float (≥0) | `modifier` value | Scales the time between barbarian spawns |
| goldGiftModifier | Float (≥0) | `modifier` value | Scales the influence gained from gifting gold to city-states |
| cityStateTributeScalingInterval | Float (≥0) | 6.5 | The number of turns it takes for the amount of gold a player demands from city-states to increase by 5 gold |
| goldenAgeLengthModifier | Float (≥0) | `modifier` value | Scales the length of golden ages |
| religiousPressureAdjacentCity | Integer (≥0) | 6 | Defines how much religious pressure a city exerts on nearby cities |
| peaceDealDuration | Integer (≥0) | 10 | The number of turns a peace deal lasts |
| dealDuration | Integer (≥0) | 30 | The number of turns a non-peace deal (research agreement, open borders, etc.) lasts |
| startYear | Float | -4000 | The start year of the game (negative is BC/BCE) |
| turns | List | Required | List of time interval per turn, [see below](#time-interval-per-turn) |
| uniques | List of Strings | empty | Will be treated as part of GlobalUniques when this speed is chosen |
### Time interval per turn
@ -293,6 +300,9 @@ With `civModifier` being the multiplicative aggregate of ["\[relativeAmount\]% G
GlobalUniques defines uniques that apply globally. e.g. Vanilla rulesets define the effects of Unhappiness here.
Base ruleset Mods can omit the file, in which case they inherit [the ones from the Vanilla ruleset](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Vanilla/GlobalUniques.json).
Alternatively, they can supply a file with an empty object (`{}`), meaning that no global Uniques exist for that Mod.
It has the following structure:
| Attribute | Type | Default | Notes |
@ -330,6 +340,8 @@ This is searched for, meaning the mod defining the Tutorial is irrelevant, mods
These files contain which victories this mod provides, and what milestones must be reached for someone to win a victory.
Most of the file contains of strings that are shown to the user in the victory screen, with the rest being the requirements for winning.
Base ruleset Mods can omit the file or supply an empty list, even though at least one victory type is mandatory, in which case they inherit [the ones from the Vanilla ruleset](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Vanilla/VictoryTypes.json).
Each victory have the following structure:
| Attribute | Type | Default | Notes |

2
docs/Modders/Mods.md
View File

@ -13,7 +13,7 @@ The game only knows how to recognize existing definitions, so you can't add *new
There are three main 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 - for example, [creating a new Civilization](Making-a-new-Civilization.md)
- **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. [A minimal example can be found here](https://github.com/yairm210/Unciv-minimal-base-ruleset) as a template to build off of ("Use this template" green button in top right, "Create a new repository")
- **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. [A minimal example can be found here](https://github.com/yairm210/Unciv-minimal-base-ruleset) as a template to build off of ("Use this template" green button in top right, "Create a new repository"). For requirements, see [Requirements](Mod-file-structure/1-Overview.md#requirements-for-base-rulesets)
- **Ruleset-agnostic mods** - these do not contain any ruleset-related jsons, but instead contain other affects. Audiovisual mods (including tilesets, unitsets, and UI skins) and map mods are in this category.
Creating and editing mods from your phone is NOT RECOMMENDED - it's *much easier* using a desktop device!