guardingCreatures(int3 pos) const;
+```
+
+## Sources
+
+[Mono project coding guidelines](http://www.mono-project.com/Coding_Guidelines)
\ No newline at end of file
diff --git a/docs/conan.md b/docs/developers/Conan.md
similarity index 56%
rename from docs/conan.md
rename to docs/developers/Conan.md
index 352085f5d..d592ef26e 100644
--- a/docs/conan.md
+++ b/docs/developers/Conan.md
@@ -1,3 +1,5 @@
+< [Documentation](../Readme.md) / Using Conan
+
# Using dependencies from Conan
[Conan](https://conan.io/) is a package manager for C/C++. We provide prebuilt binary dependencies for some platforms that are used by our CI, but they can also be consumed by users to build VCMI. However, it's not required to use only the prebuilt binaries: you can build them from source as well.
@@ -8,12 +10,10 @@ The following platforms are supported and known to work, others might require ch
- **macOS**: x86_64 (Intel) - target 10.13 (High Sierra), arm64 (Apple Silicon) - target 11.0 (Big Sur)
- **iOS**: arm64 - target 12.0
-- **Windows**: x86_64 and x86 fully supported with building from Linux
-- **Android**: armeabi-v7a (32-bit ARM) - target 4.4 (API level 19), aarch64-v8a (64-bit ARM) - target 5.0 (API level 21)
## Getting started
-1. [Install Conan](https://docs.conan.io/en/latest/installation.html). Currently we support only Conan v1, you can install it with `pip` like this: `pip3 install 'conan<2.0'`
+1. [Install Conan](https://docs.conan.io/en/latest/installation.html)
2. Execute in terminal: `conan profile new default --detect`
## Download dependencies
@@ -22,45 +22,36 @@ The following platforms are supported and known to work, others might require ch
1. Check if your build environment can use the prebuilt binaries: basically, that your compiler version (or Xcode major version) matches the information below. If you're unsure, simply advance to the next step.
- - **macOS**: libraries are built with Apple clang 14 (Xcode 14.2), should be consumable by Xcode and Xcode CLT 14.x (older library versions are also available for Xcode 13, see Releases in the respective repo)
- - **iOS**: libraries are built with Apple clang 14 (Xcode 14.2), should be consumable by Xcode 14.x (older library versions are also available for Xcode 13, see Releases in the respective repo)
- - **Windows**: libraries are built with x86_64-mingw-w64-gcc version 10 (which is available in repositories of Ubuntu 22.04)
- - **Android**: libraries are built with NDK r25c (25.2.9519653)
+ - macOS: libraries are built with Apple clang 13 (Xcode 13.4.1), should be consumable by Xcode and Xcode CLT 13.x
+ - iOS: libraries are built with Apple clang 13 (Xcode 13.4.1), should be consumable by Xcode 13.x
2. Download the binaries archive and unpack it to `~/.conan` directory:
- [macOS](https://github.com/vcmi/vcmi-deps-macos/releases/latest): pick **intel.txz** if you have Intel Mac, otherwise - **intel-cross-arm.txz**
- [iOS](https://github.com/vcmi/vcmi-ios-deps/releases/latest)
- - [Windows](https://github.com/vcmi/vcmi-deps-windows-conan/releases/latest): pick **vcmi-deps-windows-conan-w64.tgz**
- if you want x86, otherwise pick **vcmi-deps-windows-conan.tgz**
- - [Android](https://github.com/vcmi/vcmi-dependencies/releases)
-3. Only if you have Apple Silicon Mac and trying to build for macOS or iOS:
-
- 1. Open file `~/.conan/data/qt/5.15.x/_/_/export/conanfile.py` (`5.15.x` is a placeholder), search for string `Designer` (there should be only one match), comment this line and the one above it by inserting `#` in the beginning, and save the file.
- 2. (optional) If you don't want to use Rosetta, follow [instructions how to build Qt host tools for Apple Silicon](https://github.com/vcmi/vcmi-ios-deps#note-for-arm-macs), on step 3 copy them to `~/.conan/data/qt/5.15.x/_/_/package/SOME_HASH/bin` (`5.15.x` and `SOME_HASH` are placeholders). Make sure **not** to copy `qt.conf`!
+3. Only if you have Apple Silicon Mac and trying to build for macOS or iOS: follow [instructions how to build Qt host tools for Apple Silicon](https://github.com/vcmi/vcmi-ios-deps#note-for-arm-macs), on step 3 copy them to `~/.conan/data/qt/5.15.x/_/_/package/SOME_HASH/bin` (`5.15.x` and `SOME_HASH` are placeholders).
## Generate CMake integration
Conan needs to generate CMake toolchain file to make dependencies available to CMake. See `CMakeDeps` and `CMakeToolchain` [in the official documentation](https://docs.conan.io/en/latest/reference/conanfile/tools/cmake.html) for details.
-In terminal `cd` to the VCMI source directory and run the following command. Also check subsections for additional requirements on consuming prebuilt binaries.
+In terminal `cd` to the VCMI source directory and run the following command. If you want to download prebuilt binaries from ConanCenter, also read the [next section](#using-prebuilt-binaries-from-conancenter).
-
+```sh
conan install . \
--install-folder=conan-generated \
--no-imports \
--build=never \
--profile:build=default \
--profile:host=CI/conan/PROFILE
-
+```
The highlighted parts can be adjusted:
- ***conan-generated***: directory (absolute or relative) where the generated files will appear. This value is used in CMake presets from VCMI, but you can actually use any directory and override it in your local CMake presets.
- ***never***: use this value to avoid building any dependency from source. You can also use `missing` to build recipes, that are not present in your local cache, from source.
-- ***CI/conan/PROFILE***: if you want to consume our prebuilt binaries, ***PROFILE*** must be replaced with one of filenames from our [Conan profiles directory](../CI/conan) (determining the right file should be straight-forward). Otherwise, either select one of our profiles or replace ***CI/conan/PROFILE*** with `default` (your default profile).
-- ***note for Windows x86***: use profile mingw32-linux.jinja for building instead of mingw64-linux.jinja
+- ***CI/conan/PROFILE***: if you want to consume our prebuilt binaries, ***PROFILE*** must be replaced with one of filenames from our [Conan profiles directory](../../CI/conan) (determining the right file should be straight-forward). Otherwise, either select one of our profiles or replace ***CI/conan/PROFILE*** with `default` (your default profile).
If you use `--build=never` and this command fails, then it means that you can't use prebuilt binaries out of the box. For example, try using `--build=missing` instead.
@@ -68,10 +59,6 @@ VCMI "recipe" also has some options that you can specify. For example, if you do
_Note_: you can find full reference of this command [in the official documentation](https://docs.conan.io/en/latest/reference/commands/consumer/install.html) or by executing `conan help install`.
-### Using our prebuilt binaries for macOS/iOS
-
-We use custom recipes for some libraries that are provided by the OS. You must additionally pass `-o with_apple_system_libs=True` for `conan install` to use them.
-
### Using prebuilt binaries from ConanCenter
First, check if binaries for [your platform](https://github.com/conan-io/conan-center-index/blob/master/docs/supported_platforms_and_configurations.md) are produced.
@@ -81,25 +68,6 @@ You must adjust the above `conan install` command:
1. Replace ***CI/conan/PROFILE*** with `default`.
2. Additionally pass `-o default_options_of_requirements=True`: this disables all custom options of our `conanfile.py` to match ConanCenter builds.
-### Building dependencies from source
-
-This subsection describes platform specifics to build libraries from source properly.
-
-#### Building for macOS/iOS
-
-- To build Locale module of Boost in versions >= 1.81, you must use `compiler.cppstd=11` Conan setting (our profiles already contain it). To use it with another profile, either add this setting to your _host_ profile or pass `-s compiler.cppstd=11` on the command line.
-- If you wish to build dependencies against system libraries (like our prebuilt ones do), follow [below instructions](#using-recipes-for-system-libraries) executing `conan create` for all directories. Don't forget to pass `-o with_apple_system_libs=True` to `conan install` afterwards.
-
-#### Building for Android
-
-Android has issues loading self-built shared Zlib library because binary name is identical to the system one, so we enforce using the OS-provided library. To achieve that, follow [below instructions](#using-recipes-for-system-libraries), you only need `zlib` directory.
-
-##### Using recipes for system libraries
-
-1. Clone/download https://github.com/kambala-decapitator/conan-system-libs
-2. Execute `conan create PACKAGE vcmi/apple`, where `PACKAGE` is a directory path in that repository. Do it for each library you need.
-3. Now you can execute `conan install` to build all dependencies.
-
## Configure project for building
You must pass the generated toolchain file to CMake invocation.
@@ -113,14 +81,13 @@ In these examples only the minimum required amount of options is passed to `cmak
### Use our prebuilt binaries to build for macOS x86_64 with Xcode
-```
+```sh
conan install . \
--install-folder=conan-generated \
--no-imports \
--build=never \
--profile:build=default \
- --profile:host=CI/conan/macos-intel \
- -o with_apple_system_libs=True
+ --profile:host=CI/conan/macos-intel
cmake -S . -B build -G Xcode \
--toolchain conan-generated/conan_toolchain.cmake
@@ -130,7 +97,7 @@ cmake -S . -B build -G Xcode \
If you also want to build the missing binaries from source, use `--build=missing` instead of `--build=never`.
-```
+```sh
conan install . \
--install-folder=~/my-dir \
--no-imports \
@@ -145,14 +112,13 @@ cmake -S . -B build \
### Use our prebuilt binaries to build for iOS arm64 device with custom preset
-```
+```sh
conan install . \
--install-folder=~/my-dir \
--no-imports \
--build=never \
--profile:build=default \
- --profile:host=CI/conan/ios-arm64 \
- -o with_apple_system_libs=True
+ --profile:host=CI/conan/ios-arm64
cmake --preset ios-conan
```
@@ -181,28 +147,3 @@ cmake --preset ios-conan
]
}
```
-
-### Build VCMI with all deps for 32-bit windows in Ubuntu 22.04 WSL
-```powershell
-wsl --install
-wsl --install -d Ubuntu
-ubuntu
-```
-Next steps are identical both in WSL and in real Ubuntu 22.04
-```bash
-sudo pip3 install conan
-sudo apt install cmake build-essential
-sed -i 's/x86_64-w64-mingw32/i686-w64-mingw32/g' CI/mingw-ubuntu/before-install.sh
-sed -i 's/x86-64/i686/g' CI/mingw-ubuntu/before-install.sh
-sudo ./CI/mingw-ubuntu/before-install.sh
-conan install . \
- --install-folder=conan-generated \
- --no-imports \
- --build=missing \
- --profile:build=default \
- --profile:host=CI/conan/mingw32-linux \
- -c tools.cmake.cmaketoolchain.presets:max_schema_version=2
-cmake --preset windows-mingw-conan-linux
-cmake --build --preset windows-mingw-conan-linux --target package
-```
-After that, you will have functional VCMI installer for 32-bit windows.
diff --git a/docs/developers/Development_with_Qt_Creator.md b/docs/developers/Development_with_Qt_Creator.md
new file mode 100644
index 000000000..d7a481c14
--- /dev/null
+++ b/docs/developers/Development_with_Qt_Creator.md
@@ -0,0 +1,26 @@
+< [Documentation](../Readme.md) / Development with Qt Creator
+
+# Introduction to Qt Creator
+
+Qt Creator is the recommended IDE for VCMI development on Linux distributions, but it may be used on other operating systems as well. It has the following advantages compared to other IDEs:
+
+- Fast parser/indexer, stable.
+- Almost no manual configuration when used with CMake. Project configuration is read from CMake text files,
+- Easy to setup and use with multiple different compiler toolchains: GCC, Visual Studio, Clang
+
+You can install Qt Creator from repository, but better to stick to latest version from Qt website: https://www.qt.io/download-qt-installer-oss
+
+## Configuration
+
+To open the project you have to click File -\> Open file or project... -\> Select /path/to/vcmi/src/CMakeLists.txt.
+
+For the first time and for every CMake project configuration change you have to execute CMake. This step can be done when opening the project for the first time or alternatively via the left bar -\> Projects -\> Build Settings -\> Execute CMake. You have to specify CMake arguments and the build dir. CMake arguments can be the following: `-DCMAKE_BUILD_TYPE=Debug`
+
+The build dir should be set to something like /trunk/build for the debug build and /trunk/buildrel for the release build. For cleaning the build dir a command like "make clean" may be not enough. Better way is to delete the build dir, re-create it and re-execute CMake. Steps for cleaning can be configured in the Projects tab as well.
+
+## Debugging
+
+There is a problem with QtCreator when debugging both vcmiclient and vcmiserver. If you debug the vcmiclient, start a game, attach the vcmiserver process to the gdb debugger(Debug \> Start Debugging \> Attach to Running External Application...) then breakpoints which are set for vcmiserver will be ignored. This looks like a bug, in any case it's not intuitively. Two workarounds are available luckily:
+
+1. Run vcmiclient (no debug mode), then attach server process to the debugger
+2. Open two instances of QtCreator and debug vcmiserver and vcmiclient separately(it works!)
\ No newline at end of file
diff --git a/docs/developers/Logging_API.md b/docs/developers/Logging_API.md
new file mode 100644
index 000000000..65ea11ea0
--- /dev/null
+++ b/docs/developers/Logging_API.md
@@ -0,0 +1,163 @@
+< [Documentation](../Readme.md) / Logging System
+
+# Features
+
+- A logger belongs to a "domain", this enables us to change log level settings more selectively
+- The log format can be customized
+- The color of a log entry can be customized based on logger domain and logger level
+- Logger settings can be changed in the settings.json file
+- No std::endl at the end of a log entry required
+- Thread-safe
+- Macros for tracing the application flow
+- Provides stream-like and function-like logging
+
+# Class diagram
+
+
+
+Some notes:
+
+- There are two methods `configure` and `configureDefault` of the class `CBasicLogConfigurator` to initialize and setup the logging system. The latter one setups default logging and isn't dependent on VCMI's filesystem, whereas the first one setups logging based on the user's settings which can be configured in the settings.json.
+- The methods `isDebugEnabled` and `isTraceEnabled` return true if a log record of level debug respectively trace will be logged. This can be useful if composing the log message is a expensive task and performance is important.
+
+# Usage
+
+## Setup settings.json
+
+``` javascript
+{
+ "logging" : {
+ "console" : {
+ "threshold" : "debug",
+ "colorMapping" : [
+ {
+ "domain" : "network",
+ "level" : "trace",
+ "color" : "magenta"
+ }
+ ]
+ },
+ "loggers" : [
+ {
+ "domain" : "global",
+ "level" : "debug"
+ },
+ {
+ "domain" : "ai",
+ "level" : "trace"
+ }
+ ]
+ }
+}
+```
+
+The above code is an example on how to configure logging. It sets the log level to debug globally and the log level of the domain ai to trace. In addition, it tells the console to log debug messages as well with the threshold attribute. Finally, it configures the console so that it logs network trace messages in magenta.
+
+## Configuration
+
+The following code shows how the logging system can be configured:
+
+```cpp
+ console = new CConsoleHandler;
+ CBasicLogConfigurator logConfig(VCMIDirs::get().localPath() + "/VCMI_Server_log.txt", console);
+ logConfig.configureDefault(); // Initialize default logging due to that the filesystem and settings are not available
+ preinitDLL(console); // Init filesystem
+ settings.init(); // Init settings
+ logConfig.configure(); // Now setup "real" logging system, overwrites default settings
+```
+
+If `configureDefault` or `configure` won't be called, then logs aren't written either to the console or to the file. The default logging setups a system like this:
+
+**Console**
+
+Format: %m
+Threshold: info
+coloredOutputEnabled: true
+
+colorMapping: trace -\> gray, debug -\> white, info -\> green, warn -\> yellow, error -\> red
+
+**File**
+
+Format: %d %l %n \[%t\] - %m
+
+**Loggers**
+
+global -\> info
+
+## How to get a logger
+
+There exist only one logger object per domain. A logger object cannot be copied. You can get access to a logger object by using the globally defined ones like `logGlobal` or `logAi`, etc... or by getting one manually:
+```cpp
+Logger * logger = CLogger::getLogger(CLoggerDomain("rmg"));
+```
+
+## Logging
+
+Logging can be done via two ways, stream-like or function-like.
+
+```cpp
+ logGlobal->warnStream() << "Call to loadBitmap with void fname!";
+ logGlobal->warn("Call to loadBitmap with void fname!");
+```
+
+Don't include a '\n' or std::endl at the end of your log message, a new line will be appended automatically.
+
+The following list shows several log levels from the highest one to the lowest one:
+
+- error -\> for errors, e.g. if resource is not available, if a initialization fault has occured, if a exception has been thrown (can result in program termination)
+- warn -\> for warnings, e.g. if sth. is wrong, but the program can continue execution "normally"
+- info -\> informational messages, e.g. Filesystem initialized, Map loaded, Server started, etc...
+- debug -\> for debugging, e.g. hero moved to (12,3,0), direction 3', 'following artifacts influence X: .. or pattern detected at pos (10,15,0), p-nr. 30, flip 1, repl. 'D'
+- trace -\> for logging the control flow, the execution progress or fine-grained events, e.g. hero movement completed, entering CMapEditManager::updateTerrainViews: posx '10', posy '5', width '10', height '10', mapLevel '0',...
+
+The following colors are available for console output:
+
+- default
+- green
+- red
+- magenta
+- yellow
+- white
+- gray
+- teal
+
+## How to trace execution
+
+The program execution can be traced by using the macros TRACE_BEGIN, TRACE_END and their \_PARAMS counterparts. This can be important if you want to analyze the operations/internal workings of the AI or the communication of the client-server. In addition, it can help you to find bugs on a foreign VCMI installation with a custom mod configuration.
+
+```cpp
+ int calculateMovementPointsForPath(int3 start, int3 end, CHero * hero) // This is just an example, the function is fictive
+ {
+ TRACE_BEGIN_PARAMS(logGlobal, "start '%s', end '%s', hero '%s'", start.toString() % end.toString() % hero.getName()); // toString is fictive as well and returns a string representation of the int3 pos, ....
+ int movPoints;
+ // Do some stuff
+ // ...
+ TRACE_END_PARAMS(logGlobal, "movPoints '%i'", movPoints);
+ return movPoints;
+ }
+```
+
+# Concepts
+
+## Domain
+
+A domain is a specific part of the software. In VCMI there exist several domains:
+
+- network
+- ai
+- bonus
+- network
+
+In addition to these domains, there exist always a super domain called "global". Sub-domains can be created with "ai.battle" or "ai.adventure" for example. The dot between the "ai" and "battle" is important and notes the parent-child relationship of those two domains. A few examples how the log level will be inherited:
+
+global, level=info
+network, level=not set, effective level=info
+
+global, level=warn
+network, level=trace, effective level=trace
+
+global, level=debug
+ai, level=not set, effective level=debug
+ai.battle, level=trace, effective level=trace
+
+The same technique is applied to the console colors. If you want to have another debug color for the domain ai, you can explicitely set a color for that domain and level.
\ No newline at end of file
diff --git a/docs/developers/Lua_Scripting_System.md b/docs/developers/Lua_Scripting_System.md
new file mode 100644
index 000000000..fb3904a00
--- /dev/null
+++ b/docs/developers/Lua_Scripting_System.md
@@ -0,0 +1,204 @@
+< [Documentation](../Readme.md) / Lua Scripting System
+
+# Configuration
+
+``` javascript
+{
+ //general purpose script, Lua or ERM, runs on server
+ "myScript":
+ {
+ "source":"path/to/script/with/ext",
+ "implements":"ANYTHING"
+ },
+
+
+ //custom battle spell effect, Lua only, runs on both client and server
+ //script ID will be used as effect 'type' (with mod prefix)
+ "mySpellEffect":
+ {
+ "source":"path/to/script/with/ext",
+ "implements":"BATTLE_EFFECT"
+ },
+
+ //TODO: object|building type
+ //custom map object or building, Lua only, runs on both client and server
+ //script ID will be used as 'handler' (with mod prefix)
+ "myObjectType":
+ {
+ "source":"path/to/script/with/ext",
+ "implements":"MAP_OBJECT"
+ },
+ //TODO: server query
+ //TODO: client query
+
+}
+```
+
+# Lua
+
+## API Reference
+
+TODO **In near future Lua API may change drastically several times. Information here may be outdated**
+
+### Globals
+
+- DATA - persistent table
+- - DATA.ERM contains ERM state, anything else is free to use.
+- GAME - IGameInfoCallback API
+- BATTLE - IBattleInfoCallback API
+- EVENT_BUS - opaque handle, for use with events API
+- SERVICES - root "raw" access to all static game objects
+- - SERVICES:artifacts()
+- - SERVICES:creatures()
+- - SERVICES:factions()
+- - SERVICES:heroClasses()
+- - SERVICES:heroTypes()
+- - SERVICES:spells()
+- - SERVICES:skills()
+- require(URI)
+- -works similar to usual Lua require
+- -require("ClassName") - loads additional API and returns it as table (for C++ classes)
+- -require("core:relative.path.to.module") - loads module from "SCRIPTS/LIB"
+- -TODO require("modName:relative.path.to.module") - loads module from dependent mod
+- -TODO require(":relative.path.to.module") - loads module from same mod
+- logError(text) - backup error log function
+
+### Low level events API
+
+``` Lua
+
+-- Each event type must be loaded first
+local PlayerGotTurn = require("events.PlayerGotTurn")
+
+-- in this example subscription handles made global, do so if there is no better place
+-- !!! do not store them in local variables
+sub1 = PlayerGotTurn.subscribeAfter(EVENT_BUS, function(event)
+ --do smth
+ end)
+
+sub2 = PlayerGotTurn.subscribeBefore(EVENT_BUS, function(event)
+ --do smth
+ end)
+```
+
+### Lua standard library
+
+VCMI uses LuaJIT, which is Lua 5.1 API, see [upstream documentation](https://www.lua.org/manual/5.1/manual.html)
+
+Following libraries are supported
+
+- base
+- table
+- string
+- math
+- bit
+
+# ERM
+
+## Features
+
+- no strict limit on function/variable numbers (technical limit 32 bit integer except 0))
+- TODO semi compare
+- DONE macros
+
+## Bugs
+
+- TODO Broken XOR support (clashes with \`X\` option)
+
+## Triggers
+
+- TODO **!?AE** Equip/Unequip artifact
+- WIP **!?BA** when any battle occurs
+- WIP **!?BF** when a battlefield is prepared for a battle
+- TODO **!?BG** at every action taken by any stack or by the hero
+- TODO **!?BR** at every turn of a battle
+- *!?CM (client only) click the mouse button.*
+- TODO **!?CO** Commander triggers
+- TODO **!?DL** Custom dialogs
+- DONE **!?FU** function
+- TODO **!?GE** "global" event
+- TODO **!?GM** Saving/Loading
+- TODO **!?HE** when the hero \# is attacked by an enemy hero or
+ visited by an allied hero
+- TODO **!?HL** hero gains a level
+- TODO **!?HM** every step a hero \# takes
+- *!?IP Multiplayer support.*
+- TODO **!?LE** (!$LE) An Event on the map
+- WIP **!?MF** stack taking physical damage(before an action)
+- TODO **!?MG** casting on the adventure map
+- *!?MM scroll text during a battle*
+- TODO **!?MR** Magic resistance
+- TODO **!?MW** Wandering Monsters
+- WIP **!?OB** (!$OB) visiting objects
+- DONE **!?PI** Post Instruction.
+- TODO **!?SN** Sound and ERA extensions
+- *!?TH town hall*
+- TODO **!?TL** Real-Time Timer
+- TODO **!?TM** timed events
+
+## Receivers
+
+### VCMI
+
+- **!!MC:S@varName@** - declare new "normal" variable (technically
+ v-var with string key)
+- TODO Identifier resolver
+- WIP Bonus system
+
+### ERA
+
+- DONE !!if !!el !!en
+- TODO !!br !!co
+- TODO !!SN:X
+
+### WoG
+
+- TODO !!AR Артефакт (ресурс) в определенной позиции
+- TODO !!BA Битва
+ - !!BA:A$ return 1 for battle evaluation
+- TODO !!BF Препятствия на поле боя
+- TODO !!BG Действий монстров в бою
+- TODO !!BH Действия героя в бою
+- TODO !!BM Монстр в битве
+- WIP !!BU Универсальные параметры битвы
+- TODO !!CA Замок
+- TODO !!CD Разрушения замков
+- TODO !!CE События в замке
+- TODO !!CM Клика мышью
+- TODO !!DL Нестандартный диалог (только ТЕ или выше)
+- TODO !!CO Командиры
+- WIP !!DO Многократный вызов функции
+- TODO !!EA Бонусы опыта существ
+- TODO !!EX Опыт стека
+- DONE !!FU Однократный вызов функции
+- TODO !!GE Глобальное событие
+- WIP !!HE Герой
+- TODO !!HL Новый уровень героя
+- TODO !!HO Взаимодействия героев
+- TODO !!HT Подсказки по правому клику
+- WIP !!IF Диалоги и флагов
+- TODO !!IP Сетевой сервис битвы
+- TODO !!LE Локальное события
+- WIP !!MA Общие параметры монстров
+- DONE !!MC Макросы
+- WIP !!MF Получение физ. урона в бою
+- TODO !!MM Текст в битве
+- WIP !!MO Монстр в определенной позиции
+- TODO !!MP Контроль MP3
+- TODO !!MR Сопротивления магии
+- TODO !!MW Бродячих монстров
+- WIP !!OB Объект в определенной позиции
+- TODO !!OW Параметры игрока
+- TODO !!PM Пирамиды или новые объекты
+- TODO !!PO Информация квадрата карты
+- TODO (???) !!QW Журнала
+- TODO !!SN Проигрываемые звуков
+- TODO !!SS Настройка заклинаний (только ТЕ или выше)
+- TODO !!TL Контроль времени хода (только ТЕ или выше)
+- TODO !!TM Временный таймер
+- TODO !!TR Квадрата карты (почва, проходимость, т.п.)
+- TODO !!UN Универсальная команда
+- *!#VC Контроль переменных*
+- WIP !!VR Установка переменных
+
+## Persistence
\ No newline at end of file
diff --git a/docs/developers/Serialization.md b/docs/developers/Serialization.md
new file mode 100644
index 000000000..726530313
--- /dev/null
+++ b/docs/developers/Serialization.md
@@ -0,0 +1,267 @@
+< [Documentation](../Readme.md) / Serialization System
+
+# Introduction
+
+The serializer translates between objects living in our code (like int or CGameState\*) and stream of bytes. Having objects represented as a stream of bytes is useful. Such bytes can send through the network connection (so client and server can communicate) or written to the disk (savegames).
+
+VCMI uses binary format. The primitive types are simply copied from memory, more complex structures are represented as a sequence of primitives.
+
+## Typical tasks
+
+### Bumping a version number
+
+Different major version of VCMI likely change the format of the save game. Every save game needs a version identifier, that loading can work properly. Backward compatibility isn't supported for now. The version identifier is a constant named version in Connection.h and should be updated every major VCMI version or development version if the format has been changed. Do not change this constant if it's not required as it leads to full rebuilds. Why should the version be updated? If VCMI cannot detect "invalid" save games the program behaviour is random and undefined. It mostly results in a crash. The reason can be anything from null pointer exceptions, index out of bounds exceptions(ok, they aren't available in c++, but you know what I mean:) or invalid objects loading(too much elements in a vector, etc...) This should be avoided at least for public VCMI releases.
+
+### Adding a new class
+
+If you want your class to be serializable (eg. being storable in a savegame) you need to define a serialize method template, as described in [#User types](#user-types)
+
+Additionally, if your class is part of one of registered object hierarchies (basically: if it derives from CGObjectInstance, IPropagator, ILimiter, CBonusSystemNode, CPack) it needs to be registered. Just add an appropriate entry in the `RegisterTypes.h` file. See polymorphic serialization for more information.
+
+# How does it work
+
+## Primitive types
+
+They are simply stored in a binary form, as in memory. Compatibility is ensued through the following means:
+
+- VCMI uses internally types that have constant, defined size (like int32_t - has 32 bits on all platforms)
+- serializer stores information about its endianess
+
+It's not "really" portable, yet it works properly across all platforms we currently support.
+
+## Dependant types
+
+### Pointers
+
+Storing pointers mechanics can be and almost always is customized. See [#Additional features](additional-features).
+
+In the most basic form storing pointer simply sends the object state and loading pointer allocates an object (using "new" operator) and fills its state with the stored data.
+
+### Arrays
+
+Serializing array is simply serializing all its elements.
+
+## Standard library types
+
+### STL Containers
+
+First the container size is stored, then every single contained element.
+
+Supported STL types include:
+
+`vector`
+`array`
+`set`
+`unordered_set`
+`list`
+`string`
+`pair`
+`map`
+
+### Smart pointers
+
+Smart pointers at the moment are treated as the raw C-style pointers. This is very bad and dangerous for shared_ptr and is expected to be fixed somewhen in the future.
+
+The list of supported data types from standard library:
+
+`shared_ptr (partial!!!)`
+`unique_ptr`
+
+### Boost
+
+Additionally, a few types for Boost are supported as well:
+
+`variant`
+`optional`
+
+## User types
+
+To make the user-defined type serializable, it has to provide a template method serialize. The first argument (typed as template parameter) is a reference to serializer. The second one is version number.
+
+Serializer provides an operator& that is internally expanded to `<<` when serialziing or `>>` when deserializing.
+
+Serializer provides a public bool field `saving`that set to true during serialziation and to false for deserialziation.
+
+Typically, serializing class involves serializing all its members (given that they are serializable). Sample:
+
+``` cpp
+/// The rumor struct consists of a rumor name and text.
+struct DLL_LINKAGE Rumor
+{
+ std::string name;
+ std::string text;
+
+ template
+ void serialize(Handler & h, const int version)
+ {
+ h & name;
+ h & text;
+ }
+};
+```
+
+## Backwards compatibility
+
+Serializer, before sending any data, stores its version number. It is passed as the parameter to the serialize method, so conditional code ensuring backwards compatibility can be added.
+
+Yet, because of numerous changes to our game data structure, providing means of backwards compatibility is not feasible. The versioning feature is rarely used.
+
+Sample:
+
+``` cpp
+/// The rumor struct consists of a rumor name and text.
+struct DLL_LINKAGE Rumor
+{
+ std::string name; //introduced in version 1065
+ std::string text;
+
+ template
+ void serialize(Handler & h, const int version)
+ {
+ if(version >= 1065)
+ h & name;
+ else //when loading old savegame
+ name = "no name"; //set name to a sane default value
+
+ h & text;
+ }
+};
+```
+
+## Serializer classes
+
+### Common information
+
+Serializer classes provide iostream-like interface with operator `<<` for serialization and operator `>>` for deserialization. Serializer upon creation will retrieve/store some metadata (version number, endianess), so even if no object is actually serialized, some data will be passed.
+
+### Serialization to file
+
+CLoadFile/CSaveFile classes allow to read data to file and store data to file. They take filename as the first parameter in constructor and, optionally, the minimum supported version number (default to the current version). If the construction fails (no file or wrong file) the exception is thrown.
+
+### Networking
+
+CConnection class provides support for sending data structures over TCP/IP protocol. It provides 3 constructors:
+1. connect to given hostname at given port (host must be accepting connection)
+2. accept connection (takes boost.asio acceptor and io_service)
+3. adapt boost.asio socket with already established connection
+
+All three constructors take as the last parameter the name that will be used to identify the peer.
+
+## Additional features
+
+Here is the list of additional custom features serialzier provides. Most of them can be turned on and off.
+
+- Polymorphic serialization — no flag to control it, turned on by calls to registerType.
+- Vectorized list member serialization — enabled by smartVectorMembersSerialization flag.
+- Stack instance serialization — enabled by sendStackInstanceByIds flag.
+- Smart pointer serialization — enabled by smartPointerSerialization flag.
+
+### Polymorphic serialization
+
+Serializer is to recognize the true type of object under the pointer if classes of that hierarchy were previously registered.
+
+This means that following will work
+
+``` cpp
+Derived *d = new Derived();
+Base *basePtr = d;
+CSaveFile output("test.dat");
+output << b;
+//
+Base *basePtr = nullptr;
+CLoadFile input("test.dat");
+input >> basePtr; //a new Derived object will be put under the pointer
+```
+
+Class hierarchies that are now registered to benefit from this feature are mostly adventure map object (CGObjectInstance) and network packs (CPack). See the RegisterTypes.h file for the full list.
+
+It is crucial that classes are registered in the same order in the both serializers (storing and loading).
+
+### Vectorized list member serialization
+
+Both client and server store their own copies of game state and VLC (handlers with data from config). Many game logic objects are stored in the vectors and possess a unique id number that represent also their position in such vector.
+
+The vectorised game objects are:
+
+`CGObjectInstance`
+`CGHeroInstance`
+`CCreature`
+`CArtifact`
+`CArtifactInstance`
+`CQuest`
+
+For this to work, serializer needs an access to gamestate library classes. This is done by calling a method `CSerializer::addStdVecItems(CGameState *gs, LibClasses *lib)`.
+
+When the game ends (or gamestate pointer is invaldiated for another reason) this feature needs to be turned off by toggling its flag.
+
+When vectorized member serialization is turned on, serializing pointer to such object denotes not sending an object itself but rather its identity. For example:
+
+``` cpp
+//Server code
+CCreature *someCreature = ...;
+connection << someCreature;
+```
+
+the last line is equivalent to
+
+``` cpp
+connection << someCreature->idNumber;
+```
+
+``` cpp
+//Client code
+CCreature *someCreature = nullptr;
+connection >> someCreature;
+```
+
+the last line is equivalent to
+
+``` cpp
+CreatureID id;
+connection >> id;
+someCreature = VLC->creh->creatures[id.getNum()];
+```
+
+Important: this means that the object state is not serialized.
+
+This feature makes sense only for server-client network communication.
+
+### Stack instance serialization
+
+This feature works very much like the vectorised object serialization. It is like its special case for stack instances that are not vectorised (each hero owns its map). When this option is turned on, sending CStackInstance\* will actually send an owning object (town, hero, garrison, etc) id and the stack slot position.
+
+For this to work, obviously, both sides of the connection need to have exactly the same copies of an armed object and its stacks.
+
+This feature depends on vectorised member serialization being turned on. (Sending owning object by id.)
+
+### Smart pointer serialization
+
+Note: name is unfortunate, this feature is not about smart pointers (like shared-ptr and unique_ptr). It is for raw C-style pointers, that happen to point to the same object.
+
+This feature makes it that multiple pointers pointing to the same object are not stored twice.
+
+Each time a pointer is stored, a unique id is given to it. If the same pointer is stored a second time, its contents is not serialized — serializer just stores a reference to the id.
+
+For example:
+
+``` cpp
+Foo * a = new Foo();
+Foo * b = b;
+
+{
+ CSaveFile test("test.txt");
+ test << a << b;
+}
+
+Foo *loadedA, *loadedB;
+{
+ CLoadFile test("test.txt");
+ test >> loadedA >> loadedB;
+ //now both pointers point to the same object
+ assert(loadedA == loadedB);
+}
+```
+
+The feature recognizes pointers by addresses. Therefore it allows mixing pointers to base and derived classes. However, it does not allow serializing classes with multiple inheritance using a "non-first" base (other bases have a certain address offset from the actual object).
+
+Pointer cycles are properly handled. This feature makes sense for savegames and is turned on for them.
\ No newline at end of file
diff --git a/docs/maintainers/Project_Infrastructure.md b/docs/maintainers/Project_Infrastructure.md
new file mode 100644
index 000000000..710f1f994
--- /dev/null
+++ b/docs/maintainers/Project_Infrastructure.md
@@ -0,0 +1,136 @@
+< [Documentation](../Readme.md) / Project Infrastructure
+
+# Project Infrastructure
+
+This section hold important information about project infrastructure for current and future contributors. At moment it's all maintained by me (SXX), but following information will be useful if someone going to replace me in future.
+
+## Services and accounts
+
+So far we using following services:
+
+### Most important
+
+- VCMI.eu domain paid until July of 2019.
+ - Owner: Tow
+ - Our main domain used by services.
+- VCMI.download paid until November of 2026.
+ - Owner: SXX
+ - Intended to be used for all assets downloads.
+ - Domain registered on GANDI and **can be renewed by anyone without access to account**.
+- [DigitalOcean](https://cloud.digitalocean.com/) team.
+ - Our hosting sponsor.
+ - Administrator access: SXX, Warmonger.
+ - User access: AVS, Tow.
+- [CloudFlare](https://www.cloudflare.com/a/overview) account.
+ - Access through shared login / password.
+ - All of our infrastructure is behind CloudFlare and all our web. We manage our DNS there.
+- [Google Apps (G Suite)](https://admin.google.com/) account.
+ - It's only for vcmi.eu domain and limited to 5 users. Each account has limit of 500 emails / day.
+ - One administrative email used for other services registration.
+ - "noreply" email used for outgoing mail on Wiki and Bug Tracker.
+ - "forum" email used for outgoing mail on Forums. Since we authenticate everyone through forum it's should be separate email.
+ - Administrator access: Tow, SXX.
+- [Google Play Console](https://play.google.com/apps/publish/) account.
+ - Hold ownership over VCMI Android App.
+ - Owner: SXX
+ - Administrator access: Warmonger, AVS, Ivan.
+ - Release manager access: Fay.
+
+Not all services let us safely share login credentials, but at least when possible at least two of core developers must have access to them in case of emergency.
+
+### Public relations
+
+We want to notify players about updates on as many social services as possible.
+
+- Facebook page:
+ - Administrator access: SXX, Warmonger
+- Twitter account:
+ - Administrator access: SXX.
+ - User access via TweetDeck:
+- VK / VKontakte page:
+ - Owner: SXX
+ - Administrator access: AVS
+- Steam group:
+ - Administrator access: SXX
+ - Moderator access: Dydzio
+- Reddit:
+ - Administrator access: SXX
+- ModDB entry:
+ - Administrator access: SXX
+
+### Communication channels
+
+- Slack team:
+ - Owner: vmarkovtsev
+ - Administrator access: SXX, Warmonger, AVS...
+- Trello team:
+ - Administrator access: SXX
+- Discord:
+ - Owner: dydzio
+ - Administrator access: SXX, Warmonger, Ivan...
+
+### Other services
+
+- Launchpad PPA:
+ - Member access: AVS
+ - Administrator access: Ivan, SXX
+- Snapcraft Dashboard:
+ - Administrator access: SXX
+- Coverity Scan page:
+ - Administrator access: SXX, Warmonger, AVS
+- OpenHub page:
+ - Administrator access: Tow
+- Docker Hub organization:
+ - Administrator access: SXX
+
+Reserve accounts for other code hosting services:
+
+- GitLab organization:
+ - Administrator access: SXX
+- BitBucket organization:
+ - Administrator access: SXX
+
+## What's to improve
+
+1. Encourage Tow to transfer VCMI.eu to GANDI so it's can be also renewed without access.
+2. Use 2FA on CloudFlare and just ask everyone to get FreeOTP and then use shared secret.
+3. Centralized way to post news about game updates to all social media.
+
+# Project Servers Configuration
+
+This section dedicated to explain specific configurations of our servers for anyone who might need to improve it in future.
+
+## Droplet configuration
+
+### Droplet and hosted services
+
+Currently we using two droplets:
+
+- First one serve all of our web services:
+ - [Forum](https://forum.vcmi.eu/)
+ - [Bug tracker](https://bugs.vcmi.eu/)
+ - [Wiki](https://wiki.vcmi.eu/)
+ - [Slack invite page](https://slack.vcmi.eu/)
+- Second serve downloads:
+ - [Legacy download page](http://download.vcmi.eu/)
+ - [Build download page](https://builds.vcmi.download/)
+
+To keep everything secure we should always keep binary downloads separate from any web services.
+
+### Rules to stick to
+
+- SSH authentication by public key only.
+- Incoming connections to all ports except SSH (22) must be blocked.
+- Exception for HTTP(S) connection on ports 80 / 443 from [CloudFlare IP Ranges](https://www.cloudflare.com/ips/).
+- No one except core developers should ever know real server IPs.
+- Droplet hostname should never be valid host. Otherwise it's exposed in [reverse DNS](https://en.wikipedia.org/wiki/Reverse_DNS).
+- If some non-web service need to listen for external connections then read below.
+
+### Our publicly-facing server
+
+We only expose floating IP that can be detached from droplet in case of emergency using [DO control panel](https://cloud.digitalocean.com/networking/floating_ips). This also allow us to easily move public services to dedicated droplet in future.
+
+- Address: beholder.vcmi.eu (67.207.75.182)
+- Port 22 serve SFTP for file uploads as well as CI artifacts uploads.
+
+If new services added firewall rules can be adjusted in [DO control panel](https://cloud.digitalocean.com/networking/firewalls).
\ No newline at end of file
diff --git a/docs/maintainers/Release_Process.md b/docs/maintainers/Release_Process.md
new file mode 100644
index 000000000..2e23e41b7
--- /dev/null
+++ b/docs/maintainers/Release_Process.md
@@ -0,0 +1,48 @@
+< [Documentation](../Readme.md) / Release Process
+
+## Branches
+Our branching strategy is very similar to GitFlow
+* `master` branch has release commits. One commit - one release. Each release commit should be tagged with version `maj.min.patch`
+* `beta` branch is for stabilization of ongoing release. We don't merge new features into `beta` branch - only bug fixes are acceptable. Hotfixes for already released software should be delivered to this branch as well.
+* `develop` branch is a main branch for ongoing development. Pull requests with new features should be targeted to this branch, `develop` version is one step ahead of 'beta`
+
+## Release process step-by-step
+Assuming that all features planned to be released are implemented in `develop` branch and next release version will be `1.x.0`
+
+### Start of stabilization stage
+Should be done several weeks before planned release date
+
+- Create [milestone](https://github.com/vcmi/vcmi/milestones) named `Release 1.x`
+- Specify new milestone for all regression bugs and major bugs related to new functionality
+- Create `beta` branch from `develop`
+- Bump vcmi version on `develop` branch
+- Bump version for linux on `develop` branch
+
+### Release preparation stage
+Should be done several days before planned release date
+
+- Make sure to announce codebase freeze deadline to all developers
+- Update [release notes](https://github.com/vcmi/vcmi/blob/develop/ChangeLog.md)
+- Update release date for Linux packaging. See [example](https://github.com/vcmi/vcmi/pull/1258)
+- Update release date for Android packaging. See [example](https://github.com/vcmi/vcmi/pull/2090)
+- Create draft release page, specify `1.x.0` as tag for `master` after publishing
+- Prepare pull request with release update for web site https://github.com/vcmi/VCMI.eu
+- Prepare pull request for [vcmi-updates](https://github.com/vcmi/vcmi-updates)
+
+### Release publishing phase
+Should be done on release date
+
+- Check that all items from milestone `Release 1.x` completed
+- Merge `beta` into `master`
+- Check that artifacts for all platforms are available on `master` branch
+- Trigger builds for new release on Ubuntu PPA
+- Attach build artifacts for all platforms to release page
+- Merge prepared pull requests
+- Publish release page
+
+### After release publish
+
+- Close `Release 1.x` milestone
+- Write announcements in social networks
+- Merge `master` into `develop`
+- Update downloads counter in readme.md. See [example](https://github.com/vcmi/vcmi/pull/2091)
diff --git a/docs/maintainers/Ubuntu_PPA.md b/docs/maintainers/Ubuntu_PPA.md
new file mode 100644
index 000000000..6241d91da
--- /dev/null
+++ b/docs/maintainers/Ubuntu_PPA.md
@@ -0,0 +1,44 @@
+< [Documentation](../Readme.md) / Ubuntu PPA
+
+## Main links
+- [Team](https://launchpad.net/~vcmi)
+- [Project](https://launchpad.net/vcmi)
+- [Sources](https://code.launchpad.net/~vcmi/vcmi/+git/vcmi)
+- [Recipes](https://code.launchpad.net/~vcmi/+recipes)
+- - [Stable recipe](https://code.launchpad.net/~vcmi/+recipe/vcmi-stable)
+- - [Daily recipe](https://code.launchpad.net/~vcmi/+recipe/vcmi-daily)
+- PPA's
+- - [Stable PPA](https://launchpad.net/~vcmi/+archive/ubuntu/ppa)
+- - [Daily PPA](https://launchpad.net/~vcmi/+archive/ubuntu/vcmi-latest)
+
+## Automatic daily builds process
+
+### Code import
+- Launchpad performs regular (once per few hours) clone of our git repository.
+- This process can be observed on [Sources](https://code.launchpad.net/~vcmi/vcmi/+git/vcmi) page.
+- If necessary, it is possible to trigger fresh clone immediately (Import Now button)
+### Build dependencies
+- All packages required for building of vcmi are defined in [debian/control](https://github.com/vcmi/vcmi/blob/develop/debian/control) file
+- Launchpad will automatically install build dependencies during build
+- Dependencies of output .deb package are defined implicitly as dependencies of packages required for build
+### Recipe building
+- Every 24 hours Launchpad triggers daily builds on all recipes that have build schedule enable. For vcmi this is [Daily recipe](https://code.launchpad.net/~vcmi/+recipe/vcmi-daily)
+- Alternatively, builds can be triggered manually using "request build(s) link on recipe page. VCMI uses this for [Stable recipe](https://code.launchpad.net/~vcmi/+recipe/vcmi-stable)
+### Recipe content (build settings)
+- Version of resulting .deb package is set in recipe content, e.g `{debupstream}+git{revtime}` for daily builds
+- Base version (referred as `debupstream` on Launchpad is taken from source code, [debian/changelog](https://github.com/vcmi/vcmi/blob/develop/debian/changelog) file
+- CMake configuration settings are taken from source code, [debian/rules](https://github.com/vcmi/vcmi/blob/develop/debian/rules) file
+- Branch which is used for build is specified in recipe content, e.g. `lp:vcmi master`
+## Workflow for creating a release build
+- if necessary, push all required changes including `debian/changelog` update to `vcmi/master` branch
+- Go to [Sources](https://code.launchpad.net/~vcmi/vcmi/+git/vcmi) and run repository import.
+- Wait for import to finish, which usually happens within a minute. Press F5 to actually see changes.
+- Go to [Stable recipe](https://code.launchpad.net/~vcmi/+recipe/vcmi-stable) and request new builds
+- Wait for builds to finish. This takes quite a while, usually - over a hour, even more for arm builds
+- Once built, all successfully built packages are automatically copied to PPA linked to the recipe
+- If any of builds have failed, open page with build info and check logs.
+## People with access
+- [alexvins](https://github.com/alexvins) (https://launchpad.net/~alexvins)
+- [ArseniyShestakov](https://github.com/ArseniyShestakov) (https://launchpad.net/~sxx)
+- [IvanSavenko](https://github.com/IvanSavenko) (https://launchpad.net/~saven-ivan)
+- (Not member of VCMI, creator of PPA) (https://launchpad.net/~mantas)
\ No newline at end of file
diff --git a/docs/modders/Animation_Format.md b/docs/modders/Animation_Format.md
new file mode 100644
index 000000000..17083f7d5
--- /dev/null
+++ b/docs/modders/Animation_Format.md
@@ -0,0 +1,208 @@
+< [Documentation](../Readme.md) / [Modding](Readme.md) / Animation Format
+
+VCMI allows overriding HoMM3 .def files with .json replacement. Compared
+to .def this format allows:
+
+- Overriding individual frames from json file (e.g. icons)
+- Modern graphics formats (targa, png - all formats supported by VCMI
+ image loader)
+- Does not requires any special tools - all you need is text editor
+ and images.
+
+# Format description
+
+``` javascript
+{
+ // Base path of all images in animation. Optional.
+ // Can be used to avoid using long path to images
+ "basepath" : "path/to/images/directory/",
+
+ // List of sequiences / groups in animation
+ // This will replace original group with specified list of files
+ // even if original animation is longer
+ "sequences" :
+ [
+ {
+ // Index of group, zero-based
+ "group" : 1,
+
+ // List of files in this group
+ "frames" :
+ [
+ "frame1.png",
+ "frame2.png"
+ ...
+ ]
+ },
+ ...
+ ],
+
+ // Allow overriding individual frames in file
+ "images" :
+ [
+ {
+ // Group of this image. Optional, default = 0
+ "group" : 0,
+
+ // Imdex of the image in group
+ "frame" : 0,
+
+ // Filename for this frame
+ "file" : "filename.png"
+ }.
+ ...
+ ]
+
+}
+```
+
+# Creature animation groups
+
+Animation for creatures consist from multiple groups, with each group
+representing specific one animation. VCMI uses groups as follows:
+
+**Basic animations**
+
+- \[0\] Movement: Used for creature movement
+- \[1\] Mouse over: Used for random idle movements and when mouse is
+ moved on the creature
+- \[2\] Idle: Basic animation that plays continuously when stack is
+ not acting
+- \[3\] Hitted: Animation that plays whenever stack is hit
+- \[4\] Defence: Alternative animation that plays when stack is
+ defending and was hit in melee
+- \[5\] Death: Animation that plays when stack dies
+- \[6\] Death (ranged): Alternative animation, plays when stack is
+ killed by ranged attack
+
+**Rotation animations**
+
+- \[7\] Turn left: Animation for rotating stack, only contains first
+ part of animation, with stack turning towards viewer
+- \[8\] Turn right: Second part of animation for rotating stack
+- \[9\] (unused in vcmi, present in H3 files)
+- \[10\] (unused in vcmi, present in H3 files)
+
+**Melee attack animations**
+
+- \[11\] Attack (up): Attacking animation, stack facing upwards
+- \[12\] Attack (front): Attacking animation, stack facing front
+- \[13\] Attack (down): Attacking animation, stack facing downwards
+
+**Ranged attack animations**
+
+- \[14\] Shooting (up): Ranged attack animation, stack facing upwards
+- \[15\] Shooting (front): Ranged attack animation, stack facing front
+- \[16\] Shooting (down): Ranged attack animation, stack facing
+ downwards
+
+**Special animations**
+
+- \[17\] Special (up): Special animation, used if dedicated cast or
+ group attack animations were not found
+- \[18\] Special (front): Special animation, used if dedicated cast or
+ group attack animations were not found
+- \[19\] Special (down): Special animation, used if dedicated cast or
+ group attack animations were not found
+
+**Additional H3 animations**
+
+- \[20\] Movement start: Animation that plays before movement
+ animation starts.
+- \[21\] Movement end: Animation that plays after movement animation
+ ends.
+
+**Additional VCMI animations**
+
+- \[22\] \[VCMI 1.0\] Dead: Animation that plays when creature is
+ dead. If not present, will consist from last frame from "Death"
+ group
+- \[23\] \[VCMI 1.0\] Dead (ranged): Animation that plays when
+ creature is dead after ranged attack. If not present, will consist
+ from last frame from "Death (ranged)" group
+- \[24\] \[VCMI 1.2\] Resurrection: Animation that plays when creature
+ is resurrected. If not present, will consist from reversed version
+ of "Death" animation
+
+**Spellcasting animations**
+
+- \[30\] \[VCMI 1.2\] Cast (up): Used when creature casts spell facing
+ upwards
+- \[31\] \[VCMI 1.2\] Cast (front): Used when creature casts spell
+ facing front
+- \[32\] \[VCMI 1.2\] Cast (down): Used when creature casts spell
+ facing downwards
+
+**Group attack animations**
+
+- \[40\] \[VCMI 1.2\] Group Attack (up): Used when creature attacks
+ multiple target, with primary target facing up (Dragon Breath
+ attack, or creatures like Hydra)
+- \[41\] \[VCMI 1.2\] Group Attack (front): Used when creature attacks
+ multiple target, with primary target facing front (Dragon Breath
+ attack, or creatures like Hydra)
+- \[42\] \[VCMI 1.2\] Group Attack (down): Used when creature attacks
+ multiple target, with primary target facing downwards (Dragon Breath
+ attack, or creatures like Hydra)
+
+# Proposed format extensions
+
+## Texture atlas format
+
+**TODO**
+
+- arbitrary texture coordinates
+- margins
+- grid-like layout
+
+### Texture atlas format
+
+``` javascript
+{
+ // Base path of all images in animation. Optional.
+ // Can be used to avoid using long path to images
+ // If a path is a filename is is treated as single texture atlas
+ "basepath" : "path/to/images/atlas/bitmap.png",
+
+ // List of sequences / groups in animation
+ "sequences" :
+ [
+ {
+ // Index of group, zero-based
+ "group" : 1,
+
+ // List of files in this group
+ "frames" :
+ [
+ {"x":0, "y":0, "w": 64, "h": 64},
+ {"x":64, "y":0, "w": 64, "h": 64}
+ ...
+ ]
+ },
+ ...
+ ]
+}
+```
+
+### Texture atlas grid format
+
+``` javascript
+{
+ // filename is is treated as single texture atlas
+ "basepath" : "path/to/images/atlas/bitmap.png",
+
+ //optional, atlas is a grid with same size images
+ //located left to right, top to bottom
+ //[columns, rows]
+ //default [1,1]
+ "gridCols":3,
+ "gridRows":3,
+
+ // List of sequences / groups in animation
+ // sequence index -> images count in sequence
+ "sequences" :
+ [
+ 1,3,5
+ ]
+}
+```
\ No newline at end of file
diff --git a/docs/modders/Bonus/Bonus_Duration_Types.md b/docs/modders/Bonus/Bonus_Duration_Types.md
new file mode 100644
index 000000000..53408d3c2
--- /dev/null
+++ b/docs/modders/Bonus/Bonus_Duration_Types.md
@@ -0,0 +1,19 @@
+< [Documentation](../../Readme.md) / [Modding](../Readme.md) / [Bonus Format](../Bonus_Format.md) / Bonus Duration Types
+
+
+Bonus may have any of these durations. They acts in disjunction.
+
+## List of all bonus duration types
+
+- PERMANENT
+- ONE_BATTLE //at the end of battle
+- ONE_DAY //at the end of day
+- ONE_WEEK //at the end of week (bonus lasts till the end of week,
+ thats NOT 7 days
+- N_TURNS //used during battles, after battle bonus is always removed
+- N_DAYS
+- UNTIL_BEING_ATTACKED //removed after any damage-inflicting attack
+- UNTIL_ATTACK //removed after attack and counterattacks are performed
+- STACK_GETS_TURN //removed when stack gets its turn - used for
+ defensive stance
+- COMMANDER_KILLED
\ No newline at end of file
diff --git a/docs/modders/Bonus/Bonus_Limiters.md b/docs/modders/Bonus/Bonus_Limiters.md
new file mode 100644
index 000000000..c5b6cfa9d
--- /dev/null
+++ b/docs/modders/Bonus/Bonus_Limiters.md
@@ -0,0 +1,107 @@
+< [Documentation](../../Readme.md) / [Modding](../Readme.md) / [Bonus Format](../Bonus_Format.md) / Bonus Limiters
+
+## Predefined Limiters
+
+The limiters take no parameters:
+
+- SHOOTER_ONLY
+- DRAGON_NATURE
+- IS_UNDEAD
+- CREATURE_NATIVE_TERRAIN
+- OPPOSITE_SIDE
+
+Example:
+
+``` javascript
+"limiters" : [ "SHOOTER_ONLY" ]
+```
+
+## Customizable Limiters
+
+### HAS_ANOTHER_BONUS_LIMITER
+
+Parameters:
+
+- Bonus type
+- (optional) bonus subtype
+- (optional) bonus sourceType and sourceId in struct
+- example: (from Adele's bless):
+
+``` javascript
+ "limiters" : [
+ {
+ "type" : "HAS_ANOTHER_BONUS_LIMITER",
+ "parameters" : [
+ "GENERAL_DAMAGE_PREMY",
+ 1,
+ {
+ "type" : "SPELL_EFFECT",
+ "id" : "spell.bless"
+ }
+ ]
+ }
+ ],
+```
+
+### CREATURE_TYPE_LIMITER
+
+Parameters:
+
+- Creature id (string)
+- (optional) include upgrades - default is false
+
+### CREATURE_ALIGNMENT_LIMITER
+
+Parameters:
+
+- Alignment identifier
+
+### CREATURE_FACTION_LIMITER
+
+Parameters:
+
+- Faction identifier
+
+### CREATURE_TERRAIN_LIMITER
+
+Parameters:
+
+- Terrain identifier
+
+Example:
+
+``` javascript
+"limiters": [ {
+ "type":"CREATURE_TYPE_LIMITER",
+ "parameters": [ "angel", true ]
+} ],
+```
+
+``` javascript
+"limiters" : [ {
+ "type" : "CREATURE_TERRAIN_LIMITER",
+ "parameters" : ["sand"]
+} ]
+```
+
+## Aggregate Limiters
+
+The following limiters must be specified as the first element of a list,
+and operate on the remaining limiters in that list:
+
+- allOf (default when no aggregate limiter is specified)
+- anyOf
+- noneOf
+
+Example:
+
+``` javascript
+"limiters" : [
+ "noneOf",
+ "IS_UNDEAD",
+ {
+ "type" : "HAS_ANOTHER_BONUS_LIMITER",
+ "parameters" : [ "SIEGE_WEAPON" ]
+ }
+]
+```
\ No newline at end of file
diff --git a/docs/modders/Bonus/Bonus_Propagators.md b/docs/modders/Bonus/Bonus_Propagators.md
new file mode 100644
index 000000000..783355151
--- /dev/null
+++ b/docs/modders/Bonus/Bonus_Propagators.md
@@ -0,0 +1,27 @@
+< [Documentation](../../Readme.md) / [Modding](../Readme.md) / [Bonus Format](../Bonus_Format.md) / Bonus Propagators
+
+## Available propagators
+
+- BATTLE_WIDE
+
+Affects both sides during battle
+
+- VISITED_TOWN_AND_VISITOR
+
+Used with Legion artifacts (town visited by hero)
+
+- PLAYER_PROPAGATOR
+
+Bonus will affect all objects owned by player. Used by Statue of Legion.
+
+- TEAM_PROPAGATOR
+
+Bonus will affect all objects owned by player and his allies.
+
+- HERO
+
+Bonus will be transferred to hero (for example from stacks in his army).
+
+- GLOBAL_EFFECT
+
+This effect will influence all creatures, heroes and towns on the map.
\ No newline at end of file
diff --git a/docs/modders/Bonus/Bonus_Range_Types.md b/docs/modders/Bonus/Bonus_Range_Types.md
new file mode 100644
index 000000000..51274054a
--- /dev/null
+++ b/docs/modders/Bonus/Bonus_Range_Types.md
@@ -0,0 +1,22 @@
+< [Documentation](../../Readme.md) / [Modding](../Readme.md) / [Bonus Format](../Bonus_Format.md) / Bonus Range Types
+
+# List of all Bonus range types
+
+- NO_LIMIT
+- ONLY_DISTANCE_FIGHT
+- ONLY_MELEE_FIGHT
+- ONLY_ENEMY_ARMY (before 1.2)
+
+TODO: in 0.91 ONLY_MELEE_FIGHT / ONLY_DISTANCE_FIGHT range types work
+ONLY with creature attack, should be extended to all battle abilities.
+
+(1.2+) For replacing ONLY_ENEMY_ARMY alias, you should use the following
+parameters of bonus:
+
+ "propagator": "BATTLE_WIDE",
+ "propagationUpdater" : "BONUS_OWNER_UPDATER",
+ "limiters" : [ "OPPOSITE_SIDE" ]
+
+If some propagators was set before, it was actually ignored and should
+be replaced to code above. And OPPOSITE_SIDE limiter should be first, if
+any other limiters exists.
\ No newline at end of file
diff --git a/docs/modders/Bonus/Bonus_Sources.md b/docs/modders/Bonus/Bonus_Sources.md
new file mode 100644
index 000000000..bd6122241
--- /dev/null
+++ b/docs/modders/Bonus/Bonus_Sources.md
@@ -0,0 +1,23 @@
+< [Documentation](../../Readme.md) / [Modding](../Readme.md) / [Bonus Format](../Bonus_Format.md) / Bonus Sources
+
+# List of all possible bonus sources
+
+- ARTIFACT
+- ARTIFACT_INSTANCE
+- OBJECT
+- CREATURE_ABILITY
+- TERRAIN_NATIVE
+- TERRAIN_OVERLAY
+- SPELL_EFFECT
+- TOWN_STRUCTURE
+- HERO_BASE_SKILL
+- SECONDARY_SKILL
+- HERO_SPECIAL
+- ARMY
+- CAMPAIGN_BONUS
+- SPECIAL_WEEK
+- STACK_EXPERIENCE
+- COMMANDER
+- GLOBAL_EFFECT (before 1.2)
+- GLOBAL (after 1.2)
+- OTHER
\ No newline at end of file
diff --git a/docs/modders/Bonus/Bonus_Types.md b/docs/modders/Bonus/Bonus_Types.md
new file mode 100644
index 000000000..c033c404d
--- /dev/null
+++ b/docs/modders/Bonus/Bonus_Types.md
@@ -0,0 +1,834 @@
+< [Documentation](../../Readme.md) / [Modding](../Readme.md) / [Bonus Format](../Bonus_Format.md) / Bonus Types
+
+The bonuses were grouped according to their original purpose. The bonus
+system allows them to propagate freely betwen the nodes, however they
+may not be recognized properly beyond the scope of original use.
+
+# General-purpose bonuses
+
+### NONE
+
+### MORALE, LUCK
+
+- val = value
+
+### MAGIC_SCHOOL_SKILL
+
+eg. for magic plains terrain and for magic school secondary skills
+
+- subtype: school of magic (0 - all, 1 - air, 2 - fire, 4 - water, 8 -
+ earth)
+- val - level
+
+### NO_TYPE
+
+### DARKNESS
+
+- val = radius
+
+# Hero bonuses
+
+### MOVEMENT
+
+Before 1.2: both water / land After 1.2: subtype 0 - sea, subtype 1 -
+land
+
+- val = number of movement points (100 points for a tile)
+
+### LAND_MOVEMENT, SEA_MOVEMENT (before 1.2)
+
+- val = number of movement points (100 points for a tile)
+
+### WATER_WALKING
+
+- subtype: 1 - without penalty, 2 - with penalty
+
+### FLYING_MOVEMENT
+
+- subtype: 1 - without penalty, 2 - with penalty
+
+### NO_TERRAIN_PENALTY (since 0.98f)
+
+Hero does not get movement penalty on certain terrain type (Nomads
+ability).
+
+- subtype - type of terrain
+
+### PRIMARY_SKILL
+
+- uses subtype to pick skill
+- additional info if set: 1 - only melee, 2 - only distance
+
+### SIGHT_RADIOUS (before 1.2)
+
+Additional bonus to range of sight (Used for Scouting secondary skill)
+
+- val = distance in tiles
+
+### SIGHT_RADIUS (after 1.2)
+
+Sight radius of a hero. Used for base radius + Scouting secondary skill
+
+- val = distance in tiles
+
+### MANA_REGENERATION
+
+Before 1.2: points per turn apart from normal (1 + mysticism) After 1.2:
+points per turn (used for artifacts, global 1 point/turn regeneration
+and mysticism secondary skill)
+
+### FULL_MANA_REGENERATION
+
+all mana points are replenished every day
+
+### NONEVIL_ALIGNMENT_MIX
+
+good and neutral creatures can be mixed without morale penalty
+
+### SECONDARY_SKILL_PREMY (before 1.2)
+
+%
+
+### SURRENDER_DISCOUNT
+
+%
+
+### IMPROVED_NECROMANCY
+
+Before 1.2: allows Necropolis units other than skeletons to be raised by
+necromancy After 1.2: determine units which is raised by necromancy
+skill.
+
+- subtype: creature raised
+- val: Necromancer power
+- addInfo: limiter by Necromancer power
+- Example (from Necromancy skill):
+
+` "power" : {`
+` "type" : "IMPROVED_NECROMANCY",`
+` "subtype" : "creature.skeleton",`
+` "addInfo" : 0`
+` }`
+
+### LEARN_BATTLE_SPELL_CHANCE (since 1.2)
+
+- subtype: 0 - from enemy hero, 1 - from entire battlefield (not
+ implemented now).
+- val: chance to learn spell after battle victory
+
+Note: used for Eagle Eye skill
+
+### LEARN_BATTLE_SPELL_LEVEL_LIMIT (since 1.2)
+
+- subtype: school (-1 for all), others TODO
+- val: maximum learning level
+
+Note: used for Eagle Eye skill
+
+### LEARN_MEETING_SPELL_LIMIT (since 1.2)
+
+- subtype: school (-1 for all), others TODO
+- val: maximum learning level for learning a spell during hero
+ exchange
+
+Note: used for Scholar skill
+
+### ROUGH_TERRAIN_DISCOUNT (since 1.2)
+
+- val: Non-road terrain discount in movement points
+
+Note: used for Pathfinding skill
+
+### WANDERING_CREATURES_JOIN_BONUS (since 1.2)
+
+- val: value than used as level of diplomacy inside joining
+ probability calculating
+
+### BEFORE_BATTLE_REPOSITION (since 1.2)
+
+- val: number of hexes - 1 than should be used as repositionable hexes
+ before battle (like H3 tactics skill)
+
+### BEFORE_BATTLE_REPOSITION_BLOCK (since 1.2)
+
+- val: value than block opposite tactics, if value of opposite tactics
+ is less than this value of your hero (for 1.2, double-side tactics
+ is not working).
+
+### HERO_EXPERIENCE_GAIN_PERCENT (since 1.2)
+
+- val: how many experience hero gains from any source. There is a
+ global effect which set it by 100 (global value) and it is used as
+ learning skill
+
+### UNDEAD_RAISE_PERCENTAGE (since 1.2)
+
+- val: Percentage of killed enemy creatures to be raised after battle
+ as undead.
+
+Note: used for Necromancy secondary skill, Necromancy artifacts and town
+buildings.
+
+### MANA_PER_KNOWLEDGE (since 1.2)
+
+- val: Percentage rate of translating 10 hero knowledge to mana, used
+ for intelligence and global bonus
+
+### HERO_GRANTS_ATTACKS (since 1.2)
+
+- subtype: creature to have additional attacks
+- val: Number of attacks
+
+Note: used for Artillery secondary skill
+
+### BONUS_DAMAGE_PERCENTAGE (since 1.2)
+
+- subtype: creature to have additional damage percentage
+- val: percentage to be granted
+
+Note: used for Artillery secondary skill
+
+### BONUS_DAMAGE_CHANCE (since 1.2)
+
+- subtype: creature to have additional damage chance (will have
+ BONUS_DAMAGE_PERCENTAGE applied before attack concluded)
+- val: chance in percent
+
+### MAX_LEARNABLE_SPELL_LEVEL (since 1.2)
+
+- val: maximum level of spells than hero can learn from any source.
+ This bonus have priority above any other LEARN\_\*SPELL_LEVEL
+ bonuses.
+
+Note: used as global effect and as wisdom secondary skill.
+
+## Hero specialties
+
+### SPECIAL_SPELL_LEV
+
+- subtype = id
+- additionalInfo = value per level in percent
+
+### SPELL_DAMAGE
+
+Since 1.2: used for Sorcery secondary skill
+
+- val = value in percent
+
+### SPECIFIC_SPELL_DAMAGE
+
+- subtype = id of spell
+- val = value in percent (Luna, Ciele)
+
+### SPECIAL_BLESS_DAMAGE (before 1.2)
+
+- subtype = spell (bless by default)
+- val = value per level in percent
+
+### MAXED_SPELL (before 1.2)
+
+Spell always has expert effects but not expert range
+
+- subtype = id
+
+### SPECIAL_PECULIAR_ENCHANT
+
+blesses and curses with id = val dependent on unit's level
+
+- subtype = 0 or 1 for Coronius
+
+### SPECIAL_UPGRADE
+
+- subtype = base creature ID
+- addInfo = target creature ID
+
+# Artifact bonuses
+
+### SPELL_DURATION
+
+### AIR_SPELL_DMG_PREMY, EARTH_SPELL_DMG_PREMY, FIRE_SPELL_DMG_PREMY, WATER_SPELL_DMG_PREMY
+
+Effect of original Orb artifacts.
+
+- val - **percent** bonus to air / earth / fire / water spell damage.
+
+### BLOCK_MORALE, BLOCK_LUCK (removed in 1.2)
+
+### SPELL
+
+Hero knows spell, even if this spell is banned in map options or set to
+"special".
+
+- subtype - spell id
+- val - skill level (0 - 3)
+
+### SPELLS_OF_LEVEL
+
+hero knows all spells of given level
+
+- subtype - level
+- val - skill level
+
+Does not grant spells banned in map options.
+
+### FIRE_SPELLS, AIR_SPELLS, WATER_SPELLS, EARTH_SPELLS
+
+All spells of this school are granted to hero, eg. by Tomes of Magic.
+Does not grant spells banned in map options.
+
+### GENERATE_RESOURCE
+
+- subtype - resource
+- val - daily income
+
+### CREATURE_GROWTH
+
+for legion artifacts
+
+- value - weekly growth bonus,
+- subtype - monster level if aplicable
+
+### CREATURE_GROWTH_PERCENT
+
+increases growth of all units in all towns,
+
+- val - percentage
+
+### BATTLE_NO_FLEEING
+
+for Shackles of War
+
+### NEGATE_ALL_NATURAL_IMMUNITIES
+
+Orb of Vulnerability
+
+### OPENING_BATTLE_SPELL
+
+casts a spell at expert level at beginning of battle
+
+- subtype - Spell ID
+- val - spell power
+
+### FREE_SHIP_BOARDING
+
+movement points preserved with ship boarding and landing
+
+### WHIRLPOOL_PROTECTION
+
+hero won't lose army when teleporting through whirlpool
+
+# Creature bonuses
+
+### STACK_HEALTH
+
+### STACKS_SPEED
+
+- additional info - percent of speed bonus applied after direct
+ bonuses; \>0 - added, \<0 - subtracted to this part
+
+### CREATURE_DAMAGE
+
+- subtype: 0 = both, 1 = min, 2 = max
+
+### SHOTS
+
+### EXP_MULTIPLIER
+
+- val - percent of additional exp gained by stack / commander (base
+ value 100)
+
+# Creature abilities
+
+## Static abilities and immunities
+
+### NON_LIVING
+
+eg. golems, elementals
+
+### GARGOYLE
+
+Gargoyle is special than NON_LIVING, cannot be rised or healed
+
+### UNDEAD
+
+### SIEGE_WEAPON
+
+War machines have it. They cannot be raised or healed, have no morale
+and don't move.
+
+### DRAGON_NATURE
+
+### KING1, KING2, KING3 (before 1.2)
+
+Creatures take more damage from basic, advanced or expert Slayer effect.
+
+### KING (after 1.2)
+
+Creatures take more damage from Slayer effect than have greater or equal
+value than KING bonus.
+
+### FEARLESS
+
+### NO_LUCK
+
+eg. when fighting on cursed ground
+
+### NO_MORALE
+
+eg. when fighting on cursed ground
+
+### SELF_MORALE (before 1.2)
+
+eg. minotaur
+
+### SELF_LUCK (before 1.2)
+
+halfling
+
+## Combat abilities
+
+### FLYING
+
+- subtype - 0 - regular, 1 - teleport
+
+### SHOOTER
+
+### CHARGE_IMMUNITY
+
+### ADDITIONAL_ATTACK
+
+### UNLIMITED_RETALIATIONS
+
+### ADDITIONAL_RETALIATION
+
+- value - number of additional retaliations
+
+### JOUSTING
+
+for champions
+
+- val: percentage of charge
+
+### HATE
+
+eg. angels hate devils,
+
+- subtype - ID of hated creature,
+- val - damage bonus percent
+
+### SPELL_LIKE_ATTACK
+
+range is taken from spell, but damage from creature; eg. magog, lich
+
+- subtype - spell,
+- value - spell level
+
+### THREE_HEADED_ATTACK
+
+eg. cerberus
+
+### ATTACKS_ALL_ADJACENT
+
+eg. hydra
+
+### TWO_HEX_ATTACK_BREATH
+
+eg. dragons
+
+### RETURN_AFTER_STRIKE
+
+### ENEMY_DEFENCE_REDUCTION
+
+in % (value) eg. behemots
+
+### GENERAL_DAMAGE_REDUCTION
+
+- subtype - 0 - shield (melee) , 1 - air shield effect (ranged), -1 -
+ armorer secondary skill (all, since 1.2)
+
+### PERCENTAGE_DAMAGE_BOOST (since 1.2)
+
+- subtype: -1 - any damage (not used), 0 - melee damage (offence), 1 -
+ ranged damage (archery)
+
+### GENERAL_ATTACK_REDUCTION
+
+eg. while stoned or blinded - in %
+
+- subtype: -1 - any damage, 0 - melee damage, 1 - ranged damage
+
+### DEFENSIVE_STANCE
+
+WoG ability.
+
+- val - bonus to defense while defending
+
+### NO_DISTANCE_PENALTY
+
+### NO_MELEE_PENALTY
+
+Ranged stack does full damage in melee.
+
+### NO_WALL_PENALTY
+
+### FREE_SHOOTING
+
+stacks can shoot even if otherwise blocked (sharpshooter's bow effect)
+
+### BLOCKS_RETALIATION
+
+eg. naga
+
+### SOUL_STEAL
+
+WoG ability. Gains new creatures for each enemy killed
+
+- val: number of units gained per enemy killed
+- subtype: 0 - gained units survive after battle, 1 - they do not
+
+### TRANSMUTATION
+
+WoG ability. % chance to transform attacked unit to other type
+
+- val: chance to trigger in %
+- subtype: 0 - resurrection based on HP, 1 - based on unit count
+- addInfo: additional info - target creature ID (attacker default)
+
+### SUMMON_GUARDIANS
+
+WoG ability. Summon guardians surrounding desired stack
+
+- val - amount in % of stack count
+- subtype = creature ID
+
+### RANGED_RETALIATION
+
+Allows shooters to perform ranged retaliation
+
+- no additional parameters
+
+### BLOCKS_RANGED_RETALIATION
+
+Disallows ranged retaliation for shooter unit, BLOCKS_RETALIATION bonus
+is for melee retaliation only
+
+- no additional parameters
+
+### WIDE_BREATH
+
+Dragon breath affecting multiple nearby hexes
+
+- no additional parameters
+
+### FIRST_STRIKE
+
+First counterattack, then attack if possible
+
+- no additional parameters
+
+### SHOOTS_ALL_ADJACENT
+
+H4 Cyclops-like shoot (attacks all hexes neighboring with target)
+without spell-like mechanics
+
+- no additional parameters
+
+### DESTRUCTION
+
+Kills extra units after hit
+
+- subtype: 0 - kill percentage of units, 1 - kill amount
+- val: chance in percent to trigger
+- addInfo: amount/percentage to kill
+
+### LIMITED_SHOOTING_RANGE (since VCMI 1.2)
+
+Limits shooting range and/or changes long range penalty
+
+- val: max shooting range in hexes
+- addInfo: optional - sets range for "broken arrow" half damage
+ mechanic - default is 10
+
+## Special abilities
+
+### CATAPULT
+
+- subtype: (since 1.2) ability to use when catapulting (usually it
+ contains ballistics parameters, ability for standard catapult and
+ affected by ballistics is core:spell.catapultShot)
+
+### CATAPULT_EXTRA_SHOTS
+
+- subtype: (since 1.2) ability to be affected. Ability of CATAPULT
+ bonus should match. Used for ballistics secondary skill with subtype
+ of core:spell.catapultShot.
+- val: (since 1.2) ability level to be used with catapult. Additional
+ shots configured in ability level, not here.
+- val: (before 1.2) number of additional shots, requires CATAPULT
+ bonus to work
+
+### MANUAL_CONTROL
+
+- manually control warmachine with
+- id = subtype
+- val = chance
+
+### CHANGES_SPELL_COST_FOR_ALLY
+
+eg. mage
+
+- value - reduction in mana points
+
+### CHANGES_SPELL_COST_FOR_ENEMY
+
+eg. Silver Pegasus
+
+- value - mana points penalty
+
+### SPELL_RESISTANCE_AURA
+
+eg. unicorns
+
+- value - resistance bonus in % for adjacent creatures
+
+### HP_REGENERATION
+
+creature regenerates val HP every new round
+
+- val: amount of HP regeneration per round
+
+### MANA_DRAIN
+
+value - spell points per turn
+
+### MANA_CHANNELING
+
+eg. familiar
+
+- value in %
+
+### LIFE_DRAIN
+
+- val - precentage of life drained
+
+### DOUBLE_DAMAGE_CHANCE
+
+eg. dread knight
+
+- value in %
+
+### FEAR
+
+### HEALER
+
+First aid tent
+
+- subtype: (since 1.2) ability used for healing.
+
+### FIRE_SHIELD
+
+### MAGIC_MIRROR
+
+- value - chance of redirecting in %
+
+### ACID_BREATH
+
+- val - damage per creature after attack,
+- additional info - chance in percent
+
+### DEATH_STARE
+
+- subtype: 0 - gorgon, 1 - commander
+- val: if subtype is 0, its the (average) percentage of killed
+ creatures related to size of attacking stack
+
+### SPECIAL_CRYSTAL_GENERATION
+
+Crystal dragon crystal generation
+
+### NO_SPELLCAST_BY_DEFAULT
+
+Spellcast will not be default attack option for this creature
+
+## Creature spellcasting and activated abilities
+
+### SPELLCASTER
+
+Creature gain activated ability to cast a spell. Example: Archangel,
+Faerie Dragon
+
+- subtype - spell id
+- value - level of school
+- additional info - weighted chance
+
+use SPECIFIC_SPELL_POWER, CREATURE_SPELL_POWER or CREATURE_ENCHANT_POWER
+for calculating the power (since 1.2 those bonuses can be used for
+calculating CATAPULT and HEALER bonuses)
+
+### ENCHANTER
+
+for Enchanter spells
+
+- val - skill level
+- subtype - spell id
+- additionalInfo - cooldown (number of turns)
+
+### RANDOM_SPELLCASTER
+
+eg. master genie
+
+- val - spell mastery level
+
+### SPELL_AFTER_ATTACK
+
+- subtype - spell id
+- value - chance %
+- additional info - \[X, Y\]
+- X - spell level
+- Y = 0 - all attacks, 1 - shot only, 2 - melee only
+
+### SPELL_BEFORE_ATTACK
+
+- subtype - spell id
+- value - chance %
+- additional info - \[X, Y\]
+- X - spell level
+- Y = 0 - all attacks, 1 - shot only, 2 - melee only
+
+### CASTS
+
+how many times creature can cast activated spell
+
+### SPECIFIC_SPELL_POWER
+
+- value used for Thunderbolt and Resurrection casted by units, also
+ for Healing secondary skill (for core:spell.firstAid used by First
+ Aid tent)
+- subtype - spell id
+
+### CREATURE_SPELL_POWER
+
+- value per unit, divided by 100 (so faerie Dragons have 500)
+
+### CREATURE_ENCHANT_POWER
+
+total duration of spells casted by creature
+
+### REBIRTH
+
+- val - percent of total stack HP restored
+- subtype = 0 - regular, 1 - at least one unit (sacred Phoenix)
+
+### ENCHANTED
+
+Stack is permanently enchanted with spell subID of skill level = val, if
+val \> 3 then spell is mass and has level of val-3. Enchantment is
+refreshed every turn.
+
+## Spell immunities
+
+### LEVEL_SPELL_IMMUNITY
+
+creature is immune to all spell with level below or equal to value of
+this bonus
+
+### MAGIC_RESISTANCE
+
+- value - percent
+
+### SPELL_DAMAGE_REDUCTION
+
+eg. golems
+
+- value - reduction in %
+- subtype - spell school; -1 - all, 0 - air, 1 - fire, 2 - water, 3 -
+ earth
+
+### MORE_DAMAGE_FROM_SPELL
+
+- value - damage increase in %
+- subtype - spell id
+
+### FIRE_IMMUNITY,WATER_IMMUNITY, EARTH_IMMUNITY, AIR_IMMUNITY
+
+- subtype 0 - all, 1 - all except positive, 2 - only damage spells
+
+### MIND_IMMUNITY
+
+Creature is immune to all mind spells.
+
+### SPELL_IMMUNITY
+
+- subtype - spell id
+- ainfo - 0 - normal, 1 - absolute
+
+### DIRECT_DAMAGE_IMMUNITY
+
+WoG ability. Creature is completely immune to damage spells.
+
+### RECEPTIVE
+
+WoG ability. Creature accepts all friendly spells even though it would
+be normally immune to it.
+
+## Deprecated creature abilities
+
+### DAEMON_SUMMONING
+
+pit lord - removed in VCMI 1.2 as part of major battles refactoring
+
+- subtype - type of creatures
+- val - hp per unit
+
+# Spell effects
+
+### POISON
+
+- val - max health penalty from poison possible
+
+### SLAYER
+
+- value - spell level
+
+### BIND_EFFECT
+
+doesn't do anything particular, works as a marker
+
+### FORGETFULL
+
+forgetfulness spell effect
+
+- value - level
+
+### NOT_ACTIVE
+
+### ALWAYS_MINIMUM_DAMAGE
+
+unit does its minimum damage from range
+
+- subtype: -1 - any attack, 0 - melee, 1 - ranged
+- value: additional damage penalty (it'll subtracted from dmg)
+- additional info - multiplicative anti-bonus for dmg in % \[eg 20
+ means that creature will inflict 80% of normal minimal dmg\]
+
+### ALWAYS_MAXIMUM_DAMAGE
+
+eg. bless effect
+
+- subtype: -1 - any attack, 0 - melee, 1 - ranged
+- value: additional damage
+- additional info - multiplicative bonus for dmg in %
+
+### ATTACKS_NEAREST_CREATURE
+
+while in berserk
+
+### IN_FRENZY
+
+- value - level
+
+### HYPNOTIZED
+
+### NO_RETALIATION
+
+Eg. when blinded or paralyzed.
\ No newline at end of file
diff --git a/docs/modders/Bonus/Bonus_Updaters.md b/docs/modders/Bonus/Bonus_Updaters.md
new file mode 100644
index 000000000..20d6ae3d2
--- /dev/null
+++ b/docs/modders/Bonus/Bonus_Updaters.md
@@ -0,0 +1,85 @@
+< [Documentation](../../Readme.md) / [Modding](../Readme.md) / [Bonus Format](../Bonus_Format.md) / Bonus Updaters
+
+# List of Bonus Updaters
+
+Updaters come in two forms: simple and complex. Simple updaters take no
+parameters and are specified as strings. Complex updaters do take
+parameters (sometimes optional), and are specified as structs.
+
+Check the files in *config/heroes/* for additional usage examples.
+
+## GROWS_WITH_LEVEL
+
+- Type: Complex
+- Parameters: valPer20, stepSize=1
+- Effect: Updates val to
+
+` ceil(valPer20 * floor(heroLevel / stepSize) / 20)`
+
+Example: The following updater will cause a bonus to grow by 6 for every
+40 levels. At first level, rounding will cause the bonus to be 0.
+
+` "updater" : {`
+` "parameters" : [ 6, 2 ],`
+` "type" : "GROWS_WITH_LEVEL"`
+` }`
+
+Example: The following updater will cause a bonus to grow by 3 for every
+20 levels. At first level, rounding will cause the bonus to be 1.
+
+` "updater" : {`
+` "parameters" : [ 3 ],`
+` "type" : "GROWS_WITH_LEVEL"`
+` }`
+
+Remarks:
+
+- The rounding rules are designed to match the attack/defense bonus
+ progression for heroes with creature specialties in HMM3.
+- There is no point in specifying val for a bonus with a
+ GROWS_WITH_LEVEL updater.
+
+## TIMES_HERO_LEVEL
+
+- Type: Simple
+- Effect: Updates val to
+
+` val * heroLevel`
+
+Usage:
+
+` "updater" : "TIMES_HERO_LEVEL"`
+
+Remark: This updater is redundant, in the sense that GROWS_WITH_LEVEL
+can also express the desired scaling by setting valPer20 to 20\*val. It
+has been added for convenience.
+
+## TIMES_STACK_LEVEL
+
+- Type: Simple
+- Effect: Updates val to
+
+` val * stackLevel`
+
+Usage:
+
+` "updater" : "TIMES_STACK_LEVEL"`
+
+Remark: The stack level for war machines is 0.
+
+## ARMY_MOVEMENT
+
+- Type: Complex
+- Parameters: basePerSpeed, dividePerSpeed, additionalMultiplier,
+ maxValue
+- Effect: Updates val to val+= max((floor(basePerSpeed /
+ dividePerSpeed)\* additionalMultiplier), maxValue)
+- Remark: this updater is designed for MOVEMENT bonus to match H3 army
+ movement rules (in the example - actual movement updater, which
+ produces values same as in default movement.txt).
+- Example:
+
+` "updater" : {`
+` "parameters" : [ 20, 3, 10, 700 ],`
+` "type" : "ARMY_MOVEMENT"`
+` }`
diff --git a/docs/modders/Bonus/Bonus_Value_Types.md b/docs/modders/Bonus/Bonus_Value_Types.md
new file mode 100644
index 000000000..8cedfb28a
--- /dev/null
+++ b/docs/modders/Bonus/Bonus_Value_Types.md
@@ -0,0 +1,33 @@
+< [Documentation](../../Readme.md) / [Modding](../Readme.md) / [Bonus Format](../Bonus_Format.md) / Bonus Value Types
+
+Total value of Bonus is calculated using the following:
+
+- For each bonus source type we calculate new source value (for all
+ bonus value types except PERCENT_TO_SOURCE and
+ PERCENT_TO_TARGET_TYPE) using the following:
+
+` newVal = (val * (100 + PERCENT_TO_SOURCE) / 100))`
+
+PERCENT_TO_TARGET_TYPE applies as PERCENT_TO_SOURCE to targetSourceType
+of bonus.
+
+- All bonus value types summarized and then used as subject of the
+ following formula:
+
+` clamp(((BASE_NUMBER * (100 + PERCENT_TO_BASE) / 100) + ADDITIVE_VALUE) * (100 + PERCENT_TO_ALL) / 100), INDEPENDENT_MAX, INDEPENDENT_MIN)`
+
+As for 1.2, semantics of INDEPENDENT_MAX and INDEPENDENT_MIN are
+wrapped, and first means than bonus total value will be at least
+INDEPENDENT_MAX, and second means than bonus value will be at most
+INDEPENDENT_MIN.
+
+# List of all bonus value types
+
+- ADDITIVE_VALUE
+- BASE_NUMBER
+- PERCENT_TO_ALL
+- PERCENT_TO_BASE
+- INDEPENDENT_MAX
+- INDEPENDENT_MIN
+- PERCENT_TO_SOURCE (since 1.2)
+- PERCENT_TO_TARGET_TYPE (since 1.2)
\ No newline at end of file
diff --git a/docs/modders/Bonus_Format.md b/docs/modders/Bonus_Format.md
new file mode 100644
index 000000000..9a40b07b7
--- /dev/null
+++ b/docs/modders/Bonus_Format.md
@@ -0,0 +1,100 @@
+< [Documentation](../Readme.md) / [Modding](Readme.md) / Bonus Format
+
+## Full format
+
+All parameters but type are optional.
+
+``` javascript
+{
+ "type": "BONUS_TYPE",
+ "subtype": 0,
+ "val" : 0,
+ "valueType": "VALUE_TYPE",
+ "addInfo" : 0, // or [1, 2, ...]
+
+ "duration" : "BONUS_DURATION", //or ["BONUS_DURATION1", "BONUS_DURATION2", ...]"
+ "turns" : 0,
+
+ "sourceType" : "SOURCE_TYPE",
+ "sourceID" : 0,
+ "effectRange" : "EFFECT_RANGE",
+
+ "limiters" : [
+ "PREDEFINED_LIMITER", optional_parameters (...), //whhich one is preferred?
+ {"type" : LIMITER_TYPE, "parameters" : [1,2,3]}
+ ],
+
+ "propagator" : ["PROPAGATOR_TYPE", optional_parameters (...)],
+ "updater" : {Bonus Updater},
+ "propagationUpdater" : {Bonus Updater, but works during propagation},
+ "description" : "",
+ "stacking" : ""
+}
+```
+
+## Supported bonus types
+
+- [Bonus Duration Types](Bonus/Bonus_Duration_Types.md)
+- [Bonus Sources](Bonus/Bonus_Sources.md)
+- [Bonus Limiters](Bonus/Bonus_Limiters.md)
+- [Bonus Types](Bonus/Bonus_Types.md)
+- [Bonus Propagators](Bonus/Bonus_Propagators.md)
+- [Bonus Updaters](Bonus/Bonus_Updaters.md)
+- [Bonus Range Types](Bonus/Bonus_Range_Types.md)
+- [Bonus Value Types](Bonus/Bonus_Value_Types.md)
+
+## Subtype resolution
+
+All string identifiers of items can be used in "subtype" field. This
+allows cross-referencing between the mods and make config file more
+readable.
+
+### Available prefixes
+
+- creature.
+- artifact.
+- skill:
+``` javascript
+ "pathfinding", "archery", "logistics", "scouting", "diplomacy",
+ "navigation", "leadership", "wisdom", "mysticism", "luck",
+ "ballistics", "eagleEye", "necromancy", "estates", "fireMagic",
+ "airMagic", "waterMagic", "earthMagic", "scholar", "tactics",
+ "artillery", "learning", "offence", "armorer", "intelligence",
+ "sorcery", "resistance", "firstAid"
+```
+
+- resource:
+``` javascript
+ "wood", "mercury", "ore", "sulfur", "crystal", "gems", "gold", "mithril"
+```
+
+- hero.
+- faction.
+- spell.
+- primarySkill
+``` javascript
+ "attack", "defence", "spellpower", "knowledge"
+```
+
+- terrain:
+``` javascript
+ "dirt", "sand", "grass", "snow", "swamp", "rough", "subterra", "lava", "water", "rock"
+```
+
+- spellSchool
+```javascript
+"any", "fire", "air", "water", "earth"
+```
+
+### Example
+
+``` javascript
+"bonus" :
+{
+ "type" : "HATE",
+ "subtype" : "creature.enchanter",
+ "val" : 50
+}
+```
+
+This bonus makes creature do 50% more damage to Enchanters.
\ No newline at end of file
diff --git a/docs/modders/Building_Bonuses.md b/docs/modders/Building_Bonuses.md
new file mode 100644
index 000000000..59804a915
--- /dev/null
+++ b/docs/modders/Building_Bonuses.md
@@ -0,0 +1,171 @@
+< [Documentation](../Readme.md) / [Modding](Readme.md) / Building Bonuses
+
+Work-in-progress page do describe all bonuses provided by town buildings
+for future configuration.
+
+## unique buildings
+
+Hardcoded functionalities, selectable but not configurable. In future
+should be moved to scripting.
+
+Includes:
+
+- mystic pond
+- treasury
+- god of fire
+- castle gates
+- cover of darkness
+- portal of summoning
+- escape tunnel
+
+Function of all of these objects can be enabled by this:
+
+``` javascript
+ "function" : "castleGates"
+```
+
+## trade-related
+
+Hardcoded functionality for now due to complexity of these objects.
+Temporary can be handles as unique buildings. Includes:
+
+- resource - resource
+- resource - player
+- artifact - resource
+- resource - artifact
+- creature - resource
+- resource - skills
+- creature - skeleton
+
+## hero visitables
+
+Buildings that give one or another bonus to visiting hero. All should be
+handled via configurable objects system.
+
+Includes:
+
+- gives mana points
+- gives movement points
+- give bonus to visitor
+- permanent bonus to hero
+
+## generic functions
+
+Generic town-specific functions that can be implemented as part of
+CBuilding class.
+
+### unlock guild level
+
+``` javascript
+ "guildLevels" : 1
+```
+
+### unlock hero recruitment
+
+``` javascript
+ "allowsHeroPurchase" : true
+```
+
+### unlock ship purchase
+
+``` javascript
+ "allowsShipPurchase" : true
+```
+
+### unlock building purchase
+
+``` javascript
+ "allowsBuildingPurchase" : true
+```
+
+### unlocks creatures
+
+``` javascript
+ "dwelling" : { "level" : 1, "creature" : "archer" }
+```
+
+### creature growth bonus
+
+Turn into town bonus? What about creature-specific bonuses from hordes?
+
+### gives resources
+
+``` javascript
+ "provides" : { "gold" : 500 }
+```
+
+### gives guild spells
+
+``` javascript
+ "guildSpells" : [5, 0, 0, 0, 0]
+```
+
+### gives thieves guild
+
+``` javascript
+ "thievesGuildLevels" : 1
+```
+
+### gives fortifications
+
+``` javascript
+ "fortificationLevels" : 1
+```
+
+### gives war machine
+
+``` javascript
+ "warMachine" : "ballista"
+```
+
+## simple bonuses
+
+Bonuses that can be made part of CBuilding. Note that due to how bonus
+system works this bonuses won't be stackable.
+
+TODO: how to handle stackable bonuses like Necromancy Amplifier?
+
+Includes:
+
+- bonus to defender
+- bonus to alliance
+- bonus to scouting range
+- bonus to player
+
+``` javascript
+"bonuses" :
+{
+ "moraleToDefenders" :
+ {
+ "type": "MORALE",
+ "val" : 1,
+ "propagator" : ["VISITED_TOWN_AND_VISITOR"]
+ },
+ "luckToTeam" :
+ {
+ "type" : "LUCK",
+ "val" : 2,
+ "propagator" : [ "TEAM_PROPAGATOR" ]
+ }
+```
+
+## misc
+
+Some other properties of town building that does not fall under "bonus"
+category.
+
+### unique building
+
+Possible issue - with removing of fixed ID's buildings in different town
+may no longer share same ID. However Capitol must be unique across all
+town. Should be fixed somehow.
+
+``` javascript
+ "onePerPlayer" : true
+```
+
+### chance to be built on start
+
+``` javascript
+ "prebuiltChance" : 75
+```
\ No newline at end of file
diff --git a/docs/modders/Campaign_Format.md b/docs/modders/Campaign_Format.md
new file mode 100644
index 000000000..32500d269
--- /dev/null
+++ b/docs/modders/Campaign_Format.md
@@ -0,0 +1,215 @@
+< [Documentation](../Readme.md) / [Modding](Readme.md) / Campaign Format
+
+# Introduction
+
+Starting from version 1.3, VCMI supports its own campaign format.
+Campaigns have *.vcmp file format and it consists from campaign json and set of scenarios (can be both *.vmap and *.h3m)
+
+To start making campaign, create file named `00.json`. See also [Packing campaign](#packing-campaign)
+
+Basic structure of this file is here, each section is described in details below
+```js
+{
+ "version" : 1,
+
+
+
+ "scenarios" : [
+ {
+ //scenario 1
+
+ },
+ {
+ //scenario 2
+
+ }
+ ]
+}
+```
+
+`"version"` defines version of campaign file. Larger versions should have more features and flexibility, but may not be supported by older VCMI engines. See [compatibility table](#compatibility-table)
+
+# Header properties
+
+In header are parameters describing campaign properties
+```js
+ ...
+ "regions": {...},
+ "name": "Campaign name",
+ "description": "Campaign description",
+ "allowDifficultySelection": true,
+```
+
+- `"regions"` contains information about background and regions. See section [campaign regions](#regions-description) for more information
+- `"name"` is a human readable title of campaign
+- `"description"` is a human readable description of campaign
+- `"allowDifficultySelection"` is a boolean field (`true`/`false`) which allows or disallows to choose difficulty before scenario start
+
+# Scenario description
+
+Scenario description looks like follow:
+```js
+{
+ "map": "maps/SomeMap",
+ "preconditions": [],
+ "color": 0,
+ "difficulty": 2,
+ "regionText": "",
+ "prolog": {},
+ "epilog": {},
+ "heroKeeps": [],
+ "keepCreatures": [],
+ "startOptions": "none",
+ "playerColor": 0,
+ "bonuses": [ ]
+}
+```
+
+- `"map"` map name without extension but with relative path. Both *.h3m and *.vmap maps are supported. If you will pack scenarios inside campaign, numerical map name should be used, see details in [packing campaign](#packing-campaign)
+- `"preconditions"` enumerate scenarios indexes which must be completed to unlock this scenario. For example, if you want to make sequential missions, you should specify `"preconditions": []` for first scenario, but for second scenario it should be `"preconditions": [0]` and for third `"preconditions": [0, 1]`. But you can allow non-linear conquering using this parameter
+- `"color"` defines color id for the region. Possible values are `0: red, 1: blue, tan: 2, green: 3, orange: 4, purple: 5, teal: 6, pink: 7`
+- `"difficulty"` sets initial difficulty for this scenario. If `"allowDifficultySelection"`is defined for campaign, difficulty may be changed by player. Possible values are `0: pawn, 1: knight, 2: rook, 3: queen, 4: king`
+- `"regionText"` is a text which will be shown if player holds right button over region
+- `"prolog"`/`"epilog"` optional, defines prolog/epilog for scenario. See [prolog/epilog](#prologepilog) section for more information
+- `"heroKeeps"` defines what hero will carry to the next scenario. Can be specified one or several attributes from list `"experience", "primarySkills", "secondarySkills", "spells", "artifacts"`
+- `"keepCreatures"` array of creature types which hero will carry to the next scenario. Game identifiers are used to specify creature type.
+- `"startOptions"` defines what type of bonuses player may have. Possible values are `"none", "bonus", "crossover", "hero"`
+ - `none`: player starts scenario without bonuses. [Description](#none-start-option)
+ - `bonus`: player chooses one of the predefined bonuses. [Description](#bonus-start-option)
+ - `crossover`: player will start with hero from previous scenario. [Description](#crossover-start-option)
+ - `hero` : player will start scenario with specified hero. [Description](#hero-start-option)
+- `"playerColor"` defines color id of flag which player will play for. Possible values are `0: red, 1: blue, tan: 2, green: 3, orange: 4, purple: 5, teal: 6, pink: 7`
+- "bonuses" array of possible bonus objects, format depends on `"startOptions"` parameter
+
+## Prolog/Epilog
+
+Prolog and epilog properties are optional
+```js
+{
+ "video": "NEUTRALA.smk", //video to show
+ "music": "musicFile.ogg", //music to play, should be located in music directory
+ "text": "some long text" //text to be shown
+}
+```
+
+## Start options and bonuses
+
+### None start option
+
+If `startOptions` is `none`, `bonuses` field will be ignored
+
+### Bonus start option
+
+If `startOptions` is `bonus`, bonus format may vary depending on its type.
+
+```js
+{
+ "what": "",
+
+
+},
+```
+
+- `"what"` field defines bonus type. Possible values are: `spell, creature, building, artifact, scroll, primarySkill, secondarySkill, resource`
+ - `"spell"` has following attributes (fields):
+ - `"hero"`: hero who will get spell (see below)
+ - `"type"`: spell type, string, e.g. "firewall"
+ - `"creature"` has following attributes (fields):
+ - `"hero"`: hero who will get spell (see below)
+ - `"type"`: creature type, string, e.g. "pikeman"
+ - `"amount"`: amount of creatures
+ - `"building"` has following attributes (fields):
+ - `"type"`: building type (string), e.g. "citadel" or "dwellingLvl1"
+ - `"artifact"` has following attributes (fields):
+ - `"hero"`: hero who will get spell (see below)
+ - `"type"`: artifact type, string, e.g. "spellBook"
+ - `"scroll"` has following attributes (fields):
+ - `"hero"`: hero who will get spell (see below)
+ - `"type"`: spell type in the scroll, string, e.g. "firewall"
+ - `"primarySkill"` has following attributes (fields):
+ - `"hero"`: hero who will get spell (see below)
+ - `"attack"`: amount of attack gained
+ - `"defence"`: amount of defence gained
+ - `"spellpower"`: amount of spellpower gained
+ - `"knowledge"`: amount of knowledge gained
+ - `"secondarySkill"` has following attributes (fields):
+ - `"hero"`: hero who will get spell (see below)
+ - `"type"`: skill type, string, e.g. "logistics"
+ - `"amount"`: skill level, `1: beginner, 2: advanced, 3: expert`
+ - `"resource"` has following attributes (fields):
+ - `"type"`: resource type, one of `wood, ore, mercury, sulfur, crystal, gems, gold, common, rare`, where `common` is both wood and ore, `rare` means that bonus gives each rare resource
+ - `"amount"`: amount of resources
+- `"hero"` can be specified as explicit hero name and as one of keywords: `strongest`, `generated`
+
+### Crossover start option
+
+If `startOptions` is `crossover`, heroes from specific scenario will be moved to this scenario. Bonus format is following
+
+```js
+{
+ "playerColor": 0,
+ "scenario": 0
+},
+```
+- `"playerColor"` from what player color heroes shall be taken. Possible values are `0: red, 1: blue, tan: 2, green: 3, orange: 4, purple: 5, teal: 6, pink: 7`
+- `"scenario"` from which scenario heroes shall be taken. 0 means first scenario
+
+### Hero start option
+
+If `startOptions` is `hero`, hero can be chosen as a starting bonus. Bonus format is following
+```js
+{
+ "playerColor": 0,
+ "hero": "random"
+}
+```
+
+- `"playerColor"` from what player color heroes shall be taken. Possible values are `0: red, 1: blue, tan: 2, green: 3, orange: 4, purple: 5, teal: 6, pink: 7`
+- `"hero"` can be specified as explicit hero name and as one of keywords: `random`
+
+## Regions description
+
+Predefined campaign regions are located in file `campaign_regions.json`
+
+```js
+{
+ "prefix": "G3",
+ "color_suffix_length": 1,
+ "desc": [
+ { "infix": "A", "x": 289, "y": 376 },
+ { "infix": "B", "x": 60, "y": 147 },
+ { "infix": "C", "x": 131, "y": 202 }
+ ]
+},
+```
+
+- `"prefix"` used to identify all images related to campaign. In this example, background picture will be `G3_BG`
+- `"inflix"` ised to identify all images related to region. In this example, it will be pictures starting from `G3A_..., G3B_..., G3C_..."`
+- `"color_suffix_length"` identifies suffix length for region colourful frames. 1 is used for `R, B, N, G, O, V, T, P`, value 2 is used for `Re, Bl, Br, Gr, Or, Vi, Te, Pi`
+
+# Packing campaign
+
+After campaign scenarios and campaign description are ready, you should pack them into *.vcmp file.
+This file is basically headless gz archive.
+
+Your campaign should be stored in some folder with json describing campaign information.
+Place all your scenarios inside same folder and enumerate their filenames, e.g `01.vmap`, '02.vmap', etc.
+```
+my-campaign/
+|-- 00.json
+|-- 01.vmap
+|-- 02.vmap
+|-- 03.vmap
+```
+
+If you use unix system, execute this command to pack your campaign:
+```
+gzip -c -n ./* >> my-campaign.vcmp
+```
+
+If you are using Windows system, try this https://gnuwin32.sourceforge.net/packages/gzip.htm
+
+# Compatibility table
+| Version | Min VCMI | Max VCMI | Description |
+|---------|----------|----------|-------------|
+| 1 | 1.3 | | Initial release |
\ No newline at end of file
diff --git a/docs/modders/Configurable_Widgets.md b/docs/modders/Configurable_Widgets.md
new file mode 100644
index 000000000..d13af3a64
--- /dev/null
+++ b/docs/modders/Configurable_Widgets.md
@@ -0,0 +1,835 @@
+< [Documentation](../Readme.md) / [Modding](Readme.md) / Configurable Widgets
+
+# Table of contents
+
+- [Introduction](#introduction)
+- [Tutorial](#tutorial)
+- [Documentation](#documentation)
+ - [Types](#types)
+ - [Configurable objects](#configurable-objects)
+ - [Basic widgets](#basic-widgets)
+ - [High-level widgets](#high-level-widgets)
+ - [Custom widgets](#custom-widgets)
+- [For developers](#for-developers)
+
+# Introduction
+
+VCMI has capabilities to change some UI elements in your mods beyond only replacing one image with another. Not all UI elements are possible to modify currently, but development team is expanding them.
+
+Elements possible to modify are located in `config/widgets`.
+
+# Tutorial
+
+Let's take `extendedLobby` mod from `vcmi-extras` as an example for VCMI-1.4. [Example sources](https://github.com/vcmi-mods/vcmi-extras/tree/vcmi-1.4/Mods/extendedLobby).
+
+**You can take all assets from this tutorial from sources.**
+
+This submod offers extended options while player creates new game.
+For random map tab it defines UI to select RMG template, select map size bigger than XL, configure teams and roads.
+For options tab it introduces UI for chess timers.
+
+In this tutorial we will recreate options tab to support chess timers UI.
+
+## Creating mod structure
+
+To start making mod, create following folders structure;
+```
+extendedLobby/
+|- content/
+| |- sprites/
+| |- config/
+| | |- widgets/
+|- mod.json
+```
+
+File `mod.json` is generic and could look like this:
+```json
+{
+ "name" : "Configurable UI tutorial mod",
+ "description" : "See tutorial here https://github.com/vcmi/vcmi/wiki/Configurable-UI-widgets",
+ "version" : "0.1",
+ "modType" : "Interface",
+ "compatibility":
+ {
+ "min" : "1.4.0"
+ },
+}
+```
+
+After that you can copy `extendedLobby/ folder to `mods/` folder and your mod will immediately appear in launcher but it does nothing for now.
+
+## Making layout for timer
+
+Let's copy `config/widgets/optionsTab.json` file from VCMI folder to `content/config/widgets/` folder from our mod.
+It defines UI for options tab as it designed in original game, we will keep everything related to player settings and will modify only timer area.
+
+**It's important, that when you are modifying `optionsTab.json`, game restart is not needed! When you updated file, it's enough to go back to main menu and then open lobby and options again. However, when you add new assets (images), you have to restart game to make possible find them.**
+
+It looks like on image below and has 3 elements: label with "Player Turn Duration", label with timer duration ("Unlimited" on picture) and slider to control timer.
+
+
+
+So we need to modify turn duration label and add combo box with timer types
+
+
+
+Open `optionsTab.json` and scroll it until you see comment `timer`. Three elements after this comment are related to timer.
+
+Let's find first element, which is label
+```json
+{
+ "items"
+ [
+ ...
+ // timer
+ {
+ "type": "label",
+ "font": "small",
+ "alignment": "center",
+ "color": "yellow",
+ "text": "core.genrltxt.521",
+ "position": {"x": 222, "y": 544}
+ },
+ ...
+ ],
+ ...
+}
+```
+
+And modify it a bit
+```json
+{
+ "name": "labelTimer", //add name, only for convenience
+ "type": "label",
+ "font": "small",
+ "alignment": "center",
+ "color": "yellow",
+ "text": "vcmi.optionsTab.widgets.labelTimer", //replace text
+ "position": {"x": 104, "y": 542} //move to the left
+},
+```
+
+But we also need proper background image for this label. Add image widget BEFORE labelTimer widget:
+```json
+{
+ "type": "picture",
+ "image": "RmgTTBk",
+ "position": {"x": 54, "y": 532}
+},
+{
+ "name": "labelTimer", //add name, only for convenience
+ ...
+},
+```
+In order to make it work, add file `RmgTTBk.bmp` to `content/sprites/`
+
+Elements named `labelTurnDurationValue` and `sliderTurnDuration` we will keep without change - they are needed to configure classic timer.
+
+## Adding combo box
+
+Now, let's add combo box.
+
+Copy image `DrDoCoBk.bmp` to `content/sprites/`. Button objects use animated images to show different button states.
+For normal, pressed, blocked and highlighted. Our combo box inherits this behavior, so let's convert image to animation.
+In order to do it, we need to create file `DrDoCoBk.json` in same folder `content/sprites/` with following content:
+
+```json
+{
+ "sequences" :
+ [
+ {
+ "group" : 0,
+ "frames" :
+ [
+ "DrDoCoBk.bmp"
+ ]
+ }
+ ]
+}
+```
+
+Thus we created file with animation, containing single frame which can be used for combo box.
+
+Let's add one more element after `//timer` comment:
+
+```json
+...
+//timer
+{
+ "name": "timerModeSwitch", //this is important to name it timerModeSwitch, because VCMI binds behavior to element called this way
+ "type": "comboBox",
+ "image": "DrDoCoBk",
+ "position": {"x": 158, "y": 532},
+ "imageOrder": [0, 0, 0, 0],
+ "dropDown": {}, //here will be defined elements to be shown in drop down list
+},
+```
+
+`imageOrder` helps VCMI to understand, which frame from animation to use in normal, pressed, blocked and highlighted states. In our case they will be same and we use 0 frame from `DrDoCoBk` animation.
+
+We also want to have label on the top of this combo box showing which element is selected. You need to add `items` array, where additional elements can be specified, label in our case:
+
+```json
+...
+//timer
+{
+ "name": "timerModeSwitch",
+ "type": "comboBox",
+ "image": "DrDoCoBk",
+ "position": {"x": 158, "y": 532},
+ "imageOrder": [0, 0, 0, 0],
+ "dropDown": {}, //here will be defined elements to be shown in drop down list
+ "items":
+ [
+ {
+ "name": "timer",
+ "type": "label",
+ "font": "small",
+ "alignment": "left",
+ "color": "yellow",
+ "text": "vcmi.optionsTab.widgets.timerModeSwitch.classic" //default value for timer label
+ }
+ ]
+},
+```
+
+With that we already have desired layout with all elements shown by default, but we also need to add elements with timer modes into drop-down list:
+
+
+
+First of all, add images to `content/sprites/` folder: `List2Bk.bmp` for drop-down background and `List10Sl.bmp` for element highlighting.
+
+Now specify items inside `dropDown` field
+
+```json
+"dropDown":
+{
+ "items":
+ [
+ {
+ "name": "background",
+ "type": "picture",
+ "image": "List2Bk",
+ "position": {"x": 0, "y": -52} //negative value because our drop-down shall open in the top direction
+ },
+
+ {
+ "name": "slider", //let's add slider if we have more elements in future
+ "type": "slider",
+ "position": {"x": 212, "y": -52},
+ "size": 52,
+ "style": "blue",
+ "itemsVisible": 2, //we show only two elements
+ "itemsTotal": 0,
+ "selected": 0,
+ "orientation": "vertical",
+ "callback": "sliderMove" //callback predefined for drop-down menu to control which elements to show
+ },
+
+ //now list elements
+ { //classic timer
+ "type": "item", //this is special type for drop-down elements
+ "position": {"x": 0, "y": -52},
+ "items": //each element may have several elements
+ [
+ {
+ "type": "label",
+ "name": "labelName",
+ "font": "small",
+ "alignment": "left",
+ "color": "white",
+ "position": {"x": 4, "y": 0},
+ "text": "vcmi.optionsTab.widgets.timerModeSwitch.classic"
+ },
+ {
+ "type": "picture",
+ "name": "hoverImage", //"hoverImage" is a key word, helping VCMI to understand which element to show when cursor hovers element
+ "visible": false, //invisible by default
+ "image": "List10Sl"
+ }
+ ]
+ },
+
+ { //chess timer
+ "type": "item",
+ "position": {"x": 0, "y": -27},
+ "items":
+ [
+ {
+ "type": "label",
+ "name": "labelName",
+ "font": "small",
+ "alignment": "left",
+ "color": "white",
+ "position": {"x": 4, "y": 0},
+ "text": "vcmi.optionsTab.widgets.timerModeSwitch.chess"
+ },
+ {
+ "type": "picture",
+ "name": "hoverImage",
+ "visible": false,
+ "image": "List10Sl"
+ }
+ ]
+ },
+ ]
+},
+```
+
+Now we can press drop-down menu and even select elements.
+
+## Switching timer modes
+
+After view part is done, let's make behavioural part.
+Let's hide elements, related to classic timer when chess timer is selected and show them back if classic selected.
+
+To do that, find `"variables"` part inside `optionsTab.json` and add there `"timers"` array, containing 2 elements:
+```json
+"variables":
+{
+ "timers":
+ [
+ { //variables used if first element is chosen
+ "text": "vcmi.optionsTab.widgets.timerModeSwitch.classic",
+ "showWidgets": ["labelTurnDurationValue", "sliderTurnDuration"],
+ "hideWidgets": [],
+ },
+
+ { //variables used if second element is chosen
+ "text": "vcmi.optionsTab.widgets.timerModeSwitch.chess",
+ "showWidgets": [],
+ "hideWidgets": ["labelTurnDurationValue", "sliderTurnDuration"],
+ },
+ ],
+ "timerPresets" :
+ [
+ ...
+ ]
+}
+```
+
+Now we show and hide elements, but visually you still can some "artifacts":
+
+
+
+It's because options tab background image we use has those elements drawn. Let's hide them with overlay image `timchebk.bmp`.
+It should be drawn before all other timer elements:
+
+```json
+...
+// timer
+{
+ "name": "timerBackground",
+ "type": "picture",
+ "image": "timchebk",
+ "position": {"x": 0, "y": 530}
+},
+
+{
+ "name": "timerModeSwitch",
+ ...
+ },
+...
+```
+
+This background must be visible for chess timer and hidden for classic timer. Just put its name `"timerBackground"` into `"hideWidgets"` and `"showWidgets"` for corresponding elements.
+
+It works and can switch elements, the only missing part is chess timer configuration.
+
+## Chess timer configuration
+
+We should add text input fields, to specify different timers. We will use background for them `timerField.bmp`, copy it to `content/sprites/` folder of your mod.
+
+There are 4 different timers: base, turn, battle and creature. Read about them here: https://github.com/vcmi/vcmi/issues/1364
+We can add editors for them into items list, their format will be following:
+```json
+{
+ "name": "chessFieldBase",
+ "type": "textInput",
+ "background": "timerField",
+ "alignment": "center",
+ "text": "00:00", //default text
+ "rect": {"x": 54, "y": 557, "w": 84, "h": 25},
+ "offset": {"x": 0, "y": 0},
+ "callback": "parseAndSetTimer_base", //callback to specify base timer value from string
+ "help": "vcmi.optionsTab.widgets.chessFieldBase.help"
+},
+```
+
+Add three remaining elements for different timers by yourself. You can play with all settings, except callback. There are 4 predefined callbacks to setup timers:
+- `parseAndSetTimer_base`
+- `parseAndSetTimer_turn`
+- `parseAndSetTimer_battle`
+- `parseAndSetTimer_creature`
+
+And what we want to do is to hide/show those fields when classic/chess times is selected. Just add names of those elements into corresponding variables `"showWidgets"`, `"hideWidgets".
+
+We are done! You can find more information about configurable UI elements in documentation section.
+
+# Documentation
+
+## Types
+
+All fields have format `"key": value`
+There are different basic types, which can be used as value.
+
+### Primitive types
+
+Read JSON documentation for primitive types description: https://www.json.org/json-en.html
+
+### Text
+
+Load predefined text which can be localised, examples:
+`"vcmi.otherOptions.availableCreaturesAsDwellingLabel"`
+`"core.genrltxt.738"`
+
+### Position
+
+Point with two coordinates, example:
+`{ "x": 43, "y": -28 }`
+
+### Rect
+
+Rectangle ares, example:
+`{ "x": 28, "y": 220, "w": 108, "h": 50 }`
+
+### Text alignment
+
+Defines text alignment, can be one of values:
+`"center"`, `"left"`, `"right"`
+
+### Color
+
+Predefined colors:
+`"yellow"`, `"white"`, `"gold"`, `"green"`, `"orange"`, `"bright-yellow"`
+
+To have custom color make an array of four elements in RGBA notation:
+`[255, 128, 0, 255]`
+
+### Font
+
+Predefined fonts:
+`"big"`, `"medium"`, `"small"`, `"tiny"`, `"calisto"`
+
+### Hint text
+
+Hint text is a pair of strings, one is usually shown in status bar when cursor hovers element, another hint while right button pressed.
+Each of elements is a [Text](#text)
+
+```
+{
+ "hover": "Text",
+ "help": "Text
+}
+```
+
+If one string specified, it will be applied for both hover and help.
+
+`"text"`
+
+### Shortcut
+
+String value defines shortcut. Some examples of shortcuts:
+`"globalAccept", "globalCancel", "globalReturn","globalFullscreen", "globalOptions", "globalBackspace", "globalMoveFocus"`
+
+Full list is TBD
+
+### [VCMI-1.4] Player color
+
+One of predefined values:
+`"red"`, `"blue"`, `"tan"`, `"green"`, `"orange"`, `"purple"`, `"teal"`, `"pink"`
+
+## Configurable objects
+
+Configurable object has following structure:
+```json
+{
+ "items": [],
+ "variables": {}, //optional
+ "customTypes": {}, //optional
+ "library": {} //optional
+}
+```
+
+`items` - array of widgets to be created. Widgets are created in sequentially in same order as they described.
+
+`variables` - variables, which can be used by object. Meaningful variable names are predefined for each object
+
+`customTypes` - description of custom widgets, which can be used for this object, see [Custom widgets](#custom-widgets)
+
+`library` - same as above, but custom widgets are described in separate json, this parameter should contain path to library json is specified
+
+## Basic widgets
+
+### Label
+
+`"type": "label"`
+
+`"name": "string"` optional, object name
+
+`"font"`: [font](#font)
+
+`"alignment"`: [alignment](#text-alignment),
+
+`"color"`: [color](#color),
+
+`"text"`: [text](#text),
+
+`"position"`: [position](#position)
+
+### [VCMI-1.4] Multi-line label
+
+`"type": "multiLineLabel"`
+
+`"name": "string"` optional, object name
+
+`"font"`: [font](#font)
+
+`"alignment"`: [alignment](#text-alignment),
+
+`"color"`: [color](#color),
+
+`"text"`: [text](#text),
+
+`"position"`: [position](#position)
+
+`"rect"`: [rect](#rect) //text area
+
+`"adoptHeight": bool` //if true, text area height will be adopted automatically based on content
+
+### Label group
+
+`"type": "labelGroup"`
+
+`"name": "string"` optional, object name
+
+`"font"`: [font](#font)
+
+`"alignment"`: [alignment](#text-alignment),
+
+`"color"`: [color](#color),
+
+`"items": []` array of elements
+
+**Label group item**
+
+`"position"`: [position](#position)
+
+`"text"`: [text](#text),
+
+### Picture
+
+`"type": "picture"`
+
+`"name": "string"` optional, object name
+
+`"position"`: [position](#position)
+
+`"image": string`, specify filename
+
+`"visible": bool`, optional
+
+`"playerColored", bool`, optional, if true will be colorised to current player
+
+### Image
+
+Use to show single frame from animation
+
+`"type": "image"`
+
+`"name": "string"` optional, object name
+
+`"position"`: [position](#position)
+
+`"image": string`, specify filename, animation only (def, json)
+
+`"group": integer` optional, specify animation group
+
+`"frame": integer` optional, specify animation frame
+
+### Texture
+
+Filling area with texture
+
+`"type": "texture"`
+
+`"name": "string"` optional, object name
+
+`"image": string`, specify filename
+
+`"rect"`: [rect](#rect)
+
+### Animation
+
+`"type": "animation"`
+
+`"name": "string"` optional, object name
+
+`"position"`: [position](#position)
+
+`"image": string`, specify filename, animation only (def, json)
+
+`"repeat": bool`, play only once or repeat animation
+
+`"group": integer` optional, specify animation group
+
+`"alpha": integer` optional, specify alpha opacity
+
+`"callback": string` optional, callback to be called after animation complete
+
+`"frames": []` optional, array of frame ranges to show
+
+**Frame range**
+
+`"start": integer`, first frame
+
+`"end": integer`, last frame
+
+### [VCMI-1.4] Text input
+
+`"type": "textInput"`
+
+`"name": "string"` optional, object name
+
+`"rect"`: [rect](#rect)
+
+`"backgroundOffset": [position](#position)
+
+`"background": string`, specify filename
+
+`"font"`: [font](#font)
+
+`"alignment"`: [alignment](#text-alignment),
+
+`"color"`: [color](#color),
+
+`"text": string` optional, default text. Translations are not supported
+
+`"position"`: [position](#position)
+
+`"help"`: [hint](#hint-text)
+
+`"callback": string` optional, callback to be called on text changed. Input text is passed to callback function as an argument.
+
+### Button
+
+`"type": "button"`
+
+`"name": "string"` optional, object name
+
+`"position"`: [position](#position)
+
+`"image": string`, specify filename, animation only (def, json)
+
+`"help"`: [hint](#hint-text)
+
+`"imageOrder": []` array of 4 integers, each is responsible for frame to be shown in different states: normal, pressed, blocked and highlighted
+
+`"borderColor"`: [color](#color), optional
+
+`"hotkey"`: [shortcut](#shortcut), optional
+
+`"callback": string` optional, callback to be called on press. No arguments are passed to callback function.
+
+`"items": []` array of widgets to be shown as overlay (caption [label](#label), for example)
+
+### Toggle button
+
+`"type": "toggleButton"`
+
+`"name": "string"` optional, object name
+
+`"position"`: [position](#position)
+
+`"image": string`, specify filename, animation only (def, json)
+
+`"help"`: [hint](#hint-text)
+
+`"imageOrder": []` array of 4 integers, each is responsible for frame to be shown in different states: normal, pressed, blocked and highlighted
+
+`"callback": string` optional, callback to be called on selection. Toggle identifier is passed to callback function as an argument.
+
+`"selected": bool`, optional, is selected by default
+
+`"items": []` array of widgets to be shown as overlay (caption [label](#label), for example)
+
+### Toggle group
+
+Group of [toggle buttons](#toggle-button), when one is selected, other will be de-selected
+
+`"type": "toggleGroup"`
+
+`"name": "string"` optional, object name
+
+`"position"`: [position](#position)
+
+`"callback": string` optional, callback to be called when one of toggles is selected
+
+`"items": []` array of [toggle buttons](#toggle-button)
+
+### Slider
+
+`"type": "slider"`
+
+`"name": "string"` optional, object name
+
+`"position"`: [position](#position)
+
+`"size": integer` size in pixels
+
+`"style": string`, can be `"brown"` or `"blue"`
+
+`"itemsVisible": integer`, how many items are visible
+
+`"itemsTotal": integer`, how many items in total
+
+`"selected": integer`, current state for slider
+
+`"orientation" string`, can be `"horizontal"` or `"vertical"`
+
+`"callback": string` callback to be called on state change. Slider position is passed to callback function as an argument.
+
+`"scrollBounds":` [rect](#rect), optional
+
+`"panningStep": integer`, optional
+
+### Combo box
+
+`"type": "comboBox"`
+
+`"name": "string"` optional, object name
+
+`"position"`: [position](#position)
+
+`"image": string`, specify filename, animation only (def, json)
+
+`"help"`: [hint](#hint-text)
+
+`"imageOrder": []` array of 4 integers, each is responsible for frame to be shown in different states: normal, pressed, blocked and highlighted
+
+`"borderColor"`: [color](#color), optional
+
+`"hotkey"`: [shortcut](#shortcut), optional
+
+`"items": []` array of widgets to be shown as overlay, for example, [label](#label)
+
+`"dropDown" : {}` description of [drop down](#drop-down) menu widget
+
+### Drop down
+
+Used only as special object for [combo box](#combo-box)
+
+`"items": []` array of widgets to be built. Usually contains background [picture](#picture), [slider](#slider) and item elements.
+
+**Item elements**
+
+`"type": "item"`
+
+`"name": "string"` optional, object name
+
+`"position"`: [position](#position)
+
+`"items": []` array of overlay widgets with certain types and names:
+ - `"name": "hoverImage"`, `"type": ` [picture](#picture) - image to be shown when cursor hovers elements
+ - `"name": "labelName"`, `"type": ` [label](#label) - element caption
+
+**Callbacks**
+ - `sliderMove` connect to slider callback to correctly navigate over elements
+
+### Layout
+
+`"type": "layout"`
+
+`"name": "string"` optional, object name
+
+## High-level widgets
+
+## Custom widgets
+
+# For developers
+
+While designing a new element, you can make it configurable to reuse all functionality described above. It will provide flexibility to further changes as well as modding capabilities.
+
+Class should inherit `InterfaceObjectConfigurable`.
+```C++
+#include "gui/InterfaceObjectConfigurable.h" //assuming we are in client folder
+
+class MyYesNoDialog: public InterfaceObjectConfigurable
+{
+}
+```
+
+`InterfaceObjectConfigurable` doesn't have default constructor, but has possibility to specify arguments to be passed to `CIntObject`.
+
+To make new object work, it's sufficient to define constructor, which receives const reference to `JsonNode`.
+
+```C++
+MyYesNoDialog::MyYesNoDialog(const JsonNode & config):
+ InterfaceObjectConfigurable(), //you can pass arguments same as for CIntObject
+{
+ //register custom builders
+ REGISTER_BUILDER("MyItem", &MyYesNoDialog::buildMyItem);
+
+ //add callbacks which can be used by widgets
+ addCallback("okPressed", std::bind(&MyYesNoDialog::onOk, this, std::placeholders::_1));
+ addCallback("cancelPressed", std::bind(&MyYesNoDialog::onCancel, this, std::placeholders::_1));
+
+ build(config); //after this point all widgets are built and accessible
+
+ //access widgets by name
+ if(auto w = widget("cancel"))
+ {
+ //now you can do something with button
+ }
+}
+```
+
+## Callbacks
+
+## Custom widgets
+
+You can build custom widgets, related to your UI element specifically. Like in example above, there is Item widget, which can be also used on JSON config.
+
+```C++
+REGISTER_BUILDER("myItem", &MyYesNoDialog::buildMyItem);
+```
+
+You have to define function, which takes JsonNode as an argument and return pointer to built widget
+
+```C++
+std::shared_ptr MyYesNoDialog::buildMyItem(const JsonNode & config)
+{
+ auto position = readPosition(config["position"]);
+ return std::make_shared(*this, position); //define Item object as you want
+}
+```
+
+After that, if your JSON file has items with type "MyItem", the new Item element will be constructed.
+
+```json
+{
+ "items":
+ [
+ {
+ "type": "myItem",
+ "position": {"x": 100, "y": 50}
+ }
+ ]
+}
+```
+
+## Variables
+
+After calling `build(config)` variables defined in config JSON file become available. You can interpret them and use in callbacks or in element code
+
+```C++
+build(config);
+
+if(variables["colorfulText"].Bool())
+{
+ if(auto w = widget("text"))
+ {
+ w->setColor(getMyPlayerColor()); //for reference only, getMyPlayerColor is not defined
+ }
+}
+```
diff --git a/docs/modders/Entities_Format/Artifact_Format.md b/docs/modders/Entities_Format/Artifact_Format.md
new file mode 100644
index 000000000..f29274109
--- /dev/null
+++ b/docs/modders/Entities_Format/Artifact_Format.md
@@ -0,0 +1,65 @@
+< [Documentation](../../Readme.md) / [Modding](../Readme.md) / Entities Format / Artifact Format
+
+Artifact bonuses use [Bonus Format](../Bonus_Format.md)
+
+TODO:
+
+- Artifacts growing with Commander level
+
+## Required data
+
+In order to make functional artifact you also need:
+
+- Icon for hero inventory (1 image)
+- Icon for popup windows (1 image, optional)
+- Animation for adventure map (1 animation)
+
+## Format
+
+``` javascript
+{
+ //what kind of bearer can use this artifact
+ "type": ["HERO", "CREATURE", "COMMANDER"]
+
+ //TREASURE, MINOR, MAJOR, RELIC, SPECIAL
+ "class": "TREASURE",
+
+ //SHOULDERS, NECK, RIGHT_HAND, LEFT_HAND, TORSO, RIGHT_RING, LEFT_RING, FEET, MISC1, MISC2, MISC3, MISC4,
+ //MACH1, MACH2, MACH3, MACH4, SPELLBOOK, MISC5
+ //also possible MISC, RING
+ "slot": "HEAD",
+
+ //based on ARTRAITS.txt
+ "value": 12000,
+
+ "text":
+ {
+ "name": "Big Sword",
+ "description": "Big sword gived +10 attack to hero",
+ "event": "On your travel, you stumble upon big sword. You dust it off and stick in your backpack"
+ },
+ "graphics":
+ {
+ "image": "BigSword.png",
+ "large": "BigSword_large.png",
+ //def file for adventure map
+ "map": "BigSword.def"
+ },
+ "bonuses":
+ {
+ Bonus_1,
+ Bonus_2
+ },
+
+ //optional, for combined artifacts only
+ "components":
+ [
+ "artifact1",
+ "artifact2",
+ "artifact3"
+ ],
+
+ //if set with artifact works like war machine
+ "warMachine" : "some.creature"
+}
+```
\ No newline at end of file
diff --git a/docs/modders/Entities_Format/Battle_Obstacle_Format.md b/docs/modders/Entities_Format/Battle_Obstacle_Format.md
new file mode 100644
index 000000000..e0d64eeb4
--- /dev/null
+++ b/docs/modders/Entities_Format/Battle_Obstacle_Format.md
@@ -0,0 +1,3 @@
+< [Documentation](../../Readme.md) / [Modding](../Readme.md) / Entities Format / Battle Obstacle Format
+
+TODO
\ No newline at end of file
diff --git a/docs/modders/Entities_Format/Battlefield_Format.md b/docs/modders/Entities_Format/Battlefield_Format.md
new file mode 100644
index 000000000..bdbc098c5
--- /dev/null
+++ b/docs/modders/Entities_Format/Battlefield_Format.md
@@ -0,0 +1,3 @@
+< [Documentation](../../Readme.md) / [Modding](../Readme.md) / Entities Format / Battlefield Format
+
+TODO
\ No newline at end of file
diff --git a/docs/modders/Entities_Format/Creature_Format.md b/docs/modders/Entities_Format/Creature_Format.md
new file mode 100644
index 000000000..ce4268691
--- /dev/null
+++ b/docs/modders/Entities_Format/Creature_Format.md
@@ -0,0 +1,195 @@
+< [Documentation](../../Readme.md) / [Modding](../Readme.md) / Entities Format / Creature Format
+
+## Required data
+
+In order to make functional creature you also need:
+
+### Animation
+
+- Battle animation (1 def file)
+- Set of rendered projectiles (1 def files, shooters only)
+- Adventure map animation (1 def file)
+
+### Images
+
+- Small portrait for hero exchange window (1 image)
+- Large portrait for hero window (1 image)
+
+### Sounds
+
+- Set of sounds (up to 8 sounds)
+
+## Format
+
+``` javascript
+// camelCase unique creature identifier
+"creatureName" :
+{
+ // translatable names
+ "name" :
+ {
+ "singular" : "Creature",
+ "plural" : "Creatures"
+ },
+ "level" : 0,
+
+ // if set to true creature will not appear in-game randomly (e.g. as neutral creature)
+ "special" : true,
+
+ // config name of faction. Examples: castle, rampart
+ "faction" : "",
+ // cost to recruit, zero values can be omitted.
+ "cost" :
+ {
+ "wood" : 0,
+ "mercury" : 0,
+ "ore" : 0,
+ "sulfur" : 0,
+ "crystal" : 0,
+ "gems" : 0,
+ "gold" : 0
+ },
+ // "value" of creature, used to determine for example army strength
+ "fightValue" : 0,
+
+ // "ai value" - how valuable this creature should be for AI
+ "aiValue" : 0,
+
+ // normal growth in town or external dwellings
+ "growth" : 0,
+
+ // growth bonus from horde building
+ // TODO: reconsider need of this field after configurable buildings support
+ "hordeGrowth" : 0,
+
+ // Creature stats in battle
+ "attack" : 0,
+ "defense" : 0,
+ "hitPoints" : 0,
+ "shots" : 0,
+ "speed" : 0,
+ "damage" :
+ {
+ "min" : 0,
+ "max" : 0
+ },
+ // spellpoints this creature has, how many times creature may cast its spells
+ "spellPoints" : 0,
+ // initial size of creature army on adventure map
+ "advMapAmount" :
+ {
+ "min" : 0,
+ "max" : 0
+ },
+
+ // Creature to which this creature can be upgraded
+ // Note that only one upgrade can be available from UI
+ "upgrades" :
+ [
+ "anotherCreature"
+ ],
+
+ // Creature is 2-tiles in size on the battlefield
+ "doubleWide" : false,
+
+ // All creature abilities, using bonus format
+ "abilities" :
+ [
+ "someName1" : Bonus Format,
+ "someName2" : Bonus Format
+ ],
+
+ "hasDoubleWeek": true,
+
+ "graphics" :
+ {
+ // name of file with creature battle animation
+ "animation" : "",
+ // adventure map animation def
+ "map" : "",
+ // path to small icon for tooltips & hero exchange window
+ "iconSmall" : "",
+ // path to large icon, used on town screen and in hero screen
+ "iconLarge" : "",
+
+ // animation parameters
+
+ // how often creature should play idle animation
+ "timeBetweenFidgets" : 1.00,
+ // unused H3 property
+ "troopCountLocationOffset" : 0,
+ "animationTime" :
+ {
+ // movement animation time.
+ "walk" : 1.00,
+
+ // idle animation time. For H3 creatures this value is always 10
+ "idle" : 10.00,
+
+ // ranged attack animation time. Applicable to shooting and casting animation
+ // NOTE: does NOT affects melee attacks
+ // This is H3 behaviour, for proper synchronization of attack/defense animations
+ "attack" : 1.00,
+
+ // How far flying creature should move during one "round" of movement animation
+ // This is multiplier to base value (200 pixels)
+ "flight" : 1.00
+ },
+ "missile" :
+ {
+ // name of file for missile
+ "animation" : "",
+
+ // (VCMI 1.1 or later only) indicates that creature uses ray animation for ranged attacks instead of missile image (e.g. Evil Eye)
+ "ray" :
+ [
+ { // definition of first (top-most) line in the ray
+ "start" : [ 160, 192, 0, 255 ], // color (RGBA components) of ray at starting point
+ "end" : [ 160, 192, 0, 64 ] // color (RGBA components) of ray at finishing point
+ },
+ {}, // definition of second from top line in the ray, identical format
+ ... // definitions of remaining lines, till desired width of the ray
+ ],
+ // Frame at which shooter shoots his projectile (e.g. releases arrow)
+ "attackClimaxFrame" : 0,
+
+ // offsets between position of shooter and position where projectile should appear
+ "offset" :
+ {
+ "upperX" : 0,
+ "upperY" : 0,
+ "middleX" : 0,
+ "middleY" : 0,
+ "lowerX" : 0,
+ "lowerY" : 0
+ },
+ // angles from which frames in .def file were rendered, -90...90 range
+ // Example below will work for file that contains following frames:
+ // 1) facing top, 2) facing top-right, 3)facing right,
+ // 4) facing bottom-right 5) facing bottom.
+ "frameAngles" : [ -90, -45, 0, 45, 90]
+ }
+ },
+
+ // names of sound files
+ "sound" :
+ {
+ // Creature attack enemy in melee (counter-)attack
+ "attack": "",
+ // Creature in "defend mode" is attacked
+ "defend": "",
+ // Creature killed
+ "killed": "",
+ // Plays in loop during creature movement
+ "move": "",
+ // Shooters only, creature shoots
+ "shoot" : "",
+ // Creature not in "defend mode" is under attack
+ "wince": "",
+
+ // Creature start/end movement or teleports
+ "startMoving" : "",
+ "endMoving" : ""
+ }
+}
+```
\ No newline at end of file
diff --git a/docs/modders/Entities_Format/Faction_Format.md b/docs/modders/Entities_Format/Faction_Format.md
new file mode 100644
index 000000000..153cf05d6
--- /dev/null
+++ b/docs/modders/Entities_Format/Faction_Format.md
@@ -0,0 +1,390 @@
+< [Documentation](../../Readme.md) / [Modding](../Readme.md) / Entities Format / Faction Format
+
+## Required data
+
+In order to make functional town you also need:
+
+### Images
+
+- Creature backgrounds images, 120x100 and 130x100 versions (2 images)
+- Set of puzzle map pieces (48 images)
+- Background scenery (1 image)
+- Mage guild window view (1 image)
+- Town hall background (1 image)
+
+
+
+- Set of town icons, consists from all possible combinations of: (8
+ images total)
+ - small and big icons
+ - village and fort icons
+ - built and normal icons
+
+
+
+- Set for castle siege screen, consists from:
+ - Background (1 image)
+ - Destructible towers (3 parts, 3 images each)
+ - Destructible walls (4 parts, 3 images each)
+ - Static walls (3 images)
+ - Town gates (5 images)
+ - Moat (2 images)
+
+### Animation
+
+- Adventure map images for village, town and capitol (3 def files)
+
+### Music
+
+- Town theme music track (1 music file)
+
+### Buildings
+
+Each town requires a set of buildings (Around 30-45 buildings)
+
+- Town animation file (1 animation file)
+- Selection highlight (1 image)
+- Selection area (1 image)
+- Town hall icon (1 image)
+
+## Faction node (root entry for town configuration)
+
+``` javascript
+// Unique faction identifier. Should be unique.
+"myTown" :
+{
+ // Main part of town description, see below
+ // Optional but it should be present for playable faction
+ "town" : { ... },
+
+ // Native terrain for this town. See config/terrains.json for identifiers
+ "nativeTerrain" : "grass",
+
+ // Localizable town name, e.g. "Rampart"
+ "name" : "",
+
+ // Faction alignment. Can be good, neutral (default) or evil.
+ "alignment" : "",
+
+ // Backgrounds for creature screen, two versions: 120px-height and 130-px height
+ "creatureBackground"
+ {
+ // Paths to background images
+ "120px" : "",
+ "130px" : ""
+ }
+
+ // Town puzzle map
+ "puzzleMap" :
+ {
+ // Prefix for image names, e.g. "PUZCAS" for name "PUZCAS12.png"
+ "prefix" : "",
+ // List of map pieces. First image will have name 00, second - 01 and so on
+ "pieces" :
+ [
+ {
+ // Position of image on screen
+ "x" : 0
+ "y" : 0
+
+ //indicates order in which this image will be opened
+ "index" : 0
+ },
+ ...
+ ]
+ ]
+}
+```
+
+## Town node
+
+``` javascript
+{
+ // DEPRECATED, see "mapObject" field below | Path to images of object on adventure map
+ "adventureMap" :
+ {
+ "village": "", // village without built fort
+ "castle" : "", // town with built fort
+ "capitol": "" // town with capitol (usually have some additional flags)
+ },
+
+ // field that describes behavior of map object part of town. Town-specific part of object format
+ "mapObject" :
+ {
+ // Optional, controls what template will be used to display this object.
+ // Whenever player builds a building in town game will test all applicable templates using
+ // tests with matching name and on success - set such template as active.
+ // There are 3 predefined filters: "village", "fort" and "capitol" that emulate H3 behavior
+ "filter" : {
+ "capitol" : [ "anyOf", [ "capitol" ], [ "castle" ] ]
+ },
+
+ // List of templates that represent this object. For towns only animation is required
+ // See object template description for other fields that can be used.
+ "templates" : {
+ "village" : { "animation" : "" },
+ "castle" : { "animation" : "" },
+ "capitol" : { "animation" : "" }
+ }
+ },
+
+ //icons, small and big. Built versions indicate constructed during this turn building.
+ "icons" :
+ {
+ "village" : {
+ "normal" : {
+ "small" : "modname/icons/hall-small.bmp",
+ "large" : "modname/icons/hall-big.bmp"
+ },
+ "built" : {
+ "small" : "modname/icons/hall-builded-small.bmp",
+ "large" : "modname/icons/hall-builded-big.bmp"
+ }
+ },
+ "fort" : {
+ "normal" : {
+ "small" : "modname/icons/fort-small.bmp",
+ "large" : "modname/icons/fort-big.bmp"
+ },
+ "built" : {
+ "small" : "modname/icons/fort-builded-small.bmp",
+ "large" : "modname/icons/fort-builded-big.bmp"
+ }
+ }
+ },
+ // Path to town music theme, e.g. "music/castleTheme"
+ "musicTheme" : "",
+
+ // List of structures which represents visible graphical objects on town screen.
+ // See detailed description below
+ "structures" :
+ {
+ "building1" : { ... },
+ ...
+ "building9" : { ... }
+ },
+
+ // List of names for towns on adventure map e.g. "Dunwall", "Whitestone"
+ // Does not have any size limitations
+ "names" : [ "", ""],
+
+ // Background scenery for town screen, size must be 800x374
+ "townBackground": "",
+
+ // Small scenery for window in mage guild screen
+ "guildWindow": "",
+
+ // Background image for window in mage guild screen - since 0.95b
+ "guildBackground" : "",
+
+ // Video for tavern window - since 0.95b
+ "tavernVideo" : "",
+
+ // Building icons for town hall
+ "buildingsIcons": "HALLCSTL.DEF",
+
+ // Background image for town hall window
+ "hallBackground": "",
+
+ // List of buildings available in each slot of town hall window
+ // As in most cases there is no hard limit on number of columns, rows
+ // or items in any of them, but size of gui is limited to 5 rows and 4 columns
+ "hallSlots":
+ [
+ [ [ "buildingID1" ], [ "buildingID2", "buildingID3" ] ],
+ ...
+ ],
+ // List of creatures available on each tier. Number of creatures on each tier
+ // is not hardcoded but it should match with number of dwelling for each level.
+ // For example structure below would need buildings with these id's:
+ // first tier: 30 and 37, second tier: 31, third tier: 32, 39, 46
+ "creatures" :
+ [
+ ["centaur", "captainCentaur"],
+ ["dwarf"],
+ ["elf", "grandElf", "sharpshooter"],
+ ...
+ ],
+
+ // Buildings, objects in town that affect mechanics. See detailed description below
+ "buildings" :
+ {
+ "building1" : { ... },
+ ...
+ "building9" : { ... }
+ },
+ // Description of siege screen, see below
+ "siege" : { ... },
+
+ // Chance for a hero class to appear in this town, creates pair with same field in class format
+ // Used for situations where chance was not set in "tavern" field, chance will be determined as:
+ // square root( town tavern chance * hero class tavern chance )
+ "defaultTavern" : 5,
+
+ // Chance of specific hero class to appear in this town
+ // Mirrored version of field "tavern" from hero class format
+ "tavern" :
+ {
+ "knight" : 5,
+ "druid" : 6
+ },
+
+ // Chance of specific spell to appear in mages guild of this town
+ // If spell is missing or set to 0 it will not appear unless set as "always present" in editor
+ // Spells from unavailable levels are not required to be in this list
+ // TODO: Mirrored version of field "guildSpells" from spell format
+ "guildSpells" :
+ {
+ "magicArrow" : 30,
+ "bless" : 10
+ },
+
+ // TODO: Entries below should be replaced with autodetection
+
+ // Which tiers in this town have creature hordes. Set to -1 to disable horde(s)
+ "horde" : [ 2, -1 ],
+
+ // Resource given by starting bonus, if not set silo will produce wood + ore
+ "primaryResource" : "gems",
+
+ // maximum level of mage guild
+ "mageGuild" : 4,
+
+ // war machine produced in town
+ "warMachine" : "ballista"
+}
+```
+
+## Siege node
+
+``` javascript
+// Describes town siege screen
+// Comments in the end of each graphic position indicate specify required suffix for image
+// Note: one not included image is battlefield background with suffix "BACK"
+{
+ // shooter creature name
+ "shooter" : "archer",
+
+ // (VCMI 1.1 or later) Large icon of towers, for use in battle queue
+ "towerIconLarge" : "",
+
+ // (VCMI 1.1 or later) Small icon of towers, for use in battle queue
+ "towerIconSmall" : "",
+
+ // prefix for all siege images. Final name will be composed as
+ "imagePrefix" : "SGCS",
+
+ // Descriptions for towers. Each tower consist from 3 parts:
+ // tower itself - two images with untouched and destroyed towers
+ // battlement or creature cover - section displayed on top of creature
+ // creature using type from "shooter" field above
+ "towers":
+ {
+ // Top tower description
+ "top" :
+ {
+ "tower" : { "x": 0, "y": 0}, // "TW21" ... "TW22"
+ "battlement" : { "x": 0, "y": 0}, // "TW2C"
+ "creature" : { "x": 0, "y": 0}
+ },
+ // Central keep description
+ "keep" :
+ {
+ "tower" : { "x": 0, "y": 0}, // "MAN1" ... "MAN2"
+ "battlement" : { "x": 0, "y": 0}, // "MANC"
+ "creature" : { "x": 0, "y": 0}
+ },
+ // Bottom tower description
+ "bottom" :
+ {
+ "tower" : { "x": 0, "y": 0}, // "TW11" ... "TW12"
+ "battlement" : { "x": 0, "y": 0}, // "TW1C"
+ "creature" : { "x": 0, "y": 0}
+ },
+ },
+ //Two parts of gate: gate itself and arch above it
+ "gate" :
+ {
+ "gate" : { "x": 0, "y": 0}, // "DRW1" ... "DRW3" and "DRWC" (rope)
+ "arch" : { "x": 0, "y": 0} // "ARCH"
+ },
+ // Destructible walls. In this example they are ordered from top to bottom
+ // Each of them consist from 3 files: undestroyed, damaged, destroyed
+ "walls" :
+ {
+ "upper" : { "x": 0, "y": 0}, // "WA61" ... "WA63"
+ "upperMid" : { "x": 0, "y": 0}, // "WA41" ... "WA43"
+ "bottomMid" : { "x": 0, "y": 0}, // "WA31" ... "WA33"
+ "bottom" : { "x": 0, "y": 0} // "WA11" ... "WA13"
+ },
+ // Two pieces for moat: moat itself and shore
+ "moat" : { "x": 0, "y": 0}, // moat: "MOAT", shore: "MLIP"
+
+ // Static non-destructible walls. All of them have only one piece
+ "static" :
+ {
+ // Section between two bottom destructible walls
+ "bottom" : { "x": 0, "y": 0}, // "WA2"
+
+ // Section between two top destructible walls
+ "top" : { "x": 0, "y": 0}, // "WA5"
+
+ // Topmost wall located behind hero
+ "background" : { "x": 0, "y": 0} // "TPWL"
+ }
+}
+```
+
+## Building node
+
+``` javascript
+{
+ "id" : 0,
+ "name" : "",
+ "description" : "",
+ "upgrades" : "baseBuilding", // optional, which building can be upgraded by this one
+ "requires" : [ "allOf", [ "mageGuild1" ], [ "tavern" ] ], // building requirements, H3-style. See below for full format.
+ "cost" : { ... }, //resources needed to buy building
+ "produce" : { ... }, //resources produced each day by building - since 0.95b
+
+ //determine how this building can be built. Possible values are:
+ // normal - default value. Fulfill requirements, use resources, spend one day
+ // auto - building appears when all requirements are built
+ // special - building can not be built manually
+ // grail - building reqires grail to be built
+ "mode" : "auto"
+}
+```
+
+Building requirements can be described using logical expressions:
+
+``` javascript
+"requires" :
+[
+ "allOf", // Normal H3 "build all" mode
+ [ "mageGuild1" ],
+ [
+ "noneOf", // available only when none of these building are built
+ [ "dwelling5A" ],
+ [ "dwelling5AUpgrade" ]
+ ],
+ [
+ "anyOf", // any non-zero number of these buildings must be built
+ [ "tavern" ],
+ [ "blacksmith" ]
+ ]
+]
+```
+
+## Structure node
+
+``` javascript
+{
+ "animation" : "", // def file with animation
+ "x" : 0,
+ "y" : 0,
+ "z" : 0, // used for blit order. Higher value places structure close to screen
+ "border" : "", // selection highlight
+ "area" : "" // used to detect building selection
+}
+```
\ No newline at end of file
diff --git a/docs/modders/Entities_Format/Hero_Class_Format.md b/docs/modders/Entities_Format/Hero_Class_Format.md
new file mode 100644
index 000000000..f92f2a765
--- /dev/null
+++ b/docs/modders/Entities_Format/Hero_Class_Format.md
@@ -0,0 +1,111 @@
+< [Documentation](../../Readme.md) / [Modding](../Readme.md) / Entities Format / Hero Class Format
+
+## Required data
+
+In order to make functional hero class you also need:
+
+- Adventure animation (1 def file)
+- Battle animation, male and female version (2 def files)
+
+## Format
+
+``` javascript
+// Unique identifier of hero class, camelCase
+"myClassName" :
+{
+ // Various hero animations
+ "animation"
+ {
+ "battle" :
+ {
+ // Battle animation for female heroes
+ "female" : "myMod/battle/heroFemale",
+
+ // Battle animation for male heroes, can be same as female
+ "male" : "myMod/battle/heroMale"
+ }
+ },
+
+ // Description of map object representing this hero class. See map template format for details
+ "mapObject" : {
+ // Optional, hero ID-base filter, using same rules as building requirements
+ "filters" : {
+ "mutare" : [ "anyOf", [ "mutare" ], [ "mutareDrake" ]]
+ },
+
+ // List of templates used for this object, normally - only one is needed
+ "templates" : {
+ "normal" : { "animation" : "AH00_.def" }
+ }
+ },
+
+ // Translatable name of hero class
+ "name" : "My hero class",
+
+ // Identifier of faction this class belongs to
+ "faction" : "myFaction",
+
+ // Identifier of creature that should be used as commander for this hero class
+ // Can be a regular creature that has shooting animation
+ "commander" : "mage",
+
+ // Affinity of this class, might or magic
+ "affinity" : "might",
+
+ // Initial primary skills of heroes
+ "primarySkills" :
+ {
+ "attack" : 2,
+ "defence" : 0,
+ "spellpower" : 1,
+ "knowledge" : 2
+ },
+
+ // Chance to get specific primary skill on level-up
+ // This set specifies chances for levels 2-9
+ "lowLevelChance" :
+ {
+ "attack" : 15,
+ "defence" : 10,
+ "spellpower" : 50,
+ "knowledge" : 25
+ },
+
+ // Chance to get specific primary skill on level-up
+ // This set specifies chances for levels starting from 10
+ "highLevelChance" :
+ {
+ "attack" : 25,
+ "defence" : 5,
+ "spellpower" : 45,
+ "knowledge" : 25
+ },
+
+ // Chance to get specific secondary skill on level-up
+ // Skills not listed here will be considered as unavailable, including universities
+ "secondarySkills" :
+ {
+ "pathfinding" : 3.
+ "archery" : 6.
+ ...
+ "resistance" : 5,
+ "firstAid" : 4
+ },
+
+ // Chance for a this hero class to appear in a town, creates pair with same field in town format
+ // Used for situations where chance was not set in "tavern" field, chance will be determined as:
+ // square root( town tavern chance * hero class tavern chance )
+ "defaultTavern" : 5,
+
+ // Chance for this hero to appear in tavern of this factions.
+ // Reversed version of field "tavern" from town format
+ // If faction-class pair is not listed in any of them
+ // chance set to 0 and the class won't appear in tavern of this town
+ "tavern" :
+ {
+ "castle" : 4,
+ ...
+ "conflux" : 6
+ }
+}
+```
\ No newline at end of file
diff --git a/docs/modders/Entities_Format/Hero_Type_Format.md b/docs/modders/Entities_Format/Hero_Type_Format.md
new file mode 100644
index 000000000..7e1b7df25
--- /dev/null
+++ b/docs/modders/Entities_Format/Hero_Type_Format.md
@@ -0,0 +1,128 @@
+< [Documentation](../../Readme.md) / [Modding](../Readme.md) / Entities Format / Hero Type Format
+
+## Required data
+
+In order to make functional hero you also need:
+
+- Portraits, small and big versions (2 images)
+- Specialty icons, small and big versions (2 images)
+
+## Format
+
+``` javascript
+"myHeroName" :
+{
+ // Identifier of class. Usually camelCase version of human-readable name
+ "class" : "wizard",
+
+ // List of starting spells, if available. Will also grant spellbook
+ "spellbook" :
+ [
+ "magicArrow"
+ ],
+
+ // Set to true if the hero is female by default (can be changed in map editor)
+ "female" : true,
+
+ // If set to true hero will be unavailable on start and won't appear in taverns (campaign heroes)
+ "special" : true,
+
+ // All translatable texts related to hero
+ "texts" :
+ {
+ "name" : "My Hero",
+ "biography" : "This is a long story...",
+
+ "specialty" :
+ {
+ // Description visible when hovering over specialty icon
+ "description" : "Spell mastery: Magic Arrow",
+
+ // Tooltip visible on clicking icon. Can use {} symbols to change title to yellow
+ // as well as escape sequences "\n" to add line breaks
+ "tooltip" : "{Magic Arrow}\n\nCasts powerfull magic arrows",
+
+ // Name of your specialty
+ "name" : "Magic Arrow"
+ }
+ },
+
+ // Graphics used by hero
+ "images" :
+ {
+ // Small 32px speciality icon
+ "specialtySmall" : "myMod/myHero/specSmall.png",
+
+ // Large 44px speciality icon
+ "specialtyLarge" : "myMod/myHero/specLarge.png",
+
+ // Large 58x64px portrait
+ "large" : "myMod/myHero/large.png",
+
+ // Small 48x32px portrait
+ "small" : "myMod/myHero/small.png"
+
+ // Class-independent animation in battle
+ "small" : "myMod/myHero/battle.def"
+
+ },
+
+ // Initial hero army when recruited in tavern
+ // Must have 1-3 elements
+ "army" :
+ [
+ // First always available stack
+ {
+ // Identifier of creature in this stack
+ "creature" : "mage",
+
+ // Minimal and maximum size of stack. Size will be
+ // determined randomly at the start of the game
+ "max" : 2,
+ "min" : 1
+ },
+ // Second stack has 90 % chance to appear
+ {
+ "creature" : "archmage",
+ "max" : 1,
+ "min" : 1
+ },
+ // Third stack with just 20 % chance to appear
+ {
+ "creature" : "mage",
+ "max" : 2,
+ "min" : 1
+ }
+ ],
+
+ // List of skills received by hero
+ // Not limited by size - you can add as many skills as you wish
+ "skills" :
+ [
+ {
+ // Skill level, basic, advanced or expert
+ "level" : "basic",
+
+ // Skill identifier, camelCase version of name
+ "skill" : "wisdom"
+ },
+ {
+ "level" : "basic",
+ "skill" : "waterMagic"
+ }
+ ],
+
+ // Description of specialty mechanics using bonuses (with updaters)
+ "specialty" : {
+ // to be merged with all bonuses, use for specialties with multiple similar bonuses (optional)
+ "base" : {common bonus properties},
+ "bonuses" : {
+ // use updaters for bonuses that grow with level
+ "someBonus" : {Bonus Format},
+ "anotherOne" : {Bonus Format}
+ },
+ // adds creature specialty following the HMM3 default formula
+ "creature" : "griffin"
+ }
+}
+```
\ No newline at end of file
diff --git a/docs/modders/Entities_Format/River_Format.md b/docs/modders/Entities_Format/River_Format.md
new file mode 100644
index 000000000..8b157aa90
--- /dev/null
+++ b/docs/modders/Entities_Format/River_Format.md
@@ -0,0 +1,3 @@
+< [Documentation](../../Readme.md) / [Modding](../Readme.md) / Entities Format / River Format
+
+TODO
\ No newline at end of file
diff --git a/docs/modders/Entities_Format/Road_Format.md b/docs/modders/Entities_Format/Road_Format.md
new file mode 100644
index 000000000..a15c0af36
--- /dev/null
+++ b/docs/modders/Entities_Format/Road_Format.md
@@ -0,0 +1,3 @@
+< [Documentation](../../Readme.md) / [Modding](../Readme.md) / Entities Format / Road Format
+
+TODO
\ No newline at end of file
diff --git a/docs/modders/Entities_Format/Secondary_Skill_Format.md b/docs/modders/Entities_Format/Secondary_Skill_Format.md
new file mode 100644
index 000000000..c0eb2526c
--- /dev/null
+++ b/docs/modders/Entities_Format/Secondary_Skill_Format.md
@@ -0,0 +1,88 @@
+< [Documentation](../../Readme.md) / [Modding](../Readme.md) / Entities Format / Secondary Skill Format
+
+## Main format
+
+``` javascript
+{
+ "skillName":
+ {
+ //numeric id of skill required only for original skills, prohibited for new skills
+ "index": 0,
+ //Mandatory
+ "name": "Localizable name",
+ //optional base format, will be merged with basic/advanced/expert
+ "base": {Skill level base format},
+ //configuration for different skill levels
+ "basic": {Skill level format},
+ "advanced": {Skill level format},
+ "expert": {Skill level format}
+ }
+}
+```
+
+## Skill level base format
+
+Json object with data common for all levels can be put here. These
+configuration parameters will be default for all levels. All mandatory
+level fields become optional if they equal "base" configuration.
+
+## Skill level format
+
+``` javascript
+{
+ //Optional, localizable description
+ //Use {xxx} for formatting
+ "description": "",
+ //Bonuses provided by skill at given level
+ //If different levels provide same bonus with different val, only the highest applies
+ "effects":
+ {
+ "firstEffect": {bonus format},
+ "secondEffect": {bonus format}
+ //...
+ }
+}
+```
+
+## Example
+
+The following modifies the tactics skill to grant an additional speed
+boost at advanced and expert levels.
+
+``` javascript
+"core:tactics" : {
+ "base" : {
+ "effects" : {
+ "main" : {
+ "subtype" : "skill.tactics",
+ "type" : "SECONDARY_SKILL_PREMY",
+ "valueType" : "BASE_NUMBER"
+ },
+ "xtra" : {
+ "type" : "STACKS_SPEED",
+ "valueType" : "BASE_NUMBER"
+ }
+ }
+ },
+ "basic" : {
+ "effects" : {
+ "main" : { "val" : 3 },
+ "xtra" : { "val" : 0 }
+ }
+ },
+ "advanced" : {
+ "description" : "{Advanced Tactics}\n\nAllows you to rearrange troups within 5 hex rows, and increases their speed by 1.",
+ "effects" : {
+ "main" : { "val" : 5 },
+ "xtra" : { "val" : 1 }
+ }
+ },
+ "expert" : {
+ "description" : "{Expert Tactics}\n\nAllows you to rearrange troups within 7 hex rows, and increases their speed by 2.",
+ "effects" : {
+ "main" : { "val" : 7 },
+ "xtra" : { "val" : 2 }
+ }
+ }
+}
+```
\ No newline at end of file
diff --git a/docs/modders/Entities_Format/Spell_Format.md b/docs/modders/Entities_Format/Spell_Format.md
new file mode 100644
index 000000000..3bd3882e3
--- /dev/null
+++ b/docs/modders/Entities_Format/Spell_Format.md
@@ -0,0 +1,383 @@
+< [Documentation](../../Readme.md) / [Modding](../Readme.md) / Entities Format / Spell Format
+
+# Main format
+
+``` javascript
+{
+ "spellName":
+ { //numeric id of spell required only for original spells, prohibited for new spells
+ "index": 0,
+ //Original Heroes 3 info
+ //Mandatory, spell type
+ "type": "adventure",//"adventure", "combat", "ability"
+
+ //Mandatory, spell target type
+ "targetType":"NO_TARGET",//"CREATURE","OBSTACLE"."LOCATION"
+
+ //Mandatory
+ "name": "Localizable name",
+ //Mandatory, flags structure of school names, Spell schools this spell belongs to
+ "school": {"air":true, "earth":true, "fire":true, "water":true},
+ //number, mandatory, Spell level, value in range 1-5
+ "level": 1,
+ //Mandatory, base power
+ "power": 10,
+ //Mandatory, default chance for this spell to appear in Mage Guilds
+ //Used only if chance for a faction is not set in gainChance field
+ "defaultGainChance": 0,
+ //Optional, chance for it to appear in Mage Guild of a specific faction
+ //NOTE: this field is linker with faction configuration
+ "gainChance":
+ {
+ "factionName": 3
+ },
+ //VCMI info
+
+ "animation":{},
+
+ //countering spells, flags structure of spell ids (spell. prefix is required)
+ "counters": {"spell.spellID1":true, ...}
+
+ //Mandatory,flags structure:
+ // indifferent, negative, positive - Positiveness of spell for target (required)
+ // damage - spell does damage (direct or indirect)
+ // offensive - direct damage (implicitly sets damage and negative)
+ // rising - rising spell (implicitly sets positive)
+ // summoning //todo:
+ // special - can be obtained only with bonus::SPELL
+
+ "flags" : {"flag1": true, "flag2": true},
+
+ //DEPRECATED | optional| no default | flags structure of bonus names,any one of these bonus grants immunity. Negatable by the Orb.
+ "immunity": {"BONUS_NAME":true, ...},
+
+ //DEPRECATED | optional| no default | flags structure of bonus names
+ //any one of these bonus grants immunity, cant be negated
+ "absoluteImmunity": {"BONUS_NAME": true, ...},
+
+ //DEPRECATED | optional| no default | flags structure of bonus names, presence of all bonuses required to be affected by. Negatable by the Orb.
+ "limit": {"BONUS_NAME": true, ...},
+
+ //DEPRECATED | optional| no default | flags structure of bonus names, presence of all bonuses required to be affected by. Cant be negated
+ "absoluteLimit": {"BONUS_NAME": true, ...},
+
+ //[WIP] optional | default no limit no immunity
+ //
+ "targetCondition" {
+ //at least one required to be affected
+ "anyOf" : {
+ //generic format
+ "mod:metaClassName.typeName":"absolute",//"normal", null or empty ignored - use for overrides
+ },
+ //all required to be affected (like [absolute]limit)
+ "allOf" : {
+ //bonus type format
+ "bonus.BONUS_TYPE":"absolute"//"normal" Short bonus type format
+ "modId:bonus.bonusTypeName":"absolute"//"normal" Future bonus format for configurable bonuses
+ },
+ //at least one grants immunity (like [absolute]immunity)
+ "noneOf": {
+ //some more examples
+ "core:creature.imp":"absolute", //[to be in initial version] this creature explicitly absolutely immune
+ "core:bonus.MIND_IMMUITY":"normal", // [to be in initial version] new format of existing mind spell immunity
+ "core:artifact.armorOfWonder":"absolute", //[possible future extension] this artifact on target itself (!) explicitly grant absolute immune
+ "core:luck":["absolute", 3], // [possible future extension] lack value of at least 3 grant absolute immunity from this horrible spell
+ "core:custom":[