bcb26b6d2a
* Treat remaining untyped Uniques in default rulesets, make unit test catch them * Change untyped filtering Uniques check to Validation by inclusion in GlobalUniques instead of UniqueType.AircraftMarker * Wiki for untyped filtering Uniques * Re-include the "Who knows" of Future Tech on the Tech picker
7.6 KiB
Mod file structure Overview
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
- Civilization-related JSON files
- Map-related JSON files
- Unit-related JSON files
- Miscellaneous JSON files
- Stats
- Sounds
- Civilopedia text
General Overview of JSON files
Resources: json.org, ISO standard
Almost all Unciv JSON files start with a "[" and end with a "]". In between these are different objects of the type you are describing, each of which is contained between a "{" and a "}". For example, a very simple units.json may look like:
[
{
"name": "Warrior",
"cost": 16
},
{
"name": "Spearman",
"cost": 24,
"promotions": ["Shock I", "Drill I"]
}
]
This file contains two unit objects, one for a warrior and one for a spearman. These objects have different attributes, in this case "name", "cost" and "promotions". All these attributes have a certain type, a String (text) for "name", an Integer for "cost" and a List of Strings for "promotions".
There are different types of attributes:
| type | notes |
|---|---|
| String | A word or sentence. Should be between double quotes (") |
| Integer | A number. Can be both positive or negative. Should not be between quotes |
| Boolean | A value that can either be 'true' or 'false'. Should not be between quotes |
| List of [type] | If multiple values could apply (such as with the promotions above), they should be put inside a list. Each element of the list should be written like a normal attribute, separated by commas, and enclosed between square braces. E.g.: ["Shock I", "Shock II"] or [1, 2, 3]. |
| Object | The most complicated type of attribute. An object is comprised of multiple attributes, each of which again has a type. These attributes have a key (the part before the ":") and a value (the part behind it). For an example, see below. |
Example of a Buildings.json adding a new "Cultural Library" building which gives +50% science and +50% culture:
[
{
"name": "Cultural Library"
"percentStatBonus" : {"science": 50, "culture": 50}
}
]
The keys in this example are "science" and "culture", and both have the value "50".
In some sense you can see from these types that JSON files themselves are actually a list of objects, each describing a single building, unit or something else.
Uniques
"Uniques" are a label used by Unciv for extensible and customizable effects. Nearly every "ruleset object" allows a set of them, as a List with the name "uniques".
Every Unique follows a general structure: Unique type defining name [placeholder] more name [another placeholder] <condition or trigger> <condition or trigger>...
The entire string, excluding all <>-delimited conditionals or triggers with their separating blanks, and excluding the placeholders but not their [] delimiters, are used to look up the Unique's implementation.
The content of the optional [placeholder]s are implementation-dependant, they are parameters modifying the effect, and described in Unique parameters.
All <condition or trigger>s are optional (but if they are used the spaces separating them are mandatory), and each in turn follows the Unique structure rules for the part between the <> angled brackets, including possible placeholders, but not nested conditionals.
Example: "uniques":["[+1 Gold] <with a garrison>"] on a building - does almost the same thing as the "gold":1 attribute does, except it only applies when the city has a garrison. In this example, [] and with a garrison are the keys Unciv uses to look up two Uniques, an effect (of type Stats) and a condition (of type ConditionalWhenGarrisoned).
All Unique "types" that have an implementation in Unciv are automatically documented in uniques. Note that file is entirely machine-generated from source code structures. Also kindly note the separate sections for conditionals and trigger conditions. Uniques that do not correspond to any of those entries (verbatim including upper/lower case!) are called "untyped", will have no direct effect, and may result in the "Ruleset Validator" showing warnings (see the Options Tab "Locate mod errors", it also runs when starting new games). A legitimate use of "untyped" Uniques is their use as markers that can be recognized elsewhere in filters (example: "Aircraft" in the vanilla rulesets used as Unit filter). To allow "Ruleset Validator" to warn about mistakes leading to untyped uniques, but still allow the "filtering Unique" use, those should be "declared" by including each in GlobalUniques, too.
Information on JSON files used in the game
Many parts of Unciv are moddable, and for each there is a separate 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.