games/vcmi
1
0
Fork 0
mirror of https://github.com/vcmi/vcmi.git synced 2025-11-23 22:37:55 +02:00
Code Issues Releases Activity

Modders docs update iteration

Browse Source
This commit is contained in:
Ivan Savenko
2023-09-01 12:11:35 +03:00
parent 06f9513b32
commit 3dcd4c7a6f
35 changed files with 325 additions and 287 deletions
Download Patch File Download Diff File Expand all files Collapse all files

63
docs/modders/Entities_Format/Artifact_Format.md Normal file
View File

@@ -0,0 +1,63 @@
Artifact bonuses use [Bonus Format](../Bonus_Format.md)
TODO:
- Artifacts growing with Commander level
## Required data
In order to make functional artifact you also need:
- Icon for hero inventory (1 image)
- Icon for popup windows (1 image, optional)
- Animation for adventure map (1 animation)
## Format
``` javascript
{
//what kind of bearer can use this artifact
"type": ["HERO", "CREATURE", "COMMANDER"]
//TREASURE, MINOR, MAJOR, RELIC, SPECIAL
"class": "TREASURE",
//SHOULDERS, NECK, RIGHT_HAND, LEFT_HAND, TORSO, RIGHT_RING, LEFT_RING, FEET, MISC1, MISC2, MISC3, MISC4,
//MACH1, MACH2, MACH3, MACH4, SPELLBOOK, MISC5
//also possible MISC, RING
"slot": "HEAD",
//based on ARTRAITS.txt
"value": 12000,
"text":
{
"name": "Big Sword",
"description": "Big sword gived +10 attack to hero",
"event": "On your travel, you stumble upon big sword. You dust it off and stick in your backpack"
},
"graphics":
{
"image": "BigSword.png",
"large": "BigSword_large.png",
//def file for adventure map
"map": "BigSword.def"
},
"bonuses":
{
Bonus_1,
Bonus_2
},
//optional, for combined artifacts only
"components":
[
"artifact1",
"artifact2",
"artifact3"
],
//if set with artifact works like war machine
"warMachine" : "some.creature"
}
```

1
docs/modders/Entities_Format/Battle_Obstacle_Format.md Normal file
View File

@@ -0,0 +1 @@
TODO

1
docs/modders/Entities_Format/Battlefield_Format.md Normal file
View File

@@ -0,0 +1 @@
TODO

193
docs/modders/Entities_Format/Creature_Format.md Normal file
View File

