Next Run · Mods

Next Run Mods Guide

Detailed overview of how Next Run mods work, the file structure, and game components. Bookmark this link for quick answers when creating and publishing your own mods.

1. General

This document describes the mod system in Next Run: how to install mods, create your own, and share them with other players.

Read Section 2 at least once to understand how mods are created and how they work.
Use Sections 3 and 4 as reference materials.
Use the in-game examples to see how this works in practice in Steam Workshop: https://steamcommunity.com/app/1295870/workshop/.
Game files for version 1.1.0 can be found here: https://clarusvictoria.com/files/next_run_files_examples_1.1.0.zip.

2. Mod system

After launching the game and clicking "Play" and "Create game", the Mods folder inside the game directory is scanned. Each subfolder in this directory is considered a mod if it contains a modinfo.json file.

2.1. Steam Workshop, installation, and publishing mods

If you launch the game from the Steam client, the "Play" menu provides a "Mods" panel with the following buttons:

Steam Workshop
Mods folder
Publish
Manual

2.1.1. Steam Workshop

Opens Steam Workshop inside the Steam client. Subscribe to a mod to download it. Downloading starts automatically; if a mod is large, it may take some time. The download status is shown in the Steam client.

2.1.2. Mods folder

Opens your game's Mods folder.

2.1.3. Publish

The game automatically scans the Mods folder and publishes all mods that list you as the author to Steam Workshop.

If a mod is new, a steam_id is generated automatically.
If a mod already exists, it is updated.
The publish button changes appearance while uploading.
A mod is published only if content has changed.
Changing the modinfo.json file does not count as content change.
Published mods become available to players worldwide. Steam Workshop is not the only way to distribute mods—you can also share them directly by placing the mod folder in the Mods directory.

2.1.4. Manual

Link to this manual.

2.2. JSON files

All data and text in the game use JSON. Unlike plain text, the data must be wrapped in curly braces {}.

JSON syntax references:

We recommend following the file examples from the game.

2.3. File structure

Each mod follows the game's folder structure. These files either add new content or change the existing game content. You cannot remove game content, but you can replace it.

Example: if you create a data/game.json file and change the "Warrior" entity (a game class), only Warrior is changed, while the rest of the entities from the game remain.

A mod contains required and optional files and folders. The standard structure looks like this:

modinfo.json
preview.png
data
icons
sounds
texts
tiles
{other files and folders}

For better understanding, review the in-game examples and existing mods. Below is a detailed description of every file and folder:

2.3.1. modinfo.json

Metadata file for a mod. Some of these fields are used by Steam Workshop during publishing.

title — mod name displayed in Steam.
version — mod version.
description — mod description.
tags — tags for navigating Steam Workshop.
order — load order for mods. If multiple mods change the same data, the mod with the higher order overwrites the one with the lower value.
steam_id — no need to specify manually; generated automatically when publishing.
created_time — creation time.
changed_time — modification time.
Other fields can be added, but they will only be used inside the file. The mod author is determined automatically through Steam Workshop.

2.3.2. preview.png

Preview image (icon) for Steam Workshop. Recommended resolution: 256x256 or 512x512. Aspect ratio must be square. Transparent PNG or JPG is allowed.

2.3.3. data

Folder with JSON data files. Contains files that change existing game entities or add new ones. You can delete files from this folder if you want to keep default game content.

2.3.4. icons

Folder with game icons. Stores most images except GUI and tiles. Several standard sizes are used: 256x256, 128x128, 64x64, and 44x44.

2.3.5. sounds

Folder with sounds and music. You can add new files or replace existing ones. Use the OGG format.

2.3.6. texts

Folder with localized game text. Each file corresponds to one language and uses the IETF BCP-47 / ISO standard. Name the files using the format {lang}.json, for example en-US.json.

2.3.7. tiles

Folder with tile images. Uses PNG files with transparent backgrounds. Standard tile size is 256x384. Tiles are put together into atlases with gaps that depend on atlas parameters.

2.4. Mod synchronization

After obtaining a mod, it is automatically synchronized with the latest version published on the Steam Workshop every time the game launches.

If you are the mod's author, synchronization is skipped and the mod files are not overwritten. This prevents your changes from being lost after restarting the game.

If you want to create a mod based on someone else's mod, do the following before restarting the game:

Change the mod folder name to any other name different from its id.
In the modinfo.json file, remove the fields: "author", "created_time", "steam_id", "changed_time".

2.5. Data merging

