vcmi/docs/modders/Entities_Format/Creature_Format.md

Creature Format

This page tells you what you need to do to make your creature work. For help, tips and advices, read the creature help.

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

// camelCase unique creature identifier
"creatureName" : 
{
	// Translatable names for this creature
	"name" :
	{
		"singular" : "Creature",
		"plural" : "Creatures"
	},

	// Description of creature
	"description" : "",

	"level" : 0,

	// Marks this object as special and not available by default
	"special" : true, 
	
	// If set, this creature will never be picked as random monster on premade maps and will not appear in Refugee Camp
	// Random map generator does not checks for this flag and can still pick this creature
	"excludeFromRandomization" : false,

	// Faction this creature belongs to. Examples: castle, rampart
	"faction" : "", 

	// Cost to recruit this creature, 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,

	// Describes how valuable this creature is to AI. Usually similar to fightValue
	"aiValue" : 0,
	
	// Basic growth of this creature in town or in external dwellings
	"growth" : 0,
	
	// Bonus growth of this creature from built horde, if any
	"horde" : 0,
	
	// Creature stats in battle
	"attack" : 0,
	"defense" : 0,
	"hitPoints" : 0,
	"speed" : 0,
	"damage" :
	{
		"min" : 0,
		"max" : 0
	},

	// Number of shots this creature has, required only for ranged units
	"shots" : 0,

	// Spell points this creature has (usually equal to number of casts)
	"spellPoints" : 0,

	// Initial size of random stacks on adventure map
	"advMapAmount" :
	{
		"min" : 0,
		"max" : 0
	},
	
	// List of creatures to which this one can be upgraded
	"upgrades" :
	[
		"anotherCreature"
	],

	// If set, creature will be two tiles wide on battlefield
	"doubleWide" : false,

	// Creature abilities described using Bonus system
	"abilities" :
	[
		"someName1" : Bonus Format,
		"someName2" : Bonus Format
	],

	// creature may receive "week of" events
	"hasDoubleWeek": true,
	
	"graphics" :
	{
		// File with animation of this creature in battles
		"animation" : "",
		// File with animation of this creature on adventure map
		"map" : "",
		// Optional. Object mask that describes on which tiles object is visible/blocked/activatable
		"mapMask" : [ "VV", "VA" ],

		// Small icon for this creature, used for example in exchange screen
		"iconSmall" : "",
		// Large icon for this creature, used for example in town screen
		"iconLarge" : "",
		
		// animation parameters

		// how often creature should play idle animation
		"timeBetweenFidgets" : 1.00,

		"animationTime" :
		{
			// movement animation time factor
			"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, likely for proper synchronization of attack/defense animations
			"attack" : 1.00,
		},
		"missile" :
		{
			// name of file for missile
			"animation" : "", 

			// 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,

			// Position where projectile image appears during shooting in specific direction
			"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" : ""
	},
	
	// Stack experience, using bonus system
	"stackExperience" : [
		{
			// Bonus description
			"bonus" : { BONUS_FORMAT },
			// Per-level value of bonus. Must have 10 elements
			"values" : [
				0, 0, 1, 1, 2, 2, 3, 3, 4, 4
			]
		},
		...
	]
}