Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 91 additions & 0 deletions docs/docs/config.md
Original file line number Diff line number Diff line change
@@ -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.
67 changes: 67 additions & 0 deletions docs/docs/debugging.md
Original file line number Diff line number Diff line change
@@ -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<n>.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<n>.json` | The avatar data of every version. |
| `Localization/language_<code>.json` | All terms of each language. Use one as the start for a [new language](localization.md#adding-a-new-language). |
| `Localization/localization_<category>.csv` | All terms of each localization category, with one column per language. |
| `Sprites/<atlas>/<sprite>.png` | Every sprite of every loaded atlas. |
| `Sprites/<atlas>/sprites_<atlas>.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_<tribe>.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). |
123 changes: 123 additions & 0 deletions docs/docs/getting-started.md
Original file line number Diff line number Diff line change
@@ -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#.
Loading
Loading