Difference between revisions of "Object Format"

From VCMI Project Wiki
Jump to: navigation, search
(→‎Object format)
Line 1: Line 1:
−
== Object type format ==
+
==Description==
−
 
+
Work-in-progress draft, not implemented in code
−
''Current draft. WiP.''
 
  
 +
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
 +
== Object group format ==
 
<syntaxhighlight lang="javascript">
 
<syntaxhighlight lang="javascript">
  
 
{
 
{
−
  "objectTypes":  
+
"myCoolObjectGroup":
−
  [
+
{
−
+
//numeric ID, mandatory for h3/wog objects, shall be unique if not defined
−
"myCoolObject":{
+
//not recommended for VCMI objects
−
//numeric ID, mandatory for h3/wog objects, shall be unique is defined
+
"id":689
−
//not recommended for VCMI objects, shall be unique is defined, default: engine defined
 
−
"id":689,
 
−
 
−
//Mandatory for new objects,
 
−
// human readable name, localized
 
−
//default for original objects from "OBJNAMES.TXT"
 
−
"name": "My cool object",
 
−
 
 
−
//if true, activable tiles are not visitable, but activable from neighbouring tile.
 
−
//default false
 
−
"blockVisit" : true,
 
−
 
 
−
//if true object can be visited from top
 
−
//default false
 
−
"topVisitable" : false,
 
−
 
 
−
//range of numeric sub id`s, mapped to this object type. Optional for h3/wog objects.
 
−
//not recommended for VCMI objects.
 
−
"subIdMax":0,
 
−
"subIdMin":1,
 
−
 
 
−
//defaults for objects of this type (see below)
 
−
//optional
 
−
//Note: objects of same type that have random object, should have identical masks
 
−
"instance":
 
−
{
 
−
"mask":[
 
−
"00000000",
 
−
"00000000",
 
−
"00000000",
 
−
"0000VVVV",
 
−
"0000VBBB",
 
−
"0000VBBA"],
 
−
}
 
  
 +
//TODO: define C++/script class name that describes behavior of this object
 
}
 
}
  
 
   ]
 
   ]
 
}
 
}
−
 
−
 
 
</syntaxhighlight>
 
</syntaxhighlight>
−
 
+
== Object format ==
−
'''Example:'''
 
−
 
 
 
<syntaxhighlight lang="javascript">
 
<syntaxhighlight lang="javascript">
  
 
{
 
{
−
  "objectTypes":  
+
"myCoolObject":
−
  [
+
{
−
+
// defines base object class this object belongs to
−
"artifact":{
+
"base" : "myCoolObjectGroup",
−
"id":5,
 
−
"blockVisit" : true
 
−
},
 
  
−
"treasureChest":{
+
//numeric sub ID, mandatory for h3/wog objects, shall be unique if not defined
−
"id":101,
+
//not recommended for VCMI objects
−
"subIdMax":0,
+
"id":689,
−
"blockVisit" : true
+
−
},
+
//Mandatory for new objects,
 +
// human readable name, localized
 +
//default for original objects from "OBJNAMES.TXT"  
 +
"name": "My cool object",
  
−
"treasureChestWoG":{
+
// parameters that will be passed over to class that controls behavior of the object
−
"id":101,
+
"parameters" : {
−
"subIdMin":1,
+
"producedResources" : "gold",
−
"blockVisit" : true
+
"producedValue" : 1000
−
},
+
}
−
 
 
−
"pyramid": {
 
−
"id":63,
 
−
"subIdMax":0 //subtype 0
 
−
},
 
−
 
 
−
"wogObject": {
 
−
"id":63,
 
−
"subIdMin":1 //subtype> 0
 
 
}
 
}
  
 
   ]
 
   ]
 
}
 
}
−
 
 
</syntaxhighlight>
 
</syntaxhighlight>
−
 
+
== Object template format ==
−
== Object format ==
 
−
 
 
−
''Current draft. WiP.''
 
−
 
 
−
* Used by editor, RMG, (???) by engine for random new objects.
 
−
* analogue of "ZOBJCTS.TXT", "ZEOBJTS.TXT", "ZAOBJTS.TXT" from WoG.
 
−
 
 
 
<syntaxhighlight lang="javascript">
 
