games/vcmi
1
0
Fork 0
mirror of https://github.com/vcmi/vcmi.git synced 2025-03-19 21:10:12 +02:00
Code Issues Releases Activity

First part of documentation import

Browse Source
This commit is contained in:
Ivan Savenko 2023-08-12 12:39:44 +03:00
parent 211bcb6e82
commit 6ac0dabcab
18 changed files with 2924 additions and 209 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

0
docs/conan.md → docs/developers/conan.md
View File

116
docs/maintainers/Project Infrastructure.md Normal file
View File

@ -0,0 +1,116 @@
This page hold important information about project infrastructure for
current and future contributors. At moment it's all maintained by me
(SXX), but following information will be useful if someone going to
replace me in future.
You can also check [detailed information on server
configuration](Project_servers_configuration "wikilink").
## Services and accounts
So far we using following services:
### Most important
- VCMI.eu domain paid until July of 2019.
- Owner: Tow
- Our main domain used by services.
- VCMI.download paid until November of 2026.
- Owner: SXX
- Intended to be used for all assets downloads.
- Domain registered on GANDI and **can be renewed by anyone
without access to account**.
- [DigitalOcean](https://cloud.digitalocean.com/) team.
- Our hosting sponsor.
- Administrator access: SXX, Warmonger.
- User access: AVS, Tow.
- [CloudFlare](https://www.cloudflare.com/a/overview) account.
- Access through shared login / password.
- All of our infrastructure is behind CloudFlare and all our
webWe'll manage our DNS there.
- [Google Apps (G Suite)](https://admin.google.com/) account.
- It's only for vcmi.eu domain and limited to 5 users. Each
account has limit of 500 emails / day.
- One administrative email used for other services registration.
- "noreply" email used for outgoing mail on Wiki and Bug Tracker.
- "forum" email used for outgoing mail on Forums. Since we
authenticate everyone through forum it's should be separate
email.
- Administrator access: Tow, SXX.
- [Google Play Console](https://play.google.com/apps/publish/)
account.
- Hold ownership over VCMI Android App.
- Owner: SXX
- Administrator access: Warmonger, AVS.
- Release manager access: Fay.
Not all services let us safely share login credentials, but at least
when possible at least two of core developers must have access to them
in case of emergency.
### Public relations
We want to notify players about updates on as many social services as
possible.
- Facebook page: <https://www.facebook.com/VCMIOfficial>
- Administrator access: SXX, Warmonger
- Twitter account: <https://twitter.com/VCMIOfficial>
- Administrator access: SXX.
- User access via TweetDeck:
- VK / VKontakte page: <https://vk.com/VCMIOfficial>
- Owner: SXX
- Administrator access: AVS
- Google+ page: <https://plus.google.com/+VCMIOfficial>
- Administrator access: SXX
Other media:
- Steam group: <https://steamcommunity.com/groups/VCMI>
- Administrator access: SXX
- Moderator access: Dydzio
- Sub Reddit: <https://reddit.com/r/vcmi/>
- Administrator access: SXX
- ModDB entry: <http://www.moddb.com/engines/vcmi>
- Administrator access: SXX
### Communication channels
- Slack team: <https://h3vcmi.slack.com/>
- Owner: vmarkovtsev
- Administrator access: SXX, Warmonger, AVS...
- Trello team: <https://trello.com/vcmi/>
- Administrator access: SXX
- Unofficial discord:
- Owner: dydzio
- Administrator access: SXX
- Unofficial IRC channel: irc.freenode.net #vcmi
### Other services
- Launchpad PPA: <https://launchpad.net/~vcmi>
- Member access: AVS
- Administrator access: Ivan, SXX
- Snapcraft Dashboard: <https://dashboard.snapcraft.io/>
- Administrator access: SXX
- Coverity Scan page: <https://scan.coverity.com/projects/vcmi>
- Administrator access: SXX, Warmonger, AVS
- OpenHub page: <https://www.openhub.net/p/VCMI>
- Administrator access: Tow
- Docker Hub organization: <https://hub.docker.com/u/vcmi/>
- Administrator access: SXX
Reserve accounts for other code hosting services:
- GitLab organization: <https://gitlab.com/vcmi/>
- Administrator access: SXX
- BitBucket organization: <https://bitbucket.org/vcmi/>
- Administrator access: SXX
## What's to improve
1. Encourage Tow to transfer VCMI.eu to GANDI so it's can be also
renewed without access.
2. Use 2FA on CloudFlare and just ask everyone to get FreeOTP and then
use shared secret.
3. Centralized way to post news about game updates to all social media.

48
docs/maintainers/Project servers configuration.md Normal file
View File

@ -0,0 +1,48 @@
This page dedicated to explain specific configurations of our servers
for anyone who might need to improve it in future. Check [project
infrastructure](project_infrastructure "wikilink") page for services and
accounts overview.
## Droplet configuration
### Droplet and hosted services
Currently we using two droplets:
- First one serve all of our web services:
- [Forum](https://forum.vcmi.eu/)
- [Bug tracker](https://bugs.vcmi.eu/)
- [Wiki](https://wiki.vcmi.eu/)
- [Slack invite page](https://slack.vcmi.eu/)
- Second serve downloads:
- [Legacy download page](http://download.vcmi.eu/)
- [Build download page](https://builds.vcmi.download/)
To keep everything secure we should always keep binary downloads
separate from any web services.
### Rules to stick to
- SSH authentication by public key only.
- Incoming connections to all ports except SSH (22) must be blocked.
- Exception for HTTP(S) connection on ports 80 / 443 from [CloudFlare
IP Ranges](https://www.cloudflare.com/ips/).
- No one except core developers should ever know real server IPs.
- Droplet hostname should never be valid host. Otherwise it's exposed
in [reverse DNS](https://en.wikipedia.org/wiki/Reverse_DNS).
- If some non-web service need to listen for external connections then
read below.
### Our publicly-facing server
We only expose floating IP that can be detached from droplet in case of
emergency using [DO control
panel](https://cloud.digitalocean.com/networking/floating_ips). This
also allow us to easily move public services to dedicated droplet in
future.
- Address: beholder.vcmi.eu (67.207.75.182)
- Port 22 serve SFTP for file uploads as well as CI artifacts uploads.
If new services added firewall rules can be adjusted in [DO control
panel](https://cloud.digitalocean.com/networking/firewalls).

218
docs/modders/Animation Format.md Normal file
View File

@ -0,0 +1,218 @@
VCMI allows overriding HoMM3 .def files with .json replacement. Compared
to .def this format allows:
- Overriding individual frames from json file (e.g. icons)
- Modern graphics formats (targa, png - all formats supported by VCMI
image loader)
- Does not requires any special tools - all you need is text editor
and images.
# Format description
``` javascript
{
// Base path of all images in animation. Optional.
// Can be used to avoid using long path to images
"basepath" : "path/to/images/directory/",
// List of sequiences / groups in animation
// This will replace original group with specified list of files
// even if original animation is longer
"sequences" :
[
{
// Index of group, zero-based
"group" : 1,
// List of files in this group
"frames" :
[
"frame1.png",
"frame2.png"
...
]
},
...
],
// Allow overriding individual frames in file
"images" :
[
{
// Group of this image. Optional, default = 0
"group" : 0,
// Imdex of the image in group
"frame" : 0,
// Filename for this frame
"file" : "filename.png"
}.
...
]
}
```
# Creature animation groups
Animation for creatures consist from multiple groups, with each group
representing specific one animation. VCMI uses groups as follows:
**Basic animations**
- \[0\] Movement: Used for creature movement
- \[1\] Mouse over: Used for random idle movements and when mouse is
moved on the creature
- \[2\] Idle: Basic animation that plays continuously when stack is
not acting
- \[3\] Hitted: Animation that plays whenever stack is hit
- \[4\] Defence: Alternative animation that plays when stack is
defending and was hit in melee
- \[5\] Death: Animation that plays when stack dies
- \[6\] Death (ranged): Alternative animation, plays when stack is
killed by ranged attack
**Rotation animations**
- \[7\] Turn left: Animation for rotating stack, only contains first
part of animation, with stack turning towards viewer
- \[8\] Turn right: Second part of animation for rotating stack
- \[9\] (unused in vcmi, present in H3 files)
- \[10\] (unused in vcmi, present in H3 files)
**Melee attack animations**
- \[11\] Attack (up): Attacking animation, stack facing upwards
- \[12\] Attack (front): Attacking animation, stack facing front
- \[13\] Attack (down): Attacking animation, stack facing downwards
**Ranged attack animations**
- \[14\] Shooting (up): Ranged attack animation, stack facing upwards
- \[15\] Shooting (front): Ranged attack animation, stack facing front
- \[16\] Shooting (down): Ranged attack animation, stack facing
downwards
**Special animations**
- \[17\] Special (up): Special animation, used if dedicated cast or
group attack animations were not found
- \[18\] Special (front): Special animation, used if dedicated cast or
group attack animations were not found
- \[19\] Special (down): Special animation, used if dedicated cast or
group attack animations were not found
**Additional H3 animations**
- \[20\] Movement start: Animation that plays before movement
animation starts.
- \[21\] Movement end: Animation that plays after movement animation
ends.
**Additional VCMI animations**
- \[22\] \[VCMI 1.0\] Dead: Animation that plays when creature is
dead. If not present, will consist from last frame from "Death"
group
- \[23\] \[VCMI 1.0\] Dead (ranged): Animation that plays when
creature is dead after ranged attack. If not present, will consist
from last frame from "Death (ranged)" group
- \[24\] \[VCMI 1.2\] Resurrection: Animation that plays when creature
is resurrected. If not present, will consist from reversed version
of "Death" animation
**Spellcasting animations**
- \[30\] \[VCMI 1.2\] Cast (up): Used when creature casts spell facing
upwards
- \[31\] \[VCMI 1.2\] Cast (front): Used when creature casts spell
facing front
- \[32\] \[VCMI 1.2\] Cast (down): Used when creature casts spell
facing downwards
**Group attack animations**
- \[40\] \[VCMI 1.2\] Group Attack (up): Used when creature attacks
multiple target, with primary target facing up (Dragon Breath
attack, or creatures like Hydra)
- \[41\] \[VCMI 1.2\] Group Attack (front): Used when creature attacks
multiple target, with primary target facing front (Dragon Breath
attack, or creatures like Hydra)
- \[42\] \[VCMI 1.2\] Group Attack (down): Used when creature attacks
multiple target, with primary target facing downwards (Dragon Breath
attack, or creatures like Hydra)
# Proposed format extensions
## Void format
- vcmi client
- map editor
Json header may be omitted. In such case a single frame will be loaded
from same resource ID. Resource id should have no extension, image must
be in SPRITES/ virtual directory.
## Texture atlas format
**TODO**
- arbitrary texture coordinates
- margins
- grid-like layout
### Texture atlas format
``` javascript
{
// Base path of all images in animation. Optional.
// Can be used to avoid using long path to images
// If a path is a filename is is treated as single texture atlas
"basepath" : "path/to/images/atlas/bitmap.png",
// List of sequences / groups in animation
"sequences" :
[
{
// Index of group, zero-based
"group" : 1,
// List of files in this group
"frames" :
[
{"x":0, "y":0, "w": 64, "h": 64},
{"x":64, "y":0, "w": 64, "h": 64}
...
]
},
...
]
}
```
### Texture atlas grid format
- vcmi client
- map editor
``` javascript
{
// filename is is treated as single texture atlas
"basepath" : "path/to/images/atlas/bitmap.png",
//optional, atlas is a grid with same size images
//located left to right, top to bottom
//[columns, rows]
//default [1,1]
"gridCols":3,
"gridRows":3,
// List of sequences / groups in animation
// sequence index -> images count in sequence
"sequences" :
[
1,3,5
]
}
```

52
docs/modders/Artifact Format.md Normal file
View File

@ -0,0 +1,52 @@
See thread <http://forum.vcmi.eu/viewtopic.php?t=558> for discussion
Artifact bonuses use [Bonus Format](Bonus_Format "wikilink").
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
{
"type": ["HERO", "CREATURE", "COMMANDER"] //what kind of bearer can use this artifact
"class": "TREASURE", //TREASURE, MINOR, MAJOR, RELIC, SPECIAL
"slot": "HEAD", //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
"value": 12000, //based on ARTRAITS.txt
"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",
"map": "BigSword.def"//def file for adventure map
},
"bonuses":
{
Bonus_1,
Bonus_2
},
"components": //optional, for combined artifacts only
[
"artifact1",
"artifact2",
"artifact3"
],
"warMachine" : "some.creature" //if set with artifact works like war machine
}
```

96
docs/modders/Bonus Format.md Normal file
View File

@ -0,0 +1,96 @@
Enumerative parameters are described in HeroBonus.h file.
### Short format
``` javascript
{
["BONUS_TYPE", val, subtype, addInfo]
}
```
### Full format
All parameters but type are optional.
``` javascript
{
"type": "BONUS_TYPE",
"subtype": 0,
"val" : 0,
"valueType": "VALUE_TYPE",
"addInfo" : 0, // or [1, 2, ...]
"duration" : "BONUS_DURATION", //or ["BONUS_DURATION1", "BONUS_DURATION2", ...]"
"turns" : 0,
"sourceType" : "SOURCE_TYPE",
"sourceID" : 0,
"effectRange" : "EFFECT_RANGE",
"limiters" : [
"PREDEFINED_LIMITER", optional_parameters (...), //whhich one is preferred?
{"type" : LIMITER_TYPE, "parameters" : [1,2,3]}
],
"propagator" : ["PROPAGATOR_TYPE", optional_parameters (...)],
"updater" : {Bonus Updater},
"propagationUpdater" : {Bonus Updater, but works during propagation},
"description" : "",
"stacking" : ""
}
```
## Subtype resolution
All string identifiers of items can be used in "subtype" field. This
allows cross-referencing between the mods and make config file more
readable.
### Available prefixes
- creature.
- artifact.
- skill.
``` javascript
"pathfinding", "archery", "logistics", "scouting", "diplomacy",
"navigation", "leadership", "wisdom", "mysticism", "luck",
"ballistics", "eagleEye", "necromancy", "estates", "fireMagic",
"airMagic", "waterMagic", "earthMagic", "scholar", "tactics",
"artillery", "learning", "offence", "armorer", "intelligence",
"sorcery", "resistance", "firstAid"
```
- resource.
Possible values:
``` javascript
"wood", "mercury", "ore", "sulfur", "crystal", "gems", "gold", "mithril"
```
- hero.
- faction.
- spell.
- primSkill
``` javascript
"attack", "defence", "spellpower", "knowledge"
```
- terrain (since 0.99)
``` javascript
"dirt", "sand", "grass", "snow", "swamp", "rough", "subterra", "lava", "water", "rock"
```
### Example
``` javascript
"bonus" :
{
"type" : "HATE",
"subtype" : "creature.enchanter",
"val" : 50
}
```
This bonus makes creature do 50% more damage to Enchanters.

198
docs/modders/Creature Format.md Normal file
View File

@ -0,0 +1,198 @@
Schema in git:
[config/schemas/creature.json](https://github.com/vcmi/vcmi/blob/develop/config/schemas/creature.json)
See thread <http://forum.vcmi.eu/viewtopic.php?t=533> for discussion.
## 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" : ""
}
}
```

112
docs/modders/Hero Classes Format.md Normal file
View File

@ -0,0 +1,112 @@
Schema in git:
[config/schemas/heroClass.json](https://github.com/vcmi/vcmi/blob/develop/config/schemas/heroClass.json)
## 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
}
}
```

129
docs/modders/Hero Format.md Normal file
View File

@ -0,0 +1,129 @@
Schema in git:
[config/schemas/hero.json](https://github.com/vcmi/vcmi/blob/develop/config/schemas/hero.json)
## 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"
}
}
```

164
docs/modders/Mod file Format.md Normal file
View File

@ -0,0 +1,164 @@
This is description of mod.json file, main file for mods.
Schema in git:
[config/schemas/mod.json](https://github.com/vcmi/vcmi/blob/develop/config/schemas/mod.json)
## Fields for local file and repository
``` javascript
{
// Name of your mod. While it does not have hard length limit
// it should not be longer than ~30 symbols to fit into allowed space
"name" : "My test mod",
// More lengthy description of mod. No hard limit. This text will be visible in launcher.
// This field can use small subset of HTML, see link at the bottom of this page.
"description" : "My test mod that add a lot of useless stuff into the game",
// Author of mod. Can be nickname, real name or name of team
"author" : "Anonymous",
// Full name of license used by mod. Should be set only if you're author of mod
// or received permission to use such license from original author
"licenseName" : "Creative Commons Attribution-ShareAlike",
// URL which user can use to see license terms and text
"licenseURL" : "https://creativecommons.org/licenses/by-sa/4.0/",
// Home page of mod or link to forum thread to contact the author
"contact" : "http://example.com",
// Type of mod, list of all possible values:
// "Translation", "Town", "Test", "Templates", "Spells", "Music", "Sounds", "Skills", "Other", "Objects",
// "Mechanics", "Interface", "Heroes", "Graphical", "Expansion", "Creatures", "Artifacts", "AI"
"modType" : "Graphical",
// List of mods that are required to run this one
"depends" :
[
"baseMod"
],
// List of mods that can't be enabled in the same time as this one
"conflicts" :
[
"badMod"
],
//List of changes/new features in each version
"changelog" :
{
"1.0" : [ "initial release" ],
"1.0.1" : [ "change 1", "change 2" ],
"1.1" : [ "change 3", "change 4" ]
},
// If set to true, mod will not be enabled automatically on install
"keepDisabled" : false
}
```
## Fields specific for local file
These are fields that are present only in local mod.json file
``` javascript
{
// Following section describes configuration files with content added by mod
// It can be split into several files in any way you want but recommended organization is
// to keep one file per object (creature/hero/etc) and, if applicable, add separate file
// with translatable strings for each type of content
// See "additional links" at the bottom of page for descriptions of each of these formats
// list of factions/towns configuration files
"factions" :
[
"config/myMod/faction.json"
]
// List of hero classes configuration files
"heroClasses" :
[
"config/myMod/heroClasses.json"
],
// List of heroes configuration files
"heroes" :
[
"config/myMod/heroes.json"
],
// list of creature configuration files
"creatures" :
[
"config/myMod/creatures.json"
],
// List of artifacts configuration files
"artifacts" :
[
"config/myMod/artifacts.json"
],
// List of objects defined in this mod
"objects" :
[
"config/myMod/objects.json"
],
// List of spells defined in this mod
"spells" :
[
"config/myMod/spells.json"
],
// List of RMG templates defined in this mod
"templates" :
[
"config/myMod/templates.json"
],
// Optional, description on how files are organized in your mod
// In most cases you do not need to use this field
// Needed mostly to port any existing mods to vcmi (e.g. WoG distributed with Era)
// Example below is default value, which is "Content" directory that acts as H3 root directory
"filesystem":
{
"":
[
{"type" : "dir", "path" : "/Content"}
]
}
}
```
## Fields present only in repository
This is list of fields that must be added to mod record in repository
file
``` javascript
{
// URL which launcher will use to download mod
"download" : "http://example.com/mods/helloworld.zip",
// size of mod archive, in kilobytes
"size" : 12345,
// list of URL's with screenshots for this mod
"screenshots" : [
"http://example.com/images/helloworld_1.png"
]
}
```
## Notes
For mod description it is possible to use certain subset of HTML as
described here:
<http://qt-project.org/doc/qt-5.0/qtgui/richtext-html-subset.html>

236
docs/modders/Modding guidelines.md Normal file
View File

@ -0,0 +1,236 @@
If you just want to play see [mod list](mod_list "wikilink").
## Creating mod
To make your own mod you need to create subdirectory in
**<data dir>/Mods/** with name that will be used as identifier for your
mod.
Main mod is file called **mod.json** and should be placed into main
folder of your mod, e.g. **Mods/myMod/mod.json**
All content of your mod should go into **Content** directory, e.g.
**Mods/myMod/Content/**. In future it will be possible to replace this
directory with single .zip archive.
Example of how directory structure of your mod may look like:
Mods/
myMod/
mod.json
Content/
data/ - unorganized files, mostly bitmap images (.bmp, .png, .pcx)
config/ - json configuration files
maps/ - h3m maps added or modified by mod
music/ - music files. Mp3 is fully supported, ogg may be added if needed
sounds/ - sound files, in wav format.
sprites/ - animation, image sets (H3 .def files or VCMI .json files)
video/ - video files, .bik or .smk
## Updating mod to next version of VCMI
See [Modding changelog](Modding_changelog "wikilink")
## Creating mod file
All VCMI configuration files use [JSON
format](http://en.wikipedia.org/wiki/Json) so you may want to
familiarize yourself with it first.
Mod.json is main file in your mod and must be present in any mod. This
file contains basic description of your mod, dependencies or conflicting
mods (if present), list of new content and so on.
Minimalistic version of this file:
``` javascript
{
"name" : "My test mod",
"description" : "My test mod that add a lot of useless stuff into the game"
}
```
See [Mod file Format](Mod_file_Format "wikilink") for its full
description.
## Overriding graphical files from Heroes III
Any graphical replacer mods fall under this category. In VCMI directory
**<mod name>/Content** acts as mod-specific game root directory. So for
example file **<mod name>/Content/Data/AISHIELD.PNG** will replace file
with same name from **H3Bitmap.lod** game archive.
Any other files can be replaced in exactly same way.
Note that replacing files from archives requires placing them into
specific location:
H3Bitmap.lod -> Data
H3Sprite.lod -> Sprites
Heroes3.snd -> Sounds
Video.vid -> Video
This includes archives added by expansions (e.g. **H3ab_bmp.lod** uses
same rules as **H3Bitmap.lod**)
### Replacing .def animation files
Heroes III uses custom format for storing animation: def files. These
files are used to store all in-game animations as well as for some GUI
elements like buttons and for icon sets.
These files can be replaced by another def file but in some cases
original format can't be used. This includes but not limited to:
- Replacing one (or several) icons in set
- Replacing animation with fully-colored 32-bit images
In VCMI these animation files can also be replaced by json description
of their content. See [Animation Format](Animation_Format "wikilink")
for full description of this format.
Example: replacing single icon
``` javascript
{
// List of replaced images
"images" :
[ // Index of replaced frame
{ "frame" : 0, "file" : "HPS000KN.bmp"}
//name of file that will be used as replacement
]
}
```
"High resolution main menu" mod can be used as example of file replacer
mod.
## Packaging mod into archive
For distribution it is recommended to package mod into .zip archives. To
create .zip archive you need to have file archiver like
[7zip](http://www.7-zip.org)
File structure of packaged mod should look like this
<modname>.zip/ <- Zip archive with high compression ratio
modname/ <- Archive contains main mod directory
mod.json <- main mod file
Content.zip/ <- Uncompressed archive with all mod data
Data/
... <- Identical to Content directory
Sprites/
You can create such structure using following instructions:
- Go to Mods/<modname>/Content directory
- Select all files in this directory and create archive with following
parameters:
- Archive name: Content.zip
- Format: ZIP
- Compression level: None/Store only
- Move created archive into Mods/<modname> directory and remove no
longer needed Content directory.
- Go to Mods/ directory
- Create archive from your mod with following parameters:
- Archive name: <modname>.zip
- Format: ZIP
- Compression level: Maximum
Resulting archive is recommended form for distributing mods for VCMI
## Releasing mods
Right now there are 3 ways to bring your mod to players:
- Manual download
- VCMI Repository
- Private repository
### Manual download
You can upload mod into some online file hosting and add link with
description of your mod into [mod list](mod_list "wikilink").
Note: Avoid using services that require registration or remove files
after certain period of time (examples are Wikisend and 4shared).
Instead you may use any of the services listed below:
- [MediaFire](http://mediafire.com)
- [Dropbox](https://dropbox.com)
- [Google Drive](https://drive.google.com)
- Any other service that does not has aforementioned problems
### VCMI Repository
Another option is to add mod into VCMI repository. This will allow
players to install mods directly from VCMI Launcher without visiting any
3rd-party sites.
Check for more details in [Mods repository](Mods_repository "wikilink").
### Private repository
It it also possible to create your own repository. To do this you need
to own your own server capable of file hosting or use file service that
provide direct download links (e.g. Dropbox with enabled public
directory).
Providing own repository allows you to deliver any new mods or updates
almost instantly and on the same level of integration with VCMI as mods
from VCMI repository.
To create empty repository you need to:
- Create directory that will contain repository
- Create file named "repository.json" in it
To add mods into such repository you need to:
- Copy packaged archive <modname>.zip into repository directory
- Copy mod information from mod.json into repository.json
- Add two extra fields about this mod into repository.json:
- "download" - public link that can be used to download the mod,
including <http://> prefix
- "size" - size of mod, in kilobytes. VCMI will use this number to
inform player on size of the mod.
Example on how mod entry should look in repository.json
``` javascript
{
...
"exampleMod" // ID of the mod, lowercase version of mod directory name
{
"name" : "My test mod",
"description" : "My test mod that add a lot of useless stuff into the game",
"author" : "Anonymous",
"contact" : "http://example.com",
"modType" : "Graphical",
"depends" :
[
"baseMod"
],
"download" : "http://example.com/vcmi/repository/exampleMod.zip",
"size" : 1234 //size, in kilobytes
//Note that entries that refer to files, e.g. "heroes". "creatures", "artifacts" and such
//are not necessary in repository.json and therefore can be removed
},
...
}
```
When repository is ready you can share public link to repository.json
with players. New repositories can added to vcmi launcher from settings
tab.
#### Dropbox: enabling public directory
New accounts create on Dropbox no longer have Public directory enabled
by default. You can enable it using this
[link](https://www.dropbox.com/enable_public_folder)
This will give you directory named "Public" as well as option "get
public link" for all files inside this directory.

99
docs/modders/Mods repository.md Normal file
View File

@ -0,0 +1,99 @@
This article will introduce you to new VCMI mod repository system and
explain how new mods can be added there.
# How mod repository work
## Where files are hosted
Mods list hosted under main VCMI organization:
[vcmi-mods-repository](https://github.com/vcmi/vcmi-mods-repository).
Each mod hosted in it's own repository under separate organization
[vcmi-mods](https://github.com/vcmi-mods). This way if engine become
more popular in future we can create separate teams for each mod and
accept as many people as needed.
## Why Git / GitHub?
It's solve a lot of problems:
- Engine developers get control over all mods and can easily update
them without adding extra burden for modders / mod maintainers.
- With tools such as [GitHub Desktop](https://desktop.github.com/)
it's easy for non-programmers to contribute.
- Forward and backward compatibility. Stable releases of game use
compatible version of mods while users of daily builds will be able
to test mods supporting bleeding edge features.
- Tracking of changes for repository and mods. It's not big deal now,
but once we have scripting it's will be important to keep control
over what code included in mods.
- GitHub also create ZIP archives for us so mods will be stored
uncompressed and version can be identified by commit hash.
## On backward compatibility
Our mod list in vcmi-mods-repository had "develop" as primary branch.
Daily builds of VCMI use mod list file from this branch.
Once VCMI get stable release there will be branching into "1.0.0",
"1.1.0", etc. Launcher of released version will request mod list for
particular version.
Same way we can also create special stable branch for every mod under
"vcmi-mods" organization umbrella once new stable version is released.
So this way it's will be easier to maintain two versions of same mod:
for stable and latest version.
# Getting mod into repository
## Getting into vcmi-mods organization
Before your mod can be accepted into official mod list you need to get
it into repository under "vcmi-mods" organization umbrella. To do this
contact one of mod repository maintainers. If needed you can get own
team within "vcmi-mods" organization.
Link to our mod will looks like that:
https://github.com/vcmi-mods/adventure-ai-trace
## Rules of repository
### Allowed name for mod identifier
For sanity reasons mod identifier must only contain lower-case English
characters, numbers and hyphens.
my-mod-name
2000-new-maps
Sub-mods can be named as you like, but we strongly encourage everyone to
use proper identifiers for them as well.
### Rewriting History
Once you submitted certain commit into official mod list you are not
allowed to rewrite history before that commit. This way we can make sure
that VCMI launcher will always be able to download older version of any
mod.
Branches such as "develop" or stable branches like "1.0.0" should be
marked as protected on GitHub.
## Submitting mods to repository
Once mod ready for general public maintainer to make PR to
[vcmi-mods-repository](https://github.com/vcmi/vcmi-mods-repository).
## Requirements
Right now main requirements for a mod to be accepted into VCMI mods list
are:
- Mod must be complete. For work-in-progress mods it is better to use
other way of distribution.
- Mod must met some basic quality requirements. Having high-quality
content is always preferable.
- Mod must not contain any errors detectable by validation (console
message you may see during loading)
- Music files must be in Ogg/Vorbis format (\*.ogg extension)

153
docs/modders/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](https://github.com/vcmi/vcmi/wiki/Modding-~-Objects-~-Rewardable)
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
}
}
```

86
docs/modders/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 }
}
}
}
```

400
docs/modders/Spell Format.md Normal file
View File

@ -0,0 +1,400 @@
# 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

388
docs/modders/Town 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
}
```

429
docs/players/manual.md Normal file
View File

@ -0,0 +1,429 @@
# Introduction
The purpose of VCMI project is to rewrite entire HoMM3: WoG engine from
scratch, giving it new and extended possibilities. We are hoping to
support mods and new towns already made by fans, but abandoned because
of game code limitations.\
VCMI is a fan-made open-source project in progress. We already allow
support for maps of any sizes, higher resolutions and extended engine
limits. However, although working, the game is not finished. There are
still many features and functionalities to add, both old and brand new.\
Learn more about VCMI Project at
[Wiki](http://wiki.vcmi.eu/index.php?title=VCMI).\
Check [google
docs](http://spreadsheets.google.com/ccc?key=pRhYM0YkAF9lIpLe4raNAWA&hl=pl)
for the list of already implemented objects, spells and artifacts.
# Installation
VCMI requires Heroes of Might & Magic 3 complete + WoG 3.58f
installation and will not run properly without their files. We strongly
recommend using English version, other languages may cause unexpected
errors or bizarre font glitches.\
If you don't have Wake of Gods 3.58f yet, click
[here](http://www.maps4heroes.com/heroes3/files/allinone_358f.zip).\
For English language files, extract [this
package](http://download.vcmi.eu/dataEN.7z) to your `Data` folder.\
Starting from 0.90, VCMI can be also installed on H3 + ERA setups.
## Windows
To install VCMI, simply unzip downloaded archive to main HoMM3
directory. To launch it, click `VCMI_client` icon. Server mode is
inactive yet.\
## Linux
Visit [Wiki
article](http://wiki.vcmi.eu/index.php?title=Installation_on_Linux) for
Linux packages and installation guidelines.\
# New features
A number of enchancements had been introduced thorough new versions of
VCMI. In this section you can learn about all of them.
## High resolutions
VCMI supports resolutions higher than original 800x600. Namely these
are:
- 1024x600
- 1024x768
- 1280x960
- 1280x1024
- 1366x768
- 1440x900
- 1600x1050
- 1600x1200
- 1920x1080
Switching resolution may not only change visible area of map, but also
alters some interface features such as [Stack Queue.](#Stack_Queue)\
To change resolution or full screen mode use System Options menu when in
game. Changes in resolution will take place when you restart VCMI.\
Fullscreen mode can be toggled anytime using F4 hotkey. []{#Mods
label="Mods"}
## Game modification
Since 0.9, there is a possibility to edit gameplay settings with config
file. You may turn some options on/off or adjust certain values in
`config/defaultMods.json` file. This file is read at game launch and the
settings are stored in savegame file, so editing config won't break
existing games.\
Files placed in `Mods` subfolders will override all default files and
settings. []{#Stack_Experience label="Stack_Experience"}
## New creature info window
In 0.85, new stack experience interface has been merged with regular
creature window. Among old functionalities, it includes new useful info:
- Click experience icon to see detailed info about creature rank and
experience needed for next level. This window works only if stack
experience module is enabled (true by default).
- Stack Artifact. As yet creature artifacts are not handled, so this
place is unused. You can choose enabled artifact with arrow buttons.
There is also additional button below to pass currently selected
artifact back to hero.
- Abilities description contain information about actual values and
types of bonuses received by creature - be it default ability, stack
experience, artifact or other effect. These descriptions use custom
text files which have not been translated.
By default new window is used. In order to switch back to original
creature window, use system setting dialog or type `switchCreWin` in
console\
[]{#Commanders label="Commanders"}
## Commanders
VCMI offers native support for Commanders. By default, they resemble
original WoG behaviour with basic \"Commanders: script enabled.
[]{#Stack_Artifacts label="Stack_Artifacts"}
## Stack artifacts
The possibility to equip creatures with artifacts has been extended -
now a number of artifacts can be potentially equipped. By default, there
artifacts are not possible to use by hero itself. Drag them from
backpack onto Stack portrait to equip.\
Current list of Stack Artifacts available for testing:
- Warlord's banner
- Magic Wand
- Gold Tower Arrow
- Monster's Power
[]{#Stack_Queue label="Stack_Queue"}
## Stack Queue
Stack queue is a feature coming straight from HoMM5, which allows you to
see order of stacks on the battlefield, sorted from left to right. To
toggle in on/off, press 'Q' during the battle.\
There is smaller and bigger version of it, the second one is available
only in higher resolutions.
## Pathfinder
VCMI introduces improved pathfinder, which may find the way on adventure
map using ships and subterranean gates. Simply click your destination on
another island or level and the proposed path will be displayed.
[]{#Quest_Log label="Quest_Log"}
## Quest log
In 0.9 new quest log was introduced. It can display info about Seer Hut
or Quest Guard mission, but also handle Borderguard and Border Gate
missions. When you choose a quest from the list on the left, it's
description is shown. Additionally, on inner minimap you can see small
icons indicating locations of quest object. Clicking these objects
immediately centers adventure map on desired location.
## Attack range
In combat, some creatures, such as Dragon or Cerberi, may attack enemies
on multiple hexes. All such attacked stacks will be highlighted if the
attack cursor is hovered over correct destination tile.\
Whenever battle stack is hovered, its movement range is highlighted in
darker shade. This can help when you try to avoid attacks of melee
units.
## Power rating
When hovering cursor over neutral stack on adventure map, you may notice
additional info about relative threat this stack poses to selected hero.
This feature has been introduced in Heroes of Might and Magic V and is
planned to be extended to all kinds of armed objects.\
Custom text file is in use, so using localized version of data files
will not change text in your game. It is not a bug, but lack of new
translated files.
## FPS counter
VCMI 0.85 introduces new feature for testing, the FPS counter. To enable
it, edit this line in config/settings.txt file:\
[`showFPS=0;`]{style="background-color: SpringGreen"}\
Value of 1 enables simple FPS counter which may be useful to test
graphical performance on mobile platforms.
## Custom menu graphics
Since 0.9, it is possible to use any background graphics in main menu.
Open `config/mainmenu.json` file for that reason and edit this line:\
[`"background" : "background-file-name"`]{style="background-color: SpringGreen"}\
Place the background file in `Data` folder.
## Minor improvements
### Linux directory
In Linux-based sysems, files placed in $\sim$`/.vcmi` directory will
override data files with the same name.
## New controls
VCMI introduces several minor improvements and new keybinds in user
interface.
### Pregame - Scenario / Saved Game list
- Mouse wheel - scroll through the Scenario list.
- Home - move to the top of the list.
- End - move to the bottom of the list.
- NumPad keys can be used in the Save Game screen (they didn't work in
H3).
### Adventure Map
- CTRL + R - Quick restart of current scenario.
- CTRL + Arrows - scrolls Adventure Map behind an open window.
- CTRL pressed blocks Adventure Map scrolling (it allows us to leave
the application window without losing current focus).
- NumPad 5 - centers view on selected hero.
- NumPad Enter functions same as normal Enter in the game (it didn't
in H3).
### Spellbook
- ALT + 1-10 or '-' or '=' on main pad - cast 1st to 12th visible
spell
- ALT + 1-10 or '-' or '+' on NumPad - cast 1st to 12th spell
### Miscellaneous
- Numbers for components in selection window - for example Treasure
Chest, skill choice dialog and more yet to come.
- Type numbers in the Split Stack screen (for example 25 will split
the stacks as such that there are 25 creatures in the second stack).
- 'Q' - Toggles the [Stack Queue](#Stack_Queue) display (so it can be
enabled/disabled with single key press).
- During Tactics phase, click on any of your stack to instantly
activate it. No need to scroll trough entire army anymore.
## Cheat codes
Following cheat codes have been implemented in VCMI. Type them in
console:
- `vcmiistari` - Gives all spells and 999 mana to currently selected
hero
- `vcmiainur` - Gives 5 Archangels to every empty slot of currently
selected hero
- `vcmiangband` - Gives 10 Black Knights into each slot
- `vcmiarmenelos` - Build all structures in currently selected town
- `vcminoldor` - All war machines
- `vcminahar` - 1000000 movement points
- `vcmiformenos` - Give resources (100 wood, ore and rare resources
and 20000 gold)
- `vcmieagles` - Reveals fog of war
- `vcmiglorfindel` - Advances currently selected hero to the next
level
- `vcmisilmaril` - Player wins
- `vcmimelkor` - Player loses
- `vcmiforgeofnoldorking` - Hero gets all artifacts except spell book,
spell scrolls and war machines
## Command line
It is possible to save a starting configuration (such as map and
options) in pregame by typing \"`sinfo` filename\". Then VCMI can be
started with option `-i –start=fname` and it will automatically start
the game.\
`–onlyAI` command line option allows to run AI-on-AI game (without GUI).
Also, typing `onlyai` in pregame triggers that mode.
# Release notes
- In 0.89 [Commanders](#Commanders) and [Stack
Artifacts](#Stack_Artifacts) were implemented and enabled by
default. There are four Stack Artifacts available. Their behaviour
has been altered for testing purpose only.
- [Stack Experience](#Stack_Experience) is enabled by default. It's an
optional feature, but needs complex tesing. Mechanics and tables
from original WoG 3.58f were used for this purpose. Note that not
all of WoG creature abilities are handled.
- Online game, random map generator as well as some other parts of the
game are not yet implemented. Do not worry if nothing happens when
you click them, please report only actual bugs and game crashes.
- It is possible to start the campaign, although heroes will not carry
over to subsequent scenarios.
## Android port
Android port, despite some rumours, is not complete and may crash at
random. The port is work of a Peyla - volunteer outside of VCMI team,
who abandoned it. Any Android support is beyond our scope. []{#Feedback
label="Feedback"}
# Feedback
Our project is open and its sources are available for everyone to browse
and download. We do our best to inform community of Heroes fans with all
the details and development progress. We also look forward to your
comments, support and advice.\
A good place to start is [VCMI
Wiki](http://wiki.vcmi.eu/index.php?title=Main_Page) which contains all
necessary information for developers, testers and the people who would
like to get familiar with our project. If you want to report a bug, use
[Mantis Bugtracker](http://bugs.vcmi.eu/bug_report_advanced_page.php).\
Make sure the issue is not already mentioned on [the
list](http://bugs.vcmi.eu/view_all_bug_page.php) unless you can provide
additional details for it.\
Please do not report as bugs features not yet implemented. For proposing
new ideas and requests, visit [our
board](http://forum.vcmi.eu/index.php).\
VCMI comes with its own bug handlers: the console which prints game log
`(server_log, VCMI_Client_log, VCMI_Server_log)` and memory dump file
(`.dmp`) created on crash on Windows systems. These may be very helpful
when the nature of bug is not obvious, please attach them if necessary.\
To resolve an issue, we must be able to reproduce it on our computers.
Please put down all circumstances in which a bug occurred and what did
you do before, especially if it happens rarely or is not clearly
visible. The better report, the better chance to track the bug quickly.
### Linux notes
On \*nix-like systems logs can be found in $\sim$`/.vcmi` directory.\
When reporting compilation issues please specify name and version of
your distribution.
# FAQ
## When will the final version be released?
When it is finished, which is another year at least. Exact date is
impossible to predict.\
Development tempo depends mostly on free time of active programmers and
community members, there is no exact shedule. You may expect new version
every three months. Of course, joining the project will speed things up.
## Are you going to add / change X?
VCMI recreates basic H3:TSoD + WoG engine and does not add new content
or modify original mechanics by default. Only engine and interface
improvements are likely to be supported now. The list of possible
features is placed on [Wiki TODO
list](http://wiki.vcmi.eu/index.php?title=TODO_list). If you want
something specific to be done, please present detailed project on [our
board](http://forum.vcmi.eu/index.php). Of course you are free to
contribute with anything you can do.
## Will it be possible to do Y?
Removing engine restrictions and allowing flexible modding of game is
the main aim of the project.\
As yet modification of game is not supported.
## The game is not working, it crashes and I get strange console messages.
Report your bug. Details are described [here](#Feedback). The sooner you
tell the team about the problem, the sooner it will be resolved. Many
problems come just from improper installation or system settings.
## What is the current status of the project?
Check [Wiki](http://wiki.vcmi.eu/index.php?title=VCMI), [release
notes](http://forum.vcmi.eu/viewforum.php?f=1) or
[changelog](https://github.com/vcmi/vcmi/blob/develop/ChangeLog). The
best place to watch current changes as they are committed to the develop
branch is the [Github commits
page](https://github.com/vcmi/vcmi/commits/develop). The game is quite
playable by now, although many important features are missing.
## I have a great idea!
Share it on [VCMI forum](http://forum.vcmi.eu/index.php) so all team
members can see it and share their thoughts. Remember, brainstorming is
good for your health.
## Are you going to support Horn of The Abyss / Wog 3.59 / Grove Town etc.?
Yes, of course. VCMI is designed as a base for any further mods and uses
own executables, so the compatibility is not an issue. The team is not
going to compete, but to cooperate with the community of creative
modders.
## I don't like Wake of Gods at all. Can I disable it?
Most WoG features already implemented are just for testing purposes and
can be disabled in [mod settings](#Mods).
## Can I help VCMI Project in any way?
If you are C++ programmer, graphican, tester or just have tons of ideas,
do not hesistate - your help is needed. The game is huge and many
different ares of activity are still waiting for someone like you. See
[Wiki TODO list](http://wiki.vcmi.eu/index.php?title=TODO_list) for more
info.
## I would like to join development team.
You are always welcome. Contact the core team via [our
board](http://forum.vcmi.eu/index.php). In the meantime, read 'building
VCMI' guide at [Wiki](http://wiki.vcmi.eu/index.php?title=Main_Page).\
The usual way to join the team is to post your patch for review on our
board. If the patch is positively rated by core team members, you will
be given access to SVN repository.
# Credits

209
vcmimanual.tex
View File

@ -1,209 +0,0 @@
\documentclass[a4size,final]{article}
\usepackage{fullpage}
%\usepackage{graphicx}
\usepackage[usenames,dvipsnames]{color}
\usepackage{hyperref}
\hypersetup{
colorlinks,
citecolor=black,
filecolor=black,
linkcolor=ForestGreen,
urlcolor=blue
}
\begin{document}
\normalsize
\pagestyle{plain}
\setcounter{secnumdepth}{1}
\title{\Huge VCMI 0.90 player manual}
\author{The Team}
\maketitle
\section{Introduction}
The purpose of VCMI project is to rewrite entire HoMM3: WoG engine from scratch, giving it new and extended possibilities. We are hoping to support mods and new towns already made by fans, but abandoned because of game code limitations.\\
VCMI is a fan-made open-source project in progress. We already allow support for maps of any sizes, higher resolutions and extended engine limits. However, although working, the game is not finished. There are still many features and functionalities to add, both old and brand new.\smallskip\\
Learn more about VCMI Project at \href{http://wiki.vcmi.eu/index.php?title=VCMI}{Wiki}.\\
Check \href{http://spreadsheets.google.com/ccc?key=pRhYM0YkAF9lIpLe4raNAWA&hl=pl}{google docs} for the list of already implemented objects, spells and artifacts.
\section{Installation}
VCMI requires Heroes of Might \& Magic 3 complete + WoG 3.58f installation and will not run properly without their files. We strongly recommend using English version, other languages may cause unexpected errors or bizarre font glitches.\\
If you don't have Wake of Gods 3.58f yet, click \href{http://www.maps4heroes.com/heroes3/files/allinone_358f.zip}{here}.\\
For English language files, extract \href{http://download.vcmi.eu/dataEN.7z}{this package} to your \texttt{Data} folder.\bigskip\\
Starting from 0.90, VCMI can be also installed on H3 + ERA setups.
\subsection{Windows}
To install VCMI, simply unzip downloaded archive to main HoMM3 directory. To launch it, click \texttt{VCMI\_client} icon. Server mode is inactive yet.\medskip\\
\subsection{Linux}
Visit \href{http://wiki.vcmi.eu/index.php?title=Installation_on_Linux}{Wiki article} for Linux packages and installation guidelines.\\
\newpage
\section{New features}
A number of enchancements had been introduced thorough new versions of VCMI. In this section you can learn about all of them.
\subsection{High resolutions}
VCMI supports resolutions higher than original 800x600. Namely these are:
\begin{itemize}
\item 1024x600
\item 1024x768
\item 1280x960
\item 1280x1024
\item 1366x768 %\footnote{May cause bugs on old video cards}
\item 1440x900
\item 1600x1050
\item 1600x1200
\item 1920x1080
\end{itemize}
Switching resolution may not only change visible area of map, but also alters some interface features such as \hyperref[Stack_Queue]{Stack Queue.}\\
To change resolution or full screen mode use System Options menu when in game. Changes in resolution will take place when you restart VCMI. \\
Fullscreen mode can be toggled anytime using F4 hotkey.
%\end{itemize}
\label{Mods}
\subsection{Game modification}
Since 0.9, there is a possibility to edit gameplay settings with config file. You may turn some options on/off or adjust certain values in \texttt{config/defaultMods.json} file. This file is read at game launch and the settings are stored in savegame file, so editing config won't break existing games.\\
Files placed in \texttt{Mods} subfolders will override all default files and settings.
\label{Stack_Experience}
\subsection{New creature info window}
In 0.85, new stack experience interface has been merged with regular creature window. Among old functionalities, it includes new useful info:
\begin{itemize}
\item Click experience icon to see detailed info about creature rank and experience needed for next level. This window works only if stack experience module is enabled (true by default).
\item Stack Artifact. As yet creature artifacts are not handled, so this place is unused. You can choose enabled artifact with arrow buttons. There is also additional button below to pass currently selected artifact back to hero.
\item Abilities description contain information about actual values and types of bonuses received by creature - be it default ability, stack experience, artifact or other effect. These descriptions use custom text files which have not been translated.
\end{itemize}
By default new window is used. In order to switch back to original creature window, use system setting dialog or type \texttt{switchCreWin} in console\\
\label{Commanders}
\subsection{Commanders}
VCMI offers native support for Commanders. By default, they resemble original WoG behaviour with basic "Commanders: script enabled.
\label{Stack_Artifacts}
\subsection{Stack artifacts}
The possibility to equip creatures with artifacts has been extended - now a number of artifacts can be potentially equipped. By default, there artifacts are not possible to use by hero itself. Drag them from backpack onto Stack portrait to equip.\\
Current list of Stack Artifacts available for testing:
\begin{itemize}
\item Warlord's banner
\item Magic Wand
\item Gold Tower Arrow
\item Monster's Power
\end{itemize}
\label{Stack_Queue}
\subsection{Stack Queue}
Stack queue is a feature coming straight from HoMM5, which allows you to see order of stacks on the battlefield, sorted from left to right. To toggle in on/off, press `Q' during the battle.\\
There is smaller and bigger version of it, the second one is available only in higher resolutions.
\subsection{Pathfinder}
VCMI introduces improved pathfinder, which may find the way on adventure map using ships and subterranean gates. Simply click your destination on another island or level and the proposed path will be displayed.
\label{Quest_Log}
\subsection{Quest log}
In 0.9 new quest log was introduced. It can display info about Seer Hut or Quest Guard mission, but also handle Borderguard and Border Gate missions. When you choose a quest from the list on the left, it's description is shown. Additionally, on inner minimap you can see small icons indicating locations of quest object. Clicking these objects immediately centers adventure map on desired location.
\subsection{Attack range}
In combat, some creatures, such as Dragon or Cerberi, may attack enemies on multiple hexes. All such attacked stacks will be highlighted if the attack cursor is hovered over correct destination tile.\\
Whenever battle stack is hovered, its movement range is highlighted in darker shade. This can help when you try to avoid attacks of melee units.
\subsection{Power rating}
When hovering cursor over neutral stack on adventure map, you may notice additional info about relative threat this stack poses to selected hero. This feature has been introduced in Heroes of Might and Magic V and is planned to be extended to all kinds of armed objects.\\
Custom text file is in use, so using localized version of data files will not change text in your game. It is not a bug, but lack of new translated files.
\subsection{FPS counter}
VCMI 0.85 introduces new feature for testing, the FPS counter. To enable it, edit this line in config/settings.txt file:\\
\colorbox{SpringGreen}{\texttt{showFPS=0;}}\\
Value of 1 enables simple FPS counter which may be useful to test graphical performance on mobile platforms.
\subsection{Custom menu graphics}
Since 0.9, it is possible to use any background graphics in main menu. Open \texttt{config/mainmenu.json} file for that reason and edit this line:\\
\colorbox{SpringGreen}{\texttt{"background" : "background-file-name"}}\\
Place the background file in \texttt{Data} folder.
\subsection{Minor improvements}
\subsubsection{Linux directory}
In Linux-based sysems, files placed in \texttt{$\sim$/.vcmi} directory will override data files with the same name.
\subsection{New controls}
VCMI introduces several minor improvements and new keybinds in user interface.
\subsubsection{Pregame - Scenario / Saved Game list}
\begin{itemize}
\item Mouse wheel - scroll through the Scenario list.
\item Home - move to the top of the list.
\item End - move to the bottom of the list.
\item NumPad keys can be used in the Save Game screen (they didn't work in H3).
\end{itemize}
\subsubsection{Adventure Map}
\begin{itemize}
\item CTRL + R - Quick restart of current scenario.
\item CTRL + Arrows - scrolls Adventure Map behind an open window.
\item CTRL pressed blocks Adventure Map scrolling (it allows us to leave the application window without losing current focus).
\item NumPad 5 - centers view on selected hero.
\item NumPad Enter functions same as normal Enter in the game (it didn't in H3).
\end{itemize}
\subsubsection{Spellbook}
\begin{itemize}
\item ALT + 1-10 or `-' or `=' on main pad - cast 1st to 12th visible spell
\item ALT + 1-10 or `-' or `+' on NumPad - cast 1st to 12th spell
\end{itemize}
\subsubsection{Miscellaneous}
\begin{itemize}
\item Numbers for components in selection window - for example Treasure Chest, skill choice dialog and more yet to come.
\item Type numbers in the Split Stack screen (for example 25 will split the stacks as such that there are 25 creatures in the second stack).
\item `Q' - Toggles the \hyperref[Stack_Queue]{Stack Queue} display (so it can be enabled/disabled with single key press).
\item During Tactics phase, click on any of your stack to instantly activate it. No need to scroll trough entire army anymore.
\end{itemize}
\subsection{Cheat codes}
Following cheat codes have been implemented in VCMI. Type them in console:
\begin{itemize}
\item \texttt{vcmiistari} - Gives all spells and 999 mana to currently selected hero
\item \texttt{vcmiainur} - Gives 5 Archangels to every empty slot of currently selected hero
\item \texttt{vcmiangband} - Gives 10 Black Knights into each slot
\item \texttt{vcmiarmenelos} - Build all structures in currently selected town
\item \texttt{vcminoldor} - All war machines
\item \texttt{vcminahar} - 1000000 movement points
\item \texttt{vcmiformenos} - Give resources (100 wood, ore and rare resources and 20000 gold)
\item \texttt{vcmieagles} - Reveals fog of war
\item \texttt{vcmiglorfindel} - Advances currently selected hero to the next level
\item \texttt{vcmisilmaril} - Player wins
\item \texttt{vcmimelkor} - Player loses
\item \texttt{vcmiforgeofnoldorking} - Hero gets all artifacts except spell book, spell scrolls and war machines
\end{itemize}
\subsection{Command line}
It is possible to save a starting configuration (such as map and options) in pregame by typing "\texttt{sinfo} filename". Then VCMI can be started with option \texttt{-i --start=fname} and it will automatically start the game.\\
\texttt{--onlyAI} command line option allows to run AI-on-AI game (without GUI). Also, typing \texttt{onlyai} in pregame triggers that mode.
\newpage
\section{Release notes}
\begin{itemize}
\item In 0.89 \hyperref[Commanders]{Commanders} and \hyperref[Stack_Artifacts]{Stack Artifacts} were implemented and enabled by default. There are four Stack Artifacts available. Their behaviour has been altered for testing purpose only.
\item \hyperref[Stack_Experience]{Stack Experience} is enabled by default. It's an optional feature, but needs complex tesing. Mechanics and tables from original WoG 3.58f were used for this purpose. Note that not all of WoG creature abilities are handled.
\item Online game, random map generator as well as some other parts of the game are not yet implemented. Do not worry if nothing happens when you click them, please report only actual bugs and game crashes.
\item It is possible to start the campaign, although heroes will not carry over to subsequent scenarios.
\end{itemize}
\subsection{Android port}
Android port, despite some rumours, is not complete and may crash at random. The port is work of a Peyla - volunteer outside of VCMI team, who abandoned it. Any Android support is beyond our scope.
\label{Feedback}
\section{Feedback}
Our project is open and its sources are available for everyone to browse and download. We do our best to inform community of Heroes fans with all the details and development progress. We also look forward to your comments, support and advice.\medskip\\
A good place to start is \href{http://wiki.vcmi.eu/index.php?title=Main_Page}{VCMI Wiki} which contains all necessary information for developers, testers and the people who would like to get familiar with our project.
If you want to report a bug, use \href{http://bugs.vcmi.eu/bug_report_advanced_page.php}{Mantis Bugtracker}.\\
Make sure the issue is not already mentioned on \href{http://bugs.vcmi.eu/view_all_bug_page.php}{the list} unless you can provide additional details for it.\\
Please do not report as bugs features not yet implemented. For proposing new ideas and requests, visit \href{http://forum.vcmi.eu/index.php}{our board}.\medskip\\
VCMI comes with its own bug handlers: the console which prints game log \texttt{(server\_log, VCMI\_Client\_log, VCMI\_Server\_log)} and memory dump file (\texttt{.dmp}) created on crash on Windows systems. These may be very helpful when the nature of bug is not obvious, please attach them if necessary.\medskip\\
To resolve an issue, we must be able to reproduce it on our computers. Please put down all circumstances in which a bug occurred and what did you do before, especially if it happens rarely or is not clearly visible. The better report, the better chance to track the bug quickly.
\subsubsection{Linux notes}
On *nix-like systems logs can be found in \texttt{$\sim$/.vcmi} directory. \\
When reporting compilation issues please specify name and version of your distribution.
\section{FAQ}
\subsection{When will the final version be released?}
When it is finished, which is another year at least. Exact date is impossible to predict.\\
Development tempo depends mostly on free time of active programmers and community members, there is no exact shedule. You may expect new version every three months. Of course, joining the project will speed things up.
\subsection{Are you going to add / change X?}
VCMI recreates basic H3:TSoD + WoG engine and does not add new content or modify original mechanics by default. Only engine and interface improvements are likely to be supported now. The list of possible features is placed on \href{http://wiki.vcmi.eu/index.php?title=TODO_list}{Wiki TODO list}.
If you want something specific to be done, please present detailed project on \href{http://forum.vcmi.eu/index.php}{our board}. Of course you are free to contribute with anything you can do.
\subsection{Will it be possible to do Y?}
Removing engine restrictions and allowing flexible modding of game is the main aim of the project.\\
As yet modification of game is not supported.
\subsection{The game is not working, it crashes and I get strange console messages.}
Report your bug. Details are described \hyperref[Feedback]{here}. The sooner you tell the team about the problem, the sooner it will be resolved. Many problems come just from improper installation or system settings.
\subsection{What is the current status of the project?}
Check \href{http://wiki.vcmi.eu/index.php?title=VCMI}{Wiki}, \href{http://forum.vcmi.eu/viewforum.php?f=1}{release notes} or \href{https://github.com/vcmi/vcmi/blob/develop/ChangeLog}{changelog}. The best place to watch current changes as they are committed to the develop branch is the \href{https://github.com/vcmi/vcmi/commits/develop}{Github commits page}. The game is quite playable by now, although many important features are missing.
\subsection{I have a great idea!}
Share it on \href{http://forum.vcmi.eu/index.php}{VCMI forum} so all team members can see it and share their thoughts. Remember, brainstorming is good for your health.
\subsection{Are you going to support Horn of The Abyss / Wog 3.59 / Grove Town etc.?}
Yes, of course. VCMI is designed as a base for any further mods and uses own executables, so the compatibility is not an issue. The team is not going to compete, but to cooperate with the community of creative modders.
\subsection{I don't like Wake of Gods at all. Can I disable it?}
Most WoG features already implemented are just for testing purposes and can be disabled in \hyperref[Mods]{mod settings}.
\subsection{Can I help VCMI Project in any way?}
If you are C++ programmer, graphican, tester or just have tons of ideas, do not hesistate - your help is needed. The game is huge and many different ares of activity are still waiting for someone like you. See \href{http://wiki.vcmi.eu/index.php?title=TODO_list}{Wiki TODO list} for more info.
\subsection{I would like to join development team.}
You are always welcome. Contact the core team via \href{http://forum.vcmi.eu/index.php}{our board}. In the meantime, read `building VCMI' guide at \href{http://wiki.vcmi.eu/index.php?title=Main_Page}{Wiki}.\\
The usual way to join the team is to post your patch for review on our board. If the patch is positively rated by core team members, you will be given access to SVN repository.
\section{Credits}
Visit
\href{http://forum.vcmi.eu/index.php}{VCMI board}
for additional support.
\bigskip\\
\begin{center}
This manual will be updated with every new release.
\end{center}
\end{document}