Skip to content

Commit c710b84

Browse files
incomplete-treeincomplete-tree
committed
add docs-tm
1 parent ced36ef commit c710b84

20 files changed

Lines changed: 443 additions & 39 deletions

‎docs/articles/getting-started.md‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎docs/articles/introduction.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,7 @@
1-
# Introduction
1+
# Introduction
2+
3+
Polymod is the modding framework for The Battle Of Polytopia.
4+
5+
If you would like information about how to **develop** mods, go to [modding](modding/your-first-mod.md).
6+
7+
If you would like information about how to use and configure PolyMod and its mods, go to [using](using/installing.md)

‎docs/articles/modding/gld.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
# Gld Patching
2+
3+
## Rules
4+
The rules that PolyMod uses to merge patches into the gld are:
5+
- If an array exists in both the patch and the gld, the array will be **completely replaced**, it will not be merged. This can be useful to remove items from an array.
6+
- If a value is `null` in the patch, it will be removed from the gld.
7+
8+
## The basics
9+
The `patch.json` file is essentially a mini GLD that includes only the values you want to change and nothing else. If you want to make a mod that just changes a `warrior`'s attack, for example…
10+
```json
11+
{
12+
"unitData": {
13+
"warrior": {
14+
"attack": 1000
15+
}
16+
}
17+
}
18+
```
19+
20+
As you can see, this uses the exact same keys as the GLD file, but excludes everything that's unnecessary for the mod.
21+
22+
## Adding new content
23+
Well, adding new content is as simple as editing existing content! You just have to pretend that something exists, and then it will exist: you need to set its `idx` to `-1` for it to work. This will make PolyMod automatically assign an `idx` when the game starts (autoindex).
24+
> [!WARNING]
25+
> Manually setting `idx` to something other than `-1` breaks mod compatibility!
26+
27+
Additionally, make sure that all the internal names you use are in lowercase. PolyMod will crash otherwise.
28+
Here's part of an example gld patch which adds new tribe:
29+
```json
30+
{
31+
"tribeData": {
32+
"testingtribe": {
33+
"color":15713321,
34+
"language":"az,bar,bryn,dûm,girt,hall,kar,khâz,kol,kruk,lok,rûdh,ruf,und,vorn,zak",
35+
"startingTech":[
36+
"basic",
37+
"mining"
38+
],
39+
"startingResource":[
40+
"metal"
41+
],
42+
"skins":[
43+
"Testingskin"
44+
],
45+
"priceTier":0,
46+
"category":2,
47+
"bonus":0,
48+
"startingUnit":"warrior",
49+
"idx":-1,
50+
"preview": [
51+
{
52+
"x": 0,
53+
"y": 0,
54+
"terrainType": "mountain",
55+
"unitType": "swordsman",
56+
"improvementType ": "mine"
57+
}
58+
]
59+
}
60+
}
61+
}
62+
```
63+
64+
## Custom Tribe Preview
65+
As you could have noticed, our testingtribe has a field `preview` which does not exist in GLD. This field was added in order to modify tribe previews if needed.
66+
```json
67+
{
68+
"preview": [
69+
{
70+
"x": 0,
71+
"y": 0,
72+
"terrainType": "mountain",
73+
"unitType": "swordsman",
74+
"improvementType ": "mine"
75+
}
76+
]
77+
}
78+
```
79+
Each tile of preview consists of:
80+
* `x` X coordinate of the tile in the preview
81+
* `y` Y coordinate of the tile in the preview
82+
* `terrainType` terrain of the original tile will be replaced with the one you choose here
83+
* `resourceType` resource of the original tile will be replaced with the one you choose here
84+
* `unitType` unit of the original tile will be replaced with the one you choose here
85+
* `improvementType` improvement of the original tile will be replaced with the one you choose here
86+
87+
Based on that, our chosen preview tile will have `mountain`, `swordsman` and `mine`.
88+
You can see all tiles and their coordinates in Tribe Preview by enabling PolyMod debug mode in `PolyMod.json`
89+
90+
## Custom Skins
91+
Also, our tribe has a non-existing skin. By writing such, PolyMod will create a skin automatically:
92+
```json
93+
{
94+
"skins": [
95+
"Testingskin"
96+
]
97+
}
98+
```
99+
100+
## Prefabs
101+
Let's look at this patch which adds new unit:
102+
```json
103+
{
104+
"unitData": {
105+
"dashbender": {
106+
"health": 100,
107+
"defence": 10,
108+
"movement": 1,
109+
"range": 1,
110+
"attack": 0,
111+
"cost": 15,
112+
"unitAbilities": [
113+
"dash",
114+
"convert",
115+
"stiff",
116+
"land"
117+
],
118+
"weapon": 4,
119+
"promotionLimit": 3,
120+
"idx": -1,
121+
"prefab": "mindbender"
122+
}
123+
}
124+
}
125+
```
126+
127+
By default, when creating a new unit, improvement or resource PolyMod will set basic sprites for them, such as:
128+
129+
* New **Unit** have explorer's sprites by default
130+
* New **Improvement**s have custom house's sprites by default
131+
* New **Resource**s have animal's sprites by default
132+
133+
If you want to change it to another already existing type, you can do just what we did for `dashbender`:
134+
```json
135+
{
136+
"prefab": "mindbender"
137+
}
138+
```
139+
That sets `mindbender`'s sprites as our base sprites for `dashbender`.
140+
141+
## Config
142+
Say that, in your mod, you created a new unit, but you aren't a balancing expert and thus you want the user to be able to configure how expensive it is. Before, you would need polyscript to do this. However, in polymod 1.2 there is a new feature that allows you to have configurable options in gld patches!
143+
Say that, for example, you wanted to change the warrior's cost to whatever the user wants.
144+
you can use `{{ config key defaultValue}}`.
145+
```
146+
{
147+
"unitData" : {
148+
"warrior" : {
149+
"cost" : {{ config "warriorCost" 5 }}
150+
}
151+
}
152+
}
153+
```
154+
but what if you want to disable or enable a unit based on config? For that, you need to do more advanced templating. Here is an example that gives ai-mo a dashbender if dashbenders are enabled, otherwise a mindbender. In reality you will also need to modify tech etc.
155+
```
156+
{
157+
"unitData": {
158+
{% if config "dashbenders" true %}
159+
"dashbender": {
160+
"health": 100,
161+
"defence": 10,
162+
"movement": 1,
163+
"range": 1,
164+
"attack": 0,
165+
"cost": 15,
166+
"unitAbilities": [
167+
"dash",
168+
"convert",
169+
"stiff",
170+
"land"
171+
],
172+
"weapon": 4,
173+
"promotionLimit": 3,
174+
"idx": -1,
175+
"prefab": "mindbender"
176+
}
177+
}
178+
{% aimo-starting = "dashbender" %}
179+
{% else %}
180+
{% aimo-starting = "mindbender" %}
181+
{% end %}
182+
"tribeData":{
183+
"ai-mo":{
184+
"startingUnit": "{{ aimo-starting }}"
185+
}
186+
}
187+
}
188+
```
189+
For a full list of templates, see [Scriban docs](https://github.com/scriban/scriban/blob/master/doc/language.md).

‎docs/articles/modding/index.md‎

Whitespace-only changes.

‎docs/articles/modding/localization.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Localization
2+
Localization is a json file in a mod that declares mod's localization strings. Mod localization is declared in `localization.json` file.
3+
4+
If you've ever used the custom language system before it was removed, you'll notice that the keys follow the same format as custom langs, but **with all the periods replaced with underscores**.
5+
If you want to translate your strings to other languages, you can simply use a comma and enter another language's name with its corresponding string.
6+
7+
### Languages
8+
* `English`
9+
* `Portuguese (Brazil)`
10+
* `Russian`
11+
* `Italian (Italy)`
12+
* `French (France)`
13+
* `Spanish (Mexico)`
14+
* `German (Germany)`
15+
* `Japanese`
16+
* `Korean`
17+
* `Hindi`
18+
* `Indonesian`
19+
* `Malay`
20+
* `Polish`
21+
* `Thai`
22+
* `Turkish`
23+
* `Vietnamese`
24+
* `Elyrion`

‎docs/articles/modding/polyscript.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
TODO

‎docs/articles/modding/sprites.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# Texture
2+
A texture is an image file in png format, which is being loaded by PolyMod in order to be used ingame.
3+
4+
PolyMod decides how to load the texture based on filename. Texture's file name consists of `name`, `style` and `level`.
5+
* `name` id of the texture
6+
* `style` tribe or skin id, for which this texture should be set
7+
* `level` level of the texture
8+
9+
### Format
10+
Here is all possible combinations of how you can name the texture file:
11+
* `name__.png` will replace the texture of chosen target for all tribes, skins and possible levels
12+
* `name_style_.png` will replace the texture of chosen target for chosen tribe or skin and for all possible levels
13+
* `name__level.png` will replace the texture of chosen target for all tribes and skins, but for chosen level
14+
* `name_style_level.png` will replace the texture of chosen target for chosen tribe or skin and for chosen level
15+
16+
### Example
17+
You want to replace all lumberhut textures for all tribes.
18+
* We want to replace it for **all** tribes and skins, so we dont specify the style.
19+
* Lumber hut has only one level, which means we dont want to specify it.
20+
In such case, you should name it as `lumberhut__.png`
21+
22+
# Sprites
23+
Sprites file is a json file which declares advanced settings for how each texture should be transformed into the sprite. Mod sprites is declared in `sprites.json` file.
24+
25+
### Format
26+
* `pixelsPerUnit` _(optional, default `2112`)_ in Unity, a **sprite PPU** is a property that determines how many pixels from a sprite texture correspond to one unit in the Unity game world.
27+
28+
* `pivot` _(optional, default `[0.5, 0.5]`)_ in Unity, a **sprite pivot** is the reference point that determines how a sprite is positioned within the Unity game world. It acts as the point relative to which happen all movements, rotation and scaling of the sprite.
29+
30+
> [!TIP]
31+
> You can find more info in [Unity Documentation](https://docs.unity.com/).
32+
33+
### Example
34+
```json
35+
{
36+
"lumberhut__": {
37+
"pixelsPerUnit": 256,
38+
"pivot": [0.1, 0.5]
39+
}
40+
}
41+
```
42+
43+
# Prefab
44+
A prefab is a json file in a mod that describes a unit prefab. Prefabs are declared in `prefab_name.json` files (name is your prefab name).
45+
46+
### Format
47+
* `type` int value of the type of a prefab. Here is all current prefab types:
48+
```
49+
Unit,
50+
Improvement,
51+
Resource
52+
```
53+
* `name` name of your prefab
54+
* `visualParts` array of prfab's visual parts
55+
* `gameObjectName` name of the GameObject of the visual part
56+
* `baseName` sprite name of the visual part
57+
* `coordinates` position of the visual part
58+
* `rotation` _(optional, default `0`)_ rotation of the visual part
59+
* `scale` scale of the visual part
60+
* `tintable` _(optional, default `false`)_ is visual part a tint
61+
62+
### Example
63+
```json
64+
{
65+
"type": 0,
66+
"name": "Yuukwi",
67+
"visualParts": [
68+
{
69+
"gameObjectName": "Body",
70+
"baseName": "body",
71+
"coordinates": [0, 0.2],
72+
"rotation": 180,
73+
"scale": [1, 1],
74+
"tintable": false
75+
},
76+
{
77+
"gameObjectName": "Body_Tint",
78+
"baseName": "body_tint",
79+
"coordinates": [0, 0.2],
80+
"rotation": 90,
81+
"scale": [1, 1],
82+
"tintable": true
83+
}
84+
]
85+
}
86+
```

‎docs/articles/modding/toc.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
- name: Your first mod
2+
href: your-first-mod.md
3+
- name: Gld Patching
4+
href: gld.md
5+
- name: Sprites
6+
href: sprites.md
7+
- name: Localization
8+
href: localization.md
9+
- name: Polyscript
10+
href: polyscript.md
11+

‎docs/articles/modding/your-first-mod.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Creating your first mod
2+
3+
## Step 1: Setting up your environment
4+
Before you start writing mods, you should ensure you have the following:
5+
- A text editor. Notepad or Text Editor will be enough.
6+
> [!TIP]
7+
> Using a text editor meant for writing code, like [vscode](https://code.visualstudio.com/) or Kate(preinstalled on most linux distros) is a lot easier when writing and editing code. However, this isn't required.
8+
9+
[Install PolyMod.](../using/installing.md)
10+
Inside your mods folder, create a folder, e.g. `example`. If you have an IDE, open that folder with your IDE. Else, open the folder with file manager(or finder, or dolphin etc.)
11+
12+
## Step 2: Writing the manifest
13+
Create `manifest.json` and paste the following into it:
14+
```json
15+
{
16+
"id" : "my_first_mod",
17+
"name": "My first mod",
18+
"version": "1.0.0",
19+
"authors": ["your-name"],
20+
"dependencies": [
21+
{
22+
"id": "polytopia"
23+
}
24+
]
25+
}
26+
```
27+
28+
## Step 3: Creating a patch
29+
Create `patch.json` and paste the following into it:
30+
```
31+
{
32+
"unitData" : {
33+
"warrior" : {
34+
"attack" : 100
35+
}
36+
}
37+
}
38+
```
39+
This will make the warrior have a large attack value. For more information about GLD patching, see (gld.md)
40+
41+
## Step 4: loading the mod
42+
Start the game. Thats it! You should see your mod listed under the polymod hub.
43+
44+
## Step 5: publishing your mod
45+
Once you have finished your mod, you may want to bundle it into a single file for easier sharing. Here's how to do that:
46+
1. zip the folder of the mod
47+
2. rename the zipfile to `example.polymod`

‎docs/articles/toc.yml‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
- name: Introduction
22
href: introduction.md
3-
- name: Getting Started
4-
href: getting-started.md
3+
- name: Modding
4+
href: modding/toc.yml
5+
- name: Using
6+
href: using/toc.yml

0 commit comments

Comments
 (0)