User:AVS/Spell Format Version2

Current version. WiP.

Effect format

Bonus

"modID:bonus.effectName":{[bonus format]}

Special

Describes effect, implemented inside engine of mod scripts. No configuration possible except disabling/enabling it.

"modID:special.effectName":
{
	//mandatory, boolean, (default: false as fallback value for all booleans)
	"enabled": true //false
}

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":
	{
		"massive": true, //true: all targets; false: based on range
		"smart": false	//true: friendly/hostile based on positiveness; false: all targets
	}

	//Mandatory
	//spell range description in SRSL
	"range": "X",
	//Optional, arbitrary name - bonus format map
	//timed effects, overriding by name
	"effects":
	{
		{effect format]},
	//[...]
			
	}

Spell format

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

		//<SCRIPT RELATED> For a bit distant future. Just ideas.
		//
		// script identifier
		"mechanicsClient":"myClientScript",
		"mechanicsServer":"myServerScript",

		//dictionary: mod-id (string) - arbitrary data (object)
		//Initialized here, r/w accessible in-game, persistent.
		"modData":{
			"firstModID":{},
			"secondModID":{} 
			// [...]
		},

		//</SCRIPT RELATED>
	
		//   anim: main effect animation (AC format), -1 - none
		//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
		"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
		"limit": {"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",

			//TODO: more flexible system to allow defining custom spell effects 
			"animation":{[spell animation format]}
		},

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

		},

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

}

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