Mod system proposal

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.

Modules

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

• Stack experience
• Mithril (unsupported)
• Stack artifacts
• Commanders (unsupported)

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

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

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 mod.py file with newer modification date has priority and is selected for execution.

Scripting

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.

Safety

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	How to create a town mod	Mod Handler

Formats
	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