Modders docs update iteration

docs/Readme.md

@@ -17,7 +17,7 @@ VCMI is work-in-progress attempt to recreate engine for Heroes III, giving it ne
 
 ## Latest release
 
-Latest release can be found [here](https://github.com/vcmi/vcmi/releases/latest). As of right now we plan to have major releases around 3 times per year. Daily builds are still available at [builds.vcmi.download](https://builds.vcmi.download/branch/develop/) but they are not guaranteed to be stable. So we encourage everybody to use them and report found bugs so that we can fix them.
+Latest release can be found [in Github Releases page](https://github.com/vcmi/vcmi/releases/latest). As of right now we plan to have major releases around 3 times per year. Daily builds are still available at [builds.vcmi.download](https://builds.vcmi.download/branch/develop/) but they are not guaranteed to be stable. So we encourage everybody to use them and report found bugs so that we can fix them.
 Loading saves made with different major version of VCMI is usually **not** supported, so you may want to finish your ongoing games before updating.
 Please see corresponding installation guide articles for details for your platform.  
 
@@ -40,31 +40,22 @@ Please see corresponding installation guide articles for details for your platfo
 
 ## Documentation and guidelines for game modders
 
-- [Modding guidelines](Modding_guidelines "wikilink")
+- [Modding Guidelines](modders/Readme.md)
-- [Mods repository](Mods_repository "wikilink")
+- [Mod File Format](modders/Mod_File_Format.md)
-- Formats:
+- [Bonus Format](modders/Bonus_Format.md)
- - [Mod file Format](Mod_file_Format "wikilink")
+- [Translations](modders/Translations.md)
- - [Town Format](Town_Format "wikilink")
+- [Map Editor](modders/Map_Editor.md)
- - [Hero Classes Format](Hero_Classes_Format "wikilink")
+- [Campaign Format](modders/Campaign_Format.md)
- - [Hero Format](Hero_Format "wikilink")
- - [Creature Format](Creature_Format "wikilink")
- - [Artifact Format](Artifact_Format "wikilink")
- - [Animation Format](Animation_Format "wikilink")
- - [Bonus Format](Bonus_Format "wikilink")
- - [Object Format](Object_Format "wikilink")
- - [Spell Format](Spell_Format "wikilink")
- - [Skill Format](Skill_Format "wikilink")
 
 ## Documentation and guidelines for developers
 
 - How to build using CMake:
   - [Linux](How_to_build_VCMI_(Linux) "wikilink")
-  - [Linux/MinGW (for
+  - [Linux/MinGW (for Windows)](How_to_build_VCMI_(Linux/MinGW) "wikilink")
-    Windows)](How_to_build_VCMI_(Linux/MinGW) "wikilink")
   - [macOS](How_to_build_VCMI_(macOS) "wikilink")
   - [Windows](How_to_build_VCMI_(Windows/Vcpkg) "wikilink")
   - [iOS](How_to_build_VCMI_(iOS) "wikilink")
-  - [ Android](How_to_build_VCMI_(Android) "wikilink")
+  - [Android](How_to_build_VCMI_(Android) "wikilink")
 - Unsupported build instructions:
   - [Windows/MSVS (Visual Studio 2015)](How_to_build_VCMI_(Windows/Visual_Studio_2015) "wikilink")
 - [Coding guidelines](Coding_guidelines "wikilink")

docs/modders/Bonus/Bonus_Updaters.md

@@ -81,9 +81,3 @@ Remark: The stack level for war machines is 0.
 `       "parameters" : [ 20, 3, 10, 700 ],`  
 `       "type" : "ARMY_MOVEMENT"`  
 `   }`
-
-# Additional links
-
--   [Bonus system](Bonus_system "wikilink")
--   [Bonus Format](Bonus_Format "wikilink")
--   [Hero Format](Hero_Format "wikilink")

docs/modders/Bonus_Format.md

@@ -1,6 +1,6 @@
 Enumerative parameters are described in HeroBonus.h file.
 
-### Full format
+## Full format
 
 All parameters but type are optional.
 
@@ -32,6 +32,17 @@ All parameters but type are optional.
 }
 ```
 
+## 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

docs/modders/Entities_Format/Artifact_Format.md

@@ -1,4 +1,4 @@
-Artifact bonuses use [Bonus Format](Bonus_Format.md)
+Artifact bonuses use [Bonus Format](../Bonus_Format.md)
 
 TODO:
 

docs/modders/Entities_Format/Battle_Obstacle_Format.md

@@ -0,0 +1 @@
+TODO

docs/modders/Entities_Format/Battlefield_Format.md

@@ -0,0 +1 @@
+TODO

docs/modders/Entities_Format/River_Format.md

@@ -0,0 +1 @@
+TODO

docs/modders/Entities_Format/Road_Format.md

@@ -0,0 +1 @@
+TODO

docs/modders/Entities_Format/Terrain_Format.md

@@ -0,0 +1 @@
+TODO

docs/modders/Map_Editor.md

@@ -0,0 +1,234 @@
+# Interface
+
+<img width="738" src="https://user-images.githubusercontent.com/9308612/188775648-8551107d-9f0b-4743-8980-56c2c1c58bbc.png">
+
+# Create the map
+
+<img width="145" src="https://user-images.githubusercontent.com/9308612/188782248-b7895eb1-86a9-4f06-9309-43c6b3a3a728.png">
+
+## New map
+
+Create the new map by pressing **New** button from the toolbar
+
+### Empty map
+
+To create empty map, define its size by choosing option from drop-down list or enter required size manually in the text fields and press Ok button. Check **Two level map** option to create map with underground.
+`Note: there are no limits on map size but be careful with sizes larger predefined XL size. It will be processed quite long to create even empty map. Also, it will be difficult to work with the huge maps because of possible performance issues`
+
+Other parameters won't be used for empty map.
+
+<img width="413" src="https://user-images.githubusercontent.com/9308612/188782588-c9f1a164-df1e-46bc-a6d3-24ff1e5396c2.png">
+
+### Random map
+
+To generate random map, check the **Random map** option and configure map parameters. You can select template from the drop-down list.
+
+<img width="439" src="https://user-images.githubusercontent.com/9308612/188783256-7e498238-14a0-4377-8c09-d702d54ee7d9.png">
+
+Templates are dynamically filtered depending on parameters you choose.
+
+* [Default] template means that template will be randomly chosen
+* If you see empty list it means that there are no templates fit your settings. It could be related to the settings chosen or it can mean that there are no templates install.
+
+<img width="412" src="https://user-images.githubusercontent.com/9308612/188783360-1c042782-328d-4692-952f-58fa5110d0d0.png">
+
+## Map load & save
+
+To load the map, press open and select map file from the browser.
+
+You can load both *.h3m and *.vmap formats but for saving *.vmap is allowed only.
+
+# Views
+
+There are 3 buttons switching views <img width="131" alt="Снимок экрана 2022-09-07 в 06 48 08" src="https://user-images.githubusercontent.com/9308612/188777527-b7106146-0d8c-4f14-b78d-f13512bc7bad.png">
+
+### Ground/underground
+
+**"U/G"** switches you between ground and underground
+
+### Grid view
+
+**Grid** show/hide grid
+
+<img width="153" src="https://user-images.githubusercontent.com/9308612/188777723-934d693b-247d-42a6-815c-aecd0d34f653.png">
+
+### Passability view
+
+**Pass** show/hide passability map
+
+<img width="190" src="https://user-images.githubusercontent.com/9308612/188778010-a1d45d59-7333-4432-b83f-57190fbe09f4.png">
+
+# Setup terrain
+
+1. Select brush you want
+<img width="124" src="https://user-images.githubusercontent.com/9308612/188776299-fd688696-a98d-4f89-8bef-e81c90d3724b.png">
+
+2. Select area you'd like to change
+
+`Note: left mouse button selects tiles, right button removes selection`
+
+![Image](https://user-images.githubusercontent.com/9308612/188776895-ce1607fb-694b-4edb-b0cc-263a0c5d04b8.png)
+
+3. Press terrain you want
+
+<img width="116" src="https://user-images.githubusercontent.com/9308612/188777176-1167561a-f23c-400a-a57b-be7fc90accae.png">
+
+### Drawing roads and rivers
+
+Actually, the process to draw rivers or roads is exactly the same as for terrains. You need to select tiles and then choose road/river type from the panel. 
+
+<img width="232" src="https://user-images.githubusercontent.com/9308612/189968965-7adbd76c-9ffc-46e5-aeb7-9a79214cc506.png">
+
+To erase roads or rivers, you need to select tiles to be cleaned and press empty button.
+
+<img width="130" src="https://user-images.githubusercontent.com/9308612/189969309-87ff7818-2915-4b38-b9db-ec4a616d18e7.png">
+
+_Erasing works either for roads or for rivers, e.g. empty button from the roads tab erases roads only, but not rivers. You also can safely select bigger area, because it won't erase anything on tiles without roads/rivers accordingly_
+
+## About brushes
+* Buttons "1", "2", "4" - 1x1, 2x2, 4x4 brush sizes accordingly
+* Button "[]" - non-additive rectangle selection
+* Button "O" - lasso brush (not implemented yet)
+* Button "E" - object erase, not a brush
+
+## Fill obstacles
+
+Map editor supports automatic obstacle placement.
+Obstacle types are automatically selected for appropriate terrain types
+
+To do that, select area (see Setup terrains) and press **Fill** button from the toolbar
+<img width="222" src="https://user-images.githubusercontent.com/9308612/188778572-f80b3706-1713-40c7-a5aa-e4c3b9fc6649.png">
+
+<img width="335" src="https://user-images.githubusercontent.com/9308612/188778694-507009a1-4bb0-4f37-afc7-4aa26a6f3eeb.png">
+
+<img width="350" src="https://user-images.githubusercontent.com/9308612/188778728-f66adcbe-9cf2-41f2-8947-f60b38901317.png">
+
+`Note: obstacle placer may occupy few neighbour tiles outside of selected area`
+
+# Manipulating objects
+
+## Adding new objects
+
+1. Find the object you'd like to place in the object browser
+
+<img width="188" src="https://user-images.githubusercontent.com/9308612/188779107-dc2ab212-9ed2-48ee-ba0d-7856b94a87b1.png">
+
+2. You can also see selected object in preview area in the left part of application window
+
+<img width="130" src="https://user-images.githubusercontent.com/9308612/188779263-a78577f7-8278-4927-a44e-18a7d85e2f64.png">
+
+3. Hold mouse at object you want to place and move it to the map. You will see transparent object. Release object at point to confirm its creation
+
+<img width="181" src="https://user-images.githubusercontent.com/9308612/188779350-653bad29-c54f-471b-93aa-90096da6d98c.png">
+
+4. Press somewhere on the map to locate object.
+
+**Right click over the scene - cancel object placement**
+
+## Removing objects
+
+1. **Make sure that no one terrain brush is selected.** To de-select brush click on selected brush again.
+
+2. Select object you'd like to remove by simple clicking on it. You can also select multiple objects by moving mouse while left button is pressed
+<img width="170" src="https://user-images.githubusercontent.com/9308612/188780096-6aefcad5-e092-44c6-8647-975e95f9a8a3.png">
+
+3. Press **"E"** button from the brush panel or press **delete** on keyboard
+
+## Changing object's properties
+
+1. **Make sure that no one terrain brush is selected.** To de-select brush click on selected brush again.
+
+2. Select object you'd like to remove by simple clicking on it. **You cannot review and modify properties for several objects, multiple selection is not supported.**
+
+3. Go to the **inspector** tab. You will see object's properties
+
+<img width="197" src="https://user-images.githubusercontent.com/9308612/188780504-40713019-3cdd-4077-9e2f-e3417c960efe.png">
+
+4. You are able to modify properties which are not gray
+`Note: sometimes there are empty editable fields`
+
+### Assigning player to the object
+
+Objects with flags can be assigned to the player. Find Owner property in the inspector for selected object, press twice to modify right cell. Type player number from **0 to 7 or type NEUTRAL** for neutral objects.
+
+# Set up the map
+
+You can modify general properties of the map
+
+## Map name and description
+
+1. Open **Map** menu on the top and select **General**
+
+<img width="145" src="https://user-images.githubusercontent.com/9308612/188780943-70578b79-001b-45a2-bdfd-94577db40a6b.png">
+
+2. You will see a new window with text fields to edit map name and description
+
+3. Pressing **Ok** will save the changes, closing the window will discard the changes
+
+<img width="307" src="https://user-images.githubusercontent.com/9308612/188781063-50ce65f8-aab4-43c3-a308-22acafa7d0a2.png">
+
+# Player settings
+
+Open **Map** menu on the top and select **Player settings" 
+
+<img width="141" src="https://user-images.githubusercontent.com/9308612/188781357-4a6091cf-f175-4649-a000-620f306d2c46.png">
+
+You will see a window with player settings. Combobox players defines amount of players on the map. To review settings for particular player scroll the internal window. There are bunch on settings for each player you can change.
+
+`Important: at least one player must be controlled as Human/CPU. Maps without human players won't be started in the game at most cases`
+
+<img width="641" src="https://user-images.githubusercontent.com/9308612/188781400-7d5ba463-4f82-4dba-83ff-56210995e2c7.png">
+
+# Compatibility questions
+
+## Platform compatibility
+
+vcmieditor is a cross-platform application, so in general can support all platforms, supported by VCMI.
+
+However, currently it doesn't support mobile platforms.
+
+## Engine compatibility
+
+vcmieditor is independent application so potentially it can be installed just in the folder with existing stable vcmi. However, on the initial stages of development compatibility was not preserved because major changes were needed to introduce into vcmi library. So it's recommended to download full package to use editor.
+
+## Map compatibility
+
+vcmieditor haven't introduced any change into map format yet, so all maps made by vcmieditor can be easily played with any version of vcmi. At the same time, those maps can be open and read in the old map editor and vice verse - maps from old editor can be imported in the new editor. So, full compatibility is ensured here.
+
+## Mod compatibilty
+
+vcmieditor loads set of mods using exactly same mechanism as game uses and mod manipulations can be done using vcmilaucnher application, just enable or disable mods you want and open editor to use content from those mods. In regards on compatibility, of course you need to play maps with same set of mods as you used in the editor. Good part is that is maps don't use content from the mods (even mods were enabled), it can be played on vcmi without mods as well
+
+# Working With Mods
+
+## Enabling and disabling mods
+
+The mods mechanism used in map editor is the same as in game.
+
+To enable or disable mods
+* Start launcher, activate or deactivate mods you want
+* Close launcher
+* Run map editor
+
+There is no button to start map editor directly from launcher, however you may use this approach to control active mods from any version of vcmi.
+
+## Placing objects from mods
+
+* All objects from mods will be automatically added into objects Browser. You can type mod name into filter field to find them.
+
+<img width="269" src="https://user-images.githubusercontent.com/9308612/189965141-62ee0d2c-2c3e-483c-98fe-63517ed51912.png">
+
+* Objects from mods related to new terrains (if mod adds any) should not be filtered this way, instead choose terrain from terrains filter on the top of objects browser
+
+<img width="271" src="https://user-images.githubusercontent.com/9308612/189965836-de1fd196-2f6d-4996-a62a-e2fcb52b8d74.png">
+
+## Playing maps with mods
+
+If you place any kind of objects from the mods, obviously, you need those mods to be installed to play the map.
+Also, you need to activate them.
+
+You also may have other mods being activated in addition to what was used during map designing.
+
+### Mod versions
+
+In the future, the will be support of mods versioning so map will contain information about mods used and game can automatically search and activate required mods or let user know which are required. However, it's not implemented yet

docs/modders/Map_Editor/Map_Editor.md

@@ -1,19 +0,0 @@
-# Compatibility questions
-
-## Platform compatibility
-
-vcmieditor is a cross-platform application, so in general can support all platforms, supported by VCMI.
-
-However, currently it doesn't support mobile platforms.
-
-## Engine compatibility
-
-vcmieditor is independent application so potentially it can be installed just in the folder with existing stable vcmi. However, on the initial stages of development compatibility was not preserved because major changes were needed to introduce into vcmi library. So it's recommended to download full package to use editor.
-
-## Map compatibility
-
-vcmieditor haven't introduced any change into map format yet, so all maps made by vcmieditor can be easily played with any version of vcmi. At the same time, those maps can be open and read in the old map editor and vice verse - maps from old editor can be imported in the new editor. So, full compatibility is ensured here.
-
-## Mod compatibilty
-
-vcmieditor loads set of mods using exactly same mechanism as game uses and mod manipulations can be done using vcmilaucnher application, just enable or disable mods you want and open editor to use content from those mods. In regards on compatibility, of course you need to play maps with same set of mods as you used in the editor. Good part is that is maps don't use content from the mods (even mods were enabled), it can be played on vcmi without mods as well

docs/modders/Map_Editor/Map_Editor_Quick_Guide.md

@@ -1,181 +0,0 @@
-# Interface
-
-<img width="738" alt="Снимок экрана 2022-09-07 в 06 31 12" src="https://user-images.githubusercontent.com/9308612/188775648-8551107d-9f0b-4743-8980-56c2c1c58bbc.png">
-
-# Create the map
-
-<img width="145" alt="Снимок экрана 2022-09-07 в 07 28 05" src="https://user-images.githubusercontent.com/9308612/188782248-b7895eb1-86a9-4f06-9309-43c6b3a3a728.png">
-
-## New map
-
-Create the new map by pressing **New** button from the toolbar
-
-### Empty map
-
-To create empty map, define its size by choosing option from drop-down list or enter required size manually in the text fields and press Ok button. Check **Two level map** option to create map with underground.
-`Note: there are no limits on map size but be careful with sizes larger predefined XL size. It will be processed quite long to create even empty map. Also, it will be difficult to work with the huge maps because of possible performance issues`
-
-Other parameters won't be used for empty map.
-
-<img width="413" alt="Снимок экрана 2022-09-07 в 07 31 07" src="https://user-images.githubusercontent.com/9308612/188782588-c9f1a164-df1e-46bc-a6d3-24ff1e5396c2.png">
-
-### Random map
-
-To generate random map, check the **Random map** option and configure map parameters. You can select template from the drop-down list.
-
-<img width="439" alt="Снимок экрана 2022-09-07 в 07 36 34" src="https://user-images.githubusercontent.com/9308612/188783256-7e498238-14a0-4377-8c09-d702d54ee7d9.png">
-
-Templates are dynamically filtered depending on parameters you choose.
-
-* [Default] template means that template will be randomly chosen
-* If you see empty list it means that there are no templates fit your settings. It could be related to the settings chosen or it can mean that there are no templates install.
-
-<img width="412" alt="Снимок экрана 2022-09-07 в 07 37 35" src="https://user-images.githubusercontent.com/9308612/188783360-1c042782-328d-4692-952f-58fa5110d0d0.png">
-
-## Map load & save
-
-To load the map, press open and select map file from the browser.
-
-You can load both *.h3m and *.vmap formats but for saving *.vmap is allowed only.
-
-# Views
-
-There are 3 buttons switching views <img width="131" alt="Снимок экрана 2022-09-07 в 06 48 08" src="https://user-images.githubusercontent.com/9308612/188777527-b7106146-0d8c-4f14-b78d-f13512bc7bad.png">
-
-### Ground/underground
-
-**"U/G"** switches you between ground and underground
-
-### Grid view
-
-**Grid** show/hide grid
-
-<img width="153" alt="Снимок экрана 2022-09-07 в 06 49 39" src="https://user-images.githubusercontent.com/9308612/188777723-934d693b-247d-42a6-815c-aecd0d34f653.png">
-
-### Passability view
-
-**Pass** show/hide passability map
-
-<img width="190" alt="Снимок экрана 2022-09-07 в 06 51 46" src="https://user-images.githubusercontent.com/9308612/188778010-a1d45d59-7333-4432-b83f-57190fbe09f4.png">
-
-# Setup terrain
-
-1. Select brush you want
-<img width="124" alt="Снимок экрана 2022-09-07 в 06 38 46" src="https://user-images.githubusercontent.com/9308612/188776299-fd688696-a98d-4f89-8bef-e81c90d3724b.png">
-
-2. Select area you'd like to change
-
-`Note: left mouse button selects tiles, right button removes selection`
-
-![Снимок экрана 2022-09-07 в 06 39 53](https://user-images.githubusercontent.com/9308612/188776895-ce1607fb-694b-4edb-b0cc-263a0c5d04b8.png)
-
-3. Press terrain you want
-
-<img width="116" alt="Снимок экрана 2022-09-07 в 06 45 49" src="https://user-images.githubusercontent.com/9308612/188777176-1167561a-f23c-400a-a57b-be7fc90accae.png">
-
-### Drawing roads and rivers
-
-Actually, the process to draw rivers or roads is exactly the same as for terrains. You need to select tiles and then choose road/river type from the panel. 
-
-<img width="232" alt="Снимок экрана 2022-09-13 в 21 25 18" src="https://user-images.githubusercontent.com/9308612/189968965-7adbd76c-9ffc-46e5-aeb7-9a79214cc506.png">
-
-To erase roads or rivers, you need to select tiles to be cleaned and press empty button.
-
-<img width="130" alt="Снимок экрана 2022-09-13 в 21 26 54" src="https://user-images.githubusercontent.com/9308612/189969309-87ff7818-2915-4b38-b9db-ec4a616d18e7.png">
-
-_Erasing works either for roads or for rivers, e.g. empty button from the roads tab erases roads only, but not rivers. You also can safely select bigger area, because it won't erase anything on tiles without roads/rivers accordingly_
-
-## About brushes
-* Buttons "1", "2", "4" - 1x1, 2x2, 4x4 brush sizes accordingly
-* Button "[]" - non-additive rectangle selection
-* Button "O" - lasso brush (not implemented yet)
-* Button "E" - object erase, not a brush
-
-
-## Fill obstacles
-
-Map editor supports automatic obstacle placement.
-Obstacle types are automatically selected for appropriate terrain types
-
-To do that, select area (see Setup terrains) and press **Fill** button from the toolbar
-<img width="222" alt="Снимок экрана 2022-09-07 в 06 56 05" src="https://user-images.githubusercontent.com/9308612/188778572-f80b3706-1713-40c7-a5aa-e4c3b9fc6649.png">
-
-<img width="335" alt="Снимок экрана 2022-09-07 в 06 57 23" src="https://user-images.githubusercontent.com/9308612/188778694-507009a1-4bb0-4f37-afc7-4aa26a6f3eeb.png">
-
-<img width="350" alt="Снимок экрана 2022-09-07 в 06 57 41" src="https://user-images.githubusercontent.com/9308612/188778728-f66adcbe-9cf2-41f2-8947-f60b38901317.png">
-
-`Note: obstacle placer may occupy few neighbour tiles outside of selected area`
-
-# Manipulating objects
-
-## Adding new objects
-
-1. Find the object you'd like to place in the object browser
-
-<img width="188" alt="Снимок экрана 2022-09-07 в 07 00 59" src="https://user-images.githubusercontent.com/9308612/188779107-dc2ab212-9ed2-48ee-ba0d-7856b94a87b1.png">
-
-2. You can also see selected object in preview area in the left part of application window
-
-<img width="130" alt="Снимок экрана 2022-09-07 в 07 02 19" src="https://user-images.githubusercontent.com/9308612/188779263-a78577f7-8278-4927-a44e-18a7d85e2f64.png">
-
-3. Hold mouse at object you want to place and move it to the map. You will see transparent object. Release object at point to confirm its creation
-
-<img width="181" alt="Снимок экрана 2022-09-07 в 07 03 02" src="https://user-images.githubusercontent.com/9308612/188779350-653bad29-c54f-471b-93aa-90096da6d98c.png">
-
-4. Press somewhere on the map to locate object.
-
-**Right click over the scene - cancel object placement**
-
-## Removing objects
-
-1. **Make sure that no one terrain brush is selected.** To de-select brush click on selected brush again.
-
-2. Select object you'd like to remove by simple clicking on it. You can also select multiple objects by moving mouse while left button is pressed
-<img width="170" alt="Снимок экрана 2022-09-07 в 07 09 15" src="https://user-images.githubusercontent.com/9308612/188780096-6aefcad5-e092-44c6-8647-975e95f9a8a3.png">
-
-3. Press **"E"** button from the brush panel or press **delete** on keyboard
-
-## Changing object's properties
-
-1. **Make sure that no one terrain brush is selected.** To de-select brush click on selected brush again.
-
-2. Select object you'd like to remove by simple clicking on it. **You cannot review and modify properties for several objects, multiple selection is not supported.**
-
-3. Go to the **inspector** tab. You will see object's properties
-
-<img width="197" alt="Снимок экрана 2022-09-07 в 07 12 45" src="https://user-images.githubusercontent.com/9308612/188780504-40713019-3cdd-4077-9e2f-e3417c960efe.png">
-
-4. You are able to modify properties which are not gray
-`Note: sometimes there are empty editable fields`
-
-### Assigning player to the object
-
-Objects with flags can be assigned to the player. Find Owner property in the inspector for selected object, press twice to modify right cell. Type player number from **0 to 7 or type NEUTRAL** for neutral objects.
-
-# Set up the map
-
-You can modify general properties of the map
-
-## Map name and description
-
-1. Open **Map** menu on the top and select **General**
-
-<img width="145" alt="Снимок экрана 2022-09-07 в 07 17 02" src="https://user-images.githubusercontent.com/9308612/188780943-70578b79-001b-45a2-bdfd-94577db40a6b.png">
-
-2. You will see a new window with text fields to edit map name and description
-
-3. Pressing **Ok** will save the changes, closing the window will discard the changes
-
-<img width="307" alt="Снимок экрана 2022-09-07 в 07 18 02" src="https://user-images.githubusercontent.com/9308612/188781063-50ce65f8-aab4-43c3-a308-22acafa7d0a2.png">
-
-## Player settings
-
-Open **Map** menu on the top and select **Player settings" 
-
-<img width="141" alt="Снимок экрана 2022-09-07 в 07 20 40" src="https://user-images.githubusercontent.com/9308612/188781357-4a6091cf-f175-4649-a000-620f306d2c46.png">
-
-You will see a window with player settings. Combobox players defines amount of players on the map. To review settings for particular player scroll the internal window. There are bunch on settings for each player you can change.
-
-`Important: at least one player must be controlled as Human/CPU. Maps without human players won't be started in the game at most cases`
-
-<img width="641" alt="Снимок экрана 2022-09-07 в 07 21 05" src="https://user-images.githubusercontent.com/9308612/188781400-7d5ba463-4f82-4dba-83ff-56210995e2c7.png">

docs/modders/Map_Editor/Map_Editor_Working_With_Mods.md

@@ -1,31 +0,0 @@
-## Enabling and disabling mods
-
-The mods mechanism used in map editor is the same as in game.
-
-To enable or disable mods
-* Start launcher, activate or deactivate mods you want
-* Close launcher
-* Run map editor
-
-There is no button to start map editor directly from launcher, however you may use this approach to control active mods from any version of vcmi.
-
-## Placing objects from mods
-
-* All objects from mods will be automatically added into objects Browser. You can type mod name into filter field to find them.
-
-<img width="269" alt="Снимок экрана 2022-09-13 в 21 14 46" src="https://user-images.githubusercontent.com/9308612/189965141-62ee0d2c-2c3e-483c-98fe-63517ed51912.png">
-
-* Objects from mods related to new terrains (if mod adds any) should not be filtered this way, instead choose terrain from terrains filter on the top of objects browser
-
-<img width="271" alt="Снимок экрана 2022-09-13 в 21 17 47" src="https://user-images.githubusercontent.com/9308612/189965836-de1fd196-2f6d-4996-a62a-e2fcb52b8d74.png">
-
-## Playing maps with mods
-
-If you place any kind of objects from the mods, obviously, you need those mods to be installed to play the map.
-Also, you need to activate them.
-
-You also may have other mods being activated in addition to what was used during map designing.
-
-### Mod versions
-
-In the future, the will be support of mods versioning so map will contain information about mods used and game can automatically search and activate required mods or let user know which are required. However, it's not implemented yet

docs/modders/Map_Objects/Boat.md

@@ -0,0 +1 @@
+TODO

docs/modders/Readme.md

@@ -1,5 +1,3 @@
-If you just want to play see [mod list](mod_list "wikilink").
-
 # Creating mod
 
 To make your own mod you need to create subdirectory in **<data dir>/Mods/** with name that will be used as identifier for your mod.
@@ -10,16 +8,16 @@ Example of how directory structure of your mod may look like:
 
 ```
     Mods/
-         myMod/
+        myMod/
-               mod.json
+            mod.json
-               Content/
+            Content/
-                        config/  - json configuration files
+                config/  - json configuration files
-                        data/    - unorganized files, mostly bitmap images (.bmp, .png, .pcx)
+                data/    - unorganized files, mostly bitmap images (.bmp, .png, .pcx)
-                        maps/    - h3m maps added or modified by mod
+                maps/    - h3m maps added or modified by mod
-                        music/   - music files. Mp3 and ogg/vorbis are supported
+                music/   - music files. Mp3 and ogg/vorbis are supported
-                        sounds/  - sound files, in wav format.
+                sounds/  - sound files, in wav format.
-                        sprites/ - animation, image sets (H3 .def files or VCMI .json files)
+                sprites/ - animation, image sets (H3 .def files or VCMI .json files)
-                        video/   - video files, .bik or .smk
+                video/   - video files, .bik or .smk
 ```
 
 ## Creating mod file
@@ -37,9 +35,41 @@ Minimalistic version of this file:
 
 See [Mod file Format](Mod_File_Format.md) for its full description.
 
+## Creation of new objects
+
+In order to create new object use following steps:
+1. Create json file with definition of new object. See list of supported object types below.
+2. Add any resources needed for this object, such as images, animations or sounds.
+2. Add reference to new object in corresponding section of mod.json file
+
+### List of supported new object types
+
+- [Random Map Template](Entities_Format/Random_Map_Template.md)
+
+- [Artifact](Entities_Format/Artifact_Format.md)
+- [Creature](Entities_Format/Creature_Format.md)
+- [Faction](Entities_Format/Faction_Format.md)
+- [Hero Class](Entities_Format/Hero_Classes_Format.md)
+- [Hero Type](Entities_Format/Hero_Type_Format.md)
+- [Spell](Entities_Format/Spell_Format.md)
+- [Secondary Skill](Entities_Format/Object_Format.md)
+
+- [Map Objects](Entities_Format/Map_Object_Format.md)
+- - [Rewardable](Map_Objects/Rewardable.md)
+- - [Creature Bank](Map_Objects/Creature_Bank.md)
+- - [Dwelling](Map_Objects/Dwelling.md)
+- - [Market](Map_Objects/Markets.md)
+- - [Boat](Map_Objects/Boat.md)
+
+- [Terrain](Entities_Format/Terrain_Format.md)
+- [River](Entities_Format/River_Format.md)
+- [Road](Entities_Format/Road_Format.md)
+- [Battlefield](Entities_Format/Battlefield_Format.md)
+- [Battle Obstacle](Entities_Format/Battle_Obstacle_Format.md)
+
 ## Game Identifiers system
 
-VCMI uses strings to reference objects:
+VCMI uses strings to reference objects. Examples:
 
 - Referencing H3 objects: `"nativeTerrain" : "sand"`. 
 Note: All mods can freely access any existing objects from H3 data.
@@ -51,7 +81,7 @@ Note: Mods can only reference object from mods that are marked as dependencies
 Note: Bonus system requires explicit definition of object type since different bonuses may require different identifier class.
 
 - Referencing object from specific mod: `"nativeTerrain" : "hota.cove:sorceress"`
-Note: In some cases, for example to resolve conflicts when multiple mods use same object name you might need to explicitly specify mod in which game needs to look up an identifier
+Note: In some cases, for example to resolve conflicts when multiple mods use same object name you might need to explicitly specify mod in which game needs to look up an identifier. Alternatively, you can use this form for clarity if you want to clearly specify that object comes from another mod.
 
 ### Modifying existing objects
 
@@ -85,7 +115,7 @@ In order to access and modify existing object you need to specify mod that you w
 ```
 Note that modification of existing objects does not requires a dependency on edited mod. Such definitions will only be used by game if corresponding mod is installed and active.
 
- This allows using objects editing not just for rebalancing mods but also to provide compatibility between two different mods or to add interaction between two mods.
+This allows using objects editing not just for rebalancing mods but also to provide compatibility between two different mods or to add interaction between two mods.
 
 ## Overriding graphical files from Heroes III
 
@@ -99,13 +129,15 @@ Note that replacing files from archives requires placing them into specific loca
 
 This includes archives added by expansions (e.g. **H3ab_bmp.lod** uses same rules as **H3Bitmap.lod**)
 
+- **Warning:** overriding graphical files from other mods is discouraged and may be removed in future versions of vcmi. Please use modification of existing objects instead.
+
 ### Replacing .def animation files
 
 Heroes III uses custom format for storing animation: def files. These files are used to store all in-game animations as well as for some GUI elements like buttons and for icon sets.
 These files can be replaced by another def file but in some cases original format can't be used. This includes but not limited to:
 -   Replacing one (or several) icons in set
 -   Replacing animation with fully-colored 32-bit images
-In VCMI these animation files can also be replaced by json description of their content. See [Animation Format](Animation_Format "wikilink") for full description of this format.
+In VCMI these animation files can also be replaced by json description of their content. See [Animation Format](Animation_Format.md) for full description of this format.
 Example: replacing single icon
 
 ``` javascript

docs/modders/Translations.md

@@ -9,6 +9,7 @@ TODO: write me
 TODO: write me
 
 ## For modders
+
 ### Adding new translation to mod
 TODO: write me
 

docs/players/Installation_Android.md

@@ -1,4 +1,4 @@
-## Download and install VCMI
+## Step 1: Download and install VCMI
 
 **This app requires original heroes 3 sod / complete files to operate, they are not supplied with this installer. it is recommended to purchase version from gog.com. Heroes 3 "hd edition" (steam version) files are not supported !!!**  
 Installation is a two step process, at first you need to install game, then you need to upload Heroes3 original data files into your android device.
@@ -7,13 +7,13 @@ Installation is a two step process, at first you need to install game, then you
 - Latest release as .apk file: <https://github.com/vcmi/vcmi/releases/latest>
 - Daily builds (unstable): <https://builds.vcmi.download/branch/develop/Android/>
 
-## Installing Heroes III data files
+## Step 2: Installing Heroes III data files
 
 - Install Heroes III on your PC or extract Heroes III data files from gog installer
 - Connect your device to PC and enable file transfer.
 - Copy "Data", "Maps" and "Mp3" from Heroes III to any folder on  mobile device, then open VCMI, select Heroes III data import option, then select the folder where you copied Heroes III data.
 
-## Troubleshooting / well known issues
+## Troubleshooting / known issues
 
 ### The game crashes on start
 

docs/players/Installation_Linux.md

@@ -1,6 +1,6 @@
 VCMI requires data from original Heroes 3: Shadow of Death or Complete editions. Data from native Linux version made by LOKI will not work.
 
-# Binaries installation
+# Step 1: Binaries installation
 
 ## Ubuntu
 
@@ -63,7 +63,7 @@ If you are interested in providing builds for other distributions, please let us
 
 Please check following developer guide: [How to build VCMI (Linux)](How_to_build_VCMI_(Linux) "wikilink")
 
-# Installing Heroes III data files
+# Step 2: Installing Heroes III data files
 
 To install VCMI you will need Heroes III: Shadow of Death or Complete edition.
 
@@ -105,7 +105,7 @@ Copy "Data", "Maps" and "Mp3" from Heroes III to `$HOME/.local/share/vcmi/`
 Or, in case of flatpak install to `$HOME/.var/app/eu.vcmi.VCMI/data/vcmi/`
 On some distributions $XDG_DATA_HOME could differ so instead you may need to use: `$XDG_DATA_HOME/vcmi/`
 
-# Launching game
+# Step 3: Launching game
 
 VCMI should be available via desktop environment menu or launcher (Games/Strategy/VCMI)
 
@@ -114,4 +114,4 @@ Or, to start game directly avoiding Launcher: `vcmiclient`
 
 # Reporting bugs
 
-Please report any issues with packages according to [Bug reporting guidelines](http://wiki.vcmi.eu/index.php?title=Bug_reporting_guidelines)
+Please report any issues with packages according to [Bug Reporting Guidelines](Bug_Reporting_Guidelines.md)

docs/players/Installation_iOS.md

@@ -1,6 +1,6 @@
 You can run VCMI on iOS 12.0 and later, all devices are supported. If you wish to run on iOS 10 or 11, you should build from source, see [How to build VCMI (iOS)](How_to_build_VCMI_(iOS) "wikilink").
 
-## Download and install VCMI
+## Step 1: Download and install VCMI
 
 - The latest release (recommended): <https://github.com/vcmi/vcmi/releases/latest>
 - Daily builds: <https://builds.vcmi.download/branch/develop/iOS/>
@@ -14,21 +14,21 @@ have the following options:
 - [Create signing assets on macOS from terminal](https://github.com/kambala-decapitator/xcode-auto-signing-assets). In the command replace `your.bundle.id` with something like `com.MY-NAME.vcmi`. After that use the above signer tool.
 - [Sign from any OS](https://github.com/indygreg/PyOxidizer/tree/main/tugger-code-signing). You'd still need to find a way to create signing assets (private key and provisioning profile) though.
 
-## Installing Heroes III data files
+## Step 2: Installing Heroes III data files
 
 Note: if you don't need in-game videos, you can omit downloading/copying file VIDEO.VID from data folder - it will save your time and space. The same applies to the Mp3 directory.
 
-### Installing data files with Finder or Windows explorer
+### Step 2.a: Installing data files with Finder or Windows explorer
 
 To play the game, you need to upload HoMM3 data files - **Data**, **Maps** and **Mp3** directories - to the device. Use Finder (or iTunes, if you're on Windows or your macOS is 10.14 or earlier) for that. You can also add various [mods](https://wiki.vcmi.eu/Mod_list) by uploading **Mods** directory. Follow [official Apple guide](https://support.apple.com/en-us/HT210598) and place files into VCMI app. Unfortunately, Finder doesn't display copy progress, give it about 10 minutes to finish.
 
-### Installing data files using iOS device only
+### Step 2.b: Installing data files using iOS device only
 
 If you have data somewhere on device or in shared folder or you have downloaded it, you can copy it directly on your iPhone/iPad using Files application.
 
 Move or copy **Data**, **Maps** and **Mp3** folders into vcmi application - it will be visible in Files along with other applications' folders.
 
-### Installing data files with Xcode on macOS
+### Step 2.c: Installing data files with Xcode on macOS
 
 You can also upload files with Xcode. You need to prepare "container" for that.
 

docs/players/Installation_macOS.md

@@ -1,7 +1,7 @@
 **For iOS installation look here:
 <https://wiki.vcmi.eu/Installation_on_iOS>**
 
-# Download and install VCMI
+# Step 1: Download and install VCMI
 
 - The latest release (recommended): <https://github.com/vcmi/vcmi/releases/latest>
 - Daily builds (might be unstable) 
@@ -12,7 +12,7 @@ If the app doesn't open, right-click the app bundle - select *Open* menu item -
 
 Please report about gameplay problem on forums: [Help & Bugs](https://forum.vcmi.eu/c/international-board/help-bugs) Make sure to specify what hardware and macOS version you use.
 
-# Installing Heroes III data files
+# Step 2: Installing Heroes III data files
 
 1.  Find a way to unpack Windows Heroes III or GOG installer. For example, use `vcmibuilder` script inside app bundle or install the game with [CrossOver](https://www.codeweavers.com/crossover) or [Wineskin](https://github.com/Gcenx/WineskinServer).
 2.  Copy (or symlink) **Data**, **Maps** and **Mp3** directories from Heroes III to:`~/Library/Application\ Support/vcmi/`