games/vcmi
1
0
Fork 0
mirror of https://github.com/vcmi/vcmi.git synced 2025-08-15 20:03:15 +02:00
Code Issues Releases Activity

Updated user docs

Browse Source
This commit is contained in:
Ivan Savenko
2023-08-25 13:02:01 +03:00
parent 6cbc0b6a1f
commit 489faef604
16 changed files with 428 additions and 1008 deletions
Download Patch File Download Diff File Expand all files Collapse all files

92
docs/Readme.md
View File

@@ -22,69 +22,55 @@ Loading saves made with different major version of VCMI is usually **not** suppo
Please see corresponding installation guide articles for details for your platform. Please see corresponding installation guide articles for details for your platform.
## Installation guides ## Installation guides
- [Windows](players/Installation_Windows.md)
To use VCMI you need to own original data files. - [macOS](players/Installation_macOS.md)
- [Linux](players/Installation_Linux.md)
* [Android](https://wiki.vcmi.eu/Installation_on_Android) - [Android](players/Installation_Android.md)
* [Linux](https://wiki.vcmi.eu/Installation_on_Linux) - [iOS](players/Installation_iOS.md)
* [macOS](https://wiki.vcmi.eu/Installation_on_macOS)
* [Windows](https://wiki.vcmi.eu/Installation_on_Windows)
* [iOS](https://wiki.vcmi.eu/Installation_on_iOS)
## Documentation and guidelines for players ## Documentation and guidelines for players
- [General information about VCMI Project](VCMI "wikilink") - [General information about VCMI Project](players/Manual.md)
- [Frequently asked questions](Frequently_asked_questions "wikilink") - [Frequently asked questions](https://vcmi.eu/faq/)
- [Engine features](Engine_features "wikilink") - [Game mechanics](players/Game_Mechanics.md)
- [Game mechanics](Game_mechanics "wikilink")
- [Bug reporting guidelines](players/Bug_Reporting_Guidelines.md) - [Bug reporting guidelines](players/Bug_Reporting_Guidelines.md)
- [Mod list](Mod_list "wikilink") - [Cheat codes](players/Cheat_Codes.md)
- [Cheat codes](Cheat_Codes.md) - [Cheat codes](players/Client_Commands.md)
- [Cheat codes](Client_Commands.md) - [Privacy Policy](players/Privacy_Policy.md)
### Installation guides
- [Windows](Installation_on_Windows "wikilink")
- [macOS](Installation_on_macOS "wikilink")
- [Linux](Installation_on_Linux "wikilink")
- [Android](Installation_on_Android "wikilink")
- [iOS](Installation_on_iOS "wikilink")
## Documentation and guidelines for game modders ## Documentation and guidelines for game modders
- [Modding guidelines](Modding_guidelines "wikilink") - [Modding guidelines](Modding_guidelines "wikilink")
- [Mods repository](Mods_repository "wikilink") - [Mods repository](Mods_repository "wikilink")
- Formats: - Formats:
- [Mod file Format](Mod_file_Format "wikilink") - [Mod file Format](Mod_file_Format "wikilink")
- [Town Format](Town_Format "wikilink") - [Town Format](Town_Format "wikilink")
- [Hero Classes Format](Hero_Classes_Format "wikilink") - [Hero Classes Format](Hero_Classes_Format "wikilink")
- [Hero Format](Hero_Format "wikilink") - [Hero Format](Hero_Format "wikilink")
- [Creature Format](Creature_Format "wikilink") - [Creature Format](Creature_Format "wikilink")
- [Artifact Format](Artifact_Format "wikilink") - [Artifact Format](Artifact_Format "wikilink")
- [Animation Format](Animation_Format "wikilink") - [Animation Format](Animation_Format "wikilink")
- [Bonus Format](Bonus_Format "wikilink") - [Bonus Format](Bonus_Format "wikilink")
- [Object Format](Object_Format "wikilink") - [Object Format](Object_Format "wikilink")
- [Spell Format](Spell_Format "wikilink") - [Spell Format](Spell_Format "wikilink")
- [Skill Format](Skill_Format "wikilink") - [Skill Format](Skill_Format "wikilink")
## Documentation and guidelines for developers ## Documentation and guidelines for developers
- How to build using CMake: - How to build using CMake:
- [Linux](How_to_build_VCMI_(Linux) "wikilink") - [Linux](How_to_build_VCMI_(Linux) "wikilink")
- [Linux/MinGW (for - [Linux/MinGW (for
Windows)](How_to_build_VCMI_(Linux/MinGW) "wikilink") Windows)](How_to_build_VCMI_(Linux/MinGW) "wikilink")
- [macOS](How_to_build_VCMI_(macOS) "wikilink") - [macOS](How_to_build_VCMI_(macOS) "wikilink")
- [Windows](How_to_build_VCMI_(Windows/Vcpkg) "wikilink") - [Windows](How_to_build_VCMI_(Windows/Vcpkg) "wikilink")
- [iOS](How_to_build_VCMI_(iOS) "wikilink") - [iOS](How_to_build_VCMI_(iOS) "wikilink")
- [ Android](How_to_build_VCMI_(Android) "wikilink") - [ Android](How_to_build_VCMI_(Android) "wikilink")
- Unsupported build instructions: - Unsupported build instructions:
- [Windows/MSVS (Visual Studio - [Windows/MSVS (Visual Studio 2015)](How_to_build_VCMI_(Windows/Visual_Studio_2015) "wikilink")
2015)](How_to_build_VCMI_(Windows/Visual_Studio_2015) "wikilink") - [Coding guidelines](Coding_guidelines "wikilink")
- [Coding guidelines](Coding_guidelines "wikilink") - [Code structure](Code_structure "wikilink")
- [Code structure](Code_structure "wikilink") - [Logging API](Logging_API "wikilink")
- [Logging API](Logging_API "wikilink") - [Development with Qt Creator](Development_with_Qt_Creator "wikilink")
- Development environment guides:
- [Development with Qt
Creator](Development_with_Qt_Creator "wikilink")
## Documentation and guidelines for maintainers ## Documentation and guidelines for maintainers

239
docs/modders/Modding_Guidelines.md
View File

@@ -1,46 +1,31 @@
If you just want to play see [mod list](mod_list "wikilink"). If you just want to play see [mod list](mod_list "wikilink").
## Creating mod # Creating mod
To make your own mod you need to create subdirectory in 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.
**<data dir>/Mods/** with name that will be used as identifier for your Main mod is file called **mod.json** and should be placed into main folder of your mod, e.g. **Mods/myMod/mod.json**
mod. All content of your mod should go into **Content** directory, e.g. **Mods/myMod/Content/**. Alternatively, it is possible to replace this directory with single .zip archive.
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: Example of how directory structure of your mod may look like:
```
Mods/ Mods/
myMod/ myMod/
mod.json mod.json
Content/ Content/
data/ - unorganized files, mostly bitmap images (.bmp, .png, .pcx)
config/ - json configuration files config/ - json configuration files
data/ - unorganized files, mostly bitmap images (.bmp, .png, .pcx)
maps/ - h3m maps added or modified by mod maps/ - h3m maps added or modified by mod
music/ - music files. Mp3 is fully supported, ogg may be added if needed music/ - music files. Mp3 and ogg/vorbis are supported
sounds/ - sound files, in wav format. sounds/ - sound files, in wav format.
sprites/ - animation, image sets (H3 .def files or VCMI .json files) sprites/ - animation, image sets (H3 .def files or VCMI .json files)
video/ - video files, .bik or .smk video/ - video files, .bik or .smk
```
## Updating mod to next version of VCMI
See [Modding changelog](Modding_changelog "wikilink")
## Creating mod file ## Creating mod file
All VCMI configuration files use [JSON All VCMI configuration files use [JSON format](http://en.wikipedia.org/wiki/Json) so you may want to familiarize yourself with it first.
format](http://en.wikipedia.org/wiki/Json) so you may want to 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.
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: Minimalistic version of this file:
``` javascript ``` javascript
@@ -50,187 +35,105 @@ Minimalistic version of this file:
} }
``` ```
See [Mod file Format](Mod_file_Format "wikilink") for its full See [Mod file Format](Mod_file_Format "wikilink") for its full description.
description.
## Adding new objects
(TODO)
## Modifying existing objects
(TODO)
## Overriding graphical files from Heroes III ## Overriding graphical files from Heroes III
Any graphical replacer mods fall under this category. In VCMI directory 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.
**<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. 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
Note that replacing files from archives requires placing them into This includes archives added by expansions (e.g. **H3ab_bmp.lod** uses same rules as **H3Bitmap.lod**)
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 ### Replacing .def animation files
Heroes III uses custom format for storing animation: def files. These 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.
files are used to store all in-game animations as well as for some GUI 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:
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 one (or several) icons in set
- Replacing animation with fully-colored 32-bit images - 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.
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 Example: replacing single icon
``` javascript ``` javascript
{ {
// List of replaced images // List of replaced images
"images" : "images" :
[ // Index of replaced frame [
{ "frame" : 0, "file" : "HPS000KN.bmp"} {
//name of file that will be used as replacement "frame" : 0, // Index of replaced frame
"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 # Publishing mods in VCMI Repository
mod.
## Packaging mod into archive This will allow players to install mods directly from VCMI Launcher without visiting any 3rd-party sites.
For distribution it is recommended to package mod into .zip archives. To ## Where files are hosted
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 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.
<modname>.zip/ <- Zip archive with high compression ratio ## Why Git / GitHub?
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: It's solve a lot of problems:
- Go to Mods/<modname>/Content directory - Engine developers get control over all mods and can easily update them without adding extra burden for modders / mod maintainers.
- Select all files in this directory and create archive with following - With tools such as [GitHub Desktop](https://desktop.github.com/) it's easy for non-programmers to contribute.
parameters: - 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.
- Archive name: Content.zip - 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.
- Format: ZIP - GitHub also create ZIP archives for us so mods will be stored uncompressed and version can be identified by commit hash.
- 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 ## On backward compatibility
## Releasing mods 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.
Right now there are 3 ways to bring your mod to players: ## Getting into vcmi-mods organization
- Manual download 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.
- VCMI Repository Link to our mod will looks like that: https://github.com/vcmi-mods/adventure-ai-trace
- Private repository
### Manual download ## Rules of repository
You can upload mod into some online file hosting and add link with ### Allowed name for mod identifier
description of your mod into [mod list](mod_list "wikilink").
Note: Avoid using services that require registration or remove files For sanity reasons mod identifier must only contain lower-case English characters, numbers and hyphens.
after certain period of time (examples are Wikisend and 4shared).
Instead you may use any of the services listed below:
- [MediaFire](http://mediafire.com) my-mod-name
- [Dropbox](https://dropbox.com) 2000-new-maps
- [Google Drive](https://drive.google.com)
- Any other service that does not has aforementioned problems
### VCMI Repository Sub-mods can be named as you like, but we strongly encourage everyone to use proper identifiers for them as well.
Another option is to add mod into VCMI repository. This will allow ### Rewriting History
players to install mods directly from VCMI Launcher without visiting any
3rd-party sites.
Check for more details in [Mods repository](Mods_repository "wikilink"). 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.
### Private repository ## Submitting mods to repository
It it also possible to create your own repository. To do this you need Once mod ready for general public maintainer to make PR to [vcmi-mods-repository](https://github.com/vcmi/vcmi-mods-repository).
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 ## Requirements
almost instantly and on the same level of integration with VCMI as mods
from VCMI repository.
To create empty repository you need to: Right now main requirements for a mod to be accepted into VCMI mods list are:
- Create directory that will contain repository - Mod must be complete. For work-in-progress mods it is better to use other way of distribution.
- Create file named "repository.json" in it - 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)
To add mods into such repository you need to: - Music files must be in Ogg/Vorbis format (\*.ogg extension)
- 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
View File

@@ -1,99 +0,0 @@
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)

61
docs/modders/Spell_Format.md
View File

@@ -153,14 +153,11 @@
# Spell level base format # Spell level base format
Json object with data common for all levels can be put here. These 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.
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, This will make spell affect single target on all levels except expert, where it is massive spell.
where it is massive spell.
``` javascript ``` javascript
@@ -239,14 +236,11 @@ where it is massive spell.
# Configurable battle effects # Configurable battle effects
**If spell have at least one special effect it become configurable spell **If spell have at least one special effect it become configurable spell and spell configuration processed different way**
and spell configuration processed different way**
## Configurable spell ## Configurable spell
Configurable spells ignore *offensive* flag, *effects* and Configurable spells ignore *offensive* flag, *effects* and *cumulativeEffects*. For backward compatibility *offensive* flag define Damage effect, *effects* and *cumulativeEffects* define Timed effect.
*cumulativeEffects*. For backward compatibility *offensive* flag define
Damage effect, *effects* and *cumulativeEffects* define Timed effect.
## Special effect common format ## Special effect common format
@@ -300,8 +294,7 @@ Configurable version of Clone spell.
## Damage effect ## Damage effect
If effect is automatic, spell behave like offensive spell (uses power, If effect is automatic, spell behave like offensive spell (uses power, levelPower etc)
levelPower etc)
``` javascript ``` javascript
@@ -367,34 +360,22 @@ cumulativeEffects ignored)
## Targets, ranges, modifiers ## Targets, ranges, modifiers
- CREATURE target (only battle spells) - CREATURE target (only battle spells)
- range 0: smart assumed single creature target - range 0: smart assumed single creature target
- range "X" + smart modifier = enchanter casting, expert massive - range "X" + smart modifier = enchanter casting, expert massive spells
spells - range "X" + no smart modifier = armageddon, death ripple, destroy undead
- range "X" + no smart modifier = armageddon, death ripple, - any other range (including chain effect)
destroy undead - smart modifier: smth like cloud of confusion in H4 (if I remember correctly :) )
- any other range (including chain effect) - no smart modifier: like inferno, fireball etc. but target only creature
- 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)
- NO_TARGET - LOCATION
- no target selection,(abilities, most adventure spells) - 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
- LOCATION - range X: all obstacles
- 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

8
docs/players/Game_Mechanics.md
View File

@@ -21,10 +21,10 @@ These bugs were present in original Shadow of Death game, however the team decid
Some of H3 mechanics can't be straight considered as bug, but default VCMI behaviour is different: Some of H3 mechanics can't be straight considered as bug, but default VCMI behaviour is different:
- Pathfinding. Hero can't grab artifact while flying when all tiles around it are guarded without triggering attack from guard. - Pathfinding. Hero can't grab artifact while flying when all tiles around it are guarded without triggering attack from guard.
- Battles. Hero that won battle, but only have temporary summoned creatures alive going to appear in tavern like if he retreated. - 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. - Battles. Spells from artifacts like AOTD are autocasted on beginning of the battle, not beginning of turn.
- Spells. Dimension Door spell doesn't allow to teleport to unexplored tiles. - Spells. Dimension Door spell doesn't allow to teleport to unexplored tiles.
# List of extended game functionality # List of extended game functionality

63
docs/players/Installation on Android.md
View File

@@ -1,63 +0,0 @@
# Download and install VCMI
**This app requires original heroes 3 sod / complete files to operate,
they are not supplied with this installer. it is recommended to purchase
version from gog.com. Heroes 3 "hd edition" (steam version) files are
not supported !!!**
Installation is a two step process, at first you need to install game,
then you need to upload Heroes3 original data files into your android
device.
- Latest release on Google Play (recommended):
<https://play.google.com/store/apps/details?id=is.xyz.vcmi>
- Latest release as .apk file:
<https://github.com/vcmi/vcmi/releases/latest>
- Daily builds (unstable):
<https://builds.vcmi.download/branch/develop/Android/>
# Installing Heroes III data files
- Install Heroes III on your PC or extract Heroes III data files from
gog installer
<!-- -->
- Connect your device to PC and enable file transfer.
<!-- -->
- Copy "Data", "Maps" and "Mp3" from Heroes III to any folder on
mobile device, then open VCMI, select Heroes III data import option,
then select the folder where you copied Heroes III data.
# Troubleshooting / well known issues
## The game crashes on start
**Please double check that you copied original SoD/Complete game files
into your Android Device**
## I installed google play version, but have a problem while installing daily builds
**Solution:** Uninstall google play version first, before installing
daily build version.
## I installed play version, but the screen is flashing / blank on its edges
**Solution:** Should be fixed since VCMI 1.3
## The game always starts in 800x600 resolution, cannot effectively change it, also there is a lot of blank space on my widescreen device
**Solution:** Should be fixed since VCMI 1.3 onwards.
If you use version 1.2 or older - please download "VCMI-extras" mod from
VCMI Launcher. Resolution setting 1024x600 is better than original
800x600 for widescreen mobile phones.
## Other problems
- Please report about gameplay problem on forums: [Help &
Bugs](https://forum.vcmi.eu/c/international-board/help-bugs) or
[Discord](https://discord.gg/chBT42V)
Make sure to specify your device and used version of Android.

158
docs/players/Installation on Linux.md
View File

@@ -1,158 +0,0 @@
VCMI requires data from original Heroes 3: Shadow of Death or Complete
editions. Data from native Linux version made by LOKI will not work.
# Binaries installation
## Ubuntu
**Latest stable build from PPA (recommended)**
Up-to-date releases can be found in our PPA here:
<https://launchpad.net/~vcmi/+archive/ubuntu/ppa>
To install VCMI from PPA use:
sudo apt-add-repository ppa:vcmi/ppa
sudo apt update
sudo apt install vcmi
**Unstable testing build from PPA**
We also provide latest, unstable builds mostly suitable for testing
here: <https://launchpad.net/~vcmi/+archive/ubuntu/vcmi-latest>
In order to install from this PPA use:
sudo add-apt-repository ppa:vcmi/vcmi-latest
sudo apt update
sudo apt install vcmi
**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:
sudo apt update
sudo apt install vcmi
Note that version available in Ubuntu is outdated. Install via PPA is
preferred.
## 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:
sudo apt-get update
sudo apt-get install vcmi
## 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:
<https://www.flatpak.org/setup/>
Once you have flatpak, you can install VCMI package which can be found
here: <https://flathub.org/apps/details/eu.vcmi.VCMI>
## 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.
- Archlinux [vcmi](https://aur.archlinux.org/packages/vcmi/)
[vcmi-git](https://aur.archlinux.org/packages/vcmi-git/)
- openSUSE [1 Click
Install](https://software.opensuse.org/download.html?project=games&package=vcmi)
If you are interested in providing builds for other distributions,
please let us know.
## Compiling from source
Please check following developer guide: [How to build VCMI
(Linux)](How_to_build_VCMI_(Linux) "wikilink")
# Installing Heroes III data files
To install VCMI you will need Heroes III: Shadow of Death or Complete
edition.
## Install data using vcmibuilder script (recommended for non-Flatpak installs)
To install Heroes 3 data using automated script you need any of:
- Offline Installer downloaded from gog.com (both .exe and .bin files
are required)
- Directory with preinstalled game
- One or two CD's or CD images
Run the script using options appropriate to your input files:
vcmibuilder --cd1 /path/to/iso/or/cd --cd2 /path/to/second/cd
vcmibuilder --gog /path/to/gog.com/installer.exe
vcmibuilder --data /path/to/h3/data
You should use only one of these commands.
On flatpak install, it's also possible to run the script, but any path
seems to be interpreted from within the Flatpak sandbox:
flatpak run --command=vcmibuilder eu.vcmi.VCMI --data /path/to/h3/data`
## Install data using gog.com offline installer
Download both files for the "offline backup game installers" and extract
them using innoextract tool
innoextract --output-dir=~/Downloads/HoMM3 "setup_heroes_of_might_and_magic_3_complete_4.0_(28740).exe"
(note that installer file name might be different)
Once innoextract completes, start VCMI Launcher and choose to copy
existing files. Select the ~/Downloads/HoMM3 directory. Once copy is
complete, you can delete both offline installer files as well as
~/Downloads/HoMM3.
## Install 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/
# Launching game
To start the game type in console:
vcmilauncher
Or, to start game directly avoiding Launcher:
vcmiclient
VCMI should be also available via desktop environment menu or launcher
(Games/Strategy/VCMI)
# Reporting bugs
Please report any issues with packages according to [Bug reporting
guidelines](http://wiki.vcmi.eu/index.php?title=Bug_reporting_guidelines)

51
docs/players/Installation on Windows.md
View File

@@ -1,51 +0,0 @@
# Step 1: Download and install VCMI
Install one of following into new folder, same as when installing new
game:
- Latest release (recommended):
<https://github.com/vcmi/vcmi/releases/latest>
- Daily builds (unstable):
<https://builds.vcmi.download/branch/develop/Windows/>
- Please report about problems on GitHub: [Bug
Tracker](https://github.com/vcmi/vcmi/issues)
# 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.**
- Install Heroes III from disk or using GOG installer.
<!-- -->
- Copy "Data", "Maps" and "Mp3" from Heroes III to:
<!-- -->
%USERPROFILE%\Documents\My Games\vcmi\
Create this folder if it doesnt exist yet
# Step 3: (for release 1.0.0 and above) 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 and (before 1.3) support for different screen
resolutions
# Step 3: (for old builds 0.99 and earlier) download and copy and enable Essential Package
- Skip this step if you installed 1.0.0 or latest daily build
- For some technical reasons it wasn't included in game installation
package for legacy versions and needs to be downloaded and activated
seperately
- Download "VCMI essential files mods" from here
<https://wiki.vcmi.eu/Mod_list#Utilities>
- After unpacking, copy folder Mods to your main VCMI directory
- When launching game, please enable "VCMI essential files" as well as
its sub-elements: Andruids Bonus Icons, Bonus Icons, Spell Immunity
bonus icons, Extra resolutions and Default templates.

98
docs/players/Installation on iOS.md
View File

@@ -1,98 +0,0 @@
You can run VCMI on iOS 12.0 and later, all devices are supported. If
you wish to run on iOS 10 or 11, you should build from source, see [How
to build VCMI (iOS)](How_to_build_VCMI_(iOS) "wikilink").
## Download and install VCMI
The latest release (recommended):
<https://github.com/vcmi/vcmi/releases/latest>
Daily builds: <https://builds.vcmi.download/branch/develop/iOS/>
To run on a non-jailbroken device you need to sign the IPA file, you
have the following options:
- *\[Easiest way\]* [AltStore](https://altstore.io/) or
[Sideloadly](https://sideloadly.io/) - can be installed on Windows
or macOS, don't require dealing with signing on your own
- if you're on iOS 14.0-15.4.1, you can try
<https://github.com/opa334/TrollStore>
- Get signer tool
[here](https://dantheman827.github.io/ios-app-signer/) and a guide
[here](https://forum.kodi.tv/showthread.php?tid=245978) (it's for
Kodi, but the logic is the same). Signing with this app can only be
done on macOS.
- [Create signing assets on macOS from
terminal](https://github.com/kambala-decapitator/xcode-auto-signing-assets).
In the command replace `your.bundle.id` with something like
`com.MY-NAME.vcmi`. After that use the above signer tool.
- [Sign from any
OS](https://github.com/indygreg/PyOxidizer/tree/main/tugger-code-signing).
You'd still need to find a way to create signing assets (private key
and provisioning profile) though.
## Installing Heroes III data files
*Note: if you don't need in-game videos, you can omit
downloading/copying file VIDEO.VID from data folder - it will save your
time and space. The same applies to the Mp3 directory.*
### Installing data files with Finder or Windows explorer
To play the game, you need to upload HoMM3 data files - **Data**,
**Maps** and **Mp3** directories - to the device. Use Finder (or iTunes,
if you're on Windows or your macOS is 10.14 or earlier) for that. You
can also add various [mods](https://wiki.vcmi.eu/Mod_list) by uploading
**Mods** directory. Follow [official Apple
guide](https://support.apple.com/en-us/HT210598) and place files into
VCMI app. Unfortunately, Finder doesn't display copy progress, give it
about 10 minutes to finish.
### Installing data files using iOS device only
If you have data somewhere on device or in shared folder or you have
downloaded it, you can copy it directly on your iPhone/iPad using Files
application.
Just move/copy **Data**, **Maps** and **Mp3** folders into vcmi
application - it will be visible in Files along with other applications'
folders.
### Installing data files with Xcode on macOS
You can also upload files with Xcode. You need to prepare "container"
for that.
1. Connect your device to your Mac
2. Start Xcode
3. Open Devices and Simulators window: Cmd+Shift+2 or Menu - Window -
Devices and Simulators
4. Select your device
5. Select VCMI
6. In the bottom find "three dots" or "cogwheel" button (it should be
next to + - buttons) - click it - select Download Container...
7. Place the game directories inside the downloaded container -
AppData - Documents
8. Click the "three dots" / "cogwheel" button in Xcode again - Replace
Container... - select the downloaded container
9. Wait until Xcode finishes copying, progress is visible (although it
might be "indefinite")
## Game controls
- Tap = left click
- Tap and hold (long press) = right click
- before v1.3: Pinch with 2 fingers = spacebar (visit current object)
- Tap in the bottom area (status bar) to activate chat/console in the
game
You can start game directly (avoiding the launcher) by changing setting
in iOS Settings app - VCMI.
## Reporting bugs
- Please report about gameplay problem on forums: [Help &
Bugs](https://forum.vcmi.eu/c/international-board/help-bugs)
- Please report iOS-specific issues in [this forum
thread](https://forum.vcmi.eu/t/ios-port/820) or (better) at
[GitHub](https://github.com/vcmi/vcmi/issues) with **iOS** label

50
docs/players/Installation on macOS.md
View File

@@ -1,50 +0,0 @@
**For iOS installation look here:
<https://wiki.vcmi.eu/Installation_on_iOS>**
# Download and install VCMI
- The latest release (recommended):
<https://github.com/vcmi/vcmi/releases/latest>
- Daily builds (might be unstable)
- Intel (x86_64) builds:
<https://builds.vcmi.download/branch/develop/macOS/intel>
- Apple Silicon (arm64) builds:
<https://builds.vcmi.download/branch/develop/macOS/arm>
If the app doesn't open, right-click the app bundle - select *Open* menu
item - press *Open* button.
Please report about gameplay problem on forums: [Help &
Bugs](https://forum.vcmi.eu/c/international-board/help-bugs)
If your problem is Mac-specific: DMG corrupted or if it doesn't start
please use following topic:
- [VCMI for macOS](https://forum.vcmi.eu/t/macos-builds/550)
Make sure to specify what hardware and macOS version you use.
# Installing Heroes III data files
1. Find a way to unpack Windows Heroes III or GOG installer. For
example, use `vcmibuilder` script inside app bundle or install the
game with [CrossOver](https://www.codeweavers.com/crossover) /
[Wineskin](https://github.com/Gcenx/WineskinServer).
2. Copy (or symlink) **Data**, **Maps** and **Mp3** directories from
Heroes III to:
<!-- -->
~/Library/Application\ Support/vcmi/
# Connect to the mod repository (optional)
- 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 different
screen resolutions and active various helpful UI tools
- If you don't see mods available to install, go to settings tab
of the launcher and make sure that you have correct link in
"repositories" text field:
- <https://raw.githubusercontent.com/vcmi/vcmi-mods-repository/de

40
docs/players/Installation_Android.md Normal file
View File

@@ -0,0 +1,40 @@
# Download and install VCMI
**This app requires original heroes 3 sod / complete files to operate, they are not supplied with this installer. it is recommended to purchase version from gog.com. Heroes 3 "hd edition" (steam version) files are not supported !!!**
Installation is a two step process, at first you need to install game, then you need to upload Heroes3 original data files into your android device.
- Latest release on Google Play (recommended): <https://play.google.com/store/apps/details?id=is.xyz.vcmi>
- Latest release as .apk file: <https://github.com/vcmi/vcmi/releases/latest>
- Daily builds (unstable): <https://builds.vcmi.download/branch/develop/Android/>
# Installing Heroes III data files
- Install Heroes III on your PC or extract Heroes III data files from gog installer
- Connect your device to PC and enable file transfer.
- Copy "Data", "Maps" and "Mp3" from Heroes III to any folder on mobile device, then open VCMI, select Heroes III data import option, then select the folder where you copied Heroes III data.
# Troubleshooting / well known issues
### The game crashes on start
**Please double check that you copied original SoD/Complete game files into your Android Device**
### I imported game data files, but music in game is missing
**Solution:** Try to run data import again or copy Mp3 folder from Heroes III manually to Android/data/is.xyz.vcmi/files/vcmi-data/Mp3
### I installed google play version, but have a problem while installing daily builds
**Solution:** Uninstall google play version first, before installing daily build version.
### I installed play version, but the screen is flashing / blank on its edges
**Solution:** Should be fixed since VCMI 1.3
### The game always starts in 800x600 resolution, cannot effectively change it, also there is a lot of blank space on my widescreen device
**Solution:** Should be fixed since VCMI 1.3
## Other problems
Please report about gameplay problem on forums: [Help & Bugs](https://forum.vcmi.eu/c/international-board/help-bugs) or [Discord](https://discord.gg/chBT42V). Make sure to specify your device and used version of Android.

117
docs/players/Installation_Linux.md Normal file
View File

@@ -0,0 +1,117 @@
VCMI requires data from original Heroes 3: Shadow of Death or Complete editions. Data from native Linux version made by LOKI will not work.
# Binaries installation
## Ubuntu
### Latest stable build from PPA (recommended)
Up-to-date releases can be found in our PPA here: <https://launchpad.net/~vcmi/+archive/ubuntu/ppa>
To install VCMI from PPA use:
```
sudo apt-add-repository ppa:vcmi/ppa
sudo apt update
sudo apt install vcmi
```
### Unstable testing build from PPA**
We also provide latest, unstable builds mostly suitable for testing here: <https://launchpad.net/~vcmi/+archive/ubuntu/vcmi-latest>
In order to install from this PPA use:
```
sudo add-apt-repository ppa:vcmi/vcmi-latest
sudo apt update
sudo apt install vcmi
```
### 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:
```
sudo apt update
sudo apt install vcmi
```
Note that version available in Ubuntu is outdated. Install via PPA is preferred.
## 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:
```
sudo apt-get update
sudo apt-get install vcmi
```
## 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: <https://www.flatpak.org/setup/>
Once you have flatpak, you can install VCMI package which can be found here: <https://flathub.org/apps/details/eu.vcmi.VCMI>
## 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.
- Archlinux [vcmi](https://aur.archlinux.org/packages/vcmi/) [vcmi-git](https://aur.archlinux.org/packages/vcmi-git/)
- openSUSE [1 Click Install](https://software.opensuse.org/download.html?project=games&package=vcmi)
If you are interested in providing builds for other distributions, please let us know.
## Compiling from source
Please check following developer guide: [How to build VCMI (Linux)](How_to_build_VCMI_(Linux) "wikilink")
# Installing Heroes III data files
To install VCMI you will need Heroes III: Shadow of Death or Complete edition.
## Install data using vcmibuilder script (recommended for non-Flatpak installs)
To install Heroes 3 data using automated script you need any of:
- Offline Installer downloaded from gog.com (both .exe and .bin files are required)
- Directory with preinstalled game
- One or two CD's or CD images
Run the script using options appropriate to your input files:
```
vcmibuilder --cd1 /path/to/iso/or/cd --cd2 /path/to/second/cd
vcmibuilder --gog /path/to/gog.com/installer.exe
vcmibuilder --data /path/to/h3/data
```
You should use only one of these commands.
On flatpak install, it's also possible to run the script, but any path seems to be interpreted from within the Flatpak sandbox:
```
flatpak run --command=vcmibuilder eu.vcmi.VCMI --data /path/to/h3/data`
```
## Install data using gog.com offline installer
Download both files for the "offline backup game installers" and extract them using innoextract tool
```
innoextract --output-dir=~/Downloads/HoMM3 "setup_heroes_of_might_and_magic_3_complete_4.0_(28740).exe"
```
(note that installer file name might be different)
Once innoextract completes, start VCMI Launcher and choose to copy existing files. Select the ~/Downloads/HoMM3 directory. Once copy is complete, you can delete both offline installer files as well as ~/Downloads/HoMM3.
## Install 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/`
# 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
Please report any issues with packages according to [Bug reporting guidelines](http://wiki.vcmi.eu/index.php?title=Bug_reporting_guidelines)

21
docs/players/Installation_Windows.md Normal file
View File

@@ -0,0 +1,21 @@
# Step 1: Download and install VCMI
Install one of following into new folder, same as when installing new game:
- Latest release (recommended): <https://github.com/vcmi/vcmi/releases/latest>
- Daily builds (unstable): <https://builds.vcmi.download/branch/develop/Windows/>
- Please report about problems on GitHub: [Bug Tracker](https://github.com/vcmi/vcmi/issues)
# 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.**
- Install Heroes III from disk or using GOG installer.
- Copy "Data", "Maps" and "Mp3" from Heroes III to: `Documents\My Games\vcmi\`
Create this folder if it doesnt exist yet
# 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

56
docs/players/Installation_iOS.md Normal file
View File

@@ -0,0 +1,56 @@
You can run VCMI on iOS 12.0 and later, all devices are supported. If you wish to run on iOS 10 or 11, you should build from source, see [How to build VCMI (iOS)](How_to_build_VCMI_(iOS) "wikilink").
## Download and install VCMI
- The latest release (recommended): <https://github.com/vcmi/vcmi/releases/latest>
- Daily builds: <https://builds.vcmi.download/branch/develop/iOS/>
To run on a non-jailbroken device you need to sign the IPA file, you
have the following options:
- *\[Easiest way\]* [AltStore](https://altstore.io/) or [Sideloadly](https://sideloadly.io/) - can be installed on Windows or macOS, don't require dealing with signing on your own
- if you're on iOS 14.0-15.4.1, you can try <https://github.com/opa334/TrollStore>
- Get signer tool [here](https://dantheman827.github.io/ios-app-signer/) and a guide [here](https://forum.kodi.tv/showthread.php?tid=245978) (it's for Kodi, but the logic is the same). Signing with this app can only be done on macOS.
- [Create signing assets on macOS from terminal](https://github.com/kambala-decapitator/xcode-auto-signing-assets). In the command replace `your.bundle.id` with something like `com.MY-NAME.vcmi`. After that use the above signer tool.
- [Sign from any OS](https://github.com/indygreg/PyOxidizer/tree/main/tugger-code-signing). You'd still need to find a way to create signing assets (private key and provisioning profile) though.
## Installing Heroes III data files
*Note: if you don't need in-game videos, you can omit downloading/copying file VIDEO.VID from data folder - it will save your time and space. The same applies to the Mp3 directory.*
### Installing data files with Finder or Windows explorer
To play the game, you need to upload HoMM3 data files - **Data**, **Maps** and **Mp3** directories - to the device. Use Finder (or iTunes, if you're on Windows or your macOS is 10.14 or earlier) for that. You can also add various [mods](https://wiki.vcmi.eu/Mod_list) by uploading **Mods** directory. Follow [official Apple guide](https://support.apple.com/en-us/HT210598) and place files into VCMI app. Unfortunately, Finder doesn't display copy progress, give it about 10 minutes to finish.
### Installing data files using iOS device only
If you have data somewhere on device or in shared folder or you have downloaded it, you can copy it directly on your iPhone/iPad using Files application.
Just move/copy **Data**, **Maps** and **Mp3** folders into vcmi application - it will be visible in Files along with other applications' folders.
### Installing data files with Xcode on macOS
You can also upload files with Xcode. You need to prepare "container" for that.
1. Connect your device to your Mac
2. Start Xcode
3. Open Devices and Simulators window: Cmd+Shift+2 or Menu - Window - Devices and Simulators
4. Select your device
5. Select VCMI
6. In the bottom find "three dots" or "cogwheel" button (it should be next to + - buttons) - click it - select Download Container...
7. Place the game directories inside the downloaded container - AppData - Documents
8. Click the "three dots" / "cogwheel" button in Xcode again - Replace Container... - select the downloaded container
9. Wait until Xcode finishes copying, progress is visible (although it might be "indefinite")
## Game controls
- Tap = left click
- Tap and hold (long press) = right click
- Tap in the bottom area (status bar) to activate chat/console in the game
You can start game directly (avoiding the launcher) by changing setting in iOS Settings app - VCMI.
## Reporting bugs
- Please report about gameplay problem on forums: [Help & Bugs](https://forum.vcmi.eu/c/international-board/help-bugs)
- Please report iOS-specific issues in [this forum thread](https://forum.vcmi.eu/t/ios-port/820) or (better) at [GitHub](https://github.com/vcmi/vcmi/issues) with **iOS** label

18
docs/players/Installation_macOS.md Normal file
View File

@@ -0,0 +1,18 @@
**For iOS installation look here:
<https://wiki.vcmi.eu/Installation_on_iOS>**
# Download and install VCMI
- The latest release (recommended): <https://github.com/vcmi/vcmi/releases/latest>
- Daily builds (might be unstable)
- Intel (x86_64) builds: <https://builds.vcmi.download/branch/develop/macOS/intel>
- Apple Silicon (arm64) builds: <https://builds.vcmi.download/branch/develop/macOS/arm>
If the app doesn't open, right-click the app bundle - select *Open* menu item - press *Open* button.
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.
# Installing Heroes III data files
1. Find a way to unpack Windows Heroes III or GOG installer. For example, use `vcmibuilder` script inside app bundle or install the game with [CrossOver](https://www.codeweavers.com/crossover) or [Wineskin](https://github.com/Gcenx/WineskinServer).
2. Copy (or symlink) **Data**, **Maps** and **Mp3** directories from Heroes III to:`~/Library/Application\ Support/vcmi/`

265
docs/players/Manual.md
View File

@@ -1,47 +1,23 @@
# Introduction # Introduction
The purpose of VCMI project is to rewrite entire HoMM3: WoG engine from 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.
scratch, giving it new and extended possibilities. We are hoping to 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.
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 # Installation
VCMI requires Heroes of Might & Magic 3 complete + WoG 3.58f VCMI requires Heroes of Might & Magic 3 complete installation and will not run properly without their files.
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 ## Windows
To install VCMI, simply unzip downloaded archive to main HoMM3 To install VCMI, simply unzip downloaded archive to main HoMM3 directory. To launch it, click `VCMI_client` icon. Server mode is inactive yet.
directory. To launch it, click `VCMI_client` icon. Server mode is
inactive yet.\
## Linux ## Linux
Visit [Wiki Visit [Wiki article](http://wiki.vcmi.eu/index.php?title=Installation_on_Linux) for Linux packages and installation guidelines.
article](http://wiki.vcmi.eu/index.php?title=Installation_on_Linux) for
Linux packages and installation guidelines.\
# New features # New features
A number of enchancements had been introduced thorough new versions of A number of enchancements had been introduced thorough new versions of VCMI. In this section you can learn about all of them.
VCMI. In this section you can learn about all of them.
## High resolutions ## High resolutions
@@ -75,45 +51,18 @@ In 0.9 new quest log was introduced. It can display info about Seer Hut or Quest
## Attack range ## Attack range
In combat, some creatures, such as Dragon or Cerberi, may attack enemies 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.
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 ## Power rating
When hovering cursor over neutral stack on adventure map, you may notice 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.
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 ## FPS counter
VCMI 0.85 introduces new feature for testing, the FPS counter. To enable VCMI 0.85 introduces new feature for testing, the FPS counter.
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 ## Minor improvements
### Linux directory
In Linux-based sysems, files placed in $\sim$`/.vcmi` directory will
override data files with the same name.
## New controls ## New controls
VCMI introduces several minor improvements and new keybinds in user VCMI introduces several minor improvements and new keybinds in user
@@ -121,145 +70,56 @@ interface.
### Pregame - Scenario / Saved Game list ### Pregame - Scenario / Saved Game list
- Mouse wheel - scroll through the Scenario list. - Mouse wheel - scroll through the Scenario list.
- Home - move to the top of the 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).
- 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 ### Adventure Map
- CTRL + R - Quick restart of current scenario. - CTRL + R - Quick restart of current scenario.
- CTRL + Arrows - scrolls Adventure Map behind an open window. - 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).
- 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 5 - centers view on selected hero.
- NumPad Enter functions same as normal Enter in the game (it didn't in H3).
- 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 ### Miscellaneous
- Numbers for components in selection window - for example Treasure - Numbers for components in selection window - for example Treasure Chest, skill choice dialog and more yet to come.
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).
- Type numbers in the Split Stack screen (for example 25 will split - During Tactics phase, click on any of your stack to instantly activate it. No need to scroll trough entire army anymore.
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 ## Cheat codes
Following cheat codes have been implemented in VCMI. Type them in Following cheat codes have been implemented in VCMI. Type them in console:
console:
- `vcmiistari` - Gives all spells and 999 mana to currently selected
hero
- `vcmiainur` - Gives 5 Archangels to every empty slot of currently
selected hero
- `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 - `vcmiangband` - Gives 10 Black Knights into each slot
- `vcmiarmenelos` - Build all structures in currently selected town - `vcmiarmenelos` - Build all structures in currently selected town
- `vcminoldor` - All war machines - `vcminoldor` - All war machines
- `vcminahar` - 1000000 movement points - `vcminahar` - 1000000 movement points
- `vcmiformenos` - Give resources (100 wood, ore and rare resources and 20000 gold)
- `vcmiformenos` - Give resources (100 wood, ore and rare resources
and 20000 gold)
- `vcmieagles` - Reveals fog of war - `vcmieagles` - Reveals fog of war
- `vcmiglorfindel` - Advances currently selected hero to the next level
- `vcmiglorfindel` - Advances currently selected hero to the next
level
- `vcmisilmaril` - Player wins - `vcmisilmaril` - Player wins
- `vcmimelkor` - Player loses - `vcmimelkor` - Player loses
- `vcmiforgeofnoldorking` - Hero gets all artifacts except spell book, spell scrolls and war machines
- `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.
# Feedback # Feedback
Our project is open and its sources are available for everyone to browse 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.\
and download. We do our best to inform community of Heroes fans with all 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).
the details and development progress. We also look forward to your 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).
comments, support and advice.\ 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.
A good place to start is [VCMI 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.
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.
# FAQ # FAQ
### What does "VCMI" stand for? ### What does "VCMI" stand for?
VCMI is an acronym of the [Quenya](https://en.wikipedia.org/wiki/Quenya) VCMI is an acronym of the [Quenya](https://en.wikipedia.org/wiki/Quenya) phrase "Vinyar Callor Meletya Ingole", meaning "New Heroes of Might and Magic". ([Source](https://forum.vcmi.eu/t/what-vcmi-stands-for/297/4))
phrase "Vinyar Callor Meletya Ingole", meaning "New Heroes of Might and
Magic". ([Source](https://forum.vcmi.eu/t/what-vcmi-stands-for/297/4))
## How to turn off creature queue panel in battles? ## How to turn off creature queue panel in battles?
@@ -267,83 +127,40 @@ Hotkey to switch this panel is "Q"
### Is it possible to add town X to vcmi? ### Is it possible to add town X to vcmi?
This depends on town authors or anyone else willing to port it to vcmi. This depends on town authors or anyone else willing to port it to vcmi. Aim of VCMI is to provide *support* for such features.
Aim of VCMI is to provide *support* for such features.
## When will the final version be released? ## When will the final version be released?
When it is finished, which is another year at least. Exact date is 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.
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? ## Are you going to add / change X?
VCMI recreates basic H3:TSoD + WoG engine and does not add new content VCMI recreates basic H3:SoD + 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.
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? ## Will it be possible to do Y?
Removing engine restrictions and allowing flexible modding of game is 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 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. ## The game is not working, it crashes and I get strange console messages.
Report your bug. Details are described [here](#Feedback). The sooner you 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.
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? ## What is the current status of the project?
Check [Wiki](http://wiki.vcmi.eu/index.php?title=VCMI), [release 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.
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! ## I have a great idea!
Share it on [VCMI forum](http://forum.vcmi.eu/index.php) so all team 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.
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.? ## 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 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.
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? ## Can I help VCMI Project in any way?
If you are C++ programmer, graphican, tester or just have tons of ideas, 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.
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. ## I would like to join development team.
You are always welcome. Contact the core team via [our 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.
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