Skip to content

Town Building Format

Required data

Each building requires following assets:

  • Town animation file (1 animation file)
  • Selection highlight (1 image)
  • Selection area (1 image)
  • Town hall icon (1 image)

Examples

These are just a couple of examples of what can be done in VCMI. See vcmi configuration files to check how buildings from Heroes III are implemented or other mods for more examples

Order of Fire from Inferno
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
"special4": {
    "requires" : [ "mageGuild1" ],
    "name" : "Order of Fire",
    "description" : "Increases spellpower of visiting hero",
    "cost" : {
        "mercury" : 5,
        "gold" : 1000
    },
    "configuration" : {
        "visitMode" : "hero",
        "rewards" : [
            {
                // NOTE: this forces vcmi to load string from H3 text file. In order to define own string simply write your own message without '@' symbol
                "message" : "@core.genrltxt.582", 
                "primary" : { "spellpower" : 1 }
            }
        ]
    }
}
Mana Vortex from Dungeon
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
"special2": {
    "requires" : [ "mageGuild1" ],
    "name" : "Mana Vortex",
    "description" : "Doubles mana points of the first visiting hero each week",
    "cost" : {
        "gold" : 5000
    },
    "configuration" : {
        "resetParameters" : {
            "period" : 7,
            "visitors" : true
        },
        "visitMode" : "once",
        "rewards" : [
            {
                "limiter" : {
                    "noneOf" : [ { "manaPercentage" : 200 } ]
                },
                "message" : "As you near the mana vortex your body is filled with new energy. You have doubled your normal spell points.",
                "manaPercentage" : 200
            }
        ]
    }
}

Resource Silo with custom production

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
"resourceSilo": {
    "name" : "Wood Resource Silo",
    "description" : "Produces 2 wood every day",
    "cost" : {
        "wood" : 10,
        "gold" : 5000
    },
    "produce" : {
        "wood": 2
    }
},

Brotherhood of Sword - bonuses in siege

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
"special3": {
    // replaces +1 Morale bonus from Tavern
    "upgradeReplacesBonuses" : true, 
    // Gives +2 bonus to morale to town (effective only during siege)
    "bonuses": [
        {
            "type": "MORALE",
            "val": 2
        }
    ],
    "upgrades" : "tavern"
},

Lighthouse - bonus to all heroes under player control

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
"special1":       { 
    "bonuses": [
        {
            "propagator": "PLAYER_PROPAGATOR", // bonus affects everything under player control
            "type": "MOVEMENT",
            "subtype": "heroMovementSea",
            "val": 500 // +500 movement points
        }
    ],
    "requires" : [ "shipyard" ]
},

Town Building node

 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
{
    // Numeric identifier of this building
    "id" : 0,

    // Localizable name of this building
    "name" : "",

    // Localizable decsription of this building
    "description" : "",

    // 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" : { 
        "wood" : 20,
        "ore" : 20,
        "gold" : 10000
    }, 

    // Artifact ID of a war machine produced in this town building, if any
    "warMachine" : "ballista",

    // Allows to define additional functionality of this building, usually using logic of one of original H3 town building
    // Generally only needs to be specified for "special" buildings
    // See 'List of unique town buildings' section below for detailed description of this field
    "type" : "",

    // If set, building will have Lookout Tower logic - extend sight radius of a town.
    // Possible values: 
    // low - increases town sight radius by 5 tiles
    // average - sight radius extended by 15 tiles
    // high - sight radius extended by 20 tiles
    // skyship - entire map will be revealed
    // If not set, building will not affect sight radius of a town
    "height" : "average"

    // Resources produced each day by this building
    "produce" : { 
        "sulfur" : 1,
        "gold" : 2000
    },

    // Optional, allows this building to add fortifications during siege
    "fortifications" : {
        // Maximum health of destructible walls. Walls are only present if their health is above zero".
        // Presence of walls is required for all other fortification types
        "wallsHealth" : 3,

        // If set to true, moat will be placed in front of the walls. Requires walls presence.
        "hasMoat" : true

        // Maximum health of central tower or 0 if not present. Requires walls presence.
        "citadelHealth" : 2,
        // Maximum health of upper tower or 0 if not present. Requires walls presence.
        "upperTowerHealth" : 2,
        // Maximum health of lower tower or 0 if not present. Requires walls presence.
        "lowerTowerHealth" : 2,

        // Creature ID of shooter located in central keep (citadel). Used only if citadel is present.
        "citadelShooter" : "archer",
        // Creature ID of shooter located in upper tower. Used only if upper tower is present.
        "upperTowerShooter" : "archer",
        // Creature ID of shooter located in lower tower. Used only if lower tower is present.
        "lowerTowerShooter" : "archer",
    },

    //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 requires grail to be built
    "mode" : "auto",

    // Buildings which bonuses should be overridden with bonuses of the current building
    "overrides" : [ "anotherBuilding ]

    // Bonuses provided by this special building if this building or any of its upgrades are constructed in town
    "bonuses" : [ BONUS_FORMAT ]

    // If set to true, this building will not automatically activate on new day or on entering town and needs to be activated manually on click
    // Note that such building can only be activated by visiting hero, and not by garrisoned hero.
    "manualHeroVisit" : false,

    // Bonuses provided by this special building if this building or any of its upgrades are constructed in town
    "bonuses" : [ BONUS_FORMAT ]


    // If the building is a market, it requires market mode.
    "marketModes" : [ "resource-resource", "resource-player" ],
}

Building requirements can be described using logical expressions:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
"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" ]
    ]
]

List of unique town buildings

Buildings from Heroes III

Following Heroes III buildings can be used as unique buildings for a town. Their functionality should be identical to a corresponding H3 building. H3 buildings that are not present in this list contain no hardcoded functionality. See vcmi json configuration to see how such buildings can be implemented in a mod.

  • mysticPond
  • artifactMerchant
  • freelancersGuild
  • magicUniversity
  • castleGate
  • creatureTransformer
  • portalOfSummoning
  • library
  • escapeTunnel
  • treasury

Buildings from other Heroes III mods

Following HotA buildings can be used as unique building for a town. Functionality should match corresponding HotA building:

  • bank

Custom buildings

In addition to above, it is possible to use same format as Rewardable map objects for town buildings. In order to do that, configuration of a rewardable object must be placed into configuration json node in building config.

Town Structure node

 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
{
    // Main animation file for this building
    "animation" : "", 

    // Horizontal position on town screen
    "x" : 0,

    // Vertical  position on town screen
    "y" : 0,

    // 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 
}

Markets in towns

Market buildings require list of available modes

Marketplace
1
    "marketplace":    { "marketModes" : ["resource-resource", "resource-player"] },
Artifact merchant
1
    "special1":       { "type" : "artifactMerchant", "requires" : [ "marketplace" ], "marketModes" : ["resource-artifact", "artifact-resource"] },