JSON data files from mods and the base game are merged rather than replaced.

Merge order:

Original entities from the game's JSON files are taken as the base.
Mod data is applied on top. Mods are applied according to the priorities set by the order field in modinfo.json.

During merging, every field of every component is processed separately. For example, if an entity has "hideIfZero":true and you need it to become false, removing the field is not enough—you must explicitly set "hideIfZero":false.

Lists in list.json are merged the same way. You don't need to duplicate each list with all fields if you're adding only one entry. However, lists that contain only simple data are completely replaced, such as RndGoodEvents and RndEvents.

3. Components

Next Run is built on an ECS architecture. The entire game consists of entities. An entity is a container for components and only stores an id field. All other data is described by components. All data is defined in JSON files.

Example entry in a JSON file:

"Speed": {
    "Button": {"panel": "statsPanel","iconType": "btnBig","numText1Type": "total","icon": "arrow2"},
    "Tooltip": {"text": "Speed"},
    "Total": {"now": 25}
}

This example describes the entity "Speed" with three components: Button — defines the appearance and behavior of the in-game button; Tooltip — the tooltip description; Total — the numerical value of the entity, in this case the speed is 25.

Below is a more detailed description of the components and their fields. Some properties are set automatically and cannot be edited in JSON files. For example, the difficulty of clearing dungeons depends on the level and other parameters calculated by the game.

3.1. Button

Describes the appearance and behavior of a button in the game.

panel = string, default button panel. All buttons in the game are inside panels and menus. Use the examples to choose the panel where you want to place your button.
icon = string, button icon name. The name matches a PNG file in the icons folder.
iconType = string, button type that affects button size and elements. Options: "btn" — simple button, "btnBig" — button with the value below.
color = string, icon background color, for example green, yellow. Colors recognized by the game: green, superGreen, lightGreen, darkGreen, red, superRed, darkRed, gray, lightGray, darkGray, lightBlue, blue, darkBlue, darkDarkBlue, grayYellow, yellow, pink, cyan, darkCyan, almostBlack, black, orange, darkOrange, lightViolet, purple, chartreuse, num, gameBack, blank, halfTrans, white, base.
numText1 = double, icon value.
numTextAdd = string, suffix for the icon value, for example the "%" symbol.
numText1Type = string, icon value type, for example level, total, duration.
numCustom = string, custom icon value, for example "∞".
numIcon = string, icon next to the value, for example star for levels, coin for items.
hotkey = string, keyboard hotkey.
hide = bool, whether the button is hidden.
hideIfZero = bool, hides the button if the Total.now field is 0.
disabled = bool, whether the button is disabled or enabled; some menus at the start of the game are disabled.
interactable = bool, whether the button is interactive (yes by default). Example of non-interactive buttons: inventory slots.
cantBeDeselect = bool, prevents removing the selection from this button.
cantBeSelect = bool, prevents selecting the button when clicking it.
draggable = bool, whether the button can be moved using drag'n drop.
x = double, X position of the interface for buttons without panels, such as inventory slots.
y = double, like X but for the Y position.
upMiniPred = string, name of the action checked for this entity. If the action is available, an improvement-style mini hint icon appears.
craftMiniPred = string, similar hint for the Craft action.
raiseMiniPred = string, similar hint for the Raise action.

3.3. GameClass

Describes class mechanics.

text = string, class name in the game.
portrait_back = string, background image when choosing a class (391x598).
portrait_front = string, transparent class image when choosing a class (411x620).
figurine = string, character avatar image on the map (149x243).
doll = string, grayscale class image in the inventory (460x784).
bonusSkill1 = string, name of the skill that receives bonus 1.
bonusSkillVal1 = double, size of bonus 1.
bonusSkill2 = string, name of the skill that receives bonus 2.
bonusSkillVal2 = double, size of bonus 2.
debuffSkill1 = string, name of the skill that receives penalty 1.
debuffSkillVal1 = double, size of penalty 1.
debuffSkill2 = string, name of the skill that receives penalty 2.
debuffSkillVal2 = double, size of penalty 2.
gold = double, amount of gold the class starts with.
remains = double, number of remains at the start.
equip = List<string>, list of items to equip at the start.
units = string, name of the creature available at the start.
itemName = string, name of the item in the starting inventory.
itemNum = double, quantity of the inventory item at the start.
learnList = string, list of spells or blueprints to learn; the list is stored in list.json.
learnNum = double, number of spells or blueprints to be learned from the list.
lessTime = double, how much less time there is between hell attacks.
manaBonus = double, mana bonus (maximum and total).
upgradeDexterityBonusMod = double, bonus to upgradeable items from the Dexterity skill.
skillPointsPerLevel = double, number of skill points granted when leveling up.
upgradeManaCostMod = double, efficiency bonus for upgrading spells.
freeRegion = bool, free region.
necroBonus = bool, Necromancer gameplay and bonuses.
druidBonus = bool, Druid gameplay and bonuses.
stances = bool, availability of stances/forms/orders.
defStance = string, default stance.
notDemo = bool, class unavailable in the demo.
notTutorial = bool, whether the class is available in Tutorial mode.

