Spell Format

Current version. WiP.

{
	"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"

		//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
			
		//   anim: main effect animation (AC format), -1 - none
		//TODO: more flexible system to allow defining custom spell effects DEPRECATED
		"anim": -1,
			
		//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},

		//flags structure of bonus names,any one of these bonus grants immunity. Negatable by the Orb.
		"immunity": {"BONUS_NAME":true, ...},
			
		//optional| no default |flags structure of bonus names
		//any one of these bonus grants immunity, cant be negated
		"absoluteImmunity": {"BONUS_NAME": true, ...},

		//flags structure of bonus names, presence of all bonuses required to be affected by. Negatable by the Orb.
		"limit": {"BONUS_NAME": true, ...},

		//flags structure of bonus names, presence of all bonuses required to be affected by. Cant be negated
		"absoluteLimit": {"BONUS_NAME": true, ...},

		//graphics; mandatory; object;
		"graphics":
		{
			//  ! will be moved to bonus type config in next bonus config version
			//  iconImmune - OPTIONAL; string; 
			//resource path of icon for SPELL_IMMUNITY bonus (relative to DATA or SPRITES)
			"iconImmune":"ZVS/LIB1.RES/E_SPMET",


			//  iconScenarioBonus- mandatory, string, image resource path
			//resource path of icon for scenario bonus
			"iconScenarioBonus": "MYSPELL_B",

			//  iconEffect- mandatory, string, image resource path
			//resource path of icon for spell effects during battle
			"iconEffect": "MYSPELL_E",

			//  iconBook- mandatory, string, image resource path
			//resource path of icon for spellbook
			"iconBook": "MYSPELL_E",

			//  iconScroll- mandatory, string, image resource path
			//resource path of icon for spell scrolls
			"iconScroll": "MYSPELL_E"

		},

		//OPTIONAL; object; TODO
		"sounds":
		{
			//OPTIONAL; resourse path, casting sound
			"cast":"LIGHTBLT"

		},

		//Mandatory structure
		//configuration for no skill, basic, adv, expert
		"levels":{
			"none": {Spell level format},
			"basic":{Spell level format},
			"advanced":{Spell level format},
			"expert":{Spell level format}
		}
	}

}

Spell level format

{
			//Mandatory, localizable description
			//Use {xxx} for formatting
			"description": "",


			//Mandatory, number, 
			//cost in mana points
			"cost": 1,

			//Mandatory, number
			"power": 10,

			//Mandatory, number
			"aiValue": 20,

			//Mandatory, flags structure //TODO
			// modifiers make sense for creature target
			//
			//
			"targetModifier":
			{
				"smart": false	//true: friendly/hostile based on positiveness; false: all targets
			}
			//Mandatory
			//spell range description in SRSL
			// range "X" + smart modifier = enchanter casting, expert massive spells
			// range "X" + no smart modifier = armageddon, death ripple, destroy undead

			"range": "X",

			//Optional, arbitrary name - bonus format map
			//timed effects, overriding by name
			"effects":
			{
				"firstEffect": {[bonus format]},
				"secondEffect": {[bonus format]}
			
			}
		}

Additional documentation

Targets, ranges, modifiers

• CREATURE target (only battle spells)
  • range 0: smart assumed single creature target
  • range "X" + smart modifier = enchanter casting, expert massive spells
  • range "X" + no smart modifier = armageddon, death ripple, destroy undead
  • any other range (including chain effect)
    • smart modifier: smth like cloud of confusion in H4 (if I remember correctly :) )
    • no smart modifier: like inferno, fireball etc. but target only creature

• NO_TARGET
  • range 0: target = any tile on map/battlefield (inferno, fireball etc.), DD also here but with special handling
  • range "X": no target selection,(most adventure spells)
  • any other range = any tile on map/battlefield (firewall, force field)

• OBSTACLE target
• range 0: any single obstacle
• range X: all obstacles (earthquake also goes here)

Modding related articles

Main articles
Modding changelog	Modding guidelines	How to create a town mod	Mod Handler

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

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

Outdated pages
	Mod system proposal