diff --git a/docs/docs/config.md b/docs/docs/config.md new file mode 100644 index 0000000..137dfb6 --- /dev/null +++ b/docs/docs/config.md @@ -0,0 +1,91 @@ +# Config + +A mod can let players change values of its [GLD patches](gld-patching.md) without editing the mod. For example, the player can choose how much a new unit costs, or turn a feature off. + +## How it works + +Every patch file is a [Scriban](https://github.com/scriban/scriban/blob/master/doc/language.md) template. PolyMod renders the template before it reads the patch as JSON. In the template, the function `config` gets a config value: + +``` +{{ config "key" "default" }} +``` + +- `key` is the name of the value. +- `default` is the value to use when the player has not set one. + +PolyMod keeps the values in `mods.json` in the game folder, in an object with the id of your mod as its key. When a template asks for a key that is not there, PolyMod adds the key with the default value, so after the first start the player finds all your config values in `mods.json`: + +```json +{ + "first_mod": { + "warriorCost": "5", + "lancers": "true" + } +} +``` + +The player edits `mods.json` and restarts the game. The new values apply the next time that PolyMod loads the patch. + +> [!NOTE] +> `config` always gives the value as **text**. The text is inserted into the JSON as it is. So `"cost": {{ config "warriorCost" "5" }}` becomes `"cost": 5`, a number, and `"startingUnit": "{{ config "unit" "warrior" }}"` becomes a string because the template puts the quotes around it. + +PolyMod only renders a patch as a template if it contains `{{`. A patch without `{{` is read as plain JSON. + +## Example: a configurable value + +``` +{ + "unitData": { + "warrior": { + "cost": {{ config "warriorCost" "5" }} + } + } +} +``` + +## Example: turning content on and off + +Because `config` gives text, compare it with a text value in conditions. A plain `if config ...` is always true, because any non-empty text is true in Scriban. + +This patch adds the `dashbender` unit and makes it the starting unit of Ai-Mo, but only if the config value `dashbenders` is `true`: + +``` +{{ dashbenders = (config "dashbenders" "true") == "true" }} +{ + "unitData": { + {{ if dashbenders }} + "dashbender": { + "idx": -1, + "health": 100, + "defence": 10, + "movement": 1, + "range": 1, + "attack": 0, + "cost": 15, + "weapon": "magic", + "unitAbilities": ["dash", "convert", "stiff", "land"], + "movementTerrain": ["field", "forest", "mountain"] + }, + {{ end }} + "mindbender": {} + }, + "tribeData": { + "aimo": { + "startingUnit": "{{ if dashbenders }}dashbender{{ else }}mindbender{{ end }}" + } + } +} +``` + +The empty `"mindbender": {}` entry keeps the JSON valid when the `if` block is left out: it makes sure that a comma inside the block is always followed by another entry. In a real mod you would also add the unit to a tech. + +For all template features, such as variables, loops and functions, see the [Scriban language documentation](https://github.com/scriban/scriban/blob/master/doc/language.md). + +## Errors + +If the template has a syntax error, PolyMod writes `error during parse of gld patch template` and the details to the log, and sets the status of the mod to *Error*. The rendered text must also be valid JSON; see [Errors](gld-patching.md#errors). + +## Other settings files + +- `PolyMod.json` holds the settings of PolyMod itself. See [Debugging and dumping](debugging.md#polymodjson). +- PolyMod 2.0 also contains a config API for [PolyScripts](polyscripts.md#configuration), but it is not public yet. diff --git a/docs/docs/debugging.md b/docs/docs/debugging.md new file mode 100644 index 0000000..4a77af8 --- /dev/null +++ b/docs/docs/debugging.md @@ -0,0 +1,67 @@ +# Debugging and dumping + +## The PolyMod Hub + +The PolyMod Hub shows all mods with their version, authors, status and checksum, and the global checksum. Open it with the PolyMod button on the start screen, or with **Ctrl + Tab** anywhere in the game. + +The **Config** button of the hub opens the PolyMod settings: + +| Setting | Effect | +| --- | --- | +| Debug | Shows the BepInEx console window with the live log, adds the **Dump** button to the hub, and turns off the warning for saved games with a different mod set. | +| Show coordinates | Shows the coordinates of every tile in games and in the [tribe previews](tribe-previews.md#finding-coordinates). | + +## The log + +PolyMod, BepInEx and your [PolyScripts](polyscripts.md) write to the BepInEx log, `BepInEx/LogOutput.log` in the game folder. In debug mode, the console window shows the same log while the game runs. + +Search the log for the id of your mod. PolyMod writes a line for each file that it registers, for example `Registered patch from first_mod mod`, and an error with details for each problem. + +## PolyMod.json + +`PolyMod.json` in the game folder holds the PolyMod settings. PolyMod makes it with the default values on the first start. + +| Field | Type | Default | Description | +| --- | --- | --- | --- | +| `debug` | boolean | `false` | Debug mode, as above. | +| `showCoordinates` | boolean | `false` | Shows tile coordinates, as above. | +| `allowUnsafeIndexes` | boolean | `false` | Lets PolyMod accept a fixed `idx` for new GLD content, if it is larger than all vanilla values of that type. For testing only; see [Adding new content](gld-patching.md#adding-new-content). | +| `overrideDeviceId` | string | `""` | Not used by PolyMod at this time. | +| `disabledMods` | array of strings | `[]` | Ids of mods that PolyMod does not load. | + +```json +{"debug":true,"showCoordinates":false,"allowUnsafeIndexes":false,"overrideDeviceId":"","disabledMods":["first_mod"]} +``` + +Close the game before you edit the file. + +## Dumping game data + +In debug mode, the hub has a **Dump** button. It writes the data of the running game to the `DumpedData` folder in the game folder, and shows a popup with a button that opens the folder. + +| Path | Content | +| --- | --- | +| `Logic/GameLogicData.json` | The vanilla GLD of every GLD version from 1 to the current one. The file with the highest number is the current one. | +| `Logic/AvatarData.json` | The avatar data of every version. | +| `Localization/language_.json` | All terms of each language. Use one as the start for a [new language](localization.md#adding-a-new-language). | +| `Localization/localization_.csv` | All terms of each localization category, with one column per language. | +| `Sprites//.png` | Every sprite of every loaded atlas. | +| `Sprites//sprites_.json` | The pixels per unit and the pivot of each sprite, in the [sprites file format](sprites.md). | +| `Prefabs/prefabs.json` | Every vanilla unit, improvement and resource prefab, in the [prefab file format](prefabs.md). | +| `preview_.json` | The tiles of the preview map of each tribe, in the [preview format](tribe-previews.md). | + +> [!TIP] +> The dumped `GameLogicData` file is the best reference for vanilla values. Use it together with the [GLD reference](../gld/index.md), which explains the fields. + +The dump contains the *vanilla* GLD, without the patches of your mods. The sprite dump contains only the atlases that are loaded at the time, so dump while a game is open to get the in-game sprites. + +## Common problems + +| Problem | Likely cause | +| --- | --- | +| The mod is not in the hub. | `manifest.json` is missing, not at the root, or invalid; the id has uppercase letters or digits; or the mod is in `disabledMods`. The log says why. | +| The game data does not load after you add a patch. | The patch is not valid JSON, or it uses an unknown or uppercase id. | +| The mod has the status *Error*. | A PolyScript threw an exception, or a config template has an error. The log has the details. | +| A new unit has the wrong look. | It has no [unit prefab](prefabs.md#unit-prefabs), or the `skinnedKey` does not match. | +| A texture does not replace the vanilla sprite. | The file name does not match the sprite name. Compare it with the dumped sprite names, see [Textures](textures.md). | +| A saved game does not open. | The mod set changed since the game was saved. See [Checksums](manifest.md#checksums-and-saved-games). | diff --git a/docs/docs/getting-started.md b/docs/docs/getting-started.md new file mode 100644 index 0000000..5f6d0bc --- /dev/null +++ b/docs/docs/getting-started.md @@ -0,0 +1,123 @@ +# Your first mod + +This guide makes a small mod that changes the warrior and adds a new unit. It takes a few minutes and shows the files that most mods use. + +## 1. Install PolyMod + +Install PolyMod with the [PolyMod Launcher](https://polymod.dev/download/) and start the game once from the launcher. PolyMod then makes the `Mods` folder in the game folder. + +## 2. Make the mod folder + +Make a folder `Mods/first_mod` and add a `manifest.json`: + +```json +{ + "id": "first_mod", + "name": "My First Mod", + "version": "1.0.0", + "authors": [ + "YourName" + ] +} +``` + +The `id` can only contain lowercase letters and underscores. See [Manifest](manifest.md). + +## 3. Change a vanilla value + +Add a `patch.json` that gives the warrior 3 attack instead of 2: + +```json +{ + "unitData": { + "warrior": { + "attack": 30 + } + } +} +``` + +Unit attack, defence and health are stored as ten times the value that the game shows, so `30` is 3 attack. See [UnitData](../gld/unit-data.md). + +Start the game and train a warrior. Its attack is now 3. Open the PolyMod Hub with **Ctrl + Tab** to see that your mod has the status *Success*. + +## 4. Add a new unit + +Extend `patch.json` to add a new unit and let the Imperius tribe train it with the Riding tech: + +```json +{ + "unitData": { + "warrior": { + "attack": 30 + }, + "lancer": { + "idx": -1, + "health": 100, + "defence": 10, + "movement": 2, + "range": 1, + "attack": 25, + "cost": 4, + "weapon": "sword", + "unitAbilities": [ + "dash", + "fortify", + "land" + ], + "movementTerrain": [ + "field", + "forest", + "mountain" + ] + } + }, + "techData": { + "riding": { + "unitUnlocks": [ + "+lancer" + ] + } + } +} +``` + +- `"idx": -1` tells PolyMod that `lancer` is new content. PolyMod gives it a free index when the game starts. +- `"+lancer"` adds `lancer` to the existing `unitUnlocks` array of the Riding tech instead of replacing the whole array. See [Merge rules](gld-patching.md#merge-rules). +- All ids are lowercase. + +## 5. Give it a name + +The game shows a new unit by its localization key, `unit.names.lancer`. Add a `localization.json`: + +```json +{ + "unit_names_lancer": { + "English": "Lancer", + "German (Germany)": "Lanzenreiter" + } +} +``` + +Underscores in the key become dots. See [Localization](localization.md). + +## 6. Give it a look + +Without a prefab, a new unit uses a fallback look. To build a real look, add a unit prefab and textures. The easiest way is to start from a dumped vanilla prefab: + +1. Turn on debug mode in the hub config, open the hub again, and press **Dump**. See [Debugging and dumping](debugging.md). +2. In `DumpedData/Prefabs/prefabs.json`, copy the entry of a unit whose shape you like. +3. Save it as `unitPrefab_lancer.json` in your mod, and change `skinnedKey.unitType` to `lancer`. +4. Change the `defaultSpriteName` of the visual parts to your own names, and add `.png` files with those names. + +See [Prefabs](prefabs.md) and [Textures](textures.md). + +## 7. Share it + +Zip the *contents* of `Mods/first_mod` (so that `manifest.json` is at the root of the archive) and rename the archive to `first_mod.polymod`. Players put that file in their `Mods` folder. + +## Next steps + +- [GLD patching](gld-patching.md): all merge rules, new tribes, skins and PolyMod-only fields. +- [Game logic data reference](../gld/index.md): every GLD section and field. +- [PolyScripts](polyscripts.md): change game code with C#. diff --git a/docs/docs/gld-patching.md b/docs/docs/gld-patching.md new file mode 100644 index 0000000..4e9f0cf --- /dev/null +++ b/docs/docs/gld-patching.md @@ -0,0 +1,251 @@ +# GLD patching + +A GLD patch is a JSON file (`patch.json` or `patch_*.json`) that changes the [game logic data](../gld/index.md) (GLD): the stats of units, the tech tree, tribes, buildings and more. PolyMod merges every patch into the GLD before the game reads it. + +## The basics + +A patch is a small GLD that only contains the values that you want to change. It uses the same sections, ids and field names as the GLD. For example, this patch gives the warrior 100 attack: + +```json +{ + "unitData": { + "warrior": { + "attack": 1000 + } + } +} +``` + +All other values of the warrior, and all other units, stay as they are. + +To find the ids and the current values, dump the GLD: see [Debugging and dumping](debugging.md). The [GLD reference](../gld/index.md) explains each field. + +## Merge rules + +PolyMod merges a patch into the GLD with these rules: + +| In the patch | Result | +| --- | --- | +| An object | Merged recursively, field by field. Fields that the patch does not contain stay unchanged. | +| A number, string or boolean | Replaces the value in the GLD. If the field or entry does not exist, PolyMod adds it. | +| `null` | Sets the value in the GLD to `null`. The key stays. | +| An array of plain values | **Replaces** the whole array. | +| An array with `"+value"` items | Adds `value` to the end of the existing array. | +| An array with `"-value"` items | Removes every `value` from the existing array. | + +### Changing arrays + +Arrays such as `unitAbilities` or `techUnlocks` hold many values. To change only some of them, prefix strings with `+` or `-`: + +```json +{ + "unitData": { + "warrior": { + "unitAbilities": [ + "+fortify", + "-dash" + ] + } + }, + "techData": { + "riding": { + "unitUnlocks": [ + "+lancer" + ] + } + } +} +``` + +Rules for arrays: + +- If the patch array contains at least one `+` or `-` string, PolyMod applies them to the existing array. It ignores the other plain strings in that patch array, but it adds items that are not strings, such as objects. +- If the patch array contains no `+` or `-` string, it replaces the whole existing array. Use this to set an exact list, or `[]` to clear it. +- `skins` arrays are special: a plain string *adds* the skin. So `"skins": ["myskin"]` adds a skin to a tribe and does not remove the vanilla skins. Use `"-skinname"` to remove a skin. + +> [!NOTE] +> The `+`/`-` array syntax exists since PolyMod 1.2. Before 1.2, every array replaced the original array, as the old wiki describes. + +### Order of patches + +When several patches change the same value, the patch that PolyMod merges last wins. Patches merge in the [load order](mod-structure.md#load-order) of the mods. If your patch must come after the patch of another mod, add that mod as a dependency. + +## Ids + +GLD ids are the lowercase names of the content, such as `warrior`, `imperius` or `lumberhut`. **Always write ids in lowercase**, in keys and in values. The game looks up ids case-sensitively, and an unknown id makes the game fail while it reads the GLD. See [Ids](../gld/index.md#ids). + +## Adding new content + +To add new content, write an entry with a new id and set its `idx` to `-1`: + +```json +{ + "unitData": { + "lancer": { + "idx": -1, + "health": 100, + "defence": 10, + "movement": 2, + "range": 1, + "attack": 25, + "cost": 4, + "weapon": "sword", + "unitAbilities": [ + "dash", + "fortify", + "land" + ], + "movementTerrain": [ + "field", + "forest", + "mountain" + ] + } + } +} +``` + +PolyMod gives each new entry an automatic index (autoindex) when the game starts. Autoindexes start at 1000 and are shared by all kinds of content, so indexes of new content never collide with vanilla indexes or with each other. + +You can add new entries to every section that has an `idx`: `tribeData`, `techData`, `unitData`, `improvementData`, `terrainData`, `resourceData` and `taskData`, and to the [PolyMod-only sections](#new-abilities-and-weapons). + +> [!WARNING] +> Do not set `idx` to a fixed number. PolyMod only maps entries with `"idx": -1`. A fixed number collides with other mods, and the game cannot read an entry that PolyMod did not map. The `allowUnsafeIndexes` setting in `PolyMod.json` lets PolyMod accept a fixed `idx` that is larger than all vanilla values of that type, but it is meant for testing only. + +New content is not reachable on its own. Remember to connect it to the game: + +- a new **unit** must be in the `unitUnlocks` of a tech, or be the `startingUnit` of a tribe; +- a new **improvement** must be in the `improvementUnlocks` of a tech or a task; +- a new **tech** must be in the `techUnlocks` of another tech, or in the `startingTech` of a tribe; +- a new **resource** must list the terrains that it spawns on, and tribes must have a `resourceModifier` above 0 for it if it should spawn; +- new content needs [localization](localization.md#keys-for-game-content) and a [look](prefabs.md). + +### New tribes + +A new tribe is an entry in `tribeData` with `"idx": -1`. PolyMod also: + +- unlocks every custom tribe and skin for free, +- fills in the legacy `style` and `climate` values of the tribe, so do not set them, +- lets you change its preview map with the [`preview` field](tribe-previews.md). + +```json +{ + "tribeData": { + "testingtribe": { + "idx": -1, + "color": 15713321, + "language": "az,bar,bryn,dum,girt,hall,kar,khaz,kol,kruk,lok,rudh,ruf,und,vorn,zak", + "startingTech": [ + "basic", + "mining" + ], + "startingResource": [ + "metal" + ], + "startingUnit": "warrior", + "skins": [ + "testingskin" + ], + "priceTier": 0, + "category": 1, + "bonus": 0, + "preview": [ + { + "x": 0, + "y": 0, + "terrainType": "mountain", + "unitType": "swordsman", + "improvementType": "mine" + } + ] + } + } +} +``` + +The tribe needs a name and description in [localization](localization.md#keys-for-game-content) (`tribes_testingtribe` and `tribes_testingtribe_info`), and textures for its buildings, units and terrain. Without tribe-specific textures, the game uses the generic sprites. See [TribeData](../gld/tribe-data.md). + +### New skins + +When a tribe lists a skin id that does not exist in `skins`, PolyMod creates that skin. Skin ids can use any case in `skins`; PolyMod changes them to lowercase. + +```json +{ + "tribeData": { + "imperius": { + "skins": [ + "goldenimperius" + ] + } + }, + "skinData": { + "goldenimperius": { + "color": 16766720, + "language": "au,rum,gol,den" + } + } +} +``` + +The `skinData` entry is optional. It gives the skin its own color and city name syllables. See [SkinData](../gld/skin-data.md). + +If the tribe has the `flooded` tribe ability, PolyMod also creates a tile effect `_flood` for each new skin of that tribe, so that tiles flooded by that skin use the sprites `field_flooded_` and the matching shorelines. + +Give the skin a name with the localization keys `tribeskins_` and `tribeskins__description`. + +### New abilities and weapons + +PolyMod reads some GLD sections that the game itself does not have. They only create new enum values with a name, so that other GLD entries can refer to them, and [PolyScripts](polyscripts.md) can give them a behavior: + +| Section | Creates a new | Used in | +| --- | --- | --- | +| `unitAbility` | unit ability | `unitData.*.unitAbilities` | +| `improvementAbility` | improvement ability | `improvementData.*.improvementAbilities` | +| `tribeAbility` | tribe ability | `tribeData.*.tribeAbilities` | +| `playerAbility` | player ability | `techData.*.abilityUnlocks` | +| `weaponData` | weapon | `unitData.*.weapon` | + +```json +{ + "unitAbility": { + "berserk": { + "idx": -1 + } + }, + "unitData": { + "lancer": { + "unitAbilities": [ + "+berserk" + ] + } + } +} +``` + +A new ability has no effect in the game until a PolyScript checks for it, for example with `EnumCache.GetType("berserk")` and a Harmony patch. + +## PolyMod-only fields + +PolyMod reads some extra fields in GLD entries. The game ignores them. + +| Section | Field | Description | +| --- | --- | --- | +| `tribeData` | `preview` | Changes the tribe preview map. See [Tribe previews](tribe-previews.md). | +| `tribeData` | `skins` | Accepts new skin ids, see [New skins](#new-skins). | +| `unitData` | `weapon` | Accepts a weapon id such as `"sword"` in place of a number. | +| `unitData` | `embarksTo` | The id of the unit that this unit turns into when it embarks, in place of the default boat. | +| `improvementData` | `prefab` | `true` makes a [simple prefab](prefabs.md#simple-prefabs-from-the-gld). | +| `improvementData` | `attractsResource` | For an improvement with the `attract` ability: the id of the resource that it spawns. Default `game`. | +| `improvementData` | `attractsToTerrain` | For an improvement with the `attract` ability: the id of the terrain that the resource spawns on. Default `forest`. | +| `improvementData` | `infoOverride` | A localization key (underscores allowed, as in localization files) whose text replaces the info text of the improvement. | +| `resourceData` | `prefab` | `true` makes a [simple prefab](prefabs.md#simple-prefabs-from-the-gld). | + +The [GLD reference](../gld/index.md) explains each field on the page of its section. + +## Errors + +- **Invalid JSON.** PolyMod does not catch JSON syntax errors in patch files. An invalid patch can stop the game data from loading. Check every patch with a JSON validator before you test it. +- **Templates.** PolyMod does not support config templates at this time. A patch that contains `{{ }}` is not valid JSON. +- **Unknown ids.** A wrong or uppercase id makes the game fail while it reads the GLD. The log shows `Missing enum value for string `. + +See [Debugging and dumping](debugging.md) for how to read the log. diff --git a/docs/docs/introduction.md b/docs/docs/introduction.md index f6ecaa6..d1d95f4 100644 --- a/docs/docs/introduction.md +++ b/docs/docs/introduction.md @@ -1 +1,33 @@ -# Introduction \ No newline at end of file +# Introduction + +PolyMod is the mod loader for The Battle of Polytopia. It runs as a [BepInEx](https://github.com/BepInEx/BepInEx) plugin inside the game, finds the mods in the `Mods` folder, and loads their content: game logic changes, sprites, translations, prefabs and code. + +This documentation is for **PolyMod 2.0** (`2.0.0-pre`). It was written against Polytopia `2.18.0.16751`, the version that PolyMod 2.0 is built for, and against game logic data (GLD) version 28. + +> [!NOTE] +> These pages replace the old GitHub wiki, which described the PolyMod 1.x API. A lot of the formats changed in 2.0, for example the texture names, the prefab files and the GLD patch merge rules. If you are porting a 1.x mod, read [Porting a mod from PolyMod 1.x](porting.md). + +## What a mod can do + +| You want to… | Use | Page | +| --- | --- | --- | +| Describe your mod (id, version, authors, dependencies) | `manifest.json` | [Manifest](manifest.md) | +| Change units, tribes, techs, buildings and other game rules | `patch.json` | [GLD patching](gld-patching.md), [Game logic data](../gld/index.md) | +| Add names and descriptions for new content, or translate it | `localization.json` | [Localization](localization.md) | +| Add a completely new language | `language_.json` | [Localization](localization.md#adding-a-new-language) | +| Replace or add images | `.png` files | [Textures](textures.md) | +| Set the pivot, scale, outline or blur of images | `sprites.json` | [Sprites](sprites.md) | +| Build the look of a new unit, building or resource | prefab files | [Prefabs](prefabs.md) | +| Change the tribe preview map | `preview` in a tribe | [Tribe previews](tribe-previews.md) | +| Change game code | `.dll` PolyScripts | [PolyScripts](polyscripts.md) | + +## Where to start + +1. Read [Mod structure](mod-structure.md) to see how a mod is laid out and how PolyMod finds its files. +2. Follow [Your first mod](getting-started.md) to make a working mod in a few minutes. +3. Turn on debug mode and dump the game data, as [Debugging and dumping](debugging.md) explains. The dumped `GameLogicData` file shows every vanilla value that you can change. +4. Use the [Game logic data reference](../gld/index.md) to look up what each GLD field does. + +## Getting help + +The community on [Discord](https://discord.gg/eWPdhWtfVy) is happy to help with questions about modding. You can also look at the [PolyMod source code](https://github.com/PolyModdingTeam/PolyMod) and the generated [API reference](xref:PolyMod). diff --git a/docs/docs/localization.md b/docs/docs/localization.md new file mode 100644 index 0000000..4023aa2 --- /dev/null +++ b/docs/docs/localization.md @@ -0,0 +1,94 @@ +# Localization + +PolyMod supports two kinds of text files: + +- **Localization files** (`localization.json`, `localization_*.json`) add or change terms in the existing game languages. Use them for the names and descriptions of your content. +- **Language files** (`language.json`, `language_*.json`) add a new language to the game, or change many terms of one language. + +## Localization files + +A localization file is a JSON object. Each key is a term key. Each value is an object that maps a **language name** to the text in that language. + +```json +{ + "polymod": { + "English": "PolyMod", + "Elyrion": "πȱ∫ỹmȱΔ" + }, + "unit_names_lancer": { + "English": "Lancer", + "Russian": "Копейщик" + } +} +``` + +### Term keys + +The game uses dots in its term keys, for example `unit.names.warrior`. In a localization file, write the key with underscores: + +| You write | PolyMod uses | +| --- | --- | +| `_` (one underscore) | `.` | +| `__` (two underscores) | `_` | + +So `unit_names_lancer` becomes `unit.names.lancer`, and `unit_names_cloak__boat` becomes `unit.names.cloak_boat`. + +A key that starts with `tribeskins` gets the prefix `TribeSkins/`, which is where the game keeps skin names. For example, `tribeskins_myskin` becomes `TribeSkins/tribeskins.myskin`. + +If a term already exists, the new texts replace the old ones. So you can also change vanilla texts. + +### Languages + +The language names are the names that the game uses for its languages. At the time of writing these are: + +`English`, `Portuguese (Brazil)`, `Russian`, `Italian (Italy)`, `French (France)`, `Spanish (Mexico)`, `German (Germany)`, `Japanese`, `Korean`, `Hindi`, `Indonesian`, `Malay`, `Polish`, `Thai`, `Turkish`, `Vietnamese`, `Elyrion` + +The column headers of the dumped `localization_*.csv` files show the current list. See [Debugging and dumping](debugging.md). + +If a term has no text for a language, PolyMod uses the `English` text for that language. If there is no `English` text either, it uses the term key. + +### Keys for game content + +The game finds the text of GLD content from its id. For new content, add these keys (shown here with dots; write them with underscores in the file): + +| Content | Key | Example id `lancer` | +| --- | --- | --- | +| Tribe name | `tribes.` | `tribes_lancer` | +| Tribe description | `tribes..info` | `tribes_lancer_info` | +| Unit name | `unit.names.` | `unit_names_lancer` | +| Unit ability name | `unit.abilities.` | `unit_abilities_lancer` | +| Improvement name | `building.names.` | `building_names_lancer` | +| Tech name | `technology.names.` | `technology_names_lancer` | +| Resource name | `resource.names.` | `resource_names_lancer` | +| Terrain name | `terrain.` | `terrain_lancer` | +| Task title | `polyplayer.task..title` | `polyplayer_task_lancer_title` | +| Task description | `polyplayer.task..description` | `polyplayer_task_lancer_description` | +| Player ability name | `player.abilities.` | `player_abilities_lancer` | +| Skin name | `TribeSkins/tribeskins.` | `tribeskins_lancer` | +| Skin description | `TribeSkins/tribeskins..description` | `tribeskins_lancer_description` | + +To find the key of any other text, dump the localization and search the `language_en.json` file for the text. + +Some game code builds keys with the number of an enum value instead of its name. PolyMod changes a custom number (1000 or more) in a key to the id of the content, so your keys always use the id. + +To replace the info text of an improvement, use the PolyMod field [`infoOverride`](../gld/improvement-data.md#polymod-fields). + +## Adding a new language + +A language file adds a language or changes many terms of one language. The file name gives the **language code**: `language_xx.json` has the code `xx`. + +The file is a JSON object that maps term keys to texts. Here the keys use dots, exactly as the game does. The file must contain the key `language`, whose value is the name of the language in the language selection. + +```json +{ + "language": "Pirate English", + "unit.names.warrior": "Deckhand", + "unit.names.archer": "Musketeer" +} +``` + +- If no game language has that code, PolyMod adds a new language with that name and code. +- If a game language already has that code, PolyMod changes the terms of that language. +- Terms that are not in the file get no text from PolyMod in a new language. Start from a dumped `language_en.json` and translate it, so that every term has a text. + +Each language code can come from only one file. If two files use the same code, PolyMod writes an error to the log for the second one. diff --git a/docs/docs/manifest.md b/docs/docs/manifest.md new file mode 100644 index 0000000..db2c9e5 --- /dev/null +++ b/docs/docs/manifest.md @@ -0,0 +1,83 @@ +# Manifest + +The manifest is the `manifest.json` file at the root of a mod. It gives the metadata of the mod: its id, name, version, authors and dependencies. A mod without a valid manifest does not load. + +## Format + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `id` | string | yes | The unique id of the mod. It must match `^(?!polytopia$)[a-z_]+$`: only lowercase letters `a`–`z` and underscores, no digits, and not `polytopia`. | +| `name` | string | no | The name that the hub shows. If you leave it out, PolyMod uses the id. | +| `description` | string | no | A description that the hub shows under the mod. | +| `version` | string | yes | The version of the mod, with 2 to 4 numbers: `1.0`, `1.2.3` or `1.2.3.4`. Pre-release suffixes such as `1.0.0-beta` are not allowed. | +| `authors` | array of strings | yes | The authors of the mod. The array must not be empty. | +| `dependencies` | array of objects | no | The mods that this mod needs. See [Dependencies](#dependencies). | +| `client` | boolean | no, default `false` | Set to `true` for a mod that only changes how the game looks or sounds on this computer, for example a texture pack. PolyMod leaves client mods out of the [checksum](#checksums-and-saved-games). | + +Field names are case-sensitive: write them exactly as in the table. + +> [!WARNING] +> PolyMod does not catch errors while it reads `manifest.json`. A file that is not valid JSON, or a `version` that is not a valid version, can stop PolyMod from loading. Check your manifest with a JSON validator. Trailing commas are not allowed. + +## Dependencies + +Each item of `dependencies` is an object: + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `id` | string | yes | The id of the mod that this mod needs. | +| `min` | string | no | The lowest allowed version, inclusive. | +| `max` | string | no | The highest allowed version, inclusive. | +| `required` | boolean | no, default `true` | If `true`, the mod does not load when the dependency is missing or has a bad version. If `false`, PolyMod only writes a warning to the log. | + +A dependency also sets the [load order](mod-structure.md#load-order): your mod always loads after the mods that it depends on, also when the dependency is not required. + +> [!TIP] +> There is a special mod with the id `polytopia`. Its version is the version of the game, for example `2.18.0.16751`. Use it to limit your mod to the game versions that it works with. + +## Example + +```json +{ + "id": "docs_mod", + "name": "Docs Mod", + "description": "An example mod for the documentation.", + "version": "1.2.3", + "authors": [ + "DocMan", + "bro0x7" + ], + "dependencies": [ + { + "id": "polytopia", + "min": "2.18.0" + }, + { + "id": "another_cool_mod", + "required": false + } + ] +} +``` + +## Validation + +PolyMod skips a mod and writes an error to the log when: + +- the mod has no `manifest.json` at its root, +- the manifest has no `id`, no `version`, or no `authors` (or an empty `authors` array), +- the `id` does not match the pattern above, +- another mod with the same `id` was already registered. + +PolyMod also skips a mod whose id is in the `disabledMods` list of `PolyMod.json`. See [Debugging and dumping](debugging.md#polymodjson). + +## Checksums and saved games + +PolyMod computes a SHA-256 checksum for each loaded mod from its id, its version, and the name and contents of every file (except `manifest.json`). It combines the checksums of all loaded mods that are not `client` mods into one global checksum. + +The global checksum is saved with every new game. When you open a saved game that was made with a different set of mods, PolyMod shows a warning and does not open the game, because the game data would not match. In debug mode, PolyMod does not show this warning. + +The hub shows the first 12 characters of each checksum, so you can compare mod sets with other players. + +> [!NOTE] +> Modded multiplayer is not supported yet. diff --git a/docs/docs/mod-structure.md b/docs/docs/mod-structure.md new file mode 100644 index 0000000..6307246 --- /dev/null +++ b/docs/docs/mod-structure.md @@ -0,0 +1,84 @@ +# Mod structure + +A mod is a folder or an archive in the `Mods` folder of the game. The `Mods` folder is next to the `BepInEx` folder, in the game folder. PolyMod makes it the first time that it starts. + +``` +The Battle of Polytopia/ +├── BepInEx/ +├── Mods/ +│ ├── my_mod/ ← a mod as a folder +│ │ ├── manifest.json +│ │ ├── patch.json +│ │ └── ... +│ └── other_mod.polymod ← a mod as an archive +└── PolyMod.json ← PolyMod settings +``` + +## Mod types + +PolyMod accepts three kinds of mod container: + +| Container | Use it for | +| --- | --- | +| Folder | Development. You can edit the files and restart the game. | +| `.polymod` file | Distribution. It is a ZIP archive with a different extension. | +| `.zip` file | Also accepted. Prefer `.polymod`, so that players do not confuse the mod with a normal archive and unpack it. | + +> [!IMPORTANT] +> In an archive, `manifest.json` must be at the root of the archive, not in a subfolder. Zip the *contents* of your mod folder, not the folder itself. If PolyMod does not find `manifest.json` at the root, it writes `Mod manifest not found` to the log and skips the mod. + +## How PolyMod reads a mod + +PolyMod reads **all** files of a mod, in all subfolders. It then decides what to do with each file from its **file name** (not its folder), so you can put files in subfolders such as `sprites/` or `patches/` to keep your mod tidy. The only exception is `manifest.json`, which must be at the root. + +| File name | What PolyMod does | When | Page | +| --- | --- | --- | --- | +| `manifest.json` (root only) | Reads the mod metadata. | At game start | [Manifest](manifest.md) | +| `*.dll` | Loads the assembly and runs its `Load` methods. | At game start | [PolyScripts](polyscripts.md) | +| `sprites.json`, `sprites_*.json` | Reads sprite settings. | At game start | [Sprites](sprites.md) | +| `language.json`, `language_*.json` | Adds or changes a language. | At game start | [Localization](localization.md#adding-a-new-language) | +| `localization.json`, `localization_*.json` | Adds localization terms. | When the GLD loads | [Localization](localization.md) | +| `patch.json`, `patch_*.json` | Merges the patch into the GLD. | When the GLD loads | [GLD patching](gld-patching.md) | +| `prefabs.json`, `prefabs_*.json` | Reads unit, improvement and resource prefabs. | After the GLD merge | [Prefabs](prefabs.md) | +| `unitPrefab.json`, `unitPrefab_*.json` | Reads one unit prefab. | After the GLD merge | [Prefabs](prefabs.md) | +| `improvementPrefab.json`, `improvementPrefab_*.json` | Reads one improvement prefab. | After the GLD merge | [Prefabs](prefabs.md) | +| `resourcePrefab.json`, `resourcePrefab_*.json` | Reads one resource prefab. | After the GLD merge | [Prefabs](prefabs.md) | +| `*.png` | Loads a texture. | When the GLD loads | [Textures](textures.md) | +| `*.bundle` | Loads a Unity asset bundle. | When the GLD loads | [Asset bundles](#asset-bundles) | + +All other files are ignored, but they still count for the [mod checksum](manifest.md#checksums-and-saved-games). + +The name patterns are case-sensitive: `unitPrefab.json` works, `unitprefab.json` does not. The `_*` part can be any text, so you can split content into several files, for example `patch_units.json` and `patch_tribes.json`, or `localization_en.json`. + +> [!NOTE] +> Audio files are not loaded in PolyMod 2.0. The audio manager exists, but it is a stub, and `.wav` loading is turned off in the loader. + +## Load order + +PolyMod loads the mods in this sequence: + +1. It registers every mod in `Mods` and checks the manifests. It skips a mod with a missing or invalid manifest, a duplicate id, or an id in `disabledMods` of `PolyMod.json`. +2. It checks the [dependencies](manifest.md#dependencies). A mod with a missing required dependency gets the status *dependencies unsatisfied* and does not load. +3. It sorts the mods so that each mod comes after the mods that it depends on. If the dependencies make a cycle, PolyMod loads no mod content and shows a popup that only lets you exit the game. +4. In that order, it loads the `.dll`, `sprites` and `language` files of each mod. +5. When the game loads its game logic data, PolyMod goes through the mods again in the same order. It loads localization, merges patches and loads textures and asset bundles. Then it creates the enum values for new content, loads the prefab files, makes sprites and makes prefabs. + +Only the dependencies give a fixed order. If your patch must apply after the patch of another mod, add that mod as a dependency, with `"required": false` if your mod also works without it. + +Within one mod, files are processed in the order in which PolyMod reads them from the folder or archive. Do not rely on that order between two patch files that change the same value. + +## Mod status + +The PolyMod Hub (**Ctrl + Tab**, or the PolyMod button on the start screen) shows every mod with its status: + +| Status | Meaning | +| --- | --- | +| Success | The mod loaded. | +| Error | An error occurred while PolyMod loaded the mod, for example a PolyScript threw an exception or a patch template failed. PolyMod stops loading the files of that mod. | +| Dependencies unsatisfied | A required dependency is missing or has a version outside the allowed range. | + +The details of each error are in the BepInEx log, `BepInEx/LogOutput.log`. See [Debugging and dumping](debugging.md). + +## Asset bundles + +PolyMod loads every `.bundle` file as a Unity `AssetBundle` and keeps it in `Registry.assetBundles`, keyed by the file name without the extension. PolyMod itself does not use the assets in a bundle. Use them from a [PolyScript](polyscripts.md). diff --git a/docs/docs/polyscripts.md b/docs/docs/polyscripts.md new file mode 100644 index 0000000..e52ab82 --- /dev/null +++ b/docs/docs/polyscripts.md @@ -0,0 +1,148 @@ +# PolyScripts + +A PolyScript is a compiled .NET class library (a `.dll` file) in a mod. It lets a mod change the code of the game at runtime, which JSON files cannot do: new ability behavior, new UI, new rules. + +PolyScripts use [HarmonyX](https://github.com/BepInEx/HarmonyX) to patch methods of the game without changing the game files. The game runs on IL2CPP, so the game types come from the interop assemblies that BepInEx generates. + +> [!TIP] +> The official [PolyScript template](https://github.com/PolyModdingTeam/PolyScriptTemplate) gives you a ready project. + +## Entry point + +PolyMod loads every `.dll` file of a mod. In each assembly, it calls every **public static** method named `Load` that has one of these signatures, on every type: + +```cs +public static void Load(ManualLogSource logger) +public static void Load() +``` + +The `ManualLogSource` writes to the BepInEx log with the prefix `[PolyMod] []`. Use it to see what your script does. + +```cs +using BepInEx.Logging; +using HarmonyLib; + +namespace MyCoolMod; + +public static class MyCoolScript +{ + internal static ManualLogSource? Logger; + + public static void Load(ManualLogSource logger) + { + Logger = logger; + Harmony.CreateAndPatchAll(typeof(MyCoolScript)); + logger.LogMessage("PolyScript loaded!"); + } + + [HarmonyPostfix] + [HarmonyPatch(typeof(GameManager), nameof(GameManager.Update))] + private static void GameManager_Update() + { + // Your code here. + } +} +``` + +### When `Load` runs + +PolyMod calls `Load` very early: when BepInEx loads PolyMod, before the game shows its splash screen and before it reads the game logic data. At that time most game objects do not exist yet. Use `Load` to apply Harmony patches and to register [GLD extensions](#extending-the-gld), and do the real work in your patches. + +The mods load in [load order](mod-structure.md#load-order), so the scripts of your dependencies are already loaded. + +### Errors + +If a `Load` method throws an exception, PolyMod writes the message to the log and sets the status of the mod to *Error*. PolyMod then does not load the patches, localization, textures and prefabs of that mod. + +> [!WARNING] +> PolyMod calls *every* public method named `Load` with these signatures, in *every* `.dll` of the mod. Do not use the name `Load` for other public methods with these signatures, also not for instance methods: PolyMod would try to call them too. If your mod contains library `.dll` files, they are loaded the same way. + +## Building a PolyScript + +1. Make a .NET 6 class library project. You need the [.NET SDK](https://dotnet.microsoft.com/download) 6 or newer. +2. Add the package sources and the PolyMod package. The PolyMod package also brings the game and BepInEx references. + +```xml + + + net6.0 + enable + enable + + https://api.nuget.org/v3/index.json; + https://nuget.bepinex.dev/v3/index.json; + https://nuget.samboy.dev/v3/index.json; + https://polymod.dev/nuget/v3/index.json; + + + + + + + +``` + + Use the PolyMod version that your players have. A floating version such as `*` does not pick pre-release versions such as `2.0.0-pre`. + +3. Build the project: + + ```bash + dotnet build + ``` + +4. Copy the `.dll` from `bin/Debug/net6.0/` into your mod folder. It can be anywhere in the mod, but next to `manifest.json` is common. +5. Start the game and check the log for your message. + +Do not copy the PolyMod, BepInEx or game assemblies into your mod. They are already loaded. + +## Useful PolyMod API + +PolyScripts can use the public API of PolyMod. Some useful members: + +| Member | Use | +| --- | --- | +| `PolyMod.Registry.GetSprite(name, tribe, skin, level)` | Gets a mod sprite with the [texture name rules](textures.md#texture-names). | +| `PolyMod.Registry.GetSpriteByText(...)` | The same with tribe, skin and level as text. | +| `PolyMod.Loader.AddPatchDataType(section, enumType)` | Registers a new GLD section whose entries become values of an enum. | +| `PolyMod.Loader.AddTypeHandler(enumType, handler)` | Runs code for each GLD entry of a section. | +| `PolyMod.Managers.Visual.BuildSprite(bytes, pivot, pixelsPerUnit)` | Makes a sprite from PNG bytes. | +| `PolyMod.Managers.Visual.ShowSetWidth(popup, width)` | Shows a legacy popup with a custom width. | +| `PolyMod.Managers.Prefabs.unitInfos`, `improvementInfos`, `resourceInfos` | The prefab descriptions that PolyMod will make. | +| `PolyMod.Plugin.MODS_PATH`, `BASE_PATH`, `DUMPED_DATA_PATH` | Paths of the `Mods` folder, the game folder and the dump folder. | +| `PolyMod.Json.JsonMerger.Merge(original, patch)` | Merges JSON with the [GLD merge rules](gld-patching.md#merge-rules). | + +See the [API reference](xref:PolyMod) for all members. + +### Extending the GLD + +The game turns ids into enum values with `EnumCache`. PolyMod adds new values for GLD entries with `"idx": -1`. Your script can use the same system for its own content: + +```cs +public static void Load(ManualLogSource logger) +{ + // Entries of the GLD section "unitAbility" become UnitAbility.Type values. + // PolyMod registers this section already; this shows the API for your own sections. + Loader.AddPatchDataType("unitAbility", typeof(UnitAbility.Type)); + + // Runs for each entry of the section. The bool is true in the first pass, + // just after PolyMod created the enum value of a new entry, and false in the + // second pass, which runs for every entry. + Loader.AddTypeHandler(typeof(UnitAbility.Type), (entry, isNewEntry) => + { + logger.LogInfo($"Unit ability entry: {entry.Path}"); + }); +} +``` + +To check for a new ability in a Harmony patch, get its enum value by its id: + +```cs +UnitAbility.Type berserk = EnumCache.GetType("berserk"); +if (unitData.HasAbility(berserk)) { /* ... */ } +``` + +`AddTypeHandler` only works for a type that has a section registered with `AddPatchDataType` (or by PolyMod). Register both in `Load`, because PolyMod reads the GLD after all scripts are loaded. + +## Configuration + +PolyMod 2.0 does not support mod configuration at this time. Mods cannot read config files or values that players can change. PolyMod 2.0 also contains a class-based script API with a `PolyScript` base class. In the current build (`2.0.0-pre`) it is internal, so mods cannot use it yet. Until it is public, use static `Load` methods. diff --git a/docs/docs/porting.md b/docs/docs/porting.md new file mode 100644 index 0000000..e653f43 --- /dev/null +++ b/docs/docs/porting.md @@ -0,0 +1,32 @@ +# Porting a mod from PolyMod 1.x + +PolyMod 2.0 changes several file formats. Check this list when you update a mod that was made for PolyMod 1.x and the old wiki. + +| Area | PolyMod 1.x | PolyMod 2.0 | Page | +| --- | --- | --- | --- | +| Texture names | `name_style_level.png` with empty parts, for example `lumberhut__.png` | `name.png`, `name_tribe.png`, `name_skin.png`, `name_level_tribe.png`, … without empty parts, for example `lumberhut.png` | [Textures](textures.md) | +| Terrain, resource and improvement textures | Internal game sprite names | The GLD ids also work, for example `field.png` | [Textures](textures.md#base-names-of-terrain-resources-and-improvements) | +| `sprites.json` | `pixelsPerUnit`, `pivot` | Also `spriteOrigin`, `transformToOutline`, `gaussianBlurRadius` | [Sprites](sprites.md) | +| Prefabs | `.json` with `type`, `name` and `visualParts` (`gameObjectName`, `baseName`, `scale`) | `prefabs.json`, `unitPrefab.json`, `improvementPrefab.json`, `resourcePrefab.json` with `skinnedKey` and `visualParts` (`defaultSpriteName`, …) | [Prefabs](prefabs.md) | +| Reusing a vanilla unit look | `"prefab": "mindbender"` in `unitData` | Not supported. Copy the dumped vanilla prefab into a `unitPrefab` file. | [Prefabs](prefabs.md#unit-prefabs) | +| New improvement or resource look | Custom house or animal sprites by default | `"prefab": true` in the GLD entry, or a prefab file | [Prefabs](prefabs.md#simple-prefabs-from-the-gld) | +| Arrays in patches | Before 1.2: always replaced. Since 1.2: `+`/`-` items | `"+value"` adds, `"-value"` removes; plain arrays still replace; plain strings in `skins` add. The old wiki only describes the pre-1.2 rule. | [GLD patching](gld-patching.md#merge-rules) | +| `null` in patches | The old wiki says it removed the value | Sets the value to `null`; the key stays | [GLD patching](gld-patching.md#merge-rules) | +| Config templates | `{% if config "key" true %}` examples | Not supported at this time. Write fixed values in the patch. | — | +| Tribe preview coordinates | Shown in debug mode | Shown with the **Show coordinates** setting, or in the dumped `preview_.json` | [Tribe previews](tribe-previews.md#finding-coordinates) | +| Manifest | `id`, `name`, `version`, `authors`, `dependencies` | Also `description` and `client` | [Manifest](manifest.md) | +| Localization files | Only `localization.json` | Also `localization_*.json`, and `language_.json` for new languages | [Localization](localization.md) | +| PolyScripts | `public static void Load(ManualLogSource)` | The same, and `public static void Load()` also works | [PolyScripts](polyscripts.md) | +| Audio | — | Not supported yet | [Mod structure](mod-structure.md#how-polymod-reads-a-mod) | + +## GLD changes in the game + +The game itself also changed since the old wiki, which was written for Polytopia 2.13 and GLD version 22. Some examples: + +- `unitData.*.promotionLimit` no longer exists. The promotion limit is 3, or 2 with the Discipline player ability. +- `diplomacyData.embassyTechPriceMultiplier` no longer exists. +- `tribeData.*.style` and `climate` are no longer read by the game. PolyMod fills them for new tribes. +- `tribeData.*.startingStars` is new. +- There are new enum values, for example the tribe abilities, unit abilities, the `algaespawn` improvement and the `convert` task. + +The [GLD reference](../gld/index.md) lists the current fields and values. diff --git a/docs/docs/prefabs.md b/docs/docs/prefabs.md new file mode 100644 index 0000000..88cc9d1 --- /dev/null +++ b/docs/docs/prefabs.md @@ -0,0 +1,165 @@ +# Prefabs + +A prefab is the game object that the game shows for a unit, an improvement or a resource. It is made of **visual parts**: sprites with a position, a rotation and settings for tinting and skins. PolyMod can make new prefabs from JSON files, so that new content gets its own look. + +> [!NOTE] +> The prefab format changed completely in PolyMod 2.0. The old format with `type`, `name` and `visualParts` with `gameObjectName`/`baseName`, and the old `"prefab": ""` field in `unitData`, no longer exist. + +## Prefab files + +| File name | Content | +| --- | --- | +| `prefabs.json`, `prefabs_*.json` | Any number of prefabs: `{ "units": [...], "improvements": [...], "resources": [...] }` | +| `unitPrefab.json`, `unitPrefab_*.json` | One [unit prefab](#unit-prefabs). | +| `improvementPrefab.json`, `improvementPrefab_*.json` | One [improvement prefab](#improvement-prefabs). | +| `resourcePrefab.json`, `resourcePrefab_*.json` | One [resource prefab](#resource-prefabs). | + +PolyMod reads prefab files after it merges the GLD patches, so they can use the ids of new content. Field names in prefab files are not case-sensitive. + +> [!TIP] +> Dump the game data to get every vanilla prefab in this format in `DumpedData/Prefabs/prefabs.json`. Copy the prefab that is closest to what you want and change it. See [Debugging and dumping](debugging.md). + +## Visual parts + +Each prefab has a `visualParts` array. Each visual part is an object: + +| Field | Type | Default | Description | +| --- | --- | --- | --- | +| `defaultSpriteName` | string | — | The base name of the sprite of this part. The game looks up the sprite by this name with the tribe, skin and level, as [Textures](textures.md#texture-names) describes. It is also the name of the part's game object. | +| `coordinates` | `[x, y]` | `[0, 0]` | The position of the part, in world units. | +| `rotation` | number | `0` | The rotation around the z axis, in degrees. | +| `tintable` | boolean | `false` | If `true`, the game tints the sprite with the color of the owner. Use it for parts that show the tribe color. The game multiplies the sprite colors by the tribe color, so draw these parts in white: white becomes the exact tribe color, and gray becomes a darker shade of it. Use gray for shading. Other colors mix with the tribe color and do not tint completely. | +| `skinningLogic` | string | `"UseTribe"` | Which skin the sprite uses: `UseTribe`, `UseClimate`, `UseBirthClimate` or `DontChangeSkin`. | +| `improvementSkinningLogic` | string | `"FoundingTribe"` | Improvements only. Which skin the sprite uses: `TileOwner`, `TileClimate`, `FoundingTribe` or `DontChangeSkin`. | +| `levels` | boolean | `false` | Improvements only. If `true`, the sprite changes with the level of the improvement (`base_level` sprite names). | +| `sortingOrderOverride` | integer | calculated | Units only. The sorting order of the part. | +| `outlineSortingOrderOverride` | integer | calculated | Units only. The sorting order of the outline of the part. | + +Each part also gets an outline object, named `defaultSpriteName` plus `_Outline`, which shows the [outline sprite](textures.md#outlines). + +**Drawing order.** For improvements and resources, the first part in the array is drawn at the back and each next part in front of it. For units, it is the other way around: the *last* part is drawn at the back and the first part is drawn in front. The outlines are drawn behind all parts. Use the sorting order overrides to change the order of unit parts. + +## Unit prefabs + +| Field | Type | Description | +| --- | --- | --- | +| `skinnedKey` | object | The unit, tribe and skin that this prefab is for: `{ "unitType": "...", "tribeType": "...", "skinType": "..." }`. Use the ids, for example `"tribeType": "none"` for all tribes and `"skinType": "default"` for the default skin. | +| `headPositionMarker` | string | The `defaultSpriteName` of the part that marks the head of the unit. If no part has this name, PolyMod uses the first part. | +| `uiOverride` | boolean | If `true`, this prefab is only used in the UI, in place of the normal prefab of the same key. Default `false`. | +| `visualParts` | array | The [visual parts](#visual-parts). | + +```json +{ + "skinnedKey": { + "unitType": "lancer", + "tribeType": "none", + "skinType": "default" + }, + "headPositionMarker": "lancer_head", + "visualParts": [ + { + "defaultSpriteName": "lancer_head", + "coordinates": [ + 0, + 0.35 + ] + }, + { + "defaultSpriteName": "lancer_body", + "coordinates": [ + 0, + 0.15 + ], + "tintable": true + }, + { + "defaultSpriteName": "lancer_legs", + "coordinates": [ + 0, + 0 + ] + } + ] +} +``` + +### How the game finds a unit prefab + +For a unit of type *U*, tribe *T* and skin *S*, PolyMod looks for a prefab in this sequence and uses the first one that exists: + +1. During the Christmas season, the Christmas prefab of *U*, if the game has one. +2. The prefab for *U*, *T*, *S*. +3. The prefab for *U* with tribe `none` and skin *S*. +4. The prefab for *U*, *T* with the default skin. +5. The prefab for *U* with tribe `none` and the default skin. +6. As a last resort, the prefab of unit type `none` with tribe `none` and the default skin. PolyMod writes `Couldn't find prefab for type` to the log. + +So one prefab with tribe `none` and the default skin covers all tribes and skins. Add more specific prefabs only where the look must differ. + +You can also add a prefab for a vanilla unit, tribe and skin to replace the vanilla look. + +## Improvement prefabs + +| Field | Type | Description | +| --- | --- | --- | +| `improvementType` | string | The id of the improvement. Required: PolyMod skips a prefab without it. | +| `needsOutlines` | boolean | If `true`, the outline objects get a renderer and show the outline sprites. Default `false`. | +| `visualParts` | array | The [visual parts](#visual-parts). | + +```json +{ + "improvementType": "mytemple", + "visualParts": [ + { + "defaultSpriteName": "mytemple", + "levels": true + } + ] +} +``` + +An improvement prefab replaces the prefab of that improvement for all tribes and skins. The sprites of the parts still change with the tribe and skin, through the [sprite names](textures.md#texture-names). + +## Resource prefabs + +| Field | Type | Description | +| --- | --- | --- | +| `resourceType` | string | The id of the resource. Required: PolyMod skips a prefab without it. | +| `visualParts` | array | The [visual parts](#visual-parts). | + +```json +{ + "resourceType": "gems", + "visualParts": [ + { + "defaultSpriteName": "gems" + } + ] +} +``` + +## Simple prefabs from the GLD + +For an improvement or a resource with only one sprite, you do not need a prefab file. Set the PolyMod field `"prefab": true` in its GLD entry: + +```json +{ + "improvementData": { + "mytemple": { + "idx": -1, + "prefab": true, + "maxLevel": 5 + } + }, + "resourceData": { + "gems": { + "idx": -1, + "prefab": true + } + } +} +``` + +PolyMod then makes a prefab with one visual part whose `defaultSpriteName` is the id (`mytemple`, `gems`). For an improvement with `maxLevel` above 0, the part has `levels` set, so it uses the level sprites `mytemple_` (for example `mytemple_1`, `mytemple_2`). Add textures with these names. + +Do not use `"prefab": true` and a prefab file for the same type. PolyMod makes the simple prefabs after the prefabs from files, so the simple prefab replaces the one from the file. diff --git a/docs/docs/sprites.md b/docs/docs/sprites.md new file mode 100644 index 0000000..a931782 --- /dev/null +++ b/docs/docs/sprites.md @@ -0,0 +1,100 @@ +# Sprites + +A sprites file (`sprites.json` or `sprites_*.json`) gives settings for how PolyMod makes sprites. With it you can: + +- change the pivot and the pixels per unit of a sprite, +- make several sprites from one texture, +- make a sprite from a vanilla game sprite, +- turn a sprite into an outline, or blur it. + +A texture that has no entry in a sprites file still becomes a sprite, with the [default settings](textures.md#how-the-sprite-is-made). + +## Format + +The file is a JSON object. Each key is a **sprite name** (PolyMod changes it to lowercase). Each value is an object with these fields: + +| Field | Type | Default | Description | +| --- | --- | --- | --- | +| `pixelsPerUnit` | number | `2112` for a texture; the original value for a game sprite | How many texture pixels make one unit in the game world. A larger value makes the sprite smaller. | +| `pivot` | `[x, y]` | The [preset pivot](textures.md#how-the-sprite-is-made) for a texture; the original pivot for a game sprite | The point that the sprite is positioned, rotated and scaled around, as a fraction of the sprite size. `[0, 0]` is the bottom-left corner and `[1, 1]` is the top-right corner. Values outside 0–1 are allowed. | +| `spriteOrigin` | object | none | Where the image comes from. See [Sprite origin](#sprite-origin). Without it, PolyMod uses the texture with the same name as the sprite. | +| `transformToOutline` | boolean | `false` | Changes the image into a white silhouette with an 8 pixel border. See [Making outlines](#making-outlines). | +| `gaussianBlurRadius` | number | none | Blurs the image with this radius, in pixels. | + +Field names are case-sensitive. + +> [!TIP] +> Unity documents pixels per unit and pivots in its [Sprite documentation](https://docs.unity3d.com/Manual/sprite/sprite-editor/use-editor.html). + +### Sprite origin + +| Field | Type | Default | Description | +| --- | --- | --- | --- | +| `name` | string | — | The name of the source image. | +| `originType` | `"Outer"` or `"Inner"` | `"Outer"` | `Outer`: the source is a texture of a mod, by its [texture name](textures.md#texture-names). `Inner`: the source is a sprite of the game, by its sprite name. | + +PolyMod makes `Outer` sprites when the game data loads, and `Inner` sprites when the start screen opens, because the game sprites are not loaded before that. + +If the source texture or game sprite does not exist, PolyMod skips the entry. For a missing `Inner` sprite, it writes a warning to the log. + +## Examples + +Change the pivot and size of a texture: + +```json +{ + "lumberhut": { + "pixelsPerUnit": 1056, + "pivot": [ + 0.5, + 0.1 + ] + } +} +``` + +Use one texture for two sprites with different pivots. The texture `lancer.png` also stays available as the sprite `lancer`: + +```json +{ + "lancer_head": { + "spriteOrigin": { + "name": "lancer" + }, + "pivot": [ + 0.5, + 0.2 + ] + } +} +``` + +Reuse a vanilla sprite under a new name, for example for a new improvement: + +```json +{ + "mytemple": { + "spriteOrigin": { + "name": "temple", + "originType": "Inner" + } + } +} +``` + +### Making outlines + +Units have an outline sprite next to each body sprite, named like the sprite plus `_outline`. Instead of drawing it, let PolyMod make it from the same texture: + +```json +{ + "lancer_body_outline": { + "spriteOrigin": { + "name": "lancer_body" + }, + "transformToOutline": true + } +} +``` + +The outline is larger than the source by 8 pixels on each side. Set its `pivot` if it must line up with a sprite that does not use the center pivot. diff --git a/docs/docs/textures.md b/docs/docs/textures.md new file mode 100644 index 0000000..69618f2 --- /dev/null +++ b/docs/docs/textures.md @@ -0,0 +1,62 @@ +# Textures + +A texture is a `.png` file in a mod. PolyMod loads each texture and makes a sprite from it. The game then uses the sprite in place of the vanilla sprite with the same name, or a prefab uses it as a visual part. + +## Texture names + +The sprite name is the file name without `.png`, in lowercase. The folder does not matter: `sprites/units/Lancer.png` gives the sprite name `lancer`. + +> [!WARNING] +> Two textures with the same file name overwrite each other, also when they are in different folders or different mods. The texture that PolyMod loads last wins. + +When the game looks for a sprite, it gives a **base name**, and optionally a tribe, a skin and a level. PolyMod tries these sprite names, from the least to the most specific, and uses the most specific one that exists: + +| Sprite name | Used for | +| --- | --- | +| `base` | all tribes and skins | +| `base_tribe` | one tribe, all its skins | +| `base_skin` | one skin | +| `base_tribe_skin` | one skin of one tribe | + +For sprites that have levels, the level comes directly after the base name: `base_level`, `base_level_tribe`, `base_level_skin`, `base_level_tribe_skin`. + +`tribe` and `skin` are the [ids](../gld/index.md#ids) of the tribe and skin, for example `imperius` or `baerion`. The default skin has no skin part. + +These are the same rules that the game uses for its own sprite names, so the names of the dumped vanilla sprites show the base names that you can use. + +### Base names of terrain, resources and improvements + +For terrain, resources and improvements, PolyMod also accepts the [id](../gld/index.md#ids) of the type as the base name, in place of the internal sprite name of the game. For example, `field.png` replaces the field tile for all tribes, `forest_imperius.png` replaces the Imperius forest, and `lumberhut.png` replaces the lumber hut. A flooded field has the base name `field_flooded`. + +New terrains, resources and improvements always use their id as the base name. + +### Outlines + +Units and some other objects have an outline sprite. Its name is the sprite name followed by `_outline`, for example `lancer_body_outline` for the sprite `lancer_body`. To make an outline from an existing texture, use [`transformToOutline`](sprites.md#making-outlines) in `sprites.json`. + +## Examples + +| File | Effect | +| --- | --- | +| `lumberhut.png` | Replaces the lumber hut of all tribes and skins. | +| `lumberhut_cymanti.png` | Replaces the lumber hut only for Cymanti. | +| `city_3.png` | Replaces the level 3 city for all tribes. | +| `city_3_bardur_baerion.png` | Replaces the level 3 city of Bardur with the Baerion skin. | +| `mightyleader_imperius.png` | Replaces the image at the top of the Mighty Leader popup for Imperius. | + +## How the sprite is made + +PolyMod makes the sprite with these default settings: + +| Setting | Default | +| --- | --- | +| Pixels per unit | `2112` | +| Pivot | `[0.5, 0]` for names that start with `field`, `[0.5, -0.375]` for names that start with `mountain`, and `[0.5, 0.5]` for all other names | + +Use a [`sprites.json` file](sprites.md) to change these settings for a sprite. + +PolyMod also fixes common problems of exported images: if an image looks like it has premultiplied alpha, PolyMod changes it back to straight alpha, and it fills the color of fully transparent edge pixels so that no dark seams show when the game scales the sprite. + +## Getting the vanilla sprites + +Dump the game data to get every loaded sprite as a `.png`, together with its pixels per unit and pivot in `sprites_.json`. See [Debugging and dumping](debugging.md). Use these files as templates: an image with the same size and pivot as the vanilla sprite fits in the same place. diff --git a/docs/docs/toc.yml b/docs/docs/toc.yml index 4333c5b..5267c2b 100644 --- a/docs/docs/toc.yml +++ b/docs/docs/toc.yml @@ -1,2 +1,28 @@ -- name: Introduction - href: introduction.md \ No newline at end of file +- name: Introduction + href: introduction.md +- name: Your first mod + href: getting-started.md +- name: Mod structure + href: mod-structure.md +- name: Manifest + href: manifest.md +- name: Content + items: + - name: GLD patching + href: gld-patching.md + - name: Localization + href: localization.md + - name: Textures + href: textures.md + - name: Sprites + href: sprites.md + - name: Prefabs + href: prefabs.md + - name: Tribe previews + href: tribe-previews.md +- name: PolyScripts + href: polyscripts.md +- name: Debugging and dumping + href: debugging.md +- name: Porting from PolyMod 1.x + href: porting.md diff --git a/docs/docs/tribe-previews.md b/docs/docs/tribe-previews.md new file mode 100644 index 0000000..9c493ec --- /dev/null +++ b/docs/docs/tribe-previews.md @@ -0,0 +1,54 @@ +# Tribe previews + +The tribe selection screen shows a small preview map for each tribe. PolyMod lets a mod change the tiles of that map with the PolyMod-only field `preview` in a [tribe entry](../gld/tribe-data.md). + +```json +{ + "tribeData": { + "testingtribe": { + "preview": [ + { + "x": 0, + "y": 0, + "terrainType": "mountain", + "unitType": "swordsman", + "improvementType": "mine" + }, + { + "x": 1, + "y": 0, + "resourceType": "none" + } + ] + } + } +} +``` + +## Preview tile fields + +`preview` is an array of tile changes. Each tile change has these fields (field names are case-sensitive): + +| Field | Type | Description | +| --- | --- | --- | +| `x` | integer | The x coordinate of the tile. Required. | +| `y` | integer | The y coordinate of the tile. Required. | +| `terrainType` | terrain id | The new terrain of the tile. Leave it out to keep the terrain. | +| `resourceType` | resource id | The new resource of the tile. Leave it out to keep the resource, or use `"none"` to remove it. | +| `unitType` | unit id | The new unit on the tile, owned by the tribe. Leave it out to keep the unit, or use `"none"` to remove it. | +| `improvementType` | improvement id | The new improvement on the tile, at level 0. Leave it out to keep the improvement, or use `"none"` to remove it. | +| `tileEffects` | array of tile effect ids | The new [tile effects](../gld/effects.md#tile-effects), for example `["flooded"]`. If the array is not empty, it replaces all effects of the tile. Leave it out to keep the effects. | + +PolyMod skips a tile change without `x` and `y`, or with coordinates outside the map. + +## Which map is changed + +- For a vanilla tribe, PolyMod changes a copy of that tribe's own preview map. +- For a new tribe, which has no preview map, PolyMod starts from the game's fallback preview map and adds the changed copy as the preview of the tribe. + +## Finding coordinates + +There are two ways to find the coordinates of the preview tiles: + +- Turn on **Show coordinates** in the PolyMod Hub config (or set `showCoordinates` in `PolyMod.json`). The tribe selection screen then shows a zoomed-out preview, and every tile shows its coordinates. +- Dump the game data. PolyMod writes `DumpedData/preview_.json` for each vanilla tribe with the terrain, resource, unit, improvement and effects of every tile, in the same format as `preview`. See [Debugging and dumping](debugging.md). diff --git a/docs/gld/diplomacy-data.md b/docs/gld/diplomacy-data.md new file mode 100644 index 0000000..af4c5bd --- /dev/null +++ b/docs/gld/diplomacy-data.md @@ -0,0 +1,28 @@ +# DiplomacyData + +`diplomacyData` holds the values of embassies. Unlike the other sections, it is one object, not a list of entries, and it is the same for all tribes. + +```json +"diplomacyData": { + "embassyCost": 5, + "embassyIncome": 2, + "embasyGrowthTime": 3, + "embassyMaxLevel": 3, + "embassyTechPriceMultiplier": 0.5, + "embassyUpgradeCost": 20, + "dividendIncome": 2 +} +``` + +## Fields + +| Field | Type | Description | +| --- | --- | --- | +| `embassyCost` | integer | The star cost of an embassy, but only in games made with game version 113 or older. In newer games the cost is `4 + 2 × (players that already have an embassy with this player)`, and this field is ignored. | +| `embassyIncome` | integer | The star income of an embassy: `embassyIncome × embassy level`, doubled when the two players are at peace. It is paid to the capital. | +| `embasyGrowthTime` | integer | Not read by the game; left over from the development of diplomacy. (The spelling with one *s* is the real field name.) | +| `embassyMaxLevel` | integer | Not read by the game; left over from the development of diplomacy. | +| `embassyUpgradeCost` | integer | Not read by the game; left over from the development of diplomacy. | +| `dividendIncome` | integer | Not read by the game. (The `dividend` [player ability](tech-data.md#player-abilities) has no effect either.) | + +The field `embassyTechPriceMultiplier`, which older GLD versions had, no longer exists. diff --git a/docs/gld/effects.md b/docs/gld/effects.md new file mode 100644 index 0000000..49c1caa --- /dev/null +++ b/docs/gld/effects.md @@ -0,0 +1,34 @@ +# Effects + +Effects are states of tiles and units. They are not GLD sections, but GLD fields and abilities refer to them. + +## Tile effects + +Tile effects are used in the [`creates`](improvement-data.md#creates) field of improvements and in the [`tileEffects`](../docs/tribe-previews.md#preview-tile-fields) of tribe previews. + +| Id | Number | Created by | Effect | +| --- | --- | --- | --- | +| `none` | 0 | — | No effect. | +| `flooded` | 1 | The `flood` improvement ability, the `autoflood` and `drench` unit abilities, the `flooded` tribe ability, `creates`. | The tile counts as wetland: it changes movement, matches `wetland` and `mangrove` requirements, allows `fill` improvements and gives amphibious units a bubble. Removed by `fill` improvements and by some captures. | +| `swamped` | 2 | Added with `flooded` by players with the `swamp` skin. | Only visual. | +| `tentacle` | 3 | Units with the `tentacles` ability, on the tiles around them. | An enemy that enters the tile is attacked. | +| `algae` | 4 | The `algae` and `algaespawn` improvements, the `algae` unit ability, exploding units. | The tile counts as wetland; land units must stop there. Removed by `fill` improvements. | +| `foam` | 5 | Added with `algae` by players with the `cute` skin. | Only visual. | + +PolyMod adds a flood effect `_flood` for each new skin of a tribe with the `flooded` ability. See [New skins](../docs/gld-patching.md#new-skins). + +## Unit effects + +Unit effects come from unit abilities and actions. No GLD field sets them directly, but they explain several [unit abilities](unit-data.md#unit-abilities). + +| Id | Number | Effect | +| --- | --- | --- | +| `frozen` | 0 | The unit cannot move or attack and does not strike back. Removed at the end of its owner's turn. | +| `poisoned` | 1 | −1 movement (at least 1) and half the defence bonus. Healing cures the poison instead of giving health. Spores spawn where a poisoned unit dies. | +| `boosted` | 2 | Old version of the boost (only in old saved games): +0.5 attack and +1 movement. | +| `invisible` | 3 | Enemies cannot see the unit, and it ignores zones of control. Removed when the unit attacks, captures, builds or examines ruins. | +| `bubble` | 4 | +1 movement. Removed when the unit is hit, or when an amphibious unit moves onto dry land. | +| `petrified` | 5 | The look of `frozen` for the `magma` skin. | +| `swift` | 6 | +1 movement, from `boost` and `swarm`. Removed when the unit is hit. | +| `doubleready` | 7 | The unit can attack a second time this turn (`doubleattack`). | +| `charmed` | 8 | The look of `poisoned` for the `cute` skin. | diff --git a/docs/gld/improvement-data.md b/docs/gld/improvement-data.md new file mode 100644 index 0000000..372fbd6 --- /dev/null +++ b/docs/gld/improvement-data.md @@ -0,0 +1,327 @@ +# ImprovementData + +`improvementData` lists everything that can be built or done on a tile: buildings such as the farm or the temple, and tile actions such as clearing a forest or fishing. In the game code, improvements are also called buildings. + +The example uses the windmill (values from game logic data version 28): + +```json +"windmill": { + "cost": 5, + "adjacencyImprovements": [ + { + "improvement": "farm" + }, + { + "improvement": "aquafarm" + } + ], + "adjacencyRequirements": [ + { + "improvement": "farm" + }, + { + "improvement": "aquafarm" + } + ], + "improvementAbilities": [ + "limited" + ], + "maxLevel": 8, + "terrainRequirements": [ + { + "terrain": "field" + } + ], + "idx": 6, + "growthRewards": [ + { + "score": 0, + "population": 1 + } + ] +} +``` + +## Fields + +| Field | Type | Default | Description | +| --- | --- | --- | --- | +| [`idx`](#idx) | integer | — | The number of the improvement. `-1` for a new improvement. | +| [`hidden`](#hidden) | boolean | `false` | Players cannot build it. | +| [`cost`](#cost) | integer | `0` | The star cost to build it. | +| [`work`](#work) | integer | `0` | Star income per turn per level. | +| [`borderSize`](#bordersize) | integer | `0` | The border size of the improvement state. | +| [`maxLevel`](#maxlevel) | integer | `0` | The highest level. `0` means no cap. | +| [`improvementAbilities`](#improvement-abilities) | improvement ability id list | `[]` | Special rules. | +| [`creates`](#creates) | array of objects | `[]` | Terrain, resources, units or effects that building it creates. | +| [`rewards`](#rewards) | array of objects | `[]` | Population, stars and score for building it. | +| [`terrainRequirements`](#terrainrequirements) | array of objects | `[]` | The terrain and resource that the tile needs. | +| [`adjacencyRequirements`](#adjacencyrequirements) | array of objects | `[]` | What a neighbor tile must (or must not) have. | +| [`adjacencyImprovements`](#adjacencyimprovements) | array of objects | `[]` | Neighbors that give the improvement levels. | +| [`routes`](#routes-and-range) | terrain id list | `[]` | Terrains for route connections. | +| [`range`](#routes-and-range) | integer | `0` | Distance of route connections. | +| [`growthRate`](#growthrate) | integer | `0` | Turns per level (`patina`) or per spawn (`attract`). | +| [`growthRewards`](#growthrewards) | array of objects | `[]` | Population and score for each level-up. | +| [`prefab`](#polymod-fields) | boolean | `false` | **PolyMod.** Makes a simple prefab. | +| [`attractsResource`](#polymod-fields) | resource id | `game` | **PolyMod.** The resource that `attract` spawns. | +| [`attractsToTerrain`](#polymod-fields) | terrain id | `forest` | **PolyMod.** The terrain that `attract` spawns on. | +| [`infoOverride`](#polymod-fields) | localization key | — | **PolyMod.** Replaces the info text. | + +The name of an improvement is the localization key `building.names.`. + +## idx + +The number of the improvement in the `ImprovementData.Type` enum. Use `-1` for a new improvement. + +## hidden + +If `true`, players cannot build the improvement, it does not show in the tech tree, and the AI ignores it. The game can still place it by code; for example, the `algae` and `algaespawn` improvements are hidden and placed by abilities. A hidden improvement does not count as an unlocked `embark` improvement. + +## cost + +The stars that it costs to build the improvement. When a player decomposes an improvement, they get the cost back. + +## work + +The **star income per turn** of the improvement, not its build cost. Each turn the owner gets `work × level` stars, or twice that with the `doubled` ability next to a port. + +A new improvement starts at level 0 and then gives nothing. `work` only matters if something raises the level: [`adjacencyImprovements`](#adjacencyimprovements), the `patina` ability, or the hard-coded rules of the ice bank and the lighthouse. Cities ignore `work` and use their own income rules. + +## borderSize + +Copied into the improvement on the map. The game only reads border sizes of cities, and it creates cities with a fixed border size. No effect was found for other improvements. + +## maxLevel + +The highest level that the improvement can reach through adjacency or `patina`. `0` means no cap. The fungi get +1 maximum level with the `microbes` player ability. For PolyMod's [simple prefabs](../docs/prefabs.md#simple-prefabs-from-the-gld), a `maxLevel` above 0 makes the sprite change with the level. + +## creates + +What the improvement creates on its tile when it is built. Each entry is an object with one or more of these fields: + +| Field | Type | Effect | +| --- | --- | --- | +| `terrain` | terrain id | Changes the terrain of the tile and removes its resource. For example, clearing a forest creates `field`. | +| `resource` | resource id | Creates the resource, if the tile has no resource that the player can see. | +| `unit` | unit id | Trains the unit for free on the tile. If a unit stands there, it is pushed away. | +| `effect` | [tile effect](effects.md#tile-effects) id | Adds the effect to the tile. | + +```json +"creates": [ + { + "terrain": "field" + }, + { + "resource": "crop" + } +] +``` + +The improvement cannot be built if the tile already has the resource or the effect that it creates. + +## rewards + +What the player gets when the improvement is built. The values of all entries are added up. + +| Field | Type | Effect | +| --- | --- | --- | +| `population` | integer | Population for the city that the tile belongs to. A tile outside any city gets nothing. | +| `currency` | integer | Stars, paid at once. | +| `score` | integer | Score for the player. It is lost for improvements that do not stay on the tile (roads, `consumed` and `discrete` improvements). | + +```json +"rewards": [ + { + "population": 2 + } +] +``` + +When the improvement is destroyed, its score and the population that it gave (including from levels) are taken away again. + +> [!WARNING] +> Do not use negative `population` or `currency` rewards. The game treats them as huge positive numbers. + +## terrainRequirements + +The tiles that the improvement can be built on. Each entry is an object with a `terrain` and/or a `resource` (ids): + +```json +"terrainRequirements": [ + { + "terrain": "field", + "resource": "crop" + } +] +``` + +The game collects all terrains and all resources of all entries. The tile must have **one of the terrains** (if any are listed) **and one of the resources** (if any are listed). A terrain and a resource in the same entry are *not* paired: `[{ "terrain": "field", "resource": "crop" }, { "terrain": "forest" }]` means "field or forest, with crop". An empty list allows every tile. + +Special matches: + +- `wetland` also matches flooded or algae tiles that are not forest. +- `mangrove` also matches a flooded forest. +- With the `pontoon` player ability, `field` also matches water, except for the road, temple, canal and grow forest. +- With the `treehouse` player ability, `field` also matches forest. + +When the improvement is destroyed, the required resource is put back on the tile. + +## adjacencyRequirements + +What the 8 neighbor tiles must have. Each entry is an object with one of these fields: + +| Field | Type | Requirement | +| --- | --- | --- | +| `improvement` | improvement id | A neighbor of the same owner has this improvement. | +| `terrain` | terrain id | A neighbor of the same owner has this terrain. | +| `resource` | resource id | A neighbor of the same owner has this resource. | +| `notImprovement` | improvement id | No neighbor, of any owner, has this improvement. | + +```json +"adjacencyRequirements": [ + { + "improvement": "farm" + } +] +``` + +`improvement`, `terrain` and `resource` entries are alternatives: one match is enough. + +> [!WARNING] +> Two limits of the game code: +> - The check stops at the first positive match, so a `notImprovement` entry together with positive entries is not always enforced. Use `notImprovement` alone. +> - A `resource` entry seems to make the game throw an error when a neighbor of the same owner has no resource. This was found by reading the code and not tested. Avoid `resource` adjacency requirements. + +## adjacencyImprovements + +Neighbors that give the improvement its level. If this list is not empty, the level of the improvement is computed from the neighbor tiles of the same owner. Each entry is an object with one of these fields: + +| Field | Type | Adds to the level | +| --- | --- | --- | +| `improvement` | improvement id | The level of each neighbor with this improvement (at least 1). | +| `resources` | resource id | 1 for each neighbor with this resource and no improvement. Note the plural field name. | + +```json +"adjacencyImprovements": [ + { + "improvement": "farm" + } +] +``` + +The abilities `simple` (each neighbor counts 1) and `picky` (each type counts once) change the count. The level is capped by `maxLevel` and recomputed when neighbors change and at the start of each turn. This is how the windmill, sawmill, forge and market work. + +## routes and range + +An improvement with a non-empty `routes` list opens **routes**, like the port. Two route openers of a player connect if they are within the `range` of the first one, over a path of the terrains that both list and that the player can move on. The tiles of the path get a route: units following it move at road speed, and the route connects cities. With the `network` ability, the improvement also connects to the player's cities within `range`. + +```json +"routes": [ + "water", + "ocean" +], +"range": 5 +``` + +With `range` 0 nothing connects. Routes are not roads; road building is hard-coded to the `road` improvement. + +## growthRate + +The number of turns per level for the `patina` ability, and the number of turns between spawns for the `attract` ability. It must be above 0 if the improvement has either ability; `0` makes the game divide by zero. + +## growthRewards + +What each level-up of the improvement gives, whatever caused it. Each entry has `population` (for the city of the tile) and `score`. + +```json +"growthRewards": [ + { + "population": 1 + } +] +``` + +When the level goes down, the population is taken away again, but not the score. + +## Improvement abilities + +| Id | Number | Effect | +| --- | --- | --- | +| `none` | 0 | No effect. | +| `unique` | 1 | Each player can build it only once per game, also if it is destroyed. | +| `limited` | 2 | Only one per city. The check only looks at the city tiles up to 2 tiles from the city. This covers all vanilla cities, but if a mod lets city borders grow past 2 tiles, the outer tiles are not checked. | +| `expand` | 3 | No effect found in the game code. | +| `consumed` | 4 | An action, not a building: nothing stays on the tile. It removes the resource of the tile (except for the canal). | +| `patina` | 5 | Gains a level every `growthRate` turns, up to `maxLevel`. | +| `heal` | 7 | At the end of the owner's turn, heals the friendly unit on the tile and the units next to it. | +| `attract` | 10 | Every `growthRate` turns, spawns a resource on a free tile next to it. With PolyMod, the resource and terrain are set by [`attractsResource` and `attractsToTerrain`](#polymod-fields). | +| `bridge` | 13 | Land units can stand on and cross the tile, and units can leave boats there. | +| `poison` | 14 | Poisons units that enter the tile, except flying units and tribes with `poisonresist`. | +| `network` | 15 | Also connects routes to cities. See [routes](#routes-and-range). | +| `embark` | 16 | Land units that move onto it on water or wetland board a boat. See [UnitData](unit-data.md#hard-coded-unit-behavior). | +| `freelance` | 17 | Can be built on tiles that the player does not own (on another player's tile only with `manual`). | +| `manual` | 18 | Built by a unit standing on the tile, from the unit's actions. The unit's turn ends. | +| `slow` | 19 | Units that enter the tile must stop, unless they follow a road. | +| `picky` | 21 | For the adjacency level, each type of neighbor counts once. | +| `doubled` | 22 | Double `work` income if a port of the same owner is next to it. | +| `flood` | 23 | Floods its tile. Cannot be built on a flooded tile. | +| `discrete` | 24 | Can be built on a tile that already has an improvement, which stays. | +| `fill` | 25 | Can only be built on flooded or algae tiles, and removes the flood and algae. | +| `simple` | 27 | For the adjacency level, each neighbor counts 1, whatever its level. | + +New improvement abilities can be added with the PolyMod section `improvementAbility`; they need a [PolyScript](../docs/polyscripts.md) to do something. The ability texts in the building info use the localization keys `building.ability.`. + +## PolyMod fields + +| Field | Type | Description | +| --- | --- | --- | +| `prefab` | boolean | `true` makes a [simple prefab](../docs/prefabs.md#simple-prefabs-from-the-gld) whose sprite is the id of the improvement. | +| `attractsResource` | resource id | For the `attract` ability: the resource that is spawned. Default `game`. | +| `attractsToTerrain` | terrain id | For the `attract` ability: the terrain that the resource is spawned on. Default `forest`. | +| `infoOverride` | localization key | The key of a text that replaces the info text of the improvement. Write it with underscores as in [localization files](../docs/localization.md#term-keys), for example `my_building_info`. | + +## Vanilla improvements + +| Id | idx | | Id | idx | | Id | idx | +| --- | --- | --- | --- | --- | --- | --- | --- | +| `none` | 0 | | `watertemple` | 19 | | `algae` | 38 | +| `city` | 1 | | `mountaintemple` | 20 | | `mycelium` | 39 | +| `ruin` | 2 | | `mine` | 21 | | `burnspores` | 40 | +| `road` | 3 | | `forge` | 22 | | `clathrus` | 41 | +| `customshouse` | 4 | | `monument1` | 23 | | `hiddensanctuary` | 42 | +| `farm` | 5 | | `monument2` | 24 | | `harvestspores` | 43 | +| `windmill` | 6 | | `monument3` | 25 | | `nullbuilding` | 44 | +| `fishing` | 7 | | `monument4` | 26 | | `cultivate` | 45 | +| `port` | 8 | | `monument5` | 27 | | `starfishing` | 46 | +| `hunting` | 9 | | `monument6` | 28 | | `lighthouse` | 47 | +| `clearforest` | 10 | | `monument7` | 29 | | `bridge` | 48 | +| `burnforest` | 11 | | `enchantanimal` | 30 | | `aquafarm` | 49 | +| `lumberhut` | 12 | | `enchantwhale` | 31 | | `market` | 50 | +| `sawmill` | 13 | | `sanctuary` | 32 | | `atoll` | 51 | +| `growforest` | 14 | | `outpost` | 33 | | `canal` | 52 | +| `harvestfruit` | 15 | | `icebank` | 34 | | `fertilize` | 53 | +| `whalehunting` | 16 | | `icetemple` | 35 | | `landfill` | 54 | +| `temple` | 17 | | `polarisclimate` | 36 | | `algaespawn` | 55 | +| `foresttemple` | 18 | | `fungi` | 37 | | | | + +## Hard-coded improvement behavior + +These improvements have rules in the game code. Copying their fields to a new improvement does not copy these rules: + +- **city**: income, levels, borders, capture and roads. Created by the game, cannot be built or destroyed. +- **ruin**: placed by map generation, examined by units, cannot be destroyed. +- **lighthouse**: placed at the map corners; its level grows when players find it. Cannot be destroyed. +- **road**: sets a road on the tile instead of placing an improvement, and can be built over an improvement. +- **bridge**: needs a valid direction across water, and keeps its direction in its level. +- **port**: the only improvement that triggers `doubled`. +- **icebank**: its level is the number of ice tiles divided by 20. +- **fungi**: +1 maximum level with `microbes`; placed by map generation. +- **algae**, **algaespawn**: placed by abilities, not by players. +- **temples** and **monument1**–**monument7**: counted in player statistics by their type. +- **road**, **temple**, **canal**, **growforest**: cannot use the `pontoon` rule. + +The **market**, **sawmill**, **windmill**, **forge**, **customshouse**, **outpost** and **sanctuary** have no special rules: their behavior comes only from their GLD data. + +## Removing an improvement from a tribe + +A tribe can lose an improvement with an `improvementOverrides` entry whose value is `"none"`, as Cymanti do with `"bridge": "none"`. The improvement then disappears from that tribe's build menu. Some game code does not expect this case, so test it well. See [Overrides](tribe-data.md#overrides). diff --git a/docs/gld/index.md b/docs/gld/index.md new file mode 100644 index 0000000..5386036 --- /dev/null +++ b/docs/gld/index.md @@ -0,0 +1,92 @@ +# Game logic data + +The game logic data (GLD) is a JSON file in the game assets. It holds most of the rules of the game: the stats of every unit, the tech tree, the tribes, the buildings and their requirements, and more. Mods change it with [GLD patches](../docs/gld-patching.md). + +Each GLD has a version. Each game version uses one GLD version. This reference describes **GLD version 28**. To see the vanilla values of your game version, [dump the game data](../docs/debugging.md#dumping-game-data) and open the `GameLogicData` file with the highest number. + +## Sections + +The GLD is one JSON object with these sections: + +| Section | Content | Keyed by | Page | +| --- | --- | --- | --- | +| `tribeData` | Tribes | tribe id | [TribeData](tribe-data.md) | +| `techData` | Technologies | tech id | [TechData](tech-data.md) | +| `unitData` | Units | unit id | [UnitData](unit-data.md) | +| `improvementData` | Buildings and tile actions | improvement id | [ImprovementData](improvement-data.md) | +| `terrainData` | Terrain types | terrain id | [TerrainData](terrain-data.md) | +| `resourceData` | Resources | resource id | [ResourceData](resource-data.md) | +| `taskData` | Tasks that unlock monuments | task id | [TaskData](task-data.md) | +| `skinData` | Colors and city names of skins | skin id | [SkinData](skin-data.md) | +| `diplomacyData` | Embassy values | — (one object) | [DiplomacyData](diplomacy-data.md) | + +PolyMod also reads the sections `unitAbility`, `improvementAbility`, `tribeAbility`, `playerAbility` and `weaponData`, which the game does not have. They create new ability and weapon ids. See [New abilities and weapons](../docs/gld-patching.md#new-abilities-and-weapons). + +Unit effects and tile effects are not in the GLD, but some GLD fields refer to them. See [Effects](effects.md). + +## An entry + +Each section except `diplomacyData` is an object of entries. The key of an entry is its id. The value is an object with the fields of that section: + +```json +{ + "unitData": { + "warrior": { + "health": 100, + "defence": 20, + "movement": 1, + "range": 1, + "attack": 20, + "cost": 2, + "unitAbilities": [ + "dash", + "fortify", + "land" + ], + "weapon": 1, + "promotionLimit": 3, + "idx": 2 + } + } +} +``` + +The main example on each page uses the values from game logic data version 28. The smaller examples only show the format. Check the dumped GLD for the current values. + +## Ids + +An id is the name of a value of a game enum, in lowercase. For example, the enum value `UnitData.Type.BabyDragon` has the id `babydragon`, and `TribeType.Aimo` has the id `aimo`. The game uses ids in two places: + +- as the **keys** of entries, for example `"babydragon": { ... }`; +- as **values** that refer to other content, for example `"startingUnit": "warrior"` or `"techUnlocks": ["riding"]`. + +> [!IMPORTANT] +> The game looks up ids case-sensitively, and all ids are lowercase. An id with an uppercase letter, or an id that does not exist, makes the game fail while it reads the GLD (`Missing enum value for string ` in the log). + +Each reference page lists the vanilla ids of its section. For ids that are only names of enum values (abilities, effects), the ids are on the page that uses them. + +### Fields that refer to content + +Fields can refer to other content in several ways. The reference pages give the type of each field with these names: + +| Type | JSON | Example | +| --- | --- | --- | +| *id* | A string id. | `"startingUnit": "warrior"` | +| *id list* | An array of string ids. | `"startingTech": ["basic", "farming"]` | +| *id map* | An object with ids as keys and numbers as values. | `"terrainModifier": { "mountain": 1.2 }` | +| *id→id map* | An object with ids as keys and ids as values. | `"unitOverrides": { "rider": "hexapod" }` | +| *enum number* | A number, or the C# name of the enum value as a string. | `"category": 1` | + +## idx + +Every entry in `tribeData`, `techData`, `unitData`, `improvementData`, `terrainData`, `resourceData` and `taskData` has an integer `idx`. It is the number of the enum value of the entry, so the vanilla `idx` values match the numbers in the enum tables on each page. + +For **new** content, set `"idx": -1`. PolyMod then gives the entry a free number from 1000 up. See [Adding new content](../docs/gld-patching.md#adding-new-content). + +## Overrides + +Several tribes have their own versions of vanilla content. For example, Cymanti have the `hexapod` in place of the `rider`. The tribe fields `techOverrides`, `unitOverrides` and `improvementOverrides` map the vanilla id to the tribe's version. The tech tree, the training menu and the build menu then show the override in place of the original. See [TribeData](tribe-data.md#overrides). + +## PolyMod-only fields + +PolyMod reads some extra fields in the GLD that the game ignores, such as `preview` for tribes and `embarksTo` for units. They are marked **PolyMod** on the reference pages. The full list is in [GLD patching](../docs/gld-patching.md#polymod-only-fields). diff --git a/docs/gld/resource-data.md b/docs/gld/resource-data.md new file mode 100644 index 0000000..4509aab --- /dev/null +++ b/docs/gld/resource-data.md @@ -0,0 +1,45 @@ +# ResourceData + +`resourceData` lists the resources, such as fruit, game or metal, and the terrains that they spawn on. + +```json +"crop": { + "resourceTerrainRequirements": [ + "field" + ], + "idx": 2 +} +``` + +## Fields + +| Field | Type | Default | Description | +| --- | --- | --- | --- | +| `idx` | integer | — | The number of the resource. `-1` for a new resource. | +| [`resourceTerrainRequirements`](#resourceterrainrequirements) | terrain id list | `[]` | The terrains that the resource can spawn on. | +| [`prefab`](#prefab) | boolean | `false` | **PolyMod.** Makes a simple prefab. | + +The name of a resource is the localization key `resource.names.`. + +## resourceTerrainRequirements + +The terrains that map generation can place the resource on. An empty list allows every terrain. The list also decides which terrain the game creates for a [starting resource](tribe-data.md#startingresource) when no fitting tile is next to the capital. + +How often a resource spawns is set per tribe, with the tribe's [`resourceModifier`](tribe-data.md#resourcemodifier). A new resource has a base chance of 0, so it only spawns for tribes that give it a `resourceModifier` value. + +What players can do with a resource comes from improvements: an improvement that requires the resource in its [`terrainRequirements`](improvement-data.md#terrainrequirements) can be built on it, for example `hunting` on `game`. + +## prefab + +**PolyMod.** `true` makes a [simple prefab](../docs/prefabs.md#simple-prefabs-from-the-gld) whose sprite is the id of the resource. Without a prefab, a new resource has no look of its own. + +## Vanilla resources + +| Id | idx | | Id | idx | | Id | idx | +| --- | --- | --- | --- | --- | --- | --- | --- | +| `none` | 0 | | `whale` | 4 | | `starfish` | 8 | +| `game` | 1 | | `metal` | 5 | | `aquacrop` | 9 | +| `crop` | 2 | | `fruit` | 6 | | | | +| `fish` | 3 | | `spores` | 7 | | | | + +`starfish` is not placed by the normal resource generation. diff --git a/docs/gld/skin-data.md b/docs/gld/skin-data.md new file mode 100644 index 0000000..09ba9e3 --- /dev/null +++ b/docs/gld/skin-data.md @@ -0,0 +1,51 @@ +# SkinData + +`skinData` gives skins their own tribe color and city names. A tribe lists its skins in its [`skins`](tribe-data.md#skins) field; `skinData` only adds values that differ from the tribe. + +```json +"skinData": { + "swamp": { + "color": 6786096, + "language": "bub,ly,sq,ee,to,ad,bo,swa,bu,oa,squ,am,goo,pho,am,oct" + } +} +``` + +## Fields + +| Field | Type | Description | +| --- | --- | --- | +| `color` | integer | The color of the skin, as an RGB number: `red × 65536 + green × 256 + blue`. For example, `6786096` is `0x678C30`. If it is `0` or missing, the skin uses the [tribe color](tribe-data.md#color). | +| `language` | string | The city name syllables of the skin, separated by commas. If it is empty or missing, the skin uses the [tribe language](tribe-data.md#language). | + +The key is the id of the skin. PolyMod changes `skinData` keys to lowercase. + +## Vanilla skins + +| Id | Number | Note | +| --- | --- | --- | +| `none` | -1 | No skin. | +| `default` | 0 | The default look of every tribe. | +| `ranger` | 1 | | +| `ninja` | 2 | | +| `baerion` | 3 | | +| `scholar` | 5 | | +| `mercenary` | 7 | | +| `sfinx` | 8 | | +| `skeleton` | 9 | | +| `arty` | 10 | | +| `pirate` | 11 | | +| `aibo` | 12 | | +| `urkaz` | 13 | | +| `ikarus` | 14 | | +| `darkelf` | 15 | | +| `swamp` | 17 | | +| `magma` | 18 | | +| `cute` | 19 | | +| `test` | 2000 | A test skin, not for play. | + +Which tribe has which skin is set by the `skins` field of each tribe in the GLD. Numbers 4, 6 and 16 are not used. + +## New skins + +A new skin is made by listing a new id in the `skins` of a tribe. See [New skins](../docs/gld-patching.md#new-skins). diff --git a/docs/gld/task-data.md b/docs/gld/task-data.md new file mode 100644 index 0000000..9ae1154 --- /dev/null +++ b/docs/gld/task-data.md @@ -0,0 +1,41 @@ +# TaskData + +`taskData` lists the tasks: goals that a player can complete during a game. Completing a task unlocks an improvement, usually a monument. In this example the monument is only an illustration; check the dumped GLD for which task unlocks which monument. + +```json +"wealth": { + "improvementUnlocks": [ + "monument4" + ], + "idx": 4 +} +``` + +## Fields + +| Field | Type | Default | Description | +| --- | --- | --- | --- | +| `idx` | integer | — | The number of the task. | +| `improvementUnlocks` | improvement id list | `[]` | The improvements that the player can build after completing the task. Tribe `improvementOverrides` do not apply to them. | + +The title of a task is the localization key `polyplayer.task..title`, and its description is `polyplayer.task..description`. + +A task starts when the player gets a tech that has it in its [`taskUnlocks`](tech-data.md#taskunlocks). Some tasks also start by themselves, as the table shows. + +> [!NOTE] +> The condition of each task is code in the game, one class per task. A new task id from a patch has no condition, so it can never be completed without a [PolyScript](../docs/polyscripts.md). You can change the `improvementUnlocks` of the vanilla tasks. + +## Vanilla tasks + +| Id | idx | Completed when | Starts by itself | +| --- | --- | --- | --- | +| `none` | 0 | — | — | +| `pacifist` | 1 | The player does not attack for 5 turns. | no | +| `genius` | 2 | The player owns every tech of their tribe's tree. | no | +| `network` | 3 | 5 cities are connected to the capital. | when a city is connected | +| `wealth` | 4 | The player has 100 stars. | no | +| `killer` | 5 | The player has killed 10 units. | on a kill | +| `metropolis` | 6 | The player has a city of level 5 or more. | when a city levels up or is captured | +| `explorer` | 7 | The player has explored every tile of the map. | no | +| `explorelighthouses` | 8 | The player has explored all 4 corners of the map (the lighthouses). | yes | +| `convert` | 9 | The player has converted 3 units. | no | diff --git a/docs/gld/tech-data.md b/docs/gld/tech-data.md new file mode 100644 index 0000000..8a5d02e --- /dev/null +++ b/docs/gld/tech-data.md @@ -0,0 +1,164 @@ +# TechData + +`techData` lists the technologies: the tech tree, what each tech unlocks, and how much it costs. + +The example uses the basic tech, the root of the tree (values from game logic data version 28): + +```json +"basic": { + "techUnlocks": [ + "organization", + "climbing", + "fishing", + "hunting", + "riding" + ], + "unitUnlocks": [ + "giant", + "bunny", + "scout", + "transportship", + "warrior", + "babydragon", + "firedragon", + "dagger", + "larva" + ], + "improvementUnlocks": [ + "city", + "ruin" + ], + "movementUnlocks": { + "field": 1, + "forest": 2, + "ice": 1, + "wetland": 2 + }, + "cost": 0, + "idx": 0 +} +``` + +## Fields + +| Field | Type | Default | Description | +| --- | --- | --- | --- | +| [`idx`](#idx) | integer | — | The number of the tech. `-1` for a new tech. | +| [`cost`](#cost) | integer | `0` | The cost tier of the tech. | +| [`techUnlocks`](#techunlocks) | tech id list | `[]` | The techs that come after this tech in the tree. | +| [`unitUnlocks`](#unitunlocks) | unit id list | `[]` | The units that the tech lets cities train. | +| [`improvementUnlocks`](#improvementunlocks) | improvement id list | `[]` | The improvements that the tech lets the player build. | +| [`abilityUnlocks`](#abilityunlocks) | player ability id list | `[]` | The player abilities that the tech gives. | +| [`taskUnlocks`](#taskunlocks) | task id list | `[]` | The tasks that the tech starts. | +| [`movementUnlocks`](#movementunlocks) | terrain id map | `{}` | The terrains that units can enter. | +| [`defenceBonusUnlocks`](#defencebonusunlocks) | terrain id map | `{}` | The terrains that give a defence bonus. | + +The name of a tech is the localization key `technology.names.`. + +## idx + +The number of the tech in the `TechData.Type` enum. Use `-1` for a new tech. + +## cost + +The cost tier. The star price of the tech is: + +``` +price = ceil((4 + cost × cities) × multiplier) +``` + +where `cities` is the number of cities of the player, and `multiplier` is 2/3 with the `literacy` player ability and 1 without it. A tech with `cost` 0 is free and does not count for the score or for the Genius task. Vanilla techs have the tiers 1, 2 and 3. + +## techUnlocks + +The techs that come after this tech. The tech tree of a tribe starts at `basic` and follows `techUnlocks`, with the tribe's [`techOverrides`](tribe-data.md#overrides) applied to each tech. + +A player can research a tech if they own the tech before it. In current games, a player can also research a tech if they own one of the techs after it. + +A new tech must be in the `techUnlocks` of another tech (or in a tribe's `startingTech`), or no one can reach it. The tech tree screen spreads the branches of `basic` evenly around the circle, so PolyMod supports more than 5 branches. + +## unitUnlocks + +The units that cities can train once the player owns the tech, after the tribe's [`unitOverrides`](tribe-data.md#overrides). [Hidden](unit-data.md#hidden) units are not trainable, but a tech still makes them available as [upgrades](unit-data.md#upgradesfrom). A `unique` unit is not trainable while the player has one. + +## improvementUnlocks + +The improvements that the player can build once they own the tech, after the tribe's [`improvementOverrides`](tribe-data.md#overrides). [Hidden](improvement-data.md#hidden) improvements are left out. + +## abilityUnlocks + +The [player abilities](#player-abilities) that the player gets with the tech. + +## taskUnlocks + +The [tasks](task-data.md) that start when the player gets the tech. Some tasks also start by themselves; see [TaskData](task-data.md#vanilla-tasks). + +## movementUnlocks + +The terrains that the units of the player can enter once they own the tech. Only the keys matter; the game does not read the numbers. Unlocking `ocean` also unlocks `water`. + +```json +"movementUnlocks": { + "mountain": 1 +} +``` + +A unit with a non-empty [`movementTerrain`](unit-data.md#movementterrain) can only use the unlocked terrains that are also in its list (or all terrains of its list with `navigate`). + +## defenceBonusUnlocks + +The terrains on which the units of the player get a defence bonus. Any number above 1 gives the same bonus of 1.5×; the exact number does not matter. + +```json +"defenceBonusUnlocks": { + "water": 15, + "ocean": 15 +} +``` + +## Player abilities + +Player abilities are rules that a player gets from a tech, through `abilityUnlocks`. + +| Id | Number | Effect | +| --- | --- | --- | +| `disband` | 0 | Units that have not moved or attacked can be disbanded for half their cost. | +| `destroy` | 1 | Improvements can be destroyed. | +| `literacy` | 2 | Techs cost 1/3 less. | +| `glide` | 3 | Units without `skate` move slightly cheaper on ice. | +| `decompose` | 5 | Improvements can be decomposed: at the end of the turn they are removed and their cost is paid back. | +| `peacetreaty` | 6 | The player can offer peace treaties. | +| `embassy` | 7 | The player can build embassies with players who own their capital. | +| `capitalvision` | 8 | The player sees the capitals of the players that they know. | +| `dividend` | 9 | No effect in game code. | +| `discipline` | 10 | Units are promoted after 2 kills instead of 3. | +| `pontoon` | 11 | Improvements that need `field` can be built on water (except road, temple, canal and grow forest). | +| `treehouse` | 12 | Improvements that need `field` can be built on forest. | +| `bubble` | 13 | Units with `amphibious` get a bubble (+1 movement) on flooded tiles. | +| `microbes` | 14 | Fungi can reach one more level. | + +New player abilities can be added with the PolyMod section `playerAbility`; they need a [PolyScript](../docs/polyscripts.md) to do something. The name of a player ability is the localization key `player.abilities.`. + +## Vanilla techs + +| Id | idx | | Id | idx | | Id | idx | +| --- | --- | --- | --- | --- | --- | --- | --- | +| `basic` | 0 | | `mathematics` | 17 | | `shock` | 35 | +| `riding` | 1 | | `archery` | 18 | | `recycling` | 36 | +| `freespirit` | 2 | | `spiritualism` | 19 | | `hydrology` | 37 | +| `chivalry` | 3 | | `climbing` | 20 | | `diplomacy` | 38 | +| `roads` | 4 | | `meditation` | 21 | | `aquaculture` | 39 | +| `trade` | 5 | | `philosophy` | 22 | | `fishingsimple` | 40 | +| `organization` | 6 | | `mining` | 23 | | `sledding` | 41 | +| `shields` | 7 | | `smithery` | 24 | | `icefishing` | 42 | +| `farming` | 8 | | `freediving` | 25 | | `pescetism` | 43 | +| `construction` | 9 | | `spearing` | 26 | | `ramming` | 44 | +| `fishing` | 10 | | `riding2` | 27 | | `aquabase` | 45 | +| `whaling` | 11 | | `forestmagic` | 28 | | `marinelife` | 46 | +| `aquatism` | 12 | | `watermagic` | 29 | | `aquafishing` | 47 | +| `sailing` | 13 | | `frostwork` | 30 | | `waterways` | 48 | +| `navigation` | 14 | | `polarwarfare` | 31 | | `rituals` | 49 | +| `hunting` | 15 | | `polarism` | 32 | | `mysticism` | 50 | +| `forestry` | 16 | | `oceanology` | 33 | | | | + +There is no tech with the number 34. Some techs are tribe versions of other techs, used through [`techOverrides`](tribe-data.md#overrides), for example `shock` for Cymanti in place of `chivalry`. diff --git a/docs/gld/terrain-data.md b/docs/gld/terrain-data.md new file mode 100644 index 0000000..b209c31 --- /dev/null +++ b/docs/gld/terrain-data.md @@ -0,0 +1,39 @@ +# TerrainData + +`terrainData` lists the terrain types. A terrain entry only has an index; the rules for a terrain are in other sections, for example the movement and defence unlocks of [techs](tech-data.md#movementunlocks), the `movementTerrain` of [units](unit-data.md#movementterrain) and the requirements of [improvements](improvement-data.md#terrainrequirements). + +```json +"terrainData": { + "field": { + "idx": 3 + }, + "mountain": { + "idx": 4 + } +} +``` + +## Fields + +| Field | Type | Description | +| --- | --- | --- | +| `idx` | integer | The number of the terrain type. `-1` for new terrain. | + +The name of a terrain is the localization key `terrain.`. + +## Vanilla terrains + +| Id | idx | +| --- | --- | +| `none` | 0 | +| `water` | 1 | +| `ocean` | 2 | +| `field` | 3 | +| `mountain` | 4 | +| `forest` | 5 | +| `ice` | 6 | +| `wetland` | 7 | +| `mangrove` | 8 | + +> [!NOTE] +> Much terrain behavior is hard-coded in the game, for example that units on `water` and `ocean` are boats, or how `ice` renders. A new terrain only gets the behavior that the GLD fields give it. It uses its id as its [sprite name](../docs/textures.md#base-names-of-terrain-resources-and-improvements). diff --git a/docs/gld/toc.yml b/docs/gld/toc.yml new file mode 100644 index 0000000..45e8138 --- /dev/null +++ b/docs/gld/toc.yml @@ -0,0 +1,22 @@ +- name: Overview + href: index.md +- name: TribeData + href: tribe-data.md +- name: TechData + href: tech-data.md +- name: UnitData + href: unit-data.md +- name: ImprovementData + href: improvement-data.md +- name: TerrainData + href: terrain-data.md +- name: ResourceData + href: resource-data.md +- name: TaskData + href: task-data.md +- name: SkinData + href: skin-data.md +- name: DiplomacyData + href: diplomacy-data.md +- name: Effects + href: effects.md diff --git a/docs/gld/tribe-data.md b/docs/gld/tribe-data.md new file mode 100644 index 0000000..32384f8 --- /dev/null +++ b/docs/gld/tribe-data.md @@ -0,0 +1,230 @@ +# TribeData + +`tribeData` lists the tribes: their color, city names, start, abilities, skins and the tribe-specific versions of techs, units and improvements. + +The example uses Cymanti (values from game logic data version 28): + +```json +"cymanti": { + "color": 12778752, + "style": 16, + "climate": 16, + "skins": [ + "Cute" + ], + "language": "cy,zi,phy,dio,bio,tic,sy,ca,ly,um,sis,ci,hex,pod,ea,rhi,the,exo,neo,ner,seg,ho,lo,chy,ia,ce,li,co,ta,my,aph,ich,zo,di,bo", + "unitOverrides": { + "rider": "hexapod", + "giant": "centipede", + "knight": "doomux", + "archer": "phychi", + "swordsman": "mantis", + "catapult": "exida", + "defender": "kiton", + "mindbender": "shaman", + "cloak": "moth", + "dagger": "bugegg", + "pirate": "bugegg", + "rammership": "boomchi", + "scoutship": "raychi", + "bombership": "island" + }, + "techOverrides": { + "construction": "recycling", + "chivalry": "shock", + "meditation": "rituals", + "philosophy": "mysticism" + }, + "startingTech": [ + "basic", + "farming" + ], + "startingResource": [ + "spores", + "spores" + ], + "improvementOverrides": { + "market": "clathrus", + "farm": "fungi", + "port": "algae", + "road": "mycelium", + "bridge": "none" + }, + "priceTier": 2, + "category": 2, + "bonus": 0, + "startingUnit": "shaman", + "tribeAbilities": [ + "poisonresist" + ], + "idx": 17, + "terrainModifier": { + "mountain": 1.2 + }, + "resourceModifier": { + "spores": 0.3, + "crop": 0 + } +} +``` + +## Fields + +| Field | Type | Default | Description | +| --- | --- | --- | --- | +| [`idx`](#idx) | integer | — | The number of the tribe. `-1` for a new tribe. | +| [`color`](#color) | integer | `0` | The tribe color. | +| [`language`](#language) | string | — | The syllables for city names. | +| [`startingStars`](#startingstars) | integer | `5` | The stars at the start of a game. | +| [`bonus`](#bonus) | enum number | `0` | A special bonus at the start of a game. | +| [`startingUnit`](#startingunit) | unit id | — | The unit in the capital at the start. | +| [`category`](#category) | enum number | `0` | Where the tribe shows in tribe selection. | +| [`priceTier`](#pricetier) | enum number | `0` | The store price tier of the tribe. | +| [`skins`](#skins) | list of skin names | `[]` | The skins of the tribe. | +| [`terrainModifier`](#terrainmodifier) | terrain id map | `{}` | Multipliers for terrain generation. | +| [`resourceModifier`](#resourcemodifier) | resource id map | `{}` | Multipliers for resource generation. | +| [`startingTech`](#startingtech) | tech id list | `[]` | The techs that the tribe has at the start. | +| [`startingResource`](#startingresource) | resource id list | `[]` | Resources placed near the capital at the start. | +| [`tribeAbilities`](#tribeabilities) | tribe ability id list | `[]` | Special rules of the tribe. | +| [`techOverrides`](#overrides) | tech id→id map | `{}` | Tribe versions of techs. | +| [`unitOverrides`](#overrides) | unit id→id map | `{}` | Tribe versions of units. | +| [`improvementOverrides`](#overrides) | improvement id→id map | `{}` | Tribe versions of improvements. | +| [`preview`](#preview) | array | — | **PolyMod.** Changes to the tribe preview map. | + +The name of a tribe is the localization key `tribes.`, and its description is `tribes..info`. + +## Vanilla tribes + +| Id | idx | | Id | idx | +| --- | --- | --- | --- | --- | +| `none` | 0 | | `luxidoor` | 9 | +| `nature` | 1 | | `oumaji` | 10 | +| `aimo` | 2 | | `quetzali` | 11 | +| `aquarion` | 3 | | `vengir` | 12 | +| `bardur` | 4 | | `xinxi` | 13 | +| `elyrion` | 5 | | `yadakk` | 14 | +| `hoodrick` | 6 | | `zebasi` | 15 | +| `imperius` | 7 | | `polaris` | 16 | +| `kickoo` | 8 | | `cymanti` | 17 | + +`none` and `nature` are not playable tribes. + +## idx + +The number of the tribe in the `TribeType` enum. Use `-1` for a new tribe; see [Adding new content](../docs/gld-patching.md#new-tribes). + +## color + +The tribe color as an RGB number: `red × 65536 + green × 256 + blue`. For example, `12778752` is `0xC2FD00`. A [skin](skin-data.md) with a color above 0 replaces it. If two players in a game would have the same color, the game gives one of them the unused color of another tribe. + +## language + +The syllables that the game combines into names, separated by commas. The game uses them for city names and for the names of AI players. It joins random syllables until the name has about 3 to 6 characters, and capitalizes the first letter (except for Elyrion). A [skin](skin-data.md) can have its own syllables. + +## startingStars + +The stars that the player has at the start of a game. Default `5`. (In the tutorial, the game uses 0.) + +## bonus + +A special rule at the start of a game. The value is a number, or the name as a string: + +| Value | Name | Effect | +| --- | --- | --- | +| 0 | `None` | No bonus. | +| 1 | `CityLevel3` | The capital starts at level 3. Luxidoor uses it. | +| 2 | `Spores` | Places a `fungi` improvement on the first field tile next to the capital. Not used by vanilla tribes. | + +## startingUnit + +The id of the unit that the game puts in the capital at the start of a game. It can move and attack in the first turn. The game uses this unit as it is: `unitOverrides` do not apply to it. + +## category + +Where the tribe shows in the tribe selection. A number, or the name as a string: + +| Value | Name | Meaning | +| --- | --- | --- | +| 0 | `Hidden` | Not shown in the tribe selection. | +| 1 | `Human` | Shown with the regular tribes. | +| 2 | `Special` | Shown with the special tribes. | + +The category only changes the tribe selection screen. Random tribes and AI players can still be any tribe, also a `Hidden` one. + +## priceTier + +The store price tier: `0` (`Tier0`) to `3` (`Tier3`). The game reads this field, but no game code uses it. PolyMod unlocks all custom tribes anyway. + +## skins + +The skins that players can choose for this tribe, by skin name, for example `["Baerion"]`. Vanilla skin names are not case-sensitive here. A name that is not a vanilla skin creates a new skin; see [New skins](../docs/gld-patching.md#new-skins). The skin ids are listed in [SkinData](skin-data.md#vanilla-skins). + +In a patch, a plain string in `skins` **adds** the skin, and `"-name"` removes it. See [Merge rules](../docs/gld-patching.md#merge-rules). + +## terrainModifier + +Multipliers for the terrain that map generation makes on the land of this tribe. The keys are [terrain ids](terrain-data.md#vanilla-terrains) and the values are numbers: `1` is normal, `1.2` is 20% more, `0` is none. + +Map generation divides the land of a tribe between `field`, `forest` and `mountain` in proportion to their weights (base weights 0.5, 0.4 and 0.15). Only these three keys have a visible effect. `water` is only used when its value is above 1, and `ocean`, `ice`, `wetland` and `mangrove` have no effect found in the map generator. + +## resourceModifier + +Chances for the resources that map generation places on the land of this tribe. The keys are [resource ids](resource-data.md#vanilla-resources) and the values are numbers. + +- For a resource with a base chance above 0, the value is a **multiplier**: `1` is normal, `0` is none. The base chances are 0.5 for `crop`, `fish`, `fruit` and `game`, 0.8 for `metal` and 0.3 for `aquacrop`. +- For a resource with a base chance of 0 (`whale` and `spores`), the value **is** the chance. So `"spores": 0.2` gives spores a chance of 0.2. +- `starfish` is not placed by map generation, whatever the value. +- New resources have a base chance of 0, so their value is their chance. + +A resource can only be placed on the terrains in its [`resourceTerrainRequirements`](resource-data.md#resourceterrainrequirements). + +## startingTech + +The techs that the tribe gets for free at the start of a game. Every vanilla tribe has `basic`, which is the root of the tech tree. + +## startingResource + +Resources that the game guarantees on the 8 tiles around the capital. Each entry gives one tile, so list a resource twice to get two. Resources that are already there count. If no tile has a fitting terrain, the game changes the terrain of a tile to one that the resource needs. + +If the list is empty, the game uses the resource that the first improvement of the starting techs needs. + +## tribeAbilities + +Special rules of the tribe, by tribe ability id: + +| Id | Number | Effect | +| --- | --- | --- | +| `none` | 0 | No effect. | +| `rainbowvision` | 1 | Only visual: ruins show a rainbow fire for the player. Elyrion. | +| `alienclimate` | 2 | Map generation: the land of the tribe does not get the usual climate growth. For Polaris, water next to the capital becomes ice. | +| `spread` | 3 | When the tribe captures a city or its borders grow, the climate of the city area changes to the tribe's climate (for Polaris: the tiles freeze). Other tribes change these tiles back. | +| `freeze` | 4 | No effect in game logic; only an achievement checks it. The freezing of Polaris is tied to the tribe, not to this ability. | +| `poisonresist` | 5 | Units are not poisoned by improvements with the `poison` ability. Cymanti. | +| `flooded` | 6 | Map generation floods the field and forest tiles of the tribe; captured cities are flooded; ruins on water become cities for the tribe. Aquarion. | + +Some Polaris behavior is tied to the tribe `polaris` itself, not to its abilities. New tribe abilities can be added with the PolyMod section `tribeAbility`; see [New abilities and weapons](../docs/gld-patching.md#new-abilities-and-weapons). + +## Overrides + +`techOverrides`, `unitOverrides` and `improvementOverrides` replace vanilla content with the tribe's own version. Each key is the id of the original content, and each value is the id of the tribe version: + +```json +"unitOverrides": { + "rider": "hexapod" +} +``` + +The game applies overrides when it builds the tech tree of the tribe, lists the units that it can train, and lists the improvements that it can build. So where other tribes get a `rider`, this tribe gets a `hexapod`. Overrides do **not** apply to the `startingUnit`, to the improvements of tasks (monuments), to embark boats, or to unit growth. + +To take an improvement away from a tribe, use `"none"` as the value, as Cymanti do with `"bridge": "none"`. The improvement then disappears from that tribe's build menu. This only works well for improvements: + +- for units, `"none"` seems to crash the training list (found by reading the code, not tested); +- for techs, `"none"` is not a valid id and makes the game fail while it reads the GLD. + +## preview + +**PolyMod.** Changes the tiles of the preview map in tribe selection. See [Tribe previews](../docs/tribe-previews.md). + +## style and climate + +Older GLD versions had the fields `style` and `climate`. The game no longer reads them. PolyMod sets them for new tribes; you do not need to. diff --git a/docs/gld/unit-data.md b/docs/gld/unit-data.md new file mode 100644 index 0000000..2b8ddf7 --- /dev/null +++ b/docs/gld/unit-data.md @@ -0,0 +1,241 @@ +# UnitData + +`unitData` lists the units: their stats, abilities, movement and upgrades. + +The example uses the baby dragon (values from game logic data version 28): + +```json +"babydragon": { + "health": 150, + "defence": 30, + "movement": 2, + "range": 1, + "attack": 30, + "cost": 10, + "hidden": true, + "upgradesFrom": "dragonegg", + "unitAbilities": [ + "grow", + "dash", + "fly", + "escape", + "scout", + "static" + ], + "weapon": 7, + "promotionLimit": 0, + "idx": 18, + "growthRate": 3 +} +``` + +## Fields + +| Field | Type | Default | Description | +| --- | --- | --- | --- | +| [`idx`](#idx) | integer | — | The number of the unit. `-1` for a new unit. | +| [`hidden`](#hidden) | boolean | `false` | The unit cannot be trained. | +| [`cost`](#cost) | integer | `0` | The star cost to train or upgrade into the unit. | +| [`health`](#health-defence-and-attack) | integer | `0` | Maximum health, ×10. | +| [`defence`](#health-defence-and-attack) | integer | `0` | Defence, ×10. | +| [`attack`](#health-defence-and-attack) | integer | `0` | Attack, ×10. | +| [`movement`](#movement) | integer | `0` | Tiles per turn. | +| [`range`](#range) | integer | `0` | Attack range in tiles. | +| [`weapon`](#weapon) | weapon number or id | `0` | The attack animation. | +| [`unitAbilities`](#unitabilities) | unit ability id list | `[]` | The abilities of the unit. | +| [`movementTerrain`](#movementterrain) | terrain id list | `[]` | The terrains that the unit can enter. | +| [`upgradesFrom`](#upgradesfrom) | unit id | none | The unit that can be upgraded into this unit. | +| [`promotesTo`](#promotesto) | unit id | none | The unit that this unit turns into when it is promoted. | +| [`growthRate`](#growthrate) | integer | `0` | Turns until a unit with `grow` grows. | +| [`embarksTo`](#embarksto) | unit id | — | **PolyMod.** The boat that this unit becomes when it embarks. | + +The name of a unit is the localization key `unit.names.`. + +The old field `promotionLimit` no longer exists; the game ignores it. A unit is promoted after 3 kills, or after 2 kills if the player has the `discipline` [player ability](tech-data.md#player-abilities). A unit can be promoted only once. + +## idx + +The number of the unit in the `UnitData.Type` enum. Use `-1` for a new unit. + +## hidden + +If `true`, the unit is not in the training menu of cities and cannot be trained. A hidden unit can still: + +- be the target of a paid upgrade (see [`upgradesFrom`](#upgradesfrom)), +- appear through growth, promotion, rewards or abilities. + +A hidden unit gets no experience from kills and can never be promoted. + +## cost + +The stars that it costs to train the unit, and to upgrade another unit into it. The unit is also worth `cost × 5` score. Disbanding a unit gives back half of its cost, rounded down. For a boat, the cost of its passenger counts too. + +## health, defence and attack + +These values are stored as **ten times** the value that the game shows: `"health": 100` is 10 HP, `"defence": 20` is 2 defence, `"attack": 25` is 2.5 attack. + +- **health** is the maximum health. A new unit starts with full health. A promoted (veteran) unit has 5 more maximum HP. +- **defence** is multiplied by a defence bonus: 1.5× on a terrain where the player has a [defence bonus](tech-data.md#defencebonusunlocks), 1.5× for a `fortify` unit in its own city and 4× in a city with a city wall. A poisoned unit gets only half the bonus. +- **attack** is the attack strength. A unit with `0` attack can only target something if it has `convert` or `infiltrate`. + +The damage of an attack is `round(attackForce / (attackForce + defenceForce) × attack × 4.5)`, where each force is the stat multiplied by the current health share of the unit. The defender strikes back with its base defence, unless the defender is `stiff` or frozen, the attacker has `convert`, `surprise` or `freeze`, or the attacker is out of the defender's range. + +## movement + +The number of tiles that the unit can move per turn. A road step costs half. Some terrain and improvements stop a unit when it enters them. The [unit effects](effects.md#unit-effects) `swift` and `bubble` each give +1 movement, and `poisoned` gives −1 (at least 1). + +## range + +The attack range in tiles, counting diagonal steps as 1. A unit with range 1 moves onto the tile of a unit that it kills, if it can. The `splash` ability only works with a range above 1. + +## weapon + +The look of the attack: the animation, the projectile and the sound. It has almost no effect on game rules. In the GLD it is a number; in a patch PolyMod also accepts the id. + +| Id | Number | | Id | Number | +| --- | --- | --- | --- | --- | +| `none` | 0 | | `trident` | 9 | +| `club` | 1 | | `icearrow` | 10 | +| `sword` | 2 | | `poison` | 11 | +| `arrow` | 3 | | `sting` | 12 | +| `magic` | 4 | | `dagger` | 13 | +| `gun` | 5 | | `burn` | 14 | +| `rock` | 6 | | `laser` | 15 | +| `claw` | 7 | | `pierce` | 16 | +| `fireblow` | 8 | | `water` | 17 | + +`arrow`, `icearrow`, `fireblow`, `rock`, `sting`, `gun`, `poison`, `pierce`, `trident`, `water` and `burn` are projectiles. New weapon ids can be added with the PolyMod section `weaponData`, but a new weapon has no animation of its own. + +## unitAbilities + +The abilities of the unit, by unit ability id. See [Unit abilities](#unit-abilities). + +## movementTerrain + +The terrains that the unit can move on, by [terrain id](terrain-data.md#vanilla-terrains). + +- **Empty**: the unit can enter every terrain that the techs of the player unlock (see [`movementUnlocks`](tech-data.md#movementunlocks)), and water if it has `swim`. +- **Not empty**: the unit can only enter these terrains, and only after the player unlocked them with a tech, unless the unit has `navigate`. The terrain `wetland` in this list also matches flooded and algae tiles. + +A city can only train the unit if at least one tile next to the city matches. + +The list, together with `swim` and `carry`, also decides the movement class of the unit: + +| Abilities and list | Class | Behavior | +| --- | --- | --- | +| no `swim` | land unit | Stops when it enters an algae tile. Embarks on water at an `embark` improvement (port). | +| `swim`, empty list, no `carry` | amphibious | Moves on water and land, but stops after the first land tile that is not flooded. | +| `swim` with a list, or `carry` | water-bound | Stops when it enters a flooded tile. | + +## upgradesFrom + +The id of another unit. It has two uses: + +1. **Paid upgrades.** If unit *X* has `"upgradesFrom": "Y"`, a unit *Y* can be upgraded into *X* for *X*'s cost, once a tech unlocks *X* (hidden units are allowed). This is how boats become ships. Upgrades are only offered in your own or an allied territory. Units with `grow` cannot be upgraded. +2. **Growth.** A unit with `grow` grows into the first unit in `unitData` whose `upgradesFrom` is that unit. For example, the baby dragon has `"upgradesFrom": "dragonegg"`, so the dragon egg grows into it. Growth ignores techs and tribe overrides. + +When a unit upgrades or grows, it becomes a new unit: experience and promotion are reset. + +## promotesTo + +If set, the unit turns into this unit for free when it is promoted, instead of becoming a veteran. + +## growthRate + +For units with `grow`: the number of turns after which the unit grows, at the end of its owner's turn. `0` makes it grow at the first end of turn. When a growing unit leaves a boat, it grows if it is at least 3 turns old, whatever the growth rate. + +## embarksTo + +**PolyMod.** The id of the boat that this unit becomes when it embarks. Without it, the game picks the boat: `transportship`, `cloak_boat` for units with `hide`, `pirate` for the dagger and `juggernaut` for the giant. + +## Unit abilities + +| Id | Number | Effect | +| --- | --- | --- | +| `none` | 0 | No effect. | +| `dash` | 1 | Can attack after it moves. | +| `escape` | 2 | Can move after it attacks. | +| `scout` | 3 | Sees 2 tiles far instead of 1. | +| `sneak` | 4 | Ignores enemy zones of control: enemies next to it do not stop it. | +| `hide` | 5 | Becomes invisible when it moves, can move through enemy units, and ignores zones of control. Embarks into a `cloak_boat`. | +| `persist` | 7 | Can attack again after a kill, if another target is in range. Needs `dash` or `escape`: every attack marks the unit as moved, and a moved unit can only attack with `dash`. | +| `convert` | 8 | A hit that does not kill converts the target to the attacker's side. The target does not strike back. Works with 0 attack. | +| `heal` | 9 | Can heal friendly units next to it by 4 HP, or cure their poison, instead of moving. | +| `swim` | 10 | Moves on water without a port and never embarks. See [movementTerrain](#movementterrain). | +| `carry` | 11 | A boat: it carries a passenger unit and unloads it on land or in a city. Its health is the passenger's, unless it has `protect`. A city that trains a boat puts a warrior in it. | +| `grow` | 12 | Grows into another unit after `growthRate` turns. See [upgradesFrom](#upgradesfrom). | +| `fly` | 13 | Can enter every terrain, at the same cost, without a port; it is not hurt by poison improvements. | +| `splash` | 14 | With a range above 1, units next to the target take half damage (or are poisoned, with `poison`). | +| `navigate` | 16 | Can enter the terrains of its `movementTerrain` without a tech. | +| `crush` | 17 | No effect in game logic; only a text exists. | +| `freeze` | 18 | Its attack freezes the target. The target does not strike back. | +| `freezearea` | 19 | Can freeze the area around it instead of moving: water becomes ice and enemy units are frozen. | +| `autofreeze` | 20 | Freezes the area around it after each move. | +| `skate` | 21 | Moves fast on ice, but every other tile stops it. | +| `fortify` | 22 | Gets the higher defence bonus in its own cities. See [defence](#health-defence-and-attack). | +| `creep` | 23 | Every tile except mountains costs normal movement: forest, flood and algae do not slow it. Gets no road bonus. | +| `boost` | 24 | Can give friendly units next to it +1 movement (`swift`) instead of moving. | +| `independent` | 25 | Belongs to no city, so it uses no city unit slot. | +| `poison` | 26 | A hit that does not kill poisons the target. | +| `eat` | 27 | When it kills a unit, a `segment` unit grows at the end of its body. | +| `unique` | 29 | The player can only have one of it at a time. | +| `explode` | 30 | Can explode: it dies, spawns spores and deals half damage and poison to enemy units next to it. | +| `surprise` | 31 | Its targets never strike back. | +| `infiltrate` | 35 | Attacks only enemy cities next to it. It dies, robs the city and spawns daggers (or pirates on water) there. | +| `detect` | 36 | No effect in game logic; only a text exists. | +| `stiff` | 38 | Never strikes back. | +| `protect` | 39 | A boat with its own health, instead of the passenger's health. | +| `stomp` | 40 | Deals half damage to all enemy units next to it after each move. | +| `autoheal` | 41 | Heals friendly units next to it after each move. | +| `static` | 42 | Gets no experience and can never be promoted. | +| `tentacles` | 44 | Attacks with its defence. Hits all units next to it when it is trained or moves, and hits enemies that move next to it. | +| `autoflood` | 45 | Floods the tile that it moves to. | +| `drench` | 46 | Can target any tile that can be flooded, also an empty one, and floods it. | +| `amphibious` | 47 | Gets a bubble (+1 movement) on flooded tiles, if the player has the `bubble` ability, and can clear algae. Also the movement label in the unit info. | +| `water` | 48 | The movement label in the unit info. | +| `land` | 49 | The movement label in the unit info. | +| `algae` | 51 | Spreads algae on the water tiles along its path. | +| `consumed` | 52 | Dies when it attacks. | +| `swarm` | 53 | Like `boost`. | +| `doubleattack` | 54 | Can attack twice per turn. Needs `dash` or `escape` for the same reason as `persist`. | + +New unit abilities can be added with the PolyMod section `unitAbility`; they need a [PolyScript](../docs/polyscripts.md) to do something. The name of an ability is the localization key `unit.abilities.`. + +## Vanilla units + +| Id | idx | | Id | idx | | Id | idx | +| --- | --- | --- | --- | --- | --- | --- | --- | +| `none` | 0 | | `tridention` | 21 | | `scoutship` | 42 | +| `scout` | 1 | | `mooni` | 22 | | `transportship` | 43 | +| `warrior` | 2 | | `battlesled` | 23 | | `rammership` | 44 | +| `rider` | 3 | | `icefortress` | 24 | | `juggernaut` | 45 | +| `knight` | 4 | | `icearcher` | 25 | | `mermaidwarrior` | 46 | +| `defender` | 5 | | `crab` | 26 | | `mermaidarcher` | 47 | +| `ship` | 6 | | `gaami` | 27 | | `mermaidswordsman` | 48 | +| `battleship` | 7 | | `hexapod` | 28 | | `mermaiddefender` | 49 | +| `catapult` | 8 | | `doomux` | 29 | | `mermaidcloak` | 50 | +| `archer` | 9 | | `phychi` | 30 | | `mermaiddagger` | 51 | +| `mindbender` | 10 | | `kiton` | 31 | | `jelly` | 52 | +| `swordsman` | 11 | | `exida` | 32 | | `shark` | 53 | +| `giant` | 12 | | `centipede` | 33 | | `siren` | 54 | +| `bunny` | 13 | | `segment` | 34 | | `aquapult` | 55 | +| `boat` | 14 | | `raychi` | 35 | | `boomchi` | 56 | +| `polytaur` | 15 | | `shaman` | 36 | | `island` | 57 | +| `navalon` | 16 | | `dagger` | 37 | | `ciru` | 58 | +| `dragonegg` | 17 | | `cloak` | 38 | | `mantis` | 59 | +| `babydragon` | 18 | | `cloak_boat` | 39 | | `bugegg` | 60 | +| `firedragon` | 19 | | `pirate` | 40 | | `moth` | 61 | +| `amphibian` | 20 | | `bombership` | 41 | | `larva` | 62 | + +Some of these ids are unused or only used in special modes. Check the dumped GLD for the units that the game uses. + +## Hard-coded unit behavior + +Some behavior is tied to specific units in the game code, so copying the abilities of such a unit to a new unit does not copy it: + +- The boats that units embark into (see [`embarksTo`](#embarksto)), and the warrior that a trained boat carries. +- `eat` always spawns a `segment`; when a unit with a follower dies, the follower becomes a `centipede`. +- `infiltrate` spawns `dagger` (or `pirate` on water, and in some cases `bugegg`); the `moth` always uses the poison variant. +- The `bunny` destroys the improvement that it steps on. The `polytaur` remembers the climate where it was born. +- The `giant` is the super unit of the city reward. Ruins can give a `swordsman`, `giant`, `navalon`, `battleship`, `bombership` or `rammership`. +- Tribe overrides apply to training, tech unlocks and spawns, but not to embark boats, the warrior in a trained boat, or growth. diff --git a/docs/index.md b/docs/index.md index 6023cdd..4b40ef7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,11 +1,27 @@ ---- -_layout: landing ---- - -# This is the **HOMEPAGE**. - -Refer to [Markdown](http://daringfireball.net/projects/markdown/) for how to write markdown files. - -## Quick Start Notes: - -1. Add images to the *images* folder if the file is referencing an image. \ No newline at end of file +--- +_layout: landing +--- + +# PolyMod + +**The mod loader for The Battle of Polytopia.** + +PolyMod lets you play Polytopia with new tribes, units, buildings, skins and much more, made by the community. This site is the documentation for mod authors, for PolyMod 2.0. + +## Start here + +- [Introduction](docs/introduction.md): what a mod can do and where to start. +- [Your first mod](docs/getting-started.md): make a working mod in a few minutes. +- [Mod structure](docs/mod-structure.md): how PolyMod finds and loads the files of a mod. + +## Reference + +- [Game logic data](gld/index.md): every section and field of the game logic data that patches change. +- [GLD patching](docs/gld-patching.md): merge rules, new content and PolyMod-only fields. +- [API](xref:PolyMod): the C# API for PolyScripts. + +## Links + +- [Download PolyMod](https://polymod.dev/download/) +- [Source code](https://github.com/PolyModdingTeam/PolyMod) +- [Discord](https://discord.gg/eWPdhWtfVy) diff --git a/docs/toc.yml b/docs/toc.yml index 6da36ae..edde86a 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -1,4 +1,6 @@ -- name: Docs - href: docs/ -- name: API - href: api/ \ No newline at end of file +- name: Docs + href: docs/ +- name: Game logic data + href: gld/ +- name: API + href: api/