3.4. GameMode

Describes game mode mechanics.

text = string, mode name in the game.
back = string, background image when choosing the mode (391x598).
moreTime = double, how much more time there is between hell attacks.
lessTime = double, how much less time there is between hell attacks.
woundChance = double, chance to receive a wound.
notDemo = bool, mode unavailable in the demo.
scenario = string, name of the dedicated map for this mode.
noHellAttacks = bool, no hell attacks in this mode (like in sandbox).
savesOnExitOnly = bool, in this mode the game only saves on exit.

3.5. Biome

Defines biome mechanics.

panel = string, panel name.
icon = string, icon name.
iconBg = string, icon background.
color = string, icon background color.
desc = string, biome description.

3.6. TileAsset

Defines how an object looks on the game map.

icon = string, tile image name.
icon2 = string, the second tile image name, selected with probability pctIcon2.
pctIcon2 = double, probability of selecting icon2.
iconType = string, icon size.
iconOffset = double, vertical icon offset.

3.7. Shop

Describes shop mechanics.

panel = string, panel name.
icon = string, icon name.

3.8. Item

Describes item mechanics.

slot = string, equipment slot name.
stackable = bool, whether more than 1 item can be in a single stack.
upgradable = bool, whether the item can be upgraded; upgrade duration depends on the Level.
upProgress = double, upgrade duration.
order = double, item ordering in the shop; the smaller the value, the higher it appears.

3.9. Mob

Describes creature mechanics.

panel = string, panel name.
icon = string, icon name.
iconBg = string, icon background.
desc = string, description.
descPlus = string, additional description.
race = string, creature race name.

3.10. Dungeon

Describes dungeon mechanics.

panel = string, panel name.
icon = string, dungeon icon.

3.11. Ruins

Describes the mechanics of ruins—locations for searching items.

3.12. Addon

Extension mechanics. Addons are objects located on a tile with a dungeon or ruins that change their parameters and grant separate rewards.

skill = string, the name of the skill gained after clearing the dungeon or inspecting the ruins. You can set "Random", "Strength", etc.
unit = string, the name of the bonus unit after finishing the action. You can set "Random".
item = string, the name of the bonus item after finishing the action. You can set "Random".
phyChanceMulti = double, modifier to the chance of physical damage during Clearing. For example by 50(%).
magChanceMulti = double, modifier to the chance of magical damage during Clearing. For example by 50(%).
progressMulti = double, how much longer a Clearing or Inspection-type action takes. For example by 100(%).
dmgMulti = double, modifier to damage amount during Clearing. For example by 50(%).

3.13. Build

Defines that this object is a building.

3.14. Center

Defines that this object is a settlement.

captureProgress = double, effort required to capture the settlement.
upProgress = double, effort required to upgrade the settlement.
upCostName1 = string, name of item 1 required for the upgrade.
upCostNum1 = double, amount of item 1 required for the upgrade.
upCostName2 = string, same for item 2.
upCostNum2 = double, same for item 2.
upCostName3 = string, same for item 3.
upCostNum3 = double, same for item 3.
upProp = string, which settlement it upgrades into.

3.15. Gatherable

Defines that this object can be gathered to obtain resources.

gather = string, the resource name that will be gathered.
deposit = bool, whether this resource is a deposit; if yes, a mine can be built here.

3.16. AlliedForest

Defines the mechanics and values of the 'allied forest' when playing as a druid.

allyBonus = double, the size of the "Allied Forest" bonus.

3.17. Graveyard

Defines that this object is a graveyard, which matters when playing as the Necromancer. The value is generated randomly for each map tile.

panel = string, panel name.
icon = string, icon name.
chance = double, probability that a tile is a graveyard.
level = int, average level of mobs on a graveyard tile.

3.18. Pred

Action component. Most of its functionality lives in code, but part of it is available.

