Mirrors/Unciv
1
0
Fork 0
mirror of https://github.com/yairm210/Unciv.git synced 2025-02-20 19:56:51 +01:00
Code Issues Packages Projects Releases Wiki Activity

Fixed the official wiki (#6453)

Browse Source 
* Fixed the links in the docs

* Fixed broken tables

Tables without a line break above are not treated as valid tables

* Removed redundant table of contents and formatted some bulleted lists

* The image in Regions.md is now properly displayed

* Standardized list indentation, line spacing, table header rows, and JSON code blocks

* Standardized headers

* Fixed remaining broken links, edited pseudo-footnotes
This commit is contained in:
청하늘 2022-03-31 08:47:58 +01:00 committed by GitHub
parent 133e3f72f9
commit 279178f103
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
24 changed files with 1541 additions and 1495 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1449
docs/Credits.md
View File

File diff suppressed because it is too large Load Diff

48
docs/Developers/Building-Locally.md
View File

@ -6,25 +6,25 @@ So first things first - the initial "No assumptions" setup to have Unciv run fro
## With Android Studio
* 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.3 under "Android SDK Build-Tools <whatever version you have>"
* 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'
- 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.3 under "Android SDK Build-Tools <whatever version you have>"
- 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!
@ -34,15 +34,13 @@ If you also have JDK 11 installed, you can compile Unciv on your own by cloning
### Windows
Running: `gradlew desktop:run`
Building: `gradlew desktop:dist`
- Running: `gradlew desktop:run`
- Building: `gradlew desktop:dist`
### Linux/Mac OS
Running: `./gradlew desktop:run`
Building: `./gradlew desktop:dist`
- 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.*

4
docs/Developers/Coding-standards.md
View File

@ -1,3 +1,5 @@
# Coding standards
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.
@ -12,4 +14,4 @@ For loops go waaaay back, forEach doesn't. As an added bonus, I'm pretty sure th
## 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.
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.

67
docs/Developers/From-code-to-deployment.md
View File

@ -8,31 +8,31 @@ The process has two major parts, one is "Getting your code in the main repositor
## 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!
- 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 "prepare version" in one of the open PRs tagged as 'mergeable translation' to trigger the translation branch creation.
This also bumps the versions in the buildConfig.kt file, and generates a starting version summary in changelog.md.
Merge the PR and delete the branch (so next version branch starts fresh)
* From my workstation - pull the latest changes and run the [translation generation](../Other/Translating.md#translation-generation---for-developers)
* Edits to the autogenerated version notes in changelog.md to make them less than 500 chars (needed for Google Play) and more user-readable
* 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://monitor.f-droid.org/builds/running), and the new release will eventually be available [here](https://f-droid.org/en/packages/com.unciv.app/)
- Comment "prepare version" in one of the open PRs tagged as 'mergeable translation' to trigger the translation branch creation.
- This also bumps the versions in the buildConfig.kt file, and generates a starting version summary in changelog.md.
- Merge the PR and delete the branch (so next version branch starts fresh)
- From my workstation - pull the latest changes and run the [translation generation](../Other/Translating.md#translation-generation---for-developers)
- Edits to the autogenerated version notes in changelog.md to make them less than 500 chars (needed for Google Play) and more user-readable
- 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:
- 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://monitor.f-droid.org/builds/running), and the new release will eventually be available [here](https://f-droid.org/en/packages/com.unciv.app/)
## About Google Play publishing
@ -41,33 +41,34 @@ We start at a 10% rollout, after a day with no major problems go to 30%, and aft
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.
- 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.
## Updating the wiki
Pages for the [Unciv Github Wiki](https://github.com/yairm210/Unciv/wiki/) are kept in the main repository under [/docs/wiki](/docs/wiki).
Pages for the [Unciv Github Wiki](https://github.com/yairm210/Unciv/wiki/) are kept in the main repository under [docs](https://github.com/yairm210/Unciv/tree/master/docs).
The process to edit the wiki is as follows:
1. Open a pull request in the main Unciv repository that changes files under [/docs/wiki](/docs/wiki).
1. Open a pull request in the main Unciv repository that changes files under [docs](https://github.com/yairm210/Unciv/tree/master/docs).
2. Once the pull request is merged, an account with commit privileges on the Unciv repository leaves a comment saying "`update wiki`".
3. This comment triggers a bot to copy all the wiki files from the main repository into the Github wiki, with a link back to the PR in its commit message for credit.
Doing things this way has several distinct advantages over using the Github Wiki web interface directly:
* Changes can be proposed via PR and proofread or fact-checked.
* A proper MarkDown editor or IDE can be used to write the wiki, bringing faster editing, clickable links while editing, better live HTML preview, and automatic detection of problems like broken links.
* The wiki files can also be browsed at https://github.com/yairm210/Unciv/tree/master/docs/wiki.
* Auto-generated documentation made by the build process can be placed directly in the wiki.
- Changes can be proposed via PR and proofread or fact-checked.
- A proper MarkDown editor or IDE can be used to write the wiki, bringing faster editing, clickable links while editing, better live HTML preview, and automatic detection of problems like broken links.
- The wiki files can also be browsed at https://github.com/yairm210/Unciv/tree/master/docs/wiki.
- Auto-generated documentation made by the build process can be placed directly in the wiki.
However, it also imposes a couple of conventions about how links should best be formatted:
|Link type|Format|Example|
|---|---|---|
|Inter-wiki|Should begin with "./", and include ".md".|[`./Mods.md#other`](../Modders/Mods.md#other)|
|Code or asset file|Should begin with "/", and be relative to the project root.|[`/android/assets/game.png`](/game.png)|
| Link type | Format | Example |
| --------- | ------ | ------- |
| Inter-wiki | Should begin with "./", and include ".md". | [`./Mods.md#other`](../Modders/Mods.md#other) |
| Code or asset file | Should begin with "https://github.com/yairm210/Unciv/blob/master/", and be relative to the project root. | [`https://github.com/yairm210/Unciv/blob/master/android/assets/game.png`](https://github.com/yairm210/Unciv/blob/master/android/assets/game.png) |
These formats will allow IDEs like Android studio to resolve these links and check for broken links, while also working on the [Github code browser](https://github.com/yairm210/Unciv/tree/master/docs/wiki).
These formats will allow IDEs like Android studio to resolve these links and check for broken links, while also working on the [Github code browser](https://github.com/yairm210/Unciv/tree/master/docs).
The bot that updates the wiki from the main repository automatically translates them into formats that are compatible with Github Wikis, which have somewhat non-standard requirements.

69
docs/Developers/Game Making Tips.md → docs/Developers/Game-Making-Tips.md
View File

@ -1,16 +1,18 @@
# Tips and tricks for making a LibGDX game
# Game Making Tips
## Tips and tricks for making a LibGDX game
Here are a bunch of things I've learned from by brief excursion into the world of game making.
Some of our will be obvious to you, some will not.
## Use Kotlin
### Use Kotlin
Unciv started its life as a Unity project in C#, was shifted to Java and LibGDX, and finally to Kotlin.
I regret every minute that I spent writing events in Java, this is probably the most significant change that your application could see.
## Use Scene2d
### Use Scene2d
Unless you plan on creating images on the fly, you'll probably be using prerendered assets.
@ -18,7 +20,7 @@ Placing them manually is akin to manually positioning html tags, instead of usin
So too is Scene2d - as a placement framework. it's relatively simple to understand, especially when you...
## Ignore Horizontal and Vertical groups - use Table
### Ignore Horizontal and Vertical groups - use Table
I personally found that table has all the functionality of the above, and more.
@ -26,27 +28,25 @@ Each class has a different syntax too, so I found it much simpler to just stick
Table does just about EVERYTHING! It's insanely amazing!
## If your game is getting slow, use the Android profiler in Android Studio
### If your game is getting slow, use the Android profiler in Android Studio
The top-down CPU chart is the best code profiler I've ever seen, use it to your advantage!
### Cache everything
#### Cache everything
Caching is a trade-off between purer, state-agnostic code and higher performance.
Coming from a PC background, I automatically assume that anything less than O(n^2) is less than a millisecond and therefore, not a caching candidate.
This is not so in mobile development.
This becomes especially relevant when you need to save and load game data which has lots of connected parts - you have to avoid circular references, and you want to minimise the save size, but you need to reconstruct the missing links when loading.
### Minimize String operations
#### Minimize String operations
All the tip and tricks you've heard to minimize String operations? Use them!
String constants should be consts, use StringBuilders (or just ArrayLists of strings that you later .joinToString())
### Sequences everywhere!
#### Sequences everywhere!
One thing I did not expect to be such an issue is intermediate lists when sorting and mapping.
@ -54,12 +54,11 @@ But apparently, the memory allocation for these tasks is Serious Business.
So whenever possible, take your list and .asSequence() it before activating list operations - this results in huge savings of both time and memory!
The only time you shouldn't be doing this, though, is when you want to cache the specific values for future use -
sequences will go through the whole process every time you iterate on them, so just .toList() them when you've gotten the final results!
# General tips for making an Open Source game
The only time you shouldn't be doing this, though, is when you want to cache the specific values for future use - sequences will go through the whole process every time you iterate on them, so just .toList() them when you've gotten the final results!
## Lower the entry bar - for both programmers and players
## General tips for making an Open Source game
### Lower the entry bar - for both programmers and players
I think that most Open Source games suffer from this problem - those that are in are way in, but those that are out and want to join have to learn the ecosystem.
@ -73,11 +72,11 @@ Same think with new players - getting the game up and running should be AS SIMPL
This includes:
- Source-To-Executable automation - I use Travis
- Play stores and the like
- Internal game tutorials - your players will NEVER BE SATISFIED with this last point, but at least do what you candidate
- Source-To-Executable automation - I use Travis
- Play stores and the like
- Internal game tutorials - your players will NEVER BE SATISFIED with this last point, but at least do what you candidate
## Community, Community, Community!
### Community, Community, Community!
I, personally, underestimated this point for about a year after launch.
@ -94,14 +93,14 @@ Another think to remember is that there's a larger community around you - the Op
There are lots of people who will play your game only because it's open source, and it also means they don't have as many options.
For example...
For example...
- Being the best 4X game means competing with the biggest names out there
- Being the best 4X game for Linux means many less competitors, but All The Cool Kids (tm) are multiplatforming nowadays so you're still outperformed.
- Being the best Open Source 4X game means about 5 competitors, and no money is involved either so the average entry is not as polished.
- Being the best Open Source 4X game for Android... means having so few competitors that it's totally doable.
- Being the best 4X game means competing with the biggest names out there
- Being the best 4X game for Linux means many less competitors, but All The Cool Kids (tm) are multiplatforming nowadays so you're still outperformed.
- Being the best Open Source 4X game means about 5 competitors, and no money is involved either so the average entry is not as polished.
- Being the best Open Source 4X game for Android... means having so few competitors that it's totally doable.
## Everything is marketing.
### Everything is marketing.
Your game's name, the icon, screenshots, everything a player sees about your game is marketing.
@ -109,7 +108,7 @@ Icons and bylines are especially important, since they're the first things your
I saw an almost 50% (!) by changing the icon, after several experiments, which Google Play lets you conduct very easily.
## Translations are part of your source code
### Translations are part of your source code
This may be slightly controversial, so I'll explain.
@ -117,15 +116,15 @@ We went though a number of iterations regarding how to save translations until w
The important parts are:
- Game translation files should be AUTO GENERATED. This allows you to add new objects into the game with impunity,
knowing that corresponding lines will be auto-added to the translations.
- Translations for each language should be stored separately - this allows concurrent modification of several independent languages with no risk of conflict
- Game translation files should be AUTO GENERATED. This allows you to add new objects into the game with impunity,
knowing that corresponding lines will be auto-added to the translations.
- Translations should be PR'd in! This allows other speakers to question or change the proposed translations, and allows you to run tests on your translations.
If you require a specific format, this is invaluable as it means that bad translations will be rejected at the door.
- Translations for each language should be stored separately - this allows concurrent modification of several independent languages with no risk of conflict
## Open source problems require open (source?) solutions
- Translations should be PR'd in! This allows other speakers to question or change the proposed translations, and allows you to run tests on your translations.
If you require a specific format, this is invaluable as it means that bad translations will be rejected at the door.
### Open source problems require open (source?) solutions
TL;DR, consider using APIs that are free, even if they're not Open Source.
@ -144,8 +143,7 @@ We are small and open, so we just allow to download from Github, which lets us u
And unlike the Dropbox usage, which is basically abuse, Github is built for this kind of thing!
This is exactly the kind of use case they were thinking of to start with!
# The Reckoning
## The Reckoning
There comes a time in every project where the cool stuff is done. All the cutting-edge awesomeness and algorithmic playdough is done, and now all (hah) it needs is polish.
@ -176,4 +174,3 @@ And that's basically the loop I've been in for the last hundred versions or so!
I don't think I'll ever really continue to finish G&K, I'm DEFINITELY not planning on implementing BNW mechanics which frankly I think are...not great.
That's where I am right now. Kind of done with the game, but considering that I thought that half a year ago and releases are still releasing roughly every week, also kind of not.

111
docs/Developers/Project-structure-and-major-classes.md
View File

@ -22,22 +22,22 @@ So yes, you can - for instance - get the center tile of a city, a TileInfo, dire
The Game State:
* GameInfo
* CivilizationInfo
* CityInfo
* TileMap
* TileInfo
* MapUnit
* RuleSet (unique in that it is not part of 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
- MainMenuScreen
- NewGameScreen
- WorldScreen
- CityScreen
- MapEditorScreen
- Picker Screens - TechPickerScreen, PolicyPickerScreen, ImprovementPickerScreen, PromotionPickerScreen
## Game State
@ -45,14 +45,14 @@ The UI:
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*.
That is, The Game is the *currently playe*_ 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.
- 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.
@ -64,9 +64,9 @@ This represents one of the players of the game, and NOT a specific nation - mean
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`
- 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`
@ -74,9 +74,9 @@ 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
- 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`
@ -87,11 +87,12 @@ This contains mostly helper functions and acts as a wrapper for the list of tile
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 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`
@ -100,9 +101,10 @@ Unlike buildings, Unit in Unciv has two meanings. One is a *Type* of unit (like
`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`
- A name - references a specific `BaseUnit`
- Health and Movement
- Promotion status - `UnitPromotions`
### Ruleset
@ -113,15 +115,16 @@ Since these things remain the same for every game, these are not saved on a per-
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`
- `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.
@ -141,9 +144,9 @@ This is what the user sees when first entering the game. It acts as a hub to loa
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
- 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`
@ -152,20 +155,22 @@ This is basically a giant setting screen for GameOptions and MapOptions classes,
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 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.
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`
- 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

56
docs/Developers/Translations,-mods,-and-modding-freedom-in-Open-Source.md
View File

@ -1,10 +1,12 @@
# Translations, mods, and modding freedom in Open Source
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
## Translations
## The translation process
### 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?
@ -13,40 +15,34 @@ This means translators are both amateurs and not *obligated* to translate, so if
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
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.
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 in the past:
- 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.
- 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.
- 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
### 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).
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
### 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!
@ -56,19 +52,20 @@ As you can see, the *placement* of the parameters can change between languages,
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
- 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
## Uniques
## Moddable unique effects
### 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.
@ -82,7 +79,7 @@ Since the translation template is the same as the unique template, these uniques
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
### 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.
@ -93,10 +90,9 @@ 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](../Modders/Unique-parameter-types.md).
There are also filters for units, all acceptable values are documented [here](../Modders/unique%20parameters).
## Unique management with Enums
### 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.
@ -104,9 +100,9 @@ Modders discover during gameplay that the values they put for uniques were incor
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
- 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,.
@ -115,7 +111,7 @@ The "autodetection" of parameter types for translations can also be fed from her
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
### 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.
@ -126,7 +122,7 @@ B. Turns the conditional into an extra piece that can be added onto any other un
Conditionals have a lot of nuance, especially regarding translation and ordering, so work in that field is more gradual.
## What's next?
### 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.

37
docs/Modders/Creating-a-custom-tileset.md
View File

@ -1,34 +1,34 @@
# How to make Unciv use your custom tileset
### You should read the [Mods](Mods.md) page first before proceeding
**You should read the [Mods](Mods.md) 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.
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:
- 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.
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},
@ -40,25 +40,28 @@ This is an example of such a config file that I will explain below:
```
### 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.
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.
@ -68,12 +71,10 @@ Unciv can colour units according to the civilization that owns them. [[PR3231]](
This is used by providing multiple images per unit, each representing a coloured layer. The image suffixed with "-1" will be tinted to the civilization's inner colour, and the image suffixed with "-2" will be tinted to the civilization's outer colour. For example:
|Image|Description|Colour|
|---|---|---|
|Archer.png|Base image|Untinted|
|Archer-1.png|Colour layer|Nation inner colour|
|Arhcer-2.png|Colour layer|Nation outer colour|
| Image | Description | Colour |
| ----- | ----------- | ------ |
| Archer.png | Base image | Untinted |
| Archer-1.png | Colour layer | Nation inner colour |
| Arhcer-2.png | Colour layer | Nation outer colour |
The [Civ Army Color Style Sheet](https://github.com/AdityaMH/Civ-Army-Color-Style-Sheet/tree/main/Images/TileSets/FantasyHex/Units) mod by @AdityaMH and the [5Hex Tileset](https://github.com/ravignir/5Hex-Tileset/tree/master/Images/TileSets/5Hex/Units) by @ravignir are very good practical examples of how this can be used.

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

@ -1,35 +1,32 @@
# Images and Audio
- [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.md)
- [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.md#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. The first part of the path is not relevant for overriding, it controls which of a set of atlas files will carry the image, but for selection in the game only the rest of the path is relevant. So, to override "Images.Tech/TechIcons/Archery.png" you could place your image as "Images/TechIcons/Archery.png" and it would work because the "TechIcons/Archery" part is the key.
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. The first part of the path is not relevant for overriding, it controls which of a set of atlas files will carry the image, but for selection in the game only the rest of the path is relevant. So, to override "Images.Tech/TechIcons/Archery.png" you could place your image as "Images/TechIcons/Archery.png" and it would work because the "TechIcons/Archery" part is the key.
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
You will need to supply the graphics for new elements - a new unit needs its icon just as a new nation does. The rules are:
* The path and name of the image file need to conform to the rule: `Image[.AtlasName]/Type-specific/Objectname.png` (Type-specific means "TechIcons" for a Technology, "NationIcons" for a Nation and so on. See vanilla game folders. Objectname is the exact name as defined in json, before translation.)
* All path parts are case sensitive.
* Unit Pixel sprites and [Tilesets](Creating-a-custom-tileset.md) follow special rules.
* Promotions can be named "`[Unitname] ability`". In such a case, if `UnitIcons/Unitname.png` exists it will fall back to that unit icon when `UnitPromotionIcons/Unitname ability.png` is missing.
* Promotions can be named "Something I" (or " II" or " III"). The suffix will be removed and painted as little stars, only the base `UnitPromotionIcons/Something.png` will be loaded.
* The special rules for promotions can be combined, e.g. "`[Warrior] ability III`" will fall back to the Warrior unit icon and paint 3 Stars on it.
- The path and name of the image file need to conform to the rule: `Image[.AtlasName]/Type-specific/Objectname.png` (Type-specific means "TechIcons" for a Technology, "NationIcons" for a Nation and so on. See vanilla game folders. Objectname is the exact name as defined in json, before translation.)
- All path parts are case sensitive.
- Unit Pixel sprites and [Tilesets](Creating-a-custom-tileset.md) follow special rules.
- Promotions can be named "`[Unitname] ability`". In such a case, if `UnitIcons/Unitname.png` exists it will fall back to that unit icon when `UnitPromotionIcons/Unitname ability.png` is missing.
- Promotions can be named "Something I" (or " II" or " III"). The suffix will be removed and painted as little stars, only the base `UnitPromotionIcons/Something.png` will be loaded.
- The special rules for promotions can be combined, e.g. "`[Warrior] ability III`" will fall back to the Warrior unit icon and paint 3 Stars on it.
Additionally, there there are two kinds of images 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"
@ -37,28 +34,31 @@ Add the images to `/Images/WonderImages/`. They need to be named according to th
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.
## Sounds
Standard values are below. The sounds themselves can be found [here](/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_.
- _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.
## 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. Except for context-specific music as described in the following paragraphs, 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).
### Context-sensitive music: Overview
The Music Controller will generally play one track after another, with a pause (can be changed in options) between. While the "Leave game?" confirmation dialog is opened playback will fade out and pause and can resume when it is closed.
There are various 'triggers' in the game code initiating a choice for a new track. The new track will, if necessary, fade out the currently playing track quickly before it starts playing. Track choice involves context provided by the trigger and a random factor, and an attempt is made to not repeat any track until at least eight others have played.
@ -68,39 +68,41 @@ Mods can provide their own music folder, and if they are active its contents wil
One track is special: The Thatched Villagers (see also credits.md). The game is able to download it if the music folder is empty, and it is played when the music volume slider is used. It is also a fallback track should certain problems occur (a broken file, however, will shut down the player until another trigger happens).
### Context-sensitive music: List of Triggers
Triggers indicate context (call it intent, mood, whatever, it doesn't matter) by optionally providing a prefix and/or suffix to match against the file name. There are a few flags as well influencing choice or behaviour - one flag function is to make prefix or suffix mandatory, meaning if no available file matches the track chooser will do nothing. Otherwise, a next track will always be chosen from the available list by sorting and then picking the first entry. Sorting is done by in order of precedence: Prefix match, Suffix match, Recently played, and a random number. Therefore, as currently no triggers have an empty prefix, files matching none of the prefixes will never play unless there are less than eight files matching the requested prefix.
The current list of triggers is as follows:
| Description | Prefix | M[^M] | Suffix | M[^X] | Flags |
| ----------- |:------ |:---:| ----:|:---:|:---:|
| Description | Prefix | [^M] | Suffix | [^X] | Flags |
| ----------- |:------ |:----:| ------:|:----:|:-----:|
| Automatic next-track[^0] | | | Ambient | | |
| Launch game[^1] | | | Menu | | |
| Every 10th turn | (player civ name) | M | Peace or War[^2] | | F[^F] |
| New game: Select a mod | (mod name) | M | Theme | | S[^S] |
| New game: Pick a nation for a player | (nation name) | M | Theme or Peace | | S[^S] |
| Diplomacy: Select player | (nation name) | M | Peace or War[^3] | | S[^S] |
| First contact[^4] | (civ name) | M | Theme or Peace | M | |
| War declaration[^5] | (civ name) | M | War | M | |
| Civ defeated | (civ name) | | Defeat | M | |
| Golden Age | (civ name) | M | Golden | M | N[^N] |
| Wonder built | (wonder name) | M | Built | M | N[^N] |
| Tech researched | (tech name) | M | Researched | M | N[^N] |
| Map editor: Select nation start location | (nation name) | M | Theme | | S[^S] N[^N] |
| Options: Volume slider or Default track downloaded | | | | | D[^D] |
| Options: Click currently playing label[^6] | | M | Ambient | | S[^S] |
| Every 10th turn | (player civ name) | [^M] | Peace or War[^2] | | [^F] |
| New game: Select a mod | (mod name) | [^M] | Theme | | [^S] |
| New game: Pick a nation for a player | (nation name) | [^M] | Theme or Peace | | [^S] |
| Diplomacy: Select player | (nation name) | [^M] | Peace or War[^3] | | [^S] |
| First contact[^4] | (civ name) | [^M] | Theme or Peace | [^X] | |
| War declaration[^5] | (civ name) | [^M] | War | [^X] | |
| Civ defeated | (civ name) | | Defeat | [^X] | |
| Golden Age | (civ name) | [^M] | Golden | [^X] | [^N] |
| Wonder built | (wonder name) | [^M] | Built | [^X] | [^N] |
| Tech researched | (tech name) | [^M] | Researched | [^X] | [^N] |
| Map editor: Select nation start location | (nation name) | [^M] | Theme | | [^S] [^N] |
| Options: Volume slider or Default track downloaded | | | | | [^D] |
| Options: Click currently playing label[^6] | | [^M] | Ambient | | [^S] |
Legend:
[^N]: **Not implemented**
[^M]: Prefix must match. If no matching file is found, the trigger will do nothing.
[^X]: Suffix must match. If no matching file is found, the trigger will do nothing.
[^S]: Stop after playback. No automatic next choice.
[^F]: Slow fadeout of replaced track.
[^D]: Always plays the default file.
[^0]: Whenever a track finishes and the configured silence has elapsed, an 'Ambient' track without any context is chosen. Also triggered by 'resume' (e.g. switching to another app and back on Android)
[^1]: First opening of the Main Menu (or the initial language picker).
[^2]: Whether the active player is at war with anybody.
[^3]: According to your relation to the picked player.
[^4]: Excluding City States.
[^5]: Both in the alert when another player declares War on you and declaring War yourself in Diplomacy screen.
[^6]: Yes these flags are not optimal.
- [^N]: **Not implemented**
- [^M]: Prefix must match. If no matching file is found, the trigger will do nothing.
- [^X]: Suffix must match. If no matching file is found, the trigger will do nothing.
- [^S]: Stop after playback. No automatic next choice.
- [^F]: Slow fadeout of replaced track.
- [^D]: Always plays the default file.
- [^0]: Whenever a track finishes and the configured silence has elapsed, an 'Ambient' track without any context is chosen. Also triggered by 'resume' (e.g. switching to another app and back on Android)
- [^1]: First opening of the Main Menu (or the initial language picker).
- [^2]: Whether the active player is at war with anybody.
- [^3]: According to your relation to the picked player.
- [^4]: Excluding City States.
- [^5]: Both in the alert when another player declares War on you and declaring War yourself in Diplomacy screen.
- [^6]: Yes these flags are not optimal.

75
docs/Modders/JSON-files-for-mods.md
View File

@ -1,43 +1,45 @@
These pages are a work in progress. Information they contain may be incomplete.
# JSON files for mods
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](../Other/Civilization-related-JSON-files.md)
* [Beliefs.json](../Other/Civilization-related-JSON-files.md#beliefsjson)
* [Buildings.json](../Other/Civilization-related-JSON-files.md#buildingsjson)
* [Nations.json](../Other/Civilization-related-JSON-files.md#nationsjson)
* [Policies.json](../Other/Civilization-related-JSON-files.md#policiesjson)
* [Quests.json](../Other/Civilization-related-JSON-files.md#questsjson)
* [Religions.json](../Other/Civilization-related-JSON-files.md#religionsjson)
* [Specialists.json](../Other/Civilization-related-JSON-files.md#specialistsjson)
* [Techs.json](../Other/Civilization-related-JSON-files.md#techsjson)
* [Map-related JSON files](../Other/Map-related-JSON-files.md)
* [Terrains.json](../Other/Map-related-JSON-files.md#terrainsjson)
* [TileResources.json](../Other/Map-related-JSON-files.md#tileresourcesjson)
* [TileImprovements.json](../Other/Map-related-JSON-files.md#tileimprovementsjson)
* [Ruins.json](../Other/Map-related-JSON-files.md#ruinsjson)
* [Tileset-specific json](../Other/Map-related-JSON-files.md#tileset-specific-json)
* [Unit-related JSON files](../Other/Unit-related-JSON-files.md)
* [Units.json](../Other/Unit-related-JSON-files.md#unitsjson)
* [UnitPromotions.json](../Other/Unit-related-JSON-files.md#unitpromotionsjson)
* [UnitTypes.json](../Other/Unit-related-JSON-files.md#unittypesjson)
* [Miscellaneous JSON files](../Other/Miscellaneous-JSON-files.md)
* [Difficulties.json](../Other/Miscellaneous-JSON-files.md#difficultiesjson)
* [Eras.json](../Other/Miscellaneous-JSON-files.md#erasjson)
* [ModOptions.json](../Other/Miscellaneous-JSON-files.md#modoptionsjson)
* [Stats](../Other/Map-related-JSON-files.md#stats)
* [Sounds](../Other/Unit-related-JSON-files.md#sounds)
* [Civilopedia text](../Other/Miscellaneous-JSON-files.md#civilopedia-text)
## Table of Contents
- [General Overview of JSON files](#general-overview-of-json-files)
- [Civilization-related JSON files](../Other/Civilization-related-JSON-files.md)
- [Beliefs.json](../Other/Civilization-related-JSON-files.md#beliefsjson)
- [Buildings.json](../Other/Civilization-related-JSON-files.md#buildingsjson)
- [Nations.json](../Other/Civilization-related-JSON-files.md#nationsjson)
- [Policies.json](../Other/Civilization-related-JSON-files.md#policiesjson)
- [Quests.json](../Other/Civilization-related-JSON-files.md#questsjson)
- [Religions.json](../Other/Civilization-related-JSON-files.md#religionsjson)
- [Specialists.json](../Other/Civilization-related-JSON-files.md#specialistsjson)
- [Techs.json](../Other/Civilization-related-JSON-files.md#techsjson)
- [Map-related JSON files](../Other/Map-related-JSON-files.md)
- [Terrains.json](../Other/Map-related-JSON-files.md#terrainsjson)
- [TileResources.json](../Other/Map-related-JSON-files.md#tileresourcesjson)
- [TileImprovements.json](../Other/Map-related-JSON-files.md#tileimprovementsjson)
- [Ruins.json](../Other/Map-related-JSON-files.md#ruinsjson)
- [Tileset-specific json](../Other/Map-related-JSON-files.md#tileset-specific-json)
- [Unit-related JSON files](../Other/Unit-related-JSON-files.md)
- [Units.json](../Other/Unit-related-JSON-files.md#unitsjson)
- [UnitPromotions.json](../Other/Unit-related-JSON-files.md#unitpromotionsjson)
- [UnitTypes.json](../Other/Unit-related-JSON-files.md#unittypesjson)
- [Miscellaneous JSON files](../Other/Miscellaneous-JSON-files.md)
- [Difficulties.json](../Other/Miscellaneous-JSON-files.md#difficultiesjson)
- [Eras.json](../Other/Miscellaneous-JSON-files.md#erasjson)
- [ModOptions.json](../Other/Miscellaneous-JSON-files.md#modoptionsjson)
- [Stats](../Other/Map-related-JSON-files.md#stats)
- [Sounds](../Other/Unit-related-JSON-files.md#sounds)
- [Civilopedia text](../Other/Miscellaneous-JSON-files.md#civilopedia-text)
# General Overview of JSON files
## 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:
```
[
{
@ -51,6 +53,7 @@ Almost all Unciv JSON files start with a "[" and end with a "]". In between thes
}
]
```
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:
@ -63,6 +66,7 @@ There are different types of attributes:
| 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:
```
[
{
@ -71,18 +75,13 @@ Example of a Buildings.json adding a new "Cultural Library" building which gives
}
]
```
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
## 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](../Other/Civilization-related-JSON-files.md)
* [Map-related JSON files](../Other/Map-related-JSON-files.md)
* [Unit-related JSON files](../Other/Unit-related-JSON-files.md)
* [Miscellaneous JSON files](../Other/Miscellaneous-JSON-files.md)
The individual files are described on [separate pages](#Table-of-Contents).

14
docs/Modders/Making-a-new-Civilization.md
View File

@ -10,7 +10,7 @@ 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](/jsons/Civ%20V%20-%20Gods%20&%20Kings/Nations.json)
All of these need to be filled in in [Nations.json](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Gods%20&%20Kings/Nations.json)
## Get your Civ icon
@ -22,15 +22,13 @@ You'll need to put your icon in the [NationIcons folder](/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](/jsons/Civ%20V%20-%20Gods%20&%20Kings/Units.json) file, with an icon in the
[UnitIcons](/Images.Construction/UnitIcons) folder.
Units in general are added in the [Units.json](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Gods%20&%20Kings/Units.json) file, with an icon in the [UnitIcons](/Images.Construction/UnitIcons) folder.
The icon must be 200x200 pixels, white on transparent background - see [icon considerations](#icon-considerations) for details
@ -38,13 +36,11 @@ Remember that these are unique units, so search for an existing unique unit to s
## Adding unique buildings
Same as the units - info is in the [Buildings.json](/jsons/Civ%20V%20-%20Gods%20&%20Kings/Buildings.json) file
and icons in the [BuildingIcons](/Images.Construction/BuildingIcons) folder,
same rules for the icons apply (200x200 pixels, icon considerations)
Same as the units - info is in the [Buildings.json](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Gods%20&%20Kings/Buildings.json) file and icons in the [BuildingIcons](/Images.Construction/BuildingIcons) folder, same rules for the icons apply (200x200 pixels, icon considerations)
## Civ Unique
Check out our [list of uniques](Unique-parameter-types.md) to see all the cool special effects you can add to your civilization!
Check out our [list of uniques](Unique-parameters.md) to see all the cool special effects you can add to your civilization!
## Icon considerations
@ -54,4 +50,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](/docs/Credits.md) page
Credits for icons should go in the [Credits](/docs/Credits.md) page.

41
docs/Modders/Mods.md
View File

@ -1,3 +1,5 @@
# Mods
## What's this about?
Everyone has that thing they wish could be in the game.
@ -10,33 +12,31 @@ The game only knows how to recognize existing definitions, so you can't add *new
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.
- 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.md).
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](Images-and-Audio.md).
Custom tilesets are closely related, see [Creating a custom tileset](Creating-a-custom-tileset.md).
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:
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](/jsons). More information on these can be found [here](JSON-files-for-mods.md)
- Images - here you should put game images, as in [the base image files](/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](/jsons). More information on these can be found [here](JSON-files-for-mods.md)
- Images - here you should put game images, as in [the base image files](/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)
@ -47,6 +47,7 @@ For an example, you can refer to [the example mod](https://github.com/yairm210/U
If you want to add a new civilization as a mod, you should check out [the Civ making instructions](Making-a-new-Civilization.md) 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.
@ -71,17 +72,17 @@ The Images and jsons folders need to be in the root directory of the repo - see
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!
- 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"
- 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!
@ -97,10 +98,8 @@ In general, you should never be manually-loading your mods - not only is this cl
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`
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.
@ -108,6 +107,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](Unique-parameter-types.md)!
A list of uniques and how to use them can be found [here](Unique-parameters.md)!
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.md).
Some images don't exist at all in the base game, but can be added in mods. For more info, see [Audiovisual Mods](Images-and-Audio.md).

174
docs/Modders/Unique-parameters.md Normal file
View File

@ -0,0 +1,174 @@
# Unique parameters
This page contains an overview of all different parameters used in uniques and what values can be filled into them.
Each of the different parameter types is described below, including all possible values for them.
These are split into two categories:
- descriptions: e.g., "the name of any unit"
- `Text that looks like this`. This last one must be used exactly the same
Note that all of these are case-sensitive!
## baseUnitFilter
Unit filters can be divided up into two parts: `baseUnitFilter`s and `mapUnitFilter`s.
The former is tested against the unit as it appears in the json.
This means it doesn't have an owning civ or tile it stands on, just its base properties.
The latter is tested against the unit as it appears on the map, including its nation, tile, health and all other properties.
The following are allowed to be used:
- unit name
- unit type - e.g. Melee, Ranged, WaterSubmarine, etc.
- `Land`, `Water`, `Air`
- `land units`, `water units`, `air units`
- `non-air` for non-air non-missile units
- `Military`, `military units`
- `Civilian`, `civilian units`
- `All`
- `Melee`
- `Ranged`
- `Nuclear Weapon`
- `Great Person`, `Great`
- `Embarked`
- Any exact unique the unit has
- Any exact unique the unit type has
- Any combination of the above (will match only if all match). The format is `{filter1} {filter2}` and can match any number of filters. For example: `[{Military} {Water}]` units, `[{non-air} {Armor}]` units, etc. No space or other text is allowed between the `[` and the first `{`.
## buildingFilter
Allows to only activate a unique for certain buildings. Allowed options are:
- `All`
- `Buildings`, `Building`
- `Wonders`, `Wonders`
- `National Wonder`
- `World Wonder` -- All wonders that are not national wonders
- building name
- The name of the building it replaces (so for example uniques for libraries will apply to paper makers as well)
- an exact unique the building has (e.g.: `spaceship part`)
- `Culture`, `Gold`, etc. if the building is `stat-related` for that stat. Stat-related buildings are defined as one of the following:
- Provides that stat directly (e.g. +1 Culture)
- Provides a percentage bonus for that stat (e.g. +10% Production)
- Provides that stat as a bonus for resources (e.g. +1 Food from every Wheat)
- Provides that stat per some amount of population (e.g. +1 Science for every 2 population [cityFilter])
## cityFilter
cityFilters allow us to choose the range of cities affected by this unique:
- `in this city`
- `in all cities`
- `in other cities`
- `in all coastal cities`
- `in capital`
- `in all non-occupied cities` - all cities that are not puppets and don't have extra unhappiness from being recently conquered
- `in all cities with a world wonder`
- `in all cities connected to capital`
- `in all cities with a garrison`
- `in non-enemy foreign cities` - In all cities owned by civs other than you that you are not at war with
- `in foreign cities`
- `in annexed cities`
- `in holy cities`
- `in City-State cities`
- `in cities following this religion` - Should only be used in pantheon/follower uniques for religions
- `in all cities in which the majority religion is a major religion`
- `in all cities in which the majority religion is a enhanced religion`
## improvementFilter
For filtering a specific improvement.
Allowed values are:
- improvement name (Note that "Road" and "Railroad" _do_ work as improvementFilters, but not as tileFilters at the moment.)
- `All`
- `Great Improvements`, `Great`
- `All Road` - for Roads & Railroads
## mapUnitFilter
This indicates a unit as placed on the map. Compare with `baseUnitFilter`.
It can be any value noted in `baseUnitFilter` or one of the following:
- `Wounded`, `wounded units`
- `City-State`
- `Barbarians`, `Barbarian`
- Again, any combination of the above is also allowed, e.g. `[{Wounded} {Water}]` units.
## populationFilter
A filter determining a part of the population of a city. It can be any of the following values:
- `Population`
- `Specialists`
- `Unemployed`
- `Followers of the Majority Religion` or `Followers of this Religion`, both of which only apply when this religion is the majority religion in that city
## regionType
Used for dividing the world into regions in each of which a single player is placed at the start of the game.
Allowed values are `Hybrid` and the name of any terrain that has one of the following two uniques:
- `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]`
## simpleTerrain
Used by NaturalWonderGenerator to place natural wonders
Allowed values are:
- `Land`
- `Water`
- `Elevated`
- The name of any terrain
## stats
This indicates a text comprised of specific stats and is slightly more complex.
Each stats is comprised of several stat changes, each in the form of `+{amount} {stat}`, where 'stat' is one of the seven major stats mentioned above.
For example: `+1 Science`.
These can be strung together with ", " between them, for example: `+2 Production, +3 Food`.
## terrainFilter
This indicates the terrain on a single tile. The following values are allowed:
- A filter names a specific json attribute (by name):
- Base terrain
- Terrain features
- Base terrain uniques
- Terrain feature uniques
- Resource
- Natural wonder
- Or the filter is a constant string choosing a derived test:
- `All`
- `Water`, `Land`
- `Coastal` (at least one direct neighbor is a coast)
- `River` (as in all 'river on tile' contexts, it means 'adjacent to a river on at least one side')
- `Open terrain`, `Rough terrain` (note all terrain not having the rough unique is counted as open)
- `Friendly Land` - land belonging to you, or other civs with open borders to you
- `Foreign Land` - any land that isn't friendly land
- `Enemy land` - any land belonging to a civ you are at war with
- `Water resource`, `Strategic resource`, `Luxury resource`, `Bonus resource`
- `Natural Wonder` (as opposed to above which means testing for a specific Natural Wonder by name, this tests for any of them)
Please note all of these are _case-sensitive_.
Also note: Resource filters depend on whether a viewing civ is known in the context where the filter runs. Water and specific tests require a viewing civ, and if the resource needs a tech to be visible, that tech to be researched by the viewing civ. The other resource category tests can succeed without a known viewing civ only for resources not requiring any tech. So - test your mod!
So for instance, the unique "[stats] from [tileFilter] tiles [cityFilter]" can match several cases:
## terrainQuality
Used to indicate for what use the terrain should be viewed when dividing the world into regions, in each of which a single player is placed at the start of the game.
Allowed values are:
- improvement name (Note that "Road" and "Railroad" _do_ work as improvementFilters, but not as tileFilters at the moment.)
- "All"
- "Great Improvements", "Great"
- "All Road" - for Roads & Railroads

170
docs/Modders/unique parameters.md
View File

@ -1,170 +0,0 @@
# Unique parameter types
This page contains an overview of all different parameters used in uniques and what values can be filled into them.
Each of the different parameter types is described below, including all possible values for them.
These are split into two categories:
- descriptions: e.g., "the name of any unit"
- `Text that looks like this`. This last one must be used exactly the same
Note that all of these are case-sensitive!
## baseUnitFilter
Unit filters can be divided up into two parts: `baseUnitFilter`s and `mapUnitFilter`s.
The former is tested against the unit as it appears in the json.
This means it doesn't have an owning civ or tile it stands on, just its base properties.
The latter is tested against the unit as it appears on the map, including its nation, tile, health and all other properties.
The following are allowed to be used:
- unit name
- unit type - e.g. Melee, Ranged, WaterSubmarine, etc.
- `Land`, `Water`, `Air`
- `land units`, `water units`, `air units`
- `non-air` for non-air non-missile units
- `Military`, `military units`
- `Civilian`, `civilian units`
- `All`
- `Melee`
- `Ranged`
- `Nuclear Weapon`
- `Great Person`, `Great`
- `Embarked`
- Any exact unique the unit has
- Any exact unique the unit type has
- Any combination of the above (will match only if all match). The format is `{filter1} {filter2}` and can match any number of filters. For example: `[{Military} {Water}]` units, `[{non-air} {Armor}]` units, etc. No space or other text is allowed between the `[` and the first `{`.
## buildingFilter
Allows to only activate a unique for certain buildings. Allowed options are:
- `All`
- `Buildings`, `Building`
- `Wonders`, `Wonders`
- `National Wonder`
- `World Wonder` -- All wonders that are not national wonders
- building name
- The name of the building it replaces (so for example uniques for libraries will apply to paper makers as well)
- an exact unique the building has (e.g.: `spaceship part`)
- `Culture`, `Gold`, etc. if the building is `stat-related` for that stat. Stat-related buildings are defined as one of the following:
- Provides that stat directly (e.g. +1 Culture)
- Provides a percentage bonus for that stat (e.g. +10% Production)
- Provides that stat as a bonus for resources (e.g. +1 Food from every Wheat)
- Provides that stat per some amount of population (e.g. +1 Science for every 2 population [cityFilter])
## cityFilter
cityFilters allow us to choose the range of cities affected by this unique:
- `in this city`
- `in all cities`
- `in other cities`
- `in all coastal cities`
- `in capital`
- `in all non-occupied cities` - all cities that are not puppets and don't have extra unhappiness from being recently conquered
- `in all cities with a world wonder`
- `in all cities connected to capital`
- `in all cities with a garrison`
- `in non-enemy foreign cities` - In all cities owned by civs other than you that you are not at war with
- `in foreign cities`
- `in annexed cities`
- `in holy cities`
- `in City-State cities`
- `in cities following this religion` - Should only be used in pantheon/follower uniques for religions
- `in all cities in which the majority religion is a major religion`
- `in all cities in which the majority religion is a enhanced religion`
## improvementFilter
For filtering a specific improvement.
Allowed values are:
- improvement name (Note that "Road" and "Railroad" _do_ work as improvementFilters, but not as tileFilters at the moment.)
- `All`
- `Great Improvements`, `Great`
- `All Road` - for Roads & Railroads
## mapUnitFilter
This indicates a unit as placed on the map. Compare with `baseUnitFilter`.
It can be any value noted in `baseUnitFilter` or one of the following:
- `Wounded`, `wounded units`
- `City-State`
- `Barbarians`, `Barbarian`
- Again, any combination of the above is also allowed, e.g. `[{Wounded} {Water}]` units.
## populationFilter
A filter determining a part of the population of a city. It can be any of the following values:
- `Population`
- `Specialists`
- `Unemployed`
- `Followers of the Majority Religion` or `Followers of this Religion`, both of which only apply when this religion is the majority religion in that city
## regionType
Used for dividing the world into regions in each of which a single player is placed at the start of the game.
Allowed values are `Hybrid` and the name of any terrain that has one of the following two uniques:
- `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]`
## simpleTerrain
Used by NaturalWonderGenerator to place natural wonders
Allowed values are:
- `Land`
- `Water`
- `Elevated`
- The name of any terrain
## stats
This indicates a text comprised of specific stats and is slightly more complex.
Each stats is comprised of several stat changes, each in the form of `+{amount} {stat}`, where 'stat' is one of the seven major stats mentioned above.
For example: `+1 Science`.
These can be strung together with ", " between them, for example: `+2 Production, +3 Food`.
## terrainFilter
This indicates the terrain on a single tile. The following values are allowed:
- A filter names a specific json attribute (by name):
- Base terrain
- Terrain features
- Base terrain uniques
- Terrain feature uniques
- Resource
- Natural wonder
- Or the filter is a constant string choosing a derived test:
- `All`
- `Water`, `Land`
- `Coastal` (at least one direct neighbor is a coast)
- `River` (as in all 'river on tile' contexts, it means 'adjacent to a river on at least one side')
- `Open terrain`, `Rough terrain` (note all terrain not having the rough unique is counted as open)
- `Friendly Land` - land belonging to you, or other civs with open borders to you
- `Foreign Land` - any land that isn't friendly land
- `Enemy land` - any land belonging to a civ you are at war with
- `Water resource`, `Strategic resource`, `Luxury resource`, `Bonus resource`
- `Natural Wonder` (as opposed to above which means testing for a specific Natural Wonder by name, this tests for any of them)
Please note all of these are _case-sensitive_.
Also note: Resource filters depend on whether a viewing civ is known in the context where the filter runs. Water and specific tests require a viewing civ, and if the resource needs a tech to be visible, that tech to be researched by the viewing civ. The other resource category tests can succeed without a known viewing civ only for resources not requiring any tech. So - test your mod!
So for instance, the unique "[stats] from [tileFilter] tiles [cityFilter]" can match several cases:
## terrainQuality
Used to indicate for what use the terrain should be viewed when dividing the world into regions, in each of which a single player is placed at the start of the game.
Allowed values are:
- improvement name (Note that "Road" and "Railroad" _do_ work as improvementFilters, but not as tileFilters at the moment.)
- "All"
- "Great Improvements", "Great"
- "All Road" - for Roads & Railroads

110
docs/Other/Civilization-related-JSON-files.md
View File

@ -1,38 +1,30 @@
- [Beliefs.json](#beliefsjson)
- [Buildings.json](#buildingsjson)
- [Nations.json](#nationsjson)
- [Policies.json](#policiesjson)
- [Branch priorities](#branch-priorities)
- [Quests.json](#questsjson)
- [Religions.json](#religionsjson)
- [Specialists.json](#specialistsjson)
- [Techs.json](#techsjson)
- [Column structure](#column-structure)
- [Tech structure](#tech-structure)
# Civilization-related JSON files
## Beliefs.json
[link to original](/jsons/Civ%20V%20-%20Gods%20&%20Kings/Beliefs.json)
[link to original](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Gods%20%26%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 |
| --------- | ---- | --------------- | ----- |
| Attribute | Type | Optional | 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](../Modders/Unique-parameter-types.md#buildings-only), as well as the general uniques on that page |
| 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](../Modders/Unique-parameters.md#buildings-only), as well as the general uniques on that page |
| civilopediaText | List | Default empty | see [civilopediaText chapter](Miscellaneous-JSON-files.md#civilopedia-text) |
## Buildings.json
[link to original](/jsons/Civ%20V%20-%20Vanilla/Buildings.json)
[link to original](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Gods%20%26%20Kings/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 |
| --------- | ---- | --------------- | ----- |
| Attribute | Type | Optional | 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 |
@ -45,8 +37,8 @@ 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](/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](/jsons/Civ%20V%20-%20Gods%20&%20Kings/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/yairm210/Unciv/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/yairm210/Unciv/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](Map-related-JSON-files.md#tileresourcesjson) |
@ -58,21 +50,21 @@ 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](../Modders/Unique-parameter-types.md#buildings-only) |
| uniques | List of Strings | defaults to none | List of unique abilities this building has. Most of these can be found [here](../Modders/uniques) |
| 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](/jsons/Civ%20V%20-%20Gods%20&%20Kings/Specialists.json)), valid values are Integers, the amount of slots provided for this specialist |
| 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/yairm210/Unciv/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.md#civilopedia-text) |
## Nations.json
[Link to original](/jsons/Civ%20V%20-%20Vanilla/Nations.json)
[Link to original](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Gods%20%26%20Kings/Nations.json)
This file contains all the nations and city states, including Barbarians and Spectator.
| Attribute | Type | Optional? | Notes |
|-----------|------|-----------|-------|
| 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 |
@ -93,41 +85,44 @@ 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](../Modders/Unique-parameter-types.md#general-uniques) |
| uniques | List | Default empty | Properties of the civilization - see [here](../Modders/Unique-parameters.md#general-uniques) |
| cities | List | Default empty | City names used sequentially for newly founded cities. |
| civilopediaText | List | Default empty | see [civilopediaText chapter](Miscellaneous-JSON-files.md#civilopedia-text) |
## Policies.json
[Link to original](/jsons/Civ%20V%20-%20Vanilla/Policies.json)
[Link to original](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Gods%20%26%20Kings/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 |
|-----------|------|-----------|-------|
| Attribute | Type | Optional | Notes |
| --------- | ---- | -------- | ----- |
| name | String | Required | |
| era | String | Required | Unlocking era as defined in [Eras.json](Miscellaneous-JSON-files.md#erasjson) |
| era | String | Required | Unlocking era as defined in [Eras.json](Miscellaneous-JSON-files.md#Eras.json) |
| priorities | Object | Default empty | Priorities for each victory type, [see here](#branch-priorities)
| uniques | List | Default empty | List of effects, [see here](../Modders/Unique-parameter-types.md#general-uniques) |
| uniques | List | Default empty | List of effects, [see here](../Modders/Unique-parameters.md#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](../Modders/Unique-parameter-types.md#general-uniques) |
| uniques | List | Default empty | List of effects, [see here](../Modders/Unique-parameters.md#general-uniques) |
#### Branch priorities
The "priorities" object lists its branch's priorities for each victory type. The AI refers to this when deciding which branch to prioritize, also taking its preferred victory type into consideration. If two or more candidate branches have the same priority, the AI chooses a random branch among the candidates. All values are set to 0 if the object itself is missing or empty.
| Attribute | Type | Optional? | Notes |
|-----------|------|-----------|-------|
| Attribute | Type | Optional | Notes |
| --------- | ---- | -------- | ----- |
| Neutral | Int | Default 0 | Priority value when the AI's preferred victory type is Neutral |
| Cultural | Int | Default 0 | Priority value when the AI's preferred victory type is Cultural |
| Diplomatic | Int | Default 0 | Priority value when the AI's preferred victory type is Diplomatic |
@ -135,12 +130,13 @@ The "priorities" object lists its branch's priorities for each victory type. The
| Scientific | Int | Default 0 | Priority value when the AI's preferred victory type is Scientific |
## Quests.json
[Link to original](/jsons/Civ%20V%20-%20Vanilla/Quests.json)
[Link to original](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Gods%20%26%20Kings/Quests.json)
This file contains the Quests that may be given to major Civilizations by City States.
| Attribute | Type | Optional? | Notes |
|-----------|------|-----------|-------|
| 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 |
@ -148,21 +144,23 @@ This file contains the Quests that may be given to major Civilizations by City S
| 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](/jsons/Civ%20V%20-%20Gods%20&%20Kings/Religions.json)
[Link to original](https://github.com/yairm210/Unciv/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](/jsons/Civ%20V%20-%20Vanilla/Specialists.json)
[Link to original](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Gods%20%26%20Kings/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 |
| --------- | ---- | --------------- | ----- |
| Attribute | Type | Optional | 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 |
@ -173,29 +171,31 @@ Each specialist can have the following attributes:
| 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](/jsons/Civ%20V%20-%20Vanilla/Techs.json)
[Link to original](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Gods%20%26%20Kings/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 |
|-----------|------|-----------|-------|
| Attribute | Type | Optional | Notes |
| --------- | ---- | -------- | ----- |
| columnNumber | Integer | Required | Horizontal placement in the Tech Tree. |
| era | String | Required | References [Eras.json](Miscellaneous-JSON-files.mdrasjson). |
| era | String | Required | References [Eras.json](Miscellaneous-JSON-files.md#Eras.json). |
| 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 |
|-----------|------|-----------|-------|
| 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.mdeneral-uniques). |
| civilopediaText | List | Default empty | see [civilopediaText chapter](Miscellaneous-JSON-files.mdivilopedia-text). |
| uniques | List | Default empty | Properties granted by the tech - see [here](../Modders/uniques.md). |
| civilopediaText | List | Default empty | see [civilopediaText chapter](Miscellaneous-JSON-files.md#Civilopedia-text). |

240
docs/Other/Force-rating-calculation.md
View File

@ -1,137 +1,143 @@
# Force rating
# Force rating calculation
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
- 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.
- 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`
- `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`

5
docs/Other/Hosting_a_Multiplayer_server.md → docs/Other/Hosting-a-Multiplayer-server.md
View File

@ -1,4 +1,3 @@
# Hosting a Multiplayer server
Due to certain limitations on Dropbox's API, with the current influx of players, we've many times reached the point that Dropbox has become unavailable.
@ -11,6 +10,7 @@ From the directory where the Unciv.jar file is located, open a terminal and run
`java -cp Unciv.jar com.unciv.app.desktop.UncivServer`
Don't forget to use 'cd' to switch to the correct dictionary. Here's an example in Windows.
```
D:
cd Games
@ -20,7 +20,6 @@ java -cp Unciv.jar com.unciv.app.desktop.UncivServer
Your server has now started!
In Unciv itself, from the same computer, enter Options > Multiplayer.
Click the first text (Current IP address) to copy the IP to the clipboard.
@ -28,7 +27,6 @@ Then, click the second the second (Server IP address) to put your computer's IP
If you click "check connection to server" you should now get "Return result: true", which means it's working!
So far you ran the server and connected yourself to it, but now for the interesting part - connecting other people!
The IP should still be in your clipboard - if not, just click the 'copy to clipboard' button again.
@ -37,5 +35,4 @@ You can of course enter the IP manually if that's easier for you.
Click 'check connection' from the new device, and if you got the same result - congratulations, you're both connected to the same server and can start a multiplayer game on the server!
Please note that devices NOT connected to the same server will NOT be able to participate in multiplayer games together!

2
docs/Other/Installing-on-macOS.md
View File

@ -1,3 +1,5 @@
# Installing on macOS
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

81
docs/Other/Map-related-JSON-files.md
View File

@ -1,11 +1,13 @@
# Map-related JSON files
## Terrains.json
This file lists the base terrains, terrain features and natural wonders that can appear on the map.
Each terrain entry can have the following properties:
| Attribute | Type | Optional? | Notes |
|-----------|------|-----------|-------|
| 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 |
@ -23,31 +25,32 @@ Each terrain entry can have the following properties:
## 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 |
|-----------|------|-----------|-------|
| 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](../Modders/Unique-parameter-types.md#improvement-uniques) |
| uniques | List | Default empty | List of effects, [see here](../Modders/Unique-parameters.md#improvement-uniques) |
| shortcutKey | String | Default none | Keyboard binding. At the moment a single character (no function keys or Ctrl combinations) |
| civilopediaText | List | Default empty | see [civilopediaText chapter](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.
- 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.
@ -56,8 +59,8 @@ Note also that resources have two visual representations - icon and pixel graphi
Each resource can have the following properties:
| Attribute | Type | Optional? | Notes |
|-----------|------|-----------|-------|
| 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 |
@ -65,36 +68,37 @@ 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](../Modders/Unique-parameter-types.md#resource-uniques) - at the moment only one unique may be added |
| unique | String | Default empty | Effects, [see here](../Modders/Unique-parameters.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](/jsons/Civ%20V%20-%20Vanilla/Ruins.json)
[Link to original](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Vanilla/Ruins.json)
This file contains the possible rewards ancient ruins give. It is not required, if omitted, the default file for the game is used, even in baseRuleSet mods.
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 |
| --------- | ---- | --------------- | ----- |
| Attribute | Type | Optional | Notes |
| --------- | ---- | -------- | ----- |
| name | String | required | Name of the ruins. Never shown to the user, but they have to be distinct |
| notification | String | required | Notification added to the user when this reward is chosen. If omitted, an empty notification is shown. Some notifications may have parameters, refer to the table below. |
| weight | Integer (≥0) | defaults to 1 | Weight this reward should have. Higher weights result in a higher chance of it being chosen* |
| uniques | List of Strings | defaults to none | [uniques]Uniques#one-time-effect) or [uniques](../Modders/Unique-parameter-types.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. |
| uniques | List of Strings | defaults to none | [uniques]Uniques#one-time-effect) or [uniques](../Modders/Unique-parameters.md#one-time-effect-units) that will trigger when entering the ruins. If more than 1 unique is added, the notification will be shown multiple times due to a bug. |
| excludedDifficulties | List of Strings | defaults to None | A list of all difficulties on which this reward may _not_ be awarded |
The exact algorithm for choosing a reward is the following:
* The exact algorithm for choosing a reward is the following:
- Create a list of all possible rewards, with rewards with a higher weight appearing multiple times. A reward with weight one will appear once, a reward with weight two will appear twice, etc.
- Shuffle this list
- Try give rewards starting from the top of the list. If any of the uniques of the rewards is valid in this context, reward it and stop trying more rewards.
- Create a list of all possible rewards, 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 |
| 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 |
@ -106,46 +110,55 @@ Some of the rewards ruins can give will have results that are not deterministic
### 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"
- "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 |
|-----------|------|-----------|-------|
| 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"],
...
"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
- 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},
"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 😁.

111
docs/Other/Miscellaneous-JSON-files.md
View File

@ -1,13 +1,15 @@
# Miscellaneous JSON files
## Difficulties.json
[Link to original](/jsons/Civ%20V%20-%20Vanilla/Difficulties.json)
[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.
Each difficulty level can have the following attributes:
| Attribute | Type | Mandatory | Notes |
| --------- | ---- | ------- | ----- |
| Attribute | Type | Optional | Notes |
| --------- | ---- | -------- | ----- |
| name | String | Required | Name of the difficulty level |
| baseHappiness | Integer | Default 0 |
| extraHappinessPerLuxury | Float | Default 0 |
@ -17,7 +19,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](Unit-related-JSON-files.md#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.md#Units.json)] |
| aiCityGrowthModifier | Float | Default 1 |
| aiUnitCostModifier | Float | Default 1 |
| aiBuildingCostModifier | Float | Default 1 |
@ -32,19 +34,19 @@ Each difficulty level can have the following attributes:
| turnBarbariansCanEnterPlayerTiles | Integer | Default 0 |
| clearBarbarianCampReward | Integer | Default 25 |
## Eras.json
[Link to original](/jsons/Civ%20V%20-%20Vanilla/Eras.json)
[Link to original](https://github.com/yairm210/Unciv/tree/master/android/assets/jsons/Civ%20V%20-%20Gods%20&%20Kings/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 |
| --------- | ---- | --------------- | ----- |
| Attribute | Type | Optional | 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 |
| 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.md#unitsjson) |
@ -58,19 +60,22 @@ Each era can have the following attributes:
| 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
[Link to original](https://github.com/yairm210/Unciv/tree/master/android/assets/jsons/Civ%20V%20-%20Gods%20&%20Kings/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
- 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 |
|-----------|------|-----------|-------|
| Attribute | Type | Optional | Notes |
| --------- | ---- | -------- | ----- |
| isBaseRuleset | Boolean | false | Differentiates mods that change the vanilla ruleset or replace it |
| maxXPfromBarbarians | Integer | 30 | *Deprecated*, see [constants](#ModConstants) |
| uniques | List | empty | Mod-wide specials, [see here](../Modders/Unique-parameter-types.md#modoptions-uniques) |
| uniques | List | empty | Mod-wide specials, [see here](../Modders/uniques.md#modoptions-uniques) |
| techsToRemove | List | empty | List of [Technologies](Civilization-related-JSON-files.md#techsjson) to remove (isBaseRuleset=false only) |
| buildingsToRemove | List | empty | List of [Buildings or Wonders](Civilization-related-JSON-files.md#buildingsjson) to remove (isBaseRuleset=false only) |
| unitsToRemove | List | empty | List of [Units](Unit-related-JSON-files.md#unitsjson) to remove (isBaseRuleset=false only) |
@ -79,13 +84,14 @@ The file can have the following attributes, including the values Unciv sets (no
| 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 |
| constants | Object | empty | see [constants](#ModOptions.constants) |
| constants | Object | empty | see [ModConstants](#ModConstants) |
### ModConstants
Stored in ModOptions.constants, this is a collection of constants used internally in Unciv.
| Attribute | Type | Defaults | Notes |
|-----------|------|-----------|-------|
| Attribute | Type | Optional | Notes |
| --------- | ---- | -------- | ----- |
| maxXPfromBarbarians | Int | 30 | [^A] |
| cityStrengthBase| Float | 8.0 | [^B] |
| cityStrengthPerPop| Float | 0.4 | [^B] |
@ -104,46 +110,59 @@ Stored in ModOptions.constants, this is a collection of constants used internall
| minRiverLength| Int | 5 | [^I] |
| maxRiverLength| Int | 666 | [^I] |
[^A]: Max amount of experience that can be gained from combat with barbarians
[^B]: Formula for city Strength:
Strength = baseStrength + strengthPerPop + strengthFromTiles +
((%techs * multiplier) ^ exponent) * fullMultiplier +
(garrisonBonus * garrisonUnitStrength * garrisonUnitHealth/100) +
defensiveBuildingStrength
where %techs is the percentage of techs in the tech tree that are complete
If no techs exist in this ruleset, %techs = 0.5 (=50%)
[^C]: Formula for Unit Supply:
Supply = unitSupplyBase (difficulties.json)
unitSupplyPerCity * amountOfCities + (difficulties.json)
unitSupplyPerPopulation * amountOfPopulationInAllCities
unitSupplyBase and unitSupplyPerCity can be found in difficulties.json
unitSupplyBase, unitSupplyPerCity and unitSupplyPerPopulation can also be increased through uniques
[^D]: The minimal distance that must be between any two cities, not counting the tiles cities are on
The number is the amount of tiles between two cities, not counting the tiles the cities are on.
e.g. "C__C", where "C" is a tile with a city and "_" is a tile without a city, has a distance of 2.
First constant is for cities on the same landmass, the second is for cities on different continents.
[^E]: NaturalWonderGenerator uses these to determine the number of Natural Wonders to spawn for a given map size. The number scales linearly with map radius: #wonders = radius * naturalWonderCountMultiplier + naturalWonderCountAddedConstant. The defaults effectively mean Tiny - 1, Small - 2, Medium - 3, Large - 4, Huge - 5, Custom radius >=109 - all G&K wonders.
[^F]: MapGenerator.spreadAncientRuins: number of ruins = suitable tile count * this
[^H]: MapGenerator.spawnLakesAndCoasts: Water bodies up to this tile count become Lakes
[^I]: RiverGenerator: river frequency and length bounds
Legend:
- [^A]: Max amount of experience that can be gained from combat with barbarians
- [^B]: Formula for city Strength:
Strength = baseStrength + strengthPerPop + strengthFromTiles +
((%techs * multiplier) ^ exponent) * fullMultiplier +
(garrisonBonus * garrisonUnitStrength * garrisonUnitHealth/100) +
defensiveBuildingStrength
where %techs is the percentage of techs in the tech tree that are complete
If no techs exist in this ruleset, %techs = 0.5 (=50%)
- [^C]: Formula for Unit Supply:
Supply = unitSupplyBase (difficulties.json)
unitSupplyPerCity * amountOfCities + (difficulties.json)
unitSupplyPerPopulation * amountOfPopulationInAllCities
unitSupplyBase and unitSupplyPerCity can be found in difficulties.json
unitSupplyBase, unitSupplyPerCity and unitSupplyPerPopulation can also be increased through uniques
- [^D]: The minimal distance that must be between any two cities, not counting the tiles cities are on
The number is the amount of tiles between two cities, not counting the tiles the cities are on.
e.g. "C__C", where "C" is a tile with a city and "_" is a tile without a city, has a distance of 2.
First constant is for cities on the same landmass, the second is for cities on different continents.
- [^E]: NaturalWonderGenerator uses these to determine the number of Natural Wonders to spawn for a given map size. The number scales linearly with map radius: #wonders = radius * naturalWonderCountMultiplier + naturalWonderCountAddedConstant. The defaults effectively mean Tiny - 1, Small - 2, Medium - 3, Large - 4, Huge - 5, Custom radius >=109 - all G&K wonders.
- [^F]: MapGenerator.spreadAncientRuins: number of ruins = suitable tile count * this
- [^H]: MapGenerator.spawnLakesAndCoasts: Water bodies up to this tile count become Lakes
- [^I]: RiverGenerator: river frequency and length bounds
## 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"},
{ "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|
|---------|----|-----------|
| 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.|

13
docs/Other/Regions.md
View File

@ -1,19 +1,22 @@
# 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>
<summary>Example</summary>
<img src="https://user-images.githubusercontent.com/63475501/140308518-ad5a2f50-d5f1-4467-a296-3a67f6d0b007.png" alt="Region Example" />
</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]",
@ -22,4 +25,4 @@ The game will work without any extra json definitions, but if you want the regio
"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.
"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.

36
docs/Other/Translating.md
View File

@ -2,7 +2,7 @@
## Starting out
The translation files are at [/android/assets/jsons/translations](/jsons/translations)
The translation files are at [/android/assets/jsons/translations](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
@ -14,34 +14,26 @@ When you feel that you're ready to add your translation to the game, you'll need
## 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.
- 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!
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
@ -60,25 +52,26 @@ Do as much as you're comfortable with - it's a big game with a lot of named obje
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, to any inheritance or nesting level.
(Collections that can be parsed must be derived from List or AbstractCollection)
- Generates a 'key = value' line
- Scans knowledge from UniqueType and UniqueParameterType instances and generates 'key = value' lines for them
- 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, to any inheritance or nesting level.
(Collections that can be parsed must be derived from List or AbstractCollection)
- Generates a 'key = value' line
- Scans knowledge from UniqueType and UniqueParameterType instances and generates 'key = value' lines for them
This means that every text that ISN'T in the jsons or the UniqueType system 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)
@ -87,9 +80,10 @@ 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](../Modders/Unique-parameter-types.md) 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](../Modders/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".
## Rules for all sources
The [], {} and <> bracket types are used internally and cannot be part of a translatable text. Use () instead.

27
docs/Other/Unit-related-JSON-files.md
View File

@ -1,15 +1,17 @@
# Unit-related JSON files
## Units.json
[Link to original](/jsons/Civ%20V%20-%20Vanilla/Units.json)
[Link to original](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Gods%20%26%20Kings/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 |
| Attribute | Type | Optional | Notes |
| --------- | ---- | -------- | ----- |
| name | String | required | The name of the units (required) |
| unitType | String | required | The type of the unit. Must be in [UnitTypes.json](/jsons/Civ%20V%20-%20Gods%20&%20Kings/UnitTypes.json) |
| unitType | String | required | The type of the unit. Must be in [UnitTypes.json](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Gods%20%26%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 |
@ -24,14 +26,15 @@ Each unit can have the following attributes:
| uniqueTo | String | defaults to none | The nation that this unit is unique to. Must be in [Nations.json](Civilization-related-JSON-files.md#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](../Modders/Unique-parameter-types.md#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](../Modders/Unique-parameters.md#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](#../Modders/Images-and-Audio.md#sounds)
| civilopediaText | List | Default empty | see [civilopediaText chapter](Miscellaneous-JSON-files.md#civilopedia-text) |
## UnitPromotions.json
[Link to original](/jsons/Civ%20V%20-%20Vanilla/UnitPromotions.json)
[Link to original](https://github.com/yairm210/Unciv/blob/master/android/assets/jsons/Civ%20V%20-%20Gods%20%26%20Kings/UnitPromotions.json)
This file lists the available unit promotions.
@ -41,24 +44,24 @@ Remember, promotions can be "bought" with XP, but also granted by the unit type,
Each promotion can have the following properties:
| Attribute | Type | Optional? | Notes |
|-----------|------|-----------|-------|
| 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](../Modders/Unique-parameter-types.md#unit-uniques) |
| uniques | List | Default empty | List of effects, [see here](../Modders/Unique-parameters.md#unit-uniques) |
| civilopediaText | List | Default empty | see [civilopediaText chapter](Miscellaneous-JSON-files.md#civilopedia-text) |
## UnitTypes.json
[Link to original](/jsons/Civ%20V%20-%20Vanilla/UnitTypes.json)
[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 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 |
| Attribute | Type | Optional | 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](../Modders/Unique-parameter-types.md#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](../Modders/Unique-parameters.md#unit-uniques) |

2
docs/index.md
View File

@ -1,4 +1,4 @@
Welcome to the Unciv wiki!
# Welcome to the Unciv wiki!
If you're a developer, you'll probably want to start at the [Getting Started](Developers/Building-Locally.md) page!