vcmi/docs/modders/Object_Format.md

Description

Full object consists from 3 parts:

• Object group - set of objects that have similar behavior and share same identifier in H3 (towns, heroes, mines, etc)
• Object type - object with fixed behavior but without fixed appearance. Multiple objects types may share same group
• Object template - defines appearance of an object - image used to display it, its size & blockmap. These entries only describe templates that will be used when object is placed via map editor or generated by the game. When new object is created its starting appearance will be copied from template

To create visitable object which grants all kinds of rewards (gold, experience, Bonuses etc...), see Rewardable page.

Object group format

{
	"myCoolObjectGroup":
	{
		//numeric ID, mandatory for h3/wog objects, shall be unique if not defined
		//used only for H3 objects, mods can not be used by mods
		"index":123,

		//Mandatory for new objects,
		// human readable name, localized 
		//default for original objects from "OBJNAMES.TXT" 
		"name": "My cool object",

		//defines C++/script class name that handles behavior of this object
		"handler" : "mine",

		// default values, will be merged with each type during loading
		"base" : { <object type format> },

		"types" : {
			<list of object types, see below>
		}
	}
}

Object type format

{
	"myCoolObject":
	{
		//numeric sub ID, mandatory for h3/wog objects, shall be unique if set
		//used only for H3 objects, can not be used by mods
		"index":123,

		// parameters that will be passed over to class that controls behavior of the object
		"producedResources" : "gold",
		"producedValue" : 1000

		// TODO: allow better selection of template for object, instead of just terrain
		// field describes how object template will be selected if there are multiple possiblities
		// exact behavior and format depends on object type
		"filter" : { ... },

		// Data for random map generator that describes how object should be placed.
		// If this entry is missing object will not be placed by RMG
		"rmg" : {
			// How valuable this object is, 1k = worthless, 20k = relic level
			"value" : 5000,

			// Optional, how many of such objects can be placed on map
			"mapLimit" : 25,

			// Optional, how many of such objects can be placed in one zone
			"zoneLimit" : 4,

			// Rarity of object, 10 = rare, 100 = common
			"rarity" : 50
		}

		// default values, will be merged with each template during loading
		// mostly needed to avoid redefining whole template to change 1-2 fields
		"base" : { <template format> },

		"templates" : {
			<templates description, see below>
		}
	}
}

Object template format

{
	"myCoolObjectTemplate" : 
	{
		// resource ID  of animation, relative to SPRITES directory (def file or json file)
		"animation":"DEFNAME.def",

		// resource ID  of animation for mapeditor, relative to SPRITES directory (def file or json file)
		//0.98c+
		"editorAnimation":"DEFNAME.def",

		// directions from which hero can visit this object.
		// "+" means that object can be visited from that direction, or "-" othervice
		// default not visitable
		"visitableFrom" : [
			"---",
			"+++",
			"+++"
		],

		// passability of the object
		// 0=not visible, passable. Space symbol ' ' can be used as well
		// V=visible, passable
		// B=blocked, visible
		// H=hidden - blocked, not visible tile
		// A=activable, visible, passable depending on visitableFrom field
		// T=trigger - visiting the tile will trigger the object, tile is not visible (e.g. event)
		//top and left leading zeros are optional and in fact ignored
		//bottom, right corner of mask = bottom right corner of animation frame
		//animation can not be larger than size of mask
		"mask":[
			"00000000",
			"00000000",
			"00000000",
			"0000VVVV",
			"0000HBBB",
			"0000HHAT"
		],

		// optional; default or if explicitly set to null: all terrains except rock
		// allowed terrain types to place object too. Affects also RMG.
		// Note that map editor will still allow to place object on other terrains
                // allowed terrain types: "dirt", "sand", "grass", "snow", "swamp", "rough", "subterra", "lava", "water", "rock"
		"allowedTerrains":["dirt", "sand"],

		// TODO, default - empty
		// tags from object type are always present (???)
		// List of tags that can be used to locate object in map editor
		"tags":["dirt", "sand", "mine"],

		//zindex, defines order in which objects on same tile will be blit. optional, default is 0 
		//NOTE: legacy overlay objects has zindex = 100
		"zIndex": 0
	}
}