Difference between revisions of "Creature Format"

From VCMI Project Wiki
Jump to: navigation, search
m
(Restore forum link)
(31 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
 
* decide on long vs short format
 
* exact syntax for abilities (longer term?)
 
* creature experience
 
  
long version (83 lines):
+
==Required data==
<pre>
+
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" :
 
{
 
{
    "" : // name (for configs), should be camel case version of interface name. Examples: Pikeman, RoyalGriffin
+
// translatable names
    {
+
"name" :
        // mandatory
+
{
        "names" : ["", ""], // interface names: singular, plural
+
"singular" : "Creature",
        "level" : 0,
+
"plural" : "Creatures"
        "faction" : "", // config name of faction. Examples: Castle, Rampart
+
},
        "cost" : 0, // gold. If other, use optional longer syntax
+
"level" : 0,
        "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
+
// if set to true creature will not appear in-game randomly (e.g. as neutral creature)
        "upgrades" : "", // config name of creature that this creature can be upgraded to
+
"special" : true,  
        "cost" :
+
        {
+
// config name of faction. Examples: castle, rampart
            "Wood" : 0,
+
"faction" : "",  
            "Mercury" : 0,
+
// cost to recruit, zero values can be omitted.
            "Ore" : 0,
+
"cost" :  
            "Sulfur" : 0,
+
{
            "Crystal" : 0,
+
"wood" : 0,
            "Gems" : 0,
+
"mercury" : 0,
            "Gold" : 0
+
"ore" : 0,
        },
+
"sulfur" : 0,
        "doubleWide" : false, // if creature needs two hexes
+
"crystal" : 0,
        "shots" : 0,
+
"gems" : 0,
        "spellPoints" : 0,
+
"gold" : 0
        "abilities" :
+
},
        {
+
// "value" of creature, used to determine for example army strength
        },
+
"fightValue" : 0,
        "graphics" :
 
        {
 
            "timeBetweenFidgets" : 1.00,
 
            "troopCountLocationOffset" : 0,
 
            "attackClimaxFrame" : 0,
 
            "animationTime" :
 
            {
 
                "walk" : 1.00,
 
                "attack" : 1.00,
 
                "flight" : 1.00
 
            },
 
            "backgrounds" :
 
            {
 
                "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
 
                },
 
                "missileFrameAngles" : []
 
            }
 
        },
 
        "sounds" : // names of sound files
 
        {
 
            "attack": "",
 
            "defend": "",
 
            "killed": "",
 
            "move": "",
 
            "shoot" : "",
 
            "wince": "",
 
            "ext1" : "",
 
            "ext2" : "",
 
            "moveStart" : "",
 
            "moveEnd" : ""
 
        },
 
  
        // deprecated, move to town config
+
// "ai value" - how valuable this creature should be for AI
        "hordeGrowth" : 0, // growth bonus from horde building
+
"aiValue" : 0,
        "turretShooter" : false // if used in turret
+
    },
+
// normal growth in town or external dwellings
    // more creatures
+
"growth" : 0,
}
+
</pre>
+
// growth bonus from horde building
pikeman long (39 lines):
+
// TODO: reconsider need of this field after configurable buildings support
<pre>
+
"hordeGrowth" : 0,
{
+
    "Pikeman" :
+
// Creature stats in battle
    {
+
"attack" : 0,
        "names" : ["Pikeman", "Pikemen"],
+
"defence" : 0,
        "level" : 1,
+
"hitPoints" : 0,
        "faction" : "Castle",
+
"shots" : 0,
        "upgrades" : "Halberdier",
+
"speed" : 0,
        "cost" : 60,
+
"damage" :
        "fightValue" : 100,
+
{
        "aiValue" : 80,
+
"min" : 0,
        "growth" : 14,
+
"max" : 0
        "hitPoints" : 10,
+
},
        "speed" : 4,
+
// spellpoints this creature has, how many times creature may cast its spells
        "attack" : 4,
+
"spellPoints" : 0,
        "defence" : 5,
+
// initial size of creature army on adventure map
        "damage" : [1, 3],
+
"advMapAmount" :
        "amm" : [20, 50],
+
{
        "abilities" :
+
"min" : 0,
        {
+
"max" : 0
            "CHARGE_IMMUNITY" : {}
+
},
        },
+
        "graphics" :
+
// Creature to which this creature can be upgraded
        {
+
// Note that only one upgrade can be available from UI
            "animation" : "CPKMAN.DEF",
+
"upgrades" :
            "animationTime" :
+
[
            {
+
"anotherCreature"
                "walk" : 1.15
+
],
            }
+
 
        },
+
// Creature is 2-tiles in size on the battlefield
        "sound" :
+
"doubleWide" : false,
        {
+
 
            "attack": "PIKEATTK.wav",
+
// All creature abilities, using bonus format
            "defend": "PIKEDFND.wav",
+
"abilities" :
            "killed": "PIKEKILL.wav",
+
[
            "move": "PIKEMOVE.wav",
+
"someName1" : Bonus Format,
            "wince": "PIKEWNCE.wav"
+
"someName2" : Bonus Format
        }
+
],
    }
+
 
}
+
"hasDoubleWeek": true,
</pre>
+
 +
"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,
  
short version (65 lines):
+
// How far flying creature should move during one "round" of movement animation
<pre>
+
// This is multiplier to base value (200 pixels)
{
+
"flight" : 1.00
    "" :
+
},
    {
+
"missile" :
        // mandatory
+
{
        "names" : ["", ""],
+
// name of file for missile
        "level" : 0,
+
"animation" : "",  
        "faction" : "",
+
// Frame at which shooter shoots his projectile (e.g. releases arrow)
        "cost" : 0,
+
"attackClimaxFrame" : 0,
        "fightValue" : 0,
 
        "aiValue" : 0,
 
        "growth" : 0,
 
        "hitPoints" : 0,
 
        "speed" : 0,
 
        "attack" : 0,
 
        "defence" : 0,
 
        "damage" : [0, 0],
 
        "amm" : [0, 0],
 
        "animation" : "",
 
  
        // optional
+
// offsets between position of shooter and position where projectile should appear
        "upgrades" : "",
+
"offset" :
        "cost" :
+
{
        {
+
"upperX" : 0,
            "Wood" : 0,
+
"upperY" : 0,
            "Mercury" : 0,
+
"middleX" : 0,
            "Ore" : 0,
+
"middleY" : 0,
            "Sulfur" : 0,
+
"lowerX" : 0,
            "Crystal" : 0,
+
"lowerY" : 0
            "Gems" : 0,
+
},
            "Gold" : 0
+
// angles from which frames in .def file were rendered, -90...90 range
        },
+
// Example below will work for file that contains following frames:
        "doubleWide" : false,
+
// 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" :
+
}
        {
+
},
        },
 
        "timeBetweenFidgets" : 1.00,
 
        "troopCountLocationOffset" : 0,
 
        "attackClimaxFrame" : 0,
 
        "animationTimeWalk" : 1.00,
 
        "animationTimeAttack" : 1.00,
 
        "animationTimeFlight" : 1.00,
 
        "background120" : "",
 
        "background130" : "",
 
        "missileAnimation" : "",
 
        "missileSpin" : false,
 
        "missileOffsetUpperX" : 0,
 
        "missileOffsetUpperY" : 0,
 
        "missileOffsetMiddleX" : 0,
 
        "missileOffsetMiddleY" : 0,
 
        "missileOffsetLowerX" : 0,
 
        "missileOffsetLowerY" : 0,
 
        "missileFrameAngles" : [],
 
        "soundAttack": "",
 
        "soundDefend": "",
 
        "soundKilled": "",
 
        "soundMove": "",
 
        "soundShoot" : "",
 
        "soundWince": "",
 
        "soundExt1" : "",
 
        "soundExt2" : "",
 
        "soundMoveStart" : "",
 
        "soundMoveEnd" : "",
 
  
        // deprecated
+
// names of sound files
        "hordeGrowth" : 0,
+
"sound" :  
        "turretShooter" : false
+
{
    }
+
// 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" : ""
 +
}
 
}
 
}
</pre>
+
</syntaxhighlight>
pikeman short (30 lines):
+
 
<pre>
+
{{Modding}}
{
 
    "Pikeman" :
 
    {
 
        "names" : ["Pikeman", "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" : {}
 
        },
 
        "animation" : "CPKMAN.DEF",
 
        "animationTimeWalk" : 1.15,
 
        "soundAttack": "PIKEATTK.wav",
 
        "soundDefend": "PIKEDFND.wav",
 
        "soundKilled": "PIKEKILL.wav",
 
        "soundMove": "PIKEMOVE.wav",
 
        "soundWince": "PIKEWNCE.wav"
 
    }
 
}
 
</pre>
 

Revision as of 04:48, 3 September 2017

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,
	"defence" : 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" : "", 
			// 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 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