Difference between revisions of "Creature Format"

From VCMI Project Wiki
Jump to: navigation, search
m
(fix typo)
(27 intermediate revisions by 6 users not shown)
Line 1: Line 1:
This is only a proposal and not official information by the VCMI team. See thread http://forum.vcmi.eu/viewtopic.php?t=533.
+
Schema in git: [https://github.com/vcmi/vcmi/blob/develop/config/schemas/creature.json config/schemas/creature.json]
  
todo:
+
See thread http://forum.vcmi.eu/viewtopic.php?t=533 for discussion.
* remove deprecated attributes once implemented in town config
 
* better name for amm, something more self-documenting
 
* creature experience
 
  
Creature abilities use [[Bonus Format]].
+
==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==
 +
<syntaxhighlight lang="javascript">
 +
// camelCase unique creature identifier
 +
"creatureName" :
 +
{
 +
// translatable names
 +
"name" :
 +
{
 +
"singular" : "Creature",
 +
"plural" : "Creatures"
 +
},
 +
"level" : 0,
 +
 
 +
// if set to true creature will not appear in-game randomly (e.g. as neutral creature)
 +
"special" : true,
 +
 +
// config name of faction. Examples: castle, rampart
 +
"faction" : "",
 +
// cost to recruit, 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,
 +
 
 +
// "ai value" - how valuable this creature should be for AI
 +
"aiValue" : 0,
 +
 +
// normal growth in town or external dwellings
 +
"growth" : 0,
 +
 +
// growth bonus from horde building
 +
// TODO: reconsider need of this field after configurable buildings support
 +
"hordeGrowth" : 0,
 +
 +
// Creature stats in battle
 +
"attack" : 0,
 +
"defense" : 0,
 +
"hitPoints" : 0,
 +
"shots" : 0,
 +
"speed" : 0,
 +
"damage" :
 +
{
 +
"min" : 0,
 +
"max" : 0
 +
},
 +
// spellpoints this creature has, how many times creature may cast its spells
 +
"spellPoints" : 0,
 +
// initial size of creature army on adventure map
 +
"advMapAmount" :
 +
{
 +
"min" : 0,
 +
"max" : 0
 +
},
 +
 +
// Creature to which this creature can be upgraded
 +
// Note that only one upgrade can be available from UI
 +
"upgrades" :
 +
[
 +
"anotherCreature"
 +
],
 +
 
 +
// Creature is 2-tiles in size on the battlefield
 +
"doubleWide" : false,
 +
 
 +
// All creature abilities, using bonus format
 +
"abilities" :
 +
[
 +
"someName1" : Bonus Format,
 +
"someName2" : Bonus Format
 +
],
 +
 
 +
"hasDoubleWeek": true,
 +
 +
"graphics" :
 +
{
 +
// name of file with creature battle animation
 +
"animation" : "",
 +
// adventure map animation def
 +
"map" : "",
 +
// path to small icon for tooltips & hero exchange window
 +
"iconSmall" : "",
 +
// path to large icon, used on town screen and in hero screen
 +
"iconLarge" : "",
 +
 +
// animation parameters
 +
 
 +
// how often creature should play idle animation
 +
"timeBetweenFidgets" : 1.00,
 +
// unused H3 property
 +
"troopCountLocationOffset" : 0,
 +
"animationTime" :
 +
{
 +
// movement animation time.
 +
"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, for proper synchronization of attack/defense animations
 +
"attack" : 1.00,
 +
 
 +
// How far flying creature should move during one "round" of movement animation
 +
// This is multiplier to base value (200 pixels)
 +
"flight" : 1.00
 +
},
 +
"missile" :
 +
{
 +
// name of file for missile
 +
"animation" : "",
  
long version (83 lines):
+
// (VCMI 1.1 or later only) indicates that creature uses ray animation for ranged attacks instead of missile image (e.g. Evil Eye)
<pre>
+
"ray" :  
{
+
[
    "" : // name (for configs), should be camel case version of interface name. Examples: Pikeman, RoyalGriffin
+
{ // definition of first (top-most) line in the ray
    {
+
"start" : [ 160, 192, 0, 255 ], // color (RGBA components) of ray at starting point
        // mandatory
+
"end" : [ 160, 192, 0, 64 ]  // color (RGBA components) of ray at finishing point
        "name" :
+
},
        {
+
{}, // definition of second from top line in the ray, identical format
            "singular" : "",
+
... // definitions of remaining lines, till desired width of the ray
            "plural" : ""
+
],
        },
+
// Frame at which shooter shoots his projectile (e.g. releases arrow)
        "level" : 0,
+
"attackClimaxFrame" : 0,
        "faction" : "", // config name of faction. Examples: Castle, Rampart
 
        "cost" : 0, // gold. If other, use optional longer syntax
 
        "fightValue" : 0,
 
        "aiValue" : 0,
 
        "growth" : 0,
 
        "hitPoints" : 0,
 
        "speed" : 0,
 
        "attack" : 0,
 
        "defence" : 0,
 
        "damage" : [0, 0], // damage min, max. If same use single integer
 
        "amm" : [0, 0], // adventure map amount. If same use single integer
 
        "graphics" :
 
        {
 
            "animation" : "" // name of def file
 
        },
 
  
        // optional
+
// offsets between position of shooter and position where projectile should appear
        "upgrades" : [], // config names of creatures that this creature can be upgraded to
+
"offset" :
        "doubleWide" : false,
+
{
        "cost" :
+
"upperX" : 0,
        {
+
"upperY" : 0,
            "Wood" : 0,
+
"middleX" : 0,
            "Mercury" : 0,
+
"middleY" : 0,
            "Ore" : 0,
+
"lowerX" : 0,
            "Sulfur" : 0,
+
"lowerY" : 0
            "Crystal" : 0,
+
},
            "Gems" : 0,
+
// angles from which frames in .def file were rendered, -90...90 range
            "Gold" : 0
+
// Example below will work for file that contains following frames:
        },
+
// 1) facing top, 2) facing top-right, 3)facing right,
        "shots" : 0,
+
// 4) facing bottom-right 5) facing bottom.
        "spellPoints" : 0,
+
"frameAngles" : [ -90, -45, 0, 45, 90]
        "abilities" :
+
}
        {
+
},
        },
 
        "graphics" :
 
        {
 
            "timeBetweenFidgets" : 1.00,
 
            "troopCountLocationOffset" : 0,
 
            "attackClimaxFrame" : 0,
 
            "animationTime" :
 
            {
 
                "walk" : 1.00,
 
                "attack" : 1.00,
 
                "flight" : 1.00
 
            },
 
            "background" :
 
            {
 
                "120" : "", // if empty, uses faction background
 
                "130" : ""  // if empty, uses faction background
 
            },
 
            "missile" :
 
            {
 
                "animation" : "", // name of def file for missile
 
                "spin" : false,
 
                "offset" :
 
                {
 
                    "upperX" : 0,
 
                    "upperY" : 0,
 
                    "middleX" : 0,
 
                    "middleY" : 0,
 
                    "lowerX" : 0,
 
                    "lowerY" : 0
 
                },
 
                "frameAngles" : []
 
            }
 
        },
 
        "sound" : // names of sound files
 
        {
 
            "attack": "",
 
            "defend": "",
 
            "killed": "",
 
            "move": "",
 
            "shoot" : "",
 
            "wince": "",
 
            "moveStart" : "",
 
            "moveEnd" : ""
 
        },
 
  
        // deprecated, move to town config
+
// names of sound files
        "hordeGrowth" : 0, // growth bonus from horde building
+
"sound" :
        "turretShooter" : false // if used in turret
+
{
    },
+
// Creature attack enemy in melee (counter-)attack
    // more creatures
+
"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" : ""
 +
}
 
}
 
}
</pre>
+
</syntaxhighlight>
pikeman long (39 lines):
+
 
<pre>
+
{{Modding}}
{
 
    "Pikeman" :
 
    {
 
        "name" :
 
        {
 
            "singular" : "Pikeman",
 
            "plural" : "Pikemen"
 
        },
 
        "level" : 1,
 
        "faction" : "Castle",
 
        "upgrades" : ["Halberdier"],
 
        "cost" : 60,
 
        "fightValue" : 100,
 
        "aiValue" : 80,
 
        "growth" : 14,
 
        "hitPoints" : 10,
 
        "speed" : 4,
 
        "attack" : 4,
 
        "defence" : 5,
 
        "damage" : [1, 3],
 
        "amm" : [20, 50],
 
        "abilities" :
 
        {
 
            "CHARGE_IMMUNITY" : {}
 
        },
 
        "graphics" :
 
        {
 
            "animation" : "CPKMAN.DEF",
 
            "animationTime" :
 
            {
 
                "walk" : 1.15
 
            }
 
        },
 
        "sound" :
 
        {
 
            "attack": "PIKEATTK.wav",
 
            "defend": "PIKEDFND.wav",
 
            "killed": "PIKEKILL.wav",
 
            "move": "PIKEMOVE.wav",
 
            "wince": "PIKEWNCE.wav"
 
        }
 
    }
 
}
 
</pre>
 

Revision as of 19:48, 3 August 2023

Schema in git: config/schemas/creature.json

See thread http://forum.vcmi.eu/viewtopic.php?t=533 for discussion.

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
	"name" :
	{
		"singular" : "Creature",
		"plural" : "Creatures"
	},
	"level" : 0,

	// if set to true creature will not appear in-game randomly (e.g. as neutral creature)
	"special" : true, 
	
	// config name of faction. Examples: castle, rampart
	"faction" : "", 
	// cost to recruit, 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,

	// "ai value" - how valuable this creature should be for AI
	"aiValue" : 0,
	
	// normal growth in town or external dwellings
	"growth" : 0,
	
	// growth bonus from horde building
	// TODO: reconsider need of this field after configurable buildings support
	"hordeGrowth" : 0,
	
	// Creature stats in battle
	"attack" : 0,
	"defense" : 0,
	"hitPoints" : 0,
	"shots" : 0,
	"speed" : 0,
	"damage" :
	{
		"min" : 0,
		"max" : 0
	},
	// spellpoints this creature has, how many times creature may cast its spells
	"spellPoints" : 0,
	// initial size of creature army on adventure map
	"advMapAmount" :
	{
		"min" : 0,
		"max" : 0
	},
	
	// Creature to which this creature can be upgraded
	// Note that only one upgrade can be available from UI
	"upgrades" :
	[
		"anotherCreature"
	],

	// Creature is 2-tiles in size on the battlefield
	"doubleWide" : false,

	// All creature abilities, using bonus format
	"abilities" :
	[
		"someName1" : Bonus Format,
		"someName2" : Bonus Format
	],

	"hasDoubleWeek": true,
	
	"graphics" :
	{
		// name of file with creature battle animation
		"animation" : "",
		// adventure map animation def
		"map" : "",
		// path to small icon for tooltips & hero exchange window
		"iconSmall" : "",
		// path to large icon, used on town screen and in hero screen
		"iconLarge" : "",
		
		// animation parameters

		// how often creature should play idle animation
		"timeBetweenFidgets" : 1.00,
		// unused H3 property
		"troopCountLocationOffset" : 0,
		"animationTime" :
		{
			// movement animation time.
			"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, for proper synchronization of attack/defense animations
			"attack" : 1.00,

			// How far flying creature should move during one "round" of movement animation
			// This is multiplier to base value (200 pixels)
			"flight" : 1.00
		},
		"missile" :
		{
			// name of file for missile
			"animation" : "", 

			// (VCMI 1.1 or later only) 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,

			// offsets between position of shooter and position where projectile should appear
			"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" : ""
	}
}


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