2023-09-01 12:09:01 +02:00
< [Documentation ](../../Readme.md ) / [Modding ](../Readme.md ) / Entities Format / Faction Format
2023-08-12 11:39:44 +02:00
## Required data
In order to make functional town you also need:
### Images
- Creature backgrounds images, 120x100 and 130x100 versions (2 images)
- Set of puzzle map pieces (48 images)
- Background scenery (1 image)
- Mage guild window view (1 image)
- Town hall background (1 image)
- Set of town icons, consists from all possible combinations of: (8
images total)
- small and big icons
- village and fort icons
- built and normal icons
- Set for castle siege screen, consists from:
- Background (1 image)
- Destructible towers (3 parts, 3 images each)
- Destructible walls (4 parts, 3 images each)
- Static walls (3 images)
- Town gates (5 images)
- Moat (2 images)
### Animation
- Adventure map images for village, town and capitol (3 def files)
### Music
- Town theme music track (1 music file)
### Buildings
Each town requires a set of buildings (Around 30-45 buildings)
- Town animation file (1 animation file)
- Selection highlight (1 image)
- Selection area (1 image)
- Town hall icon (1 image)
## Faction node (root entry for town configuration)
2023-09-12 14:52:45 +02:00
```jsonc
// Unique faction identifier.
"myFaction" :
2023-08-12 11:39:44 +02:00
{
// Main part of town description, see below
// Optional but it should be present for playable faction
"town" : { ... },
2023-09-12 14:52:45 +02:00
// Native terrain for creatures. Creatures fighting on native terrain receive several bonuses
2023-08-12 11:39:44 +02:00
"nativeTerrain" : "grass",
2023-09-12 14:52:45 +02:00
// Localizable faction name, e.g. "Rampart"
2023-08-12 11:39:44 +02:00
"name" : "",
// Faction alignment. Can be good, neutral (default) or evil.
"alignment" : "",
// Backgrounds for creature screen, two versions: 120px-height and 130-px height
"creatureBackground"
{
// Paths to background images
"120px" : "",
"130px" : ""
2023-09-12 14:52:45 +02:00
},
// Identifier of boat type that is produced by shipyard and used by heroes in water taverns or prisons
"boat" : "boatFortress",
// Random map generator places player/cpu-owned towns underground if true is specified and on the ground otherwise. Parameter is unused for maps without underground.
"preferUndergroundPlacement" : false
2023-08-12 11:39:44 +02:00
// Town puzzle map
"puzzleMap" :
{
// Prefix for image names, e.g. "PUZCAS" for name "PUZCAS12.png"
"prefix" : "",
// List of map pieces. First image will have name < prefix > 00, second - < prefix > 01 and so on
"pieces" :
[
{
// Position of image on screen
"x" : 0
"y" : 0
//indicates order in which this image will be opened
"index" : 0
},
...
]
]
}
```
## Town node
2023-09-12 14:52:45 +02:00
```jsonc
2023-08-12 11:39:44 +02:00
{
2023-09-12 14:52:45 +02:00
// Field that describes behavior of map object part of town. Town-specific part of object format
2023-08-12 11:39:44 +02:00
"mapObject" :
{
// Optional, controls what template will be used to display this object.
// Whenever player builds a building in town game will test all applicable templates using
// tests with matching name and on success - set such template as active.
// There are 3 predefined filters: "village", "fort" and "capitol" that emulate H3 behavior
"filter" : {
"capitol" : [ "anyOf", [ "capitol" ], [ "castle" ] ]
},
// List of templates that represent this object. For towns only animation is required
// See object template description for other fields that can be used.
"templates" : {
"village" : { "animation" : "" },
"castle" : { "animation" : "" },
"capitol" : { "animation" : "" }
}
},
//icons, small and big. Built versions indicate constructed during this turn building.
"icons" :
{
"village" : {
"normal" : {
"small" : "modname/icons/hall-small.bmp",
"large" : "modname/icons/hall-big.bmp"
},
"built" : {
"small" : "modname/icons/hall-builded-small.bmp",
"large" : "modname/icons/hall-builded-big.bmp"
}
},
"fort" : {
"normal" : {
"small" : "modname/icons/fort-small.bmp",
"large" : "modname/icons/fort-big.bmp"
},
"built" : {
"small" : "modname/icons/fort-builded-small.bmp",
"large" : "modname/icons/fort-builded-big.bmp"
}
}
},
// Path to town music theme, e.g. "music/castleTheme"
"musicTheme" : "",
// List of structures which represents visible graphical objects on town screen.
// See detailed description below
"structures" :
{
"building1" : { ... },
...
"building9" : { ... }
},
// List of names for towns on adventure map e.g. "Dunwall", "Whitestone"
// Does not have any size limitations
"names" : [ "", ""],
// Background scenery for town screen, size must be 800x374
"townBackground": "",
// Small scenery for window in mage guild screen
"guildWindow": "",
2023-09-12 14:52:45 +02:00
// Background image for window in mage guild screen
2023-08-12 11:39:44 +02:00
"guildBackground" : "",
2023-09-12 14:52:45 +02:00
// Video for tavern window
2023-08-12 11:39:44 +02:00
"tavernVideo" : "",
2023-09-12 14:52:45 +02:00
// Path to building icons for town hall
2023-08-12 11:39:44 +02:00
"buildingsIcons": "HALLCSTL.DEF",
// Background image for town hall window
"hallBackground": "",
// List of buildings available in each slot of town hall window
2023-09-12 14:52:45 +02:00
// Note that size of gui is limited to 5 rows and 4 columns
2023-08-12 11:39:44 +02:00
"hallSlots":
[
[ [ "buildingID1" ], [ "buildingID2", "buildingID3" ] ],
...
],
// List of creatures available on each tier. Number of creatures on each tier
// is not hardcoded but it should match with number of dwelling for each level.
// For example structure below would need buildings with these id's:
// first tier: 30 and 37, second tier: 31, third tier: 32, 39, 46
"creatures" :
[
["centaur", "captainCentaur"],
["dwarf"],
["elf", "grandElf", "sharpshooter"],
...
],
// Buildings, objects in town that affect mechanics. See detailed description below
"buildings" :
{
"building1" : { ... },
...
"building9" : { ... }
},
// Description of siege screen, see below
"siege" : { ... },
// Chance for a hero class to appear in this town, creates pair with same field in class format
// Used for situations where chance was not set in "tavern" field, chance will be determined as:
// square root( town tavern chance * hero class tavern chance )
"defaultTavern" : 5,
// Chance of specific hero class to appear in this town
// Mirrored version of field "tavern" from hero class format
"tavern" :
{
"knight" : 5,
"druid" : 6
},
// Chance of specific spell to appear in mages guild of this town
// If spell is missing or set to 0 it will not appear unless set as "always present" in editor
// Spells from unavailable levels are not required to be in this list
"guildSpells" :
{
"magicArrow" : 30,
"bless" : 10
},
// Which tiers in this town have creature hordes. Set to -1 to disable horde(s)
"horde" : [ 2, -1 ],
2023-09-12 14:52:45 +02:00
// Resource given by starting bonus. If not set silo will produce wood + ore
2023-08-12 11:39:44 +02:00
"primaryResource" : "gems",
// maximum level of mage guild
"mageGuild" : 4,
// war machine produced in town
"warMachine" : "ballista"
2023-09-12 14:52:45 +02:00
// Identifier of spell that will create effects for town moat during siege
"moatAbility" : "castleMoat"
2023-08-12 11:39:44 +02:00
}
```
## Siege node
2023-09-12 14:52:45 +02:00
```jsonc
2023-08-12 11:39:44 +02:00
// Describes town siege screen
// Comments in the end of each graphic position indicate specify required suffix for image
// Note: one not included image is battlefield background with suffix "BACK"
{
// shooter creature name
"shooter" : "archer",
2023-09-12 14:52:45 +02:00
// Large icon of towers, for use in battle queue
2023-08-12 11:39:44 +02:00
"towerIconLarge" : "",
2023-09-12 14:52:45 +02:00
// (Small icon of towers, for use in battle queue
2023-08-12 11:39:44 +02:00
"towerIconSmall" : "",
2023-09-12 14:52:45 +02:00
// Prefix for all siege images. Final name will be composed as < prefix > < suffix >
2023-08-12 11:39:44 +02:00
"imagePrefix" : "SGCS",
// Descriptions for towers. Each tower consist from 3 parts:
// tower itself - two images with untouched and destroyed towers
// battlement or creature cover - section displayed on top of creature
// creature using type from "shooter" field above
"towers":
{
// Top tower description
"top" :
{
"tower" : { "x": 0, "y": 0}, // "TW21" ... "TW22"
"battlement" : { "x": 0, "y": 0}, // "TW2C"
"creature" : { "x": 0, "y": 0}
},
// Central keep description
"keep" :
{
"tower" : { "x": 0, "y": 0}, // "MAN1" ... "MAN2"
"battlement" : { "x": 0, "y": 0}, // "MANC"
"creature" : { "x": 0, "y": 0}
},
// Bottom tower description
"bottom" :
{
"tower" : { "x": 0, "y": 0}, // "TW11" ... "TW12"
"battlement" : { "x": 0, "y": 0}, // "TW1C"
"creature" : { "x": 0, "y": 0}
},
},
2023-09-12 14:52:45 +02:00
// Two parts of gate: gate itself and arch above it
2023-08-12 11:39:44 +02:00
"gate" :
{
"gate" : { "x": 0, "y": 0}, // "DRW1" ... "DRW3" and "DRWC" (rope)
"arch" : { "x": 0, "y": 0} // "ARCH"
},
// Destructible walls. In this example they are ordered from top to bottom
// Each of them consist from 3 files: undestroyed, damaged, destroyed
"walls" :
{
"upper" : { "x": 0, "y": 0}, // "WA61" ... "WA63"
"upperMid" : { "x": 0, "y": 0}, // "WA41" ... "WA43"
"bottomMid" : { "x": 0, "y": 0}, // "WA31" ... "WA33"
"bottom" : { "x": 0, "y": 0} // "WA11" ... "WA13"
},
2023-09-12 14:52:45 +02:00
// Two pieces for moat: moat itself and moat bank
"moat" :
{
"bank" : { "x" : 0, "y" : 0 }, // "MOAT"
"moat" : { "x" : 0, "y" : 0 } // "MLIP"
},
2023-08-12 11:39:44 +02:00
// Static non-destructible walls. All of them have only one piece
"static" :
{
// Section between two bottom destructible walls
"bottom" : { "x": 0, "y": 0}, // "WA2"
// Section between two top destructible walls
"top" : { "x": 0, "y": 0}, // "WA5"
// Topmost wall located behind hero
"background" : { "x": 0, "y": 0} // "TPWL"
}
}
```
## Building node
2023-09-12 14:52:45 +02:00
```jsonc
2023-08-12 11:39:44 +02:00
{
2023-09-12 14:52:45 +02:00
// Numeric identifier of this building
2023-08-12 11:39:44 +02:00
"id" : 0,
2023-09-12 14:52:45 +02:00
// Localizable name of this building
2023-08-12 11:39:44 +02:00
"name" : "",
2023-09-12 14:52:45 +02:00
// Localizable decsription of this building
2023-08-12 11:39:44 +02:00
"description" : "",
2023-09-12 14:52:45 +02:00
// Optional, indicates that this building upgrades another base building
"upgrades" : "baseBuilding",
// List of town buildings that must be built before this one. See below for full format
"requires" : [ "allOf", [ "mageGuild1" ], [ "tavern" ] ],
// Resources needed to build building
"cost" : { ... },
// TODO: Document me: Subtype for some special buildings
"type" : "",
// TODO: Document me: Height for lookout towers and some grails
"height" : "average"
// Resources produced each day by this building
"produce" : { ... },
2023-08-12 11:39:44 +02:00
//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
2023-09-12 14:52:45 +02:00
"mode" : "auto",
// Buildings which bonuses should be overridden with bonuses of the current building
"overrides" : [ "anotherBuilding ]
// Bonuses, provided by this special building on build using bonus system
"bonuses" : BONUS_FORMAT
// Bonuses, provided by this special building on hero visit and applied to the visiting hero
"onVisitBonuses" : BONUS_FORMAT
2023-08-12 11:39:44 +02:00
}
```
Building requirements can be described using logical expressions:
2023-09-12 14:52:45 +02:00
```jsonc
2023-08-12 11:39:44 +02:00
"requires" :
[
"allOf", // Normal H3 "build all" mode
[ "mageGuild1" ],
[
"noneOf", // available only when none of these building are built
[ "dwelling5A" ],
[ "dwelling5AUpgrade" ]
],
[
"anyOf", // any non-zero number of these buildings must be built
[ "tavern" ],
[ "blacksmith" ]
]
]
```
## Structure node
2023-09-12 14:52:45 +02:00
```jsonc
2023-08-12 11:39:44 +02:00
{
2023-09-12 14:52:45 +02:00
// Main animation file for this building
"animation" : "",
// Horizontal position on town screen
2023-08-12 11:39:44 +02:00
"x" : 0,
2023-09-12 14:52:45 +02:00
// Vertical position on town screen
2023-08-12 11:39:44 +02:00
"y" : 0,
2023-09-12 14:52:45 +02:00
// used for blit order. Higher value places structure close to screen and drawn on top of buildings with lower values
"z" : 0,
// Path to image with golden border around building, displayed when building is selected
"border" : "",
// Path to image with area that indicate when building is selected
"area" : "",
//TODO: describe me
"builds": "",
// If upgrade, this building will replace parent animation but will not alter its behaviour
"hidden" : false
2023-08-12 11:39:44 +02:00
}
```