action = string, name of the action that triggers when the interaction runs.
local = bool, whether you must be on the same tile as the object to interact.
attackPred = bool, this is an offensive action and triggers automatically when a combat spell is used.
gatherPred = bool, this is a gathering action and triggers automatically when a resource-gathering spell is used.
craftPred = bool, this is a crafting action and triggers automatically when a crafting spell is used.
skill = string, the skill used to perform the action; for offensive actions, the Attack skill is used.
longPred = bool, this action is not instantaneous and takes time.
repeat = bool, the action repeats until stopped.
noOwner = bool, this action does not require selecting any objects.
skipLongTooltip = bool, simplified tooltip version for the action.
onlyClass = string, this stance/form/order action is available only to a specific class.

3.19. Total

Component that defines the numerical value of an entity, usually a quantity.

now = double, base value.
nowRnd = double, bonus randomly generated on each new map tile.
val2 = double, secondary value used depending on the entity type.
min = double, minimum value.
max = double, maximum value.
min2 = double, minimum secondary value.
max2 = double, maximum secondary value.
need = double, Needed amount, for example the growth needed to reach the next population level.
level = double, region level for map tiles.
captureProgress = double, effort required to capture a settlement.

3.20. Level

Component that defines an entity’s level.

now = double, base level value.
max = double, maximum level value.
scale = double, scaling parameter.
level = double, level parameter.

3.21. Duration

Component that defines how long an entity lasts.

now = double, current duration.
max = double, maximum duration.
recovery = double, recovery speed.
total = double, full recovery time.

3.22. Mods

Modifier list component. When created, it forms a set of changes that affect other entities. When the entity is removed, these changes disappear.

radius = int, radius affected by the modification; works only on the map.
objType = string, type of entities affected by the modification, e.g., "Stat", "Skill", "Prop", "Item", "ModableVal", "PropMod".
objName = string, entity name, such as "Speed".
objComp = string, component affected by the modification, such as "Total" or "Level".
objKey = string, component field affected by the modification, such as "now", "inc", or "max".
modType = string, way the field is affected: "add", "mult", "addPerLevel", "multPerLevel".
now = double, modifier value applied to the change.
subjTooltipText = string, adds subject information to the dynamic tooltip.
skipPerTooltip = bool, replace PerLevel with Plus in the tooltip.
skipSubjTooltip = bool, skip the tooltip for this subject.

3.23. ModableVals

List component of global game variables. The link to a specific entity is conditional. Most logic for this component is hard-coded.

factionRes = double, +10% to resource acquisition for every 10 levels of reputation.

3.24. Slot

Component that defines an entity as an inventory slot.

cells = int, number of cells in the container.

3.25. Container

Defines this entity as a container with cells.

cells = int, number of cells in the container.
cellsPanel = string, name of the panel.

3.26. Tom

Defines that this entity is a spell tome that can be studied to gain or upgrade a spell.

cast = string, name of the spell that appears after studying the book.

3.27. Cast

Defines that the entity is a spell.

mana = double, mana cost of the spell.
predSkill = string, which type of actions to trigger when this spell is activated; Attack-type spells automatically trigger offensive actions.
notSkills = string, hint for which action is needed to use this spell.
attack = double, how much this spell speeds up an Attack-type action; effectively magic damage.
gather = double, how much faster a Gather Resources action becomes.
craft = double, how much faster a Craft action becomes.
heal = double, how much the player's hero is healed.
newEvent = string, name of the event the spell triggers, usually buff-type events.
teleport = bool, teleports to the selected location.
explore = double, explores this tile and neighboring tiles.

3.28. Blueprint

Blueprint entity mechanics.

panel = string, panel name.
icon = string, icon name.
iconBg = string, icon background.
build = string, name of the building that will be constructed.
costName1 = string, name of the first needed item.
costNum1 = double, quantity of the first needed item.
costName2 = string, name of the second needed item.
costNum2 = double, quantity of the second needed item.

3.29. Cost

Price component indicating that the entity can be bought and sold.

cost = double, how many resources the item can be sold for.

3.30. Event

Component for events.

chance = double, probability of the event.
eventType = string, event type.
eventMobs = string, entity that will spawn with this event.
locType = string, probability of the event happening for a location type such as forest, mountains, oasis, and other game tile types.
level = double, event level.

3.31. Proc

Component for procs (chances), such as the chance to get a disease.

chance = double, chance of triggering this effect.

3.32. ProcMod

Component that lets an entity influence proc chances.

