Text Mods

Introduction

This documentation is intended to help you understand how to create text data mods for The Ouroboros King.
Text mods are the simplest type of mod to create, as they require no programming knowledge. If you want to create script mods, see the Script Mods documentation.

General Information

The supported file formats for text mods are YAML, JSON, and CSV. The documentation applies for all three formats, but the examples will be in YAML. See Example Formats to better understand how to format data in each format. If you are unsure which format to use, YAML is recommended for its readability and ease of use.
All properties are case-insensitive, and the order of properties does not matter. Optional properties may be omitted, but required properties must be present for the mod to work correctly. Required properties are marked in bold. Strongly recommended properties are marked in italics.

Pieces

Piece Data

Name	Type	Description	Default
id	string	The unique identifier of the piece. Has to be unique within the namespace.	[REQUIRED]
namespace	string	The namespace of the piece. This is used to identify the mod that the piece belongs to. If not specified, it will default to the mod's folder name.	(Mod Folder Name)
movement	string	The Betza's Funny Notation movement of the piece. See Pieces for more information.	[REQUIRED]
white	string	The path to the white piece's image. Relative to the mod's folder, or absolute (not recommended).	[REQUIRED]
black	string	The path to the black piece's image. Relative to the mod's folder, or absolute (not recommended).	[REQUIRED]
outline	string	The path to the piece's outline image. Relative to the mod's folder, or absolute (not recommended).	[REQUIRED]
neutral	string	The path to the neutral piece's image. Relative to the mod's folder, or absolute (not recommended).	(White Image)
description	Description or string	The description of the piece. Shown on the piece's hover menu.	(Default Description)
localizedDescription	dictionary [string,string] or dictionary [string,Description]	The localized descriptions of the piece. The key is the language code, and the value is the description.	{}
value	int	The value of the piece. This is used in the game's AI to determine the piece's worth.	0
price	int	The price of the piece in the shop.	0
playerProb	float	The probability of the piece being chosen for recruitment by the player.	0.0
enemyProb	dictionary [int,float]	The probability of the piece being chosen for drafting by the enemy. The key is the stage number, and the value is the probability.	{}
upgradeId	string	The ID of the piece that this piece upgrades to. This is ., or for vanilla pieces. Can be null for no upgrade.	null

Description

Name	Type	Description	Default
title	string	The name of the piece.	"no title"
lore	string	The lore of the piece, shown at the bottom of the piece's hover menu if movement is not shown.	"no lore"
description	string	The description of the piece.	"no description"

Note: Descriptions can also be denoted as a string separated by semicolons, with the first part being the title, the second part being the lore, and the third part being the description.

Example Piece

sentinel:
  namespace: example_mod
  movement: mQcK
  white: sentinel_w.png
  black: sentinel_b.png
  outline: sentinel_outline.png
  description:
    title: Sentinel
    lore: The Sentinel watches over the battlefield with a keen eye.
    description: Moves like a Queen, captures like a King.
  value: 6
  price: 459
  playerprob: 2
  enemyprobs:
    1: 5
    2: 5
    3: 10
    4: 10

Example Mod

For a full example of a mod with five pieces, see this Google Drive file.

Overriding Pieces

To override a vanilla piece, simply write a piece with the TOK namespace and the ID of the piece you want to override. The game will replace the properties of the vanilla piece with the properties of your piece. Properties that are not specified will be left unchanged.

Detailed Descriptions

Sprites (White, Black, Outline, Neutral)

The sprites are the images of the piece. The black and white sprites are required unless a neutral sprite is specified. The outline sprite is always required.
Using transparent PNG images of 244×244 pixels is recommended, but most common image formats are supported (PNG, JPG, BMP, etc.).
To fit the game's style, it is recommended to make the sprite as follows:

White pieces should have white fill and a black outline of ~7 pixels.
Black pieces should have black fill and a white outline of ~7 pixels. Usually just inverting the colors of the white piece is enough.
The outline should be the silhouette of the piece sprite with an outline of ~8 pixels, fully white. See the example mod under the Example Mod section for examples of sprites.

Value

The value of the piece is used by the game's AI to determine the piece's worth.
Higher values make the AI consider the piece more valuable. The AI will try protecting their own high-value pieces and capturing the opponent's high-value pieces.
The value is also used when generating the enemy army. The enemy will get assigned pieces from the pool of pieces of each stage until the total value of the pieces reaches the value limit.
See the table below for some example values of vanilla pieces.

Piece	Value
(Marching) Pawn	1
Bishop	3
Rook	5
Unicorn	7
Queen	9
Martyr	11
Dragon	14
Prince	17

See Piece Values for the full list of vanilla pieces and their values.

Price

The price of the piece is used in the player's piece shop.
Weaker pieces typically have a price of 0.
Mid-tier pieces have a price of 1-600.
Stronger pieces have a price of 601 or higher.

See Player Prices for the full list of vanilla pieces and their prices.

Player Prob

The player probability is the probability of the piece being offered to the player in the piece shop. This is the weight of the piece in the random selection of pieces, rather than a percentage. Actual probabilities may vary depending on the number of pieces and their prices.
This value is pretty much always 2 for vanilla pieces, unless a similar or related piece exists, in which case it is 1. For example, the Troll (left swing) and the Troll (right swing) have a player probability of 1.

See Player Recruit Probabilities for the full list of vanilla pieces and their player probabilities.

Enemy Probs

The enemy probabilities are the probabilities of the piece being chosen by the enemy in the army generation. This is also a weight rather than a percentage.
Due to the army generation using piece values, probabilities may not always reflect the actual chances of a piece being chosen, as high-value pieces may end up being limited due to the value cap.
This should be in the format of a dictionary, where the key is the stage number from 0 to 4, and the value is the probability of the piece being chosen. Keys that are not specified will default to 0.
Vanilla pieces typically have a probability between 0 and 20, and stronger pieces generally appear only on later stages while weaker pieces appear on all stages, but have a lower probability on the later stages.

See Enemy Draft Probabilities for the full list of vanilla pieces and their enemy probabilities.

Upgrade ID

The upgrade ID is the ID of the piece that this piece upgrades to when selected in the upgrade node.
This should be in the format of ., or for vanilla pieces. If not specified or null, the piece will not have an upgrade.

See Piece Upgrades for the full list of vanilla pieces and their upgrades.

Last modified: 14 december 2024