@@ -0,0 +1,193 @@
## Required data
In order to make functional creature you also need:
### Animation
- Battle animation (1 def file)
- Set of rendered projectiles (1 def files, shooters only)
- Adventure map animation (1 def file)
### Images
- Small portrait for hero exchange window (1 image)
- Large portrait for hero window (1 image)
### Sounds
- Set of sounds (up to 8 sounds)
## Format
``` javascript
// camelCase unique creature identifier
"creatureName" :
{
// translatable names
"name" :
{
"singular" : "Creature",
"plural" : "Creatures"
},
"level" : 0,
// if set to true creature will not appear in-game randomly (e.g. as neutral creature)
"special" : true,
// config name of faction. Examples: castle, rampart
"faction" : "",
// cost to recruit, zero values can be omitted.
"cost" :
{
"wood" : 0,
"mercury" : 0,
"ore" : 0,
"sulfur" : 0,
"crystal" : 0,
"gems" : 0,
"gold" : 0
},
// "value" of creature, used to determine for example army strength
"fightValue" : 0,
// "ai value" - how valuable this creature should be for AI
"aiValue" : 0,
// normal growth in town or external dwellings
"growth" : 0,
// growth bonus from horde building
// TODO: reconsider need of this field after configurable buildings support
"hordeGrowth" : 0,
// Creature stats in battle
"attack" : 0,
"defense" : 0,
"hitPoints" : 0,
"shots" : 0,
"speed" : 0,
"damage" :
{
"min" : 0,
"max" : 0
},
// spellpoints this creature has, how many times creature may cast its spells
"spellPoints" : 0,
// initial size of creature army on adventure map
"advMapAmount" :
{
"min" : 0,
"max" : 0
},
// Creature to which this creature can be upgraded
// Note that only one upgrade can be available from UI
"upgrades" :
[
"anotherCreature"
],
// Creature is 2-tiles in size on the battlefield
"doubleWide" : false,
// All creature abilities, using bonus format
"abilities" :
[
"someName1" : Bonus Format,
"someName2" : Bonus Format
],
"hasDoubleWeek": true,
"graphics" :
{
// name of file with creature battle animation
"animation" : "",
// adventure map animation def
"map" : "",
// path to small icon for tooltips & hero exchange window
"iconSmall" : "",
// path to large icon, used on town screen and in hero screen
"iconLarge" : "",
// animation parameters
// how often creature should play idle animation
"timeBetweenFidgets" : 1.00,
// unused H3 property
"troopCountLocationOffset" : 0,
"animationTime" :
{
// movement animation time.
"walk" : 1.00,
// idle animation time. For H3 creatures this value is always 10
"idle" : 10.00,
// ranged attack animation time. Applicable to shooting and casting animation
// NOTE: does NOT affects melee attacks
// This is H3 behaviour, for proper synchronization of attack/defense animations
"attack" : 1.00,
// How far flying creature should move during one "round" of movement animation
// This is multiplier to base value (200 pixels)
"flight" : 1.00
},
"missile" :
{
// name of file for missile
"animation" : "",
// (VCMI 1.1 or later only) indicates that creature uses ray animation for ranged attacks instead of missile image (e.g. Evil Eye)
"ray" :
[
{ // definition of first (top-most) line in the ray
"start" : [ 160, 192, 0, 255 ], // color (RGBA components) of ray at starting point
"end" : [ 160, 192, 0, 64 ] // color (RGBA components) of ray at finishing point
},
{}, // definition of second from top line in the ray, identical format
... // definitions of remaining lines, till desired width of the ray
],
// Frame at which shooter shoots his projectile (e.g. releases arrow)
"attackClimaxFrame" : 0,
// offsets between position of shooter and position where projectile should appear
"offset" :
{
"upperX" : 0,
"upperY" : 0,
"middleX" : 0,
"middleY" : 0,
"lowerX" : 0,
"lowerY" : 0
},
// angles from which frames in .def file were rendered, -90...90 range
// Example below will work for file that contains following frames:
// 1) facing top, 2) facing top-right, 3)facing right,
// 4) facing bottom-right 5) facing bottom.
"frameAngles" : [ -90, -45, 0, 45, 90]
}
},
// names of sound files
"sound" :
{
// Creature attack enemy in melee (counter-)attack
"attack": "",
// Creature in "defend mode" is attacked
"defend": "",
// Creature killed
"killed": "",
// Plays in loop during creature movement
"move": "",
// Shooters only, creature shoots
"shoot" : "",
// Creature not in "defend mode" is under attack
"wince": "",
// Creature start/end movement or teleports
"startMoving" : "",
"endMoving" : ""
}
}
```

388
docs/modders/Entities_Format/Faction_Format.md Normal file
View File

