games/vcmi
1
0
Fork 0
mirror of https://github.com/vcmi/vcmi.git synced 2025-01-12 02:28:11 +02:00
Code Issues Releases Activity

Added github wiki as it

Browse Source
This commit is contained in:
Ivan Savenko 2023-08-13 00:26:58 +03:00
parent 243094b1ea
commit 3e75209939
17 changed files with 1581 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
docs/wiki/Cheat-Codes.md Normal file
View File

@ -0,0 +1,46 @@
# VCMI cheat codes that can be used within in-game chat
> _Note: All cheat codes can be applied for:_
> -_current player_ - `no arguments`
> -_specific players_ - `red`/`blue`/`ai`
> -_all players_ - `all`
`vcmiistari` or `vcmispells` - give a spell book, all spells and 999 mana (to currently selected hero)
`vcminoldor` or `vcmimachines` - give ballista, ammo cart and first aid tent
`vcmiforgeofnoldorking` or `vcmiartifacts` - give all artifacts, except spell book, spell scrolls and war machines. Artifacts added via mods included
`vcmiarmy <creatureID>` or `vcminissi <creatureID>` - give 5000, 50k, 500k,... of the specified creature in every empty slot. EG: `vcmiarmy imp`
`vcmiainur` or `vcmiarchangel` - give 5 Archangels in every empty slot (to currently selected hero)
`vcmiangband` or `vcmiblackknight` - give 10 black knight in every empty slot
`vcmiglaurung` or `vcmicrystal` - give 5000 crystal dragons in every empty slot
`vcmiazure` - give 5000 azure dragons in every empty slot
`vcmifaerie` - give 5000 faerie dragons in every empty slot
`vcminahar` or `vcmimove` - give 1000000 movement points and free ship boarding for 1 day
`vcmiformenos` or `vcmiresources` - give resources (100000 gold, 100 of wood, ore and rare resources)
`vcmiarmenelos` or `vcmibuild` - build all buildings in currently selected town
`vcmieagles` or `vcmimap` - reveal Fog of War
`vcmiungoliant` or `vcmihidemap` - conceal Fog of War
`vcmiexp <quantity>` or `vcmiolorin <quantity>` - give specified experience. EG: `vcmiexp 10000`
`vcmiglorfindel` or `vcmilevel` - advance currently selected hero to the next level
`vcmisilmaril` or `vcmiwin` - player wins
`vcmimelkor` or `vcmilose` - player loses
# Cheat code usage examples, beyond current player
`vcmieagles blue` - reveal FoW only for blue player
`vcmieagles ai` - reveal FoW only for AI players
`vcmieagles all` - reveal FoW for all players on map
`vcminahar ai` - give 1000000 movement points to each hero of every AI player
> _Note: Some cheats can also be used with certain ObjectInstanceID_
`vcminahar 123` - give 1000000 movement points to hero with id of 123
`vcmiarmenelos 123` - build all buildings in town with id of 123
# Multiplayer chat commands
> _Note: These commands are not a cheats, and can be used in multiplayer by host player to control the session_
`game exit/quit/end` - finish the game
`game save <filename>` - save the game into the specified file
`game kick red/blue/tan/green/orange/purple/teal/pink` - kick player of specified color from the game
`game kick 0/1/2/3/4/5/6/7/8` - kick player of specified ID from the game (_zero indexed!_) (`0: red, 1: blue, tan: 2, green: 3, orange: 4, purple: 5, teal: 6, pink: 7`)

47
docs/wiki/Client-commands.md Normal file
View File

