Difference between revisions of "Creature Format"
From VCMI Project Wiki
m |
(fix typo) |
||
(27 intermediate revisions by 6 users not shown) | |||
Line 1: | Line 1: | ||
− | + | Schema in git: [https://github.com/vcmi/vcmi/blob/develop/config/schemas/creature.json config/schemas/creature.json] | |
− | + | See thread http://forum.vcmi.eu/viewtopic.php?t=533 for discussion. | |
− | |||
− | |||
− | |||
− | Creature abilities | + | ==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" : "", | ||
− | + | // (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" : "" | ||
+ | } | ||
} | } | ||
− | </ | + | </syntaxhighlight> |
− | + | ||
− | + | {{Modding}} | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− |
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" : ""
}
}
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 |