https://wiki.vcmi.eu/api.php?action=feedcontributions&user=SXX&feedformat=atomVCMI Project Wiki - User contributions [en]2024-03-29T15:28:31ZUser contributionsMediaWiki 1.28.2https://wiki.vcmi.eu/index.php?title=Main_Page&diff=3355Main Page2021-02-16T22:49:08Z<p>SXX: Protected "Main Page" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))</p>
<hr />
<div>__NOTOC__<br />
= Welcome to VCMI Project Wiki =<br />
<br />
[[VCMI]] is an open-source project aiming to reimplement HMM3:WoG and SoD game engines, giving it new and extended possibilities.<br />
<br />
== Latest release ==<br />
As of January 2021, we dont make big official releases anymore, but instead we provide a new version every several days: everytime when there is a new feature finished or new bug fixed.<br/><br />
Although there are no official "big releases", we reccomend updating the game at least twice a year, to make sure you have an updated, best version.<br/><br />
We try not to break savegame files compatibility, so you shouldnt have problem returning to your old games after update.<br/><br />
Please see corresponding "installation on" articles for details for your platform.<br/><br />
<br />
== Documentation and guidelines for users ==<br />
* [[VCMI | General information about VCMI Project]]<br />
* [[Frequently asked questions]]<br />
* [[Engine features]]<br />
* [[Game mechanics]]<br />
* [[Bug reporting guidelines]]<br />
* [[Mod list]]<br />
* [[Cheat codes]]<br />
* [[Installation]] guides:<br />
** [[Installation on Windows|Windows]]<br />
** [[Installation on macOS|macOS]]<br />
** [[Installation on Linux|Linux]]<br />
** [[Installation on Android|Android]]<br />
<br />
== Documentation and guidelines for modders ==<br />
* [[Modding guidelines]]<br />
* [[Mods repository]]<br />
* Formats:<br />
** [[Mod file Format]]<br />
** [[Town Format]]<br />
** [[Hero Classes Format]]<br />
** [[Hero Format]]<br />
** [[Creature Format]]<br />
** [[Artifact Format]]<br />
** [[Animation Format]]<br />
** [[Bonus Format]]<br />
** [[Object Format]]<br />
** [[Spell Format]]<br />
** [[Skill Format]]<br />
<br />
* [[User:AVS/Scripting|Upcoming scripting support]]<br />
<br />
== Documentation and guidelines for developers ==<br />
* How to build using CMake:<br />
** [[How_to_build_VCMI_(Linux)|Linux]]<br />
** [[How_to_build_VCMI_(Linux/Cmake/MXE)|Linux/MXE (for Windows)]]<br />
** [[How_to_build_VCMI_(macOS)|macOS]]<br />
** [[How_to_build_VCMI_(Windows/Vcpkg)|Windows]]<br />
* Unsupported build instructions:<br />
** [[How_to_build_VCMI_(Windows/Visual_Studio_2015)|Windows/MSVS (Visual Studio 2015)]]<br />
* [[Coding guidelines]]<br />
* [[Code structure]]<br />
* [[Logging API]]<br />
* [[Bug tracker usage]]<br />
* [[TODO list]]<br />
* [[Project status]]<br />
* Development environment guides:<br />
** [[Development with Qt Creator]]<br />
<br />
== VCMI Places ==<br />
* [https://vcmi.eu/ Website]<br />
* [https://forum.vcmi.eu/ Forum]<br />
* [https://bugs.vcmi.eu/ Bugtracker]<br />
* [https://slack.vcmi.eu/ Slack invite page]<br />
* [https://github.com/vcmi/vcmi GitHub repository]</div>SXXhttps://wiki.vcmi.eu/index.php?title=Installation_on_Android&diff=3354Installation on Android2021-02-16T22:48:40Z<p>SXX: Protected "Installation on Android" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))</p>
<hr />
<div>= Download and install VCMI =<br />
'''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 !!!'''<br/><br />
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.<br />
<br />
* Newest daily builds: https://builds.vcmi.download/branch/develop/Android/<br />
* Tested daily build (from 21.07.2019): [https://play.google.com/store/apps/details?id=is.xyz.vcmi on Google Play].<br />
Please note that Google Play version, while being a tested and proven one, contains bugs and problems that were fixed in later versions.<br />
<br />
= Installing Heroes III data files =<br />
<br />
* Find a way to unpack Windows Heroes III or GOG installer.<br />
<br />
* Connect your device to PC and enable file transfer.<br />
<br />
* Copy "Data", "Maps" and "Mp3" from Heroes III to:<br />
<pre><br />
<external storage*>/vcmi-data/<br />
</pre><br />
External storage is whatever system returns as "external storage directory", so either actual sdcard, or internal memory if sdcard isn’t available.<br />
<br />
You are not a tech person, and want a videoguide how to do it? see youtube: https://www.youtube.com/watch?v=zGO1I3asquY<br />
<br />
= Troubleshooting / well known issues =<br />
<br />
== The game crashes on start ==<br />
'''Please double check that you copied original SoD/Complete game files into your Android Device'''<br/><br />
Another common cause of crash is when users set resolution higher than their device screen resolution.<br/><br />
For android we recommend to set a rather low resolution anyway, such as 1024x600, as high resolution means elements will be small and will be hard to click and read.<br />
<br />
== I installed google play version, but have a problem while installing daily builds ==<br />
'''Solution:''' Uninstall google play version first, before installing daily build version.<br />
<br />
== I installed play version, but the screen is flashing on its edges ==<br />
'''Solution:''' This problem is fixed in current daily builds. Either install a current daily build, or wait for a new google play version.<br />
<br />
== I use newest daily builds. The game always starts in 800x600 resolution, cannot effectively change it, also there is a lot of blank space on my widescreen device ==<br />
'''Solution:''' Please download "VCMI essential files mods" from here https://wiki.vcmi.eu/Mod_list#Utilities, unpack it and copy Mods folder into vcmi-data that you put original game files.<br/><br />
Resolution setting 1024x600 is better than original 800x600 for widescreen mobile phones.<br />
<br />
== Other problems ==<br />
* Please report about gameplay problem on forums: [https://forum.vcmi.eu/c/international-board/help-bugs Help & Bugs]<br />
<br />
If your problem is Android-specific: APK not installing of game doesn't start please use following topic:<br />
* [https://forum.vcmi.eu/t/vcmi-for-android/784 VCMI for Andoid]<br />
Make sure to specify your device and used version of Android.</div>SXXhttps://wiki.vcmi.eu/index.php?title=Installation_on_Linux&diff=3353Installation on Linux2021-02-16T22:48:33Z<p>SXX: Protected "Installation on Linux" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))</p>
<hr />
<div>VCMI requires data from original Heroes 3: Shadow of Death or Complete editions. Data from native Linux version made by LOKI will not work.<br />
= Binaries installation =<br />
== Ubuntu ==<br />
<br />
VCMI stable builds available in "multiverse" repository. Learn how to enable it in [https://help.ubuntu.com/community/Repositories/Ubuntu Ubuntu wiki].<br />
<br />
VCMI daily builds can be installed from PPA:<br />
* For testing only: https://launchpad.net/~vcmi/+archive/ppa<br />
<br />
To add PPA type in Terminal:<br />
<pre><br />
sudo apt-add-repository ppa:vcmi/ppa<br />
</pre><br />
<br />
To install VCMI from repository:<br />
<pre><br />
sudo apt-get update<br />
sudo apt-get install vcmi<br />
</pre><br />
<br />
== Debian ==<br />
<br />
Stable VCMI version is available in "contrib" repository. Learn how to enable it in [https://wiki.debian.org/SourcesList Debian wiki].<br />
<br />
To install VCMI from repository:<br />
<pre><br />
sudo apt-get update<br />
sudo apt-get install vcmi<br />
</pre><br />
<br />
== Snappy ==<br />
It's possible to install daily VCMI builds as distribution-agnostic Snap package:<br />
<br />
* Visit [https://snapcraft.io/ snapcraft.io] to learn how to get Snappy on your distribution.<br />
* Once it's running install latest VCMI build with:<br />
<pre><br />
sudo snap install --edge vcmi<br />
</pre><br />
* After you can run VCMI with following commands:<br />
<pre><br />
snap run vcmi.vcmilauncher<br />
snap run vcmi.vcmiclient<br />
snap run vcmi.vcmiserver<br />
</pre><br />
* Keep in mind that instead of '''$HOME/.local/share/vcmi/''' you must copy Heroes 3 assets into:<br />
<pre><br />
$HOME/snap/vcmi/current/.local/share/vcmi/<br />
</pre><br />
* To update to latest version:<br />
<pre><br />
sudo snap refresh vcmi<br />
</pre><br />
<br />
'''Warning:''' Snap builds are currently in experimental state.<br />
<br />
Please give your feedback on forum: [https://forum.vcmi.eu/t/experimental-snap-packages-for-linux/4300 Experimental Snap packages for Linux].<br />
<br />
== Other distributions ==<br />
For other distributions, VCMI can be installed from 3rd-party repositories listed below.<br />
* Gentoo https://github.com/qdii/qdiilay/tree/master/games-strategy/vcmi<br />
* Archlinux [https://aur.archlinux.org/packages/vcmi/ vcmi] [https://aur.archlinux.org/packages/vcmi-git/ vcmi-git]<br />
* openSUSE [https://software.opensuse.org/download.html?project=games&package=vcmi 1 Click Install]<br />
If you are interested in providing builds for other distributions, please let us know.<br />
<br />
== Compiling from source ==<br />
Please check following developer guide: [[How to build VCMI (Linux)]]<br />
<br />
= Installing Heroes III data files =<br />
To install VCMI you will need Heroes III: Shadow of Death or Complete edition.<br />
== Automated install ==<br />
To install Heroes 3 data using automated script you need any of:<br />
* One or two CD's or CD images<br />
* gog.com installer<br />
* Directory with installed game<br />
<br />
Run the script using options appropriate to your input files:<br />
<pre><br />
vcmibuilder --cd1 /path/to/iso/or/cd --cd2 /path/to/second/cd<br />
vcmibuilder --gog /path/to/gog.com/installer<br />
vcmibuilder --data /path/to/h3/data<br />
</pre><br />
You should use only one of these commands.<br />
<br />
=== Music on distributions without Mp3 support ===<br />
To have Music support on Fedora it is required to perform a additional step. Fedora doesn't provide Mp3 playback support natively due to patents applied on the Mp3 technique. The SDL_mixer package from the official Fedora repo is compiled without Mp3 support.<br />
<br />
To make music work it must be converted into ogg format. This can be done either manually or using vcmibuilder:<br />
<pre><br />
vcmibuilder --convertMP3<br />
</pre><br />
This command can be run separately after install or as additional switch during initial vcmibuilder launch<br />
<br />
== Manual install ==<br />
<br />
* Install Heroes III in Wine or manually unpack GOG installer.<br />
<br />
* Copy "Data", "Maps" and "Mp3" from Heroes III to:<br />
<pre>/home/$USER/.local/share/vcmi/</pre><br />
On some distributions $XDG_DATA_HOME could differ so instead you may need to use:<br />
<pre>$XDG_DATA_HOME/vcmi/</pre><br />
<br />
= Launching game =<br />
To start the game type in console:<br />
<pre><br />
vcmilauncher<br />
</pre><br />
Or, to start game directly avoiding Launcher:<br />
<pre><br />
vcmiclient<br />
</pre><br />
VCMI should be also available via desktop environment menu or launcher (Games/Strategy/VCMI)<br />
<br />
= Reporting bugs =<br />
Please report any issues with packages according to <br />
[http://wiki.vcmi.eu/index.php?title=Bug_reporting_guidelines Bug reporting guidelines]</div>SXXhttps://wiki.vcmi.eu/index.php?title=Installation_on_macOS&diff=3352Installation on macOS2021-02-16T22:48:27Z<p>SXX: Protected "Installation on macOS" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))</p>
<hr />
<div>= Download and install VCMI =<br />
<br />
* Stable build: not yet available for macOS.<br />
* Daily builds: https://builds.vcmi.download/branch/develop/macOS/<br />
* Please report about gameplay problem on forums: [https://forum.vcmi.eu/c/international-board/help-bugs Help & Bugs]<br />
<br />
If your problem is Mac-specific: DMG corrupted or if it doesn't start please use following topic:<br />
* [https://forum.vcmi.eu/t/macos-builds/550 VCMI for macOS]<br />
Make sure to specify what hardware and macOS version you use.<br />
<br />
= Installing Heroes III data files =<br />
<br />
* Find a way to unpack Windows Heroes III or GOG installer.<br />
<br />
* Copy "Data", "Maps" and "Mp3" from Heroes III to:<br />
<pre><br />
~/Library/Application\ Support/vcmi/<br />
</pre></div>SXXhttps://wiki.vcmi.eu/index.php?title=Installation_on_Windows&diff=3351Installation on Windows2021-02-16T22:48:19Z<p>SXX: Protected "Installation on Windows" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))</p>
<hr />
<div>= Step 1: Download and install VCMI =<br />
<br />
* Daily builds (reccomended): https://builds.vcmi.download/branch/develop/Windows/<br />
Newest one should be the best one.<br />
* Please report about problems on forums: [https://forum.vcmi.eu/c/international-board/help-bugs Help & Bugs]<br />
* old 2016's year release (not reccomended, archive version): [http://download.vcmi.eu/vcmi_099.rar 0.99]<br />
<br />
= Step 2: Installing Heroes III data files =<br />
<br />
* Install Heroes III from disk or using GOG installer.<br />
<br />
* Copy "Data", "Maps" and "Mp3" from Heroes III to:<br />
<pre><br />
%USERPROFILE%\Documents\My Games\vcmi\<br />
</pre><br />
Create this folder if it doesnt exist yet<br />
<br />
= Step 3: (for daily builds) download and copy and enable Essential Package =<br />
* For some technical reasons its not currently included in game installation package and needs to be downloaded and activated seperately<br />
* download "VCMI essential files mods" from here https://wiki.vcmi.eu/Mod_list#Utilities<br />
* After unpacking, copy folder Mods to your main VCMI directory<br />
* 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.</div>SXXhttps://wiki.vcmi.eu/index.php?title=How_to_build_VCMI_(Windows/Vcpkg)&diff=3238How to build VCMI (Windows/Vcpkg)2020-04-20T15:58:46Z<p>SXX: Update for MSVS2019</p>
<hr />
<div>= Prerequisites =<br />
* Windows Vista or newer.<br />
* Microsoft Visual Studio [https://www.visualstudio.com/vs/older-downloads/ 2015] or [http://www.visualstudio.com/downloads/download-visual-studio-vs 2017]<br />
* Git or git GUI, for example, SourceTree [http://www.sourcetreeapp.com/download download]<br />
* CMake [https://cmake.org/download/ download]. During install after accepting license agreement make sure to check "Add CMake to the system PATH for all users".<br />
* To unpack pre-build Vcpkg: [http://www.7-zip.org/download.html 7-zip]<br />
* To create installer: [http://nsis.sourceforge.net/Main_Page NSIS]<br />
<br />
= Choose directory =<br />
<br />
Create a directory for VCMI development, eg. '''C:\VCMI'''<br />
We will call this directory as '''[VCMI_DIR]'''<br />
<br />
'''Warning!''' Replace '''[VCMI_DIR]''' with path you chosen in following commands of this instruction.<br />
<br />
== How to choose good directory ==<br />
<br />
It is recommended to avoid non-ascii characters in the path to your working folders. The folder should not be write-protected by system. <br />
Good location:<br />
* '''C:\VCMI'''<br />
Bad locations:<br />
* '''C:\Users\Michał\VCMI''' (non-ascii character)<br />
* '''C:\Program Files (x86)\VCMI''' (write protection)<br />
<br />
= Install dependencies =<br />
<br />
You have two options: to use pre-built libraries or build your own. We strongly recommend start with using pre-built ones.<br />
<br />
== Option A. Use pre-built Vcpkg ==<br />
So you decide to start using Vcpkg packages pre-built by VCMI team.<br />
<br />
Package guaranteed to work since they tested with every commit by [https://ci.appveyor.com/project/vcmi/vcmi AppVeyor]<br />
<br />
=== Download and unpack archive ===<br />
<br />
Archives are available from GitHub: https://github.com/vcmi/vcmi-deps-windows/releases<br />
<br />
Only download latest version available.<br />
<br />
* vcpkg-export-'''x86'''-windows-v140.7z to build for 32-bit<br />
* vcpkg-export-'''x64'''-windows-v140.7z to build for 64-bit<br />
<br />
Extract archive by right clicking on it and choosing "7-zip -> Extract Here".<br />
<br />
=== Move dependencies to target directory ===<br />
<br />
Once extracted "vcpkg" directory will appear with "installed" and "scripts" inside it.<br />
<br />
Move extracted "vcpkg" directory into your '''[VCMI_DIR]'''.<br />
<br />
== Option B. Build Vcpkg on your own ==<br />
Be aware that building Vcpkg might take a lot of time depend on your CPU model and 10-20GB of disk space.<br />
=== Create initial directory ===<br />
<br />
=== Clone vcpkg ===<br />
<br />
# open SourceTree<br />
# File -> Clone<br />
# select '''https://github.com/microsoft/vcpkg/''' as source<br />
# select '''[VCMI_DIR]/vcpkg''' as destination<br />
# click '''Clone'''<br />
<br />
From command line use:<br />
<pre><br />
git clone https://github.com/microsoft/vcpkg.git [VCMI_DIR]/vcpkg<br />
</pre><br />
<br />
=== Build vcpkg ===<br />
* Run <br />
<pre><br />
[VCMI_DIR]/vcpkg/bootstrap-vcpkg.bat<br />
</pre><br />
<br />
=== Build dependencies ===<br />
* For 32-bit build run:<br />
<pre><br />
[VCMI_DIR]/vcpkg/vcpkg.exe install minizip:x86-windows sdl2:x86-windows sdl2-image:x86-windows sdl2-ttf:x86-windows sdl2-mixer:x86-windows boost:x86-windows qt5-base:x86-windows ffmpeg:x86-windows fuzzylite:x86-windows smpeg2:x86-windows<br />
</pre><br />
* For 64-bit build run<br />
<pre><br />
[VCMI_DIR]/vcpkg/vcpkg.exe install minizip:x64-windows sdl2:x64-windows sdl2-image:x64-windows sdl2-ttf:x64-windows sdl2-mixer:x64-windows boost:x64-windows qt5-base:x64-windows ffmpeg:x64-windows fuzzylite:x64-windows smpeg2:x64-windows<br />
</pre><br />
<br />
= Build VCMI =<br />
<br />
== Clone VCMI ==<br />
# open SourceTree<br />
# File -> Clone<br />
# select '''https://github.com/vcmi/vcmi/''' as source<br />
# select '''[VCMI_DIR]/source''' as destination<br />
# expand Advanced Options and change Checkout Branch to "develop"<br />
# tick Recursive submodules<br />
# click '''Clone'''<br />
<br />
or From command line use:<br />
<pre><br />
git clone --recursive https://github.com/vcmi/vcmi.git [VCMI_DIR]/source<br />
</pre><br />
<br />
== Generate solution for VCMI ==<br />
# create '''[VCMI_DIR]/build''' folder<br />
# open '''[VCMI_DIR]/build''' in command line:<br />
## Run Command Prompt or Power Shell.<br />
## Execute: cd [VCMI_DIR]/build<br />
# execute one of following commands to generate project<br />
<br />
'''Visual Studio 2017 - 32-bit build'''<br />
<pre><br />
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 15 2017"<br />
</pre><br />
<br />
'''Visual Studio 2017 - 64-bit build'''<br />
<pre><br />
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 15 2017 Win64"<br />
</pre><br />
<br />
'''Visual Studio 2019 - 32-bit build'''<br />
<pre><br />
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 16 2019" -A Win32<br />
</pre><br />
<br />
'''Visual Studio 2019 - 64-bit build'''<br />
<pre><br />
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 16 2019" -A x64<br />
</pre><br />
<br />
== Compile VCMI with Visual Studio ==<br />
# open '''[VCMI_DIR]/build/VCMI.sln''' in Visual Studio<br />
# select "Release" build type in combobox<br />
# right click on '''BUILD_ALL''' project - build project<br />
# grab VCMI in '''[VCMI_DIR]/build/bin''' folder!<br />
<br />
== Compile VCMI from command line ==<br />
<br />
'''For release build'''<br />
<pre><br />
cmake --build [VCMI_DIR]/build --config Release<br />
</pre><br />
<br />
'''For debug build'''<br />
<pre><br />
cmake --build [VCMI_DIR]/build --config Debug<br />
</pre><br />
Debug will be used by default even "--config" if not specified.<br />
<br />
= Create VCMI installer =<br />
Make sure NSIS is installed to default directory or have registry entry so CMake can find it.<br />
<br />
After you build VCMI execute following commands from '''[VCMI_DIR]/build'''.<br />
=== Execute following if you built for Release: ===<br />
<pre><br />
cpack<br />
</pre><br />
=== If you built for Debug: ===<br />
<pre><br />
cpack -C Debug<br />
</pre><br />
<br />
= Troubleshooting and workarounds =<br />
Vcpkg might be very unstable due to limited popularity and fact of using bleeding edge packages (such as most recent Boost). Using latest version of dependencies could also expose both problems in VCMI code or library interface changes that developers not checked yet. So if you're built Vcpkg yourself and can't get it working please try to use binary package.<br />
<br />
Pre-built version we provide is always manually tested with all supported versions of MSVC for both Release and Debug builds and all known quirks are listed below.<br />
<br />
=== Debug build of VCMI won't run since SDL2.dll / libbz2.dll missing ===<br />
<br />
Almost all of Vcpkg debug libraries are built with "d" prefix, but for whatever reason VCMI or some libraries might expect them to be named without prefix. Workaround is to just make a copy of said library with different name.<br />
<br />
Likely this can be resolved by some CMake configuration magic so if you know how please make pull request.<br />
<br />
=== I got crash within library XYZ.dll ===<br />
<br />
Good workaround is to use debug version of said library instead of release one or vice versa. If that's helped you can swap the library within Vcpkg package itself so you don't need to do it every time when you.<br />
<br />
=== Debug build is very slow ===<br />
<br />
Debug builds with MSVC are generally extremely slow since it's not just VCMI binaries are built as debug, but every single dependency too and this usually mean no optimizations at all. Debug information that available for release builds is often sufficient so just avoid full debug builds unless absolutely necessary.</div>SXXhttps://wiki.vcmi.eu/index.php?title=How_to_build_VCMI_(Linux/Cmake/MXE)&diff=3235How to build VCMI (Linux/Cmake/MXE)2020-04-13T02:52:11Z<p>SXX: Clarify MXE build process</p>
<hr />
<div>= Compiling VCMI for Windows on Linux =<br />
Some developers may want to make Windows builds without dealing with dependencies as it may be headache when you're on Windows. It's possible to setup own cross-compiler toolkit that use MinGW, but that take time and skill. Fortunately there is project called [http://mxe.cc/ MXE (M cross environment)] that make cross compilation easy and work out of box for our engine.<br />
<br />
= Setting up a MXE cross compiler =<br />
Make sure cmake and git is installed on your system as well as all libraries and utils [http://mxe.cc/#requirements listed under requirements]. MXE website have commands that will let install everything needed for almost every distribution.<br />
<br />
Once it done [http://mxe.cc/#download clone MXE repository using git].<br />
<br />
<pre>git clone https://github.com/mxe/mxe.git</pre><br />
<br />
Now just run make once to generate "settings.mk" file and then cancel build immediately with Ctrl+C:<br />
<br />
<pre>make</pre><br />
<br />
Then you need to edit "settings.mk" file:<br />
<pre># "settings.mk" not exist by default<br />
# You can create it by running "make" and then aborting it by Ctrl+C<br />
#<br />
# Uncomment "MXE_TARGETS" and make it look like that:<br />
MXE_TARGETS := i686-w64-mingw32.shared<br />
<br />
# You can add this line to plugins if you want MXE to use GCC6<br />
# This is currently break NSIS though<br />
#override MXE_PLUGIN_DIRS += plugins/gcc6<br />
<br />
# And you can add following packages list<br />
LOCAL_PKG_LIST := gcc boost zlib sdl2 sdl2_gfx sdl2_image sdl2_mixer sdl2_ttf ffmpeg minizip qtbase nsis<br />
# Make sure to uncomment two lines under the list<br />
.DEFAULT_GOAL := local-pkg-list<br />
local-pkg-list: $(LOCAL_PKG_LIST)<br />
</pre><br />
<br />
Then you can compile it:<br />
<pre>make -j 9</pre><br />
Depend on your hardware that may take from 20 minutes to more than hour.<br />
<br />
= Compiling VCMI using MXE =<br />
First of all create two directories: one for CMake (vcmi-cmake) and other for result build (vcmi-build). Now build would looks like that:<br />
<pre># Clone VCMI repository with submodules<br />
git clone --depth 1 --recursive https://github.com/vcmi/vcmi.git<br />
<br />
# Create CMake directory and cd into it<br />
mkdir vcmi-cmake && cd vcmi-cmake<br />
<br />
# To configure build with launcher:<br />
/home/test/mxe/usr/bin/i686-w64-mingw32.shared-cmake ../vcmi -DENABLE_TEST=0<br />
<br />
# Compile<br />
/home/test/mxe/usr/bin/i686-w64-mingw32.shared-cmake --build . -- -j 9<br />
<br />
# To create installer<br />
# MXE have own patched CPack that allow to pass path to makensis as option.<br />
/home/test/mxe/usr/bin/i686-w64-mingw32.shared-cpack -D CPACK_NSIS_EXECUTABLE=/home/test/mxe/usr/bin/i686-w64-mingw32.shared-makensis<br />
</pre><br />
<br />
= Script for automatic builds =<br />
If you want to have automatic build you can grab script that automatically compile and upload builds using MXE.<br />
<br />
*[https://gist.github.com/ArseniyShestakov/39261e5d268cd7c021b0 Download it from Github Gist].</div>SXXhttps://wiki.vcmi.eu/index.php?title=How_to_build_VCMI_(Windows/Vcpkg)&diff=2957How to build VCMI (Windows/Vcpkg)2018-08-27T20:07:39Z<p>SXX: Add some workarounds for problems</p>
<hr />
<div>= Prerequisites =<br />
* Windows Vista or newer.<br />
* Microsoft Visual Studio [https://www.visualstudio.com/vs/older-downloads/ 2015] or [http://www.visualstudio.com/downloads/download-visual-studio-vs 2017]<br />
* Git or git GUI, for example, SourceTree [http://www.sourcetreeapp.com/download download]<br />
* CMake [https://cmake.org/download/ download]. During install after accepting license agreement make sure to check "Add CMake to the system PATH for all users".<br />
* To unpack pre-build Vcpkg: [http://www.7-zip.org/download.html 7-zip]<br />
* To create installer: [http://nsis.sourceforge.net/Main_Page NSIS]<br />
<br />
= Choose directory =<br />
<br />
Create a directory for VCMI development, eg. '''C:\VCMI'''<br />
We will call this directory as '''[VCMI_DIR]'''<br />
<br />
'''Warning!''' Replace '''[VCMI_DIR]''' with path you chosen in following commands of this instruction.<br />
<br />
== How to choose good directory ==<br />
<br />
It is recommended to avoid non-ascii characters in the path to your working folders. The folder should not be write-protected by system. <br />
Good location:<br />
* '''C:\VCMI'''<br />
Bad locations:<br />
* '''C:\Users\Michał\VCMI''' (non-ascii character)<br />
* '''C:\Program Files (x86)\VCMI''' (write protection)<br />
<br />
= Install dependencies =<br />
<br />
You have two options: to use pre-built libraries or build your own. We strongly recommend start with using pre-built ones.<br />
<br />
== Option A. Use pre-built Vcpkg ==<br />
So you decide to start using Vcpkg packages pre-built by VCMI team.<br />
<br />
Package guaranteed to work since they tested with every commit by [https://ci.appveyor.com/project/vcmi/vcmi AppVeyor]<br />
<br />
=== Download and unpack archive ===<br />
<br />
Archives are available from GitHub: https://github.com/vcmi/vcmi-deps-windows/releases<br />
<br />
Only download latest version available.<br />
<br />
* vcpkg-export-'''x86'''-windows-v140.7z to build for 32-bit<br />
* vcpkg-export-'''x64'''-windows-v140.7z to build for 64-bit<br />
<br />
Extract archive by right clicking on it and choosing "7-zip -> Extract Here".<br />
<br />
=== Move dependencies to target directory ===<br />
<br />
Once extracted "vcpkg" directory will appear with "installed" and "scripts" inside it.<br />
<br />
Move extracted "vcpkg" directory into your '''[VCMI_DIR]'''.<br />
<br />
== Option B. Build Vcpkg on your own ==<br />
Be aware that building Vcpkg might take a lot of time depend on your CPU model and 10-20GB of disk space.<br />
=== Create initial directory ===<br />
<br />
=== Clone vcpkg ===<br />
<br />
# open SourceTree<br />
# File -> Clone<br />
# select '''https://github.com/microsoft/vcpkg/''' as source<br />
# select '''[VCMI_DIR]/vcpkg''' as destination<br />
# click '''Clone'''<br />
<br />
From command line use:<br />
<pre><br />
git clone https://github.com/microsoft/vcpkg.git [VCMI_DIR]/vcpkg<br />
</pre><br />
<br />
=== Build vcpkg ===<br />
* Run <br />
<pre><br />
[VCMI_DIR]/vcpkg/bootstrap-vcpkg.bat<br />
</pre><br />
<br />
=== Build dependencies ===<br />
* For 32-bit build run:<br />
<pre><br />
[VCMI_DIR]/vcpkg/vcpkg.exe install minizip:x86-windows sdl2:x86-windows sdl2-image:x86-windows sdl2-ttf:x86-windows sdl2-mixer:x86-windows boost:x86-windows qt5-base:x86-windows ffmpeg:x86-windows fuzzylite:x86-windows smpeg2:x86-windows<br />
</pre><br />
* For 64-bit build run<br />
<pre><br />
[VCMI_DIR]/vcpkg/vcpkg.exe install minizip:x64-windows sdl2:x64-windows sdl2-image:x64-windows sdl2-ttf:x64-windows sdl2-mixer:x64-windows boost:x64-windows qt5-base:x64-windows ffmpeg:x64-windows fuzzylite:x64-windows smpeg2:x64-windows<br />
</pre><br />
<br />
= Build VCMI =<br />
<br />
== Clone VCMI ==<br />
# open SourceTree<br />
# File -> Clone<br />
# select '''https://github.com/vcmi/vcmi/''' as source<br />
# select '''[VCMI_DIR]/source''' as destination<br />
# expand Advanced Options and change Checkout Branch to "develop"<br />
# tick Recursive submodules<br />
# click '''Clone'''<br />
<br />
or From command line use:<br />
<pre><br />
git clone --recursive https://github.com/vcmi/vcmi.git [VCMI_DIR]/source<br />
</pre><br />
<br />
== Generate solution for VCMI ==<br />
# create '''[VCMI_DIR]/build''' folder<br />
# open '''[VCMI_DIR]/build''' in command line:<br />
## Run Command Prompt or Power Shell.<br />
## Execute: cd [VCMI_DIR]/build<br />
# execute one of following commands to generate project<br />
<br />
'''Visual Studio 2015 - 32-bit build'''<br />
<pre><br />
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 14 2015"<br />
</pre><br />
<br />
'''Visual Studio 2015 - 64-bit build'''<br />
<pre><br />
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 14 2015 Win64"<br />
</pre><br />
<br />
'''Visual Studio 2017 - 32-bit build'''<br />
<pre><br />
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 15 2017"<br />
</pre><br />
<br />
'''Visual Studio 2017 - 64-bit build'''<br />
<pre><br />
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 15 2017 Win64"<br />
</pre><br />
<br />
== Compile VCMI with Visual Studio ==<br />
# open '''[VCMI_DIR]/build/VCMI.sln''' in Visual Studio<br />
# select "Release" build type in combobox<br />
# right click on '''BUILD_ALL''' project - build project<br />
# grab VCMI in '''[VCMI_DIR]/build/bin''' folder!<br />
<br />
== Compile VCMI from command line ==<br />
<br />
'''For release build'''<br />
<pre><br />
cmake --build [VCMI_DIR]/build --config Release<br />
</pre><br />
<br />
'''For debug build'''<br />
<pre><br />
cmake --build [VCMI_DIR]/build --config Debug<br />
</pre><br />
Debug will be used by default even "--config" if not specified.<br />
<br />
= Create VCMI installer =<br />
Make sure NSIS is installed to default directory or have registry entry so CMake can find it.<br />
<br />
After you build VCMI execute following commands from '''[VCMI_DIR]/build'''.<br />
=== Execute following if you built for Release: ===<br />
<pre><br />
cpack<br />
</pre><br />
=== If you built for Debug: ===<br />
<pre><br />
cpack -C Debug<br />
</pre><br />
<br />
= Troubleshooting and workarounds =<br />
Vcpkg might be very unstable due to limited popularity and fact of using bleeding edge packages (such as most recent Boost). Using latest version of dependencies could also expose both problems in VCMI code or library interface changes that developers not checked yet. So if you're built Vcpkg yourself and can't get it working please try to use binary package.<br />
<br />
Pre-built version we provide is always manually tested with all supported versions of MSVC for both Release and Debug builds and all known quirks are listed below.<br />
<br />
=== Debug build of VCMI won't run since SDL2.dll / libbz2.dll missing ===<br />
<br />
Almost all of Vcpkg debug libraries are built with "d" prefix, but for whatever reason VCMI or some libraries might expect them to be named without prefix. Workaround is to just make a copy of said library with different name.<br />
<br />
Likely this can be resolved by some CMake configuration magic so if you know how please make pull request.<br />
<br />
=== I got crash within library XYZ.dll ===<br />
<br />
Good workaround is to use debug version of said library instead of release one or vice versa. If that's helped you can swap the library within Vcpkg package itself so you don't need to do it every time when you.<br />
<br />
=== Debug build is very slow ===<br />
<br />
Debug builds with MSVC are generally extremely slow since it's not just VCMI binaries are built as debug, but every single dependency too and this usually mean no optimizations at all. Debug information that available for release builds is often sufficient so just avoid full debug builds unless absolutely necessary.</div>SXXhttps://wiki.vcmi.eu/index.php?title=Hero_Format&diff=2956Hero Format2018-08-27T06:45:14Z<p>SXX: </p>
<hr />
<div>Schema in git: [https://github.com/vcmi/vcmi/blob/develop/config/schemas/hero.json config/schemas/hero.json] <br />
<br />
==Required data==<br />
In order to make functional hero you also need:<br />
* Portraits, small and big versions (2 images)<br />
* Specialty icons, small and big versions (2 images)<br />
==Format== <br />
<syntaxhighlight lang="javascript"><br />
"myHeroName" :<br />
{<br />
// Identifier of class. Usually camelCase version of human-readable name<br />
"class" : "wizard",<br />
<br />
// List of starting spells, if available. Will also grant spellbook<br />
"spellbook" :<br />
[<br />
"magicArrow"<br />
],<br />
<br />
// Set to true if the hero is female by default (can be changed in map editor)<br />
"female" : true,<br />
<br />
// If set to true hero will be unavailable on start and won't appear in taverns (campaign heroes)<br />
"special" : true,<br />
<br />
// All translatable texts related to hero<br />
"texts" :<br />
{<br />
"name" : "My Hero",<br />
"biography" : "This is a long story...",<br />
<br />
"specialty" :<br />
{<br />
// Description visible when hovering over specialty icon<br />
"description" : "Spell mastery: Magic Arrow",<br />
<br />
// Tooltip visible on clicking icon. Can use {} symbols to change title to yellow<br />
// as well as escape sequences "\n" to add line breaks<br />
"tooltip" : "{Magic Arrow}\n\nCasts powerfull magic arrows",<br />
<br />
// Name of your specialty<br />
"name" : "Magic Arrow"<br />
}<br />
},<br />
<br />
// Graphics used by hero<br />
"images" :<br />
{<br />
// Small 32px speciality icon<br />
"specialtySmall" : "myMod/myHero/specSmall.png",<br />
<br />
// Large 44px speciality icon<br />
"specialtyLarge" : "myMod/myHero/specLarge.png",<br />
<br />
// Large 58x64px portrait<br />
"large" : "myMod/myHero/large.png",<br />
<br />
// Small 48x32px portrait<br />
"small" : "myMod/myHero/small.png"<br />
<br />
// Class-independent animation in battle<br />
"small" : "myMod/myHero/battle.def"<br />
<br />
},<br />
<br />
// Initial hero army when recruited in tavern<br />
// Must have 1-3 elements<br />
"army" :<br />
[<br />
// First always available stack<br />
{<br />
// Identifier of creature in this stack<br />
"creature" : "mage",<br />
<br />
// Minimal and maximum size of stack. Size will be<br />
// determined randomly at the start of the game<br />
"max" : 2,<br />
"min" : 1<br />
},<br />
// Second stack has 90 % chance to appear<br />
{<br />
"creature" : "archmage",<br />
"max" : 1,<br />
"min" : 1<br />
},<br />
// Third stack with just 20 % chance to appear<br />
{<br />
"creature" : "mage",<br />
"max" : 2,<br />
"min" : 1<br />
}<br />
],<br />
<br />
// List of skills received by hero<br />
// Not limited by size - you can add as many skills as you wish<br />
"skills" :<br />
[<br />
{<br />
// Skill level, basic, advanced or expert<br />
"level" : "basic",<br />
<br />
// Skill identifier, camelCase version of name<br />
"skill" : "wisdom"<br />
},<br />
{<br />
"level" : "basic",<br />
"skill" : "waterMagic"<br />
}<br />
],<br />
<br />
// Description of specialty mechanics using bonuses (with updaters)<br />
"specialty" : {<br />
// to be merged with all bonuses, use for specialties with multiple similar bonuses (optional)<br />
"base" : {common bonus properties},<br />
"bonuses" : {<br />
// use updaters for bonuses that grow with level<br />
"someBonus" : {Bonus Format},<br />
"anotherOne" : {Bonus Format}<br />
},<br />
// adds creature specialty following the HMM3 default formula<br />
"creature" : "griffin"<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
{{Modding}}</div>SXXhttps://wiki.vcmi.eu/index.php?title=Mod_file_Format&diff=2874Mod file Format2018-04-12T07:02:20Z<p>SXX: Fix CC url</p>
<hr />
<div>This is description of mod.json file, main file for mods.<br />
<br />
Schema in git: [https://github.com/vcmi/vcmi/blob/develop/config/schemas/mod.json config/schemas/mod.json] <br />
<br />
== Fields for local file and repository ==<br />
<syntaxhighlight lang="javascript"> <br />
{<br />
// Name of your mod. While it does not have hard length limit<br />
// it should not be longer than ~30 symbols to fit into allowed space<br />
"name" : "My test mod",<br />
<br />
// More lengthy description of mod. No hard limit. This text will be visible in launcher.<br />
// This field can use small subset of HTML, see link at the bottom of this page.<br />
"description" : "My test mod that add a lot of useless stuff into the game",<br />
<br />
// Author of mod. Can be nickname, real name or name of team<br />
"author" : "Anonymous",<br />
<br />
// Full name of license used by mod. Should be set only if you're author of mod<br />
// or received permission to use such license from original author<br />
"licenseName" : "Creative Commons Attribution-ShareAlike",<br />
<br />
// URL which user can use to see license terms and text<br />
"licenseURL" : "https://creativecommons.org/licenses/by-sa/4.0/",<br />
<br />
<br />
// Home page of mod or link to forum thread to contact the author<br />
"contact" : "http://example.com",<br />
<br />
// Type of mod, e.g. "Town", "Artifacts", "Graphical".<br />
"modType" : "Graphical",<br />
<br />
// List of mods that are required to run this one<br />
"depends" :<br />
[<br />
"baseMod"<br />
],<br />
<br />
// List of mods that can't be enabled in the same time as this one<br />
"conflicts" :<br />
[<br />
"badMod"<br />
],<br />
<br />
//List of changes/new features in each version<br />
"changelog" :<br />
{<br />
"1.0" : [ "initial release" ],<br />
"1.0.1" : [ "change 1", "change 2" ],<br />
"1.1" : [ "change 3", "change 4" ]<br />
},<br />
<br />
// If set to true, mod will not be enabled automatically on install<br />
"keepDisabled" : false<br />
}<br />
</syntaxhighlight><br />
==Fields specific for local file==<br />
These are fields that are present only in local mod.json file<br />
<syntaxhighlight lang="javascript"> <br />
{<br />
// Following section describes configuration files with content added by mod<br />
// It can be split into several files in any way you want but recommended organization is<br />
// to keep one file per object (creature/hero/etc) and, if applicable, add separate file<br />
// with translatable strings for each type of content<br />
// See "additional links" at the bottom of page for descriptions of each of these formats<br />
<br />
// list of factions/towns configuration files<br />
"factions" :<br />
[<br />
"config/myMod/faction.json"<br />
]<br />
<br />
// List of hero classes configuration files<br />
"heroClasses" :<br />
[<br />
"config/myMod/heroClasses.json"<br />
],<br />
<br />
// List of heroes configuration files<br />
"heroes" :<br />
[<br />
"config/myMod/heroes.json"<br />
],<br />
<br />
// list of creature configuration files<br />
"creatures" :<br />
[<br />
"config/myMod/creatures.json"<br />
],<br />
<br />
// List of artifacts configuration files<br />
"artifacts" :<br />
[<br />
"config/myMod/artifacts.json"<br />
],<br />
<br />
// List of objects defined in this mod<br />
"objects" :<br />
[<br />
"config/myMod/objects.json"<br />
],<br />
<br />
// List of spells defined in this mod<br />
"spells" :<br />
[<br />
"config/myMod/spells.json"<br />
],<br />
<br />
// List of RMG templates defined in this mod<br />
"templates" :<br />
[<br />
"config/myMod/templates.json"<br />
],<br />
<br />
// Optional, description on how files are organized in your mod<br />
// In most cases you do not need to use this field<br />
// Needed mostly to port any existing mods to vcmi (e.g. WoG distributed with Era)<br />
// Example below is default value, which is "Content" directory that acts as H3 root directory<br />
"filesystem":<br />
{<br />
"":<br />
[<br />
{"type" : "dir", "path" : "/Content"}<br />
]<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
==Fields present only in repository==<br />
This is list of fields that must be added to mod record in repository file<br />
<syntaxhighlight lang="javascript"> <br />
{<br />
// URL which launcher will use to download mod<br />
"download" : "http://example.com/mods/helloworld.zip",<br />
<br />
// size of mod archive, in kilobytes<br />
"size" : 12345,<br />
<br />
// list of URL's with screenshots for this mod<br />
"screenshots" : [<br />
"http://example.com/images/helloworld_1.png"<br />
]<br />
}<br />
</syntaxhighlight><br />
==Notes==<br />
For mod description it is possible to use certain subset of HTML as described here:<br />
<br />
http://qt-project.org/doc/qt-5.0/qtgui/richtext-html-subset.html<br />
<br />
{{Modding}}</div>SXXhttps://wiki.vcmi.eu/index.php?title=How_to_build_VCMI_(Windows/Vcpkg)&diff=2864How to build VCMI (Windows/Vcpkg)2018-03-30T07:48:29Z<p>SXX: /* Prerequisites */</p>
<hr />
<div>= Prerequisites =<br />
* Windows Vista or newer.<br />
* Microsoft Visual Studio [https://www.visualstudio.com/vs/older-downloads/ 2015] or [http://www.visualstudio.com/downloads/download-visual-studio-vs 2017]<br />
* Git or git GUI, for example, SourceTree [http://www.sourcetreeapp.com/download download]<br />
* CMake [https://cmake.org/download/ download]. During install after accepting license agreement make sure to check "Add CMake to the system PATH for all users".<br />
* To unpack pre-build Vcpkg: [http://www.7-zip.org/download.html 7-zip]<br />
* To create installer: [http://nsis.sourceforge.net/Main_Page NSIS]<br />
<br />
= Choose directory =<br />
<br />
Create a directory for VCMI development, eg. '''C:\VCMI'''<br />
We will call this directory as '''[VCMI_DIR]'''<br />
<br />
'''Warning!''' Replace '''[VCMI_DIR]''' with path you chosen in following commands of this instruction.<br />
<br />
== How to choose good directory ==<br />
<br />
It is recommended to avoid non-ascii characters in the path to your working folders. The folder should not be write-protected by system. <br />
Good location:<br />
* '''C:\VCMI'''<br />
Bad locations:<br />
* '''C:\Users\Michał\VCMI''' (non-ascii character)<br />
* '''C:\Program Files (x86)\VCMI''' (write protection)<br />
<br />
= Install dependencies =<br />
<br />
You have two options: to use pre-built libraries or build your own. We strongly recommend start with using pre-built ones.<br />
<br />
== Option A. Use pre-built Vcpkg ==<br />
So you decide to start using Vcpkg packages pre-built by VCMI team.<br />
<br />
Package guaranteed to work since they tested with every commit by [https://ci.appveyor.com/project/vcmi/vcmi AppVeyor]<br />
<br />
=== Download and unpack archive ===<br />
<br />
Archives are available from GitHub: https://github.com/vcmi/vcmi-deps-windows/releases<br />
<br />
Only download latest version available.<br />
<br />
* vcpkg-export-'''x86'''-windows-v140.7z to build for 32-bit<br />
* vcpkg-export-'''x64'''-windows-v140.7z to build for 64-bit<br />
<br />
Extract archive by right clicking on it and choosing "7-zip -> Extract Here".<br />
<br />
=== Move dependencies to target directory ===<br />
<br />
Once extracted "vcpkg" directory will appear with "installed" and "scripts" inside it.<br />
<br />
Move extracted "vcpkg" directory into your '''[VCMI_DIR]'''.<br />
<br />
== Option B. Build Vcpkg on your own ==<br />
Be aware that building Vcpkg might take a lot of time depend on your CPU model and 10-20GB of disk space.<br />
=== Create initial directory ===<br />
<br />
=== Clone vcpkg ===<br />
<br />
# open SourceTree<br />
# File -> Clone<br />
# select '''https://github.com/microsoft/vcpkg/''' as source<br />
# select '''[VCMI_DIR]/vcpkg''' as destination<br />
# click '''Clone'''<br />
<br />
From command line use:<br />
<pre><br />
git clone https://github.com/microsoft/vcpkg.git [VCMI_DIR]/vcpkg<br />
</pre><br />
<br />
=== Build vcpkg ===<br />
* Run <br />
<pre><br />
[VCMI_DIR]/vcpkg/bootstrap-vcpkg.bat<br />
</pre><br />
<br />
=== Build dependencies ===<br />
* For 32-bit build run:<br />
<pre><br />
[VCMI_DIR]/vcpkg/vcpkg.exe install minizip:x86-windows sdl2:x86-windows sdl2-image:x86-windows sdl2-ttf:x86-windows sdl2-mixer:x86-windows boost:x86-windows qt5-base:x86-windows ffmpeg:x86-windows fuzzylite:x86-windows<br />
</pre><br />
* For 64-bit build run<br />
<pre><br />
[VCMI_DIR]/vcpkg/vcpkg.exe install minizip:x64-windows sdl2:x64-windows sdl2-image:x64-windows sdl2-ttf:x64-windows sdl2-mixer:x64-windows boost:x64-windows qt5-base:x64-windows ffmpeg:x64-windows fuzzylite:x64-windows<br />
</pre><br />
<br />
= Build VCMI =<br />
<br />
== Clone VCMI ==<br />
# open SourceTree<br />
# File -> Clone<br />
# select '''https://github.com/vcmi/vcmi/''' as source<br />
# select '''[VCMI_DIR]/source''' as destination<br />
# expand Advanced Options and change Checkout Branch to "develop"<br />
# tick Recursive submodules<br />
# click '''Clone'''<br />
<br />
or From command line use:<br />
<pre><br />
git clone --recursive https://github.com/vcmi/vcmi.git [VCMI_DIR]/source<br />
</pre><br />
<br />
== Generate solution for VCMI ==<br />
# create '''[VCMI_DIR]/build''' folder<br />
# open '''[VCMI_DIR]/build''' in command line:<br />
## Run Command Prompt or Power Shell.<br />
## Execute: cd [VCMI_DIR]/build<br />
# execute one of following commands to generate project<br />
<br />
'''Visual Studio 2015 - 32-bit build'''<br />
<pre><br />
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 14 2015"<br />
</pre><br />
<br />
'''Visual Studio 2015 - 64-bit build'''<br />
<pre><br />
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 14 2015 Win64"<br />
</pre><br />
<br />
'''Visual Studio 2017 - 32-bit build'''<br />
<pre><br />
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 15 2017"<br />
</pre><br />
<br />
'''Visual Studio 2017 - 64-bit build'''<br />
<pre><br />
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 15 2017 Win64"<br />
</pre><br />
<br />
== Compile VCMI with Visual Studio ==<br />
# open '''[VCMI_DIR]/build/VCMI.sln''' in Visual Studio<br />
# select "Release" build type in combobox<br />
# right click on '''BUILD_ALL''' project - build project<br />
# grab VCMI in '''[VCMI_DIR]/build/bin''' folder!<br />
<br />
== Compile VCMI from command line ==<br />
<br />
'''For release build'''<br />
<pre><br />
cmake --build [VCMI_DIR]/build --config Release<br />
</pre><br />
<br />
'''For debug build'''<br />
<pre><br />
cmake --build [VCMI_DIR]/build --config Debug<br />
</pre><br />
Debug will be used by default even "--config" if not specified.<br />
<br />
= Create VCMI installer =<br />
Make sure NSIS is installed to default directory or have registry entry so CMake can find it.<br />
<br />
After you build VCMI execute following commands from '''[VCMI_DIR]/build'''.<br />
=== Execute following if you built for Release: ===<br />
<pre><br />
cpack<br />
</pre><br />
=== If you built for Debug: ===<br />
<pre><br />
cpack -C Debug<br />
</pre></div>SXXhttps://wiki.vcmi.eu/index.php?title=How_to_build_VCMI_(Windows/Vcpkg)&diff=2827How to build VCMI (Windows/Vcpkg)2018-02-27T14:41:59Z<p>SXX: Vcpkg now has modular build and we just need qt5-base</p>
<hr />
<div>= Prerequisites =<br />
* Windows Vista or newer.<br />
* Microsoft Visual Studio [https://www.visualstudio.com/vs/older-downloads/ 2015] or [http://www.visualstudio.com/downloads/download-visual-studio-vs 2017]<br />
* Git or git GUI, for example, SourceTree [http://www.sourcetreeapp.com/download download]<br />
* CMake [https://cmake.org/download/ download]<br />
* To unpack pre-build Vcpkg: [http://www.7-zip.org/download.html 7-zip]<br />
* To create installer: [http://nsis.sourceforge.net/Main_Page NSIS]<br />
<br />
= Choose directory =<br />
<br />
Create a directory for VCMI development, eg. '''C:\VCMI'''<br />
We will call this directory as '''[VCMI_DIR]'''<br />
<br />
'''Warning!''' Replace '''[VCMI_DIR]''' with path you chosen in following commands of this instruction.<br />
<br />
== How to choose good directory ==<br />
<br />
It is recommended to avoid non-ascii characters in the path to your working folders. The folder should not be write-protected by system. <br />
Good location:<br />
* '''C:\VCMI'''<br />
Bad locations:<br />
* '''C:\Users\Michał\VCMI''' (non-ascii character)<br />
* '''C:\Program Files (x86)\VCMI''' (write protection)<br />
<br />
= Install dependencies =<br />
<br />
You have two options: to use pre-built libraries or build your own. We strongly recommend start with using pre-built ones.<br />
<br />
== Option A. Use pre-built Vcpkg ==<br />
So you decide to start using Vcpkg packages pre-built by VCMI team.<br />
<br />
Package guaranteed to work since they tested with every commit by [https://ci.appveyor.com/project/vcmi/vcmi AppVeyor]<br />
<br />
=== Download and unpack archive ===<br />
<br />
Archives are available from GitHub: https://github.com/vcmi/vcmi-deps-windows/releases<br />
<br />
Only download latest version available.<br />
<br />
* vcpkg-export-'''x86'''-windows-v140.7z to build for 32-bit<br />
* vcpkg-export-'''x64'''-windows-v140.7z to build for 64-bit<br />
<br />
Extract archive by right clicking on it and choosing "7-zip -> Extract Here".<br />
<br />
=== Move dependencies to target directory ===<br />
<br />
Once extracted "vcpkg" directory will appear with "installed" and "scripts" inside it.<br />
<br />
Move extracted "vcpkg" directory into your '''[VCMI_DIR]'''.<br />
<br />
== Option B. Build Vcpkg on your own ==<br />
Be aware that building Vcpkg might take a lot of time depend on your CPU model and 10-20GB of disk space.<br />
=== Create initial directory ===<br />
<br />
=== Clone vcpkg ===<br />
<br />
# open SourceTree<br />
# File -> Clone<br />
# select '''https://github.com/microsoft/vcpkg/''' as source<br />
# select '''[VCMI_DIR]/vcpkg''' as destination<br />
# click '''Clone'''<br />
<br />
From command line use:<br />
<pre><br />
git clone https://github.com/microsoft/vcpkg.git [VCMI_DIR]/vcpkg<br />
</pre><br />
<br />
=== Build vcpkg ===<br />
* Run <br />
<pre><br />
[VCMI_DIR]/vcpkg/bootstrap-vcpkg.bat<br />
</pre><br />
<br />
=== Build dependencies ===<br />
* For 32-bit build run:<br />
<pre><br />
[VCMI_DIR]/vcpkg/vcpkg.exe install minizip:x86-windows sdl2:x86-windows sdl2-image:x86-windows sdl2-ttf:x86-windows sdl2-mixer:x86-windows boost:x86-windows qt5-base:x86-windows ffmpeg:x86-windows fuzzylite:x86-windows<br />
</pre><br />
* For 64-bit build run<br />
<pre><br />
[VCMI_DIR]/vcpkg/vcpkg.exe install minizip:x64-windows sdl2:x64-windows sdl2-image:x64-windows sdl2-ttf:x64-windows sdl2-mixer:x64-windows boost:x64-windows qt5-base:x64-windows ffmpeg:x64-windows fuzzylite:x64-windows<br />
</pre><br />
<br />
= Build VCMI =<br />
<br />
== Clone VCMI ==<br />
# open SourceTree<br />
# File -> Clone<br />
# select '''https://github.com/vcmi/vcmi/''' as source<br />
# select '''[VCMI_DIR]/source''' as destination<br />
# expand Advanced Options and change Checkout Branch to "develop"<br />
# tick Recursive submodules<br />
# click '''Clone'''<br />
<br />
or From command line use:<br />
<pre><br />
git clone --recursive https://github.com/vcmi/vcmi.git [VCMI_DIR]/source<br />
</pre><br />
<br />
== Generate solution for VCMI ==<br />
# create '''[VCMI_DIR]/build''' folder<br />
# open '''[VCMI_DIR]/build''' in command line:<br />
## Run Command Prompt or Power Shell.<br />
## Execute: cd [VCMI_DIR]/build<br />
# execute one of following commands to generate project<br />
<br />
'''Visual Studio 2015 - 32-bit build'''<br />
<pre><br />
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 14 2015"<br />
</pre><br />
<br />
'''Visual Studio 2015 - 64-bit build'''<br />
<pre><br />
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 14 2015 Win64"<br />
</pre><br />
<br />
'''Visual Studio 2017 - 32-bit build'''<br />
<pre><br />
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 15 2017"<br />
</pre><br />
<br />
'''Visual Studio 2017 - 64-bit build'''<br />
<pre><br />
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 15 2017 Win64"<br />
</pre><br />
<br />
== Compile VCMI with Visual Studio ==<br />
# open '''[VCMI_DIR]/build/VCMI.sln''' in Visual Studio<br />
# select "Release" build type in combobox<br />
# right click on '''BUILD_ALL''' project - build project<br />
# grab VCMI in '''[VCMI_DIR]/build/bin''' folder!<br />
<br />
== Compile VCMI from command line ==<br />
<br />
'''For release build'''<br />
<pre><br />
cmake --build [VCMI_DIR]/build --config Release<br />
</pre><br />
<br />
'''For debug build'''<br />
<pre><br />
cmake --build [VCMI_DIR]/build --config Debug<br />
</pre><br />
Debug will be used by default even "--config" if not specified.<br />
<br />
= Create VCMI installer =<br />
Make sure NSIS is installed to default directory or have registry entry so CMake can find it.<br />
<br />
After you build VCMI execute following commands from '''[VCMI_DIR]/build'''.<br />
=== Execute following if you built for Release: ===<br />
<pre><br />
cpack<br />
</pre><br />
=== If you built for Debug: ===<br />
<pre><br />
cpack -C Debug<br />
</pre></div>SXXhttps://wiki.vcmi.eu/index.php?title=Mods_repository&diff=2820Mods repository2018-02-23T11:01:08Z<p>SXX: </p>
<hr />
<div>This article will introduce you to new VCMI mod repository system and explain how new mods can be added there.<br />
<br />
= How mod repository work =<br />
<br />
== Where files are hosted ==<br />
<br />
Mods list hosted under main VCMI organization: [https://github.com/vcmi/vcmi-mods-repository vcmi-mods-repository].<br />
<br />
Each mod hosted in it's own repository under separate organization [https://github.com/vcmi-mods 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.<br />
<br />
== Why Git / GitHub? ==<br />
<br />
It's solve a lot of problems:<br />
<br />
* Engine developers get control over all mods and can easily update them without adding extra burden for modders / mod maintainers.<br />
* With tools such as [https://desktop.github.com/ GitHub Desktop] it's easy for non-programmers to contribute.<br />
* 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.<br />
* 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.<br />
* GitHub also create ZIP archives for us so mods will be stored uncompressed and version can be identified by commit hash.<br />
<br />
== On backward compatibility ==<br />
<br />
Our mod list in vcmi-mods-repository had "develop" as primary branch. Daily builds of VCMI use mod list file from this branch.<br />
<br />
Once VCMI get stable release there will be branching into "1.00", "1.01", etc. Launcher of released version will request mod list for particular version.<br />
<br />
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.<br />
<br />
== Redirect server ==<br />
<br />
Launcher will request specific version of JSON mod list from our server:<br />
<pre><br />
https://mods.vcmi.download/repository/develop.json<br />
https://mods.vcmi.download/repository/1.00.json<br />
</pre><br />
<br />
Our server redirect requests to github:<br />
<pre><br />
mods.vcmi.download/repository/develop.json -> raw.githubusercontent.com/vcmi/mods-repository/develop/repository.json<br />
repository.vcmi.download/1.00.json -> raw.githubusercontent.com/vcmi/mods-repository/1.00/repository.json<br />
</pre><br />
<br />
Same happen when launcher will request mods:<br />
<pre><br />
mods.vcmi.download/archive/adventure-ai-trace/821190ef5396702bf763c764ed532781b1fc1ce6.zip -> github.com/vcmi-mods/adventure-ai-trace/archive/821190ef5396702bf763c764ed532781b1fc1ce6.zip<br />
</pre><br />
<br />
This way in case of any problems with GitHub we can easily change the way mods are delivered.<br />
<br />
= Getting mod into repository =<br />
<br />
== Getting into vcmi-mods organization ==<br />
<br />
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.<br />
<br />
Link to our mod will looks like that:<br />
<br />
<pre><br />
https://github.com/vcmi-mods/adventure-ai-trace<br />
</pre><br />
<br />
== Rules of repository ==<br />
<br />
=== Allowed name for mod identifier ===<br />
For sanity reasons mod identifier must only contain lower-case English characters, numbers and hyphens.<br />
<pre><br />
my-mod-name<br />
2000-new-maps<br />
</pre><br />
Sub-mods can be named as you like, but we strongly encourage everyone to use proper identifiers for them as well.<br />
<br />
=== Rewriting History ===<br />
<br />
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.<br />
<br />
Branches such as "develop" or stable branches like "1.00" should be marked as protected on GitHub.<br />
<br />
== Submitting mods to repository ==<br />
<br />
Once mod ready for general public maintainer to make PR to [https://github.com/vcmi/vcmi-mods-repository vcmi-mods-repository].<br />
<br />
== Requirements ==<br />
<br />
Right now main requirements for a mod to be accepted into VCMI mods list are:<br />
<br />
* Mod must be complete. For work-in-progress mods it is better to use other way of distribution.<br />
* Mod must met some basic quality requirements. Having high-quality content is always preferable.<br />
* Mod must not contain any errors detectable by validation (console message you may see during loading)<br />
* Music files must be in Ogg/Vorbis format (*.ogg extension)</div>SXXhttps://wiki.vcmi.eu/index.php?title=Mods_repository&diff=2808Mods repository2018-02-21T08:44:06Z<p>SXX: /* Requirements */</p>
<hr />
<div>This article will introduce you to new VCMI mod repository system and explain how new mods can be added there.<br />
<br />
= How mod repository work =<br />
<br />
== Where files are hosted ==<br />
<br />
Mods list hosted under main VCMI organization: [https://github.com/vcmi/vcmi-mods-repository vcmi-mods-repository].<br />
<br />
Each mod hosted in it's own repository under separate organization [https://github.com/vcmi-mods 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.<br />
<br />
== Why Git / GitHub? ==<br />
<br />
It's solve a lot of problems:<br />
<br />
* Engine developers get control over all mods and can easily update them without adding extra burden for modders / mod maintainers.<br />
* With tools such as [https://desktop.github.com/ GitHub Desktop] it's easy for non-programmers to contribute.<br />
* 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.<br />
* 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.<br />
* GitHub also create ZIP archives for us so mods will be stored uncompressed and version can be identified by commit hash.<br />
<br />
== On backward compatibility ==<br />
<br />
Our mod list in vcmi-mods-repository had "develop" as primary branch. Daily builds of VCMI use mod list file from this branch.<br />
<br />
Once VCMI get stable release there will be branching into "1.00", "1.01", etc. Launcher of released version will request mod list for particular version.<br />
<br />
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.<br />
<br />
== Redirect server ==<br />
<br />
Launcher will request specific version of JSON mod list from our server:<br />
<pre><br />
https://mods.vcmi.download/repository/develop.json<br />
https://mods.vcmi.download/repository/1.00.json<br />
</pre><br />
<br />
Our server redirect requests to github:<br />
<pre><br />
mods.vcmi.download/repository/develop.json -> raw.githubusercontent.com/vcmi/mods-repository/develop/repository.json<br />
repository.vcmi.download/1.00.json -> raw.githubusercontent.com/vcmi/mods-repository/1.00/repository.json<br />
</pre><br />
<br />
Same happen when launcher will request mods:<br />
<pre><br />
mods.vcmi.download/archive/adventure-ai-trace/821190ef5396702bf763c764ed532781b1fc1ce6.zip -> github.com/vcmi-mods/adventure-ai-trace/archive/821190ef5396702bf763c764ed532781b1fc1ce6.zip<br />
</pre><br />
<br />
This way in case of any problems with GitHub we can easily change the way mods are delivered.<br />
<br />
= Getting mod into repository =<br />
<br />
== Requirements ==<br />
Right now main requirements for a mod to be accepted into VCMI repository are:<br />
* Mod identified must be lower case, only of English characters and dashes.<br />
* Mod must be complete. For work-in-progress mods it is better to use other way of distribution.<br />
* Mod must met some basic quality requirements. Having high-quality content is always preferable.<br />
* Mod must not contain any errors detectable by validation (console message you may see during loading)<br />
* Music files must be in Ogg/Vorbis format (*.ogg extension)<br />
<br />
== Getting into vcmi-mods organization ==<br />
<br />
To get mod into repository you need to contact person with write access to it.<br />
<br />
== Submitting mods to repository ==<br />
<br />
Once mod ready for general public maintainer to make PR to [https://github.com/vcmi/vcmi-mods-repository vcmi-mods-repository].<br />
<br />
= Rules of repository =<br />
<br />
* Force pushing to branches is forbidden when it's touch commits that already submitted into mod list!</div>SXXhttps://wiki.vcmi.eu/index.php?title=Mods_repository&diff=2807Mods repository2018-02-21T08:32:36Z<p>SXX: </p>
<hr />
<div>This article will introduce you to new VCMI mod repository system and explain how new mods can be added there.<br />
<br />
= How mod repository work =<br />
<br />
== Where files are hosted ==<br />
<br />
Mods list hosted under main VCMI organization: [https://github.com/vcmi/vcmi-mods-repository vcmi-mods-repository].<br />
<br />
Each mod hosted in it's own repository under separate organization [https://github.com/vcmi-mods 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.<br />
<br />
== Why Git / GitHub? ==<br />
<br />
It's solve a lot of problems:<br />
<br />
* Engine developers get control over all mods and can easily update them without adding extra burden for modders / mod maintainers.<br />
* With tools such as [https://desktop.github.com/ GitHub Desktop] it's easy for non-programmers to contribute.<br />
* 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.<br />
* 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.<br />
* GitHub also create ZIP archives for us so mods will be stored uncompressed and version can be identified by commit hash.<br />
<br />
== On backward compatibility ==<br />
<br />
Our mod list in vcmi-mods-repository had "develop" as primary branch. Daily builds of VCMI use mod list file from this branch.<br />
<br />
Once VCMI get stable release there will be branching into "1.00", "1.01", etc. Launcher of released version will request mod list for particular version.<br />
<br />
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.<br />
<br />
== Redirect server ==<br />
<br />
Launcher will request specific version of JSON mod list from our server:<br />
<pre><br />
https://mods.vcmi.download/repository/develop.json<br />
https://mods.vcmi.download/repository/1.00.json<br />
</pre><br />
<br />
Our server redirect requests to github:<br />
<pre><br />
mods.vcmi.download/repository/develop.json -> raw.githubusercontent.com/vcmi/mods-repository/develop/repository.json<br />
repository.vcmi.download/1.00.json -> raw.githubusercontent.com/vcmi/mods-repository/1.00/repository.json<br />
</pre><br />
<br />
Same happen when launcher will request mods:<br />
<pre><br />
mods.vcmi.download/archive/adventure-ai-trace/821190ef5396702bf763c764ed532781b1fc1ce6.zip -> github.com/vcmi-mods/adventure-ai-trace/archive/821190ef5396702bf763c764ed532781b1fc1ce6.zip<br />
</pre><br />
<br />
This way in case of any problems with GitHub we can easily change the way mods are delivered.<br />
<br />
= Getting mod into repository =<br />
<br />
== Requirements ==<br />
Right now main requirements for a mod to be accepted into VCMI repository are:<br />
* Mod must be complete. For work-in-progress mods it is better to use other way of distribution.<br />
* Mod must met some basic quality requirements. Having high-quality content is always preferable.<br />
* Mod must not contain any errors detectable by validation (console message you may see during loading)<br />
* Music files must be in Ogg/Vorbis format (*.ogg extension)<br />
<br />
== Getting into vcmi-mods organization ==<br />
<br />
To get mod into repository you need to contact person with write access to it.<br />
<br />
== Submitting mods to repository ==<br />
<br />
Once mod ready for general public maintainer to make PR to [https://github.com/vcmi/vcmi-mods-repository vcmi-mods-repository].<br />
<br />
= Rules of repository =<br />
<br />
* Force pushing to branches is forbidden when it's touch commits that already submitted into mod list!</div>SXXhttps://wiki.vcmi.eu/index.php?title=Mods_repository&diff=2806Mods repository2018-02-21T08:20:24Z<p>SXX: /* Where files are hosted */</p>
<hr />
<div>This article will introduce you to new VCMI mod repository system and explain how new mods can be added there.<br />
<br />
= How mod repository work =<br />
<br />
== Where files are hosted ==<br />
<br />
Mods list hosted under main VCMI organization: [https://github.com/vcmi/vcmi-mods-repository vcmi-mods-repository].<br />
<br />
Each mod hosted in it's own repository under separate organization [https://github.com/vcmi-mods 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.<br />
<br />
== Why Git / GitHub? ==<br />
<br />
It's solve a lot of problems:<br />
<br />
* Engine developers get control over all mods and can easily update them without adding extra burden for modders / mod maintainers.<br />
* With tools such as [https://desktop.github.com/ GitHub Desktop] it's easy for non-programmers to contribute.<br />
* 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.<br />
* 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.<br />
* GitHub also create ZIP archives for us so mods will be stored uncompressed and version can be identified by commit hash.<br />
<br />
= On backward compatibility =<br />
<br />
Our mod list in vcmi-mods-repository had "develop" as primary branch. Daily builds of VCMI use mod list file from this branch.<br />
<br />
Once VCMI get stable release there will be branching into "1.00", "1.01", etc. Launcher of released version will request mod list for particular version.<br />
<br />
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.<br />
<br />
== Redirect server ==<br />
<br />
Launcher will request specific version of JSON mod list from our server:<br />
<pre><br />
https://mods.vcmi.download/repository/develop.json<br />
https://mods.vcmi.download/repository/1.00.json<br />
</pre><br />
<br />
Our server redirect requests to github:<br />
<pre><br />
mods.vcmi.download/repository/develop.json -> raw.githubusercontent.com/vcmi/mods-repository/develop/repository.json<br />
repository.vcmi.download/1.00.json -> raw.githubusercontent.com/vcmi/mods-repository/1.00/repository.json<br />
</pre><br />
<br />
Same happen when launcher will request mods:<br />
<pre><br />
mods.vcmi.download/archive/adventure-ai-trace/821190ef5396702bf763c764ed532781b1fc1ce6.zip -> github.com/vcmi-mods/adventure-ai-trace/archive/821190ef5396702bf763c764ed532781b1fc1ce6.zip<br />
</pre><br />
<br />
This way in case of any problems with GitHub we can easily change the way mods are delivered.<br />
<br />
= Getting mod into repository =<br />
<br />
== Requirements ==<br />
Right now main requirements for a mod to be accepted into VCMI repository are:<br />
* Mod must be complete. For work-in-progress mods it is better to use other way of distribution.<br />
* Mod must met some basic quality requirements. Having high-quality content is always preferable.<br />
* Mod must not contain any errors detectable by validation (console message you may see during loading)<br />
* Music files must be in Ogg/Vorbis format (*.ogg extension)<br />
<br />
== Getting into vcmi-mods organization ==<br />
<br />
To get mod into repository you need to contact person with write access to it.<br />
<br />
== Submitting mods to repository ==<br />
<br />
Once mod ready for general public maintainer to make PR to [https://github.com/vcmi/vcmi-mods-repository vcmi-mods-repository].</div>SXXhttps://wiki.vcmi.eu/index.php?title=Mods_repository&diff=2805Mods repository2018-02-21T08:08:01Z<p>SXX: /* Redirect server */</p>
<hr />
<div>This article will introduce you to new VCMI mod repository system and explain how new mods can be added there.<br />
<br />
= How mod repository work =<br />
<br />
== Where files are hosted ==<br />
<br />
Mods list hosted under main VCMI organization: [https://github.com/vcmi/vcmi-mods-repository vcmi-mods-repository].<br />
Each mod hosted in it's own repository under separate organization [https://github.com/vcmi-mods 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.<br />
<br />
== Why Git / GitHub? ==<br />
<br />
It's solve a lot of problems:<br />
<br />
* Engine developers get control over all mods and can easily update them without adding extra burden for modders / mod maintainers.<br />
* With tools such as [https://desktop.github.com/ GitHub Desktop] it's easy for non-programmers to contribute.<br />
* 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.<br />
* 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.<br />
* GitHub also create ZIP archives for us so mods will be stored uncompressed and version can be identified by commit hash.<br />
<br />
= On backward compatibility =<br />
<br />
Our mod list in vcmi-mods-repository had "develop" as primary branch. Daily builds of VCMI use mod list file from this branch.<br />
<br />
Once VCMI get stable release there will be branching into "1.00", "1.01", etc. Launcher of released version will request mod list for particular version.<br />
<br />
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.<br />
<br />
== Redirect server ==<br />
<br />
Launcher will request specific version of JSON mod list from our server:<br />
<pre><br />
https://mods.vcmi.download/repository/develop.json<br />
https://mods.vcmi.download/repository/1.00.json<br />
</pre><br />
<br />
Our server redirect requests to github:<br />
<pre><br />
mods.vcmi.download/repository/develop.json -> raw.githubusercontent.com/vcmi/mods-repository/develop/repository.json<br />
repository.vcmi.download/1.00.json -> raw.githubusercontent.com/vcmi/mods-repository/1.00/repository.json<br />
</pre><br />
<br />
Same happen when launcher will request mods:<br />
<pre><br />
mods.vcmi.download/archive/adventure-ai-trace/821190ef5396702bf763c764ed532781b1fc1ce6.zip -> github.com/vcmi-mods/adventure-ai-trace/archive/821190ef5396702bf763c764ed532781b1fc1ce6.zip<br />
</pre><br />
<br />
This way in case of any problems with GitHub we can easily change the way mods are delivered.<br />
<br />
= Getting mod into repository =<br />
<br />
== Requirements ==<br />
Right now main requirements for a mod to be accepted into VCMI repository are:<br />
* Mod must be complete. For work-in-progress mods it is better to use other way of distribution.<br />
* Mod must met some basic quality requirements. Having high-quality content is always preferable.<br />
* Mod must not contain any errors detectable by validation (console message you may see during loading)<br />
* Music files must be in Ogg/Vorbis format (*.ogg extension)<br />
<br />
== Getting into vcmi-mods organization ==<br />
<br />
To get mod into repository you need to contact person with write access to it.<br />
<br />
== Submitting mods to repository ==<br />
<br />
Once mod ready for general public maintainer to make PR to [https://github.com/vcmi/vcmi-mods-repository vcmi-mods-repository].</div>SXXhttps://wiki.vcmi.eu/index.php?title=Mods_repository&diff=2804Mods repository2018-02-21T08:07:20Z<p>SXX: Rework article for modders</p>
<hr />
<div>This article will introduce you to new VCMI mod repository system and explain how new mods can be added there.<br />
<br />
= How mod repository work =<br />
<br />
== Where files are hosted ==<br />
<br />
Mods list hosted under main VCMI organization: [https://github.com/vcmi/vcmi-mods-repository vcmi-mods-repository].<br />
Each mod hosted in it's own repository under separate organization [https://github.com/vcmi-mods 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.<br />
<br />
== Why Git / GitHub? ==<br />
<br />
It's solve a lot of problems:<br />
<br />
* Engine developers get control over all mods and can easily update them without adding extra burden for modders / mod maintainers.<br />
* With tools such as [https://desktop.github.com/ GitHub Desktop] it's easy for non-programmers to contribute.<br />
* 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.<br />
* 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.<br />
* GitHub also create ZIP archives for us so mods will be stored uncompressed and version can be identified by commit hash.<br />
<br />
= On backward compatibility =<br />
<br />
Our mod list in vcmi-mods-repository had "develop" as primary branch. Daily builds of VCMI use mod list file from this branch.<br />
<br />
Once VCMI get stable release there will be branching into "1.00", "1.01", etc. Launcher of released version will request mod list for particular version.<br />
<br />
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.<br />
<br />
== Redirect server ==<br />
<br />
Launcher will request specific version of JSON mod list from our server:<br />
<pre><br />
https://mods.vcmi.download/repository/develop.json<br />
https://mods.vcmi.download/repository/1.00.json<br />
</pre><br />
<br />
Our server redirect requests to github:<br />
<pre><br />
mods.vcmi.download/repository/develop.json -> raw.githubusercontent.com/vcmi/mods-repository/develop/repository.json<br />
repository.vcmi.download/1.00.json -> raw.githubusercontent.com/vcmi/mods-repository/1.00/repository.json<br />
</pre><br />
<br />
Same happen when launcher will request mods:<br />
<pre><br />
mods.vcmi.download/archive/adventure-ai-trace/821190ef5396702bf763c764ed532781b1fc1ce6.zip -> github.com/vcmi-mods/adventure-ai-trace/archive/821190ef5396702bf763c764ed532781b1fc1ce6.zip<br />
</pre><br />
<br />
This way in case of any problems with GitHub we can easily change the way mods are delivered.<br />
<br />
= Getting mod into repository =<br />
<br />
== Requirements ==<br />
Right now main requirements for a mod to be accepted into VCMI repository are:<br />
* Mod must be complete. For work-in-progress mods it is better to use other way of distribution.<br />
* Mod must met some basic quality requirements. Having high-quality content is always preferable.<br />
* Mod must not contain any errors detectable by validation (console message you may see during loading)<br />
* Music files must be in Ogg/Vorbis format (*.ogg extension)<br />
<br />
== Getting into vcmi-mods organization ==<br />
<br />
To get mod into repository you need to contact person with write access to it.<br />
<br />
== Submitting mods to repository ==<br />
<br />
Once mod ready for general public maintainer to make PR to [https://github.com/vcmi/vcmi-mods-repository vcmi-mods-repository].</div>SXXhttps://wiki.vcmi.eu/index.php?title=Modding_guidelines&diff=2803Modding guidelines2018-02-21T06:45:30Z<p>SXX: /* VCMI Repository */</p>
<hr />
<div>If you just want to play see [[mod list]].<br />
<br />
== Creating mod ==<br />
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.<br />
<br />
Main mod is file called '''mod.json''' and should be placed into main folder of your mod, e.g. '''Mods/myMod/mod.json'''<br />
<br />
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.<br />
<br />
Example of how directory structure of your mod may look like:<br />
<pre><br />
Mods/<br />
myMod/<br />
mod.json<br />
Content/<br />
data/ - unorganized files, mostly bitmap images (.bmp, .png, .pcx)<br />
config/ - json configuration files<br />
maps/ - h3m maps added or modified by mod<br />
music/ - music files. Mp3 is fully supported, ogg may be added if needed<br />
sounds/ - sound files, in wav format.<br />
sprites/ - animation, image sets (H3 .def files or VCMI .json files)<br />
video/ - video files, .bik or .smk<br />
</pre><br />
== Updating mod to next version of VCMI ==<br />
See [[Modding changelog]]<br />
== Creating mod file ==<br />
All VCMI configuration files use [http://en.wikipedia.org/wiki/Json JSON format] so you may want to familiarize yourself with it first.<br />
<br />
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.<br />
<br />
Minimalistic version of this file:<br />
<syntaxhighlight lang="javascript"><br />
{<br />
"name" : "My test mod",<br />
"description" : "My test mod that add a lot of useless stuff into the game"<br />
}<br />
</syntaxhighlight><br />
See [[Mod file Format]] for its full description.<br />
<br />
== Overriding graphical files from Heroes III ==<br />
<br />
Any graphical replacer mods fall under this category. In VCMI directory '''<mod name>/Content''' acts as mod-specific game root directory.<br />
So for example file '''<mod name>/Content/Data/AISHIELD.PNG''' will replace file with same name from '''H3Bitmap.lod''' game archive.<br />
<br />
Any other files can be replaced in exactly same way.<br />
<br />
Note that replacing files from archives requires placing them into specific location:<br />
<pre><br />
H3Bitmap.lod -> Data<br />
H3Sprite.lod -> Sprites<br />
Heroes3.snd -> Sounds<br />
Video.vid -> Video<br />
</pre><br />
This includes archives added by expansions (e.g. '''H3ab_bmp.lod''' uses same rules as '''H3Bitmap.lod''')<br />
<br />
=== Replacing .def animation files ===<br />
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.<br />
<br />
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:<br />
* Replacing one (or several) icons in set<br />
* Replacing animation with fully-colored 32-bit images<br />
<br />
In VCMI these animation files can also be replaced by json description of their content. See [[Animation Format]] for full description of this format.<br />
<br />
Example: replacing single icon<br />
<syntaxhighlight lang="javascript"><br />
{<br />
// List of replaced images<br />
"images" : <br />
[ // Index of replaced frame<br />
{ "frame" : 0, "file" : "HPS000KN.bmp"} <br />
//name of file that will be used as replacement<br />
]<br />
}<br />
</syntaxhighlight><br />
<br />
<br />
"High resolution main menu" mod can be used as example of file replacer mod.<br />
== Packaging mod into archive ==<br />
For distribution it is recommended to package mod into .zip archives. To create .zip archive you need to have file archiver like [http://www.7-zip.org 7zip]<br />
<br />
File structure of packaged mod should look like this<br />
<pre><br />
<modname>.zip/ <- Zip archive with high compression ratio<br />
modname/ <- Archive contains main mod directory <br />
mod.json <- main mod file<br />
Content.zip/ <- Uncompressed archive with all mod data<br />
Data/ <br />
... <- Identical to Content directory<br />
Sprites/<br />
</pre><br />
<br />
You can create such structure using following instructions:<br />
* Go to Mods/<modname>/Content directory<br />
* Select all files in this directory and create archive with following parameters:<br />
** Archive name: Content.zip<br />
** Format: ZIP<br />
** Compression level: None/Store only<br />
* Move created archive into Mods/<modname> directory and remove no longer needed Content directory.<br />
* Go to Mods/ directory<br />
* Create archive from your mod with following parameters:<br />
** Archive name: <modname>.zip<br />
** Format: ZIP<br />
** Compression level: Maximum<br />
<br />
Resulting archive is recommended form for distributing mods for VCMI<br />
== Releasing mods ==<br />
Right now there are 3 ways to bring your mod to players:<br />
* Manual download<br />
* VCMI Repository<br />
* Private repository<br />
=== Manual download ===<br />
You can upload mod into some online file hosting and add link with description of your mod into [[mod list]].<br />
<br />
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:<br />
<!-- Note to editors: do not add any more entries in this list - please, keep it short, no more than 5 links --><br />
* [http://mediafire.com MediaFire]<br />
* [https://dropbox.com Dropbox]<br />
* [https://drive.google.com Google Drive]<br />
* Any other service that does not has aforementioned problems<br />
<br />
=== VCMI Repository ===<br />
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.<br />
<br />
Check for more details in [[Mods repository]].<br />
<br />
=== Private repository ===<br />
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).<br />
<br />
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.<br />
<br />
To create empty repository you need to:<br />
* Create directory that will contain repository<br />
* Create file named "repository.json" in it<br />
<br />
To add mods into such repository you need to:<br />
* Copy packaged archive <modname>.zip into repository directory<br />
* Copy mod information from mod.json into repository.json<br />
* Add two extra fields about this mod into repository.json:<br />
** "download" - public link that can be used to download the mod, including http:// prefix<br />
** "size" - size of mod, in kilobytes. VCMI will use this number to inform player on size of the mod.<br />
<br />
Example on how mod entry should look in repository.json<br />
<syntaxhighlight lang="javascript"><br />
{<br />
...<br />
"exampleMod" // ID of the mod, lowercase version of mod directory name<br />
{<br />
"name" : "My test mod",<br />
"description" : "My test mod that add a lot of useless stuff into the game",<br />
"author" : "Anonymous",<br />
"contact" : "http://example.com",<br />
"modType" : "Graphical",<br />
"depends" :<br />
[<br />
"baseMod"<br />
],<br />
<br />
"download" : "http://example.com/vcmi/repository/exampleMod.zip",<br />
"size" : 1234 //size, in kilobytes<br />
<br />
//Note that entries that refer to files, e.g. "heroes". "creatures", "artifacts" and such<br />
//are not necessary in repository.json and therefore can be removed<br />
},<br />
...<br />
}<br />
</syntaxhighlight><br />
<br />
When repository is ready you can share public link to repository.json with players. New repositories can added to vcmi launcher from settings tab.<br />
==== Dropbox: enabling public directory ====<br />
New accounts create on Dropbox no longer have Public directory enabled by default. You can enable it using this [https://www.dropbox.com/enable_public_folder link]<br />
<br />
This will give you directory named "Public" as well as option "get public link" for all files inside this directory.<br />
<br />
{{Modding}}</div>SXXhttps://wiki.vcmi.eu/index.php?title=Modding_guidelines&diff=2802Modding guidelines2018-02-21T06:42:31Z<p>SXX: </p>
<hr />
<div>If you just want to play see [[mod list]].<br />
<br />
== Creating mod ==<br />
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.<br />
<br />
Main mod is file called '''mod.json''' and should be placed into main folder of your mod, e.g. '''Mods/myMod/mod.json'''<br />
<br />
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.<br />
<br />
Example of how directory structure of your mod may look like:<br />
<pre><br />
Mods/<br />
myMod/<br />
mod.json<br />
Content/<br />
data/ - unorganized files, mostly bitmap images (.bmp, .png, .pcx)<br />
config/ - json configuration files<br />
maps/ - h3m maps added or modified by mod<br />
music/ - music files. Mp3 is fully supported, ogg may be added if needed<br />
sounds/ - sound files, in wav format.<br />
sprites/ - animation, image sets (H3 .def files or VCMI .json files)<br />
video/ - video files, .bik or .smk<br />
</pre><br />
== Updating mod to next version of VCMI ==<br />
See [[Modding changelog]]<br />
== Creating mod file ==<br />
All VCMI configuration files use [http://en.wikipedia.org/wiki/Json JSON format] so you may want to familiarize yourself with it first.<br />
<br />
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.<br />
<br />
Minimalistic version of this file:<br />
<syntaxhighlight lang="javascript"><br />
{<br />
"name" : "My test mod",<br />
"description" : "My test mod that add a lot of useless stuff into the game"<br />
}<br />
</syntaxhighlight><br />
See [[Mod file Format]] for its full description.<br />
<br />
== Overriding graphical files from Heroes III ==<br />
<br />
Any graphical replacer mods fall under this category. In VCMI directory '''<mod name>/Content''' acts as mod-specific game root directory.<br />
So for example file '''<mod name>/Content/Data/AISHIELD.PNG''' will replace file with same name from '''H3Bitmap.lod''' game archive.<br />
<br />
Any other files can be replaced in exactly same way.<br />
<br />
Note that replacing files from archives requires placing them into specific location:<br />
<pre><br />
H3Bitmap.lod -> Data<br />
H3Sprite.lod -> Sprites<br />
Heroes3.snd -> Sounds<br />
Video.vid -> Video<br />
</pre><br />
This includes archives added by expansions (e.g. '''H3ab_bmp.lod''' uses same rules as '''H3Bitmap.lod''')<br />
<br />
=== Replacing .def animation files ===<br />
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.<br />
<br />
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:<br />
* Replacing one (or several) icons in set<br />
* Replacing animation with fully-colored 32-bit images<br />
<br />
In VCMI these animation files can also be replaced by json description of their content. See [[Animation Format]] for full description of this format.<br />
<br />
Example: replacing single icon<br />
<syntaxhighlight lang="javascript"><br />
{<br />
// List of replaced images<br />
"images" : <br />
[ // Index of replaced frame<br />
{ "frame" : 0, "file" : "HPS000KN.bmp"} <br />
//name of file that will be used as replacement<br />
]<br />
}<br />
</syntaxhighlight><br />
<br />
<br />
"High resolution main menu" mod can be used as example of file replacer mod.<br />
== Packaging mod into archive ==<br />
For distribution it is recommended to package mod into .zip archives. To create .zip archive you need to have file archiver like [http://www.7-zip.org 7zip]<br />
<br />
File structure of packaged mod should look like this<br />
<pre><br />
<modname>.zip/ <- Zip archive with high compression ratio<br />
modname/ <- Archive contains main mod directory <br />
mod.json <- main mod file<br />
Content.zip/ <- Uncompressed archive with all mod data<br />
Data/ <br />
... <- Identical to Content directory<br />
Sprites/<br />
</pre><br />
<br />
You can create such structure using following instructions:<br />
* Go to Mods/<modname>/Content directory<br />
* Select all files in this directory and create archive with following parameters:<br />
** Archive name: Content.zip<br />
** Format: ZIP<br />
** Compression level: None/Store only<br />
* Move created archive into Mods/<modname> directory and remove no longer needed Content directory.<br />
* Go to Mods/ directory<br />
* Create archive from your mod with following parameters:<br />
** Archive name: <modname>.zip<br />
** Format: ZIP<br />
** Compression level: Maximum<br />
<br />
Resulting archive is recommended form for distributing mods for VCMI<br />
== Releasing mods ==<br />
Right now there are 3 ways to bring your mod to players:<br />
* Manual download<br />
* VCMI Repository<br />
* Private repository<br />
=== Manual download ===<br />
You can upload mod into some online file hosting and add link with description of your mod into [[mod list]].<br />
<br />
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:<br />
<!-- Note to editors: do not add any more entries in this list - please, keep it short, no more than 5 links --><br />
* [http://mediafire.com MediaFire]<br />
* [https://dropbox.com Dropbox]<br />
* [https://drive.google.com Google Drive]<br />
* Any other service that does not has aforementioned problems<br />
<br />
=== VCMI Repository ===<br />
Another option is to upload mod into VCMI repository. This will allow players to install mods directly from VCMI Launcher without visiting any 3rd-party sites.<br />
The current adress of VCMI repository is http://download.vcmi.eu/mods/repository/repository.json<br />
<br />
Right now main requirements for a mod to be accepted into VCMI repository are:<br />
* Mod must be complete. For work-in-progress mods it is better to use other way of distribution.<br />
* Mod must met some basic quality requirements. Having high-quality content is always preferable.<br />
* Mod must not contain any errors detectable by validation (console message you may see during loading)<br />
* Music files must be in Ogg/Vorbis format (*.ogg extension)<br />
<br />
To get mod into repository you need to contact person with write access to it. Right now these persons are:<br />
* [http://forum.vcmi.eu/profile.php?mode=viewprofile&u=130 Warmonger]<br />
* [http://forum.vcmi.eu/profile.php?mode=viewprofile&u=336 Ivan]<br />
* [http://forum.vcmi.eu/profile.php?mode=viewprofile&u=1080 Witchking]<br />
<br />
=== Private repository ===<br />
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).<br />
<br />
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.<br />
<br />
To create empty repository you need to:<br />
* Create directory that will contain repository<br />
* Create file named "repository.json" in it<br />
<br />
To add mods into such repository you need to:<br />
* Copy packaged archive <modname>.zip into repository directory<br />
* Copy mod information from mod.json into repository.json<br />
* Add two extra fields about this mod into repository.json:<br />
** "download" - public link that can be used to download the mod, including http:// prefix<br />
** "size" - size of mod, in kilobytes. VCMI will use this number to inform player on size of the mod.<br />
<br />
Example on how mod entry should look in repository.json<br />
<syntaxhighlight lang="javascript"><br />
{<br />
...<br />
"exampleMod" // ID of the mod, lowercase version of mod directory name<br />
{<br />
"name" : "My test mod",<br />
"description" : "My test mod that add a lot of useless stuff into the game",<br />
"author" : "Anonymous",<br />
"contact" : "http://example.com",<br />
"modType" : "Graphical",<br />
"depends" :<br />
[<br />
"baseMod"<br />
],<br />
<br />
"download" : "http://example.com/vcmi/repository/exampleMod.zip",<br />
"size" : 1234 //size, in kilobytes<br />
<br />
//Note that entries that refer to files, e.g. "heroes". "creatures", "artifacts" and such<br />
//are not necessary in repository.json and therefore can be removed<br />
},<br />
...<br />
}<br />
</syntaxhighlight><br />
<br />
When repository is ready you can share public link to repository.json with players. New repositories can added to vcmi launcher from settings tab.<br />
==== Dropbox: enabling public directory ====<br />
New accounts create on Dropbox no longer have Public directory enabled by default. You can enable it using this [https://www.dropbox.com/enable_public_folder link]<br />
<br />
This will give you directory named "Public" as well as option "get public link" for all files inside this directory.<br />
<br />
{{Modding}}</div>SXXhttps://wiki.vcmi.eu/index.php?title=Main_Page&diff=2801Main Page2018-02-21T06:30:36Z<p>SXX: /* Documentation and guidelines for modders */</p>
<hr />
<div>__NOTOC__<br />
= Welcome to VCMI Project Wiki =<br />
<br />
[[VCMI]] is an open-source project aiming to reimplement HMM3:WoG game engine, giving it new and extended possibilities.<br />
<br />
== Latest release ==<br />
Latest released version is <strong>0.99</strong>.<br />
* [https://vcmi.eu/news/vcmi-0.99-release/ Information about release]<br />
<br />
== Documentation and guidelines for users ==<br />
* [[VCMI | General information about VCMI Project]]<br />
* [[Frequently asked questions]]<br />
* [[Engine features]]<br />
* [[Game mechanics]]<br />
* [[Bug reporting guidelines]]<br />
* [[Mod list]]<br />
* [[Cheat codes]]<br />
* Installation guides:<br />
** [[Installation on Windows|Windows]]<br />
** [[Installation on macOS|macOS]]<br />
** [[Installation on Linux|Linux]]<br />
** [[Installation on Android|Android]]<br />
<br />
== Documentation and guidelines for modders ==<br />
* [[Modding guidelines]]<br />
* [[Mods repository]]<br />
* Formats:<br />
** [[Mod file Format]]<br />
** [[Town Format]]<br />
** [[Hero Classes Format]]<br />
** [[Hero Format]]<br />
** [[Creature Format]]<br />
** [[Artifact Format]]<br />
** [[Animation Format]]<br />
** [[Bonus Format]]<br />
** [[Object Format]]<br />
** [[Spell Format]]<br />
** [[Skill Format]]<br />
<br />
== Documentation and guidelines for developers ==<br />
* How to build using CMake:<br />
** [[How_to_build_VCMI_(Linux)|Linux]]<br />
** [[How_to_build_VCMI_(Linux/Cmake/MXE)|Linux/MXE (for Windows)]]<br />
** [[How_to_build_VCMI_(macOS)|macOS]]<br />
** [[How_to_build_VCMI_(Windows/Vcpkg)|Windows]]<br />
* Unsupported build instructions:<br />
** [[How_to_build_VCMI_(Windows/Visual_Studio_2015)|Windows/MSVS (Visual Studio 2015)]]<br />
* [[Coding guidelines]]<br />
* [[Code structure]]<br />
* [[Logging API]]<br />
* [[Bug tracker usage]]<br />
* [[TODO list]]<br />
* Development environment guides:<br />
** [[Development with Qt Creator]]<br />
<br />
== VCMI Places ==<br />
* [https://vcmi.eu/ Website]<br />
* [https://forum.vcmi.eu/ Forum]<br />
* [https://bugs.vcmi.eu/ Bugtracker]<br />
* [https://slack.vcmi.eu/ Slack invite page]<br />
* [https://github.com/vcmi/vcmi GitHub repository]</div>SXXhttps://wiki.vcmi.eu/index.php?title=Mods_repository&diff=2799Mods repository2018-02-21T06:06:41Z<p>SXX: SXX moved page Mods Repository to Mods repository: title fix</p>
<hr />
<div>= Problems =<br />
<br />
Current mod distribution model will eventually face following problems:<br />
<br />
* Lack of changes tracking repository and mods. It's not big deal now, but once we have scripting that will be very important especially if that would be Python or any other language where secure sandboxing is not possible.<br />
* Forward compatibility / backward compatibility. When we start to add new features newer versions of mods won't work in older versions of game. So at least we need to maintain two version of mods index: current stable and develop.<br />
* We need a way to let other contributors to help us with mod maintenance and testing.<br />
<br />
= Suggested solution =<br />
<br />
Mods index JSON hosted in git. Main branch "develop" and there will be branching into 1.00, 1.01 or whatever once they released.<br />
<br />
Launcher should request specific version of JSON index from our server:<br />
<pre><br />
https://repository.vcmi.download/develop.json<br />
https://repository.vcmi.download/0.99.json<br />
https://repository.vcmi.download/0.98.json<br />
</pre><br />
<br />
== Mods hosting ==<br />
All mods hosted in separate repositories on GitHub under separate "vcmi-mods" organization:<br />
<br />
https://github.com/vcmi-mods/adventure-ai-trace<br />
<br />
Trusted community members who can't help with programming can now help us to maintain mods.<br />
<br />
== Mods update submission ==<br />
Once mod updated by creator he or maintainer able to make PR to index JSON. All that needed to be provided is commit hash from appropriate branch. In the end our mod repository will only contain link like that:<br />
<pre><br />
https://mods.vcmi.download/adventure-ai-trace/821190ef5396702bf763c764ed532781b1fc1ce6.zip<br />
</pre><br />
Since archive will be auto-generated by GitHub from commit that also provide us with somewhat secure.<br />
<br />
== Redirect server ==<br />
<br />
That server just going to be redirect Launcher to proper download link like:<br />
<pre><br />
https://repository.vcmi.download/develop.json -> https://raw.githubusercontent.com/vcmi/mods-repository/develop/repository.json<br />
https://repository.vcmi.download/0.99.json -> https://raw.githubusercontent.com/vcmi/mods-repository/0.99/repository.json<br />
https://mods.vcmi.download/adventure-ai-trace/821190ef5396702bf763c764ed532781b1fc1ce6.zip -> https://github.com/vcmi-mods/adventure-ai-trace/archive/821190ef5396702bf763c764ed532781b1fc1ce6.zip<br />
</pre><br />
So far I hope that logic can be implemented in Jekyll and hosted on GitHub Pages, but if not then we'll have something super-lightweight in Nginx Lua.<br />
<br />
== Ideas and possible problems ==<br />
There are few and likely others will appear:<br />
<br />
* Would be great to split repository JSON into multiple small files. Sadly doubt they can be merged with Jekyll.<br />
* GitHub might change how ZIP created and that would change archives checksums. So if we want additional checksums over just commit hash then we need implement them different way.<br />
* We should decide what organization should own mods repository (JSON) and who should be able to commit into it.<br />
<br />
= Short FAQ =<br />
<br />
====What about assets licensing issues?====<br />
First of all it's only problem with some mods and they all pretty much fair use or at least not any worse than any other mod for other game. Just in case it's still better to keep them in separate organization and own repository. In worst case we'll need to host data of some particular mod separately.<br />
<br />
====What if GitHub become less generous?====<br />
It's totally possible that eventually GitHub might forbid direct RAW / ZIP access, but so far there is great amount of far more popular projects using it and VCMI unlikely ever become popular enough to reach any limits.<br />
<br />
Even if that happen we could rapidly redirect downloads to competing services such as GitLab / BitBucket by simply keeping repository clones there. In same time infrastructure could always be on GitHub.<br />
<br />
====WTF is vcmi.download?====<br />
That is my domain that I registered and pre-paid until end of 2026. I think it's smart to keep any gray area files outside of our main domain.</div>SXXhttps://wiki.vcmi.eu/index.php?title=Mods_Repository&diff=2800Mods Repository2018-02-21T06:06:41Z<p>SXX: SXX moved page Mods Repository to Mods repository: title fix</p>
<hr />
<div>#REDIRECT [[Mods repository]]</div>SXXhttps://wiki.vcmi.eu/index.php?title=Modding_guidelines&diff=2798Modding guidelines2018-02-21T06:01:00Z<p>SXX: </p>
<hr />
<div>If you're player see [[mod list]].<br />
<br />
== Creating mod ==<br />
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.<br />
<br />
Main mod is file called '''mod.json''' and should be placed into main folder of your mod, e.g. '''Mods/myMod/mod.json'''<br />
<br />
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.<br />
<br />
Example of how directory structure of your mod may look like:<br />
<pre><br />
Mods/<br />
myMod/<br />
mod.json<br />
Content/<br />
data/ - unorganized files, mostly bitmap images (.bmp, .png, .pcx)<br />
config/ - json configuration files<br />
maps/ - h3m maps added or modified by mod<br />
music/ - music files. Mp3 is fully supported, ogg may be added if needed<br />
sounds/ - sound files, in wav format.<br />
sprites/ - animation, image sets (H3 .def files or VCMI .json files)<br />
video/ - video files, .bik or .smk<br />
</pre><br />
== Updating mod to next version of VCMI ==<br />
See [[Modding changelog]]<br />
== Creating mod file ==<br />
All VCMI configuration files use [http://en.wikipedia.org/wiki/Json JSON format] so you may want to familiarize yourself with it first.<br />
<br />
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.<br />
<br />
Minimalistic version of this file:<br />
<syntaxhighlight lang="javascript"><br />
{<br />
"name" : "My test mod",<br />
"description" : "My test mod that add a lot of useless stuff into the game"<br />
}<br />
</syntaxhighlight><br />
See [[Mod file Format]] for its full description.<br />
<br />
== Overriding graphical files from Heroes III ==<br />
<br />
Any graphical replacer mods fall under this category. In VCMI directory '''<mod name>/Content''' acts as mod-specific game root directory.<br />
So for example file '''<mod name>/Content/Data/AISHIELD.PNG''' will replace file with same name from '''H3Bitmap.lod''' game archive.<br />
<br />
Any other files can be replaced in exactly same way.<br />
<br />
Note that replacing files from archives requires placing them into specific location:<br />
<pre><br />
H3Bitmap.lod -> Data<br />
H3Sprite.lod -> Sprites<br />
Heroes3.snd -> Sounds<br />
Video.vid -> Video<br />
</pre><br />
This includes archives added by expansions (e.g. '''H3ab_bmp.lod''' uses same rules as '''H3Bitmap.lod''')<br />
<br />
=== Replacing .def animation files ===<br />
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.<br />
<br />
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:<br />
* Replacing one (or several) icons in set<br />
* Replacing animation with fully-colored 32-bit images<br />
<br />
In VCMI these animation files can also be replaced by json description of their content. See [[Animation Format]] for full description of this format.<br />
<br />
Example: replacing single icon<br />
<syntaxhighlight lang="javascript"><br />
{<br />
// List of replaced images<br />
"images" : <br />
[ // Index of replaced frame<br />
{ "frame" : 0, "file" : "HPS000KN.bmp"} <br />
//name of file that will be used as replacement<br />
]<br />
}<br />
</syntaxhighlight><br />
<br />
<br />
"High resolution main menu" mod can be used as example of file replacer mod.<br />
== Packaging mod into archive ==<br />
For distribution it is recommended to package mod into .zip archives. To create .zip archive you need to have file archiver like [http://www.7-zip.org 7zip]<br />
<br />
File structure of packaged mod should look like this<br />
<pre><br />
<modname>.zip/ <- Zip archive with high compression ratio<br />
modname/ <- Archive contains main mod directory <br />
mod.json <- main mod file<br />
Content.zip/ <- Uncompressed archive with all mod data<br />
Data/ <br />
... <- Identical to Content directory<br />
Sprites/<br />
</pre><br />
<br />
You can create such structure using following instructions:<br />
* Go to Mods/<modname>/Content directory<br />
* Select all files in this directory and create archive with following parameters:<br />
** Archive name: Content.zip<br />
** Format: ZIP<br />
** Compression level: None/Store only<br />
* Move created archive into Mods/<modname> directory and remove no longer needed Content directory.<br />
* Go to Mods/ directory<br />
* Create archive from your mod with following parameters:<br />
** Archive name: <modname>.zip<br />
** Format: ZIP<br />
** Compression level: Maximum<br />
<br />
Resulting archive is recommended form for distributing mods for VCMI<br />
== Releasing mods ==<br />
Right now there are 3 ways to bring your mod to players:<br />
* Manual download<br />
* VCMI Repository<br />
* Private repository<br />
=== Manual download ===<br />
You can upload mod into some online file hosting and add link with description of your mod into [[mod list]].<br />
<br />
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:<br />
<!-- Note to editors: do not add any more entries in this list - please, keep it short, no more than 5 links --><br />
* [http://mediafire.com MediaFire]<br />
* [https://dropbox.com Dropbox]<br />
* [https://drive.google.com Google Drive]<br />
* Any other service that does not has aforementioned problems<br />
<br />
=== VCMI Repository ===<br />
Another option is to upload mod into VCMI repository. This will allow players to install mods directly from VCMI Launcher without visiting any 3rd-party sites.<br />
The current adress of VCMI repository is http://download.vcmi.eu/mods/repository/repository.json<br />
<br />
Right now main requirements for a mod to be accepted into VCMI repository are:<br />
* Mod must be complete. For work-in-progress mods it is better to use other way of distribution.<br />
* Mod must met some basic quality requirements. Having high-quality content is always preferable.<br />
* Mod must not contain any errors detectable by validation (console message you may see during loading)<br />
* Music files must be in Ogg/Vorbis format (*.ogg extension)<br />
<br />
To get mod into repository you need to contact person with write access to it. Right now these persons are:<br />
* [http://forum.vcmi.eu/profile.php?mode=viewprofile&u=130 Warmonger]<br />
* [http://forum.vcmi.eu/profile.php?mode=viewprofile&u=336 Ivan]<br />
* [http://forum.vcmi.eu/profile.php?mode=viewprofile&u=1080 Witchking]<br />
<br />
=== Private repository ===<br />
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).<br />
<br />
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.<br />
<br />
To create empty repository you need to:<br />
* Create directory that will contain repository<br />
* Create file named "repository.json" in it<br />
<br />
To add mods into such repository you need to:<br />
* Copy packaged archive <modname>.zip into repository directory<br />
* Copy mod information from mod.json into repository.json<br />
* Add two extra fields about this mod into repository.json:<br />
** "download" - public link that can be used to download the mod, including http:// prefix<br />
** "size" - size of mod, in kilobytes. VCMI will use this number to inform player on size of the mod.<br />
<br />
Example on how mod entry should look in repository.json<br />
<syntaxhighlight lang="javascript"><br />
{<br />
...<br />
"exampleMod" // ID of the mod, lowercase version of mod directory name<br />
{<br />
"name" : "My test mod",<br />
"description" : "My test mod that add a lot of useless stuff into the game",<br />
"author" : "Anonymous",<br />
"contact" : "http://example.com",<br />
"modType" : "Graphical",<br />
"depends" :<br />
[<br />
"baseMod"<br />
],<br />
<br />
"download" : "http://example.com/vcmi/repository/exampleMod.zip",<br />
"size" : 1234 //size, in kilobytes<br />
<br />
//Note that entries that refer to files, e.g. "heroes". "creatures", "artifacts" and such<br />
//are not necessary in repository.json and therefore can be removed<br />
},<br />
...<br />
}<br />
</syntaxhighlight><br />
<br />
When repository is ready you can share public link to repository.json with players. New repositories can added to vcmi launcher from settings tab.<br />
==== Dropbox: enabling public directory ====<br />
New accounts create on Dropbox no longer have Public directory enabled by default. You can enable it using this [https://www.dropbox.com/enable_public_folder link]<br />
<br />
This will give you directory named "Public" as well as option "get public link" for all files inside this directory.<br />
<br />
{{Modding}}</div>SXXhttps://wiki.vcmi.eu/index.php?title=Coding_guidelines&diff=2794Coding guidelines2018-02-11T15:35:16Z<p>SXX: /* Functions and interfaces */</p>
<hr />
<div>== C++ Standard ==<br />
VCMI implementation bases on C++11 standard. Any feature is acceptable as long as it's will pass build on our CI, but there is list below on what is already being used.<br />
<br />
Compilers we currently target are: GCC 4.8+, Clang 3.4+, MSVC 19.0+ (VS2015). You can find information about extensions and compiler support at [http://en.cppreference.com/w/cpp/compiler_support].<br />
<br />
=== Currently used C++11 features ===<br />
* auto keyword,<br />
* decltype,<br />
* lambda expressions and closures,<br />
* local and unnamed types as template arguments,<br />
* new function declaration syntax for deduced return types (returned type after argument list),<br />
* right angle brackets,<br />
* r-value references and std::move,<br />
* static assert,<br />
* nullptr keyword,<br />
* range-based for loops,<br />
* forward enum declarations,<br />
* strongly-typed enums,<br />
* override and final,<br />
* explicit conversion operators,<br />
* initializer lists,<br />
* raw string literals,<br />
* variadic templates,<br />
* defaulted and deleted functions (except for defaulted move functions),<br />
* non-static data member initializers,<br />
* extended friend Declarations,<br />
* template aliases.<br />
* atomic operations.<br />
<br />
== Style Guidelines ==<br />
<br />
<br />
In order to keep the code consistent, please use the following conventions. From here on `good' and `bad' are used to attribute things that would make the coding style match, or not match. It is not a judgment call on your coding abilities, but more of a style and look call. Please try to follow these guidelines to ensure prettiness.<br />
<br />
<br />
=== Indentation ===<br />
<br />
Use tabs for indentation. If you are modifying someone else's code, try to keep the coding style similar.<br />
<br />
=== Where to put braces ===<br />
<br />
Inside a code block put the opening brace on the next line after the current statement:<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
if(a) <br />
{<br />
code();<br />
code();<br />
}<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
if(a) {<br />
code();<br />
code();<br />
}<br />
</syntaxhighlight><br />
<br />
Avoid using unnecessary open/close braces, vertical space is usually limited: <br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
if(a)<br />
code();</syntaxhighlight><br />
<br />
Bad: <br />
<syntaxhighlight lang="cpp"><br />
if(a) {<br />
code();<br />
}<br />
</syntaxhighlight><br />
<br />
Unless there are either multiple hierarchical conditions being used or that the condition cannot fit into a single line. <br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
if(a)<br />
{<br />
if(b)<br />
code();<br />
}<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
if(a)<br />
if(b)<br />
code();<br />
</syntaxhighlight><br />
<br />
If there are brackets inside the body, outside brackets are required.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
if(a)<br />
{<br />
for(auto elem : list)<br />
{<br />
code();<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
if(a)<br />
for(auto elem : list)<br />
{<br />
code();<br />
}<br />
<br />
</syntaxhighlight><br />
<br />
<br />
If "else" branch has brackets then "if" should also have brackets even if it is one line.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
if(a)<br />
{<br />
code();<br />
}<br />
else<br />
{<br />
for(auto elem : list)<br />
{<br />
code();<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
if(a)<br />
code();<br />
else<br />
{<br />
for(auto elem : list)<br />
{<br />
code();<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
If you intentionally want to avoid usage of "else if" and keep if body indent make sure to use braces.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
if(a)<br />
{<br />
code();<br />
}<br />
else<br />
{<br />
if(b)<br />
code();<br />
}<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
if(a)<br />
code();<br />
else<br />
if(b)<br />
code();<br />
</syntaxhighlight><br />
<br />
When defining a method, use a new line for the brace, like this: <br />
<br />
Good: <br />
<syntaxhighlight lang="cpp"><br />
void method()<br />
{<br />
}<br />
</syntaxhighlight><br />
<br />
Bad: <br />
<syntaxhighlight lang="cpp"><br />
void Method() {<br />
}<br />
</syntaxhighlight><br />
<br />
=== Use whitespace for clarity ===<br />
<br />
Use white space in expressions liberally, except in the presence of parenthesis.<br />
<br />
'''Good:'''<br />
<syntaxhighlight lang="cpp"><br />
if(a + 5 > method(blah('a') + 4))<br />
foo += 24;<br />
</syntaxhighlight><br />
<br />
'''Bad:'''<br />
<syntaxhighlight lang="cpp"><br />
if(a+5>method(blah('a')+4))<br />
foo+=24;<br />
</syntaxhighlight><br />
<br />
Between if, for, while,.. and the opening brace there shouldn't be a whitespace. The keywords are highlighted, so they don't need further separation.<br />
<br />
=== Where to put spaces ===<br />
<br />
Use a space before and after the address or pointer character in a pointer declaration.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
CIntObject * images[100];<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
CIntObject* images[100]; or<br />
CIntObject *images[100];<br />
</syntaxhighlight><br />
<br />
Do not use spaces before parentheses.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
if(a)<br />
code();<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
if (a)<br />
code();<br />
</syntaxhighlight><br />
<br />
Do not use extra spaces around conditions inside parentheses.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
if(a && b)<br />
code();<br />
<br />
if(a && (b || c))<br />
code();<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
if( a && b )<br />
code();<br />
<br />
if(a && ( b || c ))<br />
code();<br />
</syntaxhighlight><br />
<br />
Do not use more than one space between operators.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
if((a && b) || (c + 1 == d))<br />
code();<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
if((a && b) || (c + 1 == d))<br />
code();<br />
<br />
if((a && b) || (c + 1 == d))<br />
code();<br />
</syntaxhighlight><br />
<br />
=== Where to use parentheses ===<br />
<br />
When allocating objects, don't use parentheses for creating stack-based objects by zero param c-tors to avoid c++ most vexing parse and use parentheses for creating heap-based objects.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
std::vector<int> v; <br />
CGBoat btn = new CGBoat();<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
std::vector<int> v(); // shouldn't compile anyway <br />
CGBoat btn = new CGBoat;<br />
</syntaxhighlight><br />
<br />
Avoid overuse of parentheses:<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
if(a && (b + 1))<br />
return c == d;<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
if((a && (b + 1)))<br />
return (c == d);<br />
</syntaxhighlight><br />
<br />
=== Class declaration ===<br />
<br />
Base class list must be on same line with class name.<br />
<br />
<syntaxhighlight lang="cpp"><br />
class CClass : public CClassBaseOne, public CClassBaseOne<br />
{<br />
int id;<br />
bool parameter;<br />
<br />
public:<br />
CClass();<br />
~CClass();<br />
};<br />
</syntaxhighlight><br />
<br />
When 'private:', 'public:' and other labels are not on the line after opening brackets there must be a new line before them.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
class CClass<br />
{<br />
int id;<br />
<br />
public:<br />
CClass();<br />
};<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
class CClass<br />
{<br />
int id;<br />
public:<br />
CClass();<br />
};<br />
</syntaxhighlight><br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
class CClass<br />
{<br />
protected:<br />
int id;<br />
<br />
public:<br />
CClass();<br />
};<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
class CClass<br />
{<br />
<br />
protected:<br />
int id;<br />
<br />
public:<br />
CClass();<br />
};<br />
</syntaxhighlight><br />
<br />
=== Constructor base class and member initialization ===<br />
<br />
Constructor member and base class initialization must be on new line, indented with tab with leading colon.<br />
<syntaxhighlight lang="cpp"><br />
CClass::CClass()<br />
: CClassBaseOne(true, nullptr), id(0), bool parameters(false)<br />
{<br />
code();<br />
}<br />
</syntaxhighlight><br />
<br />
=== Switch statement ===<br />
<br />
Switch statements have the case at the same indentation as the switch.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
switch(alignment)<br />
{<br />
case EAlignment::EVIL:<br />
do_that();<br />
break;<br />
case EAlignment::GOOD:<br />
do_that();<br />
break;<br />
case EAlignment::NEUTRAL:<br />
do_that();<br />
break;<br />
default:<br />
do_that();<br />
break;<br />
}<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
switch(alignment)<br />
{<br />
case EAlignment::EVIL:<br />
do_that();<br />
break;<br />
default:<br />
do_that();<br />
break;<br />
}<br />
<br />
switch(alignment)<br />
{<br />
case EAlignment::EVIL:<br />
do_that();<br />
break;<br />
default:<br />
do_that();<br />
break;<br />
}<br />
<br />
switch(alignment)<br />
{<br />
case EAlignment::EVIL:<br />
{<br />
do_that();<br />
}<br />
break;<br />
default:<br />
{ <br />
do_that();<br />
}<br />
break;<br />
}<br />
</syntaxhighlight><br />
<br />
=== Lambda expressions ===<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
auto lambda = [this, a, &b](int3 & tile, int index) -> bool<br />
{<br />
do_that();<br />
};<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
auto lambda = [this,a,&b](int3 & tile, int index)->bool{do_that();};<br />
</syntaxhighlight><br />
<br />
Empty parameter list is required even if function takes no arguments.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
auto lambda = []()<br />
{<br />
do_that();<br />
};<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
auto lambda = []<br />
{<br />
do_that();<br />
};<br />
</syntaxhighlight><br />
<br />
Do not use inline lambda expressions inside if-else, for and other conditions.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
auto lambda = []()<br />
{<br />
do_that();<br />
};<br />
if(lambda)<br />
{<br />
code();<br />
}<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
if([]()<br />
{<br />
do_that();<br />
})<br />
{<br />
code();<br />
}<br />
</syntaxhighlight><br />
<br />
Do not pass inline lambda expressions as parameter unless it's the last parameter.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
auto lambda = []()<br />
{<br />
do_that();<br />
};<br />
obj->someMethod(lambda, true);<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
obj->someMethod([]()<br />
{<br />
do_that();<br />
}, true);<br />
</syntaxhighlight><br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
obj->someMethod(true, []()<br />
{<br />
do_that();<br />
});<br />
</syntaxhighlight><br />
<br />
=== Serialization ===<br />
<br />
Serialization of each element must be on it's own line since this make debugging easier.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
template <typename Handler> void serialize(Handler & h, const int version)<br />
{<br />
h & identifier;<br />
h & description;<br />
h & name;<br />
h & dependencies;<br />
}<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
template <typename Handler> void serialize(Handler & h, const int version)<br />
{<br />
h & identifier & description & name & dependencies;<br />
}<br />
</syntaxhighlight><br />
<br />
Save backward compatibility code is exception when extra brackets are always useful.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
template <typename Handler> void serialize(Handler & h, const int version)<br />
{<br />
h & identifier;<br />
h & description;<br />
if(version >= 123)<br />
{<br />
h & totalValue;<br />
}<br />
else if(!h.saving)<br />
{<br />
totalValue = 200;<br />
}<br />
h & name;<br />
h & dependencies;<br />
}<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
template <typename Handler> void serialize(Handler & h, const int version)<br />
{<br />
h & identifier;<br />
h & description;<br />
if(version >= 123)<br />
h & totalValue;<br />
else if(!h.saving)<br />
totalValue = 200;<br />
h & name;<br />
h & dependencies;<br />
}<br />
</syntaxhighlight><br />
<br />
=== File headers ===<br />
<br />
For any new files, please paste the following info block at the very top of the source file:<br />
<syntaxhighlight lang="cpp">/*<br />
* Name_of_File.h, part of VCMI engine<br />
*<br />
* Authors: listed in file AUTHORS in main folder<br />
*<br />
* License: GNU General Public License v2.0 or later<br />
* Full text of license available in license.txt file, in main folder<br />
*<br />
*/</syntaxhighlight><br />
The above notice have to be included both in header and source files (.h/.cpp).<br />
<br />
<br />
=== Code order in files ===<br />
<br />
For any header or source file code must be in following order:<br />
<br />
# Licensing information<br />
# pragma once preprocessor directive<br />
# include directives<br />
# Forward declarations<br />
# All other code<br />
<syntaxhighlight lang="cpp">/*<br />
* Name_of_File.h, part of VCMI engine<br />
*<br />
* Authors: listed in file AUTHORS in main folder<br />
*<br />
* License: GNU General Public License v2.0 or later<br />
* Full text of license available in license.txt file, in main folder<br />
*<br />
*/<br />
#pragma once<br />
<br />
#include "Header.h"<br />
<br />
class CGObjectInstance;<br />
struct CPackForClient;</syntaxhighlight><br />
<br />
=== Where and how to comment ===<br />
<br />
If you comment on the same line with code there must be one single space between code and slashes.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
if(a)<br />
{<br />
code(); //Do something<br />
}<br />
else // Do something.<br />
{<br />
code(); // Do something.<br />
}<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
if(a)<br />
{<br />
code();//Do something<br />
}<br />
else // Do something.<br />
{<br />
code(); // TODO:<br />
}<br />
</syntaxhighlight><br />
<br />
If you add single-line comment on own line slashes must have same indent as code around:<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
// Do something<br />
if(a)<br />
{<br />
//Do something<br />
for(auto item : list)<br />
code();<br />
}<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
// Do something<br />
if(a)<br />
{<br />
//Do something<br />
for(auto item : list)<br />
code();<br />
}<br />
</syntaxhighlight><br />
<br />
Avoid comments inside multi-line if-else conditions. If your conditions are too hard to understand without additional comments this usually means that code need refactoring. Example given below is need improvement though. '''FIXME'''<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
bool isMyHeroAlive = a && b || (c + 1 > 15);<br />
bool canMyHeroMove = myTurn && hero.movePoints > 0;<br />
if(isMyHeroAlive && canMyHeroMove)<br />
{<br />
code();<br />
}<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
if((a && b || (c + 1 > 15)) //Check if hero still alive<br />
&& myTurn && hero.movePoints > 0) //Check if hero can move<br />
{<br />
code();<br />
}<br />
</syntaxhighlight><br />
<br />
You should write a comment before the class definition which describes shortly the class. 1-2 sentences are enough. Methods and class data members should be commented if they aren't self-describing only. Getters/Setters, simple methods where the purpose is clear or similar methods shouldn't be commented, because vertical space is usually limited. The style of documentation comments should be the three slashes-style: ///. <br />
<br />
<syntaxhighlight lang="cpp"><br />
/// Returns true if a debug/trace log message will be logged, false if not.<br />
/// Useful if performance is important and concatenating the log message is a expensive task.<br />
bool isDebugEnabled() const;<br />
bool isTraceEnabled() const;<br />
</syntaxhighlight><br />
<br />
The above example doesn't follow a strict scheme on how to comment a method. It describes two methods in one go. Comments should be kept short.<br />
<br />
If you need a more detailed description for a method you can use such style:<br />
<syntaxhighlight lang="cpp"><br />
/// <A short one line description><br />
///<br />
/// <Longer description><br />
/// <May span multiple lines or paragraphs as needed><br />
///<br />
/// @param Description of method's or function's input parameter<br />
/// @param ...<br />
/// @return Description of the return value<br />
</syntaxhighlight><br />
<br />
A good essay about writing comments: [http://ardalis.com/when-to-comment-your-code]<br />
<br />
=== Casing ===<br />
<br />
<br />
Local variables and methods start with a lowercase letter and use the camel casing. Classes/Structs start with an uppercase letter and use the camel casing as well. Macros and constants are written uppercase. <br />
<br />
<br />
=== Line length ===<br />
<br />
The line length for c++ source code is 120 columns. If your function declaration arguments go beyond this point, please align your arguments to match the opening brace. For best results use the same number of tabs used on the first line followed by enough spaces to align the arguments. <br />
<br />
<br />
=== Warnings ===<br />
<br />
Avoid use of #pragma to disable warnings. Compile at warning level 3.<br />
Avoid commiting code with new warnings.<br />
<br />
=== Type naming ===<br />
<br />
Classes are prefixed with an upper C, interfaces with an upper I, enumerations with an upper E, structs without an prefix and typedefs with an upper T<br />
<br />
=== File/directory naming ===<br />
<br />
Compilation units(.cpp,.h files) start with a uppercase letter and are named like the name of a class which resides in that file if possible. Header only files start with a uppercase letter. JSON files start with a lowercase letter and use the camel casing.<br />
<br />
Directories start with a lowercase letter and use the camel casing where necessary.<br />
<br />
<br />
=== Logging ===<br />
<br />
Outdated. There is separate entry for [[Logging API]]<br />
<br />
If you want to trace the control flow of VCMI, then you should use the macro LOG_TRACE or LOG_TRACE_PARAMS. The first one prints a message when the function is entered or leaved. The name of the function will also be logged. In addition to this the second macro, let's you specify parameters which you want to print. You should print traces with parameters like this:<br />
<br />
<syntaxhighlight lang="cpp">LOG_TRACE_PARAMS(logGlobal, "hero '%s', spellId '%d', pos '%s'.", hero, spellId, pos);</syntaxhighlight><br />
<br />
When using the macro every "simple" parameter should be logged. The parameter can be a number, a string or a type with a ostream operator<<. You should not log contents of a whole text file, a byte array or sth. like this. If there is a simple type with a few members you want to log, you should write an ostream operator<<. The produced message can look like this:<br />
<br />
<tt>{BattleAction: side '0', stackNumber '1', actionType 'Walk and attack', destinationTile '{BattleHex: x '7', y '1', hex '24'}', additionalInfo '7', selectedStack '-1'}</tt><br />
<br />
The name of the type should be logged first, e.g. {TYPE_NAME: members...}. The members of the object will be logged like logging trace parameters. Collection types (vector, list, ...) should be logged this way: [{BattleHex: ...}, {...}]<br />
There is no format which has to be followed strictly, so if there is a reason to format members/objects in a different way, then this is ok.<br />
<br />
== Best practices ==<br />
<br />
<br />
=== Avoid code duplication ===<br />
<br />
Avoid code duplication or don't repeat yourself(DRY) is the most important aspect in programming. Code duplication of any kind can lead to inconsistency and is much harder to maintain. If one part of the system gets changed you have to change the code in several places. This process is error-prone and leads often to problems. Here you can read more about the DRY principle: [http://en.wikipedia.org/wiki/Don%27t_repeat_yourself http://en.wikipedia.org/wiki/Don%27t_repeat_yourself]<br />
<br />
=== Do not use uncommon abbrevations ===<br />
<br />
Do not use uncommon abbrevations for class, method, parameter and global object names.<br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
CArt * getRandomArt(...)<br />
class CIntObject<br />
</syntaxhighlight><br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
CArtifact * getRandomArtifact(...)<br />
class CInterfaceObject<br />
</syntaxhighlight><br />
<br />
=== Loop handling ===<br />
<br />
Use range-based for loops. It should be used in any case except you absolutely need iterator, then you may use a simple for loop.<br />
<br />
The loop counter should be of type int, unless you are sure you won't need negative indices -- then use size_t.<br />
<br />
=== Include guards ===<br />
<br />
Use #pragma once instead of the traditional #ifndef/#define/#endif include guards.<br />
<br />
<br />
=== Pre compiled header file ===<br />
<br />
The header StdInc.h should be included in every compilation unit. It has to be included before any C macro and before any c++ statements. Pre compiled header should not be changed, except any important thing is missing.<br />
The StdInc includes most Boost libraries and nearly all standard STL and C libraries, so you don’t have to include them by yourself. <br />
<br />
<br />
=== Enumeration handling ===<br />
<br />
Do not declare enumerations in global namespace. It is better to use strongly typed enum or to wrap them in class or namespace to avoid polluting global namespace:<br />
<br />
<syntaxhighlight lang="cpp"><br />
enum class EAlignment<br />
{<br />
GOOD,<br />
EVIL,<br />
NEUTRAL<br />
};<br />
<br />
namespace EAlignment<br />
{<br />
enum EAlignment<br />
{<br />
GOOD, EVIL, NEUTRAL<br />
};<br />
}<br />
</syntaxhighlight><br />
<br />
=== Avoid senseless comments ===<br />
<br />
If the comment duplicates the name of commented member, it's better if it wouldn't exist at all. It just increases maintenance cost.<br />
Bad:<br />
<syntaxhighlight lang="cpp">size_t getHeroesCount(); //gets count of heroes (surprise?)</syntaxhighlight><br />
<br />
<br />
=== Class handling ===<br />
<br />
There is no definitive rule which has to be followed strictly. You can freely decide if you want to pack your own classes, where you are programming on, all in one file or each in one file. It's more important that you feel comfortable with the code, than consistency overall the project. VCMI has several container class files, so if you got one additional class to them than just add it to them instead of adding new files.<br />
<br />
=== Functions and interfaces ===<br />
<br />
Don't return const objects or primitive types from functions -- it's pointless. Also, don't return pointers to non-const game data objects from callbacks to player interfaces.<br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
const std::vector<CGObjectInstance *> guardingCreatures(int3 pos) const;<br />
</syntaxhighlight><br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
std::vector<const CGObjectInstance *> guardingCreatures(int3 pos) const;<br />
</syntaxhighlight><br />
<br />
== Sources ==<br />
[http://www.mono-project.com/Coding_Guidelines Mono project coding guidelines]</div>SXXhttps://wiki.vcmi.eu/index.php?title=Coding_guidelines&diff=2786Coding guidelines2018-02-05T14:24:50Z<p>SXX: /* C++ Standard */</p>
<hr />
<div>== C++ Standard ==<br />
VCMI implementation bases on C++11 standard. Any feature is acceptable as long as it's will pass build on our CI, but there is list below on what is already being used.<br />
<br />
Compilers we currently target are: GCC 4.8+, Clang 3.4+, MSVC 19.0+ (VS2015). You can find information about extensions and compiler support at [http://en.cppreference.com/w/cpp/compiler_support].<br />
<br />
=== Currently used C++11 features ===<br />
* auto keyword,<br />
* decltype,<br />
* lambda expressions and closures,<br />
* local and unnamed types as template arguments,<br />
* new function declaration syntax for deduced return types (returned type after argument list),<br />
* right angle brackets,<br />
* r-value references and std::move,<br />
* static assert,<br />
* nullptr keyword,<br />
* range-based for loops,<br />
* forward enum declarations,<br />
* strongly-typed enums,<br />
* override and final,<br />
* explicit conversion operators,<br />
* initializer lists,<br />
* raw string literals,<br />
* variadic templates,<br />
* defaulted and deleted functions (except for defaulted move functions),<br />
* non-static data member initializers,<br />
* extended friend Declarations,<br />
* template aliases.<br />
* atomic operations.<br />
<br />
== Style Guidelines ==<br />
<br />
<br />
In order to keep the code consistent, please use the following conventions. From here on `good' and `bad' are used to attribute things that would make the coding style match, or not match. It is not a judgment call on your coding abilities, but more of a style and look call. Please try to follow these guidelines to ensure prettiness.<br />
<br />
<br />
=== Indentation ===<br />
<br />
Use tabs for indentation. If you are modifying someone else's code, try to keep the coding style similar.<br />
<br />
=== Where to put braces ===<br />
<br />
Inside a code block put the opening brace on the next line after the current statement:<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
if(a) <br />
{<br />
code();<br />
code();<br />
}<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
if(a) {<br />
code();<br />
code();<br />
}<br />
</syntaxhighlight><br />
<br />
Avoid using unnecessary open/close braces, vertical space is usually limited: <br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
if(a)<br />
code();</syntaxhighlight><br />
<br />
Bad: <br />
<syntaxhighlight lang="cpp"><br />
if(a) {<br />
code();<br />
}<br />
</syntaxhighlight><br />
<br />
Unless there are either multiple hierarchical conditions being used or that the condition cannot fit into a single line. <br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
if(a)<br />
{<br />
if(b)<br />
code();<br />
}<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
if(a)<br />
if(b)<br />
code();<br />
</syntaxhighlight><br />
<br />
If there are brackets inside the body, outside brackets are required.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
if(a)<br />
{<br />
for(auto elem : list)<br />
{<br />
code();<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
if(a)<br />
for(auto elem : list)<br />
{<br />
code();<br />
}<br />
<br />
</syntaxhighlight><br />
<br />
<br />
If "else" branch has brackets then "if" should also have brackets even if it is one line.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
if(a)<br />
{<br />
code();<br />
}<br />
else<br />
{<br />
for(auto elem : list)<br />
{<br />
code();<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
if(a)<br />
code();<br />
else<br />
{<br />
for(auto elem : list)<br />
{<br />
code();<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
If you intentionally want to avoid usage of "else if" and keep if body indent make sure to use braces.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
if(a)<br />
{<br />
code();<br />
}<br />
else<br />
{<br />
if(b)<br />
code();<br />
}<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
if(a)<br />
code();<br />
else<br />
if(b)<br />
code();<br />
</syntaxhighlight><br />
<br />
When defining a method, use a new line for the brace, like this: <br />
<br />
Good: <br />
<syntaxhighlight lang="cpp"><br />
void method()<br />
{<br />
}<br />
</syntaxhighlight><br />
<br />
Bad: <br />
<syntaxhighlight lang="cpp"><br />
void Method() {<br />
}<br />
</syntaxhighlight><br />
<br />
=== Use whitespace for clarity ===<br />
<br />
Use white space in expressions liberally, except in the presence of parenthesis.<br />
<br />
'''Good:'''<br />
<syntaxhighlight lang="cpp"><br />
if(a + 5 > method(blah('a') + 4))<br />
foo += 24;<br />
</syntaxhighlight><br />
<br />
'''Bad:'''<br />
<syntaxhighlight lang="cpp"><br />
if(a+5>method(blah('a')+4))<br />
foo+=24;<br />
</syntaxhighlight><br />
<br />
Between if, for, while,.. and the opening brace there shouldn't be a whitespace. The keywords are highlighted, so they don't need further separation.<br />
<br />
=== Where to put spaces ===<br />
<br />
Use a space before and after the address or pointer character in a pointer declaration.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
CIntObject * images[100];<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
CIntObject* images[100]; or<br />
CIntObject *images[100];<br />
</syntaxhighlight><br />
<br />
Do not use spaces before parentheses.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
if(a)<br />
code();<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
if (a)<br />
code();<br />
</syntaxhighlight><br />
<br />
Do not use extra spaces around conditions inside parentheses.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
if(a && b)<br />
code();<br />
<br />
if(a && (b || c))<br />
code();<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
if( a && b )<br />
code();<br />
<br />
if(a && ( b || c ))<br />
code();<br />
</syntaxhighlight><br />
<br />
Do not use more than one space between operators.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
if((a && b) || (c + 1 == d))<br />
code();<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
if((a && b) || (c + 1 == d))<br />
code();<br />
<br />
if((a && b) || (c + 1 == d))<br />
code();<br />
</syntaxhighlight><br />
<br />
=== Where to use parentheses ===<br />
<br />
When allocating objects, don't use parentheses for creating stack-based objects by zero param c-tors to avoid c++ most vexing parse and use parentheses for creating heap-based objects.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
std::vector<int> v; <br />
CGBoat btn = new CGBoat();<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
std::vector<int> v(); // shouldn't compile anyway <br />
CGBoat btn = new CGBoat;<br />
</syntaxhighlight><br />
<br />
Avoid overuse of parentheses:<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
if(a && (b + 1))<br />
return c == d;<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
if((a && (b + 1)))<br />
return (c == d);<br />
</syntaxhighlight><br />
<br />
=== Class declaration ===<br />
<br />
Base class list must be on same line with class name.<br />
<br />
<syntaxhighlight lang="cpp"><br />
class CClass : public CClassBaseOne, public CClassBaseOne<br />
{<br />
int id;<br />
bool parameter;<br />
<br />
public:<br />
CClass();<br />
~CClass();<br />
};<br />
</syntaxhighlight><br />
<br />
When 'private:', 'public:' and other labels are not on the line after opening brackets there must be a new line before them.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
class CClass<br />
{<br />
int id;<br />
<br />
public:<br />
CClass();<br />
};<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
class CClass<br />
{<br />
int id;<br />
public:<br />
CClass();<br />
};<br />
</syntaxhighlight><br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
class CClass<br />
{<br />
protected:<br />
int id;<br />
<br />
public:<br />
CClass();<br />
};<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
class CClass<br />
{<br />
<br />
protected:<br />
int id;<br />
<br />
public:<br />
CClass();<br />
};<br />
</syntaxhighlight><br />
<br />
=== Constructor base class and member initialization ===<br />
<br />
Constructor member and base class initialization must be on new line, indented with tab with leading colon.<br />
<syntaxhighlight lang="cpp"><br />
CClass::CClass()<br />
: CClassBaseOne(true, nullptr), id(0), bool parameters(false)<br />
{<br />
code();<br />
}<br />
</syntaxhighlight><br />
<br />
=== Switch statement ===<br />
<br />
Switch statements have the case at the same indentation as the switch.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
switch(alignment)<br />
{<br />
case EAlignment::EVIL:<br />
do_that();<br />
break;<br />
case EAlignment::GOOD:<br />
do_that();<br />
break;<br />
case EAlignment::NEUTRAL:<br />
do_that();<br />
break;<br />
default:<br />
do_that();<br />
break;<br />
}<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
switch(alignment)<br />
{<br />
case EAlignment::EVIL:<br />
do_that();<br />
break;<br />
default:<br />
do_that();<br />
break;<br />
}<br />
<br />
switch(alignment)<br />
{<br />
case EAlignment::EVIL:<br />
do_that();<br />
break;<br />
default:<br />
do_that();<br />
break;<br />
}<br />
<br />
switch(alignment)<br />
{<br />
case EAlignment::EVIL:<br />
{<br />
do_that();<br />
}<br />
break;<br />
default:<br />
{ <br />
do_that();<br />
}<br />
break;<br />
}<br />
</syntaxhighlight><br />
<br />
=== Lambda expressions ===<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
auto lambda = [this, a, &b](int3 & tile, int index) -> bool<br />
{<br />
do_that();<br />
};<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
auto lambda = [this,a,&b](int3 & tile, int index)->bool{do_that();};<br />
</syntaxhighlight><br />
<br />
Empty parameter list is required even if function takes no arguments.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
auto lambda = []()<br />
{<br />
do_that();<br />
};<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
auto lambda = []<br />
{<br />
do_that();<br />
};<br />
</syntaxhighlight><br />
<br />
Do not use inline lambda expressions inside if-else, for and other conditions.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
auto lambda = []()<br />
{<br />
do_that();<br />
};<br />
if(lambda)<br />
{<br />
code();<br />
}<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
if([]()<br />
{<br />
do_that();<br />
})<br />
{<br />
code();<br />
}<br />
</syntaxhighlight><br />
<br />
Do not pass inline lambda expressions as parameter unless it's the last parameter.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
auto lambda = []()<br />
{<br />
do_that();<br />
};<br />
obj->someMethod(lambda, true);<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
obj->someMethod([]()<br />
{<br />
do_that();<br />
}, true);<br />
</syntaxhighlight><br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
obj->someMethod(true, []()<br />
{<br />
do_that();<br />
});<br />
</syntaxhighlight><br />
<br />
=== Serialization ===<br />
<br />
Serialization of each element must be on it's own line since this make debugging easier.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
template <typename Handler> void serialize(Handler & h, const int version)<br />
{<br />
h & identifier;<br />
h & description;<br />
h & name;<br />
h & dependencies;<br />
}<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
template <typename Handler> void serialize(Handler & h, const int version)<br />
{<br />
h & identifier & description & name & dependencies;<br />
}<br />
</syntaxhighlight><br />
<br />
Save backward compatibility code is exception when extra brackets are always useful.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
template <typename Handler> void serialize(Handler & h, const int version)<br />
{<br />
h & identifier;<br />
h & description;<br />
if(version >= 123)<br />
{<br />
h & totalValue;<br />
}<br />
else if(!h.saving)<br />
{<br />
totalValue = 200;<br />
}<br />
h & name;<br />
h & dependencies;<br />
}<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
template <typename Handler> void serialize(Handler & h, const int version)<br />
{<br />
h & identifier;<br />
h & description;<br />
if(version >= 123)<br />
h & totalValue;<br />
else if(!h.saving)<br />
totalValue = 200;<br />
h & name;<br />
h & dependencies;<br />
}<br />
</syntaxhighlight><br />
<br />
=== File headers ===<br />
<br />
For any new files, please paste the following info block at the very top of the source file:<br />
<syntaxhighlight lang="cpp">/*<br />
* Name_of_File.h, part of VCMI engine<br />
*<br />
* Authors: listed in file AUTHORS in main folder<br />
*<br />
* License: GNU General Public License v2.0 or later<br />
* Full text of license available in license.txt file, in main folder<br />
*<br />
*/</syntaxhighlight><br />
The above notice have to be included both in header and source files (.h/.cpp).<br />
<br />
<br />
=== Code order in files ===<br />
<br />
For any header or source file code must be in following order:<br />
<br />
# Licensing information<br />
# pragma once preprocessor directive<br />
# include directives<br />
# Forward declarations<br />
# All other code<br />
<syntaxhighlight lang="cpp">/*<br />
* Name_of_File.h, part of VCMI engine<br />
*<br />
* Authors: listed in file AUTHORS in main folder<br />
*<br />
* License: GNU General Public License v2.0 or later<br />
* Full text of license available in license.txt file, in main folder<br />
*<br />
*/<br />
#pragma once<br />
<br />
#include "Header.h"<br />
<br />
class CGObjectInstance;<br />
struct CPackForClient;</syntaxhighlight><br />
<br />
=== Where and how to comment ===<br />
<br />
If you comment on the same line with code there must be one single space between code and slashes.<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
if(a)<br />
{<br />
code(); //Do something<br />
}<br />
else // Do something.<br />
{<br />
code(); // Do something.<br />
}<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
if(a)<br />
{<br />
code();//Do something<br />
}<br />
else // Do something.<br />
{<br />
code(); // TODO:<br />
}<br />
</syntaxhighlight><br />
<br />
If you add single-line comment on own line slashes must have same indent as code around:<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
// Do something<br />
if(a)<br />
{<br />
//Do something<br />
for(auto item : list)<br />
code();<br />
}<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
// Do something<br />
if(a)<br />
{<br />
//Do something<br />
for(auto item : list)<br />
code();<br />
}<br />
</syntaxhighlight><br />
<br />
Avoid comments inside multi-line if-else conditions. If your conditions are too hard to understand without additional comments this usually means that code need refactoring. Example given below is need improvement though. '''FIXME'''<br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
bool isMyHeroAlive = a && b || (c + 1 > 15);<br />
bool canMyHeroMove = myTurn && hero.movePoints > 0;<br />
if(isMyHeroAlive && canMyHeroMove)<br />
{<br />
code();<br />
}<br />
</syntaxhighlight><br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
if((a && b || (c + 1 > 15)) //Check if hero still alive<br />
&& myTurn && hero.movePoints > 0) //Check if hero can move<br />
{<br />
code();<br />
}<br />
</syntaxhighlight><br />
<br />
You should write a comment before the class definition which describes shortly the class. 1-2 sentences are enough. Methods and class data members should be commented if they aren't self-describing only. Getters/Setters, simple methods where the purpose is clear or similar methods shouldn't be commented, because vertical space is usually limited. The style of documentation comments should be the three slashes-style: ///. <br />
<br />
<syntaxhighlight lang="cpp"><br />
/// Returns true if a debug/trace log message will be logged, false if not.<br />
/// Useful if performance is important and concatenating the log message is a expensive task.<br />
bool isDebugEnabled() const;<br />
bool isTraceEnabled() const;<br />
</syntaxhighlight><br />
<br />
The above example doesn't follow a strict scheme on how to comment a method. It describes two methods in one go. Comments should be kept short.<br />
<br />
If you need a more detailed description for a method you can use such style:<br />
<syntaxhighlight lang="cpp"><br />
/// <A short one line description><br />
///<br />
/// <Longer description><br />
/// <May span multiple lines or paragraphs as needed><br />
///<br />
/// @param Description of method's or function's input parameter<br />
/// @param ...<br />
/// @return Description of the return value<br />
</syntaxhighlight><br />
<br />
A good essay about writing comments: [http://ardalis.com/when-to-comment-your-code]<br />
<br />
=== Casing ===<br />
<br />
<br />
Local variables and methods start with a lowercase letter and use the camel casing. Classes/Structs start with an uppercase letter and use the camel casing as well. Macros and constants are written uppercase. <br />
<br />
<br />
=== Line length ===<br />
<br />
The line length for c++ source code is 120 columns. If your function declaration arguments go beyond this point, please align your arguments to match the opening brace. For best results use the same number of tabs used on the first line followed by enough spaces to align the arguments. <br />
<br />
<br />
=== Warnings ===<br />
<br />
Avoid use of #pragma to disable warnings. Compile at warning level 3.<br />
Avoid commiting code with new warnings.<br />
<br />
=== Type naming ===<br />
<br />
Classes are prefixed with an upper C, interfaces with an upper I, enumerations with an upper E, structs without an prefix and typedefs with an upper T<br />
<br />
=== File/directory naming ===<br />
<br />
Compilation units(.cpp,.h files) start with a uppercase letter and are named like the name of a class which resides in that file if possible. Header only files start with a uppercase letter. JSON files start with a lowercase letter and use the camel casing.<br />
<br />
Directories start with a lowercase letter and use the camel casing where necessary.<br />
<br />
<br />
=== Logging ===<br />
<br />
Outdated. There is separate entry for [[Logging API]]<br />
<br />
If you want to trace the control flow of VCMI, then you should use the macro LOG_TRACE or LOG_TRACE_PARAMS. The first one prints a message when the function is entered or leaved. The name of the function will also be logged. In addition to this the second macro, let's you specify parameters which you want to print. You should print traces with parameters like this:<br />
<br />
<syntaxhighlight lang="cpp">LOG_TRACE_PARAMS(logGlobal, "hero '%s', spellId '%d', pos '%s'.", hero, spellId, pos);</syntaxhighlight><br />
<br />
When using the macro every "simple" parameter should be logged. The parameter can be a number, a string or a type with a ostream operator<<. You should not log contents of a whole text file, a byte array or sth. like this. If there is a simple type with a few members you want to log, you should write an ostream operator<<. The produced message can look like this:<br />
<br />
<tt>{BattleAction: side '0', stackNumber '1', actionType 'Walk and attack', destinationTile '{BattleHex: x '7', y '1', hex '24'}', additionalInfo '7', selectedStack '-1'}</tt><br />
<br />
The name of the type should be logged first, e.g. {TYPE_NAME: members...}. The members of the object will be logged like logging trace parameters. Collection types (vector, list, ...) should be logged this way: [{BattleHex: ...}, {...}]<br />
There is no format which has to be followed strictly, so if there is a reason to format members/objects in a different way, then this is ok.<br />
<br />
== Best practices ==<br />
<br />
<br />
=== Avoid code duplication ===<br />
<br />
Avoid code duplication or don't repeat yourself(DRY) is the most important aspect in programming. Code duplication of any kind can lead to inconsistency and is much harder to maintain. If one part of the system gets changed you have to change the code in several places. This process is error-prone and leads often to problems. Here you can read more about the DRY principle: [http://en.wikipedia.org/wiki/Don%27t_repeat_yourself http://en.wikipedia.org/wiki/Don%27t_repeat_yourself]<br />
<br />
=== Do not use uncommon abbrevations ===<br />
<br />
Do not use uncommon abbrevations for class, method, parameter and global object names.<br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
CArt * getRandomArt(...)<br />
class CIntObject<br />
</syntaxhighlight><br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
CArtifact * getRandomArtifact(...)<br />
class CInterfaceObject<br />
</syntaxhighlight><br />
<br />
=== Loop handling ===<br />
<br />
Use range-based for loops. It should be used in any case except you absolutely need iterator, then you may use a simple for loop.<br />
<br />
The loop counter should be of type int, unless you are sure you won't need negative indices -- then use size_t.<br />
<br />
=== Include guards ===<br />
<br />
Use #pragma once instead of the traditional #ifndef/#define/#endif include guards.<br />
<br />
<br />
=== Pre compiled header file ===<br />
<br />
The header StdInc.h should be included in every compilation unit. It has to be included before any C macro and before any c++ statements. Pre compiled header should not be changed, except any important thing is missing.<br />
The StdInc includes most Boost libraries and nearly all standard STL and C libraries, so you don’t have to include them by yourself. <br />
<br />
<br />
=== Enumeration handling ===<br />
<br />
Do not declare enumerations in global namespace. It is better to use strongly typed enum or to wrap them in class or namespace to avoid polluting global namespace:<br />
<br />
<syntaxhighlight lang="cpp"><br />
enum class EAlignment<br />
{<br />
GOOD,<br />
EVIL,<br />
NEUTRAL<br />
};<br />
<br />
namespace EAlignment<br />
{<br />
enum EAlignment<br />
{<br />
GOOD, EVIL, NEUTRAL<br />
};<br />
}<br />
</syntaxhighlight><br />
<br />
=== Avoid senseless comments ===<br />
<br />
If the comment duplicates the name of commented member, it's better if it wouldn't exist at all. It just increases maintenance cost.<br />
Bad:<br />
<syntaxhighlight lang="cpp">size_t getHeroesCount(); //gets count of heroes (surprise?)</syntaxhighlight><br />
<br />
<br />
=== Class handling ===<br />
<br />
There is no definitive rule which has to be followed strictly. You can freely decide if you want to pack your own classes, where you are programming on, all in one file or each in one file. It's more important that you feel comfortable with the code, than consistency overall the project. VCMI has several container class files, so if you got one additional class to them than just add it to them instead of adding new files.<br />
<br />
=== Functions and interfaces ===<br />
<br />
Don't return const objects or primitive types from functions -- it's pointless. Also, don't return pointers to non-const game data objects from callbacks to player interfaces.<br />
<br />
Bad:<br />
<syntaxhighlight lang="cpp"><br />
const std::vector<CGObjectInstance*> guardingCreatures(int3 pos) const;<br />
</syntaxhighlight><br />
<br />
Good:<br />
<syntaxhighlight lang="cpp"><br />
std::vector<const CGObjectInstance*> guardingCreatures(int3 pos) const;<br />
</syntaxhighlight><br />
<br />
== Sources ==<br />
[http://www.mono-project.com/Coding_Guidelines Mono project coding guidelines]</div>SXXhttps://wiki.vcmi.eu/index.php?title=How_to_build_VCMI_(macOS)&diff=2706How to build VCMI (macOS)2017-09-18T22:11:32Z<p>SXX: /* Getting and configuring VCMI */</p>
<hr />
<div>= Installing dependencies =<br />
===== Installing Xcode =====<br />
App Store -> Xcode<br />
Launch it after the installation to agree with it's license terms.<br />
<br />
Alternatively Xcode can be downloaded from Apple Developers website.<br />
Registration is easier and every possible version is available: https://developer.apple.com/download/more/<br />
<br />
===== Setting Xcode version Xcode =====<br />
In case you have some weird CMake errors during generation attempts such as<br />
<pre><br />
CMake Error: Xcode 1.5 not supported.<br />
</pre><br />
You might need to specify installed version of Xcode:<br />
<pre><br />
sudo /usr/bin/xcode-select --switch /Users/admin/Downloads/Xcode.app<br />
</pre><br />
After that Cmake will be able to generate projects properly!<br />
<br />
===== Installing [https://brew.sh/ Homebrew] =====<br />
<pre><br />
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"<br />
</pre><br />
<br />
===== Installing dependencies using Homebrew =====<br />
<pre><br />
brew install git cmake sdl2 sdl2_ttf sdl2_image boost ffmpeg minizip<br />
brew install sdl2_mixer --with-smpeg2<br />
# Now install Qt5 for launcher<br />
brew install qt5<br />
# Make sure to read brew output on Qt carefully<br />
# It's will tell you how to add Qt to your $PATH environment variable<br />
#<br />
# Currently it's can be done like that<br />
# echo 'export PATH="/usr/local/opt/qt/bin:$PATH"' >> ~/.bash_profile<br />
</pre><br />
<br />
= Building VCMI in command line with Makefiles =<br />
===== Getting and configuring VCMI =====<br />
<pre><br />
# You can choose any directory<br />
mkdir ~/DEV && cd ~/DEV<br />
# Clone VCMI with all submodules<br />
git clone --recursive https://github.com/vcmi/vcmi.git<br />
# Creating directory for building<br />
mkdir cmake && cd cmake<br />
cmake ../vcmi -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -Wno-devc<br />
</pre><br />
You can as well build VCMI without Qt5 or launcher by disabling it:<br />
<pre><br />
# But please don't do that unless you know what you're doing<br />
cmake ../vcmi -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DENABLE_LAUNCHER=0 -Wno-devc<br />
</pre><br />
<br />
===== Building and packaging VCMI =====<br />
<pre><br />
cd ~/DEV/cmake<br />
# Start build using cmake<br />
cmake --build . -- -j 4<br />
# Or you can as well use simple<br />
# make -j 4<br />
<br />
# When build is completed you can trigger packaging into DMG<br />
cpack<br />
# After file named such as "vcmi-0.99.dmg" will be created<br />
</pre><br />
<br />
= Building VCMI with Xcode =<br />
===== Getting and configuring VCMI =====<br />
<pre><br />
# You can choose any directory<br />
mkdir ~/DEV && cd ~/DEV<br />
# Clone VCMI with all submodules<br />
git clone --recursive https://github.com/vcmi/vcmi.git<br />
# Creating directory for building<br />
mkdir cmake && cd cmake<br />
# Xcode is multi-configuration project so specifying CMAKE_BUILD_TYPE makes no sense<br />
cmake ../vcmi -G "Xcode"<br />
<br />
# You can as well open project in Xcode using:<br />
open VCMI.xcodeproj<br />
</pre><br />
<br />
===== Building and packaging VCMI =====<br />
<pre><br />
cd ~/DEV/xcode<br />
# Start build. Xcode built using multiple processes by default so you don't need to specify it<br />
# Since it's multi-configuration project you need to specify if you want Debug build since Release is default<br />
cmake --build . --config Debug<br />
<br />
# You have to specify build configuration for CPack. Otherwise it's will expect Release as default<br />
cpack -C Debug<br />
</pre><br />
<br />
= Building VCMI with Qt Creator =<br />
When opening project with Qt Creator installed using online installer you might have a problem with CMake unable to find Qt even if you added it into the $PATH environment variable. In that case try to open it from command line:<br />
<pre><br />
open ~/Qt/Qt\ Creator.app<br />
</pre><br />
<br />
= Running VCMI =<br />
You can run VCMI from DMG, but it's will also work from your IDE be it Xcode or Qt Creator.<br />
<br />
Alternatively you can run binaries directly from "bin" directory:<br />
<pre><br />
~/DEV/cmake/bin/vcmilauncher<br />
~/DEV/cmake/bin/vcmiclient<br />
~/DEV/cmake/bin/vcmiserver<br />
</pre><br />
CMake include commands to copy all needed assets from source directory into "bin" on each build. They'll work when you build from Xcode too.<br />
<br />
'''Be aware you still need directories "Data", "Mp3" and "Maps" from Heroes 3 game assets in VCMI app data directory:'''<br />
<pre><br />
~/Library/Application\ Support/vcmi/<br />
</pre><br />
<br />
===== Some useful debugging tips =====<br />
Anyone who might want to debug builds, but new to macOS could find following commands useful:<br />
<pre><br />
# To attach DMG file from command line use<br />
hdiutil attach vcmi-0.99.dmg<br />
# Detach volume:<br />
hdiutil detach /Volumes/vcmi-0.99<br />
# To view dependency paths<br />
otool -L /Volumes/vcmi-0.99/VCMI.app/Contents/MacOS/vcmiclient<br />
# To display load commands such as LC_RPATH <br />
otool -l /Volumes/vcmi-0.99/VCMI.app/Contents/MacOS/vcmiclient<br />
</pre></div>SXXhttps://wiki.vcmi.eu/index.php?title=How_to_build_VCMI_(macOS)&diff=2705How to build VCMI (macOS)2017-09-18T22:11:20Z<p>SXX: /* Getting and configuring VCMI */</p>
<hr />
<div>= Installing dependencies =<br />
===== Installing Xcode =====<br />
App Store -> Xcode<br />
Launch it after the installation to agree with it's license terms.<br />
<br />
Alternatively Xcode can be downloaded from Apple Developers website.<br />
Registration is easier and every possible version is available: https://developer.apple.com/download/more/<br />
<br />
===== Setting Xcode version Xcode =====<br />
In case you have some weird CMake errors during generation attempts such as<br />
<pre><br />
CMake Error: Xcode 1.5 not supported.<br />
</pre><br />
You might need to specify installed version of Xcode:<br />
<pre><br />
sudo /usr/bin/xcode-select --switch /Users/admin/Downloads/Xcode.app<br />
</pre><br />
After that Cmake will be able to generate projects properly!<br />
<br />
===== Installing [https://brew.sh/ Homebrew] =====<br />
<pre><br />
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"<br />
</pre><br />
<br />
===== Installing dependencies using Homebrew =====<br />
<pre><br />
brew install git cmake sdl2 sdl2_ttf sdl2_image boost ffmpeg minizip<br />
brew install sdl2_mixer --with-smpeg2<br />
# Now install Qt5 for launcher<br />
brew install qt5<br />
# Make sure to read brew output on Qt carefully<br />
# It's will tell you how to add Qt to your $PATH environment variable<br />
#<br />
# Currently it's can be done like that<br />
# echo 'export PATH="/usr/local/opt/qt/bin:$PATH"' >> ~/.bash_profile<br />
</pre><br />
<br />
= Building VCMI in command line with Makefiles =<br />
===== Getting and configuring VCMI =====<br />
<pre><br />
# You can choose any directory<br />
mkdir ~/DEV && cd ~/DEV<br />
# Clone VCMI with all submodules<br />
git clone --recursive https://github.com/vcmi/vcmi.git<br />
# Creating directory for building<br />
mkdir cmake && cd cmake<br />
cmake ../vcmi -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -Wno-devc<br />
</pre><br />
You can as well build VCMI without Qt5 or launcher by disabling it:<br />
<pre><br />
# But please don't do that unless you know what you're doing<br />
cmake ../vcmi -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DENABLE_LAUNCHER=0 -Wno-devc<br />
</pre><br />
<br />
===== Building and packaging VCMI =====<br />
<pre><br />
cd ~/DEV/cmake<br />
# Start build using cmake<br />
cmake --build . -- -j 4<br />
# Or you can as well use simple<br />
# make -j 4<br />
<br />
# When build is completed you can trigger packaging into DMG<br />
cpack<br />
# After file named such as "vcmi-0.99.dmg" will be created<br />
</pre><br />
<br />
= Building VCMI with Xcode =<br />
===== Getting and configuring VCMI =====<br />
<pre><br />
# You can choose any directory<br />
mkdir ~/DEV && cd ~/DEV<br />
# Clone VCMI with all submodules<br />
git clone -b develop --depth 1 --recursive https://github.com/vcmi/vcmi.git<br />
# Creating directory for building<br />
mkdir cmake && cd cmake<br />
# Xcode is multi-configuration project so specifying CMAKE_BUILD_TYPE makes no sense<br />
cmake ../vcmi -G "Xcode"<br />
<br />
# You can as well open project in Xcode using:<br />
open VCMI.xcodeproj<br />
</pre><br />
<br />
===== Building and packaging VCMI =====<br />
<pre><br />
cd ~/DEV/xcode<br />
# Start build. Xcode built using multiple processes by default so you don't need to specify it<br />
# Since it's multi-configuration project you need to specify if you want Debug build since Release is default<br />
cmake --build . --config Debug<br />
<br />
# You have to specify build configuration for CPack. Otherwise it's will expect Release as default<br />
cpack -C Debug<br />
</pre><br />
<br />
= Building VCMI with Qt Creator =<br />
When opening project with Qt Creator installed using online installer you might have a problem with CMake unable to find Qt even if you added it into the $PATH environment variable. In that case try to open it from command line:<br />
<pre><br />
open ~/Qt/Qt\ Creator.app<br />
</pre><br />
<br />
= Running VCMI =<br />
You can run VCMI from DMG, but it's will also work from your IDE be it Xcode or Qt Creator.<br />
<br />
Alternatively you can run binaries directly from "bin" directory:<br />
<pre><br />
~/DEV/cmake/bin/vcmilauncher<br />
~/DEV/cmake/bin/vcmiclient<br />
~/DEV/cmake/bin/vcmiserver<br />
</pre><br />
CMake include commands to copy all needed assets from source directory into "bin" on each build. They'll work when you build from Xcode too.<br />
<br />
'''Be aware you still need directories "Data", "Mp3" and "Maps" from Heroes 3 game assets in VCMI app data directory:'''<br />
<pre><br />
~/Library/Application\ Support/vcmi/<br />
</pre><br />
<br />
===== Some useful debugging tips =====<br />
Anyone who might want to debug builds, but new to macOS could find following commands useful:<br />
<pre><br />
# To attach DMG file from command line use<br />
hdiutil attach vcmi-0.99.dmg<br />
# Detach volume:<br />
hdiutil detach /Volumes/vcmi-0.99<br />
# To view dependency paths<br />
otool -L /Volumes/vcmi-0.99/VCMI.app/Contents/MacOS/vcmiclient<br />
# To display load commands such as LC_RPATH <br />
otool -l /Volumes/vcmi-0.99/VCMI.app/Contents/MacOS/vcmiclient<br />
</pre></div>SXXhttps://wiki.vcmi.eu/index.php?title=Installation_on_Linux&diff=2704Installation on Linux2017-09-18T08:01:44Z<p>SXX: /* Snappy */</p>
<hr />
<div>VCMI requires data from original Heroes 3: Shadow of Death or Complete editions. Data from native Linux version made by LOKI will not work.<br />
= Binaries installation =<br />
== Ubuntu ==<br />
<br />
VCMI stable builds available in "multiverse" repository. Learn how to enable it in [https://help.ubuntu.com/community/Repositories/Ubuntu Ubuntu wiki].<br />
<br />
VCMI daily builds can be installed from PPA:<br />
* For testing only: https://launchpad.net/~vcmi/+archive/ppa<br />
<br />
To add PPA type in Terminal:<br />
<pre><br />
sudo apt-add-repository ppa:vcmi/ppa<br />
</pre><br />
<br />
To install VCMI from repository:<br />
<pre><br />
sudo apt-get update<br />
sudo apt-get install vcmi<br />
</pre><br />
<br />
== Debian ==<br />
<br />
Stable VCMI version is available in "contrib" repository. Learn how to enable it in [https://wiki.debian.org/SourcesList Debian wiki].<br />
<br />
To install VCMI from repository:<br />
<pre><br />
sudo apt-get update<br />
sudo apt-get install vcmi<br />
</pre><br />
<br />
== Snappy ==<br />
It's possible to install daily VCMI builds as distribution-agnostic Snap package:<br />
<br />
* Visit [https://snapcraft.io/ snapcraft.io] to learn how to get Snappy on your distribution.<br />
* Once it's running install latest VCMI build with:<br />
<pre><br />
sudo snap install --edge vcmi<br />
</pre><br />
* After you can run VCMI with following commands:<br />
<pre><br />
snap run vcmi.vcmilauncher<br />
snap run vcmi.vcmiclient<br />
snap run vcmi.vcmiserver<br />
</pre><br />
* Keep in mind that instead of '''$HOME/.local/share/vcmi/''' you must copy Heroes 3 assets into:<br />
<pre><br />
$HOME/snap/vcmi/current/.local/share/vcmi/<br />
</pre><br />
* To update to latest version:<br />
<pre><br />
sudo snap refresh vcmi<br />
</pre><br />
<br />
'''Warning:''' Snap builds are currently in experimental state.<br />
<br />
Please give your feedback on forum: [https://forum.vcmi.eu/t/experimental-snap-packages-for-linux/4300 Experimental Snap packages for Linux].<br />
<br />
== Other distributions ==<br />
For other distributions, VCMI can be installed from 3rd-party repositories listed below.<br />
* Gentoo https://github.com/qdii/qdiilay/tree/master/games-strategy/vcmi<br />
* Archlinux [https://aur.archlinux.org/packages/vcmi/ vcmi] [https://aur.archlinux.org/packages/vcmi-git/ vcmi-git]<br />
If you are interested in providing builds for other distributions, please let us know.<br />
<br />
== Compiling from source ==<br />
Please check following developer guide: [[How to build VCMI (Linux)]]<br />
<br />
= Installing Heroes III data files =<br />
To install VCMI you will need Heroes III: Shadow of Death or Complete edition.<br />
== Automated install ==<br />
To install Heroes 3 data using automated script you need any of:<br />
* One or two CD's or CD images<br />
* gog.com installer<br />
* Directory with installed game<br />
<br />
Run the script using options appropriate to your input files:<br />
<pre><br />
vcmibuilder --cd1 /path/to/iso/or/cd --cd2 /path/to/second/cd<br />
vcmibuilder --gog /path/to/gog.com/installer<br />
vcmibuilder --data /path/to/h3/data<br />
</pre><br />
You should use only one of these commands.<br />
<br />
=== Music on distributions without Mp3 support ===<br />
To have Music support on Fedora it is required to perform a additional step. Fedora doesn't provide Mp3 playback support natively due to patents applied on the Mp3 technique. The SDL_mixer package from the official Fedora repo is compiled without Mp3 support.<br />
<br />
To make music work it must be converted into ogg format. This can be done either manually or using vcmibuilder:<br />
<pre><br />
vcmibuilder --convertMP3<br />
</pre><br />
This command can be run separately after install or as additional switch during initial vcmibuilder launch<br />
<br />
== Manual install ==<br />
<br />
* Install Heroes III in Wine or manually unpack GOG installer.<br />
<br />
* Copy "Data", "Maps" and "Mp3" from Heroes III to:<br />
<pre>/home/$USER/.local/share/vcmi/</pre><br />
On some distributions $XDG_DATA_HOME could differ so instead you may need to use:<br />
<pre>$XDG_DATA_HOME/vcmi/</pre><br />
<br />
= Launching game =<br />
To start the game type in console:<br />
<pre><br />
vcmilauncher<br />
</pre><br />
Or, to start game directly avoiding Launcher:<br />
<pre><br />
vcmiclient<br />
</pre><br />
VCMI should be also available via desktop environment menu or launcher (Games/Strategy/VCMI)<br />
<br />
= Reporting bugs =<br />
Please report any issues with packages according to <br />
[http://wiki.vcmi.eu/index.php?title=Bug_reporting_guidelines Bug reporting guidelines]</div>SXXhttps://wiki.vcmi.eu/index.php?title=Project_infrastructure&diff=2702Project infrastructure2017-09-16T10:10:15Z<p>SXX: /* Other services */</p>
<hr />
<div>This page hold important information about project infrastructure for current and future contributors. At moment it's all maintained by me (SXX), but following information will be useful if someone going to replace me in future.<br />
<br />
You can also check [[Project servers configuration|detailed information on server configuration]].<br />
<br />
== Services and accounts ==<br />
So far we using following services:<br />
=== Most important ===<br />
<br />
* VCMI.eu domain paid until July of 2019.<br />
** Owner: Tow<br />
** Our main domain used by services.<br />
* VCMI.download paid until November of 2026.<br />
** Owner: SXX<br />
** Intended to be used for all assets downloads.<br />
** Domain registered on GANDI and '''can be renewed by anyone without access to account'''. <br />
* [https://cloud.digitalocean.com/ DigitalOcean] team.<br />
** Our hosting sponsor.<br />
** Administrator access: SXX, Warmonger.<br />
** User access: AVS, Tow.<br />
* [https://www.cloudflare.com/a/overview CloudFlare] account.<br />
** Access through shared login / password.<br />
** All of our infrastructure is behind CloudFlare and all our webWe'll manage our DNS there.<br />
* [https://admin.google.com/ Google Apps (G Suite)] account.<br />
** It's only for vcmi.eu domain and limited to 5 users. Each account has limit of 500 emails / day.<br />
** One administrative email used for other services registration.<br />
** "noreply" email used for outgoing mail on Wiki and Bug Tracker.<br />
** "forum" email used for outgoing mail on Forums. Since we authenticate everyone through forum it's should be separate email.<br />
** Administrator access: Tow, SXX.<br />
* [https://play.google.com/apps/publish/ Google Play Console] account.<br />
** Hold ownership over VCMI Android App.<br />
** Owner: SXX<br />
** Administrator access: Warmonger, AVS.<br />
** Release manager access: Fay.<br />
<br />
Not all services let us safely share login credentials, but at least when possible at least two of core developers must have access to them in case of emergency.<br />
<br />
=== Public relations ===<br />
We want to notify players about updates on as many social services as possible.<br />
<br />
* Facebook page: https://www.facebook.com/VCMIOfficial<br />
** Administrator access: SXX, Warmonger<br />
* Twitter account: https://twitter.com/VCMIOfficial<br />
** Administrator access: SXX.<br />
** User access via TweetDeck: <br />
* VK / VKontakte page: https://vk.com/VCMIOfficial<br />
** Owner: SXX<br />
** Administrator access: AVS<br />
* Google+ page: https://plus.google.com/+VCMIOfficial<br />
** Administrator access: SXX<br />
<br />
Other media:<br />
* Steam group: https://steamcommunity.com/groups/VCMI<br />
** Administrator access: SXX<br />
** Moderator access: Dydzio<br />
* Sub Reddit: https://reddit.com/r/vcmi/<br />
** Administrator access: SXX<br />
* ModDB entry: http://www.moddb.com/engines/vcmi<br />
** Administrator access: SXX<br />
<br />
=== Communication channels ===<br />
* Slack team: https://h3vcmi.slack.com/<br />
** Owner: vmarkovtsev<br />
** Administrator access: SXX, Warmonger, AVS...<br />
* Trello team: https://trello.com/vcmi/<br />
** Administrator access: SXX<br />
* Unofficial discord:<br />
** Owner: dydzio<br />
** Administrator access: SXX<br />
* Unofficial IRC channel: irc.freenode.net #vcmi<br />
<br />
=== Other services ===<br />
* Launchpad PPA: https://launchpad.net/~vcmi<br />
** Member access: AVS<br />
** Administrator access: Ivan, SXX<br />
* Snapcraft Dashboard: https://dashboard.snapcraft.io/<br />
** Administrator access: SXX<br />
* Coverity Scan page: https://scan.coverity.com/projects/vcmi<br />
** Administrator access: SXX, Warmonger, AVS<br />
* OpenHub page: https://www.openhub.net/p/VCMI<br />
** Administrator access: Tow<br />
* Docker Hub organization: https://hub.docker.com/u/vcmi/<br />
** Administrator access: SXX<br />
<br />
Reserve accounts for other code hosting services:<br />
* GitLab organization: https://gitlab.com/vcmi/<br />
** Administrator access: SXX<br />
* BitBucket organization: https://bitbucket.org/vcmi/<br />
** Administrator access: SXX<br />
<br />
== What's to improve ==<br />
# Encourage Tow to transfer VCMI.eu to GANDI so it's can be also renewed without access.<br />
# Use 2FA on CloudFlare and just ask everyone to get FreeOTP and then use shared secret.<br />
# Centralized way to post news about game updates to all social media.</div>SXXhttps://wiki.vcmi.eu/index.php?title=Installation_on_Linux&diff=2695Installation on Linux2017-09-09T18:48:48Z<p>SXX: /* Snappy */</p>
<hr />
<div>VCMI requires data from original Heroes 3: Shadow of Death or Complete editions. Data from native Linux version made by LOKI will not work.<br />
= Binaries installation =<br />
== Ubuntu ==<br />
<br />
VCMI stable builds available in "multiverse" repository. Learn how to enable it in [https://help.ubuntu.com/community/Repositories/Ubuntu Ubuntu wiki].<br />
<br />
VCMI daily builds can be installed from PPA:<br />
* For testing only: https://launchpad.net/~vcmi/+archive/ppa<br />
<br />
To add PPA type in Terminal:<br />
<pre><br />
sudo apt-add-repository ppa:vcmi/ppa<br />
</pre><br />
<br />
To install VCMI from repository:<br />
<pre><br />
sudo apt-get update<br />
sudo apt-get install vcmi<br />
</pre><br />
<br />
== Debian ==<br />
<br />
Stable VCMI version is available in "contrib" repository. Learn how to enable it in [https://wiki.debian.org/SourcesList Debian wiki].<br />
<br />
To install VCMI from repository:<br />
<pre><br />
sudo apt-get update<br />
sudo apt-get install vcmi<br />
</pre><br />
<br />
== Snappy ==<br />
It's possible to install daily VCMI builds as distribution-agnostic Snap package:<br />
<br />
* Visit [https://snapcraft.io/ snapcraft.io] to learn how to get Snappy on your distribution.<br />
* Once it's running install latest VCMI build with:<br />
<pre><br />
sudo snap install --edge vcmi<br />
</pre><br />
* After you can run VCMI with following commands:<br />
<pre><br />
snap run vcmi.vcmilauncher<br />
snap run vcmi.vcmiclient<br />
snap run vcmi.vcmiserver<br />
</pre><br />
* Keep in mind that instead of '''$HOME/.local/share/vcmi/''' you must copy Heroes 3 assets into:<br />
<pre><br />
$HOME/snap/vcmi/current/.local/share/vcmi/<br />
</pre><br />
* To update to latest version:<br />
<pre><br />
sudo snap refresh vcmi<br />
</pre><br />
<br />
'''Warning:''' Snap builds are currently in experimental state.<br />
<br />
Please give your feedback on forum: [https://forum.vcmi.eu/t/experimental-snap-packages-for-linux/4300|Experimental Snap packages for Linux].<br />
<br />
== Other distributions ==<br />
For other distributions, VCMI can be installed from 3rd-party repositories listed below.<br />
* Gentoo https://github.com/qdii/qdiilay/tree/master/games-strategy/vcmi<br />
* Archlinux [https://aur.archlinux.org/packages/vcmi/ vcmi] [https://aur.archlinux.org/packages/vcmi-git/ vcmi-git]<br />
If you are interested in providing builds for other distributions, please let us know.<br />
<br />
== Compiling from source ==<br />
Please check following developer guide: [[How to build VCMI (Linux)]]<br />
<br />
= Installing Heroes III data files =<br />
To install VCMI you will need Heroes III: Shadow of Death or Complete edition.<br />
== Automated install ==<br />
To install Heroes 3 data using automated script you need any of:<br />
* One or two CD's or CD images<br />
* gog.com installer<br />
* Directory with installed game<br />
<br />
Run the script using options appropriate to your input files:<br />
<pre><br />
vcmibuilder --cd1 /path/to/iso/or/cd --cd2 /path/to/second/cd<br />
vcmibuilder --gog /path/to/gog.com/installer<br />
vcmibuilder --data /path/to/h3/data<br />
</pre><br />
You should use only one of these commands.<br />
<br />
=== Music on distributions without Mp3 support ===<br />
To have Music support on Fedora it is required to perform a additional step. Fedora doesn't provide Mp3 playback support natively due to patents applied on the Mp3 technique. The SDL_mixer package from the official Fedora repo is compiled without Mp3 support.<br />
<br />
To make music work it must be converted into ogg format. This can be done either manually or using vcmibuilder:<br />
<pre><br />
vcmibuilder --convertMP3<br />
</pre><br />
This command can be run separately after install or as additional switch during initial vcmibuilder launch<br />
<br />
== Manual install ==<br />
<br />
* Install Heroes III in Wine or manually unpack GOG installer.<br />
<br />
* Copy "Data", "Maps" and "Mp3" from Heroes III to:<br />
<pre>/home/$USER/.local/share/vcmi/</pre><br />
On some distributions $XDG_DATA_HOME could differ so instead you may need to use:<br />
<pre>$XDG_DATA_HOME/vcmi/</pre><br />
<br />
= Launching game =<br />
To start the game type in console:<br />
<pre><br />
vcmilauncher<br />
</pre><br />
Or, to start game directly avoiding Launcher:<br />
<pre><br />
vcmiclient<br />
</pre><br />
VCMI should be also available via desktop environment menu or launcher (Games/Strategy/VCMI)<br />
<br />
= Reporting bugs =<br />
Please report any issues with packages according to <br />
[http://wiki.vcmi.eu/index.php?title=Bug_reporting_guidelines Bug reporting guidelines]</div>SXXhttps://wiki.vcmi.eu/index.php?title=Project_infrastructure&diff=2694Project infrastructure2017-09-09T14:50:18Z<p>SXX: </p>
<hr />
<div>This page hold important information about project infrastructure for current and future contributors. At moment it's all maintained by me (SXX), but following information will be useful if someone going to replace me in future.<br />
<br />
You can also check [[Project servers configuration|detailed information on server configuration]].<br />
<br />
== Services and accounts ==<br />
So far we using following services:<br />
=== Most important ===<br />
<br />
* VCMI.eu domain paid until July of 2019.<br />
** Owner: Tow<br />
** Our main domain used by services.<br />
* VCMI.download paid until November of 2026.<br />
** Owner: SXX<br />
** Intended to be used for all assets downloads.<br />
** Domain registered on GANDI and '''can be renewed by anyone without access to account'''. <br />
* [https://cloud.digitalocean.com/ DigitalOcean] team.<br />
** Our hosting sponsor.<br />
** Administrator access: SXX, Warmonger.<br />
** User access: AVS, Tow.<br />
* [https://www.cloudflare.com/a/overview CloudFlare] account.<br />
** Access through shared login / password.<br />
** All of our infrastructure is behind CloudFlare and all our webWe'll manage our DNS there.<br />
* [https://admin.google.com/ Google Apps (G Suite)] account.<br />
** It's only for vcmi.eu domain and limited to 5 users. Each account has limit of 500 emails / day.<br />
** One administrative email used for other services registration.<br />
** "noreply" email used for outgoing mail on Wiki and Bug Tracker.<br />
** "forum" email used for outgoing mail on Forums. Since we authenticate everyone through forum it's should be separate email.<br />
** Administrator access: Tow, SXX.<br />
* [https://play.google.com/apps/publish/ Google Play Console] account.<br />
** Hold ownership over VCMI Android App.<br />
** Owner: SXX<br />
** Administrator access: Warmonger, AVS.<br />
** Release manager access: Fay.<br />
<br />
Not all services let us safely share login credentials, but at least when possible at least two of core developers must have access to them in case of emergency.<br />
<br />
=== Public relations ===<br />
We want to notify players about updates on as many social services as possible.<br />
<br />
* Facebook page: https://www.facebook.com/VCMIOfficial<br />
** Administrator access: SXX, Warmonger<br />
* Twitter account: https://twitter.com/VCMIOfficial<br />
** Administrator access: SXX.<br />
** User access via TweetDeck: <br />
* VK / VKontakte page: https://vk.com/VCMIOfficial<br />
** Owner: SXX<br />
** Administrator access: AVS<br />
* Google+ page: https://plus.google.com/+VCMIOfficial<br />
** Administrator access: SXX<br />
<br />
Other media:<br />
* Steam group: https://steamcommunity.com/groups/VCMI<br />
** Administrator access: SXX<br />
** Moderator access: Dydzio<br />
* Sub Reddit: https://reddit.com/r/vcmi/<br />
** Administrator access: SXX<br />
* ModDB entry: http://www.moddb.com/engines/vcmi<br />
** Administrator access: SXX<br />
<br />
=== Communication channels ===<br />
* Slack team: https://h3vcmi.slack.com/<br />
** Owner: vmarkovtsev<br />
** Administrator access: SXX, Warmonger, AVS...<br />
* Trello team: https://trello.com/vcmi/<br />
** Administrator access: SXX<br />
* Unofficial discord:<br />
** Owner: dydzio<br />
** Administrator access: SXX<br />
* Unofficial IRC channel: irc.freenode.net #vcmi<br />
<br />
=== Other services ===<br />
* Launchpad PPA: https://launchpad.net/~vcmi<br />
** Member access: SXX<br />
** Administrator access: Ivan<br />
* Snapcraft Dashboard: https://dashboard.snapcraft.io/<br />
** Administrator access: SXX<br />
* Coverity Scan page: https://scan.coverity.com/projects/vcmi<br />
** Administrator access: SXX, Warmonger, AVS<br />
* OpenHub page: https://www.openhub.net/p/VCMI<br />
** Administrator access: Tow<br />
* Docker Hub organization: https://hub.docker.com/u/vcmi/<br />
** Administrator access: SXX<br />
<br />
Reserve accounts for other code hosting services:<br />
* GitLab organization: https://gitlab.com/vcmi/<br />
** Administrator access: SXX<br />
* BitBucket organization: https://bitbucket.org/vcmi/<br />
** Administrator access: SXX<br />
<br />
== What's to improve ==<br />
# Encourage Tow to transfer VCMI.eu to GANDI so it's can be also renewed without access.<br />
# Use 2FA on CloudFlare and just ask everyone to get FreeOTP and then use shared secret.<br />
# Centralized way to post news about game updates to all social media.</div>SXXhttps://wiki.vcmi.eu/index.php?title=Project_servers_configuration&diff=2693Project servers configuration2017-09-09T14:49:58Z<p>SXX: Protected "Project servers configuration" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))</p>
<hr />
<div>This page dedicated to explain specific configurations of our servers for anyone who might need to improve it in future. Check [[project infrastructure]] page for services and accounts overview.<br />
<br />
== Droplet configuration ==<br />
<br />
=== Droplet and hosted services ===<br />
<br />
Currently we using two droplets:<br />
<br />
* First one serve all of our web services:<br />
** [https://forum.vcmi.eu/ Forum]<br />
** [https://bugs.vcmi.eu/ Bug tracker]<br />
** [https://wiki.vcmi.eu/ Wiki]<br />
** [https://slack.vcmi.eu/ Slack invite page]<br />
* Second serve downloads:<br />
** [http://download.vcmi.eu/ Legacy download page]<br />
** [https://builds.vcmi.download/ Build download page]<br />
<br />
To keep everything secure we should always keep binary downloads separate from any web services.<br />
<br />
=== Rules to stick to ===<br />
<br />
* SSH authentication by public key only.<br />
* Incoming connections to all ports except SSH (22) must be blocked.<br />
* Exception for HTTP(S) connection on ports 80 / 443 from [https://www.cloudflare.com/ips/ CloudFlare IP Ranges].<br />
* No one except core developers should ever know real server IPs.<br />
* Droplet hostname should never be valid host. Otherwise it's exposed in [https://en.wikipedia.org/wiki/Reverse_DNS reverse DNS].<br />
* If some non-web service need to listen for external connections then read below.<br />
<br />
=== Our publicly-facing server ===<br />
We only expose floating IP that can be detached from droplet in case of emergency using [https://cloud.digitalocean.com/networking/floating_ips DO control panel]. This also allow us to easily move public services to dedicated droplet in future.<br />
<br />
* Address: beholder.vcmi.eu (67.207.75.182)<br />
* Port 22 serve SFTP for file uploads as well as CI artifacts uploads.<br />
<br />
If new services added firewall rules can be adjusted in [https://cloud.digitalocean.com/networking/firewalls DO control panel].</div>SXXhttps://wiki.vcmi.eu/index.php?title=Project_servers_configuration&diff=2692Project servers configuration2017-09-09T14:49:47Z<p>SXX: Move droplet information here</p>
<hr />
<div>This page dedicated to explain specific configurations of our servers for anyone who might need to improve it in future. Check [[project infrastructure]] page for services and accounts overview.<br />
<br />
== Droplet configuration ==<br />
<br />
=== Droplet and hosted services ===<br />
<br />
Currently we using two droplets:<br />
<br />
* First one serve all of our web services:<br />
** [https://forum.vcmi.eu/ Forum]<br />
** [https://bugs.vcmi.eu/ Bug tracker]<br />
** [https://wiki.vcmi.eu/ Wiki]<br />
** [https://slack.vcmi.eu/ Slack invite page]<br />
* Second serve downloads:<br />
** [http://download.vcmi.eu/ Legacy download page]<br />
** [https://builds.vcmi.download/ Build download page]<br />
<br />
To keep everything secure we should always keep binary downloads separate from any web services.<br />
<br />
=== Rules to stick to ===<br />
<br />
* SSH authentication by public key only.<br />
* Incoming connections to all ports except SSH (22) must be blocked.<br />
* Exception for HTTP(S) connection on ports 80 / 443 from [https://www.cloudflare.com/ips/ CloudFlare IP Ranges].<br />
* No one except core developers should ever know real server IPs.<br />
* Droplet hostname should never be valid host. Otherwise it's exposed in [https://en.wikipedia.org/wiki/Reverse_DNS reverse DNS].<br />
* If some non-web service need to listen for external connections then read below.<br />
<br />
=== Our publicly-facing server ===<br />
We only expose floating IP that can be detached from droplet in case of emergency using [https://cloud.digitalocean.com/networking/floating_ips DO control panel]. This also allow us to easily move public services to dedicated droplet in future.<br />
<br />
* Address: beholder.vcmi.eu (67.207.75.182)<br />
* Port 22 serve SFTP for file uploads as well as CI artifacts uploads.<br />
<br />
If new services added firewall rules can be adjusted in [https://cloud.digitalocean.com/networking/firewalls DO control panel].</div>SXXhttps://wiki.vcmi.eu/index.php?title=Project_servers_configuration&diff=2691Project servers configuration2017-09-09T14:49:26Z<p>SXX: Move droplet information here</p>
<hr />
<div>This page dedicated to explain specific configurations of our servers for anyone who might need to improve it in future. Check [[project infrastructure]] page for services and accounts overview.<br />
<br />
== Droplet configuration ==<br />
<br />
=== Droplet and hosted services ===<br />
<br />
Currently we using two droplets:<br />
<br />
* First one serve all of our web services:<br />
** [https://forum.vcmi.eu/ Forum]<br />
** [https://bugs.vcmi.eu/ Bug tracker]<br />
** [https://wiki.vcmi.eu/ Wiki]<br />
** [https://slack.vcmi.eu/ Slack invite page]<br />
* Second serve downloads:<br />
** [http://download.vcmi.eu/ Legacy download page]<br />
** [https://builds.vcmi.download/ Build download page]<br />
<br />
To keep everything secure we should always keep binary downloads separate from any web services.<br />
<br />
=== Rules to stick to ===<br />
<br />
* SSH authentication by public key only.<br />
* Incoming connections to all ports except SSH (22) must be blocked.<br />
* Exception for HTTP(S) connection on ports 80 / 443 from [https://www.cloudflare.com/ips/ CloudFlare IP Ranges].<br />
* No one except core developers should ever know real server IPs.<br />
* Droplet hostname should never be valid host. Otherwise it's exposed in [https://en.wikipedia.org/wiki/Reverse_DNS reverse DNS].<br />
* If some non-web service need to listen for external connections then read below.<br />
<br />
=== Our publicly-facing server ===<br />
We only expose floating IP that can be detached from droplet in case of emergency using [https://cloud.digitalocean.com/networking/floating_ips DO control panel]. This also allow us to easily move public services to dedicated droplet in future.<br />
<br />
* Address: beholder.vcmi.eu (67.207.75.182)<br />
* Port 22 serve SFTP for file uploads as well as CI artifacts uploads.<br />
<br />
If new services added firewall rules can be adjusted in [https://cloud.digitalocean.com/networking/firewalls DO control panel].<br />
<br />
== Services and accounts ==<br />
So far we using following services:</div>SXXhttps://wiki.vcmi.eu/index.php?title=Project_infrastructure&diff=2690Project infrastructure2017-09-09T14:49:07Z<p>SXX: </p>
<hr />
<div>This page hold important information about project infrastructure for current and future contributors. At moment it's all maintained by me (SXX), but following information will be useful if someone going to replace me in future.<br />
<br />
You can also check [[Project servers configuration|detailed information on server configuration]].<br />
<br />
=== Most important ===<br />
<br />
* VCMI.eu domain paid until July of 2019.<br />
** Owner: Tow<br />
** Our main domain used by services.<br />
* VCMI.download paid until November of 2026.<br />
** Owner: SXX<br />
** Intended to be used for all assets downloads.<br />
** Domain registered on GANDI and '''can be renewed by anyone without access to account'''. <br />
* [https://cloud.digitalocean.com/ DigitalOcean] team.<br />
** Our hosting sponsor.<br />
** Administrator access: SXX, Warmonger.<br />
** User access: AVS, Tow.<br />
* [https://www.cloudflare.com/a/overview CloudFlare] account.<br />
** Access through shared login / password.<br />
** All of our infrastructure is behind CloudFlare and all our webWe'll manage our DNS there.<br />
* [https://admin.google.com/ Google Apps (G Suite)] account.<br />
** It's only for vcmi.eu domain and limited to 5 users. Each account has limit of 500 emails / day.<br />
** One administrative email used for other services registration.<br />
** "noreply" email used for outgoing mail on Wiki and Bug Tracker.<br />
** "forum" email used for outgoing mail on Forums. Since we authenticate everyone through forum it's should be separate email.<br />
** Administrator access: Tow, SXX.<br />
* [https://play.google.com/apps/publish/ Google Play Console] account.<br />
** Hold ownership over VCMI Android App.<br />
** Owner: SXX<br />
** Administrator access: Warmonger, AVS.<br />
** Release manager access: Fay.<br />
<br />
Not all services let us safely share login credentials, but at least when possible at least two of core developers must have access to them in case of emergency.<br />
<br />
=== Public relations ===<br />
We want to notify players about updates on as many social services as possible.<br />
<br />
* Facebook page: https://www.facebook.com/VCMIOfficial<br />
** Administrator access: SXX, Warmonger<br />
* Twitter account: https://twitter.com/VCMIOfficial<br />
** Administrator access: SXX.<br />
** User access via TweetDeck: <br />
* VK / VKontakte page: https://vk.com/VCMIOfficial<br />
** Owner: SXX<br />
** Administrator access: AVS<br />
* Google+ page: https://plus.google.com/+VCMIOfficial<br />
** Administrator access: SXX<br />
<br />
Other media:<br />
* Steam group: https://steamcommunity.com/groups/VCMI<br />
** Administrator access: SXX<br />
** Moderator access: Dydzio<br />
* Sub Reddit: https://reddit.com/r/vcmi/<br />
** Administrator access: SXX<br />
* ModDB entry: http://www.moddb.com/engines/vcmi<br />
** Administrator access: SXX<br />
<br />
=== Communication channels ===<br />
* Slack team: https://h3vcmi.slack.com/<br />
** Owner: vmarkovtsev<br />
** Administrator access: SXX, Warmonger, AVS...<br />
* Trello team: https://trello.com/vcmi/<br />
** Administrator access: SXX<br />
* Unofficial discord:<br />
** Owner: dydzio<br />
** Administrator access: SXX<br />
* Unofficial IRC channel: irc.freenode.net #vcmi<br />
<br />
=== Other services ===<br />
* Launchpad PPA: https://launchpad.net/~vcmi<br />
** Member access: SXX<br />
** Administrator access: Ivan<br />
* Snapcraft Dashboard: https://dashboard.snapcraft.io/<br />
** Administrator access: SXX<br />
* Coverity Scan page: https://scan.coverity.com/projects/vcmi<br />
** Administrator access: SXX, Warmonger, AVS<br />
* OpenHub page: https://www.openhub.net/p/VCMI<br />
** Administrator access: Tow<br />
* Docker Hub organization: https://hub.docker.com/u/vcmi/<br />
** Administrator access: SXX<br />
<br />
Reserve accounts for other code hosting services:<br />
* GitLab organization: https://gitlab.com/vcmi/<br />
** Administrator access: SXX<br />
* BitBucket organization: https://bitbucket.org/vcmi/<br />
** Administrator access: SXX<br />
<br />
== What's to improve ==<br />
# Encourage Tow to transfer VCMI.eu to GANDI so it's can be also renewed without access.<br />
# Use 2FA on CloudFlare and just ask everyone to get FreeOTP and then use shared secret.<br />
# Centralized way to post news about game updates to all social media.</div>SXXhttps://wiki.vcmi.eu/index.php?title=Project_infrastructure&diff=2689Project infrastructure2017-09-09T13:13:01Z<p>SXX: /* Other services */</p>
<hr />
<div>This page hold important information about project infrastructure for current and future contributors. At moment it's all maintained by me (SXX), but following information will be useful if someone going to replace me in future.<br />
<br />
You can also check [[Project servers configuration|detailed information on server configuration]].<br />
<br />
== Droplet configuration ==<br />
<br />
=== Droplet and hosted services ===<br />
<br />
Currently we using two droplets:<br />
<br />
* First one serve all of our web services:<br />
** [https://forum.vcmi.eu/ Forum]<br />
** [https://bugs.vcmi.eu/ Bug tracker]<br />
** [https://wiki.vcmi.eu/ Wiki]<br />
** [https://slack.vcmi.eu/ Slack invite page]<br />
* Second serve downloads:<br />
** [http://download.vcmi.eu/ Legacy download page]<br />
** [https://builds.vcmi.download/ Build download page]<br />
<br />
To keep everything secure we should always keep binary downloads separate from any web services.<br />
<br />
=== Rules to stick to ===<br />
<br />
* SSH authentication by public key only.<br />
* Incoming connections to all ports except SSH (22) must be blocked.<br />
* Exception for HTTP(S) connection on ports 80 / 443 from [https://www.cloudflare.com/ips/ CloudFlare IP Ranges].<br />
* No one except core developers should ever know real server IPs.<br />
* Droplet hostname should never be valid host. Otherwise it's exposed in [https://en.wikipedia.org/wiki/Reverse_DNS reverse DNS].<br />
* If some non-web service need to listen for external connections then read below.<br />
<br />
=== Our publicly-facing server ===<br />
We only expose floating IP that can be detached from droplet in case of emergency using [https://cloud.digitalocean.com/networking/floating_ips DO control panel]. This also allow us to easily move public services to dedicated droplet in future.<br />
<br />
* Address: beholder.vcmi.eu (67.207.75.182)<br />
* Port 22 serve SFTP for file uploads as well as CI artifacts uploads.<br />
<br />
If new services added firewall rules can be adjusted in [https://cloud.digitalocean.com/networking/firewalls DO control panel].<br />
<br />
== Services and accounts ==<br />
So far we using following services:<br />
<br />
=== Most important ===<br />
<br />
* VCMI.eu domain paid until July of 2019.<br />
** Owner: Tow<br />
** Our main domain used by services.<br />
* VCMI.download paid until November of 2026.<br />
** Owner: SXX<br />
** Intended to be used for all assets downloads.<br />
** Domain registered on GANDI and '''can be renewed by anyone without access to account'''. <br />
* [https://cloud.digitalocean.com/ DigitalOcean] team.<br />
** Our hosting sponsor.<br />
** Administrator access: SXX, Warmonger.<br />
** User access: AVS, Tow.<br />
* [https://www.cloudflare.com/a/overview CloudFlare] account.<br />
** Access through shared login / password.<br />
** All of our infrastructure is behind CloudFlare and all our webWe'll manage our DNS there.<br />
* [https://admin.google.com/ Google Apps (G Suite)] account.<br />
** It's only for vcmi.eu domain and limited to 5 users. Each account has limit of 500 emails / day.<br />
** One administrative email used for other services registration.<br />
** "noreply" email used for outgoing mail on Wiki and Bug Tracker.<br />
** "forum" email used for outgoing mail on Forums. Since we authenticate everyone through forum it's should be separate email.<br />
** Administrator access: Tow, SXX.<br />
* [https://play.google.com/apps/publish/ Google Play Console] account.<br />
** Hold ownership over VCMI Android App.<br />
** Owner: SXX<br />
** Administrator access: Warmonger, AVS.<br />
** Release manager access: Fay.<br />
<br />
Not all services let us safely share login credentials, but at least when possible at least two of core developers must have access to them in case of emergency.<br />
<br />
=== Public relations ===<br />
We want to notify players about updates on as many social services as possible.<br />
<br />
* Facebook page: https://www.facebook.com/VCMIOfficial<br />
** Administrator access: SXX, Warmonger<br />
* Twitter account: https://twitter.com/VCMIOfficial<br />
** Administrator access: SXX.<br />
** User access via TweetDeck: <br />
* VK / VKontakte page: https://vk.com/VCMIOfficial<br />
** Owner: SXX<br />
** Administrator access: AVS<br />
* Google+ page: https://plus.google.com/+VCMIOfficial<br />
** Administrator access: SXX<br />
<br />
Other media:<br />
* Steam group: https://steamcommunity.com/groups/VCMI<br />
** Administrator access: SXX<br />
** Moderator access: Dydzio<br />
* Sub Reddit: https://reddit.com/r/vcmi/<br />
** Administrator access: SXX<br />
* ModDB entry: http://www.moddb.com/engines/vcmi<br />
** Administrator access: SXX<br />
<br />
=== Communication channels ===<br />
* Slack team: https://h3vcmi.slack.com/<br />
** Owner: vmarkovtsev<br />
** Administrator access: SXX, Warmonger, AVS...<br />
* Trello team: https://trello.com/vcmi/<br />
** Administrator access: SXX<br />
* Unofficial discord:<br />
** Owner: dydzio<br />
** Administrator access: SXX<br />
* Unofficial IRC channel: irc.freenode.net #vcmi<br />
<br />
=== Other services ===<br />
* Launchpad PPA: https://launchpad.net/~vcmi<br />
** Member access: SXX<br />
** Administrator access: Ivan<br />
* Snapcraft Dashboard: https://dashboard.snapcraft.io/<br />
** Administrator access: SXX<br />
* Coverity Scan page: https://scan.coverity.com/projects/vcmi<br />
** Administrator access: SXX, Warmonger, AVS<br />
* OpenHub page: https://www.openhub.net/p/VCMI<br />
** Administrator access: Tow<br />
* Docker Hub organization: https://hub.docker.com/u/vcmi/<br />
** Administrator access: SXX<br />
<br />
Reserve accounts for other code hosting services:<br />
* GitLab organization: https://gitlab.com/vcmi/<br />
** Administrator access: SXX<br />
* BitBucket organization: https://bitbucket.org/vcmi/<br />
** Administrator access: SXX<br />
<br />
== What's to improve ==<br />
# Encourage Tow to transfer VCMI.eu to GANDI so it's can be also renewed without access.<br />
# Use 2FA on CloudFlare and just ask everyone to get FreeOTP and then use shared secret.<br />
# Centralized way to post news about game updates to all social media.</div>SXXhttps://wiki.vcmi.eu/index.php?title=Installation_on_Linux&diff=2688Installation on Linux2017-09-09T01:35:44Z<p>SXX: /* Snappy */</p>
<hr />
<div>VCMI requires data from original Heroes 3: Shadow of Death or Complete editions. Data from native Linux version made by LOKI will not work.<br />
= Binaries installation =<br />
== Ubuntu ==<br />
<br />
VCMI stable builds available in "multiverse" repository. Learn how to enable it in [https://help.ubuntu.com/community/Repositories/Ubuntu Ubuntu wiki].<br />
<br />
VCMI daily builds can be installed from PPA:<br />
* For testing only: https://launchpad.net/~vcmi/+archive/ppa<br />
<br />
To add PPA type in Terminal:<br />
<pre><br />
sudo apt-add-repository ppa:vcmi/ppa<br />
</pre><br />
<br />
To install VCMI from repository:<br />
<pre><br />
sudo apt-get update<br />
sudo apt-get install vcmi<br />
</pre><br />
<br />
== Debian ==<br />
<br />
Stable VCMI version is available in "contrib" repository. Learn how to enable it in [https://wiki.debian.org/SourcesList Debian wiki].<br />
<br />
To install VCMI from repository:<br />
<pre><br />
sudo apt-get update<br />
sudo apt-get install vcmi<br />
</pre><br />
<br />
== Snappy ==<br />
It's possible to install daily VCMI builds as distribution-agnostic Snap package:<br />
<br />
* Visit [https://snapcraft.io/ snapcraft.io] to learn how to get Snappy on your distribution.<br />
* Once it's running install latest VCMI build with:<br />
<pre><br />
sudo snap install --edge vcmi<br />
</pre><br />
* After you can run VCMI with following commands:<br />
<pre><br />
snap run vcmi.vcmilauncher<br />
snap run vcmi.vcmiclient<br />
snap run vcmi.vcmiserver<br />
</pre><br />
* Keep in mind that instead of '''$HOME/.local/share/vcmi/''' you must copy Heroes 3 assets into:<br />
<pre><br />
$HOME/snap/vcmi/current/.local/share/vcmi/<br />
</pre><br />
<br />
'''Warning:''' Snap builds are currently in experimental state.<br />
<br />
Please give your feedback on forum: [https://forum.vcmi.eu/t/experimental-snap-packages-for-linux/4300|Experimental Snap packages for Linux].<br />
<br />
== Other distributions ==<br />
For other distributions, VCMI can be installed from 3rd-party repositories listed below.<br />
* Gentoo https://github.com/qdii/qdiilay/tree/master/games-strategy/vcmi<br />
* Archlinux [https://aur.archlinux.org/packages/vcmi/ vcmi] [https://aur.archlinux.org/packages/vcmi-git/ vcmi-git]<br />
If you are interested in providing builds for other distributions, please let us know.<br />
<br />
== Compiling from source ==<br />
Please check following developer guide: [[How to build VCMI (Linux)]]<br />
<br />
= Installing Heroes III data files =<br />
To install VCMI you will need Heroes III: Shadow of Death or Complete edition.<br />
== Automated install ==<br />
To install Heroes 3 data using automated script you need any of:<br />
* One or two CD's or CD images<br />
* gog.com installer<br />
* Directory with installed game<br />
<br />
Run the script using options appropriate to your input files:<br />
<pre><br />
vcmibuilder --cd1 /path/to/iso/or/cd --cd2 /path/to/second/cd<br />
vcmibuilder --gog /path/to/gog.com/installer<br />
vcmibuilder --data /path/to/h3/data<br />
</pre><br />
You should use only one of these commands.<br />
<br />
=== Music on distributions without Mp3 support ===<br />
To have Music support on Fedora it is required to perform a additional step. Fedora doesn't provide Mp3 playback support natively due to patents applied on the Mp3 technique. The SDL_mixer package from the official Fedora repo is compiled without Mp3 support.<br />
<br />
To make music work it must be converted into ogg format. This can be done either manually or using vcmibuilder:<br />
<pre><br />
vcmibuilder --convertMP3<br />
</pre><br />
This command can be run separately after install or as additional switch during initial vcmibuilder launch<br />
<br />
== Manual install ==<br />
<br />
* Install Heroes III in Wine or manually unpack GOG installer.<br />
<br />
* Copy "Data", "Maps" and "Mp3" from Heroes III to:<br />
<pre>/home/$USER/.local/share/vcmi/</pre><br />
On some distributions $XDG_DATA_HOME could differ so instead you may need to use:<br />
<pre>$XDG_DATA_HOME/vcmi/</pre><br />
<br />
= Launching game =<br />
To start the game type in console:<br />
<pre><br />
vcmilauncher<br />
</pre><br />
Or, to start game directly avoiding Launcher:<br />
<pre><br />
vcmiclient<br />
</pre><br />
VCMI should be also available via desktop environment menu or launcher (Games/Strategy/VCMI)<br />
<br />
= Reporting bugs =<br />
Please report any issues with packages according to <br />
[http://wiki.vcmi.eu/index.php?title=Bug_reporting_guidelines Bug reporting guidelines]</div>SXXhttps://wiki.vcmi.eu/index.php?title=Installation_on_Linux&diff=2687Installation on Linux2017-09-09T01:27:30Z<p>SXX: /* Binaries installation */ Move Snappy section below Ubuntu and Debian</p>
<hr />
<div>VCMI requires data from original Heroes 3: Shadow of Death or Complete editions. Data from native Linux version made by LOKI will not work.<br />
= Binaries installation =<br />
== Ubuntu ==<br />
<br />
VCMI stable builds available in "multiverse" repository. Learn how to enable it in [https://help.ubuntu.com/community/Repositories/Ubuntu Ubuntu wiki].<br />
<br />
VCMI daily builds can be installed from PPA:<br />
* For testing only: https://launchpad.net/~vcmi/+archive/ppa<br />
<br />
To add PPA type in Terminal:<br />
<pre><br />
sudo apt-add-repository ppa:vcmi/ppa<br />
</pre><br />
<br />
To install VCMI from repository:<br />
<pre><br />
sudo apt-get update<br />
sudo apt-get install vcmi<br />
</pre><br />
<br />
== Debian ==<br />
<br />
Stable VCMI version is available in "contrib" repository. Learn how to enable it in [https://wiki.debian.org/SourcesList Debian wiki].<br />
<br />
To install VCMI from repository:<br />
<pre><br />
sudo apt-get update<br />
sudo apt-get install vcmi<br />
</pre><br />
<br />
== Snappy ==<br />
It's possible to install daily VCMI builds as distribution-agnostic Snap package:<br />
<br />
* Visit [https://snapcraft.io/ snapcraft.io] to learn how to get Snappy on your distribution.<br />
* Once it's running install latest VCMI build with:<br />
<pre><br />
sudo snap install --edge vcmi<br />
</pre><br />
* After you can run VCMI with following commands:<br />
<pre><br />
snap run vcmi.vcmilauncher<br />
snap run vcmi.vcmiclient<br />
snap run vcmi.vcmiserver<br />
</pre><br />
* Keep in mind that instead of '''$HOME/.local/share/vcmi/''' you must copy Heroes 3 assets into:<br />
<pre><br />
$HOME/snap/vcmi/current/.local/share/vcmi/<br />
</pre><br />
<br />
'''Warning:''' Snap builds are currently in experimental state.<br />
<br />
Please give your feedback on forum: [https://forum.vcmi.eu/t/experimental-snap-packages-for-linux/4300 <br />
Experimental Snap packages for Linux].<br />
<br />
== Other distributions ==<br />
For other distributions, VCMI can be installed from 3rd-party repositories listed below.<br />
* Gentoo https://github.com/qdii/qdiilay/tree/master/games-strategy/vcmi<br />
* Archlinux [https://aur.archlinux.org/packages/vcmi/ vcmi] [https://aur.archlinux.org/packages/vcmi-git/ vcmi-git]<br />
If you are interested in providing builds for other distributions, please let us know.<br />
<br />
== Compiling from source ==<br />
Please check following developer guide: [[How to build VCMI (Linux)]]<br />
<br />
= Installing Heroes III data files =<br />
To install VCMI you will need Heroes III: Shadow of Death or Complete edition.<br />
== Automated install ==<br />
To install Heroes 3 data using automated script you need any of:<br />
* One or two CD's or CD images<br />
* gog.com installer<br />
* Directory with installed game<br />
<br />
Run the script using options appropriate to your input files:<br />
<pre><br />
vcmibuilder --cd1 /path/to/iso/or/cd --cd2 /path/to/second/cd<br />
vcmibuilder --gog /path/to/gog.com/installer<br />
vcmibuilder --data /path/to/h3/data<br />
</pre><br />
You should use only one of these commands.<br />
<br />
=== Music on distributions without Mp3 support ===<br />
To have Music support on Fedora it is required to perform a additional step. Fedora doesn't provide Mp3 playback support natively due to patents applied on the Mp3 technique. The SDL_mixer package from the official Fedora repo is compiled without Mp3 support.<br />
<br />
To make music work it must be converted into ogg format. This can be done either manually or using vcmibuilder:<br />
<pre><br />
vcmibuilder --convertMP3<br />
</pre><br />
This command can be run separately after install or as additional switch during initial vcmibuilder launch<br />
<br />
== Manual install ==<br />
<br />
* Install Heroes III in Wine or manually unpack GOG installer.<br />
<br />
* Copy "Data", "Maps" and "Mp3" from Heroes III to:<br />
<pre>/home/$USER/.local/share/vcmi/</pre><br />
On some distributions $XDG_DATA_HOME could differ so instead you may need to use:<br />
<pre>$XDG_DATA_HOME/vcmi/</pre><br />
<br />
= Launching game =<br />
To start the game type in console:<br />
<pre><br />
vcmilauncher<br />
</pre><br />
Or, to start game directly avoiding Launcher:<br />
<pre><br />
vcmiclient<br />
</pre><br />
VCMI should be also available via desktop environment menu or launcher (Games/Strategy/VCMI)<br />
<br />
= Reporting bugs =<br />
Please report any issues with packages according to <br />
[http://wiki.vcmi.eu/index.php?title=Bug_reporting_guidelines Bug reporting guidelines]</div>SXXhttps://wiki.vcmi.eu/index.php?title=Installation_on_Linux&diff=2686Installation on Linux2017-09-09T01:26:47Z<p>SXX: /* Snappy */</p>
<hr />
<div>VCMI requires data from original Heroes 3: Shadow of Death or Complete editions. Data from native Linux version made by LOKI will not work.<br />
= Binaries installation =<br />
== Snappy ==<br />
It's possible to install daily VCMI builds as distribution-agnostic Snap package:<br />
<br />
* Visit [https://snapcraft.io/ snapcraft.io] to learn how to get Snappy on your distribution.<br />
* Once it's running install latest VCMI build with:<br />
<pre><br />
sudo snap install --edge vcmi<br />
</pre><br />
* After you can run VCMI with following commands:<br />
<pre><br />
snap run vcmi.vcmilauncher<br />
snap run vcmi.vcmiclient<br />
snap run vcmi.vcmiserver<br />
</pre><br />
* Keep in mind that instead of '''$HOME/.local/share/vcmi/''' you must copy Heroes 3 assets into:<br />
<pre><br />
$HOME/snap/vcmi/current/.local/share/vcmi/<br />
</pre><br />
<br />
'''Warning:''' Snap builds are currently in experimental state.<br />
<br />
Please give your feedback on forum: [https://forum.vcmi.eu/t/experimental-snap-packages-for-linux/4300 <br />
Experimental Snap packages for Linux].<br />
<br />
== Ubuntu ==<br />
<br />
VCMI stable builds available in "multiverse" repository. Learn how to enable it in [https://help.ubuntu.com/community/Repositories/Ubuntu Ubuntu wiki].<br />
<br />
VCMI daily builds can be installed from PPA:<br />
* For testing only: https://launchpad.net/~vcmi/+archive/ppa<br />
<br />
To add PPA type in Terminal:<br />
<pre><br />
sudo apt-add-repository ppa:vcmi/ppa<br />
</pre><br />
<br />
To install VCMI from repository:<br />
<pre><br />
sudo apt-get update<br />
sudo apt-get install vcmi<br />
</pre><br />
<br />
== Debian ==<br />
<br />
Stable VCMI version is available in "contrib" repository. Learn how to enable it in [https://wiki.debian.org/SourcesList Debian wiki].<br />
<br />
To install VCMI from repository:<br />
<pre><br />
sudo apt-get update<br />
sudo apt-get install vcmi<br />
</pre><br />
<br />
== Other distributions ==<br />
For other distributions, VCMI can be installed from 3rd-party repositories listed below.<br />
* Gentoo https://github.com/qdii/qdiilay/tree/master/games-strategy/vcmi<br />
* Archlinux [https://aur.archlinux.org/packages/vcmi/ vcmi] [https://aur.archlinux.org/packages/vcmi-git/ vcmi-git]<br />
If you are interested in providing builds for other distributions, please let us know.<br />
<br />
== Compiling from source ==<br />
Please check following developer guide: [[How to build VCMI (Linux)]]<br />
<br />
= Installing Heroes III data files =<br />
To install VCMI you will need Heroes III: Shadow of Death or Complete edition.<br />
== Automated install ==<br />
To install Heroes 3 data using automated script you need any of:<br />
* One or two CD's or CD images<br />
* gog.com installer<br />
* Directory with installed game<br />
<br />
Run the script using options appropriate to your input files:<br />
<pre><br />
vcmibuilder --cd1 /path/to/iso/or/cd --cd2 /path/to/second/cd<br />
vcmibuilder --gog /path/to/gog.com/installer<br />
vcmibuilder --data /path/to/h3/data<br />
</pre><br />
You should use only one of these commands.<br />
<br />
=== Music on distributions without Mp3 support ===<br />
To have Music support on Fedora it is required to perform a additional step. Fedora doesn't provide Mp3 playback support natively due to patents applied on the Mp3 technique. The SDL_mixer package from the official Fedora repo is compiled without Mp3 support.<br />
<br />
To make music work it must be converted into ogg format. This can be done either manually or using vcmibuilder:<br />
<pre><br />
vcmibuilder --convertMP3<br />
</pre><br />
This command can be run separately after install or as additional switch during initial vcmibuilder launch<br />
<br />
== Manual install ==<br />
<br />
* Install Heroes III in Wine or manually unpack GOG installer.<br />
<br />
* Copy "Data", "Maps" and "Mp3" from Heroes III to:<br />
<pre>/home/$USER/.local/share/vcmi/</pre><br />
On some distributions $XDG_DATA_HOME could differ so instead you may need to use:<br />
<pre>$XDG_DATA_HOME/vcmi/</pre><br />
<br />
= Launching game =<br />
To start the game type in console:<br />
<pre><br />
vcmilauncher<br />
</pre><br />
Or, to start game directly avoiding Launcher:<br />
<pre><br />
vcmiclient<br />
</pre><br />
VCMI should be also available via desktop environment menu or launcher (Games/Strategy/VCMI)<br />
<br />
= Reporting bugs =<br />
Please report any issues with packages according to <br />
[http://wiki.vcmi.eu/index.php?title=Bug_reporting_guidelines Bug reporting guidelines]</div>SXXhttps://wiki.vcmi.eu/index.php?title=Installation_on_Linux&diff=2685Installation on Linux2017-09-09T01:26:13Z<p>SXX: /* Binaries installation */</p>
<hr />
<div>VCMI requires data from original Heroes 3: Shadow of Death or Complete editions. Data from native Linux version made by LOKI will not work.<br />
= Binaries installation =<br />
== Snappy ==<br />
It's possible to install VCMI as distribution-agnostic Snap package:<br />
<br />
* Visit [https://snapcraft.io/ snapcraft.io] to learn how to get Snappy on your distribution.<br />
* Once it's running install latest VCMI build with:<br />
<pre><br />
sudo snap install --edge vcmi<br />
</pre><br />
* After you can run VCMI with following commands:<br />
<pre><br />
snap run vcmi.vcmilauncher<br />
snap run vcmi.vcmiclient<br />
snap run vcmi.vcmiserver<br />
</pre><br />
* Keep in mind that instead of '''$HOME/.local/share/vcmi/''' you must copy Heroes 3 assets into:<br />
<pre><br />
$HOME/snap/vcmi/current/.local/share/vcmi/<br />
</pre><br />
<br />
'''Warning:''' Snap builds are currently in experimental state.<br />
<br />
Please give your feedback on forum: [https://forum.vcmi.eu/t/experimental-snap-packages-for-linux/4300 <br />
Experimental Snap packages for Linux].<br />
<br />
== Ubuntu ==<br />
<br />
VCMI stable builds available in "multiverse" repository. Learn how to enable it in [https://help.ubuntu.com/community/Repositories/Ubuntu Ubuntu wiki].<br />
<br />
VCMI daily builds can be installed from PPA:<br />
* For testing only: https://launchpad.net/~vcmi/+archive/ppa<br />
<br />
To add PPA type in Terminal:<br />
<pre><br />
sudo apt-add-repository ppa:vcmi/ppa<br />
</pre><br />
<br />
To install VCMI from repository:<br />
<pre><br />
sudo apt-get update<br />
sudo apt-get install vcmi<br />
</pre><br />
<br />
== Debian ==<br />
<br />
Stable VCMI version is available in "contrib" repository. Learn how to enable it in [https://wiki.debian.org/SourcesList Debian wiki].<br />
<br />
To install VCMI from repository:<br />
<pre><br />
sudo apt-get update<br />
sudo apt-get install vcmi<br />
</pre><br />
<br />
== Other distributions ==<br />
For other distributions, VCMI can be installed from 3rd-party repositories listed below.<br />
* Gentoo https://github.com/qdii/qdiilay/tree/master/games-strategy/vcmi<br />
* Archlinux [https://aur.archlinux.org/packages/vcmi/ vcmi] [https://aur.archlinux.org/packages/vcmi-git/ vcmi-git]<br />
If you are interested in providing builds for other distributions, please let us know.<br />
<br />
== Compiling from source ==<br />
Please check following developer guide: [[How to build VCMI (Linux)]]<br />
<br />
= Installing Heroes III data files =<br />
To install VCMI you will need Heroes III: Shadow of Death or Complete edition.<br />
== Automated install ==<br />
To install Heroes 3 data using automated script you need any of:<br />
* One or two CD's or CD images<br />
* gog.com installer<br />
* Directory with installed game<br />
<br />
Run the script using options appropriate to your input files:<br />
<pre><br />
vcmibuilder --cd1 /path/to/iso/or/cd --cd2 /path/to/second/cd<br />
vcmibuilder --gog /path/to/gog.com/installer<br />
vcmibuilder --data /path/to/h3/data<br />
</pre><br />
You should use only one of these commands.<br />
<br />
=== Music on distributions without Mp3 support ===<br />
To have Music support on Fedora it is required to perform a additional step. Fedora doesn't provide Mp3 playback support natively due to patents applied on the Mp3 technique. The SDL_mixer package from the official Fedora repo is compiled without Mp3 support.<br />
<br />
To make music work it must be converted into ogg format. This can be done either manually or using vcmibuilder:<br />
<pre><br />
vcmibuilder --convertMP3<br />
</pre><br />
This command can be run separately after install or as additional switch during initial vcmibuilder launch<br />
<br />
== Manual install ==<br />
<br />
* Install Heroes III in Wine or manually unpack GOG installer.<br />
<br />
* Copy "Data", "Maps" and "Mp3" from Heroes III to:<br />
<pre>/home/$USER/.local/share/vcmi/</pre><br />
On some distributions $XDG_DATA_HOME could differ so instead you may need to use:<br />
<pre>$XDG_DATA_HOME/vcmi/</pre><br />
<br />
= Launching game =<br />
To start the game type in console:<br />
<pre><br />
vcmilauncher<br />
</pre><br />
Or, to start game directly avoiding Launcher:<br />
<pre><br />
vcmiclient<br />
</pre><br />
VCMI should be also available via desktop environment menu or launcher (Games/Strategy/VCMI)<br />
<br />
= Reporting bugs =<br />
Please report any issues with packages according to <br />
[http://wiki.vcmi.eu/index.php?title=Bug_reporting_guidelines Bug reporting guidelines]</div>SXXhttps://wiki.vcmi.eu/index.php?title=Installation_on_Linux&diff=2684Installation on Linux2017-09-09T01:26:00Z<p>SXX: /* Snappy */</p>
<hr />
<div>VCMI requires data from original Heroes 3: Shadow of Death or Complete editions. Data from native Linux version made by LOKI will not work.<br />
= Binaries installation =<br />
== Snappy ==<br />
It's possible to install VCMI as distribution-agnostic Snap package:<br />
<br />
* Visit [https://snapcraft.io/ snapcraft.io] to learn how to get Snappy on your distribution.<br />
* Once it's running install latest VCMI build with:<br />
<pre><br />
sudo snap install --edge vcmi<br />
</pre><br />
* After you can run VCMI with following commands:<br />
<pre><br />
snap run vcmi.vcmilauncher<br />
snap run vcmi.vcmiclient<br />
snap run vcmi.vcmiserver<br />
</pre><br />
* Keep in mind that instead of '''$HOME/.local/share/vcmi/''' you must copy Heroes 3 assets into:<br />
<pre><br />
$HOME/snap/vcmi/current/.local/share/vcmi/<br />
</pre><br />
<br />
'''Warning:''' Snap builds are currently in experimental state.<br />
Please give your feedback on forum: [https://forum.vcmi.eu/t/experimental-snap-packages-for-linux/4300 <br />
Experimental Snap packages for Linux].<br />
<br />
== Ubuntu ==<br />
<br />
VCMI stable builds available in "multiverse" repository. Learn how to enable it in [https://help.ubuntu.com/community/Repositories/Ubuntu Ubuntu wiki].<br />
<br />
VCMI daily builds can be installed from PPA:<br />
* For testing only: https://launchpad.net/~vcmi/+archive/ppa<br />
<br />
To add PPA type in Terminal:<br />
<pre><br />
sudo apt-add-repository ppa:vcmi/ppa<br />
</pre><br />
<br />
To install VCMI from repository:<br />
<pre><br />
sudo apt-get update<br />
sudo apt-get install vcmi<br />
</pre><br />
<br />
== Debian ==<br />
<br />
Stable VCMI version is available in "contrib" repository. Learn how to enable it in [https://wiki.debian.org/SourcesList Debian wiki].<br />
<br />
To install VCMI from repository:<br />
<pre><br />
sudo apt-get update<br />
sudo apt-get install vcmi<br />
</pre><br />
<br />
== Other distributions ==<br />
For other distributions, VCMI can be installed from 3rd-party repositories listed below.<br />
* Gentoo https://github.com/qdii/qdiilay/tree/master/games-strategy/vcmi<br />
* Archlinux [https://aur.archlinux.org/packages/vcmi/ vcmi] [https://aur.archlinux.org/packages/vcmi-git/ vcmi-git]<br />
If you are interested in providing builds for other distributions, please let us know.<br />
<br />
== Compiling from source ==<br />
Please check following developer guide: [[How to build VCMI (Linux)]]<br />
<br />
= Installing Heroes III data files =<br />
To install VCMI you will need Heroes III: Shadow of Death or Complete edition.<br />
== Automated install ==<br />
To install Heroes 3 data using automated script you need any of:<br />
* One or two CD's or CD images<br />
* gog.com installer<br />
* Directory with installed game<br />
<br />
Run the script using options appropriate to your input files:<br />
<pre><br />
vcmibuilder --cd1 /path/to/iso/or/cd --cd2 /path/to/second/cd<br />
vcmibuilder --gog /path/to/gog.com/installer<br />
vcmibuilder --data /path/to/h3/data<br />
</pre><br />
You should use only one of these commands.<br />
<br />
=== Music on distributions without Mp3 support ===<br />
To have Music support on Fedora it is required to perform a additional step. Fedora doesn't provide Mp3 playback support natively due to patents applied on the Mp3 technique. The SDL_mixer package from the official Fedora repo is compiled without Mp3 support.<br />
<br />
To make music work it must be converted into ogg format. This can be done either manually or using vcmibuilder:<br />
<pre><br />
vcmibuilder --convertMP3<br />
</pre><br />
This command can be run separately after install or as additional switch during initial vcmibuilder launch<br />
<br />
== Manual install ==<br />
<br />
* Install Heroes III in Wine or manually unpack GOG installer.<br />
<br />
* Copy "Data", "Maps" and "Mp3" from Heroes III to:<br />
<pre>/home/$USER/.local/share/vcmi/</pre><br />
On some distributions $XDG_DATA_HOME could differ so instead you may need to use:<br />
<pre>$XDG_DATA_HOME/vcmi/</pre><br />
<br />
= Launching game =<br />
To start the game type in console:<br />
<pre><br />
vcmilauncher<br />
</pre><br />
Or, to start game directly avoiding Launcher:<br />
<pre><br />
vcmiclient<br />
</pre><br />
VCMI should be also available via desktop environment menu or launcher (Games/Strategy/VCMI)<br />
<br />
= Reporting bugs =<br />
Please report any issues with packages according to <br />
[http://wiki.vcmi.eu/index.php?title=Bug_reporting_guidelines Bug reporting guidelines]</div>SXXhttps://wiki.vcmi.eu/index.php?title=Installation_on_Linux&diff=2683Installation on Linux2017-09-09T01:04:37Z<p>SXX: /* Binaries installation */</p>
<hr />
<div>VCMI requires data from original Heroes 3: Shadow of Death or Complete editions. Data from native Linux version made by LOKI will not work.<br />
= Binaries installation =<br />
== Snappy ==<br />
It's possible to install VCMI as distribution-agnostic Snap package:<br />
<br />
* Visit [https://snapcraft.io/ snapcraft.io] to learn how to get Snappy on your distribution.<br />
* Once it's running install latest VCMI build with:<br />
<pre><br />
sudo snap install --edge vcmi<br />
</pre><br />
* After you can run VCMI with following commands:<br />
<pre><br />
snap run vcmi.vcmilauncher<br />
snap run vcmi.vcmiclient<br />
snap run vcmi.vcmiserver<br />
</pre><br />
* Keep in mind that instead of '''$HOME/.local/share/vcmi/''' you must copy Heroes 3 assets into:<br />
<pre><br />
$HOME/snap/vcmi/current/.local/share/vcmi/<br />
</pre><br />
<br />
'''Warning:''' Snap builds are currently in experimental state.<br />
<br />
== Ubuntu ==<br />
<br />
VCMI stable builds available in "multiverse" repository. Learn how to enable it in [https://help.ubuntu.com/community/Repositories/Ubuntu Ubuntu wiki].<br />
<br />
VCMI daily builds can be installed from PPA:<br />
* For testing only: https://launchpad.net/~vcmi/+archive/ppa<br />
<br />
To add PPA type in Terminal:<br />
<pre><br />
sudo apt-add-repository ppa:vcmi/ppa<br />
</pre><br />
<br />
To install VCMI from repository:<br />
<pre><br />
sudo apt-get update<br />
sudo apt-get install vcmi<br />
</pre><br />
<br />
== Debian ==<br />
<br />
Stable VCMI version is available in "contrib" repository. Learn how to enable it in [https://wiki.debian.org/SourcesList Debian wiki].<br />
<br />
To install VCMI from repository:<br />
<pre><br />
sudo apt-get update<br />
sudo apt-get install vcmi<br />
</pre><br />
<br />
== Other distributions ==<br />
For other distributions, VCMI can be installed from 3rd-party repositories listed below.<br />
* Gentoo https://github.com/qdii/qdiilay/tree/master/games-strategy/vcmi<br />
* Archlinux [https://aur.archlinux.org/packages/vcmi/ vcmi] [https://aur.archlinux.org/packages/vcmi-git/ vcmi-git]<br />
If you are interested in providing builds for other distributions, please let us know.<br />
<br />
== Compiling from source ==<br />
Please check following developer guide: [[How to build VCMI (Linux)]]<br />
<br />
= Installing Heroes III data files =<br />
To install VCMI you will need Heroes III: Shadow of Death or Complete edition.<br />
== Automated install ==<br />
To install Heroes 3 data using automated script you need any of:<br />
* One or two CD's or CD images<br />
* gog.com installer<br />
* Directory with installed game<br />
<br />
Run the script using options appropriate to your input files:<br />
<pre><br />
vcmibuilder --cd1 /path/to/iso/or/cd --cd2 /path/to/second/cd<br />
vcmibuilder --gog /path/to/gog.com/installer<br />
vcmibuilder --data /path/to/h3/data<br />
</pre><br />
You should use only one of these commands.<br />
<br />
=== Music on distributions without Mp3 support ===<br />
To have Music support on Fedora it is required to perform a additional step. Fedora doesn't provide Mp3 playback support natively due to patents applied on the Mp3 technique. The SDL_mixer package from the official Fedora repo is compiled without Mp3 support.<br />
<br />
To make music work it must be converted into ogg format. This can be done either manually or using vcmibuilder:<br />
<pre><br />
vcmibuilder --convertMP3<br />
</pre><br />
This command can be run separately after install or as additional switch during initial vcmibuilder launch<br />
<br />
== Manual install ==<br />
<br />
* Install Heroes III in Wine or manually unpack GOG installer.<br />
<br />
* Copy "Data", "Maps" and "Mp3" from Heroes III to:<br />
<pre>/home/$USER/.local/share/vcmi/</pre><br />
On some distributions $XDG_DATA_HOME could differ so instead you may need to use:<br />
<pre>$XDG_DATA_HOME/vcmi/</pre><br />
<br />
= Launching game =<br />
To start the game type in console:<br />
<pre><br />
vcmilauncher<br />
</pre><br />
Or, to start game directly avoiding Launcher:<br />
<pre><br />
vcmiclient<br />
</pre><br />
VCMI should be also available via desktop environment menu or launcher (Games/Strategy/VCMI)<br />
<br />
= Reporting bugs =<br />
Please report any issues with packages according to <br />
[http://wiki.vcmi.eu/index.php?title=Bug_reporting_guidelines Bug reporting guidelines]</div>SXXhttps://wiki.vcmi.eu/index.php?title=Project_infrastructure&diff=2678Project infrastructure2017-09-06T20:40:41Z<p>SXX: /* Most important */</p>
<hr />
<div>This page hold important information about project infrastructure for current and future contributors. At moment it's all maintained by me (SXX), but following information will be useful if someone going to replace me in future.<br />
<br />
You can also check [[Project servers configuration|detailed information on server configuration]].<br />
<br />
== Droplet configuration ==<br />
<br />
=== Droplet and hosted services ===<br />
<br />
Currently we using two droplets:<br />
<br />
* First one serve all of our web services:<br />
** [https://forum.vcmi.eu/ Forum]<br />
** [https://bugs.vcmi.eu/ Bug tracker]<br />
** [https://wiki.vcmi.eu/ Wiki]<br />
** [https://slack.vcmi.eu/ Slack invite page]<br />
* Second serve downloads:<br />
** [http://download.vcmi.eu/ Legacy download page]<br />
** [https://builds.vcmi.download/ Build download page]<br />
<br />
To keep everything secure we should always keep binary downloads separate from any web services.<br />
<br />
=== Rules to stick to ===<br />
<br />
* SSH authentication by public key only.<br />
* Incoming connections to all ports except SSH (22) must be blocked.<br />
* Exception for HTTP(S) connection on ports 80 / 443 from [https://www.cloudflare.com/ips/ CloudFlare IP Ranges].<br />
* No one except core developers should ever know real server IPs.<br />
* Droplet hostname should never be valid host. Otherwise it's exposed in [https://en.wikipedia.org/wiki/Reverse_DNS reverse DNS].<br />
* If some non-web service need to listen for external connections then read below.<br />
<br />
=== Our publicly-facing server ===<br />
We only expose floating IP that can be detached from droplet in case of emergency using [https://cloud.digitalocean.com/networking/floating_ips DO control panel]. This also allow us to easily move public services to dedicated droplet in future.<br />
<br />
* Address: beholder.vcmi.eu (67.207.75.182)<br />
* Port 22 serve SFTP for file uploads as well as CI artifacts uploads.<br />
<br />
If new services added firewall rules can be adjusted in [https://cloud.digitalocean.com/networking/firewalls DO control panel].<br />
<br />
== Services and accounts ==<br />
So far we using following services:<br />
<br />
=== Most important ===<br />
<br />
* VCMI.eu domain paid until July of 2019.<br />
** Owner: Tow<br />
** Our main domain used by services.<br />
* VCMI.download paid until November of 2026.<br />
** Owner: SXX<br />
** Intended to be used for all assets downloads.<br />
** Domain registered on GANDI and '''can be renewed by anyone without access to account'''. <br />
* [https://cloud.digitalocean.com/ DigitalOcean] team.<br />
** Our hosting sponsor.<br />
** Administrator access: SXX, Warmonger.<br />
** User access: AVS, Tow.<br />
* [https://www.cloudflare.com/a/overview CloudFlare] account.<br />
** Access through shared login / password.<br />
** All of our infrastructure is behind CloudFlare and all our webWe'll manage our DNS there.<br />
* [https://admin.google.com/ Google Apps (G Suite)] account.<br />
** It's only for vcmi.eu domain and limited to 5 users. Each account has limit of 500 emails / day.<br />
** One administrative email used for other services registration.<br />
** "noreply" email used for outgoing mail on Wiki and Bug Tracker.<br />
** "forum" email used for outgoing mail on Forums. Since we authenticate everyone through forum it's should be separate email.<br />
** Administrator access: Tow, SXX.<br />
* [https://play.google.com/apps/publish/ Google Play Console] account.<br />
** Hold ownership over VCMI Android App.<br />
** Owner: SXX<br />
** Administrator access: Warmonger, AVS.<br />
** Release manager access: Fay.<br />
<br />
Not all services let us safely share login credentials, but at least when possible at least two of core developers must have access to them in case of emergency.<br />
<br />
=== Public relations ===<br />
We want to notify players about updates on as many social services as possible.<br />
<br />
* Facebook page: https://www.facebook.com/VCMIOfficial<br />
** Administrator access: SXX, Warmonger<br />
* Twitter account: https://twitter.com/VCMIOfficial<br />
** Administrator access: SXX.<br />
** User access via TweetDeck: <br />
* VK / VKontakte page: https://vk.com/VCMIOfficial<br />
** Owner: SXX<br />
** Administrator access: AVS<br />
* Google+ page: https://plus.google.com/+VCMIOfficial<br />
** Administrator access: SXX<br />
<br />
Other media:<br />
* Steam group: https://steamcommunity.com/groups/VCMI<br />
** Administrator access: SXX<br />
** Moderator access: Dydzio<br />
* Sub Reddit: https://reddit.com/r/vcmi/<br />
** Administrator access: SXX<br />
* ModDB entry: http://www.moddb.com/engines/vcmi<br />
** Administrator access: SXX<br />
<br />
=== Communication channels ===<br />
* Slack team: https://h3vcmi.slack.com/<br />
** Owner: vmarkovtsev<br />
** Administrator access: SXX, Warmonger, AVS...<br />
* Trello team: https://trello.com/vcmi/<br />
** Administrator access: SXX<br />
* Unofficial discord:<br />
** Owner: dydzio<br />
** Administrator access: SXX<br />
* Unofficial IRC channel: irc.freenode.net #vcmi<br />
<br />
=== Other services ===<br />
* Launchpad PPA: https://launchpad.net/~vcmi<br />
** Member access: SXX<br />
** Administrator access: Ivan<br />
* Coverity Scan page: https://scan.coverity.com/projects/vcmi<br />
** Administrator access: SXX, Warmonger, AVS<br />
* OpenHub page: https://www.openhub.net/p/VCMI<br />
** Administrator access: Tow<br />
* Docker Hub organization: https://hub.docker.com/u/vcmi/<br />
** Administrator access: SXX<br />
<br />
Reserve accounts for other code hosting services:<br />
* GitLab organization: https://gitlab.com/vcmi/<br />
** Administrator access: SXX<br />
* BitBucket organization: https://bitbucket.org/vcmi/<br />
** Administrator access: SXX<br />
<br />
== What's to improve ==<br />
# Encourage Tow to transfer VCMI.eu to GANDI so it's can be also renewed without access.<br />
# Use 2FA on CloudFlare and just ask everyone to get FreeOTP and then use shared secret.<br />
# Centralized way to post news about game updates to all social media.</div>SXXhttps://wiki.vcmi.eu/index.php?title=Skill_Format&diff=2677Skill Format2017-09-06T20:37:07Z<p>SXX: </p>
<hr />
<div>Work in progress. Currently you can only modify existing secondary skills, not add new ones.<br />
<br />
== Main format ==<br />
<syntaxhighlight lang="javascript"><br />
{<br />
"skillName":<br />
{<br />
//numeric id of skill required only for original skills, prohibited for new skills<br />
"index": 0,<br />
//Mandatory<br />
"name": "Localizable name",<br />
//optional base format, will be merged with basic/advanced/expert<br />
"base": {Skill level base format},<br />
//configuration for different skill levels<br />
"basic": {Skill level format},<br />
"advanced": {Skill level format},<br />
"expert": {Skill level format}<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
== Skill level base format ==<br />
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.<br />
<br />
== Skill level format ==<br />
<syntaxhighlight lang="javascript"><br />
{<br />
//Optional, localizable description<br />
//Use {xxx} for formatting<br />
"description": "",<br />
//Bonuses provided by skill at given level<br />
//If different levels provide same bonus with different val, only the highest applies<br />
"effects":<br />
{<br />
"firstEffect": {bonus format},<br />
"secondEffect": {bonus format}<br />
//...<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
== Example ==<br />
The following modifies the tactics skill to grant an additional speed boost at advanced and expert levels.<br />
<syntaxhighlight lang="javascript"><br />
"core:tactics" : {<br />
"base" : {<br />
"effects" : {<br />
"main" : {<br />
"subtype" : "skill.tactics",<br />
"type" : "SECONDARY_SKILL_PREMY",<br />
"valueType" : "BASE_NUMBER"<br />
},<br />
"xtra" : {<br />
"type" : "STACKS_SPEED",<br />
"valueType" : "BASE_NUMBER"<br />
}<br />
}<br />
},<br />
"basic" : {<br />
"effects" : {<br />
"main" : { "val" : 3 },<br />
"xtra" : { "val" : 0 }<br />
}<br />
},<br />
"advanced" : {<br />
"description" : "{Advanced Tactics}\n\nAllows you to rearrange troups within 5 hex rows, and increases their speed by 1.",<br />
"effects" : {<br />
"main" : { "val" : 5 },<br />
"xtra" : { "val" : 1 }<br />
}<br />
},<br />
"expert" : {<br />
"description" : "{Expert Tactics}\n\nAllows you to rearrange troups within 7 hex rows, and increases their speed by 2.",<br />
"effects" : {<br />
"main" : { "val" : 7 },<br />
"xtra" : { "val" : 2 }<br />
}<br />
}<br />
}<br />
</syntaxhighlight></div>SXXhttps://wiki.vcmi.eu/index.php?title=Project_infrastructure&diff=2676Project infrastructure2017-09-06T20:35:56Z<p>SXX: Protected "Project infrastructure" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))</p>
<hr />
<div>This page hold important information about project infrastructure for current and future contributors. At moment it's all maintained by me (SXX), but following information will be useful if someone going to replace me in future.<br />
<br />
You can also check [[Project servers configuration|detailed information on server configuration]].<br />
<br />
== Droplet configuration ==<br />
<br />
=== Droplet and hosted services ===<br />
<br />
Currently we using two droplets:<br />
<br />
* First one serve all of our web services:<br />
** [https://forum.vcmi.eu/ Forum]<br />
** [https://bugs.vcmi.eu/ Bug tracker]<br />
** [https://wiki.vcmi.eu/ Wiki]<br />
** [https://slack.vcmi.eu/ Slack invite page]<br />
* Second serve downloads:<br />
** [http://download.vcmi.eu/ Legacy download page]<br />
** [https://builds.vcmi.download/ Build download page]<br />
<br />
To keep everything secure we should always keep binary downloads separate from any web services.<br />
<br />
=== Rules to stick to ===<br />
<br />
* SSH authentication by public key only.<br />
* Incoming connections to all ports except SSH (22) must be blocked.<br />
* Exception for HTTP(S) connection on ports 80 / 443 from [https://www.cloudflare.com/ips/ CloudFlare IP Ranges].<br />
* No one except core developers should ever know real server IPs.<br />
* Droplet hostname should never be valid host. Otherwise it's exposed in [https://en.wikipedia.org/wiki/Reverse_DNS reverse DNS].<br />
* If some non-web service need to listen for external connections then read below.<br />
<br />
=== Our publicly-facing server ===<br />
We only expose floating IP that can be detached from droplet in case of emergency using [https://cloud.digitalocean.com/networking/floating_ips DO control panel]. This also allow us to easily move public services to dedicated droplet in future.<br />
<br />
* Address: beholder.vcmi.eu (67.207.75.182)<br />
* Port 22 serve SFTP for file uploads as well as CI artifacts uploads.<br />
<br />
If new services added firewall rules can be adjusted in [https://cloud.digitalocean.com/networking/firewalls DO control panel].<br />
<br />
== Services and accounts ==<br />
So far we using following services:<br />
<br />
=== Most important ===<br />
<br />
* VCMI.eu domain paid until July of 2019.<br />
** Owner: Tow<br />
** Our main domain used by services.<br />
* VCMI.download paid until November of 2026.<br />
** Owner: SXX<br />
** Intended to be used for all assets downloads.<br />
** Domain registered on GANDI and '''can be renewed by anyone without access to account'''. <br />
* [https://cloud.digitalocean.com/ DigitalOcean] team.<br />
** Our hosting sponsor.<br />
** Administrator access: SXX, Warmonger.<br />
** User access: AVS, Tow.<br />
* [https://www.cloudflare.com/a/overview CloudFlare] account.<br />
** Access through shared login / password.<br />
** All of our infrastructure is behind CloudFlare and all our webWe'll manage our DNS there.<br />
* [https://admin.google.com/ Google Apps (G Suite)] account.<br />
** It's only for vcmi.eu domain and limited to 5 users.<br />
** One administrative email used for other services registration.<br />
** Second "noreply" email used for outgoing mail. Has limit of 500 emails / day.<br />
** Administrator access: Tow, SXX. One more slot is available.<br />
* [https://play.google.com/apps/publish/ Google Play Console] account.<br />
** Hold ownership over VCMI Android App.<br />
** Owner: SXX<br />
** Administrator access: Warmonger, AVS.<br />
** Release manager access: Fay.<br />
<br />
Not all services let us safely share login credentials, but at least when possible at least two of core developers must have access to them in case of emergency.<br />
<br />
=== Public relations ===<br />
We want to notify players about updates on as many social services as possible.<br />
<br />
* Facebook page: https://www.facebook.com/VCMIOfficial<br />
** Administrator access: SXX, Warmonger<br />
* Twitter account: https://twitter.com/VCMIOfficial<br />
** Administrator access: SXX.<br />
** User access via TweetDeck: <br />
* VK / VKontakte page: https://vk.com/VCMIOfficial<br />
** Owner: SXX<br />
** Administrator access: AVS<br />
* Google+ page: https://plus.google.com/+VCMIOfficial<br />
** Administrator access: SXX<br />
<br />
Other media:<br />
* Steam group: https://steamcommunity.com/groups/VCMI<br />
** Administrator access: SXX<br />
** Moderator access: Dydzio<br />
* Sub Reddit: https://reddit.com/r/vcmi/<br />
** Administrator access: SXX<br />
* ModDB entry: http://www.moddb.com/engines/vcmi<br />
** Administrator access: SXX<br />
<br />
=== Communication channels ===<br />
* Slack team: https://h3vcmi.slack.com/<br />
** Owner: vmarkovtsev<br />
** Administrator access: SXX, Warmonger, AVS...<br />
* Trello team: https://trello.com/vcmi/<br />
** Administrator access: SXX<br />
* Unofficial discord:<br />
** Owner: dydzio<br />
** Administrator access: SXX<br />
* Unofficial IRC channel: irc.freenode.net #vcmi<br />
<br />
=== Other services ===<br />
* Launchpad PPA: https://launchpad.net/~vcmi<br />
** Member access: SXX<br />
** Administrator access: Ivan<br />
* Coverity Scan page: https://scan.coverity.com/projects/vcmi<br />
** Administrator access: SXX, Warmonger, AVS<br />
* OpenHub page: https://www.openhub.net/p/VCMI<br />
** Administrator access: Tow<br />
* Docker Hub organization: https://hub.docker.com/u/vcmi/<br />
** Administrator access: SXX<br />
<br />
Reserve accounts for other code hosting services:<br />
* GitLab organization: https://gitlab.com/vcmi/<br />
** Administrator access: SXX<br />
* BitBucket organization: https://bitbucket.org/vcmi/<br />
** Administrator access: SXX<br />
<br />
== What's to improve ==<br />
# Encourage Tow to transfer VCMI.eu to GANDI so it's can be also renewed without access.<br />
# Use 2FA on CloudFlare and just ask everyone to get FreeOTP and then use shared secret.<br />
# Centralized way to post news about game updates to all social media.</div>SXXhttps://wiki.vcmi.eu/index.php?title=How_to_build_VCMI_(Windows/Vcpkg)&diff=2674How to build VCMI (Windows/Vcpkg)2017-09-05T08:51:33Z<p>SXX: /* Create VCMI installer */</p>
<hr />
<div>= Prerequisites =<br />
* Windows Vista or newer.<br />
* Microsoft Visual Studio [https://www.visualstudio.com/vs/older-downloads/ 2015] or [http://www.visualstudio.com/downloads/download-visual-studio-vs 2017]<br />
* Git or git GUI, for example, SourceTree [http://www.sourcetreeapp.com/download download]<br />
* CMake [https://cmake.org/download/ download]<br />
* To unpack pre-build Vcpkg: [http://www.7-zip.org/download.html 7-zip]<br />
* To create installer: [http://nsis.sourceforge.net/Main_Page NSIS]<br />
<br />
= Choose directory =<br />
<br />
Create a directory for VCMI development, eg. '''C:\VCMI'''<br />
We will call this directory as '''[VCMI_DIR]'''<br />
<br />
'''Warning!''' Replace '''[VCMI_DIR]''' with path you chosen in following commands of this instruction.<br />
<br />
== How to choose good directory ==<br />
<br />
It is recommended to avoid non-ascii characters in the path to your working folders. The folder should not be write-protected by system. <br />
Good location:<br />
* '''C:\VCMI'''<br />
Bad locations:<br />
* '''C:\Users\Michał\VCMI''' (non-ascii character)<br />
* '''C:\Program Files (x86)\VCMI''' (write protection)<br />
<br />
= Install dependencies =<br />
<br />
You have two options: to use pre-built libraries or build your own. We strongly recommend start with using pre-built ones.<br />
<br />
== Option A. Use pre-built Vcpkg ==<br />
So you decide to start using Vcpkg packages pre-built by VCMI team.<br />
<br />
Package guaranteed to work since they tested with every commit by [https://ci.appveyor.com/project/vcmi/vcmi AppVeyor]<br />
<br />
=== Download and unpack archive ===<br />
<br />
Archives are available from GitHub: https://github.com/vcmi/vcmi-deps-windows/releases<br />
<br />
Only download latest version available.<br />
<br />
* vcpkg-export-'''x86'''-windows-v140.7z to build for 32-bit<br />
* vcpkg-export-'''x64'''-windows-v140.7z to build for 64-bit<br />
<br />
Extract archive by right clicking on it and choosing "7-zip -> Extract Here".<br />
<br />
=== Move dependencies to target directory ===<br />
<br />
Once extracted "vcpkg" directory will appear with "installed" and "scripts" inside it.<br />
<br />
Move extracted "vcpkg" directory into your '''[VCMI_DIR]'''.<br />
<br />
== Option B. Build Vcpkg on your own ==<br />
Be aware that building Vcpkg might take a lot of time depend on your CPU model and 10-20GB of disk space.<br />
=== Create initial directory ===<br />
<br />
=== Clone vcpkg ===<br />
<br />
# open SourceTree<br />
# File -> Clone<br />
# select '''https://github.com/microsoft/vcpkg/''' as source<br />
# select '''[VCMI_DIR]/vcpkg''' as destination<br />
# click '''Clone'''<br />
<br />
From command line use:<br />
<pre><br />
git clone https://github.com/microsoft/vcpkg.git [VCMI_DIR]/vcpkg<br />
</pre><br />
<br />
=== Build vcpkg ===<br />
* Run <br />
<pre><br />
[VCMI_DIR]/vcpkg/bootstrap-vcpkg.bat<br />
</pre><br />
<br />
=== Build dependencies ===<br />
* For 32-bit build run:<br />
<pre><br />
[VCMI_DIR]/vcpkg/vcpkg.exe install minizip:x86-windows sdl2:x86-windows sdl2-image:x86-windows sdl2-ttf:x86-windows sdl2-mixer:x86-windows boost:x86-windows qt5:x86-windows ffmpeg:x86-windows fuzzylite:x86-windows<br />
</pre><br />
* For 64-bit build run<br />
<pre><br />
[VCMI_DIR]/vcpkg/vcpkg.exe install minizip:x64-windows sdl2:x64-windows sdl2-image:x64-windows sdl2-ttf:x64-windows sdl2-mixer:x64-windows boost:x64-windows qt5:x64-windows ffmpeg:x64-windows fuzzylite:x64-windows<br />
</pre><br />
<br />
= Build VCMI =<br />
<br />
== Clone VCMI ==<br />
# open SourceTree<br />
# File -> Clone<br />
# select '''https://github.com/vcmi/vcmi/''' as source<br />
# select '''[VCMI_DIR]/source''' as destination<br />
# click '''Clone'''<br />
<br />
From command line use:<br />
<pre><br />
git clone --recursive https://github.com/vcmi/vcmi.git [VCMI_DIR]/source<br />
</pre><br />
<br />
== Generate solution for VCMI ==<br />
# create '''[VCMI_DIR]/build''' folder<br />
# open '''[VCMI_DIR]/build''' in command line:<br />
## Run Command Prompt or Power Shell.<br />
## Execute: cd [VCMI_DIR]/build<br />
# execute one of following commands to generate project<br />
<br />
'''Visual Studio 2015 - 32-bit build'''<br />
<pre><br />
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 14 2015"<br />
</pre><br />
<br />
'''Visual Studio 2015 - 64-bit build'''<br />
<pre><br />
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 14 2015 Win64"<br />
</pre><br />
<br />
'''Visual Studio 2017 - 32-bit build'''<br />
<pre><br />
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 15 2017"<br />
</pre><br />
<br />
'''Visual Studio 2017 - 64-bit build'''<br />
<pre><br />
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 15 2017 Win64"<br />
</pre><br />
<br />
== Compile VCMI with Visual Studio ==<br />
# open '''[VCMI_DIR]/build/VCMI.sln''' in Visual Studio<br />
# select "Release" build type in combobox<br />
# right click on '''BUILD_ALL''' project - build project<br />
# grab VCMI in '''[VCMI_DIR]/build/bin''' folder!<br />
<br />
== Compile VCMI from command line ==<br />
<br />
'''For release build'''<br />
<pre><br />
cmake --build [VCMI_DIR]/build --config Release<br />
</pre><br />
<br />
'''For debug build'''<br />
<pre><br />
cmake --build [VCMI_DIR]/build --config Debug<br />
</pre><br />
Debug will be used by default even "--config" if not specified.<br />
<br />
= Create VCMI installer =<br />
Make sure NSIS is installed to default directory or have registry entry so CMake can find it.<br />
<br />
After you build VCMI execute following commands from '''[VCMI_DIR]/build'''.<br />
=== Execute following if you built for Release: ===<br />
<pre><br />
cpack<br />
</pre><br />
=== If you built for Debug: ===<br />
<pre><br />
cpack -C Debug<br />
</pre></div>SXXhttps://wiki.vcmi.eu/index.php?title=How_to_build_VCMI_(Windows/Vcpkg)&diff=2673How to build VCMI (Windows/Vcpkg)2017-09-05T08:49:45Z<p>SXX: </p>
<hr />
<div>= Prerequisites =<br />
* Windows Vista or newer.<br />
* Microsoft Visual Studio [https://www.visualstudio.com/vs/older-downloads/ 2015] or [http://www.visualstudio.com/downloads/download-visual-studio-vs 2017]<br />
* Git or git GUI, for example, SourceTree [http://www.sourcetreeapp.com/download download]<br />
* CMake [https://cmake.org/download/ download]<br />
* To unpack pre-build Vcpkg: [http://www.7-zip.org/download.html 7-zip]<br />
* To create installer: [http://nsis.sourceforge.net/Main_Page NSIS]<br />
<br />
= Choose directory =<br />
<br />
Create a directory for VCMI development, eg. '''C:\VCMI'''<br />
We will call this directory as '''[VCMI_DIR]'''<br />
<br />
'''Warning!''' Replace '''[VCMI_DIR]''' with path you chosen in following commands of this instruction.<br />
<br />
== How to choose good directory ==<br />
<br />
It is recommended to avoid non-ascii characters in the path to your working folders. The folder should not be write-protected by system. <br />
Good location:<br />
* '''C:\VCMI'''<br />
Bad locations:<br />
* '''C:\Users\Michał\VCMI''' (non-ascii character)<br />
* '''C:\Program Files (x86)\VCMI''' (write protection)<br />
<br />
= Install dependencies =<br />
<br />
You have two options: to use pre-built libraries or build your own. We strongly recommend start with using pre-built ones.<br />
<br />
== Option A. Use pre-built Vcpkg ==<br />
So you decide to start using Vcpkg packages pre-built by VCMI team.<br />
<br />
Package guaranteed to work since they tested with every commit by [https://ci.appveyor.com/project/vcmi/vcmi AppVeyor]<br />
<br />
=== Download and unpack archive ===<br />
<br />
Archives are available from GitHub: https://github.com/vcmi/vcmi-deps-windows/releases<br />
<br />
Only download latest version available.<br />
<br />
* vcpkg-export-'''x86'''-windows-v140.7z to build for 32-bit<br />
* vcpkg-export-'''x64'''-windows-v140.7z to build for 64-bit<br />
<br />
Extract archive by right clicking on it and choosing "7-zip -> Extract Here".<br />
<br />
=== Move dependencies to target directory ===<br />
<br />
Once extracted "vcpkg" directory will appear with "installed" and "scripts" inside it.<br />
<br />
Move extracted "vcpkg" directory into your '''[VCMI_DIR]'''.<br />
<br />
== Option B. Build Vcpkg on your own ==<br />
Be aware that building Vcpkg might take a lot of time depend on your CPU model and 10-20GB of disk space.<br />
=== Create initial directory ===<br />
<br />
=== Clone vcpkg ===<br />
<br />
# open SourceTree<br />
# File -> Clone<br />
# select '''https://github.com/microsoft/vcpkg/''' as source<br />
# select '''[VCMI_DIR]/vcpkg''' as destination<br />
# click '''Clone'''<br />
<br />
From command line use:<br />
<pre><br />
git clone https://github.com/microsoft/vcpkg.git [VCMI_DIR]/vcpkg<br />
</pre><br />
<br />
=== Build vcpkg ===<br />
* Run <br />
<pre><br />
[VCMI_DIR]/vcpkg/bootstrap-vcpkg.bat<br />
</pre><br />
<br />
=== Build dependencies ===<br />
* For 32-bit build run:<br />
<pre><br />
[VCMI_DIR]/vcpkg/vcpkg.exe install minizip:x86-windows sdl2:x86-windows sdl2-image:x86-windows sdl2-ttf:x86-windows sdl2-mixer:x86-windows boost:x86-windows qt5:x86-windows ffmpeg:x86-windows fuzzylite:x86-windows<br />
</pre><br />
* For 64-bit build run<br />
<pre><br />
[VCMI_DIR]/vcpkg/vcpkg.exe install minizip:x64-windows sdl2:x64-windows sdl2-image:x64-windows sdl2-ttf:x64-windows sdl2-mixer:x64-windows boost:x64-windows qt5:x64-windows ffmpeg:x64-windows fuzzylite:x64-windows<br />
</pre><br />
<br />
= Build VCMI =<br />
<br />
== Clone VCMI ==<br />
# open SourceTree<br />
# File -> Clone<br />
# select '''https://github.com/vcmi/vcmi/''' as source<br />
# select '''[VCMI_DIR]/source''' as destination<br />
# click '''Clone'''<br />
<br />
From command line use:<br />
<pre><br />
git clone --recursive https://github.com/vcmi/vcmi.git [VCMI_DIR]/source<br />
</pre><br />
<br />
== Generate solution for VCMI ==<br />
# create '''[VCMI_DIR]/build''' folder<br />
# open '''[VCMI_DIR]/build''' in command line:<br />
## Run Command Prompt or Power Shell.<br />
## Execute: cd [VCMI_DIR]/build<br />
# execute one of following commands to generate project<br />
<br />
'''Visual Studio 2015 - 32-bit build'''<br />
<pre><br />
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 14 2015"<br />
</pre><br />
<br />
'''Visual Studio 2015 - 64-bit build'''<br />
<pre><br />
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 14 2015 Win64"<br />
</pre><br />
<br />
'''Visual Studio 2017 - 32-bit build'''<br />
<pre><br />
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 15 2017"<br />
</pre><br />
<br />
'''Visual Studio 2017 - 64-bit build'''<br />
<pre><br />
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 15 2017 Win64"<br />
</pre><br />
<br />
== Compile VCMI with Visual Studio ==<br />
# open '''[VCMI_DIR]/build/VCMI.sln''' in Visual Studio<br />
# select "Release" build type in combobox<br />
# right click on '''BUILD_ALL''' project - build project<br />
# grab VCMI in '''[VCMI_DIR]/build/bin''' folder!<br />
<br />
== Compile VCMI from command line ==<br />
<br />
'''For release build'''<br />
<pre><br />
cmake --build [VCMI_DIR]/build --config Release<br />
</pre><br />
<br />
'''For debug build'''<br />
<pre><br />
cmake --build [VCMI_DIR]/build --config Debug<br />
</pre><br />
Debug will be used by default even "--config" if not specified.<br />
<br />
= Create VCMI installer =<br />
Make sure NSIS is installed to default directory or have registry entry so CMake can find it.<br />
<br />
After you build VCMI execute following commands from '''[VCMI_DIR]/build'''.<br />
=== Execute following if you build for Release: ===<br />
<pre><br />
cpack<br />
</pre><br />
=== If you want debug build: ===<br />
<pre><br />
cpack -C Debug<br />
</pre></div>SXXhttps://wiki.vcmi.eu/index.php?title=How_to_build_VCMI_(Windows/Vcpkg)&diff=2672How to build VCMI (Windows/Vcpkg)2017-09-05T08:37:16Z<p>SXX: /* Generate solution for VCMI */</p>
<hr />
<div>= Prerequisites =<br />
* Windows Vista or newer.<br />
* Microsoft Visual Studio [https://www.visualstudio.com/vs/older-downloads/ 2015] or [http://www.visualstudio.com/downloads/download-visual-studio-vs 2017]<br />
* Git or git GUI, for example, SourceTree [http://www.sourcetreeapp.com/download download]<br />
* CMake [https://cmake.org/download/ download]<br />
* To unpack pre-build Vcpkg: [http://www.7-zip.org/download.html 7-zip]<br />
* To create installer: [http://nsis.sourceforge.net/Main_Page NSIS]<br />
<br />
= Choose directory =<br />
<br />
Create a directory for VCMI development, eg. '''C:\VCMI'''<br />
We will call this directory as '''[VCMI_DIR]'''<br />
<br />
'''Warning!''' Replace '''[VCMI_DIR]''' with path you chosen in following commands of this instruction.<br />
<br />
== How to choose good directory ==<br />
<br />
It is recommended to avoid non-ascii characters in the path to your working folders. The folder should not be write-protected by system. <br />
Good location:<br />
* '''C:\VCMI'''<br />
Bad locations:<br />
* '''C:\Users\Michał\VCMI''' (non-ascii character)<br />
* '''C:\Program Files (x86)\VCMI''' (write protection)<br />
<br />
= Install dependencies =<br />
<br />
You have two options: to use pre-built libraries or build your own. We strongly recommend start with using pre-built ones.<br />
<br />
== Option A. Use pre-built Vcpkg ==<br />
So you decide to start using Vcpkg packages pre-built by VCMI team.<br />
<br />
Package guaranteed to work since they tested with every commit by [https://ci.appveyor.com/project/vcmi/vcmi AppVeyor]<br />
<br />
=== Download and unpack archive ===<br />
<br />
Archives are available from GitHub: https://github.com/vcmi/vcmi-deps-windows/releases<br />
<br />
Only download latest version available.<br />
<br />
* vcpkg-export-'''x86'''-windows-v140.7z to build for 32-bit<br />
* vcpkg-export-'''x64'''-windows-v140.7z to build for 64-bit<br />
<br />
Extract archive by right clicking on it and choosing "7-zip -> Extract Here".<br />
<br />
=== Move dependencies to target directory ===<br />
<br />
Once extracted "vcpkg" directory will appear with "installed" and "scripts" inside it.<br />
<br />
Move extracted "vcpkg" directory into your '''[VCMI_DIR]'''.<br />
<br />
== Option B. Build Vcpkg on your own ==<br />
Be aware that building Vcpkg might take a lot of time depend on your CPU model and 10-20GB of disk space.<br />
=== Create initial directory ===<br />
<br />
=== Clone vcpkg ===<br />
<br />
* open SourceTree<br />
* File -> Clone<br />
* select '''https://github.com/microsoft/vcpkg/''' as source<br />
* select '''[VCMI_DIR]/vcpkg''' as destination<br />
* click '''Clone'''<br />
<br />
From command line use:<br />
<pre><br />
git clone https://github.com/microsoft/vcpkg.git [VCMI_DIR]/vcpkg<br />
</pre><br />
<br />
=== Build vcpkg ===<br />
* Run <br />
<pre><br />
[VCMI_DIR]/vcpkg/bootstrap-vcpkg.bat<br />
</pre><br />
<br />
=== Build dependencies ===<br />
* For 32-bit build run:<br />
<pre><br />
[VCMI_DIR]/vcpkg/vcpkg.exe install minizip:x86-windows sdl2:x86-windows sdl2-image:x86-windows sdl2-ttf:x86-windows sdl2-mixer:x86-windows boost:x86-windows qt5:x86-windows ffmpeg:x86-windows fuzzylite:x86-windows<br />
</pre><br />
* For 64-bit build run<br />
<pre><br />
[VCMI_DIR]/vcpkg/vcpkg.exe install minizip:x64-windows sdl2:x64-windows sdl2-image:x64-windows sdl2-ttf:x64-windows sdl2-mixer:x64-windows boost:x64-windows qt5:x64-windows ffmpeg:x64-windows fuzzylite:x64-windows<br />
</pre><br />
<br />
= Build VCMI =<br />
<br />
== Clone VCMI ==<br />
* open SourceTree<br />
* File -> Clone<br />
* select '''https://github.com/vcmi/vcmi/''' as source<br />
* select '''[VCMI_DIR]/source''' as destination<br />
* click '''Clone'''<br />
<br />
From command line use:<br />
<pre><br />
git clone --recursive https://github.com/vcmi/vcmi.git [VCMI_DIR]/source<br />
</pre><br />
<br />
== Generate solution for VCMI ==<br />
* create '''[VCMI_DIR]/build'''<br />
* open '''[VCMI_DIR]/build''' in terminal<br />
* execute command to generate project for:<br />
<br />
'''Visual Studio 2015 - 32-bit build'''<br />
<pre><br />
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 14 2015"<br />
</pre><br />
<br />
'''Visual Studio 2015 - 64-bit build'''<br />
<pre><br />
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 14 2015 Win64"<br />
</pre><br />
<br />
'''Visual Studio 2017 - 32-bit build'''<br />
<pre><br />
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 15 2017"<br />
</pre><br />
<br />
'''Visual Studio 2017 - 64-bit build'''<br />
<pre><br />
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 15 2017 Win64"<br />
</pre><br />
<br />
== Compile VCMI with Visual Studio ==<br />
* open '''[VCMI_DIR]/build/VCMI.sln''' in Visual Studio<br />
* select "Release" build type in combobox<br />
* right click on '''BUILD_ALL''' project - build project<br />
* grab VCMI in '''[VCMI_DIR]/build/bin''' folder!<br />
<br />
== Compile VCMI from command line ==<br />
From '''[VCMI_DIR]/build''' execute followding commands.<br />
<br />
'''For release build'''<br />
<pre><br />
cmake --build . --config Release<br />
</pre><br />
<br />
'''For debug build'''<br />
<pre><br />
cmake --build . --config Debug<br />
</pre><br />
Debug will be used by default even "--config" if not specified.<br />
<br />
= Create VCMI installer =<br />
Make sure NSIS is installed to default directory or have registry entry so CMake can find it.<br />
<br />
After you build VCMI execute following command from [VCMI_DIR]/build. <br />
=== Execute following if you build for Release: ===<br />
<pre><br />
cpack<br />
</pre><br />
=== If you want debug build: ===<br />
<pre><br />
cpack -C Debug<br />
</pre></div>SXXhttps://wiki.vcmi.eu/index.php?title=How_to_build_VCMI_(Windows/Vcpkg)&diff=2671How to build VCMI (Windows/Vcpkg)2017-09-05T08:36:23Z<p>SXX: /* Clone VCMI */</p>
<hr />
<div>= Prerequisites =<br />
* Windows Vista or newer.<br />
* Microsoft Visual Studio [https://www.visualstudio.com/vs/older-downloads/ 2015] or [http://www.visualstudio.com/downloads/download-visual-studio-vs 2017]<br />
* Git or git GUI, for example, SourceTree [http://www.sourcetreeapp.com/download download]<br />
* CMake [https://cmake.org/download/ download]<br />
* To unpack pre-build Vcpkg: [http://www.7-zip.org/download.html 7-zip]<br />
* To create installer: [http://nsis.sourceforge.net/Main_Page NSIS]<br />
<br />
= Choose directory =<br />
<br />
Create a directory for VCMI development, eg. '''C:\VCMI'''<br />
We will call this directory as '''[VCMI_DIR]'''<br />
<br />
'''Warning!''' Replace '''[VCMI_DIR]''' with path you chosen in following commands of this instruction.<br />
<br />
== How to choose good directory ==<br />
<br />
It is recommended to avoid non-ascii characters in the path to your working folders. The folder should not be write-protected by system. <br />
Good location:<br />
* '''C:\VCMI'''<br />
Bad locations:<br />
* '''C:\Users\Michał\VCMI''' (non-ascii character)<br />
* '''C:\Program Files (x86)\VCMI''' (write protection)<br />
<br />
= Install dependencies =<br />
<br />
You have two options: to use pre-built libraries or build your own. We strongly recommend start with using pre-built ones.<br />
<br />
== Option A. Use pre-built Vcpkg ==<br />
So you decide to start using Vcpkg packages pre-built by VCMI team.<br />
<br />
Package guaranteed to work since they tested with every commit by [https://ci.appveyor.com/project/vcmi/vcmi AppVeyor]<br />
<br />
=== Download and unpack archive ===<br />
<br />
Archives are available from GitHub: https://github.com/vcmi/vcmi-deps-windows/releases<br />
<br />
Only download latest version available.<br />
<br />
* vcpkg-export-'''x86'''-windows-v140.7z to build for 32-bit<br />
* vcpkg-export-'''x64'''-windows-v140.7z to build for 64-bit<br />
<br />
Extract archive by right clicking on it and choosing "7-zip -> Extract Here".<br />
<br />
=== Move dependencies to target directory ===<br />
<br />
Once extracted "vcpkg" directory will appear with "installed" and "scripts" inside it.<br />
<br />
Move extracted "vcpkg" directory into your '''[VCMI_DIR]'''.<br />
<br />
== Option B. Build Vcpkg on your own ==<br />
Be aware that building Vcpkg might take a lot of time depend on your CPU model and 10-20GB of disk space.<br />
=== Create initial directory ===<br />
<br />
=== Clone vcpkg ===<br />
<br />
* open SourceTree<br />
* File -> Clone<br />
* select '''https://github.com/microsoft/vcpkg/''' as source<br />
* select '''[VCMI_DIR]/vcpkg''' as destination<br />
* click '''Clone'''<br />
<br />
From command line use:<br />
<pre><br />
git clone https://github.com/microsoft/vcpkg.git [VCMI_DIR]/vcpkg<br />
</pre><br />
<br />
=== Build vcpkg ===<br />
* Run <br />
<pre><br />
[VCMI_DIR]/vcpkg/bootstrap-vcpkg.bat<br />
</pre><br />
<br />
=== Build dependencies ===<br />
* For 32-bit build run:<br />
<pre><br />
[VCMI_DIR]/vcpkg/vcpkg.exe install minizip:x86-windows sdl2:x86-windows sdl2-image:x86-windows sdl2-ttf:x86-windows sdl2-mixer:x86-windows boost:x86-windows qt5:x86-windows ffmpeg:x86-windows fuzzylite:x86-windows<br />
</pre><br />
* For 64-bit build run<br />
<pre><br />
[VCMI_DIR]/vcpkg/vcpkg.exe install minizip:x64-windows sdl2:x64-windows sdl2-image:x64-windows sdl2-ttf:x64-windows sdl2-mixer:x64-windows boost:x64-windows qt5:x64-windows ffmpeg:x64-windows fuzzylite:x64-windows<br />
</pre><br />
<br />
= Build VCMI =<br />
<br />
== Clone VCMI ==<br />
* open SourceTree<br />
* File -> Clone<br />
* select '''https://github.com/vcmi/vcmi/''' as source<br />
* select '''[VCMI_DIR]/source''' as destination<br />
* click '''Clone'''<br />
<br />
From command line use:<br />
<pre><br />
git clone --recursive https://github.com/vcmi/vcmi.git [VCMI_DIR]/source<br />
</pre><br />
<br />
== Generate solution for VCMI ==<br />
* create '''[VCMI_DIR]/build'''<br />
* open '''[VCMI_DIR]/build''' in terminal<br />
* execute command to generate project for:<br />
<br />
'''Visual Studio 2015 - 32-bit build'''<br />
<pre><br />
cmake ../source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 14 2015"<br />
</pre><br />
<br />
'''Visual Studio 2015 - 64-bit build'''<br />
<pre><br />
cmake ../source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 14 2015 Win64"<br />
</pre><br />
<br />
'''Visual Studio 2017 - 32-bit build'''<br />
<pre><br />
cmake ../source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 15 2017"<br />
</pre><br />
<br />
'''Visual Studio 2017 - 64-bit build'''<br />
<pre><br />
cmake ../source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 15 2017 Win64"<br />
</pre><br />
<br />
== Compile VCMI with Visual Studio ==<br />
* open '''[VCMI_DIR]/build/VCMI.sln''' in Visual Studio<br />
* select "Release" build type in combobox<br />
* right click on '''BUILD_ALL''' project - build project<br />
* grab VCMI in '''[VCMI_DIR]/build/bin''' folder!<br />
<br />
== Compile VCMI from command line ==<br />
From '''[VCMI_DIR]/build''' execute followding commands.<br />
<br />
'''For release build'''<br />
<pre><br />
cmake --build . --config Release<br />
</pre><br />
<br />
'''For debug build'''<br />
<pre><br />
cmake --build . --config Debug<br />
</pre><br />
Debug will be used by default even "--config" if not specified.<br />
<br />
= Create VCMI installer =<br />
Make sure NSIS is installed to default directory or have registry entry so CMake can find it.<br />
<br />
After you build VCMI execute following command from [VCMI_DIR]/build. <br />
=== Execute following if you build for Release: ===<br />
<pre><br />
cpack<br />
</pre><br />
=== If you want debug build: ===<br />
<pre><br />
cpack -C Debug<br />
</pre></div>SXX