Mod system proposal

From VCMI Project Wiki
Jump to: navigation, search

This article is outdated. The current state of moding system is described in Modding guidelines

This article describes the framework of modding system which is not yet implemented. Everything stated here is a subject of discussion.

System structure

The main concepts of modding system are modules and mods of two kinds: extension packages and conversions. Managing of all mods is performed by Mod Handler.


A module refers to part of the engine that handles optional mechanics. Currently considered modules are:

Modules may be prerequisites for actual mods. The mod may require one or a number of modules to be active before it is avaliable to use. The module can be active or inactive. Activation of module in game options automatically activates or deactivates all related mods, assuming they were turned on in first place


Packages are made of Python scripts. Teir purpose is to add new conetnt to the game, such as creatures or artifacts. Packages may be dependent of modules and other packages with version greater or equal of certain number.

All packages are versioned, with version being an integer. All modders are requested to bump a version number with each update.


Conversions are also made of Python scripts. Alter original objects and behaviour of the game. They may be content replacement, alter mechanics or change graphics and sounds. Conversions may also alter bahaviour of other mods, assuming they are on their prerequsites list.

Conflict between multiple conversions trying to change the same thing should be reported by Mod Handler. In such case file with newer modification date has priority and is selected for execution.


The proposed scripting language is Python thanks to if popularity and wide array of possibilities.

Python functions use high-level callback functions of the VCMI engine to perform basic game actions or access modding engine.

Adventure map scripts

These scripts allow map designers to control game flow and alter object bahaviour. They are stored as Python file, which will be a part of new map format.

ERM scripts

To maintain compatibility with old WoG mods, all ERM functions have to be mapped into new set of Python functions. This mapping may not and will not be 1-to-1 due to acrhitecture of VCMI mechanics. Also, some unsafe functions like direct memory access will be unsupported.

ERM scripts are given their own memory space, which is equivalent of variable space of original ERM.


Calling scripts by player

Scripts online

Execution of scripts by Client is forbidden in multiplayer. Client may only send requests and replies to scripts hosted by Server.

Modding engine

Synchronising mods in multiplayer

When a client tries to join server, server send him a list of mods installed on host. Client may decide to download the mods required he doesn't have yet and configure them according to server settings. Server may be configured so it does not allow mod downloading, sending only configuration files.



Modding related articles

Main articles
Modding changelog Modding guidelines Mod Handler

Mod file Format
Town Format Creature Format Hero Classes Format
Artifact Format Animation Format Hero Format
Bonus Format Object Format Spell Format

Work-in-progress formats
Building bonuses Map format
Bonus Type Format Random map template

Outdated pages
Mod system proposal