diff --git a/docs/developers/Building_macOS.md b/docs/developers/Building_macOS.md index a463c0db2..0698b535a 100644 --- a/docs/developers/Building_macOS.md +++ b/docs/developers/Building_macOS.md @@ -1,4 +1,4 @@ -# Requirements +## Requirements 1. C++ toolchain, either of: - Xcode Command Line Tools (aka CLT): `sudo xcode-select --install` @@ -9,7 +9,7 @@ * Ninja: `brew install ninja` or get it from * CCache to speed up recompilation: `brew install ccache` -# Obtaining source code +## Obtaining source code Clone with submodules. Example for command line: @@ -17,11 +17,11 @@ Clone with submodules. Example for command line: git clone --recurse-submodules https://github.com/vcmi/vcmi.git ``` -# Obtaining dependencies +## Obtaining dependencies There're 2 ways to get dependencies automatically. -## Conan package manager +### Conan package manager Please find detailed instructions [here](./Conan.md). Note that the link points to the state of the current branch, for the latest release check the same document in the [master branch](https://github.com/vcmi/vcmi/blob/master/docs/developers/Сonan.md). @@ -32,7 +32,7 @@ On the step where you need to replace **PROFILE**, choose: Note: if you wish to build 1.0 release in non-`Release` configuration, you should define `USE_CONAN_WITH_ALL_CONFIGS=1` environment variable when executing `conan install`. -## Homebrew +### Homebrew 1. [Install Homebrew](https://brew.sh/) 2. Install dependencies: `brew install boost minizip sdl2 sdl2_image sdl2_mixer sdl2_ttf tbb` @@ -41,7 +41,7 @@ Note: if you wish to build 1.0 release in non-`Release` configuration, you shoul - `brew install qt@5` for Qt 5 or `brew install qt` for Qt 6 - using [Qt Online Installer](https://www.qt.io/download) - choose **Go open source** -# Preparing build environment +## Preparing build environment This applies only to Xcode-based toolchain. If `xcrun -f clang` prints errors, then use either of the following ways: @@ -49,7 +49,7 @@ This applies only to Xcode-based toolchain. If `xcrun -f clang` prints errors, t - use `xcode-select` utility to set Xcode or Xcode Command Line Tools path: for example, `sudo xcode-select -s /Library/Developer/CommandLineTools` - set `DEVELOPER_DIR` environment variable pointing to Xcode or Xcode Command Line Tools path: for example, `export DEVELOPER_DIR=/Applications/Xcode.app` -# Configuring project for building +## Configuring project for building Note that if you wish to use Qt Creator IDE, you should skip this step and configure respective variables inside the IDE. @@ -72,28 +72,28 @@ Note that if you wish to use Qt Creator IDE, you should skip this step and confi 8. If you want to speed up the recompilation, add `-D ENABLE_CCACHE=ON` 9. Now press Return -# Building project +## Building project You must also install game files to be able to run the built version, see [Installation on macOS](players/Installation_macOS.md). -## From Xcode IDE +### From Xcode IDE Open `VCMI.xcodeproj` from the build directory, select `vcmiclient` scheme and hit Run (Cmd+R). To build Launcher, select `vcmilauncher` scheme instead. -## From command line +### From command line `cmake --build ` - If using Makefiles generator, you'd want to utilize all your CPU cores by appending `-- -j$(sysctl -n hw.ncpu)` to the above - If using Xcode generator, you can also choose which configuration to build by appending `--config ` to the above, for example: `--config Debug` -# Packaging project into DMG file +## Packaging project into DMG file After building, run `cpack` from the build directory. If using Xcode generator, also pass `-C ` with the same configuration that you used to build the project. If you use Conan, it's expected that you use **conan-generated** directory at step 4 of [Conan package manager](Conan.md). -# Running VCMI +## Running VCMI You can run VCMI from DMG, but it's will also work from your IDE be it Xcode or Qt Creator. @@ -105,7 +105,7 @@ Alternatively you can run binaries directly from the **bin** directory: CMake include commands to copy all needed assets from source directory into the **bin** directory on each build. They'll work when you build from Xcode too. -# Some useful debugging tips +## Some useful debugging tips Anyone who might want to debug builds, but new to macOS could find following commands useful: @@ -114,6 +114,6 @@ Anyone who might want to debug builds, but new to macOS could find following com - To view dependency paths: `otool -L /Volumes/vcmi-1.0/VCMI.app/Contents/MacOS/vcmiclient` - To display load commands such as `LC_RPATH`: `otool -l /Volumes/vcmi-1.0/VCMI.app/Contents/MacOS/vcmiclient` -# Troubleshooting +## Troubleshooting In case of troubles you can always consult our CI build scripts or contact the dev team via slack. diff --git a/docs/maintainers/Release_Process.md b/docs/maintainers/Release_Process.md index fb0d2b4d5..eaa6108e0 100644 --- a/docs/maintainers/Release_Process.md +++ b/docs/maintainers/Release_Process.md @@ -1,15 +1,15 @@ -# Versioning +## Versioning For releases VCMI uses version numbering in form "1.X.Y", where: - 'X' indicates major release. Different major versions are generally not compatible with each other. Save format is different, network protocol is different, mod format likely different. - 'Y' indicates hotfix release. Despite its name this is usually not urgent, but planned release. Different hotfixes for same major version are fully compatible with each other. -# Branches +## Branches Our branching strategy is very similar to GitFlow: - `master` branch has release commits. One commit - one release. Each release commit should be tagged with version `1.X.Y` when corresponding version is released. State of master branch represents state of latest public release. - `beta` branch is for stabilization of ongoing release. Beta branch is created when new major release enters stabilization stage and is used for both major release itself as well as for subsequent hotfixes. Only changes that are safe, have minimal chance of regressions and improve player experience should be targeted into this branch. Breaking changes (e.g. save format changes) are forbidden in beta. - `develop` branch is a main branch for ongoing development. Pull requests with new features should be targeted to this branch, `develop` version is one major release ahead of `beta`. -# Release process step-by-step +## Release process step-by-step ### Initial release setup (major releases only) Should be done immediately after start of stabilization stage for previous release diff --git a/docs/modders/Animation_Format.md b/docs/modders/Animation_Format.md index f1d6b0351..a4a0d9896 100644 --- a/docs/modders/Animation_Format.md +++ b/docs/modders/Animation_Format.md @@ -4,7 +4,7 @@ VCMI allows overriding HoMM3 .def files with .json replacement. Compared to .def - 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 +## Format description ``` javascript { @@ -51,9 +51,9 @@ VCMI allows overriding HoMM3 .def files with .json replacement. Compared to .def } ``` -# Examples +## Examples -## Replacing a button +### Replacing a button This json file will allow replacing .def file for a button with png images. Buttons require following images: 1. Active state. Button is active and can be pressed by player @@ -74,7 +74,7 @@ This json file will allow replacing .def file for a button with png images. Butt } ``` -## Replacing simple animation +### Replacing simple animation This json file allows defining one animation sequence, for example for adventure map objects or for town buildings. @@ -98,11 +98,11 @@ This json file allows defining one animation sequence, for example for adventure } ``` -## Replacing creature animation +### Replacing creature animation TODO -# Creature animation groups +## Creature animation groups Animation for creatures consist from multiple groups, with each group representing one specific animation. VCMI uses groups as follows: diff --git a/docs/modders/Bonus/Bonus_Range_Types.md b/docs/modders/Bonus/Bonus_Range_Types.md index 89af9d748..447632847 100644 --- a/docs/modders/Bonus/Bonus_Range_Types.md +++ b/docs/modders/Bonus/Bonus_Range_Types.md @@ -1,4 +1,4 @@ -# List of all Bonus range types +## List of all Bonus range types - NO_LIMIT - ONLY_DISTANCE_FIGHT diff --git a/docs/modders/Bonus/Bonus_Sources.md b/docs/modders/Bonus/Bonus_Sources.md index 4c18b6e8a..44fd6ed10 100644 --- a/docs/modders/Bonus/Bonus_Sources.md +++ b/docs/modders/Bonus/Bonus_Sources.md @@ -1,4 +1,4 @@ -# List of all possible bonus sources +## List of all possible bonus sources - ARTIFACT - ARTIFACT_INSTANCE diff --git a/docs/modders/Bonus/Bonus_Types.md b/docs/modders/Bonus/Bonus_Types.md index bc558a6c7..8232599b5 100644 --- a/docs/modders/Bonus/Bonus_Types.md +++ b/docs/modders/Bonus/Bonus_Types.md @@ -1,6 +1,6 @@ The bonuses were grouped according to their original purpose. The bonus system allows them to propagate freely betwen the nodes, however they may not be recognized properly beyond the scope of original use. -# General-purpose bonuses +## General-purpose bonuses ### NONE @@ -31,7 +31,7 @@ On each turn, hides area in fog of war around affected town for all players othe - val: radius in tiles -# Player bonuses +## Player bonuses Intended to be setup as global effect, AI cheat etc. @@ -49,7 +49,7 @@ Bonus that does not account for propagation and gives extra resources per day wi - subtype: resource identifier - val: - base resource amount to be multipled times number of owned towns -# Hero bonuses +## Hero bonuses ### MOVEMENT @@ -287,7 +287,7 @@ Allows creature being upgraded to another creature (Gelu, Dracon) - subtype: identifier of creature that can being upgraded - addInfo: identifier of creature to which perform an upgrade -# Artifact bonuses +## Artifact bonuses ### SPELL_DURATION @@ -362,7 +362,7 @@ Heroes affected by this bonus will not lose all movement points when embarking o Heroes affected by this bonus won't lose army when moving through whirlpool -# Creature bonuses +## Creature bonuses ### STACK_HEALTH @@ -392,7 +392,7 @@ Increases starting amount of shots that unit has in battle - val: additional shots -# Creature abilities +## Creature abilities ## Static abilities and immunities @@ -898,7 +898,7 @@ Affected unit is immune to all spells of a specified spell school Affected unit can be affected by all friendly spells even it would be normally immune to such spell. -# Spell effects +## Spell effects ### POISON @@ -954,7 +954,7 @@ Affected unit is considered to be hypnotized and will be controlled by enemy pla Affected unit will never retaliate to an attack (Blind, Paralyze) -# Others +## Others ### NEGATIVE_EFFECTS_IMMUNITY diff --git a/docs/modders/Bonus/Bonus_Updaters.md b/docs/modders/Bonus/Bonus_Updaters.md index 5c7e441b7..d8a33b6de 100644 --- a/docs/modders/Bonus/Bonus_Updaters.md +++ b/docs/modders/Bonus/Bonus_Updaters.md @@ -1,7 +1,5 @@ TODO: this page may be incorrect or outdated -# List of Bonus Updaters - Updaters come in two forms: simple and complex. Simple updaters take no parameters and are specified as strings. Complex updaters do take parameters (sometimes optional), and are specified as structs. diff --git a/docs/modders/Bonus/Bonus_Value_Types.md b/docs/modders/Bonus/Bonus_Value_Types.md index 184a14062..f33be82c4 100644 --- a/docs/modders/Bonus/Bonus_Value_Types.md +++ b/docs/modders/Bonus/Bonus_Value_Types.md @@ -11,7 +11,7 @@ Total value of Bonus is calculated using the following: Semantics of INDEPENDENT_MAX and INDEPENDENT_MIN are wrapped, and first means than bonus total value will be at least INDEPENDENT_MAX, and second means than bonus value will be at most INDEPENDENT_MIN. -# List of all bonus value types +## List of all bonus value types - ADDITIVE_VALUE - BASE_NUMBER diff --git a/docs/modders/Configurable_Widgets.md b/docs/modders/Configurable_Widgets.md index a453b9d66..0649b866b 100644 --- a/docs/modders/Configurable_Widgets.md +++ b/docs/modders/Configurable_Widgets.md @@ -1,15 +1,3 @@ -# Table of contents - -- [Introduction](#introduction) -- [Tutorial](#tutorial) -- [Documentation](#documentation) - - [Types](#types) - - [Configurable objects](#configurable-objects) - - [Basic widgets](#basic-widgets) - - [High-level widgets](#high-level-widgets) - - [Custom widgets](#custom-widgets) -- [For developers](#for-developers) - # Introduction VCMI has capabilities to change some UI elements in your mods beyond only replacing one image with another. Not all UI elements are possible to modify currently, but development team is expanding them. diff --git a/docs/modders/Entities_Format/Biome_Format.md b/docs/modders/Entities_Format/Biome_Format.md index 6d9141784..de1bb5830 100644 --- a/docs/modders/Entities_Format/Biome_Format.md +++ b/docs/modders/Entities_Format/Biome_Format.md @@ -1,4 +1,4 @@ -# General description +## General description Biome is a new entity type added in VCMI 1.5.0. It defines a set of random map obstacles which will be generated together. For each zone different obstacle sets is randomized and then only obstacles from that set will be used to fill this zone. @@ -19,13 +19,13 @@ If not enough biomes are defined for [terrain type](Terrain_Format.md), map gene } ``` -## List of possible types +### List of possible types Possible object types: `mountain`, `tree`, `lake`, `crater`, `rock`, `plant`, `structure`, `animal`, `other`. Use your best judgement, ie. mushrooms are classified as plants and animal bones are classified as animals. Template Ids are keys used in [Map Objects](../Map_Object_Format.md) -## Algorithm +### Algorithm Currently algorithm picks randomly: diff --git a/docs/modders/Entities_Format/Spell_Format.md b/docs/modders/Entities_Format/Spell_Format.md index d2b710514..32d68afa0 100644 --- a/docs/modders/Entities_Format/Spell_Format.md +++ b/docs/modders/Entities_Format/Spell_Format.md @@ -1,4 +1,4 @@ -# Main format +## Main format ``` javascript { @@ -144,7 +144,7 @@ } ``` -# Animation format +## Animation format TODO @@ -163,11 +163,11 @@ TODO } ``` -# Spell level base format +## 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 +### Example This will make spell affect single target on all levels except expert, where it is massive spell. @@ -180,7 +180,7 @@ This will make spell affect single target on all levels except expert, where it } ``` -# Spell level format +## Spell level format TODO @@ -242,15 +242,15 @@ TODO } ``` -# Configurable battle effects +## Configurable battle effects **If spell have at least one special effect it become configurable spell and spell configuration processed different way** -## Configurable spell +### 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 +### Special effect common format TODO @@ -271,7 +271,7 @@ TODO } ``` -## catapult +### Catapult TODO @@ -290,7 +290,7 @@ TODO } ``` -## Clone +### Clone TODO @@ -306,7 +306,7 @@ Configurable version of Clone spell. } ``` -## Damage effect +### Damage effect TODO @@ -325,35 +325,35 @@ If effect is automatic, spell behave like offensive spell (uses power, levelPowe } ``` -## Dispel +### Dispel TODO -## Heal +### Heal TODO -## Obstacle +### Obstacle TODO -## Remove obstacle +### Remove obstacle TODO -## Sacrifice +### Sacrifice TODO -## Summon +### Summon TODO -## Teleport +### Teleport TODO -## Timed +### Timed TODO @@ -374,9 +374,9 @@ cumulativeEffects ignored) } ``` -# Additional documentation +## Additional documentation -## Targets, ranges, modifiers +### Targets, ranges, modifiers TODO diff --git a/docs/modders/Map_Objects/Market.md b/docs/modders/Map_Objects/Market.md index 751711783..3861db879 100644 --- a/docs/modders/Map_Objects/Market.md +++ b/docs/modders/Map_Objects/Market.md @@ -1,4 +1,4 @@ -# Market schema +## Market schema Since VCMI-1.3 it's possible to create customizable markets on adventure map. Markets can be added as any other object with special handler called "market". @@ -28,7 +28,7 @@ Here is schema describing such object } ``` -# Modes +## Modes Mode parameter defines a way to exchange different entities. Multiple modes can be specified to support several types of exchange. Following options are supported: @@ -73,7 +73,7 @@ Game logic prohibits using modes unavailable for faction "modes" : ["creature-experience", "artifact-experience"] ``` -# Offer +## Offer This field allows to configure specific items available in the market. It can be used only for `resource-skill` mode diff --git a/docs/modders/Map_Objects/Rewardable.md b/docs/modders/Map_Objects/Rewardable.md index ade882337..571401a70 100644 --- a/docs/modders/Map_Objects/Rewardable.md +++ b/docs/modders/Map_Objects/Rewardable.md @@ -1,34 +1,3 @@ -## Table of Contents -- [Base object definition](#base-object-definition) -- [Configurable object definition](#configurable-object-definition) -- [Base object definition](#base-object-definition) -- [Variables Parameters definition](#variables-parameters-definition) -- [Reset Parameters definition](#reset-parameters-definition) -- [Appear Chance definition](#appear-chance-definition) -- [Configurable Properties](#configurable-properties) -- - [Current Day](#current-day) -- - [Resource](#resource) -- - [Experience](#experience) -- - [Hero Level](#hero-level) -- - [Mana Points](#mana-points) -- - [Mana Percentage](#mana-percentage) -- - [Movement Points](#movement-points) -- - [Movement Percentage](#movement-percentage) -- - [Primary Skills](#primary-skills) -- - [Secondary Skills](#secondary-skills) -- - [Can learn skills](#can-learn-skills) -- - [Bonus System](#bonus-system) -- - [Artifacts](#artifacts) -- - [Spells](#spells) -- - [Can learn spells](#can-learn-spells) -- - [Creatures](#creatures) -- - [Creatures Change](#creatures-change) -- - [Spell cast](#spell-cast) -- - [Fog of War](#fog-of-war) -- - [Player color](#player-color) -- - [Hero types](#hero-types) -- - [Hero classes](#hero-classes) - ## Base object definition Rewardable object is defined similarly to other objects, with key difference being `handler`. This field must be set to `"handler" : "configurable"` in order for vcmi to use this mode. ```jsonc diff --git a/docs/modders/Readme.md b/docs/modders/Readme.md index 130d7a086..33dee4330 100644 --- a/docs/modders/Readme.md +++ b/docs/modders/Readme.md @@ -1,4 +1,4 @@ -# Creating mod +## Creating mod To make your own mod you need to create subdirectory in **/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** @@ -157,16 +157,16 @@ Example: replacing single icon } ``` -# Publishing mods in VCMI Repository +## Publishing mods in VCMI Repository This will allow players to install mods directly from VCMI Launcher without visiting any 3rd-party sites. -## Where files are hosted +### 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? +### Why Git / GitHub? It's solve a lot of problems: @@ -176,13 +176,13 @@ It's solve a lot of problems: - 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 +### 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 into vcmi-mods organization +### 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 diff --git a/docs/modders/Translations.md b/docs/modders/Translations.md index 4d41781b2..76c6b8801 100644 --- a/docs/modders/Translations.md +++ b/docs/modders/Translations.md @@ -1,5 +1,3 @@ -# Translation system - ## List of currently supported languages This is list of all languages that are currently supported by VCMI. If your languages is missing from the list and you wish to translate VCMI - please contact our team and we'll add support for your language in next release. @@ -85,6 +83,7 @@ Translation of Map Editor is identical, except for location of translation files TODO: how to test translation locally ### Translation of Linux specific files + #### Translation of AppStream metainfo The [AppStream](https://freedesktop.org/software/appstream/docs/chap-Metadata.html) [metainfo file](https://github.com/vcmi/vcmi/blob/develop/launcher/eu.vcmi.VCMI.metainfo.xml) is used for Linux software centers. @@ -94,11 +93,11 @@ It can be translated using a text editor or using [jdAppStreamEdit](https://flat - Open `/launcher/eu.vcmi.VCMI.metainfo.xml` - Translate and save the file -#### Desktop file +##### Desktop file - Edit `/launcher/vcmilauncher.desktop` and `/launcher/vcmieditor.desktop` - Add `GenericName[xyz]` and `Comment[xyz]` with your language code and translation -### Translation of Android Launcher +##### Translation of Android Launcher - Copy `/android/vcmi-app/src/main/res/values/strings.xml` to `/android/vcmi-app/src/main/res/values-xyz/strings.xml` (`xyz` is your language code) - Translate this file @@ -147,7 +146,7 @@ After you have exported translation and added mod information for your language, Use any text editor (Notepad++ is recommended for Windows) and translate all strings from this file to your language -# Developers documentation +## Developers documentation ### Adding new languages In order to add new language it needs to be added in multiple locations in source code: diff --git a/docs/players/Bug_Reporting_Guidelines.md b/docs/players/Bug_Reporting_Guidelines.md index 4c13d26db..1ca939e36 100644 --- a/docs/players/Bug_Reporting_Guidelines.md +++ b/docs/players/Bug_Reporting_Guidelines.md @@ -1,6 +1,6 @@ First of all, thanks for your support! If you report a bug we can fix it. But keep in mind that reporting your bugs appropriately makes our (developers') lifes easier. Here are a few guidelines that will help you write good bug reports. -# Github bugtracker +## Github bugtracker The main place for managing and reporting bugs is [our bugtracker](https://github.com/vcmi/vcmi/issues). When you are not logged in, you can only browse already reported bugs. To be able to report bugs you need to make an account there. diff --git a/docs/players/Cheat_Codes.md b/docs/players/Cheat_Codes.md index 87260463a..b8d8c6387 100644 --- a/docs/players/Cheat_Codes.md +++ b/docs/players/Cheat_Codes.md @@ -1,11 +1,9 @@ -# Cheat Codes +## Cheat Codes Similar to H3, VCMI provides cheat codes to make testing game more convenient. To use cheat code, press `Tab` key or click/tap on status bar to open game chat and enter code. Most cheat codes have several alternative names, including name of this cheat code in H3:SoD -## List of Cheat Codes - ### Spells `nwcthereisnospoon` or `vcmiistari` or `vcmispells` - give a spell book, all spells and 999 mana to currently selected hero @@ -103,7 +101,7 @@ Following commands can be used by any player in multiplayer: - - `!vote simturns abort` - abort simultaneous turns once this turn ends - - `!vote timer prolong X` - prolong base timer for all players by specified number of seconds -# Client Commands +## Client Commands Client commands are set of predefined commands that are supported by VCMI, but unlike cheats they perform utility actions that do not alter state of the gameplay. As of release 1.2 client commands can work by typing them in-game like cheats, preceded by symbol / (for example `/controlai blue`) diff --git a/docs/players/Game_Mechanics.md b/docs/players/Game_Mechanics.md index 75b948609..059f4d45e 100644 --- a/docs/players/Game_Mechanics.md +++ b/docs/players/Game_Mechanics.md @@ -1,6 +1,6 @@ -# List of features added in VCMI +## List of features added in VCMI -## High resolutions +### High resolutions VCMI supports resolutions higher than original game, which ran only in 800 x 600. It also allows a number of additional features: @@ -10,7 +10,7 @@ VCMI supports resolutions higher than original game, which ran only in 800 x 600 Assets from Heroes of Might & Magic III HD - Remake released by Ubisoft in 2015 - are **not** supported. -## Extended engine limits +### Extended engine limits Some of game features have already been extended in comparison to Shadow of Death: @@ -23,9 +23,9 @@ Some of game features have already been extended in comparison to Shadow of Deat The list of implemented cheat codes and console commands is [here](Cheat_codes.md). -# New mechanics (Optional) +## New mechanics (Optional) -## Stack Experience module +### Stack Experience module VCMI natively suppoorts stack experience feature known from WoG. Any creature - old or modded - can get stack experience bonuses. However, this feature needs to be enabled as a part of WoG VCMI submod. @@ -35,23 +35,23 @@ Stack experience interface has been merged with regular creature window. Among o - 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. - [Stack Artifact](#stack-artifact-module). You can choose enabled artifact with arrow buttons. There is also additional button below to pass currently selected artifact back to hero. -## Commanders module +### Commanders module VCMI offers native support for Commanders. Commanders are part of WoG mod for VCMI and require it to be enabled. However, once this is done, any new faction can use its own Commander, too. -## Mithril module +### Mithril module VCMI natively supports Mithril resource known from WoG. However, it is not currently used by any mod. -## Stack Artifact module +### Stack Artifact module In original WoG, there is one available Stack Artifact - Warlord's Banner, which is related directly to stack experience. VCMI natively supports any number of Stack Artifacts regardless if of Stack Experience module is enabled or not. However, currently no mods make use of this feature and it hasn't been tested for many years. -# List of bugs fixed in VCMI +## List of bugs fixed in VCMI These bugs were present in original Shadow of Death game, however the team decided to fix them to bring back desired behaviour: -## List of game mechanics changes +### List of game mechanics changes Some of H3 mechanics can't be straight considered as bug, but default VCMI behaviour is different: @@ -59,9 +59,7 @@ Some of H3 mechanics can't be straight considered as bug, but default VCMI behav - Battles. Hero that won battle, but only have temporary summoned creatures alive going to appear in tavern like if he retreated. - Battles. Spells from artifacts like AOTD are autocasted on beginning of the battle, not beginning of turn. -# List of extended GUI features - -## Adventure map +## Adventure map features ### New Shortcuts @@ -88,7 +86,7 @@ When hovering cursor over neutral stack on adventure map, you may notice additio Some windows and dialogs now display extra info and images to make game more accessible for new players. This can be turned off, if desired. -## Battles +## Battles features ### Stack Queue @@ -161,15 +159,15 @@ Additional color are supported for text fields (e.g. map description). Uses HTML This is green -# Multiplayer +## Multiplayer features Opening new Turn Option menu in scenario selection dialog allows detailed configuration of turn timers and simultaneous turns -## Turn Timers +### Turn Timers TODO -## Simultaneous turns +### Simultaneous turns Simultaneous turns allow multiple players to act at the same time, speeding up early game phase in multiplayer games. During this phase if different players (allies or not) attempt to interact with each other, such as capture objects owned by other players (mines, dwellings, towns) or attack their heroes, game will block such actions. Interaction with same map objects at the same time, such as attacking same wandering monster is also blocked. @@ -178,8 +176,6 @@ Following options can be used to configure simultaneous turns: - Maximal duration (at most for): this is duration after which simultaneous turns will end unconditionally, even if players still have not contacted each other. However if contact detection discovers contact between two players, simultaneous turns between them might end before specified duration. - Simultaneous turns for AI: If this option is on, AI can act at the same time as human players. Note that AI shares settings for simultaneous turns with human players - if no simultaneous turns have been set up this option has no effect. -### Contact detection - While simultaneous turns are active, VCMI tracks contacts for each pair of player separately. Players are considered to be "in contact" if movement range of their heroes at the start of turn overlaps, or, in other words - if their heroes can meet on this turn if both walk towards each other. When calculating movement range, game uses rules similar to standard movement range calculation in vcmi, meaning that game will track movement through monoliths and subterranean gates, but will not account for any removable obstacles, such as pickable treasures that block path between heroes. Any existing wandering monsters that block path between heroes are ignored for range calculation. At the moment, game will not account for any ways to extend movement range - Dimension Door or Town Portal spells, visiting map objects such as Stables, releasing heroes from prisons, etc. @@ -192,11 +188,11 @@ Game performs contact detection once per turn, at the very start of each in-game Once maximal duration of simultaneous turns (as specified during scenario setup) has been reached, or if all players are in contact with each other, game will return to standard turn order: red, blue, brown, green... -### Differences compared to HD Mod version +Differences compared to HD Mod version: - In VCMI, players can see actions of other players immediately (provided that they have revealed fog of war) instead of waiting for next turn - In VCMI, attempt to attack hero of another player during simultaneous turns will be blocked instead of reloading save from start of turn like in HD Mod -# Manuals and guides +## Manuals and guides - https://heroes.thelazy.net/index.php/Main_Page Wiki that aims to be a complete reference to Heroes of Might and Magic III. diff --git a/docs/players/Installation_Linux.md b/docs/players/Installation_Linux.md index ae777857d..02f2e18c2 100644 --- a/docs/players/Installation_Linux.md +++ b/docs/players/Installation_Linux.md @@ -2,9 +2,7 @@ VCMI requires data from original Heroes 3: Shadow of Death or Complete editions. # Step 1: Binaries installation -## Ubuntu - -### Latest stable build from PPA (recommended) +### Ubuntu - Latest stable build from PPA (recommended) Up-to-date releases can be found in our PPA here: @@ -15,7 +13,7 @@ To install VCMI from PPA use: sudo apt install vcmi ``` -### Unstable testing build from PPA +### Ubuntu - Unstable testing build from PPA We also provide latest, unstable builds mostly suitable for testing here: @@ -25,7 +23,7 @@ In order to install from this PPA use: sudo apt update sudo apt install vcmi ``` -### From Ubuntu repository +### Ubuntu - From Ubuntu repository VCMI stable builds available in "multiverse" repository. Learn how to enable it in [Ubuntu wiki](https://help.ubuntu.com/community/Repositories/Ubuntu). Once enabled, you can install VCMI using Ubuntu Store or in terminal using following commands: @@ -35,7 +33,7 @@ Once enabled, you can install VCMI using Ubuntu Store or in terminal using follo ``` Note that version available in Ubuntu is outdated. Install via PPA is preferred. -## Debian +### Debian Stable VCMI version is available in "contrib" repository. Learn how to enable it in [Debian wiki](https://wiki.debian.org/SourcesList). To install VCMI from repository: @@ -43,14 +41,14 @@ To install VCMI from repository: sudo apt-get update sudo apt-get install vcmi ``` -## Flatpak (distribution-agnostic) +### Flatpak (distribution-agnostic) Latest public release build can be installed via Flatpak. Depending on your distribution, you may need to install flatpak itself. You can find guide for your distribution here: Once you have flatpak, you can install VCMI package which can be found here: -## Other distributions +### Other distributions For other distributions, VCMI can be installed from 3rd-party repositories listed below. Note that these repositories are not supported by vcmi team and may not be up to date. @@ -59,15 +57,15 @@ For other distributions, VCMI can be installed from 3rd-party repositories liste If you are interested in providing builds for other distributions, please let us know. -## Compiling from source +### Compiling from source Please check following developer guide: [How to build VCMI (Linux)](../developers/Building_Linux.md) -# Step 2: Installing Heroes III data files +## Step 2: Installing Heroes III data files To install VCMI you will need Heroes III: Shadow of Death or Complete edition. -## Install data using vcmibuilder script +### Install data using vcmibuilder script Recommended for non-Flatpak installs. @@ -91,7 +89,7 @@ On flatpak install, it's also possible to run the script, but any path seems to flatpak run --command=vcmibuilder eu.vcmi.VCMI --data /path/to/h3/data` ``` -## Install data using gog.com offline installer +### Install data using gog.com offline installer Download both files for the "offline backup game installers" and extract them using innoextract tool @@ -105,19 +103,19 @@ innoextract --output-dir=~/Downloads/HoMM3 "setup_heroes_of_might_and_magic_3_co Once innoextract completes, start VCMI Launcher and choose to place existing files. Select the ~/Downloads/HoMM3 directory. Once placing is complete, you can delete both offline installer files as well as ~/Downloads/HoMM3. -## Install manually using existing Heroes III data +### Install manually using existing Heroes III data Copy "Data", "Maps" and "Mp3" from Heroes III to `$HOME/.local/share/vcmi/` Or, in case of flatpak install to `$HOME/.var/app/eu.vcmi.VCMI/data/vcmi/` On some distributions $XDG_DATA_HOME could differ so instead you may need to use: `$XDG_DATA_HOME/vcmi/` -# Step 3: Launching game +## Step 3: Launching game VCMI should be available via desktop environment menu or launcher (Games/Strategy/VCMI) To start the game type in console: `vcmilauncher` Or, to start game directly avoiding Launcher: `vcmiclient` -# Reporting bugs +## Reporting bugs Please report any issues with packages according to [Bug Reporting Guidelines](Bug_Reporting_Guidelines.md) diff --git a/docs/players/Installation_Windows.md b/docs/players/Installation_Windows.md index 3968052e4..06c0e86ea 100644 --- a/docs/players/Installation_Windows.md +++ b/docs/players/Installation_Windows.md @@ -1,8 +1,8 @@ -# Prerequisites +## Prerequisites As of VCMI 1.2 and newer Windows 10 or newer is required since our automated system uses elements incompatible with older Windows. -# Step 1: Download and install VCMI +## Step 1: Download and install VCMI Install one of following into new folder, same as when installing new game: @@ -10,7 +10,7 @@ Install one of following into new folder, same as when installing new game: - Daily builds (unstable): - Please report about problems on GitHub: [Bug Tracker](https://github.com/vcmi/vcmi/issues) -# Step 2: Installing Heroes III data files +## Step 2: Installing Heroes III data files **Since VCMI 1.2 you can skip this step, just run VCMI launcher and it will help you with importing H3 data. For older releases you can follow this step.** @@ -19,7 +19,7 @@ Install one of following into new folder, same as when installing new game: Create this folder if it doesnt exist yet -# Step 3: connect to the mod repository +## Step 3: connect to the mod repository - If that's your first installation, connection to the mod repository will be configured automatically, you'll see mods available to install from VCMI launcher - - We recommend you to install VCMI extras to support various helpful UI tweaks diff --git a/docs/players/Installation_macOS.md b/docs/players/Installation_macOS.md index 13a30f2f6..f550d6e94 100644 --- a/docs/players/Installation_macOS.md +++ b/docs/players/Installation_macOS.md @@ -1,6 +1,6 @@ -**For iOS installation look here: (Installation on iOS)[Installation_iOS.md] +For iOS installation look here: (Installation on iOS)[Installation_iOS.md] -# Step 1: Download and install VCMI +## Step 1: Download and install VCMI - The latest release (recommended): - Daily builds (might be unstable) @@ -11,7 +11,7 @@ If the app doesn't open, right-click the app bundle - select *Open* menu item - Please report about gameplay problem on forums: [Help & Bugs](https://forum.vcmi.eu/c/international-board/help-bugs) Make sure to specify what hardware and macOS version you use. -# Step 2: Installing Heroes III data files +## Step 2: Installing Heroes III data files ### Step 2.a: Installing data files with GOG offline installer