Apply suggestions

docs/modders/Bonus/Bonus_Types.md

@@ -255,7 +255,7 @@ Gives additional bonus to effect of all spells of selected school
 
 ### SPECIFIC_SPELL_DAMAGE
 
-For `damage` and `heal` spell effects, increases spell power by specific percentage
+For `damage`, `heal` and `demonSummon` spell effects, increases spell power by specific percentage
 
 - subtype: identifier of affected spell
 - val: bonus to spell effect, percentage

docs/modders/Entities_Format/Spell_Format.md

@@ -330,7 +330,7 @@ Casting the spell with "massive" target will randomly pick selected number of ta
 
 ```json
 
-"mod:effectId":{
+"firstSpellEffect":{
 	"type": "core:catapult"
 
 	// How many targets will be attacked by the spell
@@ -362,7 +362,7 @@ Casting the spell with "massive" target will randomly pick selected number of ta
 Configurable version of Clone spell. Casting the spell will create clone of targeted unit that belongs to side of spell caster.
 
 ```json
-"mod:effectId":{
+"firstSpellEffect":{
 	"type": "core:clone"
 
 	// Maximal tier of unit on which this spell can be cast
@@ -383,7 +383,7 @@ Target with SPELL_DAMAGE_REDUCTION bonus with value greater than 100% for any of
 
 
 ```json
-"mod:effectId":{
+"firstSpellEffect":{
 	"type": "core:damage",
 	"killByCount": false, 
 	"killByPercentage" : false,
@@ -402,7 +402,7 @@ Only bonuses from spells with specified positiveness(es) will be dispelled. See
 
 ```json
 
-"mod:effectId":{
+"firstSpellEffect":{
 	"type": "core:dispel",
 	
 	/// if set, spell will dispell other spells with "positive" flag
@@ -425,7 +425,7 @@ If parameter `minFullUnits` is non-zero, spell can only be cast if it will at le
 Spell can be used on dead units, but only if corpse is not blocked by a living unit.
 
 ```json
-"mod:effectId":{
+"firstSpellEffect":{
 	"type": "core:heal",
 	
 	/// Minimal amount of health points that this spell can restore, based on target creature health
@@ -442,21 +442,109 @@ Spell can be used on dead units, but only if corpse is not blocked by a living u
 }
 ```
 
+### Sacrifice
+
+Sacrifice spell. Allows to destroy first target, while healing the second one. Destroyed unit is completely removed from the game.
+
+Effect configuration is identical to [Heal effect](#heal).
+
+```json
+"firstSpellEffect":{
+	"type": "core:sacrifice"
+	"minFullUnits" : 1,
+	"healLevel" : "heal",
+	"healPower" : "permanent"
+}
+```
+
 ### Obstacle
 
 TODO
 
+```json
+"firstSpellEffect":{
+	"type": "core:obstacle"
+	
+	"hidden" : false,
+	"passable" : false,
+	"trap" : false,
+	"removeOnTrigger" : false,
+	"hideNative" : false,
+
+	"patchCount" : 1,
+	"turnsRemaining" : 1,
+	"triggerAbility" : "obstacleTriggerAbility",
+	
+	"attacker" : {
+		"shape" : [],
+		"range" : [],
+		"appearSound" : {},
+		"appearAnimation" : {},
+		"animation" : {},
+		"offsetY" : 0
+	},
+	
+	"defender" : {
+		"shape" : [],
+		"range" : [],
+		"appearSound" : {},
+		"appearAnimation" : {},
+		"animation" : {},
+		"offsetY" : 0
+	}
+}
+```
+
 ### Moat
 
 TODO
 
+```json
+"firstSpellEffect":{
+	"type": "core:moat"
+	
+	"hidden" : false,
+	"trap" : false,
+	"removeOnTrigger" : false,
+	"dispellable" : false,
+
+	"moatDamage" : 90,
+	"moatHexes" : [],
+
+	"triggerAbility" : "obstacleTriggerAbility",
+	
+	"defender" : {
+		"shape" : [],
+		"range" : [],
+		"appearSound" : {},
+		"appearAnimation" : {},
+		"animation" : {},
+		"offsetY" : 0
+	}
+}
+```
+
 ### Remove obstacle
 
-TODO
+Effect removes an obstacle from targeted hex
 
-### Sacrifice
+```json
+"firstSpellEffect":{
+	"type": "core:removeObstacle",
+	
+	/// If set to true, spell can remove large ("absolute") obstacles
+	"removeAbsolute" : false,
 
-TODO
+	/// If set to true, spell can remove small obstacles (H3 behavior)
+	"removeUsual" : true,
+	
+	// If set to true, spell can remove any obstacle that was created by spell
+	"removeAllSpells" : true,
+	
+	// If set to true, spell can remove obstacles that were created with specific spell
+	"removeSpells" : [ "spellA", "spellB" ],
+}
+```
 
 ### Summon
 
@@ -472,7 +560,7 @@ if `summonSameUnit` flag is set, and same creature was already summoned before,
 
 
 ```json
-"mod:effectId":{
+"firstSpellEffect":{
 	"type": "core:summon",
 	
 	/// Unit to summon
@@ -495,7 +583,7 @@ Raised amount of units is limited by (rounded down):
 - total stack size of summoned unit can not be greater than stack size of dead unit
 
 ```json
-"mod:effectId":{
+"firstSpellEffect":{
 	"type": "core:demonSummon",
 	
 	/// Unit to summon
@@ -511,7 +599,7 @@ Raised amount of units is limited by (rounded down):
 Effect instantly moves unit from its current location to targeted tile
 
 ```json
-"mod:effectId":{
+"firstSpellEffect":{
 	"type": "core:teleport",
 	
 	/// If true, unit will trigger obstacles on destination location
@@ -540,7 +628,7 @@ Value of all bonuses can be affected by following bonuses:
 - SPECIAL_FIXED_VALUE_ENCHANT: value from addInfo replaces val of bonus
 
 ```json
-"mod:effectId" : {
+"firstSpellEffect" : {
 	"type": "core:timed",
 
 	// if set to true, recasting same spell will accumulate (and prolong) effects of previous spellcast

docs/modders/Guides/Bonus_System.md

@@ -1,7 +1,20 @@
 # Bonus System Guide
 
+Bonuses are effects that can be given to various game entities. A lot of game mechanics in VCMI are implemented as bonuses. Most notably, but not limited to:
+
+- All artifact effects
+- All hero specialties
+- All secondary skill effects
+- All creature abilities
+- Large number of spells
+- Some of town building
+
+While they don't provide same level of flexibility as ERM scripting from WoG, they are way easier to use and generally can be undestood by AI. List of supported effects is rather long, and covers all H3 mechanics, as well as some additions to support WoG creature abilities, HotA, and extensions requested by modders for VCMI.
+
 ## Basic Usage
 
+See also: [List of Bonus Types](../Bonus/Bonus_Types.md)
+
 ### Bonuses without parameters
 
 Some of the simplest bonuses don't require any parameters, so all you need to do is specify the bonus type:
@@ -72,7 +85,7 @@ In addition to the `type`, `subtype` and `val` parameters, some bonuses may requ
 }
 ```
 
-This bonus allows a hero with such an artefact to upgrade any mage in their army to an enchanter. For information on how to configure addInfo for a particular bonus, please refer to the bonus types documentation.
+This bonus allows a hero with such an artefact to upgrade any mage in their army to an enchanter. For information on how to configure addInfo for a particular bonus, please refer to the [bonus types documentation](../Bonus/Bonus_Types.md).
 
 ## Advanced Usage
 
@@ -103,7 +116,7 @@ For example, a bonus given to a player would affect all their heroes, towns and
 }
 ```
 
-This speciality increases the attack of all Pixies in the army by 3, but does not affect any other units or the hero himself. The game supports multiple other limiters for various other use cases. Please refer to the bonus system reference for details.
+This speciality increases the attack of all Pixies in the army by 3, but does not affect any other units or the hero himself. The game supports multiple other limiters for various other use cases. Please refer to the [bonus limiters documentation](../Bonus/Bonus_Limiters.md). for details.
 
 ### Bonus Propagators
 
@@ -120,7 +133,7 @@ In some cases, it is preferable to extend the effect of bonuses instead. A typic
 }
 ```
 
-This propagator extends the ability to all units in the hero's army, including the unit from which it originates. It is possible to propagate the bonus to most entities that form part of the bonus system. Please refer to the bonus system reference for details.
+This propagator extends the ability to all units in the hero's army, including the unit from which it originates. It is possible to propagate the bonus to most entities that form part of the bonus system. Please refer to the [bonus propagators documentation](../Bonus/Bonus_Propagators.md) for details.
 
 ### Bonus Updaters
 
@@ -141,6 +154,8 @@ Unlike propagators and limiters, updaters do not modify the entities affected by
 
 This speciality increases the hero's attack by 1, multiplied by their level. For example, a level 20 hero would have an attack of +20.
 
+Full list of supported bonus updaters can be found in [bonus updaters documentation](../Bonus/Bonus_Updaters.md)
+
 ### Only enemy side bonus
 
 When creating a battle-wide bonus, you can use the 'BATTLE_WIDE' propagator to achieve the desired effect. Similarly, when creating a bonus that only affects allied units, use the 'HERO' propagator instead. However, due to the implementation details of the game's bonus system, bonuses that only affect the enemy side require specific configuration.
@@ -171,7 +186,7 @@ As can be seen from the example, such bonuses must perform the following operati
 
 As mentioned in previous parts, the propagator allows bonuses to be propagated 'upwards', and bonuses only affect entities 'downwards' by default. Generally, it is clear which entities lie 'upwards' or 'downwards' – for example, creatures belong to an army, which belongs to a hero, who belongs to a player. Some cases might not be so clear, but you can consult the diagram below for help.
 
-In this diagram, all entities connected to an entity above are considered to be 'below', and vice versa:
+In this diagram, all entities connected to an entity above it are considered to be 'below', and vice versa:
 
 ![Bonus System Nodes Diagram](../../images/Bonus_System_Nodes.svg)