@@ -0,0 +1,388 @@
## 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)
``` javascript
// Unique faction identifier. Should be unique.
"myTown" :
{
// Main part of town description, see below
// Optional but it should be present for playable faction
"town" : { ... },
// Native terrain for this town. See config/terrains.json for identifiers
"nativeTerrain" : "grass",
// Localizable town name, e.g. "Rampart"
"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" : ""
}
// 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
``` javascript
{
// DEPRECATED, see "mapObject" field below | Path to images of object on adventure map
"adventureMap" :
{
"village": "", // village without built fort
"castle" : "", // town with built fort
"capitol": "" // town with capitol (usually have some additional flags)
},
// field that describes behavior of map object part of town. Town-specific part of object format
"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": "",
// Background image for window in mage guild screen - since 0.95b
"guildBackground" : "",
// Video for tavern window - since 0.95b
"tavernVideo" : "",
// Building icons for town hall
"buildingsIcons": "HALLCSTL.DEF",
// Background image for town hall window
"hallBackground": "",
// List of buildings available in each slot of town hall window
// As in most cases there is no hard limit on number of columns, rows
// or items in any of them, but size of gui is limited to 5 rows and 4 columns
"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
// TODO: Mirrored version of field "guildSpells" from spell format
"guildSpells" :
{
"magicArrow" : 30,
"bless" : 10
},
// TODO: Entries below should be replaced with autodetection
// Which tiers in this town have creature hordes. Set to -1 to disable horde(s)
"horde" : [ 2, -1 ],
// Resource given by starting bonus, if not set silo will produce wood + ore
"primaryResource" : "gems",
// maximum level of mage guild
"mageGuild" : 4,
// war machine produced in town
"warMachine" : "ballista"
}
```
## Siege node
``` javascript
// 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",
// (VCMI 1.1 or later) Large icon of towers, for use in battle queue
"towerIconLarge" : "",
// (VCMI 1.1 or later) Small icon of towers, for use in battle queue
"towerIconSmall" : "",
// prefix for all siege images. Final name will be composed as <prefix><suffix>
"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}
},
},
//Two parts of gate: gate itself and arch above it
"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"
},
// Two pieces for moat: moat itself and shore
"moat" : { "x": 0, "y": 0}, // moat: "MOAT", shore: "MLIP"
// 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
``` javascript
{
"id" : 0,
"name" : "",
"description" : "",
"upgrades" : "baseBuilding", // optional, which building can be upgraded by this one
"requires" : [ "allOf", [ "mageGuild1" ], [ "tavern" ] ], // building requirements, H3-style. See below for full format.
"cost" : { ... }, //resources needed to buy building
"produce" : { ... }, //resources produced each day by building - since 0.95b
//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"
}
```
Building requirements can be described using logical expressions:
``` javascript
"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
``` javascript
{
"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
}
```

109
docs/modders/Entities_Format/Hero_Class_Format.md Normal file
View File

@@ -0,0 +1,109 @@
## Required data
In order to make functional hero class you also need:
- Adventure animation (1 def file)
- Battle animation, male and female version (2 def files)
## Format
``` javascript
// Unique identifier of hero class, camelCase
"myClassName" :
{
// Various hero animations
"animation"
{
"battle" :
{
// Battle animation for female heroes
"female" : "myMod/battle/heroFemale",
// Battle animation for male heroes, can be same as female
"male" : "myMod/battle/heroMale"
}
},
// Description of map object representing this hero class. See map template format for details
"mapObject" : {
// Optional, hero ID-base filter, using same rules as building requirements
"filters" : {
"mutare" : [ "anyOf", [ "mutare" ], [ "mutareDrake" ]]
},
// List of templates used for this object, normally - only one is needed
"templates" : {
"normal" : { "animation" : "AH00_.def" }
}
},
// Translatable name of hero class
"name" : "My hero class",
// Identifier of faction this class belongs to
"faction" : "myFaction",
// Identifier of creature that should be used as commander for this hero class
// Can be a regular creature that has shooting animation
"commander" : "mage",
// Affinity of this class, might or magic
"affinity" : "might",
// Initial primary skills of heroes
"primarySkills" :
{
"attack" : 2,
"defence" : 0,
"spellpower" : 1,
"knowledge" : 2
},
// Chance to get specific primary skill on level-up
// This set specifies chances for levels 2-9
"lowLevelChance" :
{
"attack" : 15,
"defence" : 10,
"spellpower" : 50,
"knowledge" : 25
},
// Chance to get specific primary skill on level-up
// This set specifies chances for levels starting from 10
"highLevelChance" :
{
"attack" : 25,
"defence" : 5,
"spellpower" : 45,
"knowledge" : 25
},
// Chance to get specific secondary skill on level-up
// Skills not listed here will be considered as unavailable, including universities
"secondarySkills" :
{
"pathfinding" : 3.
"archery" : 6.
...
"resistance" : 5,
"firstAid" : 4
},
// Chance for a this hero class to appear in a town, creates pair with same field in town 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 for this hero to appear in tavern of this factions.
// Reversed version of field "tavern" from town format
// If faction-class pair is not listed in any of them
// chance set to 0 and the class won't appear in tavern of this town
"tavern" :
{
"castle" : 4,
...
"conflux" : 6
}
}
```

126
docs/modders/Entities_Format/Hero_Type_Format.md Normal file
View File

@@ -0,0 +1,126 @@
## Required data
In order to make functional hero you also need:
- Portraits, small and big versions (2 images)
- Specialty icons, small and big versions (2 images)
## Format
``` javascript
"myHeroName" :
{
// Identifier of class. Usually camelCase version of human-readable name
"class" : "wizard",
// List of starting spells, if available. Will also grant spellbook
"spellbook" :
[
"magicArrow"
],
// Set to true if the hero is female by default (can be changed in map editor)
"female" : true,
// If set to true hero will be unavailable on start and won't appear in taverns (campaign heroes)
"special" : true,
// All translatable texts related to hero
"texts" :
{
"name" : "My Hero",
"biography" : "This is a long story...",
"specialty" :
{
// Description visible when hovering over specialty icon
"description" : "Spell mastery: Magic Arrow",
// Tooltip visible on clicking icon. Can use {} symbols to change title to yellow
// as well as escape sequences "\n" to add line breaks
"tooltip" : "{Magic Arrow}\n\nCasts powerfull magic arrows",
// Name of your specialty
"name" : "Magic Arrow"
}
},
// Graphics used by hero
"images" :
{
// Small 32px speciality icon
"specialtySmall" : "myMod/myHero/specSmall.png",
// Large 44px speciality icon
"specialtyLarge" : "myMod/myHero/specLarge.png",
// Large 58x64px portrait
"large" : "myMod/myHero/large.png",
// Small 48x32px portrait
"small" : "myMod/myHero/small.png"
// Class-independent animation in battle
"small" : "myMod/myHero/battle.def"
},
// Initial hero army when recruited in tavern
// Must have 1-3 elements
"army" :
[
// First always available stack
{
// Identifier of creature in this stack
"creature" : "mage",
// Minimal and maximum size of stack. Size will be
// determined randomly at the start of the game
"max" : 2,
"min" : 1
},
// Second stack has 90 % chance to appear
{
"creature" : "archmage",
"max" : 1,
"min" : 1
},
// Third stack with just 20 % chance to appear
{
"creature" : "mage",
"max" : 2,
"min" : 1
}
],
// List of skills received by hero
// Not limited by size - you can add as many skills as you wish
"skills" :
[
{
// Skill level, basic, advanced or expert
"level" : "basic",
// Skill identifier, camelCase version of name
"skill" : "wisdom"
},
{
"level" : "basic",
"skill" : "waterMagic"
}
],
// Description of specialty mechanics using bonuses (with updaters)
"specialty" : {
// to be merged with all bonuses, use for specialties with multiple similar bonuses (optional)
"base" : {common bonus properties},
"bonuses" : {
// use updaters for bonuses that grow with level
"someBonus" : {Bonus Format},
"anotherOne" : {Bonus Format}
},
// adds creature specialty following the HMM3 default formula
"creature" : "griffin"
}
}
```

153
docs/modders/Entities_Format/Map_Object_Format.md Normal file
View File

@@ -0,0 +1,153 @@
## Description
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
To create visitable object which grants all kinds of rewards (gold,
experience, Bonuses etc...), see
[Rewardable](Map_Objects/Rewardable.md)
page.
## Object group format
``` javascript
{
"myCoolObjectGroup":
{
//numeric ID, mandatory for h3/wog objects, shall be unique if not defined
//used only for H3 objects, mods can not be used by mods
"index":123,
//Mandatory for new objects,
// human readable name, localized
//default for original objects from "OBJNAMES.TXT"
"name": "My cool object",
//defines C++/script class name that handles behavior of this object
"handler" : "mine",
// default values, will be merged with each type during loading
"base" : { <object type format> },
"types" : {
<list of object types, see below>
}
}
}
```
## Object type format
``` javascript
{
"myCoolObject":
{
//numeric sub ID, mandatory for h3/wog objects, shall be unique if set
//used only for H3 objects, can not be used by mods
"index":123,
// parameters that will be passed over to class that controls behavior of the object
"producedResources" : "gold",
"producedValue" : 1000
// TODO: allow better selection of template for object, instead of just terrain
// field describes how object template will be selected if there are multiple possiblities
// exact behavior and format depends on object type
"filter" : { ... },
// Data for random map generator that describes how object should be placed.
// If this entry is missing object will not be placed by RMG
"rmg" : {
// How valuable this object is, 1k = worthless, 20k = relic level
"value" : 5000,
// Optional, how many of such objects can be placed on map
"mapLimit" : 25,
// Optional, how many of such objects can be placed in one zone
"zoneLimit" : 4,
// Rarity of object, 10 = rare, 100 = common
"rarity" : 50
}
// default values, will be merged with each template during loading
// mostly needed to avoid redefining whole template to change 1-2 fields
"base" : { <template format> },
"templates" : {
<templates description, see below>
}
}
}
```
## Object template format
``` javascript
{
"myCoolObjectTemplate" :
{
// resource ID of animation, relative to SPRITES directory (def file or json file)
"animation":"DEFNAME.def",
// resource ID of animation for mapeditor, relative to SPRITES directory (def file or json file)
//0.98c+
"editorAnimation":"DEFNAME.def",
// directions from which hero can visit this object.
// "+" means that object can be visited from that direction, or "-" othervice
// default not visitable
"visitableFrom" : [
"---",
"+++",
"+++"
],
// passability of the object
// 0=not visible, passable. Space symbol ' ' can be used as well
// V=visible, passable
// B=blocked, visible
// H=hidden - blocked, not visible tile
// A=activable, visible, passable depending on visitableFrom field
// T=trigger - visiting the tile will trigger the object, tile is not visible (e.g. event)
//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",
"0000HHAT"
],
// optional; default or if explicitly set to null: all terrains except rock
// allowed terrain types to place object too. Affects also RMG.
// Note that map editor will still allow to place object on other terrains
// allowed terrain types: "dirt", "sand", "grass", "snow", "swamp", "rough", "subterra", "lava", "water", "rock"
"allowedTerrains":["dirt", "sand"],
// TODO, default - empty
// 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 = 100
"zIndex": 0
}
}
```

90
docs/modders/Entities_Format/Random_Map_Template.md Normal file
View File

@@ -0,0 +1,90 @@
## Template format
``` javascript
/// Unique template name
"Triangle" :
{
//optional name - useful to have several template variations with same name (since 0.99)
"name" : "Custom template name",
"description" : "Brief description of template, recommended setting or rules".
/// Minimal and maximal size of the map. Possible formats:
/// Size code: s, m, l or xl for size with optional suffix "+u" for underground
/// Numeric size, e.g. 120x120x1 (width x height x depth). Note that right now depth can only be 0 or 1
"minSize" : "m",
"maxSize" : "xl+u",
/// Number of players that will be present on map (human or AI)
"players" : "2-4",
/// Number of AI-only players
"cpu" : "2",
///Optional parameter allowing to prohibit some water modes. All modes are allowed if parameter is not specified
"allowedWaterContent" : ["none", "normal", "islands"]
/// List of named zones, see below for format description
"zones" :
{
"zoneA" : { ... },
"zoneB" : { ... },
"zoneC" : { ... }
},
"connections" :
[
{ "a" : "zoneA", "b" : "zoneB", "guard" : 5000, "road" : "false" },
{ "a" : "zoneA", "b" : "zoneC", "guard" : 5000, "road" : "random" },
{ "a" : "zoneB", "b" : "zoneC", "type" : "wide" }
//"type" can be "guarded" (default), "wide", "fictive" or "repulsive"
//"wide" connections have no border, or guard. "fictive" and "repulsive" connections are virtual -
//they do not create actual path, but only attract or repulse zones, respectively
]
}
```
## Zone format
``` javascript
{
"type" : "playerStart", //"cpuStart" "treasure" "junction"
"size" : 2, //relative size of zone
"owner" : 1, //player owned this zone
"playerTowns" : {
"castles" : 1
//"towns" : 1
},
"neutralTowns" : {
//"castles" : 1
"towns" : 1
},
"townsAreSameType" : true,
"monsters" : "normal", //"weak" "strong", "none" - All treasures will be unguarded
"terrainTypes" : [ "sand" ], //possible terrain types. All terrains will be available if not specified
"bannedTerrains" : ["lava", "asphalt"] //optional
"matchTerrainToTown" : false, //if true, terrain for this zone will match native terrain of player faction
"minesLikeZone" : 1,
"treasureLikeZone" : 1
"terrainTypeLikeZone" : 3
"allowedMonsters" : ["inferno", "necropolis"] //factions of monsters allowed on this zone
"bannedMonsters" : ["fortress", "stronghold", "conflux"] //These monsers will never appear in the zone
"allowedTowns" : ["castle", "tower", "rampart"] //towns allowed on this terrain
"bannedTowns" : ["necropolis"] //towns will never spawn on this terrain
"mines" : {
"wood" : 1,
"ore" : 1,
},
"treasure" : [
{
"min" : 2100,
"max": 3000,
"density" : 5
}
...
]
}
```

1
docs/modders/Entities_Format/River_Format.md Normal file
View File

@@ -0,0 +1 @@
TODO

1
docs/modders/Entities_Format/Road_Format.md Normal file
View File

@@ -0,0 +1 @@
TODO

86
docs/modders/Entities_Format/Secondary_Skill_Format.md Normal file
View File

@@ -0,0 +1,86 @@
## Main format
``` javascript
{
"skillName":
{
//numeric id of skill required only for original skills, prohibited for new skills
"index": 0,
//Mandatory
"name": "Localizable name",
//optional base format, will be merged with basic/advanced/expert
"base": {Skill level base format},
//configuration for different skill levels
"basic": {Skill level format},
"advanced": {Skill level format},
"expert": {Skill level format}
}
}
```
## Skill level base format
Json object with data common for all levels can be put here. These
configuration parameters will be default for all levels. All mandatory
level fields become optional if they equal "base" configuration.
## Skill level format
``` javascript
{
//Optional, localizable description
//Use {xxx} for formatting
"description": "",
//Bonuses provided by skill at given level
//If different levels provide same bonus with different val, only the highest applies
"effects":
{
"firstEffect": {bonus format},
"secondEffect": {bonus format}
//...
}
}
```
## Example
The following modifies the tactics skill to grant an additional speed
boost at advanced and expert levels.
``` javascript
"core:tactics" : {
"base" : {
"effects" : {
"main" : {
"subtype" : "skill.tactics",
"type" : "SECONDARY_SKILL_PREMY",
"valueType" : "BASE_NUMBER"
},
"xtra" : {
"type" : "STACKS_SPEED",
"valueType" : "BASE_NUMBER"
}
}
},
"basic" : {
"effects" : {
"main" : { "val" : 3 },
"xtra" : { "val" : 0 }
}
},
"advanced" : {
"description" : "{Advanced Tactics}\n\nAllows you to rearrange troups within 5 hex rows, and increases their speed by 1.",
"effects" : {
"main" : { "val" : 5 },
"xtra" : { "val" : 1 }
}
},
"expert" : {
"description" : "{Expert Tactics}\n\nAllows you to rearrange troups within 7 hex rows, and increases their speed by 2.",
"effects" : {
"main" : { "val" : 7 },
"xtra" : { "val" : 2 }
}
}
}
```

381
docs/modders/Entities_Format/Spell_Format.md Normal file
View File

@@ -0,0 +1,381 @@
# Main format
``` javascript
{
"spellName":
{ //numeric id of spell required only for original spells, prohibited for new spells
"index": 0,
//Original Heroes 3 info
//Mandatory, spell type
"type": "adventure",//"adventure", "combat", "ability"
//Mandatory, spell target type
"targetType":"NO_TARGET",//"CREATURE","OBSTACLE"."LOCATION"
//Mandatory
"name": "Localizable name",
//Mandatory, flags structure of school names, Spell schools this spell belongs to
"school": {"air":true, "earth":true, "fire":true, "water":true},
//number, mandatory, Spell level, value in range 1-5
"level": 1,
//Mandatory, base power
"power": 10,
//Mandatory, default chance for this spell to appear in Mage Guilds
//Used only if chance for a faction is not set in gainChance field
"defaultGainChance": 0,
//Optional, chance for it to appear in Mage Guild of a specific faction
//NOTE: this field is linker with faction configuration
"gainChance":
{
"factionName": 3
},
//VCMI info
"animation":{<Animation format>},
//countering spells, flags structure of spell ids (spell. prefix is required)
"counters": {"spell.spellID1":true, ...}
//Mandatory,flags structure:
// indifferent, negative, positive - Positiveness of spell for target (required)
// damage - spell does damage (direct or indirect)
// offensive - direct damage (implicitly sets damage and negative)
// rising - rising spell (implicitly sets positive)
// summoning //todo:
// special - can be obtained only with bonus::SPELL
"flags" : {"flag1": true, "flag2": true},
//DEPRECATED | optional| no default | flags structure of bonus names,any one of these bonus grants immunity. Negatable by the Orb.
"immunity": {"BONUS_NAME":true, ...},
//DEPRECATED | optional| no default | flags structure of bonus names
//any one of these bonus grants immunity, cant be negated
"absoluteImmunity": {"BONUS_NAME": true, ...},
//DEPRECATED | optional| no default | flags structure of bonus names, presence of all bonuses required to be affected by. Negatable by the Orb.
"limit": {"BONUS_NAME": true, ...},
//DEPRECATED | optional| no default | flags structure of bonus names, presence of all bonuses required to be affected by. Cant be negated
"absoluteLimit": {"BONUS_NAME": true, ...},
//[WIP] optional | default no limit no immunity
//
"targetCondition" {
//at least one required to be affected
"anyOf" : {
//generic format
"mod:metaClassName.typeName":"absolute",//"normal", null or empty ignored - use for overrides
},
//all required to be affected (like [absolute]limit)
"allOf" : {
//bonus type format
"bonus.BONUS_TYPE":"absolute"//"normal" Short bonus type format
"modId:bonus.bonusTypeName":"absolute"//"normal" Future bonus format for configurable bonuses
},
//at least one grants immunity (like [absolute]immunity)
"noneOf": {
//some more examples
"core:creature.imp":"absolute", //[to be in initial version] this creature explicitly absolutely immune
"core:bonus.MIND_IMMUITY":"normal", // [to be in initial version] new format of existing mind spell immunity
"core:artifact.armorOfWonder":"absolute", //[possible future extension] this artifact on target itself (!) explicitly grant absolute immune
"core:luck":["absolute", 3], // [possible future extension] lack value of at least 3 grant absolute immunity from this horrible spell
"core:custom":[<script>] // [possible future extension] script lines for arbitrary condition
}
}
//graphics; mandatory; object;
"graphics":
{
// ! will be moved to bonus type config in next bonus config version
// iconImmune - OPTIONAL; string;
//resource path of icon for SPELL_IMMUNITY bonus (relative to DATA or SPRITES)
"iconImmune":"ZVS/LIB1.RES/E_SPMET",
// iconScenarioBonus- mandatory, string, image resource path
//resource path of icon for scenario bonus
"iconScenarioBonus": "MYSPELL_B",
// iconEffect- mandatory, string, image resource path
//resource path of icon for spell effects during battle
"iconEffect": "MYSPELL_E",
// iconBook- mandatory, string, image resource path
//resource path of icon for spellbook
"iconBook": "MYSPELL_E",
// iconScroll- mandatory, string, image resource path
//resource path of icon for spell scrolls
"iconScroll": "MYSPELL_E"
},
//OPTIONAL; object; TODO
"sounds":
{
//OPTIONAL; resourse path, casting sound
"cast":"LIGHTBLT"
},
//Mandatory structure
//configuration for no skill, basic, adv, expert
"levels":{
"base": {Spell level base format},
"none": {Spell level format},
"basic":{Spell level format},
"advanced":{Spell level format},
"expert":{Spell level format}
}
}
}
```
# Animation format
``` javascript
{
"projectile": [
{"minimumAngle": 0 ,"defName":"C20SPX4"},
{"minimumAngle": 0.60 ,"defName":"C20SPX3"},
{"minimumAngle": 0.90 ,"defName":"C20SPX2"},
{"minimumAngle": 1.20 ,"defName":"C20SPX1"},
{"minimumAngle": 1.50 ,"defName":"C20SPX0"}
],
"hit":["C20SPX"],
"affect":[{"defName":"C03SPA0", "verticalPosition":"bottom"}, "C11SPA1"]
}
```
# Spell level base format
Json object with data common for all levels can be put here. These configuration parameters will be default for all levels. All mandatory level fields become optional if they equal "base" configuration.
## Example
This will make spell affect single target on all levels except expert, where it is massive spell.
``` javascript
"base":{
"range": 0
},
"expert":{
"range": "X"
}
```
# Spell level format
``` javascript
{
//Mandatory, localizable description
//Use {xxx} for formatting
"description": "",
//Mandatory, number,
//cost in mana points
"cost": 1,
//Mandatory, number
"power": 10,
//Mandatory, number
"aiValue": 20,
//Mandatory, flags structure //TODO
// modifiers make sense for creature target
//
//
"targetModifier":
{
"smart": false, //true: friendly/hostile based on positiveness; false: all targets
"clearTarget": false,
"clearAffected": false,
}
//Mandatory
//spell range description in SRSL
// range "X" + smart modifier = enchanter casting, expert massive spells
// range "X" + no smart modifier = armageddon, death ripple, destroy undead
"range": "X",
//DEPRECATED, Optional, arbitrary name - bonus format map
//timed effects, overriding by name
"effects":
{
"firstEffect": {[bonus format]},
"secondEffect": {[bonus format]}
//...
},
//DEPRECATED, cumulative effects that stack while active
"cumulativeEffects":
{
"firstCumulativeEffect": {[bonus format]}
//...
},
"battleEffects":
{
"mod:firstEffect": {[effect format]},
"mod:secondEffect": {[effect format]}
//...
}
}
```
# Configurable battle effects
**If spell have at least one special effect it become configurable spell and spell configuration processed different way**
## Configurable spell
Configurable spells ignore *offensive* flag, *effects* and *cumulativeEffects*. For backward compatibility *offensive* flag define Damage effect, *effects* and *cumulativeEffects* define Timed effect.
## Special effect common format
``` javascript
"mod:effectId":{
"type":"mod:effectType", //identifier of effect type
"indirect": false, // effect will be deferred (f.e. land mine damage)
"optional": false // you can cast spell even if this effect in not applicable
//for unit target effects
"ignoreImmunity" : false,
"chainFactor" : 0.5,
"chainLength" : 4
//other fields depending on type
}
```
## catapult
``` javascript
"mod:effectId":{
"type": "core:catapult"
"targetsToAttack": 1, //How many targets will be attacked by this
"chanceToHitKeep" : 5, //If it is a targeted spell, chances to hit keep
"chanceToHitGate" : 25, //If it is a targeted spell, chances to hit gate
"chanceToHitTower" : 10, //If it is a targeted spell, chances to hit tower
"chanceToHitWall" : 50, //If it is a targeted spell, chances to hit wall
"chanceToNormalHit" : 60, //Chance to have 1 damage to wall, used for both targeted and massive
"chanceToCrit" : 30 //Chance to have 2 damage to wall, used for both targeted and massive
}
```
## Clone
Configurable version of Clone spell.
``` javascript
"mod:effectId":{
"type": "core:clone"
"maxTier" : 3//unit tier
}
```
## Damage effect
If effect is automatic, spell behave like offensive spell (uses power, levelPower etc)
``` javascript
"mod:effectId":{
"type": "core:damage",
"killByCount": false, //if true works like Death Stare
"killByPercentage" : false, //if true works like DESTRUCTION ability
//TODO: options override
}
```
## Dispel
documetation
## Heal
documetation
## Obstacle
documetation
## Remove obstacle
documetation
## Sacrifice
documetation
## Summon
documetation
## Teleport
documetation
## Timed
If effect is automatic, spell behave like \[de\]buff spell (effect and
cumulativeEffects ignored)
``` javascript
"mod:effectId":{
"type": "core:timed",
"cumulative": false
"bonus":
{
"firstBonus":{[bonus format]}
//...
}
}
```
# Additional documentation
## Targets, ranges, modifiers
- CREATURE target (only battle spells)
- range 0: smart assumed single creature target
- range "X" + smart modifier = enchanter casting, expert massive spells
- range "X" + no smart modifier = armageddon, death ripple, destroy undead
- any other range (including chain effect)
- smart modifier: smth like cloud of confusion in H4 (if I remember correctly :) )
- no smart modifier: like inferno, fireball etc. but target only creature
- NO_TARGET
- no target selection,(abilities, most adventure spells)
- LOCATION
- any tile on map/battlefield (inferno, fireball etc.), DD also here but with special handling
- clearTarget - destination hex must be clear (unused so far)
- clearAfffected - all affected hexes must be clear (forceField, fireWall)
- OBSTACLE target
- range 0: any single obstacle
- range X: all obstacles

1
docs/modders/Entities_Format/Terrain_Format.md Normal file
View File

@@ -0,0 +1 @@
TODO