From 489faef604254b35f50abb1f2ad19063af117ed9 Mon Sep 17 00:00:00 2001 From: Ivan Savenko Date: Fri, 25 Aug 2023 13:02:01 +0300 Subject: [PATCH] Updated user docs --- docs/Readme.md | 92 ++++---- docs/modders/Modding_Guidelines.md | 239 +++++++-------------- docs/modders/Mods_Repository.md | 99 --------- docs/modders/Spell_Format.md | 61 ++---- docs/players/Game_Mechanics.md | 8 +- docs/players/Installation on Android.md | 63 ------ docs/players/Installation on Linux.md | 158 -------------- docs/players/Installation on Windows.md | 51 ----- docs/players/Installation on iOS.md | 98 --------- docs/players/Installation on macOS.md | 50 ----- docs/players/Installation_Android.md | 40 ++++ docs/players/Installation_Linux.md | 117 +++++++++++ docs/players/Installation_Windows.md | 21 ++ docs/players/Installation_iOS.md | 56 +++++ docs/players/Installation_macOS.md | 18 ++ docs/players/Manual.md | 265 ++++-------------------- 16 files changed, 428 insertions(+), 1008 deletions(-) delete mode 100644 docs/modders/Mods_Repository.md delete mode 100644 docs/players/Installation on Android.md delete mode 100644 docs/players/Installation on Linux.md delete mode 100644 docs/players/Installation on Windows.md delete mode 100644 docs/players/Installation on iOS.md delete mode 100644 docs/players/Installation on macOS.md create mode 100644 docs/players/Installation_Android.md create mode 100644 docs/players/Installation_Linux.md create mode 100644 docs/players/Installation_Windows.md create mode 100644 docs/players/Installation_iOS.md create mode 100644 docs/players/Installation_macOS.md diff --git a/docs/Readme.md b/docs/Readme.md index 06caf905e..989b7a7e3 100644 --- a/docs/Readme.md +++ b/docs/Readme.md @@ -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. ## Installation guides - -To use VCMI you need to own original data files. - - * [Android](https://wiki.vcmi.eu/Installation_on_Android) - * [Linux](https://wiki.vcmi.eu/Installation_on_Linux) - * [macOS](https://wiki.vcmi.eu/Installation_on_macOS) - * [Windows](https://wiki.vcmi.eu/Installation_on_Windows) - * [iOS](https://wiki.vcmi.eu/Installation_on_iOS) +- [Windows](players/Installation_Windows.md) +- [macOS](players/Installation_macOS.md) +- [Linux](players/Installation_Linux.md) +- [Android](players/Installation_Android.md) +- [iOS](players/Installation_iOS.md) ## Documentation and guidelines for players -- [General information about VCMI Project](VCMI "wikilink") -- [Frequently asked questions](Frequently_asked_questions "wikilink") -- [Engine features](Engine_features "wikilink") -- [Game mechanics](Game_mechanics "wikilink") +- [General information about VCMI Project](players/Manual.md) +- [Frequently asked questions](https://vcmi.eu/faq/) +- [Game mechanics](players/Game_Mechanics.md) - [Bug reporting guidelines](players/Bug_Reporting_Guidelines.md) -- [Mod list](Mod_list "wikilink") -- [Cheat codes](Cheat_Codes.md) -- [Cheat codes](Client_Commands.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") +- [Cheat codes](players/Cheat_Codes.md) +- [Cheat codes](players/Client_Commands.md) +- [Privacy Policy](players/Privacy_Policy.md) ## Documentation and guidelines for game modders -- [Modding guidelines](Modding_guidelines "wikilink") -- [Mods repository](Mods_repository "wikilink") -- Formats: - - [Mod file Format](Mod_file_Format "wikilink") - - [Town Format](Town_Format "wikilink") - - [Hero Classes Format](Hero_Classes_Format "wikilink") - - [Hero Format](Hero_Format "wikilink") - - [Creature Format](Creature_Format "wikilink") - - [Artifact Format](Artifact_Format "wikilink") - - [Animation Format](Animation_Format "wikilink") - - [Bonus Format](Bonus_Format "wikilink") - - [Object Format](Object_Format "wikilink") - - [Spell Format](Spell_Format "wikilink") - - [Skill Format](Skill_Format "wikilink") +- [Modding guidelines](Modding_guidelines "wikilink") +- [Mods repository](Mods_repository "wikilink") +- Formats: + - [Mod file Format](Mod_file_Format "wikilink") + - [Town Format](Town_Format "wikilink") + - [Hero Classes Format](Hero_Classes_Format "wikilink") + - [Hero Format](Hero_Format "wikilink") + - [Creature Format](Creature_Format "wikilink") + - [Artifact Format](Artifact_Format "wikilink") + - [Animation Format](Animation_Format "wikilink") + - [Bonus Format](Bonus_Format "wikilink") + - [Object Format](Object_Format "wikilink") + - [Spell Format](Spell_Format "wikilink") + - [Skill Format](Skill_Format "wikilink") ## Documentation and guidelines for developers -- How to build using CMake: - - [Linux](How_to_build_VCMI_(Linux) "wikilink") - - [Linux/MinGW (for - Windows)](How_to_build_VCMI_(Linux/MinGW) "wikilink") - - [macOS](How_to_build_VCMI_(macOS) "wikilink") - - [Windows](How_to_build_VCMI_(Windows/Vcpkg) "wikilink") - - [iOS](How_to_build_VCMI_(iOS) "wikilink") - - [ Android](How_to_build_VCMI_(Android) "wikilink") -- Unsupported build instructions: - - [Windows/MSVS (Visual Studio - 2015)](How_to_build_VCMI_(Windows/Visual_Studio_2015) "wikilink") -- [Coding guidelines](Coding_guidelines "wikilink") -- [Code structure](Code_structure "wikilink") -- [Logging API](Logging_API "wikilink") -- Development environment guides: - - [Development with Qt - Creator](Development_with_Qt_Creator "wikilink") +- How to build using CMake: + - [Linux](How_to_build_VCMI_(Linux) "wikilink") + - [Linux/MinGW (for + Windows)](How_to_build_VCMI_(Linux/MinGW) "wikilink") + - [macOS](How_to_build_VCMI_(macOS) "wikilink") + - [Windows](How_to_build_VCMI_(Windows/Vcpkg) "wikilink") + - [iOS](How_to_build_VCMI_(iOS) "wikilink") + - [ Android](How_to_build_VCMI_(Android) "wikilink") +- Unsupported build instructions: + - [Windows/MSVS (Visual Studio 2015)](How_to_build_VCMI_(Windows/Visual_Studio_2015) "wikilink") +- [Coding guidelines](Coding_guidelines "wikilink") +- [Code structure](Code_structure "wikilink") +- [Logging API](Logging_API "wikilink") +- [Development with Qt Creator](Development_with_Qt_Creator "wikilink") ## Documentation and guidelines for maintainers diff --git a/docs/modders/Modding_Guidelines.md b/docs/modders/Modding_Guidelines.md index f87ff898f..615bc77e3 100644 --- a/docs/modders/Modding_Guidelines.md +++ b/docs/modders/Modding_Guidelines.md @@ -1,46 +1,31 @@ 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 -**/Mods/** with name that will be used as identifier for your -mod. - -Main mod is file called **mod.json** and should be placed into main -folder of your mod, e.g. **Mods/myMod/mod.json** - -All content of your mod should go into **Content** directory, e.g. -**Mods/myMod/Content/**. In future it will be possible to replace this -directory with single .zip archive. +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** +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. Example of how directory structure of your mod may look like: +``` Mods/ myMod/ mod.json Content/ - data/ - unorganized files, mostly bitmap images (.bmp, .png, .pcx) config/ - json configuration files + data/ - unorganized files, mostly bitmap images (.bmp, .png, .pcx) 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. sprites/ - animation, image sets (H3 .def files or VCMI .json files) video/ - video files, .bik or .smk - -## Updating mod to next version of VCMI - -See [Modding changelog](Modding_changelog "wikilink") +``` ## Creating mod file -All VCMI configuration files use [JSON -format](http://en.wikipedia.org/wiki/Json) so you may want to -familiarize yourself with it first. - -Mod.json is main file in your mod and must be present in any mod. This -file contains basic description of your mod, dependencies or conflicting -mods (if present), list of new content and so on. - +All VCMI configuration files use [JSON format](http://en.wikipedia.org/wiki/Json) so you may want to familiarize yourself with it first. +Mod.json is main file in your mod and must be present in any mod. This file contains basic description of your mod, dependencies or conflicting mods (if present), list of new content and so on. Minimalistic version of this file: ``` javascript @@ -50,187 +35,105 @@ Minimalistic version of this file: } ``` -See [Mod file Format](Mod_file_Format "wikilink") for its full -description. +See [Mod file Format](Mod_file_Format "wikilink") for its full description. + +## Adding new objects + +(TODO) + +## Modifying existing objects + +(TODO) ## Overriding graphical files from Heroes III -Any graphical replacer mods fall under this category. In VCMI directory -**/Content** acts as mod-specific game root directory. So for -example file **/Content/Data/AISHIELD.PNG** will replace file -with same name from **H3Bitmap.lod** game archive. - +Any graphical replacer mods fall under this category. In VCMI directory **/Content** acts as mod-specific game root directory. So for example file **/Content/Data/AISHIELD.PNG** will replace file with same name from **H3Bitmap.lod** game archive. Any other files can be replaced in exactly same way. +Note that replacing files from archives requires placing them into specific location: +- H3Bitmap.lod -> Data +- H3Sprite.lod -> Sprites +- Heroes3.snd -> Sounds +- Video.vid -> Video -Note that replacing files from archives requires placing them into -specific location: - - H3Bitmap.lod -> Data - H3Sprite.lod -> Sprites - Heroes3.snd -> Sounds - Video.vid -> Video - -This includes archives added by expansions (e.g. **H3ab_bmp.lod** uses -same rules as **H3Bitmap.lod**) +This includes archives added by expansions (e.g. **H3ab_bmp.lod** uses same rules as **H3Bitmap.lod**) ### Replacing .def animation files -Heroes III uses custom format for storing animation: def files. These -files are used to store all in-game animations as well as for some GUI -elements like buttons and for icon sets. - -These files can be replaced by another def file but in some cases -original format can't be used. This includes but not limited to: - +Heroes III uses custom format for storing animation: def files. These files are used to store all in-game animations as well as for some GUI elements like buttons and for icon sets. +These files can be replaced by another def file but in some cases original format can't be used. This includes but not limited to: - Replacing one (or several) icons in set - Replacing animation with fully-colored 32-bit images - -In VCMI these animation files can also be replaced by json description -of their content. See [Animation Format](Animation_Format "wikilink") -for full description of this format. - +In VCMI these animation files can also be replaced by json description of their content. See [Animation Format](Animation_Format "wikilink") for full description of this format. Example: replacing single icon ``` javascript { // List of replaced images - "images" : - [ // Index of replaced frame - { "frame" : 0, "file" : "HPS000KN.bmp"} - //name of file that will be used as replacement + "images" : + [ + { + "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 -mod. +# Publishing mods in VCMI Repository -## 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 -create .zip archive you need to have file archiver like -[7zip](http://www.7-zip.org) +## Where files are hosted -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. - .zip/ <- Zip archive with high compression ratio - modname/ <- Archive contains main mod directory - mod.json <- main mod file - Content.zip/ <- Uncompressed archive with all mod data - Data/ - ... <- Identical to Content directory - Sprites/ +## Why Git / GitHub? -You can create such structure using following instructions: +It's solve a lot of problems: -- Go to Mods//Content directory -- Select all files in this directory and create archive with following - parameters: - - Archive name: Content.zip - - Format: ZIP - - Compression level: None/Store only -- Move created archive into Mods/ directory and remove no - longer needed Content directory. -- Go to Mods/ directory -- Create archive from your mod with following parameters: - - Archive name: .zip - - Format: ZIP - - Compression level: Maximum +- 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. -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 -- VCMI Repository -- Private repository +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 -### Manual download +## Rules of repository -You can upload mod into some online file hosting and add link with -description of your mod into [mod list](mod_list "wikilink"). +### Allowed name for mod identifier -Note: Avoid using services that require registration or remove files -after certain period of time (examples are Wikisend and 4shared). -Instead you may use any of the services listed below: +For sanity reasons mod identifier must only contain lower-case English characters, numbers and hyphens. -- [MediaFire](http://mediafire.com) -- [Dropbox](https://dropbox.com) -- [Google Drive](https://drive.google.com) -- Any other service that does not has aforementioned problems + my-mod-name + 2000-new-maps -### 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 -players to install mods directly from VCMI Launcher without visiting any -3rd-party sites. +### Rewriting History -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 -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). +Once mod ready for general public maintainer to make PR to [vcmi-mods-repository](https://github.com/vcmi/vcmi-mods-repository). -Providing own repository allows you to deliver any new mods or updates -almost instantly and on the same level of integration with VCMI as mods -from VCMI repository. +## Requirements -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 -- Create file named "repository.json" in it - -To add mods into such repository you need to: - -- Copy packaged archive .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 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. \ No newline at end of file +- 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) diff --git a/docs/modders/Mods_Repository.md b/docs/modders/Mods_Repository.md deleted file mode 100644 index 526fca134..000000000 --- a/docs/modders/Mods_Repository.md +++ /dev/null @@ -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) \ No newline at end of file diff --git a/docs/modders/Spell_Format.md b/docs/modders/Spell_Format.md index a028aeaa0..44518b7cc 100644 --- a/docs/modders/Spell_Format.md +++ b/docs/modders/Spell_Format.md @@ -153,14 +153,11 @@ # 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. +Json object with data common for all levels can be put here. These configuration parameters will be default for all levels. All mandatory level fields become optional if they equal "base" configuration. ## Example -This will make spell affect single target on all levels except expert, -where it is massive spell. +This will make spell affect single target on all levels except expert, where it is massive spell. ``` javascript @@ -239,14 +236,11 @@ where it is massive spell. # Configurable battle effects -**If spell have at least one special effect it become configurable spell -and spell configuration processed different way** +**If spell have at least one special effect it become configurable spell and spell configuration processed different way** ## Configurable spell -Configurable spells ignore *offensive* flag, *effects* and -*cumulativeEffects*. For backward compatibility *offensive* flag define -Damage effect, *effects* and *cumulativeEffects* define Timed effect. +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 @@ -300,8 +294,7 @@ Configurable version of Clone spell. ## Damage effect -If effect is automatic, spell behave like offensive spell (uses power, -levelPower etc) +If effect is automatic, spell behave like offensive spell (uses power, levelPower etc) ``` javascript @@ -367,34 +360,22 @@ cumulativeEffects ignored) ## Targets, ranges, modifiers -- CREATURE target (only battle spells) - - range 0: smart assumed single creature target - - range "X" + smart modifier = enchanter casting, expert massive - spells - - range "X" + no smart modifier = armageddon, death ripple, - destroy undead - - any other range (including chain effect) - - smart modifier: smth like cloud of confusion in H4 (if I - remember correctly :) ) - - no smart modifier: like inferno, fireball etc. but target - only creature +- CREATURE target (only battle spells) + - range 0: smart assumed single creature target + - range "X" + smart modifier = enchanter casting, expert massive spells + - range "X" + no smart modifier = armageddon, death ripple, destroy undead + - any other range (including chain effect) + - smart modifier: smth like cloud of confusion in H4 (if I remember correctly :) ) + - no smart modifier: like inferno, fireball etc. but target only creature - +- NO_TARGET + - no target selection,(abilities, most adventure spells) -- NO_TARGET - - no target selection,(abilities, most adventure spells) +- LOCATION + - any tile on map/battlefield (inferno, fireball etc.), DD also here but with special handling + - clearTarget - destination hex must be clear (unused so far) + - clearAfffected - all affected hexes must be clear (forceField, fireWall) - - -- LOCATION - - any tile on map/battlefield (inferno, fireball etc.), DD also - here but with special handling - - clearTarget - destination hex must be clear (unused so far) - - clearAfffected - all affected hexes must be clear (forceField, - fireWall) - - - -- OBSTACLE target - - range 0: any single obstacle - - range X: all obstacles \ No newline at end of file +- OBSTACLE target + - range 0: any single obstacle + - range X: all obstacles \ No newline at end of file diff --git a/docs/players/Game_Mechanics.md b/docs/players/Game_Mechanics.md index c4f21093e..7ebdb1a55 100644 --- a/docs/players/Game_Mechanics.md +++ b/docs/players/Game_Mechanics.md @@ -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: -- 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. 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. +- 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. 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. # List of extended game functionality diff --git a/docs/players/Installation on Android.md b/docs/players/Installation on Android.md deleted file mode 100644 index 0436c517d..000000000 --- a/docs/players/Installation on Android.md +++ /dev/null @@ -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): - -- Latest release as .apk file: - -- Daily builds (unstable): - - -# 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. \ No newline at end of file diff --git a/docs/players/Installation on Linux.md b/docs/players/Installation on Linux.md deleted file mode 100644 index b3772b1ba..000000000 --- a/docs/players/Installation on Linux.md +++ /dev/null @@ -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: - - -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: - -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: - - -Once you have flatpak, you can install VCMI package which can be found -here: - -## 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) \ No newline at end of file diff --git a/docs/players/Installation on Windows.md b/docs/players/Installation on Windows.md deleted file mode 100644 index 89c95d6e7..000000000 --- a/docs/players/Installation on Windows.md +++ /dev/null @@ -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): - -- Daily builds (unstable): - -- 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 - -- 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. \ No newline at end of file diff --git a/docs/players/Installation on iOS.md b/docs/players/Installation on iOS.md deleted file mode 100644 index 5d0073523..000000000 --- a/docs/players/Installation on iOS.md +++ /dev/null @@ -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): - - -Daily builds: - -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 - -- 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 \ No newline at end of file diff --git a/docs/players/Installation on macOS.md b/docs/players/Installation on macOS.md deleted file mode 100644 index 3f15113f6..000000000 --- a/docs/players/Installation on macOS.md +++ /dev/null @@ -1,50 +0,0 @@ -**For iOS installation look here: -** - -# Download and install VCMI - -- The latest release (recommended): - -- Daily builds (might be unstable) - - Intel (x86_64) builds: - - - Apple Silicon (arm64) builds: - - -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: - - +- Latest release as .apk file: +- Daily builds (unstable): + +# 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. \ No newline at end of file diff --git a/docs/players/Installation_Linux.md b/docs/players/Installation_Linux.md new file mode 100644 index 000000000..5fd2b9f29 --- /dev/null +++ b/docs/players/Installation_Linux.md @@ -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: + +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: + +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: +Once you have flatpak, you can install VCMI package which can be found here: + +## 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) \ No newline at end of file diff --git a/docs/players/Installation_Windows.md b/docs/players/Installation_Windows.md new file mode 100644 index 000000000..42fa35209 --- /dev/null +++ b/docs/players/Installation_Windows.md @@ -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): +- Daily builds (unstable): +- 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 diff --git a/docs/players/Installation_iOS.md b/docs/players/Installation_iOS.md new file mode 100644 index 000000000..5fea3bc3d --- /dev/null +++ b/docs/players/Installation_iOS.md @@ -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): +- Daily builds: + +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 +- 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 diff --git a/docs/players/Installation_macOS.md b/docs/players/Installation_macOS.md new file mode 100644 index 000000000..17d38b9ba --- /dev/null +++ b/docs/players/Installation_macOS.md @@ -0,0 +1,18 @@ +**For iOS installation look here: +** + +# Download and install VCMI + +- The latest release (recommended): +- Daily builds (might be unstable) + - Intel (x86_64) builds: + - Apple Silicon (arm64) builds: + +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/` diff --git a/docs/players/Manual.md b/docs/players/Manual.md index 60a111acc..d1d12be8a 100644 --- a/docs/players/Manual.md +++ b/docs/players/Manual.md @@ -1,47 +1,23 @@ # Introduction -The purpose of VCMI project is to rewrite entire HoMM3: WoG engine from -scratch, giving it new and extended possibilities. We are hoping to -support mods and new towns already made by fans, but abandoned because -of game code limitations. -VCMI is a fan-made open-source project in progress. We already allow -support for maps of any sizes, higher resolutions and extended engine -limits. However, although working, the game is not finished. There are -still many features and functionalities to add, both old and brand new. -Learn more about VCMI Project at -[Wiki](http://wiki.vcmi.eu/index.php?title=VCMI).\ -Check [google -docs](http://spreadsheets.google.com/ccc?key=pRhYM0YkAF9lIpLe4raNAWA&hl=pl) -for the list of already implemented objects, spells and artifacts. +The purpose of VCMI project is to rewrite entire HoMM3: WoG engine from scratch, giving it new and extended possibilities. We are hoping to support mods and new towns already made by fans, but abandoned because of game code limitations. +VCMI is a fan-made open-source project in progress. We already allow support for maps of any sizes, higher resolutions and extended engine limits. However, although working, the game is not finished. There are still many features and functionalities to add, both old and brand new. # Installation -VCMI requires Heroes of Might & Magic 3 complete + WoG 3.58f -installation and will not run properly without their files. We strongly -recommend using English version, other languages may cause unexpected -errors or bizarre font glitches.\ -If you don't have Wake of Gods 3.58f yet, click -[here](http://www.maps4heroes.com/heroes3/files/allinone_358f.zip).\ -For English language files, extract [this -package](http://download.vcmi.eu/dataEN.7z) to your `Data` folder.\ -Starting from 0.90, VCMI can be also installed on H3 + ERA setups. +VCMI requires Heroes of Might & Magic 3 complete installation and will not run properly without their files. ## Windows -To install VCMI, simply unzip downloaded archive to main HoMM3 -directory. To launch it, click `VCMI_client` icon. Server mode is -inactive yet.\ +To install VCMI, simply unzip downloaded archive to main HoMM3 directory. To launch it, click `VCMI_client` icon. Server mode is inactive yet. ## Linux -Visit [Wiki -article](http://wiki.vcmi.eu/index.php?title=Installation_on_Linux) for -Linux packages and installation guidelines.\ +Visit [Wiki article](http://wiki.vcmi.eu/index.php?title=Installation_on_Linux) for Linux packages and installation guidelines. # New features -A number of enchancements had been introduced thorough new versions of -VCMI. In this section you can learn about all of them. +A number of enchancements had been introduced thorough new versions of VCMI. In this section you can learn about all of them. ## 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 -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. +In combat, some creatures, such as Dragon or Cerberi, may attack enemies on multiple hexes. All such attacked stacks will be highlighted if the attack cursor is hovered over correct destination tile. Whenever battle stack is hovered, its movement range is highlighted in darker shade. This can help when you try to avoid attacks of melee units. ## Power rating -When hovering cursor over neutral stack on adventure map, you may notice -additional info about relative threat this stack poses to selected hero. -This feature has been introduced in Heroes of Might and Magic V and is -planned to be extended to all kinds of armed objects. -Custom text file is in use, so using localized version of data files -will not change text in your game. It is not a bug, but lack of new -translated files. +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. ## FPS counter -VCMI 0.85 introduces new feature for testing, the FPS counter. To enable -it, edit this line in config/settings.txt file:\ -[`showFPS=0;`]{style="background-color: SpringGreen"}\ -Value of 1 enables simple FPS counter which may be useful to test -graphical performance on mobile platforms. - -## Custom menu graphics - -Since 0.9, it is possible to use any background graphics in main menu. -Open `config/mainmenu.json` file for that reason and edit this line:\ -[`"background" : "background-file-name"`]{style="background-color: SpringGreen"}\ -Place the background file in `Data` folder. +VCMI 0.85 introduces new feature for testing, the FPS counter. ## Minor improvements -### Linux directory - -In Linux-based sysems, files placed in $\sim$`/.vcmi` directory will -override data files with the same name. - ## New controls VCMI introduces several minor improvements and new keybinds in user @@ -121,145 +70,56 @@ interface. ### Pregame - Scenario / Saved Game list -- Mouse wheel - scroll through the Scenario list. - -- Home - move to the top of the list. - -- End - move to the bottom of the list. - -- NumPad keys can be used in the Save Game screen (they didn't work in - H3). +- Mouse wheel - scroll through the Scenario list. +- Home - move to the top of the list. +- End - move to the bottom of the list. +- NumPad keys can be used in the Save Game screen (they didn't work in H3). ### Adventure Map - CTRL + R - Quick restart of current scenario. - - CTRL + Arrows - scrolls Adventure Map behind an open window. - -- CTRL pressed blocks Adventure Map scrolling (it allows us to leave - the application window without losing current focus). - +- CTRL pressed blocks Adventure Map scrolling (it allows us to leave the application window without losing current focus). - NumPad 5 - centers view on selected hero. - -- NumPad Enter functions same as normal Enter in the game (it didn't - in H3). - -### Spellbook - -- ALT + 1-10 or '-' or '=' on main pad - cast 1st to 12th visible - spell - -- ALT + 1-10 or '-' or '+' on NumPad - cast 1st to 12th spell +- NumPad Enter functions same as normal Enter in the game (it didn't in H3). ### Miscellaneous -- Numbers for components in selection window - for example Treasure - Chest, skill choice dialog and more yet to come. - -- Type numbers in the Split Stack screen (for example 25 will split - the stacks as such that there are 25 creatures in the second stack). - -- 'Q' - Toggles the [Stack Queue](#Stack_Queue) display (so it can be - enabled/disabled with single key press). - -- During Tactics phase, click on any of your stack to instantly - activate it. No need to scroll trough entire army anymore. +- Numbers for components in selection window - for example Treasure Chest, skill choice dialog and more yet to come. +- Type numbers in the Split Stack screen (for example 25 will split the stacks as such that there are 25 creatures in the second stack). +- 'Q' - Toggles the [Stack Queue](#Stack_Queue) display (so it can be enabled/disabled with single key press). +- During Tactics phase, click on any of your stack to instantly activate it. No need to scroll trough entire army anymore. ## Cheat codes -Following cheat codes have been implemented in VCMI. Type them in -console: - -- `vcmiistari` - Gives all spells and 999 mana to currently selected - hero - -- `vcmiainur` - Gives 5 Archangels to every empty slot of currently - selected hero +Following cheat codes have been implemented in VCMI. Type them in console: +- `vcmiistari` - Gives all spells and 999 mana to currently selected hero +- `vcmiainur` - Gives 5 Archangels to every empty slot of currently selected hero - `vcmiangband` - Gives 10 Black Knights into each slot - - `vcmiarmenelos` - Build all structures in currently selected town - - `vcminoldor` - All war machines - - `vcminahar` - 1000000 movement points - -- `vcmiformenos` - Give resources (100 wood, ore and rare resources - and 20000 gold) - +- `vcmiformenos` - Give resources (100 wood, ore and rare resources and 20000 gold) - `vcmieagles` - Reveals fog of war - -- `vcmiglorfindel` - Advances currently selected hero to the next - level - +- `vcmiglorfindel` - Advances currently selected hero to the next level - `vcmisilmaril` - Player wins - - `vcmimelkor` - Player loses - -- `vcmiforgeofnoldorking` - Hero gets all artifacts except spell book, - spell scrolls and war machines - -## Command line - -It is possible to save a starting configuration (such as map and -options) in pregame by typing \"`sinfo` filename\". Then VCMI can be -started with option `-i –start=fname` and it will automatically start -the game.\ -`–onlyAI` command line option allows to run AI-on-AI game (without GUI). -Also, typing `onlyai` in pregame triggers that mode. - -# Release notes - -- In 0.89 [Commanders](#Commanders) and [Stack - Artifacts](#Stack_Artifacts) were implemented and enabled by - default. There are four Stack Artifacts available. Their behaviour - has been altered for testing purpose only. - -- [Stack Experience](#Stack_Experience) is enabled by default. It's an - optional feature, but needs complex tesing. Mechanics and tables - from original WoG 3.58f were used for this purpose. Note that not - all of WoG creature abilities are handled. - -- Online game, random map generator as well as some other parts of the - game are not yet implemented. Do not worry if nothing happens when - you click them, please report only actual bugs and game crashes. - -- It is possible to start the campaign, although heroes will not carry - over to subsequent scenarios. +- `vcmiforgeofnoldorking` - Hero gets all artifacts except spell book, spell scrolls and war machines # Feedback -Our project is open and its sources are available for everyone to browse -and download. We do our best to inform community of Heroes fans with all -the details and development progress. We also look forward to your -comments, support and advice.\ -A good place to start is [VCMI -Wiki](http://wiki.vcmi.eu/index.php?title=Main_Page) which contains all -necessary information for developers, testers and the people who would -like to get familiar with our project. If you want to report a bug, use -[Mantis Bugtracker](http://bugs.vcmi.eu/bug_report_advanced_page.php).\ -Make sure the issue is not already mentioned on [the -list](http://bugs.vcmi.eu/view_all_bug_page.php) unless you can provide -additional details for it.\ -Please do not report as bugs features not yet implemented. For proposing -new ideas and requests, visit [our -board](http://forum.vcmi.eu/index.php).\ -VCMI comes with its own bug handlers: the console which prints game log -`(server_log, VCMI_Client_log, VCMI_Server_log)` and memory dump file -(`.dmp`) created on crash on Windows systems. These may be very helpful -when the nature of bug is not obvious, please attach them if necessary.\ -To resolve an issue, we must be able to reproduce it on our computers. -Please put down all circumstances in which a bug occurred and what did -you do before, especially if it happens rarely or is not clearly -visible. The better report, the better chance to track the bug quickly. +Our project is open and its sources are available for everyone to browse and download. We do our best to inform community of Heroes fans with all the details and development progress. We also look forward to your comments, support and advice.\ +A good place to start is [VCMI Wiki](http://wiki.vcmi.eu/index.php?title=Main_Page) which contains all necessary information for developers, testers and the people who would like to get familiar with our project. If you want to report a bug, use [Mantis Bugtracker](http://bugs.vcmi.eu/bug_report_advanced_page.php). +Make sure the issue is not already mentioned on [the list](http://bugs.vcmi.eu/view_all_bug_page.php) unless you can provide additional details for it. Please do not report as bugs features not yet implemented. For proposing new ideas and requests, visit [our board](http://forum.vcmi.eu/index.php). +VCMI comes with its own bug handlers: the console which prints game log `(server_log, VCMI_Client_log, VCMI_Server_log)` and memory dump file (`.dmp`) created on crash on Windows systems. These may be very helpful when the nature of bug is not obvious, please attach them if necessary. +To resolve an issue, we must be able to reproduce it on our computers. Please put down all circumstances in which a bug occurred and what did you do before, especially if it happens rarely or is not clearly visible. The better report, the better chance to track the bug quickly. # FAQ ### What does "VCMI" stand for? -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)) +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)) ## 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? -This depends on town authors or anyone else willing to port it to vcmi. -Aim of VCMI is to provide *support* for such features. +This depends on town authors or anyone else willing to port it to vcmi. Aim of VCMI is to provide *support* for such features. ## When will the final version be released? -When it is finished, which is another year at least. Exact date is -impossible to predict.\ -Development tempo depends mostly on free time of active programmers and -community members, there is no exact shedule. You may expect new version -every three months. Of course, joining the project will speed things up. +When it is finished, which is another year at least. Exact date is impossible to predict. Development tempo depends mostly on free time of active programmers and community members, there is no exact shedule. You may expect new version every three months. Of course, joining the project will speed things up. ## Are you going to add / change X? -VCMI recreates basic H3:TSoD + WoG engine and does not add new content -or modify original mechanics by default. Only engine and interface -improvements are likely to be supported now. The list of possible -features is placed on [Wiki TODO -list](http://wiki.vcmi.eu/index.php?title=TODO_list). If you want -something specific to be done, please present detailed project on [our -board](http://forum.vcmi.eu/index.php). Of course you are free to -contribute with anything you can do. +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. ## Will it be possible to do Y? -Removing engine restrictions and allowing flexible modding of game is -the main aim of the project.\ -As yet modification of game is not supported. +Removing engine restrictions and allowing flexible modding of game is the main aim of the project. As yet modification of game is not supported. ## The game is not working, it crashes and I get strange console messages. -Report your bug. Details are described [here](#Feedback). The sooner you -tell the team about the problem, the sooner it will be resolved. Many -problems come just from improper installation or system settings. +Report your bug. Details are described [here](#Feedback). The sooner you tell the team about the problem, the sooner it will be resolved. Many problems come just from improper installation or system settings. ## What is the current status of the project? -Check [Wiki](http://wiki.vcmi.eu/index.php?title=VCMI), [release -notes](http://forum.vcmi.eu/viewforum.php?f=1) or -[changelog](https://github.com/vcmi/vcmi/blob/develop/ChangeLog). The -best place to watch current changes as they are committed to the develop -branch is the [Github commits -page](https://github.com/vcmi/vcmi/commits/develop). The game is quite -playable by now, although many important features are missing. +Check [Wiki](http://wiki.vcmi.eu/index.php?title=VCMI), [release notes](http://forum.vcmi.eu/viewforum.php?f=1) or [changelog](https://github.com/vcmi/vcmi/blob/develop/ChangeLog). The best place to watch current changes as they are committed to the develop branch is the [Github commits page](https://github.com/vcmi/vcmi/commits/develop). The game is quite playable by now, although many important features are missing. ## I have a great idea! -Share it on [VCMI forum](http://forum.vcmi.eu/index.php) so all team -members can see it and share their thoughts. Remember, brainstorming is -good for your health. +Share it on [VCMI forum](http://forum.vcmi.eu/index.php) so all team members can see it and share their thoughts. Remember, brainstorming is good for your health. ## Are you going to support Horn of The Abyss / Wog 3.59 / Grove Town etc.? -Yes, of course. VCMI is designed as a base for any further mods and uses -own executables, so the compatibility is not an issue. The team is not -going to compete, but to cooperate with the community of creative -modders. - -## I don't like Wake of Gods at all. Can I disable it? - -Most WoG features already implemented are just for testing purposes and -can be disabled in [mod settings](#Mods). +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. ## Can I help VCMI Project in any way? -If you are C++ programmer, graphican, tester or just have tons of ideas, -do not hesistate - your help is needed. The game is huge and many -different ares of activity are still waiting for someone like you. See -[Wiki TODO list](http://wiki.vcmi.eu/index.php?title=TODO_list) for more -info. +If you are C++ programmer, graphican, tester or just have tons of ideas, do not hesistate - your help is needed. The game is huge and many different ares of activity are still waiting for someone like you. See [Wiki TODO list](http://wiki.vcmi.eu/index.php?title=TODO_list) for more info. ## I would like to join development team. -You are always welcome. Contact the core team via [our -board](http://forum.vcmi.eu/index.php). In the meantime, read 'building -VCMI' guide at [Wiki](http://wiki.vcmi.eu/index.php?title=Main_Page).\ -The usual way to join the team is to post your patch for review on our -board. If the patch is positively rated by core team members, you will -be given access to SVN repository. - -# Credits \ No newline at end of file +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.