<syntaxhighlight lang="javascript">
 +
{
 +
"myCoolObjectTemplate" :
 +
{
 +
// defines base object class this object belongs to
 +
"base" : "myCoolObject",
  
−
{"objects":[
+
// resource ID  of animation, relative to SPRITES directory (def file or json file)
 +
"animation":"DEFNAME.def",
  
−
{
+
// directions from which hero can visit this object.
−
//mandatory
+
// "+" means that object can be visited from that direction, or "-" othervice
−
//resource ID  of animation, relative to SPRITES(def file or json file (*) )
+
// if central symbol is "+" then object is visitable by standing on it (most of buildings)
−
"animation":"DEFNAME",
+
// if central symbol is "-" then object is visitable only from adjacent tiles (most of pickable objects)
−
+
"visitableFrom" : [
 +
"---",
 +
"+++",
 +
"+++"
 +
],
  
−
//mandatory
+
// passability of the object
−
//alternative to H3M actions, passability
 
 
// 0=not visible, passable
 
// 0=not visible, passable
 
// V=visible, passable
 
// V=visible, passable
 
// B=blocked, visible
 
// B=blocked, visible
−
// A=activable, visible, passable depending on blockVisit flag of object type.
+
// H=blocked, not visible
 +
// A=activable, visible, passable depending on visitableFrom field
 
//top and left leading zeros are optional and in fact ignored
 
//top and left leading zeros are optional and in fact ignored
 
//bottom, right corner of mask = bottom right corner of animation frame
 
//bottom, right corner of mask = bottom right corner of animation frame
−
//animation shall not exceed visible mask space
+
//animation can not be larger than size of mask
 
"mask":[
 
"mask":[
 
"00000000",
 
"00000000",
Line 125: Line 85:
 
"00000000",
 
"00000000",
 
"0000VVVV",
 
"0000VVVV",
−
"0000VBBB",
+
"0000HBBB",
−
"0000VBBA"],
+
"0000HHBA"
−
 
+
],
−
//mandatory (?)
 
−
"id":"objectType", //object type from object type config. (!) Only string id`s.
 
  
 
//optional; default: all terrains except rock
 
//optional; default: all terrains except rock
Line 140: Line 98:
 
"tags":["dirt", "sand", "mine"],
 
"tags":["dirt", "sand", "mine"],
  
−
//mandatory
+
//zindex, defines order in which objects on same tile will be blit. optional, default is 0  
−
//numeric ((?) needed) or full string object id
 
−
//(?) id not required if subid in full identifier
 
−
"subId":34,//or "objectType.objectName" f.e. "creature.pikeman"
 
−
 
−
//
 
−
"group":"",  
 
−
 
 
−
 
 
−
//zindex; optional; default: 0  
 
 
//NOTE: legacy overlay objects has zindex = -1.000.000
 
//NOTE: legacy overlay objects has zindex = -1.000.000
 
"zIndex": 0
 
"zIndex": 0
−
 
 
}
 
}
−
 
 
]}
 
]}
−
 
 
</syntaxhighlight>
 
</syntaxhighlight>
−
 
−
 
 
{{Modding}}
 
{{Modding}}

Revision as of 20:25, 19 December 2013

Description

Work-in-progress draft, not implemented in code

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

Object group format

{
	"myCoolObjectGroup":
	{
		//numeric ID, mandatory for h3/wog objects, shall be unique if not defined
		//not recommended for VCMI objects
		"id":689

		//TODO: define C++/script class name that describes behavior of this object
	}

   ]
}

Object format

{
	"myCoolObject":
	{
		// defines base object class this object belongs to
		"base" : "myCoolObjectGroup",

		//numeric sub ID, mandatory for h3/wog objects, shall be unique if not defined
		//not recommended for VCMI objects
		"id":689,
		
		//Mandatory for new objects,
		// human readable name, localized 
		//default for original objects from "OBJNAMES.TXT" 
		"name": "My cool object",

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

   ]
}

Object template format

{
	"myCoolObjectTemplate" : 
	{
		// defines base object class this object belongs to
		"base" : "myCoolObject",

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

		// directions from which hero can visit this object.
		// "+" means that object can be visited from that direction, or "-" othervice
		// if central symbol is "+" then object is visitable by standing on it (most of buildings)
		// if central symbol is "-" then object is visitable only from adjacent tiles (most of pickable objects)
		"visitableFrom" : [
			"---",
			"+++",
			"+++"
		],

		// passability of the object
		// 0=not visible, passable
		// V=visible, passable
		// B=blocked, visible
		// H=blocked, not visible
		// A=activable, visible, passable depending on visitableFrom field
		//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",
			"0000HHBA"
		],

		//optional; default: all terrains except rock
		//allowed terrain types to place object too, can be overridden in editor. Affects also RMG.
		"landscape":["dirt", "sand"],

		//optional; default: all terrains except rock
		// 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 = -1.000.000
		"zIndex": 0
	}
]}

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
Retrieved from "https://wiki.vcmi.eu/index.php?title=Object_Format&oldid=1336"