Revision as of 14:49, 2 October 2012

Current version of town description format.

Remaining tasks

• Remove usage of numeric ID's. Long-term goal due to heavy usage of id's in VCMI code.
• Collect any remaining hardcoded data

Split faction description from town description

Town will be split into two parts:

• faction: stores all information that can be separated from town (e.g. puzzle map, hero classes, creatures)
• town: stores only information required for town (e.g. buildings and recruitable creatures)

Current config structure

Faction node (root entry for town configuration)

{
	"town" : { ... }, // optional. Should be present for playable faction
	"nativeTerrain" : "",
	"alignment" : "", // faction alignment. Can be good, neutral (default) or evil.
	"creatureBackground"
	{
		"120px" : "",
		"130px" : ""
	}
	"puzzleMap" :
	{
		"prefix" : "", // prefix for image names, e.g. "PUZCAS" for name "PUZCAS12.png"
		"pieces" :
		[
			{
				"x" : 0
				"y" : 0
				"index" : 0 //when this piece will be opened
			}
			...
		]
	]
}

Town node

{
	"adventureMap" : // adventure map object animations
	{
		"village": "",
		"castle" : "", // town with fortifications
		"capitol": "" // town with both fort and capitol
	},
	"icons" : //icons, small and big. Built versions indicate constructed during this turn building.
	{
		"small" : "",
		"smallBuilt" : "",
		"big" : "",
		"bigBuilt" : ""
	},
	"musicTheme" : "",
	"structures" : // Structures. Represents visible graphical objects on town screen.
	[
		{ ... },
		  ...
		{ ... } 
	],
	"townName" : "", // localized town name.
	"townNames" : [ "", ""], // list of names for towns on adventure map
	"townBackground": "", // background scenery
	"guildWindow": "", // mage guild window

	"buildingsIcons": "HALLCSTL.DEF", // Not sure what to do with this

	"hallBackground": "", // Background image for town hall window
	"hallSlots": // list of buildings available in each slot of town hall window
	[
		[ [ 10, 11, 12, 13 ], [ 7, 8, 9 ], [ 5, 22 ], [ 16 ] ],
		[ [ 14, 15 ], [ 0, 1, 2, 3 ], [ 6, 17 ] ],
		[ [ 21 ], [ 18, 19 ] ],
		[ [ 30, 37 ], [ 31, 38 ], [ 32, 39 ], [ 33, 40 ] ],
		[ [ 34, 41 ], [ 35, 42 ], [ 36, 43 ] ]
	],
	"creatures" : [ [0, 1], [2, 3] ], // List of creatures available on each tier

	"buildings" : // Buildings, objects in town that affect available options
	[
		{ ... },
		  ...
		{ ... } 
	],
	"siege" : { ... },

	// Entries that should be replaced with autodetection

	"horde" : [ 2, -1 ], // Which tiers in this town have creature hordes
	"primaryResource" : 127, // Resource produced by resource silo, 127 = wood + ore
	"mageGuild" : 4, // maximum level of mages guild
	"warMachine" : 4 // war machine produced in town
}

Siege node

{
	"towers":
	{
		"top" :
		{
			"tower" :      { "x": 0, "y": 0, "image" : "" },
			"battlement" : { "x": 0, "y": 0, "image" : "" },
			"creature" :   { "x": 0, "y": 0, "cropHeight" : 0 },
			"shooter" : "" // shooter creature name
		},
		"keep" : { ... },
		"bottom" : { ... }
	},
	"gate" :
	{
		"upperWall" : { "x": 0, "y": 0, "image" : "" },
		"bottomWall": { "x": 0, "y": 0, "image" : "" },
		
		"gate" : { "x": 0, "y": 0, "image" : "" },
		"arch" : { "x": 0, "y": 0, "image" : "" }
	},
	"walls" : // destructible walls
	{
		"upper" : { "x": 0, "y": 0, "image" : "" },
		"upperMid" : { "x": 0, "y": 0, "image" : "" },
		"bottomMid" : { "x": 0, "y": 0, "image" : "" },
		"bottom" : { "x": 0, "y": 0, "image" : "" }
	},
	"moat" : { "x": 0, "y": 0, "image" : "" },
	"static" : //static non-destructible walls
	{
		"bottom" : { "x": 0, "y": 0, "image" : "" },
		"top" : { "x": 0, "y": 0, "image" : "" },
		"background" : { "x": 0, "y": 0, "image" : "" }
	}
}

Building node

{
	"id" : 0,
	"name" : "",
	"description" : "",
	"upgrades" : 0, // optional, which building can be upgraded by this one
	"requires" : [], // building requirements
	"cost" : { ... },

	//determine how this building can be built. Possible values are:
	// normal  - default value. Fulfill requirements, use resources, spend one day
	// auto    - building appears when all requirements are built
	// special - building can not be built manually
	// grail   - building reqires grail to be built
	"mode" : "auto"
}

Structure node

{
	"base" : 0, // building this structure is based on. If null - structure will be present always.
	"animation" : "", // def file with animation
	"x" : 0,
	"y" : 0,
	"z" : 0, // used for blit order. Higher value places structure close to screen
	"border" : "", // selection highlight
	"area" : "" // used to detect building selection
}