File: Creature_Format.md

package info (click to toggle)
vcmi 1.6.5%2Bdfsg-2
  • links: PTS, VCS
  • area: contrib
  • in suites: forky, sid, trixie
  • size: 32,060 kB
  • sloc: cpp: 238,971; python: 265; sh: 224; xml: 157; ansic: 78; objc: 61; makefile: 49
file content (220 lines) | stat: -rw-r--r-- 5,457 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
# 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](Creature_Help.md).

## 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

```json
// 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
			]
		},
		...
	]
}
```