From dd375b682dd8a8dada29ab2de08684406e713ef6 Mon Sep 17 00:00:00 2001 From: Ivan Savenko Date: Thu, 15 Aug 2024 18:16:33 +0000 Subject: [PATCH] Updated documentation --- .../modders/Entities_Format/Faction_Format.md | 97 +-------- .../Entities_Format/Town_Building_Format.md | 194 ++++++++++++++++++ 2 files changed, 196 insertions(+), 95 deletions(-) create mode 100644 docs/modders/Entities_Format/Town_Building_Format.md diff --git a/docs/modders/Entities_Format/Faction_Format.md b/docs/modders/Entities_Format/Faction_Format.md index a7c9935be..e68fb72c4 100644 --- a/docs/modders/Entities_Format/Faction_Format.md +++ b/docs/modders/Entities_Format/Faction_Format.md @@ -341,100 +341,7 @@ Each town requires a set of buildings (Around 30-45 buildings) ``` ## Building node - -```jsonc -{ - // 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" : { ... }, - - // 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" : { ... }, - - //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 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 -} -``` - -Building requirements can be described using logical expressions: - -```jsonc -"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" ] - ] -] -``` +See [Town Building Format](Town_Building_Format.md) ## Structure node - -```jsonc -{ - // 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 -} -``` \ No newline at end of file +See [Town Building Format](Town_Building_Format.md) \ No newline at end of file diff --git a/docs/modders/Entities_Format/Town_Building_Format.md b/docs/modders/Entities_Format/Town_Building_Format.md new file mode 100644 index 000000000..7ee42ea39 --- /dev/null +++ b/docs/modders/Entities_Format/Town_Building_Format.md @@ -0,0 +1,194 @@ +# 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) + +## Town Building node + +```jsonc +{ + // 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 + }, + + // 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 + }, + + //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 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 +} +``` + +Building requirements can be described using logical expressions: + +```jsonc +"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 + +Following Heroes III buildings can be used as unique buildings for a town. Their functionality should be identical to a corresponding H3 building: +- `mysticPond` +- `artifactMerchant` +- `freelancersGuild` +- `magicUniversity` +- `castleGate` +- `creatureTransformer` +- `portalOfSummoning` +- `ballistaYard` +- `stables` +- `manaVortex` +- `lookoutTower` +- `library` +- `brotherhoodOfSword` +- `fountainOfFortune` +- `escapeTunnel` +- `lighthouse` +- `treasury` +- `spellPowerGarrisonBonus` +- `attackGarrisonBonus` +- `defenseGarrisonBonus` + +Following HotA buildings can be used as unique building for a town. Functionality should match corresponding HotA building: +- `thievesGuild` +- `bank` + +In addition to above, it is possible to use same format as [Rewardable](../Map_Objects/Rewardable.md) map objects for town buildings. In order to do that, town building type must be set to `configurable` and configuration of a rewardable object must be placed into `configuration` node + +Example 1 - Order of Fire from Inferno: +```jsonc +"special4": { // + "type" : "configurable", + "requires" : [ "mageGuild1" ], + "configuration" : { + "visitMode" : "hero", + "rewards" : [ + { + "message" : "@core.genrltxt.582", // NOTE: this forces vcmi to load string from H3 text file. In order to define own string simply write your own message without '@' symbol + "primary" : { "spellpower" : 1 } + } + ] + } +} +``` + +Example 2 - Mana Vortex from Dungeon +```jsonc +"special2": { + "type" : "configurable", + "requires" : [ "mageGuild1" ], + "configuration" : { + "resetParameters" : { + "period" : 7, + "visitors" : true + }, + "visitMode" : "once", + "rewards" : [ + { + "limiter" : { + "noneOf" : [ { "manaPercentage" : 200 } ] + }, + "message" : "@core.genrltxt.579", + "manaPercentage" : 200 + } + ] + } +} +``` + +### Town Structure node + +```jsonc +{ + // 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 +} +``` \ No newline at end of file