@ -0,0 +1,47 @@
Client commands are set of predefined commands that are supported by VCMI, but unlike cheats they perform utility actions that do not alter state of the gameplay. As of release 1.2 client commands can work by typing them in-game like cheats, preceded by symbol / (for example `/controlai blue`)
Alternative way, the only one working for older releases is typing them in console:
> Console is separated from game window on desktop versions of VCMI Client.
> Windows builds of VCMI run separate console window by default, on other platforms you can access it by running VCMI Client from command line.
Below a list of supported commands, with their arguments wrapped in `<>`
#### Game Commands
`die, fool` - quits game
`save <filename>` - saves game in given file (at the moment doesn't work)
`mp` - on adventure map with a hero selected, shows heroes current movement points, max movement points on land and on water
`bonuses` - shows bonuses of currently selected adventure map object
#### Extract commands
`convert txt` - save game texts into json files
`get config` - save game objects data into json files
`get scripts` - dumps lua script stuff into files (currently inactive due to scripting disabled for default builds)
`get txt` - save game texts into .txt files matching original heroes 3 files
`def2bmp <.def file name>` - extract .def animation as BMP files
`extract <relative file path>` - export file into directory used by other extraction commands
#### AI commands
`setBattleAI <ai name>` - change battle AI used by neutral creatures to the one specified, persists through game quit
`gosolo` - AI takes over until the end of turn (unlike original H3 currently causes AI to take over until typed again)
`controlai <[red][blue][tan][green][orange][purple][teal][pink]>` - gives you control over specified AI player. If none is specified gives you control over all AI players
`autoskip` - Toggles autoskip mode on and off. In this mode, player turns are automatically skipped and only AI moves. However, GUI is still present and allows to observe AI moves. After this option is activated, you need to end first turn manually. Press `[Shift]` before your turn starts to not skip it
#### Settings
`set <command> <on/off>` - sets special temporary settings that reset on game quit. Below some of the most notable commands:
-`autoskip` - identical to `autoskip` option
-`onlyAI` - run without human player, all players will be _default AI_
-`headless` - run without GUI, implies `onlyAI` is set
-`showGrid` - display a square grid overlay on top of adventure map
-`showBlocked` - show blocked tiles on map
-`showVisitable` - show visitable tiles on map
-`hideSystemMessages` - suppress server messages in chat
#### Developer Commands
`crash` - force a game crash. It is sometimes useful to generate memory dump file in certain situations, for example game freeze
`gui` - displays tree view of currently present VCMI common GUI elements
`activate <0/1/2>` - activate game windows (no current use, apparently broken long ago)
`redraw` - force full graphical redraw
`screen` - show value of screenBuf variable, which prints "screen" when adventure map has current focus, "screen2" otherwise, and dumps values of both screen surfaces to .bmp files
`unlock pim` - unlocks specific mutex known in VCMI code as "pim"
`not dialog` - set the state indicating if dialog box is active to "no"
`tell hs <hero ID> <artifact slot ID>` - write what artifact is present on artifact slot with specified ID for hero with specified ID. (must be called during gameplay)

147
docs/wiki/Conan.md Normal file
View File

@ -0,0 +1,147 @@
# Using dependencies from Conan
[Conan](https://conan.io/) is a package manager for C/C++. We provide prebuilt binary dependencies for some platforms that are used by our CI, but they can also be consumed by users to build VCMI. However, it's not required to use only the prebuilt binaries: you can build them from source as well.
## Supported platforms
The following platforms are supported and known to work, others might require changes to our [conanfile.py](../conanfile.py) or upstream recipes.
- **macOS**: x86_64 (Intel) - target 10.13 (High Sierra), arm64 (Apple Silicon) - target 11.0 (Big Sur)
- **iOS**: arm64 - target 12.0
## Getting started
1. [Install Conan](https://docs.conan.io/en/latest/installation.html)
2. Execute in terminal: `conan profile new default --detect`
## Download dependencies
0. If your platform is not on the list of supported ones or you don't want to use our prebuilt binaries, you can still build dependencies from source or try consuming prebuilt binaries from the central Conan repository - [ConanCenter](https://conan.io/center/). In this case skip to the [next section](#generate-cmake-integration) directly.
1. Check if your build environment can use the prebuilt binaries: basically, that your compiler version (or Xcode major version) matches the information below. If you're unsure, simply advance to the next step.
- macOS: libraries are built with Apple clang 13 (Xcode 13.4.1), should be consumable by Xcode and Xcode CLT 13.x
- iOS: libraries are built with Apple clang 13 (Xcode 13.4.1), should be consumable by Xcode 13.x
2. Download the binaries archive and unpack it to `~/.conan` directory:
- [macOS](https://github.com/vcmi/vcmi-deps-macos/releases/latest): pick **intel.txz** if you have Intel Mac, otherwise - **intel-cross-arm.txz**
- [iOS](https://github.com/vcmi/vcmi-ios-deps/releases/latest)
3. Only if you have Apple Silicon Mac and trying to build for macOS or iOS: follow [instructions how to build Qt host tools for Apple Silicon](https://github.com/vcmi/vcmi-ios-deps#note-for-arm-macs), on step 3 copy them to `~/.conan/data/qt/5.15.x/_/_/package/SOME_HASH/bin` (`5.15.x` and `SOME_HASH` are placeholders).
## Generate CMake integration
Conan needs to generate CMake toolchain file to make dependencies available to CMake. See `CMakeDeps` and `CMakeToolchain` [in the official documentation](https://docs.conan.io/en/latest/reference/conanfile/tools/cmake.html) for details.
In terminal `cd` to the VCMI source directory and run the following command. If you want to download prebuilt binaries from ConanCenter, also read the [next section](#using-prebuilt-binaries-from-conancenter).
<pre>
conan install . \
--install-folder=<b><i>conan-generated</i></b> \
--no-imports \
--build=<b><i>never</i></b> \
--profile:build=default \
--profile:host=<b><i>CI/conan/PROFILE</i></b>
</pre>
The highlighted parts can be adjusted:
- ***conan-generated***: directory (absolute or relative) where the generated files will appear. This value is used in CMake presets from VCMI, but you can actually use any directory and override it in your local CMake presets.
- ***never***: use this value to avoid building any dependency from source. You can also use `missing` to build recipes, that are not present in your local cache, from source.
- ***CI/conan/PROFILE***: if you want to consume our prebuilt binaries, ***PROFILE*** must be replaced with one of filenames from our [Conan profiles directory](../CI/conan) (determining the right file should be straight-forward). Otherwise, either select one of our profiles or replace ***CI/conan/PROFILE*** with `default` (your default profile).
If you use `--build=never` and this command fails, then it means that you can't use prebuilt binaries out of the box. For example, try using `--build=missing` instead.
VCMI "recipe" also has some options that you can specify. For example, if you don't care about game videos, you can disable FFmpeg dependency by passing `-o with_ffmpeg=False`. If you only want to make release build, you can use `GENERATE_ONLY_BUILT_CONFIG=1` environment variable to skip generating files for other configurations (our CI does this).
_Note_: you can find full reference of this command [in the official documentation](https://docs.conan.io/en/latest/reference/commands/consumer/install.html) or by executing `conan help install`.
### Using prebuilt binaries from ConanCenter
First, check if binaries for [your platform](https://github.com/conan-io/conan-center-index/blob/master/docs/supported_platforms_and_configurations.md) are produced.
You must adjust the above `conan install` command:
1. Replace ***CI/conan/PROFILE*** with `default`.
2. Additionally pass `-o default_options_of_requirements=True`: this disables all custom options of our `conanfile.py` to match ConanCenter builds.
## Configure project for building
You must pass the generated toolchain file to CMake invocation.
- if using custom CMake presets, just make sure to inherit our `build-with-conan` preset. If you store Conan generated files in a non-default directory, define the path to the generated toolchain in `toolchainFile` field (or `CMAKE_TOOLCHAIN_FILE` cache variable) or include CMake presets file generated by Conan.
- otherwise, if passing CMake options on the command line, use `--toolchain` option (available in CMake 3.21+) or `CMAKE_TOOLCHAIN_FILE` variable.
## Examples
In these examples only the minimum required amount of options is passed to `cmake` invocation, you can pass additional ones as needed.
### Use our prebuilt binaries to build for macOS x86_64 with Xcode
```
conan install . \
--install-folder=conan-generated \
--no-imports \
--build=never \
--profile:build=default \
--profile:host=CI/conan/macos-intel
cmake -S . -B build -G Xcode \
--toolchain conan-generated/conan_toolchain.cmake
```
### Try to use binaries from ConanCenter for your platform
If you also want to build the missing binaries from source, use `--build=missing` instead of `--build=never`.
```
conan install . \
--install-folder=~/my-dir \
--no-imports \
--build=never \
--profile:build=default \
--profile:host=default \
-o default_options_of_requirements=True
cmake -S . -B build \
-D CMAKE_TOOLCHAIN_FILE=~/my-dir/conan_toolchain.cmake
```
### Use our prebuilt binaries to build for iOS arm64 device with custom preset
```
conan install . \
--install-folder=~/my-dir \
--no-imports \
--build=never \
--profile:build=default \
--profile:host=CI/conan/ios-arm64
cmake --preset ios-conan
```
`CMakeUserPresets.json` file:
```json
{
"version": 3,
"cmakeMinimumRequired": {
"major": 3,
"minor": 21,
"patch": 0
},
"configurePresets": [
{
"name": "ios-conan",
"displayName": "iOS",
"inherits": ["build-with-conan", "ios-device"],
"toolchainFile": "~/my-dir/conan_toolchain.cmake",
"cacheVariables": {
"BUNDLE_IDENTIFIER_PREFIX": "com.YOUR-NAME",
"CMAKE_XCODE_ATTRIBUTE_DEVELOPMENT_TEAM": "YOUR_TEAM_ID"
}
}
]
}
```

72
docs/wiki/Get-started-with-building-VCMI-on-Windows.md Normal file
View File

@ -0,0 +1,72 @@
# Preparations
Windows builds can be made in more than one way and with more than one tool. This guide focuses on the simplest building process using Microsoft Visual Studio 2022
## Prerequisites
Windows Vista or newer.
Microsoft Visual Studio 2022 [download](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Community&channel=Release&version=VS2022&source=VSLandingPage&cid=2030&passive=false)
Git or git GUI, for example: SourceTree [download](https://www.sourcetreeapp.com/download), or GitKraken [download](https://www.gitkraken.com/download)
CMake [download](https://cmake.org/download/). During install after accepting license agreement make sure to check _"Add CMake to the system PATH for all users"_.
[7-zip](https://www.7-zip.org/download.html) For unpacking pre-build Vcpkg
## Choose an installation directory
Create a directory for VCMI development, eg. `C:\VCMI` We will call this directory `%VCMI_DIR%`
> Warning! Replace `%VCMI_DIR%` with path you've chosen for VCMI installation in the following commands.
> It is recommended to avoid non-ascii characters in the path to your working folders. The folder should not be write-protected by system.
Good locations:
`C:\VCMI`
Bad locations:
`C:\Users\Michał\VCMI (non-ascii character)`
`C:\Program Files (x86)\VCMI (write protection)`
## Install VCMI dependencies
We strongly recommend to use pre-built vcpkg.
### Download and unpack vcpkg archive
Vcpkg Archives are available at our GitHub: https://github.com/vcmi/vcmi-deps-windows/releases
* Download latest version available.
EG: v1.6 assets - [vcpkg-export-x64-windows-v143.7z](https://github.com/vcmi/vcmi-deps-windows/releases/download/v1.6/vcpkg-export-x64-windows-v143.7z)
* Extract archive by right clicking on it and choosing "7-zip -> Extract Here".
### Move dependencies to target directory
Once extracted, a `vcpkg` directory will appear with `installed` and `scripts` subfolders inside.
Move extracted `vcpkg` directory into your `%VCMI_DIR%`
# Build VCMI
## Clone VCMI
#### From GIT GUI
* Open SourceTree
* File -> Clone
* select `https://github.com/vcmi/vcmi/` as source
* select `%VCMI_DIR%/source` as destination
* expand Advanced Options and change Checkout Branch to `develop`
* tick `Recursive submodules`
* click Clone
#### From command line
* `git clone --recursive https://github.com/vcmi/vcmi.git %VCMI_DIR%/source`
## Generate solution for VCMI
* Create `%VCMI_DIR%/build` folder
* Open a command line prompt at `%VCMI_DIR%/build`
* Execute `cd %VCMI_DIR%/build`
* Create solution (Visual Studio 2022 64-bit) `cmake %VCMI_DIR%/source -DCMAKE_TOOLCHAIN_FILE=%VCMI_DIR%/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 17 2022" -A x64`
## Compile VCMI with Visual Studio
Open `%VCMI_DIR%/build/VCMI.sln` in Visual Studio
Select `Release` build type in combobox
Right click on `BUILD_ALL` project. This `BUILD_ALL` project should be in `CMakePredefinedTargets` tree in Solution Explorer.
VCMI will be built in `%VCMI_DIR%/build/bin` folder!
# Notes
## Build is successful but can not start new game
Make sure you have:
* Installed Heroes III from disk or using GOG installer
* Copied `Data`, `Maps` and `Mp3` folders from Heroes III to: `%USERPROFILE%\Documents\My Games\vcmi\`
## Debug build is very slow
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 means no optimizations at all. Debug information that available for release builds is often sufficient so just avoid full debug builds unless absolutely necessary. Instead use RelWithDebInfo configuration. Also Debug configuration might have some compilation issues because it is not checked via CI for now.
## Further notes:
For installing / uninstalling mods you need to launch `VCMI_launcher.exe`
For Map Editor you need to launch `VCMI_mapeditor.exe`

5
docs/wiki/Home.md Normal file
View File

@ -0,0 +1,5 @@
Welcome to the vcmi wiki!
Currently, we are still in process of setting up Github wiki.
For our more complete wiki go here: https://wiki.vcmi.eu/Main_Page

20
docs/wiki/How-to-safely-combine-Horn-of-the-Abyss-and-Tides-of-War-mod-for-VCMI‐1.3.md Normal file
View File

@ -0,0 +1,20 @@
Because Horn of the Abyss and Tides of War expansions change Conflux townscreen (and some other minor aspects) it is not trivial task to get all features at once without incompatibilities and visual bugs. This article describes what to enable and/or disable in laucher to play maps safely.
1. If you want to play only Horn of the Abyss mod without Tides of War (then you won't get alternate creatures in OH3 towns) - it'e easy task. You must disable Tides of War mod in the launcher.
![image](https://github.com/vcmi/vcmi/assets/29593042/1e4d9c1a-9588-42da-aeea-913db3d46b4b)
2. If you want to play only Tides of War mod without Horn of the Abyss (then you won't get Cove town and many other features) - you must disable Horn of the Abyss mod in the launcher **and** Hota balance compatibility patch must be **disabled!**
![image](https://github.com/vcmi/vcmi/assets/29593042/0ecb04ea-2f7f-4c25-a4c5-269af098ee49)
3. If you want to play Horn of the Abyss mod **and** Tides of War mod **without** HotA's balance changes (maybe you don't like it), correct launcher settings are:
![image](https://github.com/vcmi/vcmi/assets/29593042/01da1b8a-6547-4843-99b5-576017ea45f0)
4. Full HotA and ToW compatibility is provided by 'all green' line (except HotA and ToW main menu submods - they can be enabled/disabled anytime).
![image](https://github.com/vcmi/vcmi/assets/29593042/cec57cc9-5926-4c48-97f9-0ab17058dafd)
For more Q&A, please visit VCMI [discord](https://discord.com/invite/chBT42V) channel or [slack](https://slack.vcmi.eu/) channel.

31
docs/wiki/Map-editor-Working-with-mods.md Normal file
View File

@ -0,0 +1,31 @@
## Enabling and disabling mods
The mods mechanism used in map editor is the same as in game.
To enable or disable mods
* Start launcher, activate or deactivate mods you want
* Close launcher
* Run map editor
There is no button to start map editor directly from launcher, however you may use this approach to control active mods from any version of vcmi.
## Placing objects from mods
* All objects from mods will be automatically added into objects Browser. You can type mod name into filter field to find them.
<img width="269" alt="Снимок экрана 2022-09-13 в 21 14 46" src="https://user-images.githubusercontent.com/9308612/189965141-62ee0d2c-2c3e-483c-98fe-63517ed51912.png">
* Objects from mods related to new terrains (if mod adds any) should not be filtered this way, instead choose terrain from terrains filter on the top of objects browser
<img width="271" alt="Снимок экрана 2022-09-13 в 21 17 47" src="https://user-images.githubusercontent.com/9308612/189965836-de1fd196-2f6d-4996-a62a-e2fcb52b8d74.png">
## Playing maps with mods
If you place any kind of objects from the mods, obviously, you need those mods to be installed to play the map.
Also, you need to activate them.
You also may have other mods being activated in addition to what was used during map designing.
### Mod versions
In the future, the will be support of mods versioning so map will contain information about mods used and game can automatically search and activate required mods or let user know which are required. However, it's not implemented yet

181
docs/wiki/Map-editor-quick-guide.md Normal file
View File

@ -0,0 +1,181 @@
# Interface
<img width="738" alt="Снимок экрана 2022-09-07 в 06 31 12" src="https://user-images.githubusercontent.com/9308612/188775648-8551107d-9f0b-4743-8980-56c2c1c58bbc.png">
# Create the map
<img width="145" alt="Снимок экрана 2022-09-07 в 07 28 05" src="https://user-images.githubusercontent.com/9308612/188782248-b7895eb1-86a9-4f06-9309-43c6b3a3a728.png">
## New map
Create the new map by pressing **New** button from the toolbar
### Empty map
To create empty map, define its size by choosing option from drop-down list or enter required size manually in the text fields and press Ok button. Check **Two level map** option to create map with underground.
`Note: there are no limits on map size but be careful with sizes larger predefined XL size. It will be processed quite long to create even empty map. Also, it will be difficult to work with the huge maps because of possible performance issues`
Other parameters won't be used for empty map.
<img width="413" alt="Снимок экрана 2022-09-07 в 07 31 07" src="https://user-images.githubusercontent.com/9308612/188782588-c9f1a164-df1e-46bc-a6d3-24ff1e5396c2.png">
### Random map
To generate random map, check the **Random map** option and configure map parameters. You can select template from the drop-down list.
<img width="439" alt="Снимок экрана 2022-09-07 в 07 36 34" src="https://user-images.githubusercontent.com/9308612/188783256-7e498238-14a0-4377-8c09-d702d54ee7d9.png">
Templates are dynamically filtered depending on parameters you choose.
* [Default] template means that template will be randomly chosen
* If you see empty list it means that there are no templates fit your settings. It could be related to the settings chosen or it can mean that there are no templates install.
<img width="412" alt="Снимок экрана 2022-09-07 в 07 37 35" src="https://user-images.githubusercontent.com/9308612/188783360-1c042782-328d-4692-952f-58fa5110d0d0.png">
## Map load & save
To load the map, press open and select map file from the browser.
You can load both *.h3m and *.vmap formats but for saving *.vmap is allowed only.
# Views
There are 3 buttons switching views <img width="131" alt="Снимок экрана 2022-09-07 в 06 48 08" src="https://user-images.githubusercontent.com/9308612/188777527-b7106146-0d8c-4f14-b78d-f13512bc7bad.png">
### Ground/underground
**"U/G"** switches you between ground and underground
### Grid view
**Grid** show/hide grid
<img width="153" alt="Снимок экрана 2022-09-07 в 06 49 39" src="https://user-images.githubusercontent.com/9308612/188777723-934d693b-247d-42a6-815c-aecd0d34f653.png">
### Passability view
**Pass** show/hide passability map
<img width="190" alt="Снимок экрана 2022-09-07 в 06 51 46" src="https://user-images.githubusercontent.com/9308612/188778010-a1d45d59-7333-4432-b83f-57190fbe09f4.png">
# Setup terrain
1. Select brush you want
<img width="124" alt="Снимок экрана 2022-09-07 в 06 38 46" src="https://user-images.githubusercontent.com/9308612/188776299-fd688696-a98d-4f89-8bef-e81c90d3724b.png">
2. Select area you'd like to change
`Note: left mouse button selects tiles, right button removes selection`
![Снимок экрана 2022-09-07 в 06 39 53](https://user-images.githubusercontent.com/9308612/188776895-ce1607fb-694b-4edb-b0cc-263a0c5d04b8.png)
3. Press terrain you want
<img width="116" alt="Снимок экрана 2022-09-07 в 06 45 49" src="https://user-images.githubusercontent.com/9308612/188777176-1167561a-f23c-400a-a57b-be7fc90accae.png">
### Drawing roads and rivers
Actually, the process to draw rivers or roads is exactly the same as for terrains. You need to select tiles and then choose road/river type from the panel.
<img width="232" alt="Снимок экрана 2022-09-13 в 21 25 18" src="https://user-images.githubusercontent.com/9308612/189968965-7adbd76c-9ffc-46e5-aeb7-9a79214cc506.png">
To erase roads or rivers, you need to select tiles to be cleaned and press empty button.
<img width="130" alt="Снимок экрана 2022-09-13 в 21 26 54" src="https://user-images.githubusercontent.com/9308612/189969309-87ff7818-2915-4b38-b9db-ec4a616d18e7.png">
_Erasing works either for roads or for rivers, e.g. empty button from the roads tab erases roads only, but not rivers. You also can safely select bigger area, because it won't erase anything on tiles without roads/rivers accordingly_
## About brushes
* Buttons "1", "2", "4" - 1x1, 2x2, 4x4 brush sizes accordingly
* Button "[]" - non-additive rectangle selection
* Button "O" - lasso brush (not implemented yet)
* Button "E" - object erase, not a brush
## Fill obstacles
Map editor supports automatic obstacle placement.
Obstacle types are automatically selected for appropriate terrain types
To do that, select area (see Setup terrains) and press **Fill** button from the toolbar
<img width="222" alt="Снимок экрана 2022-09-07 в 06 56 05" src="https://user-images.githubusercontent.com/9308612/188778572-f80b3706-1713-40c7-a5aa-e4c3b9fc6649.png">
<img width="335" alt="Снимок экрана 2022-09-07 в 06 57 23" src="https://user-images.githubusercontent.com/9308612/188778694-507009a1-4bb0-4f37-afc7-4aa26a6f3eeb.png">
<img width="350" alt="Снимок экрана 2022-09-07 в 06 57 41" src="https://user-images.githubusercontent.com/9308612/188778728-f66adcbe-9cf2-41f2-8947-f60b38901317.png">
`Note: obstacle placer may occupy few neighbour tiles outside of selected area`
# Manipulating objects
## Adding new objects
1. Find the object you'd like to place in the object browser
<img width="188" alt="Снимок экрана 2022-09-07 в 07 00 59" src="https://user-images.githubusercontent.com/9308612/188779107-dc2ab212-9ed2-48ee-ba0d-7856b94a87b1.png">
2. You can also see selected object in preview area in the left part of application window
<img width="130" alt="Снимок экрана 2022-09-07 в 07 02 19" src="https://user-images.githubusercontent.com/9308612/188779263-a78577f7-8278-4927-a44e-18a7d85e2f64.png">
3. Hold mouse at object you want to place and move it to the map. You will see transparent object. Release object at point to confirm its creation
<img width="181" alt="Снимок экрана 2022-09-07 в 07 03 02" src="https://user-images.githubusercontent.com/9308612/188779350-653bad29-c54f-471b-93aa-90096da6d98c.png">
4. Press somewhere on the map to locate object.
**Right click over the scene - cancel object placement**
## Removing objects
1. **Make sure that no one terrain brush is selected.** To de-select brush click on selected brush again.
2. Select object you'd like to remove by simple clicking on it. You can also select multiple objects by moving mouse while left button is pressed
<img width="170" alt="Снимок экрана 2022-09-07 в 07 09 15" src="https://user-images.githubusercontent.com/9308612/188780096-6aefcad5-e092-44c6-8647-975e95f9a8a3.png">
3. Press **"E"** button from the brush panel or press **delete** on keyboard
## Changing object's properties
1. **Make sure that no one terrain brush is selected.** To de-select brush click on selected brush again.
2. Select object you'd like to remove by simple clicking on it. **You cannot review and modify properties for several objects, multiple selection is not supported.**
3. Go to the **inspector** tab. You will see object's properties
<img width="197" alt="Снимок экрана 2022-09-07 в 07 12 45" src="https://user-images.githubusercontent.com/9308612/188780504-40713019-3cdd-4077-9e2f-e3417c960efe.png">
4. You are able to modify properties which are not gray
`Note: sometimes there are empty editable fields`
### Assigning player to the object
Objects with flags can be assigned to the player. Find Owner property in the inspector for selected object, press twice to modify right cell. Type player number from **0 to 7 or type NEUTRAL** for neutral objects.
# Set up the map
You can modify general properties of the map
## Map name and description
1. Open **Map** menu on the top and select **General**
<img width="145" alt="Снимок экрана 2022-09-07 в 07 17 02" src="https://user-images.githubusercontent.com/9308612/188780943-70578b79-001b-45a2-bdfd-94577db40a6b.png">
2. You will see a new window with text fields to edit map name and description
3. Pressing **Ok** will save the changes, closing the window will discard the changes
<img width="307" alt="Снимок экрана 2022-09-07 в 07 18 02" src="https://user-images.githubusercontent.com/9308612/188781063-50ce65f8-aab4-43c3-a308-22acafa7d0a2.png">
## Player settings
Open **Map** menu on the top and select **Player settings"
<img width="141" alt="Снимок экрана 2022-09-07 в 07 20 40" src="https://user-images.githubusercontent.com/9308612/188781357-4a6091cf-f175-4649-a000-620f306d2c46.png">
You will see a window with player settings. Combobox players defines amount of players on the map. To review settings for particular player scroll the internal window. There are bunch on settings for each player you can change.
`Important: at least one player must be controlled as Human/CPU. Maps without human players won't be started in the game at most cases`
<img width="641" alt="Снимок экрана 2022-09-07 в 07 21 05" src="https://user-images.githubusercontent.com/9308612/188781400-7d5ba463-4f82-4dba-83ff-56210995e2c7.png">

19
docs/wiki/Map-editor.md Normal file
View File

@ -0,0 +1,19 @@
# Compatibility questions
## Platform compatibility
vcmieditor is a cross-platform application, so in general can support all platforms, supported by VCMI.
However, currently it doesn't support mobile platforms.
## Engine compatibility
vcmieditor is independent application so potentially it can be installed just in the folder with existing stable vcmi. However, on the initial stages of development compatibility was not preserved because major changes were needed to introduce into vcmi library. So it's recommended to download full package to use editor.
## Map compatibility
vcmieditor haven't introduced any change into map format yet, so all maps made by vcmieditor can be easily played with any version of vcmi. At the same time, those maps can be open and read in the old map editor and vice verse - maps from old editor can be imported in the new editor. So, full compatibility is ensured here.
## Mod compatibilty
vcmieditor loads set of mods using exactly same mechanism as game uses and mod manipulations can be done using vcmilaucnher application, just enable or disable mods you want and open editor to use content from those mods. In regards on compatibility, of course you need to play maps with same set of mods as you used in the editor. Good part is that is maps don't use content from the mods (even mods were enabled), it can be played on vcmi without mods as well

100
docs/wiki/Markets.md Normal file
View File

@ -0,0 +1,100 @@
# Market schema
Since VCMI-1.3 it's possible to create customizable markets on adventure map.
Markets can be added as any other object with special handler called "market".
Here is schema describing such object
```js
"seafaringAcademy" : //object name
{
"handler" : "market", //market handler
"name" : "Seafaring Academy",
... //describe any other regular parameters, such as sounds
"types" : {
"object" : { //object here is a type name
... //describe any other regular parameters, such as aiValue or rmg
"modes": ["resource-skill"], //modes available for market
"offer": ["navigation"], //optional parameter - specific items, must be presented on market
"title": "Seafaring Academy", //optional parameter - title for market window
"efficiency": 5, //market exchange rate, equivalent to amount of markets of certain type owning by player
"speech": "", //optional parameter - extra message showing on market
"templates" : {
... //describe templates in a common way
}
}
}
}
```
# Modes
Mode parameter defines a way to exchange different entities. Multiple modes can be specified to support several types of exchange.
Following options are supported:
* `"resource-resource"` - regular resource exchange, like trading post
* `"resource-player"` - allows to send resources to another player
* `"creature-resource"` - acts like freelance guild
* `"resource-artifact"` - black market
* `"artifact-resource"` - allows to sell artifacts for resources
* `"artifact-experience"` - acts like altar of sacrifice for good factions
* `"creature-experience"` - acts like altar of sacrifice for evil factions
* `"creature-undead"` - acts like skeleton transformer
* `"resource-skill"` - acts like university, where skills can be learned
## Examples
### Trading post
Trading post allows to exchange resources and send resources to another player, so it shall be configured this way:
```json
"modes" : ["resource-resource", "resource-player"]
```
### Black market
```json
"modes" : ["resource-artifact"]
```
### Freelance guild
```json
"modes" : ["creature-resource"]
```
### Altar of sacrifice
Altar of sacrifice allows exchange creatures for experience for evil factions and artifacts for experience for good factions.
So both modes shall be available in the market.
Game logic prohibits using modes unavailable for faction
```json
"modes" : ["creature-experience", "artifact-experience"]
```
# Offer
This field allows to configure specific items available in the market.
In VCMI-1.3 it can be used only for `resource-skill` mode
See [Secondary skills](https://github.com/vcmi/vcmi/wiki/Modding-~-Objects-~-Rewardable#secondary-skills) description for more details
### Example for University of magic (e.g conflux building)
```js
"modes" : ["resource-skill"],
"offer" : ["airMagic", "waterMagic", "earthMagic", "fireMagic"]
```
### Example for regular University
```js
"modes" : ["resource-skill"],
"offer" : [ //4 random skills except necromancy
{ "noneOf" : ["necromancy"] },
{ "noneOf" : ["necromancy"] },
{ "noneOf" : ["necromancy"] },
{ "noneOf" : ["necromancy"] }
]
```

470
docs/wiki/Modding-~-Objects-~-Rewardable.md Normal file
View File

@ -0,0 +1,470 @@
## Table of Contents
- [Base object definition](#base-object-definition)
- [Configurable object definition](#configurable-object-definition)
- [Base object definition](#base-object-definition)
- [Reset Parameters definition](#reset-parameters-definition)
- [Appear Chance definition](#appear-chance-definition)
- [Configurable Properties](#configurable-properties)
- - [Current Day](#current-day)
- - [Resource](#resource)
- - [Experience](#experience)
- - [Hero Level](#hero-level)
- - [Mana Points](#mana-points)
- - [Mana Percentage](#mana-percentage)
- - [Movement Points](#movement-points)
- - [Movement Percentage](#movement-percentage)
- - [Primary Skills](#primary-skills)
- - [Secondary Skills](#secondary-skills)
- - [Bonus System](#bonus-system)
- - [Artifacts](#artifacts)
- - [Spells](#spells)
- - [Creatures](#creatures)
- - [Creatures Change](#creatures-change)
- - [Spell cast](#spell-cast)
## Base object definition
Rewardable object is defined similarly to other objects, with key difference being `handler`. This field must be set to `"handler" : "configurable"` in order for vcmi to use this mode.
```js
{
"baseObjectName" : {
"name" : "Object name",
"handler" : "configurable",
"types" : {
"objectName" :
{
"rmg" : {
"value" : 2500,
"rarity" : 25,
"zoneLimit" : 1
},
// Standard definition of object templates
"templates" : {
"avwrhscr" : {
"animation" : "warehouses/avwrhscr",
"visitableFrom" : [ "---", "-++", "+++" ],
"mask" : ["VVV","VVV","VBA"]
}
}
// See Configurable object definition section
}
}
}
}
```
## Configurable object definition
```js
// List of potential rewards
"rewards" : [
{
// see Appear Chance definition section
"appearChance" : {
},
// Conditions to receive reward. Hero can only see this reward if he fulfills limiter
"limiter" : {
// additional list of conditions. Limiter will be valid if any of these conditions are true
"anyOf" : [
{
// See "Configurable Properties" section for additiona parameters
<additional properties>
}
]
// additional list of conditions. Limiter will be valid only if none of these conditions are true
"noneOf" : [
{
// See "Configurable Properties" section for additiona parameters
<additional properties>
}
]
// See "Configurable Properties" section for additiona parameters
<additional properties>
}
// message that will be shown if this is the only available award
"message": "{Warehouse of Crystal}"
// (VCMI 1.2) object will be disappeared after taking reward is set to true
"removeObject": false
// See "Configurable Properties" section for additiona parameters
<additional properties>
}
],
// (VCMI 1.2) If true, hero can not move to visitable tile of the object and will access this object from adjacent tile (e.g. Treasure Chest)
"blockedVisitable" : true,
// Message that will be shown if there are no applicable awards
"onEmptyMessage": "",
// Alternatively, rewards for empty state:
// Format is identical to "rewards" section, allowing to fine-tune behavior in this case, including giving awards or different messages to explain why object is "empty". For example, Tree of Knowledge will give different messages depending on whether it asks for gold or crystals
"onEmpty" : [
]
// Message that will be shown if there are multiple selectable awards to choose from
"onSelectMessage" : "",
// Message that will be shown if this object has been already visited before
"onVisitedMessage" : "{Warehouse of Crystal}\r\n\r\nThe owner of the storage is apologising: 'I am sorry Milord, no crystal here. Please, return next week!'",
// Alternatively, rewards for visited state:
// Format is identical to "rewards" section, allowing to fine-tune behavior of already visited object, including potentially giving bonuses to player, e.g. Warrior's Tomb give -3 morale for visiting such object.
"onVisited" : [
]
// if true, then player can refuse from reward and don't select anything
// Note that in this case object will not become "visited" and can still be revisited later
"canRefuse": true,
// object reset period. Note that period is counted from game start and not from hero visit
// reset duration of 7 will always reset object on new week & duration of 28 will reset on new month
// if field is not present or set to 0 object will never reset
// (VCMI 1.2) This property has been removed in favor of more detailed "resetParameters" property
"resetDuration" : 7,
// (VCMI 1.2) see Reset Parameters definition section
"resetParameters" : {
}
// determines who can revisit object before reset
// "once", - object can only be visited once. First visitor takes it all.
// "hero", - object can be visited if this hero has not visited it before
// "player", - object can be visited if this player has not visited it before
// "bonus" - object can be visited if hero no longer has bonus from this object (including any other object of the same type)
// "unlimited" - no restriction on revisiting.
"visitMode" : "unlimited",
//determines way to select granted rewards if multiple options are available
// "selectFirst", - first reward which passes "limiter" will be granted to player
// "selectPlayer", - player will be allowed to choose between rewards (e.g. treasure chest)
"selectMode" : "selectFirst", "selectPlayer"
}
```
## Reset Parameters definition
(VCMI 1.2 only)
This property describes how object state should be reset. Objects without this field will never reset its state.
- Period describes interval between object resets in day. Periods are counted from game start and not from hero visit, so reset duration of 7 will always reset object on new week & duration of 28 will always reset on new month.
- If `visitors` is set to true, game will reset list of visitors (heroes and players) on start of new period, allowing revisits of objects with `visitMode` set to `once`, `hero`, or `player`. Objects with visit mode set to `bonus` are not affected. In order to allow revisit such objects use appropriate bonus duration (e.g. `ONE_DAY` or `ONE_WEEK`) instead.
- If `rewards` is set to true, object will re-randomize its provided rewards, similar to such H3 objects as "Fountain of Fortune" or "Windmill"
```js
"resetParameters" : {
"period" : 7,
"visitors" : true,
"rewards" : true
}
```
## Appear Chance definition
This property describes chance for reward to be selected.
When object is initialized on map load, game will roll a "dice" - random number in range 0-99, and pick all awards that have appear chance within selected number
```js
"appearChance":
{
// (Advanced) rewards with different dice number will get different dice number
// This allows (for example) choosing two rewards randomly, independent from each other
// For H3 objects, this is generally not needed and this field can be omitted
"dice": 1,
// reward will be selected only if random roll value is greater or equal than this
"min" : 33,
// reward will be selected only if random roll value is lower than this
"max" : 66
},
```
## Configurable Properties
Unless stated othervice, all numbers in this section can be replaced with random values, e.g.
```js
"minLevel" : { "min" : 5, "max" : 10 } // select random number between 5-10, including both 5 & 10
"minLevel" : [ 2, 4, 6, 8, 10] // (VCMI 1.2) select random number out of provided list, with equal chance for each
```
In this case, actual value for minLevel will be picked randomly.
(VCMI 1.2) Keep in mind, that all randomization is performed on map load and on reset (only if `rewards` field in `resetParameter` was set).
### Current Day
- Can only be used as limiter. To pass, current day of week should be equal to this value. 1 = first day of the week, 7 = last day
```js
"dayOfWeek" : 0
```
- (VCMI 1.2) Can only be used as limiter. To pass, number of days since game started must be at equal or greater than this value
```js
"daysPassed" : 8
```
### Resource
- Can be used as limiter. To pass, player needs to have specified resources. Note that limiter will NOT take resources.
- Can be used as reward to grant resources to player
- If negative value is used as reward, it will be used as cost and take resources from player
```js
"resources": {
"crystal" : 6,
"gold" : -1000,
},
```
- (VCMI 1.2) Alternative format that allows random selection of a resource type
```js
"resources": [
{
"list" : [ "wood", "ore" ],
"amount" : 10
},
{
"type" : "gold",
"amount" : 1000
}
],
```
### Experience
- (VCMI 1.2) Can be used as limiter
- Can be used as reward to grant experience to hero
```js
"heroExperience" : 1000,
```
### Hero Level
- Can be used as limiter. Hero requires to have at least specified level
- (VCMI 1.2) Can be used as reward, will grant hero experience amount equal to the difference between the hero's next level and current level (Tree of Knowledge)
```js
"heroLevel" : 1,
```
### Mana Points
- (VCMI 1.2) Can be used as limiter. Hero must have at least specific mana amount
- Can be used as reward, to give mana points to hero. Mana points may go above mana pool limit.
- If negative value is used as reward, it will be used as cost and take mana from player
```js
"manaPoints": -10,
```
- (VCMI 1.2) if giving mana points puts hero above mana pool limit, any overflow will be multiplied by specified percentage. If set to 0, mana will not go above mana pool limit.
```js
"manaOverflowFactor" : 50,
```
### Mana Percentage
- (VCMI 1.2) Can be used as limiter. Hero must have at least specific mana percentage
- Can be used to set hero mana level to specified percentage value, not restricted to mana pool limit (Magic Well, Mana Spring)
```js
"manaPercentage": 200,
```
### Movement Points
- Can NOT be used as limiter
- Can be used as reward, to give movement points to hero. Movement points may go above mana pool limit.
```js
"movePoints": 200,
```
### Movement Percentage
- Can NOT be used as limiter
- Can be used to set hero movement points level to specified percentage value. Value of 0 will take away any remaining movement points
```js
"movePercentage": 50,
```
### Primary Skills
- Can be used as limiter, hero must have primary skill at least at specified level
- Can be used as reward, to increase hero primary skills by selected value
- If reward value is negative, value will be used as cost, decreasing primary skill
- (VCMI 1.3) Each primary skill can be explicitly specified or randomly selected
```js
"primary": [
{
// Specific primary skill
"type" : "defence",
"amount" : 1
},
{
// Primary skill will be selected randomly from the list
"anyOf" : ["attack", "defence],
"min" : 1,
"max" : 3
},
{
// Primary skill will be selected randomly, expect those
"noneOf" : ["knowledge"],
"amount" : 1
},
{
// Primary skill will be selected randomly
"amount" : 3
}
]
```
- Possible values: `"attack", "defence", "spellpower", "knowledge"`
- (VCMI 1.2) Deprecated format
```js
"primary": {
"attack" : 1,
"spellpower": -1
},
```
### Secondary Skills
- Can be used as limiter, hero must have secondary skill at least at specified level
- Can be used as reward, to grant secondary skills to hero
- If hero already has specified skill, the skills will be leveled up specified number of times
- If hero does not have selected skill and have free skill slots, he will receive skill at specified level
- Possible values: 1 (basic), 2 (advanced), 3 (expert)
- (VCMI 1.3) Each secondary skill can be explicitly specified or randomly selected
```js
"secondary": [
{
// Specific skill
"type" : "wisdom",
"amount" : 1
},
{
// Skill will be selected randomly from the list
"anyOf" : ["airMagic", "waterMagic", "earthMagic", "fireMagic"],
"min" : 1,
"max" : 3
},
{
// Skill will be selected randomly from all allowed, expect those
"noneOf" : ["necromancy", "leadership"],
"amount" : 1
},
{
// Skill will be selected randomly from all allowed
"amount" : 3
}
]
```
- (VCMI 1.2) deprecated format
```js
"secondary": {
"wisdom" : 1
},
```
### Bonus System
- (VCMI 1.2) Can be used as reward, to grant bonus to player
- (VCMI 1.2) if present, MORALE and LUCK bonus will add corresponding image component to UI.
- (VCMI 1.2) Note that unlike most values, parameter of bonuses can NOT be randomized
- (VCMI 1.X) Description can be string or number of corresponding string from `arraytxt.txt`
```js
"bonuses" : [
{
"type" : "MORALE",
"val" : 1,
"duration" : "ONE_BATTLE",
"desription" : 94
}
]
```
### Artifacts
- Can be used as limiter, hero must have artifact either equipped or in backpack
- Can be used as reward, to give new artifact to a hero
- (VCMI 1.2) Artifacts added as reward will be used for text substitution. First `%s` in text string will be replaced with name of an artifact
```js
"artifacts": [
"ribCage"
],
```
- Alternative format, random artifact generation.
- For artifact class possible values are "TREASURE", "MINOR", "MAJOR", "RELIC"
- Artifact value range can be specified with min value and max value
```js
"artifacts": [
{
"class" : "TREASURE",
"minValue" : 5000,
"maxValue" : 10000
}
],
```
### Spells
- (VCMI 1.2) Can be used as limiter
- Can be used as reward, to give new spell to a hero
- (VCMI 1.2) Spells added as reward will be used for text substitution. First `%s` in text string will be replaced with spell name
```js
"spells": [
"magicArrow"
],
```
- Alternative format, random spell selection
- (VCMI 1.X) Spell can be selected from specifically selected school
```js
"spells": [
{
"level" : 1,
"school" : "fire",
}
],
```
### Creatures
- Can be used as limiter
- Can be used as reward, to give new creatures to a hero
- If hero does not have enough free slots, game will show selection dialog to pick troops to keep
- It is possible to specify probabilty to receive upgraded creature
```js
"creatures" : [
{
"creature" : "archer",
"upgradeChance" : 30,
"amount" : 20,
}
],
```
### Creatures Change
- (VCMI 1.2) Can NOT be used as limiter
- (VCMI 1.2) Can be used as reward, to replace creatures in hero army. It is possible to use this parameter both for upgrades of creatures as well as for changing them into completely unrelated creature, e.g. similar to Skeleton Transformer
- (VCMI 1.2) This parameter will not change creatures given by `creatures` parameter on the same visit
```js
"changeCreatures" : {
"cavalier" : "champion"
}
```
### Spell cast
- (VCMI 1.3) Can NOT be used as limiter
- (VCMI 1.3) As reward, instantly casts adventure map spell for visiting hero. All checks for spell book, wisdom or presence of mana will be ignored. It's possible to specify school level at which spell will be casted. If it's necessary to reduce player's mana or do some checks, they shall be introduced as limiters and other rewards
- School level possible values: 1 (basic), 2 (advanced), 3 (expert)
```js
"spellCast" : {
"spell" : "townPortal",
"schoolLevel": 3
}
```

46
docs/wiki/Release-process.md Normal file
View File

@ -0,0 +1,46 @@
## Branches
Our branching strategy is very similar to GitFlow
* `master` branch has release commits. One commit - one release. Each release commit should be tagged with version `maj.min.patch`
* `beta` branch is for stabilization of ongoing release. We don't merge new features into `beta` branch - only bug fixes are acceptable. Hotfixes for already released software should be delivered to this branch as well.
* `develop` branch is a main branch for ongoing development. Pull requests with new features should be targeted to this branch, `develop` version is one step ahead of 'beta`
## Release process step-by-step
Assuming that all features planned to be released are implemented in `develop` branch and next release version will be `1.x.0`
### Start of stabilization stage
Should be done several weeks before planned release date
- Create [milestone](https://github.com/vcmi/vcmi/milestones) named `Release 1.x`
- - Specify this milestone for all regression bugs and major bugs related to new functionality
- Create `beta` branch from `develop`
- Bump vcmi version on `develop` branch
- Bump version for linux on `develop` branch
### Release preparation stage
Should be done several days before planned release date
- Update [release notes](https://github.com/vcmi/vcmi/blob/develop/ChangeLog.md)
- Update release date for Linux packaging. See [example](https://github.com/vcmi/vcmi/pull/1258)
- Update release date for Android packaging. See [example](https://github.com/vcmi/vcmi/pull/2090)
- Create draft release page, specify `1.x.0` as tag for `master` after publishing
- Prepare pull request with release update for web site https://github.com/vcmi/VCMI.eu
- Prepare pull request for [vcmi-updates](https://github.com/vcmi/vcmi-updates)
### Release publishing phase
Should be done on release date
- Check that all items from milestone `Release 1.x` completed
- Merge `beta` into `master`
- Check that artifacts for all platforms are available on `master` branch
- Trigger builds for new release on Ubuntu PPA
- Attach build artifacts for all platforms to release page
- - Android build should be prepared manually from custom branch (master)
- Merge prepared pull requests
- Publish release page
### After release publish
- Close `Release 1.x` milestone
- Write announcements in social networks
- Merge `master` into `develop`
- Update downloads counter in readme.md. See [example](https://github.com/vcmi/vcmi/pull/2091)

68
docs/wiki/Roadmap.md Normal file
View File

@ -0,0 +1,68 @@
## Game engine features
### [Support remaining H3 features](https://github.com/vcmi/vcmi/labels/h3feature)
- **Description**: Original goal of vcmi project, as of right now almost all H3 features are supported. However, most of remaining features often require somewhat extensive changes.
- **Current estimation**: vcmi-1.2 (Battles), unknown(Full support)
- **Priority**: medium
- **Current assignee**: [IvanSavenko](https://github.com/IvanSavenko)
### [SDL abstraction layer & hardware acceleration](https://github.com/vcmi/vcmi/issues/1263)
- **Description**: While hardware acceleration is not critically important for vcmi, most of preceding steps are necessary for general code improvement.
- **Current estimation**: vcmi-1.3 (Testing), unknown (Full support)
- **Priority**: medium
- **Current assignee**: [IvanSavenko](https://github.com/IvanSavenko)
## Mobile Platforms
### [Adopt interface to touchscreen devices](https://github.com/vcmi/vcmi/labels/touchscreen)
- TODO: who among devs is interested in this? When do we expect any progress on this?
### Closer and frequent integration with distributing platforms (google store, altstore, ideally appstore)
- TODO: what exactly is "Closer and frequent integration"? What blocks us from doing this?
- TODO: Who among devs is interested in this? When do we expect any progress on this?
### Port VCMI launcher to Android
- TODO: What is current state with Android Launcher? What blocks us from doing this?
- TODO: Who among devs is interested in this? When do we expect any progress on this?
## Hota/HDMod features
- [Better online mode](https://github.com/vcmi/vcmi/issues/1361)
- [Quick battle](https://github.com/vcmi/vcmi/pull/1108)
- Simultaneous turns
- [Support Hota map format](https://github.com/vcmi/vcmi/issues/1259)
## Modding System
### Flexibility for configurable objects
- TODO: describe what else needs to be exposed to modding system
### [Sod as mod](https://github.com/vcmi/vcmi/milestone/3)
- Details and solution description are [here](https://github.com/vcmi/vcmi/issues/1158)
### [Map editor](https://github.com/vcmi/vcmi/labels/editor)
- [List of tasks](https://github.com/Nordsoft91/vcmi/issues) to be done in originator's fork
### Implement other modding tools
- Resource viewer embedded into map editor
- Campaign editor
- RMG template editor
### Scripting
- Description: Fundaments for scripting support is made, the scripting features just need to be gradually implemented
- Potential assignee: None?
### Missing WoG features
- Descriptions: Implement some missing WoG features like reviving commanders for money
- Potential assignee: None?
## AI
- [Battle AI](https://github.com/vcmi/vcmi/labels/battleai)
- Tactics ability
- Utilize more spells
- Proper moment for retreat/surrender
- Use some battle tricks (surround shooters, etc)
- [Adventure AI](https://github.com/vcmi/vcmi/labels/nullkillerai)
## Easy of development
- Automatic test system
- Run unit tests on GitHub actions - implement resources stub for it
- Automatic data installation
- Installation wizard from launcher which copies necessary resources automatically
- Better documentation for code and for modders
## Exclusive Content
- High quality mods at scale of add-ons, which should contain
- New content (factions, units, spells, terrains whatever),
- Unique scenarios, campaigns, story
- New game mechanics (random idea - add level above ground “sky” with “skyboat” transport)
## Community
- marketing and finding manpower - linux & open source enthusiast communities could be good start to find h3 fan devs

61
docs/wiki/Translations.md Normal file
View File

@ -0,0 +1,61 @@
## For translators
### Adding new languages
New languages require minor changes in the source code. Please contact someone from vcmi team if you wish to translate game into a new language
### Translation of Launcher and Map Editor
TODO: write me
### Translation of game content
TODO: write me
## For modders
### Adding new translation to mod
TODO: write me
### Translation of mod information
In order to display information in Launcher in language selected by user add following block into your mod.json:
```
"<language>" : {
"name" : "<translated name>",
"description" : "<translated description>",
"author" : "<translated author>",
"modType" : "<translated mod type>",
},
```
List of currently supported values for language parameter:
- english
- german
- polish
- russian
- ukrainian
However, normally you don't need to use block for English. Instead, English text should remain in root section of your mod.json file, to be used when game can not find translated version.
### Translation of mod content
TODO: write me
### Searching for missing translation strings
TODO: write me
## For developers
### Adding new languages
In order to add new language it needs to be added in multiple locations in source code:
- Generate new .ts files for launcher and map editor, either by running `lupdate` with name of new .ts or by copying english.ts and editing language tag in the header.
- Add new language into Launcher UI drop-down selector and name new string using such format:
`"<native name for language> (<english name for language>)"`
- Add new language into array of possible values for said selector
Also, make full search for a name of an existing language to ensure that there are not other places not referenced here
### Updating translation of Launcher and Map Editor to include new strings
At the moment, build system will generate binary translation files (.qs) that can be opened by Qt.
However, any new or changed lines will not be added into existing .ts files.
In order to update .ts files manually, open command line shell in `mapeditor` or `launcher` source directories and execute command
```
lupdate -no-obsolete * -ts translation/*.ts
```
This will remove any no longer existing lines from translation and add any new lines for all translations.
There *may* be a way to do the same via QtCreator UI or via CMake, if you find one feel free to update this information.
### Updating translation of Launcher and Map Editor using new .ts file from translators
Generally, this should be as simple as overwriting old files. Things that may be necessary if translation update is not visible in executable:
- Rebuild subproject (map editor/launcher).
- Regenerate translations via `lupdate -no-obsolete * -ts translation/*.ts`

41
docs/wiki/Ubuntu-PPA.md Normal file
View File

@ -0,0 +1,41 @@
## Main links
- [Team](https://launchpad.net/~vcmi)
- [Project](https://launchpad.net/vcmi)
- [Sources](https://code.launchpad.net/~vcmi/vcmi/+git/vcmi)
- [Recipes](https://code.launchpad.net/~vcmi/+recipes)
- - [Stable recipe](https://code.launchpad.net/~vcmi/+recipe/vcmi-stable)
- - [Daily recipe](https://code.launchpad.net/~vcmi/+recipe/vcmi-daily)
- PPA's
- - [Stable PPA](https://launchpad.net/~vcmi/+archive/ubuntu/ppa)
- - [Daily PPA](https://launchpad.net/~vcmi/+archive/ubuntu/vcmi-latest)
## Automatic daily builds process
### Code import
- Launchpad performs regular (once per few hours) clone of our git repository.
- This process can be observed on [Sources](https://code.launchpad.net/~vcmi/vcmi/+git/vcmi) page.
- If necessary, it is possible to trigger fresh clone immediately (Import Now button)
### Build dependencies
- All packages required for building of vcmi are defined in [debian/control](https://github.com/vcmi/vcmi/blob/develop/debian/control) file
- Launchpad will automatically install build dependencies during build
- Dependencies of output .deb package are defined implicitly as dependencies of packages required for build
### Recipe building
- Every 24 hours Launchpad triggers daily builds on all recipes that have build schedule enable. For vcmi this is [Daily recipe](https://code.launchpad.net/~vcmi/+recipe/vcmi-daily)
- Alternatively, builds can be triggered manually using "request build(s) link on recipe page. VCMI uses this for [Stable recipe](https://code.launchpad.net/~vcmi/+recipe/vcmi-stable)
### Recipe content (build settings)
- Version of resulting .deb package is set in recipe content, e.g `{debupstream}+git{revtime}` for daily builds
- Base version (referred as `debupstream` on Launchpad is taken from source code, [debian/changelog](https://github.com/vcmi/vcmi/blob/develop/debian/changelog) file
- CMake configuration settings are taken from source code, [debian/rules](https://github.com/vcmi/vcmi/blob/develop/debian/rules) file
- Branch which is used for build is specified in recipe content, e.g. `lp:vcmi master`
## Workflow for creating a release build
- if necessary, push all required changes including `debian/changelog` update to `vcmi/master` branch
- Go to [Sources](https://code.launchpad.net/~vcmi/vcmi/+git/vcmi) and run repository import.
- Wait for import to finish, which usually happens within a minute. Press F5 to actually see changes.
- Go to [Stable recipe](https://code.launchpad.net/~vcmi/+recipe/vcmi-stable) and request new builds
- Wait for builds to finish. This takes quite a while, usually - over a hour, even more for arm builds
- Once built, all successfully built packages are automatically copied to PPA linked to the recipe
- If any of builds have failed, open page with build info and check logs.
## People with access
- [alexvins](https://github.com/alexvins) (https://launchpad.net/~alexvins)
- [ArseniyShestakov](https://github.com/ArseniyShestakov) (https://launchpad.net/~sxx)
- [IvanSavenko](https://github.com/IvanSavenko) (https://launchpad.net/~saven-ivan)
- (Not member of VCMI, creator of PPA) (https://launchpad.net/~mantas)

14
docs/wiki/VCMI-App-Privacy-Policy.md Normal file
View File

@ -0,0 +1,14 @@
**Last Updated: 24th December, 2022**
### Glossary
* VCMI team - a community of VCMI developers, mod makers and testers. It is not some officially registered organization.
* VCMI app - an application provided by VCMI team.
### Single player
VCMI team does not collect any data produced by VCMI app. All game files, logs, saves, mods are stored in app's internal directory and will be removed upon app uninstallation. It should be possible so to backup this data by standard ways provided by your device.
### Multiplayer
If you decide to play with other users via Internet there are two roles. The host is the one who provides the game server. The clients are the other players who connect to the host. The host provides to the client its IP address in order to establish connections. The clients and the host during the gameplay exchange their usernames, messages and other game activity. All this data is collected and stored by the host. VCMI team does not collect and store any multiplayer data as well.

213
docs/wiki/VCMI-Campaign-format.md Normal file
View File

@ -0,0 +1,213 @@
# Introduction
Starting from version 1.3, VCMI supports its own campaign format.
Campaigns have *.vcmp file format and it consists from campaign json and set of scenarios (can be both *.vmap and *.h3m)
To start making campaign, create file named `00.json`. See also [Packing campaign](https://github.com/vcmi/vcmi/wiki/VCMI-Campaign-format/#packing-campaign)
Basic structure of this file is here, each section is described in details below
```js
{
"version" : 1,
<header properties>
"scenarios" : [
{
//scenario 1
<scenario properties>
},
{
//scenario 2
<scenario properties>
}
]
}
```
`"version"` defines version of campaign file. Larger versions should have more features and flexibility, but may not be supported by older VCMI engines. See [compatibility table](https://github.com/vcmi/vcmi/wiki/VCMI-Campaign-format#compatibility-table)
# Header properties
In header are parameters describing campaign properties
```js
...
"regions": {...},
"name": "Campaign name",
"description": "Campaign description",
"allowDifficultySelection": true,
```
- `"regions"` contains information about background and regions. See section [campaign regions](https://github.com/vcmi/vcmi/wiki/VCMI-Campaign-format#regions-description) for more information
- `"name"` is a human readable title of campaign
- `"description"` is a human readable description of campaign
- `"allowDifficultySelection"` is a boolean field (`true`/`false`) which allows or disallows to choose difficulty before scenario start
# Scenario description
Scenario description looks like follow:
```js
{
"map": "maps/SomeMap",
"preconditions": [],
"color": 0,
"difficulty": 2,
"regionText": "",
"prolog": {},
"epilog": {},
"heroKeeps": [],
"keepCreatures": [],
"startOptions": "none",
"playerColor": 0,
"bonuses": [ <see bonus description> ]
}
```
- `"map"` map name without extension but with relative path. Both *.h3m and *.vmap maps are supported
- `"preconditions"` enumerate scenarios indexes which must be completed to unlock this scenario. For example, if you want to make sequential missions, you should specify `"preconditions": []` for first scenario, but for second scenario it should be `"preconditions": [0]` and for third `"preconditions": [0, 1]`. But you can allow non-linear conquering using this parameter
- `"color"` defines color id for the region. Possible values are `0: red, 1: blue, tan: 2, green: 3, orange: 4, purple: 5, teal: 6, pink: 7`
- `"difficulty"` sets initial difficulty for this scenario. If `"allowDifficultySelection"`is defined for campaign, difficulty may be changed by player. Possible values are `0: pawn, 1: knight, 2: rook, 3: queen, 4: king`
- `"regionText"` is a text which will be shown if player holds right button over region
- `"prolog"`/`"epilog"` optional, defines prolog/epilog for scenario. See [prolog/epilog](https://github.com/vcmi/vcmi/wiki/VCMI-Campaign-format#prologepilog) section for more information
- `"heroKeeps"` defines what hero will carry to the next scenario. Can be specified one or several attributes from list `"experience", "primarySkills", "secondarySkills", "spells", "artifacts"`
- `"keepCreatures"` array of creature types which hero will carry to the next scenario. Game identifiers are used to specify creature type.
- `"startOptions"` defines what type of bonuses player may have. Possible values are `"none", "bonus", "crossover", "hero"`
- `none`: player starts scenario without bonuses. [Description](https://github.com/vcmi/vcmi/wiki/VCMI-Campaign-format#none-start-option)
- `bonus`: player chooses one of the predefined bonuses. [Description](https://github.com/vcmi/vcmi/wiki/VCMI-Campaign-format#bonus-start-option)
- `crossover`: player will start with hero from previous scenario. [Description](https://github.com/vcmi/vcmi/wiki/VCMI-Campaign-format#crossover-start-option)
- `hero` : player will start scenario with specified hero. [Description](https://github.com/vcmi/vcmi/wiki/VCMI-Campaign-format#hero-start-option)
- `"playerColor"` defines color id of flag which player will play for. Possible values are `0: red, 1: blue, tan: 2, green: 3, orange: 4, purple: 5, teal: 6, pink: 7`
- "bonuses" array of possible bonus objects, format depends on `"startOptions"` parameter
## Prolog/Epilog
Prolog and epilog properties are optional
```js
{
"video": "NEUTRALA.smk", //video to show
"music": "musicFile.ogg", //music to play, should be located in music directory
"text": "some long text" //text to be shown
}
```
## Start options and bonuses
### None start option
If `startOptions` is `none`, `bonuses` field will be ignored
### Bonus start option
If `startOptions` is `bonus`, bonus format may vary depending on its type.
```js
{
"what": "",
<attributes>
},
```
- `"what"` field defines bonus type. Possible values are: `spell, creature, building, artifact, scroll, primarySkill, secondarySkill, resource`
- `"spell"` has following attributes (fields):
- `"hero"`: hero who will get spell (see below)
- `"type"`: spell type, string, e.g. "firewall"
- `"creature"` has following attributes (fields):
- `"hero"`: hero who will get spell (see below)
- `"type"`: creature type, string, e.g. "pikeman"
- `"amount"`: amount of creatures
- `"building"` has following attributes (fields):
- `"type"`: building type (string), e.g. "citadel" or "dwellingLvl1"
- `"artifact"` has following attributes (fields):
- `"hero"`: hero who will get spell (see below)
- `"type"`: artifact type, string, e.g. "spellBook"
- `"scroll"` has following attributes (fields):
- `"hero"`: hero who will get spell (see below)
- `"type"`: spell type in the scroll, string, e.g. "firewall"
- `"primarySkill"` has following attributes (fields):
- `"hero"`: hero who will get spell (see below)
- `"attack"`: amount of attack gained
- `"defence"`: amount of defence gained
- `"spellpower"`: amount of spellpower gained
- `"knowledge"`: amount of knowledge gained
- `"secondarySkill"` has following attributes (fields):
- `"hero"`: hero who will get spell (see below)
- `"type"`: skill type, string, e.g. "logistics"
- `"amount"`: skill level, `1: beginner, 2: advanced, 3: expert`
- `"resource"` has following attributes (fields):
- `"type"`: resource type, one of `wood, ore, mercury, sulfur, crystal, gems, gold, common, rare`, where `common` is both wood and ore, `rare` means that bonus gives each rare resource
- `"amount"`: amount of resources
- `"hero"` can be specified as explicit hero name and as one of keywords: `strongest`, `generated`
### Crossover start option
If `startOptions` is `crossover`, heroes from specific scenario will be moved to this scenario. Bonus format is following
```js
{
"playerColor": 0,
"scenario": 0
},
```
- `"playerColor"` from what player color heroes shall be taken. Possible values are `0: red, 1: blue, tan: 2, green: 3, orange: 4, purple: 5, teal: 6, pink: 7`
- `"scenario"` from which scenario heroes shall be taken. 0 means first scenario
### Hero start option
If `startOptions` is `hero`, hero can be chosen as a starting bonus. Bonus format is following
```js
{
"playerColor": 0,
"hero": "random"
}
```
- `"playerColor"` from what player color heroes shall be taken. Possible values are `0: red, 1: blue, tan: 2, green: 3, orange: 4, purple: 5, teal: 6, pink: 7`
- `"hero"` can be specified as explicit hero name and as one of keywords: `random`
## Regions description
Predefined campaign regions are located in file `campaign_regions.json`
```js
{
"prefix": "G3",
"color_suffix_length": 1,
"desc": [
{ "infix": "A", "x": 289, "y": 376 },
{ "infix": "B", "x": 60, "y": 147 },
{ "infix": "C", "x": 131, "y": 202 }
]
},
```
- `"prefix"` used to identify all images related to campaign. In this example, background picture will be `G3_BG`
- `"inflix"` ised to identify all images related to region. In this example, it will be pictures starting from `G3A_..., G3B_..., G3C_..."`
- `"color_suffix_length"` identifies suffix length for region colourful frames. 1 is used for `R, B, N, G, O, V, T, P`, value 2 is used for `Re, Bl, Br, Gr, Or, Vi, Te, Pi`
# Packing campaign
After campaign scenarios and campaign description are ready, you should pack them into *.vcmp file.
This file is basically headless gz archive.
Your campaign should be stored in some folder with json describing campaign information.
Place all your scenarios inside same folder and enumerate their filenames, e.g `01.vmap`, '02.vmap', etc.
```
my-campaign/
|-- 00.json
|-- 01.vmap
|-- 02.vmap
|-- 03.vmap
```
If you use unix system, execute this command to pack your campaign:
```
gzip -c -n ./* >> my-campaign.vcmp
```
If you are using Windows system, try this https://gnuwin32.sourceforge.net/packages/gzip.htm
# Compatibility table
| Version | Min VCMI | Max VCMI | Description |
|---------|----------|----------|-------------|
| 1 | 1.3 | | Initial release |