chance = double, chance modifier.
addEvent = string, event that fires if the chance triggers.
addProc = string, component that triggers if the chance succeeds.

3.33. Usable

Single-use components that give an effect, such as potions. The component is triggered when performing an action with it equipped, usually Attack or Craft actions.

chance = double, chance to obtain.
gatherPred = bool, whether it can be used for a Gathering_reses action.
spawn = string, name of the icon and total, for example Allied_forest.
cure = bool, whether the item cures the Disease effect.
res = string, resource name, for example Forest.

3.34. Drankable

Component that lets the player drink the object on the map, such as Lake, Oasis, and similar tiles.

3.35. Sphinx

Quest component on the map: Sphinx. Parameters are determined automatically based on region levels.

3.36. Living_tree

Quest component on the map: Living tree. Parameters are determined automatically based on region levels.

3.37. Vision

Mechanic for a map object that increases the revealed area when the player’s hero enters the location with the entity.

vision = double, the size of the additional visible area.

3.38. Remains

Defines the entity as remains. Allows these entities to be turned into undead.

3.39. Audio_comp

Component that plays sounds for a specific entity depending on its type.

added = string, sound played when the entity is created, used for events.
click = string, sound when clicking the entity, used for actions and spells.
ambient1 = string, ambient sound track 1.
ambient2 = string, ambient sound track 2.
ambient3 = string, ambient sound track 3.
gatherPred = string, Gathering_reses action sound.
searchPred = string, search action sound.
attackPred = string, attack action sound.
craftPred = string, crafting sound.

3.40. Childs

Component that recursively creates new entities.

childs = string, name of the generated entity.

3.41. Preds

Component that creates actions for a specific entity, though most entities are defined in the game code.

preds = string, name of the action for this entity.

3.42. Equip

Tag component meaning this item can be equipped on the hero.

3.43. Res

Indicator component marking the entity as a resource. Needed for tooltips, animations, and game summaries.

3.44. TurnAct

Component means the entity must be checked each game tick, for example for Total and Duration components.

4. Lists

The list.json file contains data sections that are not entities or components. They define various lists for generating game content.

4.1. RndGoodEvents

List of positive random events generated right after the game starts.

4.2. RndEvents

List of positive and negative random events generated during the game.

4.3. Generator_dungeon_addons_physical

List of addons generated for dungeons with physical damage.

4.4. Generator_dungeon_addons_magical

List of addons generated for dungeons with magical damage.

4.5. Generator_ruins_addons

List of addons generated for ruins.

4.6. Generator_settlement_levels

Mapping between region levels and settlement entity names, e.g., "lvl1":"Village" means a level 1 region will generate a Village-type settlement.

4.7. Generator_rar_metals

Mapping between region levels and deposit names, e.g., "lvl2":"Deposit_tin" means a tin deposit will be generated in a level 2 region.

4.8. Generator_mages

Mapping between region levels and mages that will be generated to guard mage towers, e.g., "lvl3":"Priestesses" means priestesses appear in level 3 regions.

4.9. LevelMobs_

Lists of creatures for different region levels that the player receives after freeing prisoners when clearing dungeons or inspecting ruins.

4.10. Crafter_start, Lord_start, Mage_start,

Various lists of items that different game classes receive at the start in the GameClass component's learnList field. The number of items generated is set in learnNum.

obj = string, the item name.
min = double, minimum random number.
max = double, maximum random number.
chance = double, chance to generate this specific item.
You can create other lists and link them to different classes if you need to learn other blueprints or spells.

4.11. Gold_

This list defines the amount of generated gold depending on region level. Gold appears with a 50% chance in all types of map rewards. See point 4.10 for syntax.

4.12. Loot_-

A group of lists that defines reward generation depending on region level. Applied to creatures, dungeons, and ruins. For creatures it sets the chance of dropping specific items with a 50% chance; the remaining 50% uses the lists from point 4.13. See point 4.10 for syntax.

4.13. Warriors_, Defenders_, Mages_, Gatherers_, Crafters_,

A group of lists that defines reward generation depending on region level and creature class. Applied only to creatures. These lists extend Loot_- and trigger in 50% of cases to generate class-specific rewards, for example when you want mages to drop tomes and staves more often. See point 4.10 for syntax.

4.14. Shop_, Books_

Lists for different region levels, e.g., Books5 or Shop6. Used to generate store assortments. See point 4.10 for syntax. These lists are defined in the Shop component's type field; for towers they are generated from game code.