From 74a4a10f48b3fe610afbe7250583e3ff08264787 Mon Sep 17 00:00:00 2001 From: Ivan Savenko Date: Sat, 30 Nov 2024 20:20:15 +0000 Subject: [PATCH 1/5] Added markdownlint to Github CI - Markdown will now be validated as part of Github CI - Applied auto-fix to most common issues (mostly whitespace related) - Fixed manually some of more complex cases Some valid markdownlint rules are currently disabled, to avoid failing CI, can be enabled in future --- .github/ISSUE_TEMPLATE/bug_report.md | 8 +- .github/workflows/github.yml | 6 + CI/example.markdownlint-cli2.jsonc | 280 +++ ChangeLog.md | 1590 ++++++++++------- docs/Readme.md | 20 +- docs/developers/AI.md | 14 +- docs/developers/Bonus_System.md | 13 +- docs/developers/Building_Android.md | 17 +- docs/developers/Building_Linux.md | 39 +- docs/developers/Building_Windows.md | 44 +- docs/developers/Building_iOS.md | 3 +- docs/developers/Building_macOS.md | 2 +- docs/developers/CMake.md | 32 +- docs/developers/Code_Structure.md | 26 +- docs/developers/Coding_Guidelines.md | 148 +- docs/developers/Conan.md | 10 +- .../developers/Development_with_Qt_Creator.md | 4 +- docs/developers/Logging_API.md | 57 +- docs/developers/Lua_Scripting_System.md | 90 +- docs/developers/Networking.md | 19 +- docs/developers/RMG_Description.md | 2 +- docs/developers/Serialization.md | 4 +- docs/maintainers/Project_Infrastructure.md | 106 +- docs/maintainers/Release_Process.md | 13 +- docs/maintainers/Ubuntu_PPA.md | 22 +- docs/modders/Animation_Format.md | 13 +- docs/modders/Bonus/Bonus_Duration_Types.md | 22 +- docs/modders/Bonus/Bonus_Limiters.md | 37 +- docs/modders/Bonus/Bonus_Propagators.md | 12 +- docs/modders/Bonus/Bonus_Range_Types.md | 2 +- docs/modders/Bonus/Bonus_Sources.md | 2 +- docs/modders/Bonus/Bonus_Types.md | 113 +- docs/modders/Bonus/Bonus_Updaters.md | 70 +- docs/modders/Bonus/Bonus_Value_Types.md | 24 +- docs/modders/Bonus_Format.md | 8 +- docs/modders/Building_Bonuses.md | 74 +- docs/modders/Campaign_Format.md | 15 +- docs/modders/Configurable_Widgets.md | 39 +- docs/modders/Difficulty.md | 4 +- .../Entities_Format/Artifact_Format.md | 6 +- .../Entities_Format/Battle_Obstacle_Format.md | 2 +- .../Entities_Format/Battlefield_Format.md | 2 +- docs/modders/Entities_Format/Biome_Format.md | 2 - .../Entities_Format/Creature_Format.md | 16 +- docs/modders/Entities_Format/Creature_Help.md | 52 +- .../modders/Entities_Format/Faction_Format.md | 48 +- docs/modders/Entities_Format/Faction_Help.md | 65 +- .../Entities_Format/Hero_Class_Format.md | 8 +- .../Entities_Format/Hero_Type_Format.md | 8 +- docs/modders/Entities_Format/River_Format.md | 2 +- docs/modders/Entities_Format/Road_Format.md | 2 +- .../Entities_Format/Secondary_Skill_Format.md | 2 +- docs/modders/Entities_Format/Spell_Format.md | 42 +- .../modders/Entities_Format/Terrain_Format.md | 2 +- .../Entities_Format/Town_Building_Format.md | 32 +- docs/modders/File_Formats.md | 7 +- docs/modders/Game_Identifiers.md | 2 +- docs/modders/HD_Graphics.md | 3 + docs/modders/Map_Editor.md | 14 +- docs/modders/Map_Object_Format.md | 15 +- docs/modders/Map_Objects/Boat.md | 4 +- docs/modders/Map_Objects/Creature_Bank.md | 3 + docs/modders/Map_Objects/Dwelling.md | 4 +- docs/modders/Map_Objects/Flaggable.md | 1 + docs/modders/Map_Objects/Market.md | 4 +- docs/modders/Map_Objects/Rewardable.md | 44 +- docs/modders/Mod_File_Format.md | 6 +- docs/modders/Random_Map_Template.md | 6 +- docs/modders/Readme.md | 29 +- docs/players/Bug_Reporting_Guidelines.md | 6 +- docs/players/Cheat_Codes.md | 15 +- docs/players/Game_Mechanics.md | 8 +- docs/players/Installation_Linux.md | 17 +- docs/players/Installation_Windows.md | 12 +- docs/players/Installation_iOS.md | 15 +- docs/players/Installation_macOS.md | 6 +- docs/players/Privacy_Policy.md | 2 +- docs/translators/Translations.md | 34 +- 78 files changed, 2192 insertions(+), 1360 deletions(-) create mode 100644 CI/example.markdownlint-cli2.jsonc diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index ea3d74630..be65394fc 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -15,6 +15,7 @@ Please attach game logs: `VCMI_client.txt`, `VCMI_server.txt` etc. **To Reproduce** Steps to reproduce the behavior: + 1. Go to '...' 2. Click on '....' 3. Scroll down to '....' @@ -24,7 +25,7 @@ Steps to reproduce the behavior: A clear and concise description of what you expected to happen. **Actual behavior** -A clear description what is currently happening +A clear description what is currently happening **Did it work earlier?** If this something which worked well some time ago, please let us know about version where it works or at date when it worked. @@ -33,8 +34,9 @@ If this something which worked well some time ago, please let us know about vers If applicable, add screenshots to help explain your problem. **Version** - - OS: [e.g. Windows, macOS Intel, macOS ARM, Android, Linux, iOS] - - Version: [VCMI version] + +- OS: [e.g. Windows, macOS Intel, macOS ARM, Android, Linux, iOS] +- Version: [VCMI version] **Additional context** Add any other context about the problem here. diff --git a/.github/workflows/github.yml b/.github/workflows/github.yml index 4507ca072..b4beca40b 100644 --- a/.github/workflows/github.yml +++ b/.github/workflows/github.yml @@ -402,3 +402,9 @@ jobs: run: | sudo apt install python3-jstyleson python3 CI/validate_json.py + + - name: Validate Markdown + uses: DavidAnson/markdownlint-cli2-action@v18 + with: + config: 'CI/example.markdownlint-cli2.jsonc' + globs: '**/*.md' diff --git a/CI/example.markdownlint-cli2.jsonc b/CI/example.markdownlint-cli2.jsonc new file mode 100644 index 000000000..9b009818f --- /dev/null +++ b/CI/example.markdownlint-cli2.jsonc @@ -0,0 +1,280 @@ +{ + "config" : { + "default" : true, + + // MD001/heading-increment : Heading levels should only increment by one level at a time : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md001.md + "MD001": false, + + // MD003/heading-style : Heading style : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md003.md + "MD003": { + "style": "atx" + }, + + // MD004/ul-style : Unordered list style : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md004.md + "MD004": false, + // FIXME: enable and consider fixing + //{ + // "style": "consistent" + //}, + + // MD005/list-indent : Inconsistent indentation for list items at the same level : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md005.md + "MD005": true, + + // MD007/ul-indent : Unordered list indentation : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md007.md + "MD007": { + // Spaces for indent + "indent": 2, + // Whether to indent the first level of the list + "start_indented": false, + // Spaces for first level indent (when start_indented is set) + "start_indent": 0 + }, + + // MD009/no-trailing-spaces : Trailing spaces : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md009.md + "MD009": { + // Spaces for line break + "br_spaces": 2, + // Allow spaces for empty lines in list items + "list_item_empty_lines": false, + // Include unnecessary breaks + "strict": false + }, + + // MD010/no-hard-tabs : Hard tabs : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md010.md + "MD010": { + // Include code blocks + "code_blocks": false, + // Fenced code languages to ignore + "ignore_code_languages": [], + // Number of spaces for each hard tab + "spaces_per_tab": 4 + }, + + // MD011/no-reversed-links : Reversed link syntax : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md011.md + "MD011": true, + + // MD012/no-multiple-blanks : Multiple consecutive blank lines : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md012.md + "MD012": { + // Consecutive blank lines + "maximum": 1 + }, + + // MD013/line-length : Line length : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md013.md + "MD013": false, + + // MD014/commands-show-output : Dollar signs used before commands without showing output : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md014.md + "MD014": true, + + // MD018/no-missing-space-atx : No space after hash on atx style heading : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md018.md + "MD018": true, + + // MD019/no-multiple-space-atx : Multiple spaces after hash on atx style heading : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md019.md + "MD019": true, + + // MD020/no-missing-space-closed-atx : No space inside hashes on closed atx style heading : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md020.md + "MD020": true, + + // MD021/no-multiple-space-closed-atx : Multiple spaces inside hashes on closed atx style heading : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md021.md + "MD021": true, + + // MD022/blanks-around-headings : Headings should be surrounded by blank lines : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md022.md + "MD022": { + // Blank lines above heading + "lines_above": 1, + // Blank lines below heading + "lines_below": 1 + }, + + // MD023/heading-start-left : Headings must start at the beginning of the line : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md023.md + "MD023": true, + + // MD024/no-duplicate-heading : Multiple headings with the same content : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md024.md + "MD024": false, + // FIXME: false positives? + //{ + // // Only check sibling headings + // "allow_different_nesting": true, + // // Only check sibling headings + // "siblings_only": true + //}, + + // MD025/single-title/single-h1 : Multiple top-level headings in the same document : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md025.md + "MD025": { + // Heading level + "level": 1, + // RegExp for matching title in front matter + "front_matter_title": "^\\s*title\\s*[:=]" + }, + + // MD026/no-trailing-punctuation : Trailing punctuation in heading : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md026.md + "MD026": { + // Punctuation characters + "punctuation": ".,;:!。，；：！" + }, + + // MD027/no-multiple-space-blockquote : Multiple spaces after blockquote symbol : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md027.md + "MD027": true, + + // MD028/no-blanks-blockquote : Blank line inside blockquote : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md028.md + "MD028": true, + + // MD029/ol-prefix : Ordered list item prefix : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md029.md + "MD029": false, + // FIXME: false positives or broken formatting + //{ + // // List style + // "style": "ordered" + //}, + + // MD030/list-marker-space : Spaces after list markers : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md030.md + "MD030": { + // Spaces for single-line unordered list items + "ul_single": 1, + // Spaces for single-line ordered list items + "ol_single": 1, + // Spaces for multi-line unordered list items + "ul_multi": 1, + // Spaces for multi-line ordered list items + "ol_multi": 1 + }, + + // MD031/blanks-around-fences : Fenced code blocks should be surrounded by blank lines : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md031.md + "MD031": { + // Include list items + "list_items": false + }, + + // MD032/blanks-around-lists : Lists should be surrounded by blank lines : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md032.md + "MD032": true, + + // MD033/no-inline-html : Inline HTML : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md033.md + "MD033": false, + // FIXME: enable and consider fixing + //{ + // // Allowed elements + // "allowed_elements": [] + //}, + + // MD034/no-bare-urls : Bare URL used : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md034.md + "MD034": true, + + // MD035/hr-style : Horizontal rule style : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md035.md + "MD035": { + // Horizontal rule style + "style": "consistent" + }, + + // MD036/no-emphasis-as-heading : Emphasis used instead of a heading : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md036.md + "MD036": false, + // FIXME: enable and consider fixing + // { + // // Punctuation characters + // "punctuation": ".,;:!?。，；：！？" + // }, + + // MD037/no-space-in-emphasis : Spaces inside emphasis markers : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md037.md + "MD037": true, + + // MD038/no-space-in-code : Spaces inside code span elements : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md038.md + "MD038": true, + + // MD039/no-space-in-links : Spaces inside link text : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md039.md + "MD039": true, + + // MD040/fenced-code-language : Fenced code blocks should have a language specified : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md040.md + "MD040": false, + // FIXME: enable and consider fixing + //{ + //// List of languages + // "allowed_languages": [ "cpp", "json", "jsonc", "json5", "sh" ], + //// Require language only + // "language_only": true + //}, + + // MD041/first-line-heading/first-line-h1 : First line in a file should be a top-level heading : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md041.md + "MD041": { + // Heading level + "level": 1, + // RegExp for matching title in front matter + "front_matter_title": "^\\s*title\\s*[:=]" + }, + + // MD042/no-empty-links : No empty links : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md042.md + "MD042": true, + + // MD043/required-headings : Required heading structure : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md043.md + "MD043": false, + + // MD044/proper-names : Proper names should have the correct capitalization : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md044.md + "MD044": false, + + // MD045/no-alt-text : Images should have alternate text (alt text) : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md045.md + "MD045": false, + + // MD046/code-block-style : Code block style : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md046.md + "MD046": { + // Block style + "style": "fenced" + }, + + // MD047/single-trailing-newline : Files should end with a single newline character : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md047.md + "MD047": true, + + // MD048/code-fence-style : Code fence style : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md048.md + "MD048": { + // Code fence style + "style": "backtick" + }, + + // MD049/emphasis-style : Emphasis style : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md049.md + "MD049": { + // Emphasis style + "style": "asterisk" + }, + + // MD050/strong-style : Strong style : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md050.md + "MD050": { + // Strong style + "style": "asterisk" + }, + + + + // MD051/link-fragments : Link fragments should be valid : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md051.md + "MD051": true, + + // MD052/reference-links-images : Reference links and images should use a label that is defined : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md052.md + "MD052": { + // Include shortcut syntax + "shortcut_syntax": false + }, + + // MD053/link-image-reference-definitions : Link and image reference definitions should be needed : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md053.md + "MD053": { + // Ignored definitions + "ignored_definitions": [ + "//" + ] + }, + + // MD054/link-image-style : Link and image style : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md054.md + "MD054": { + // Allow autolinks + "autolink": true, + // Allow inline links and images + "inline": true, + // Allow full reference links and images + "full": true, + // Allow collapsed reference links and images + "collapsed": true, + // Allow shortcut reference links and images + "shortcut": true, + // Allow URLs as inline links + "url_inline": true + }, + + // MD058 - Tables should be surrounded by blank lines + "MD058" : true + + } +} \ No newline at end of file diff --git a/ChangeLog.md b/ChangeLog.md index c045b41bf..3dd77dbb7 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -1,6 +1,9 @@ -# 1.5.7 -> 1.6.0 (in development) +# VCMI Project Changelog + +## 1.5.7 -> 1.6.0 (in development) ### Major changes + * Implemented handicap system, with options to reduce income and growth in addition to starting resources restriction * Game will now show statistics after scenario completion, such as resources or army strength over time * Implemented spell quick selection panel in combat @@ -12,12 +15,14 @@ * VCMI will now launch in fullscreen on desktop systems. Use F4 hotkey or toggle option in settings to restore old behavior ### General + * Saved game size reduced by approximately 3 times, especially for large maps or games with a large number of mods. * Mods that modify game texts, such as descriptions of secondary skills, will now correctly override translation mods * Game will now correctly restore information such as hero path, order of heroes and towns, and list of sleeping heroes on loading a save game * Added translation for missing texts, such as random map descriptions, quick exchange buttons, wog commander abilities, moat names ### Multiplayer + * Added option to start vcmi server on randomly selected TCP port * Fixed potential desynchronization between server and clients on randomization of map objects if client and server run on different operating systems * Fixed possible freeze on receiving turn in multiplayer when player has town window opened @@ -27,11 +32,13 @@ * Game will now correctly show turn timers and simultaneous turns state on loading game ### Stability + * Fixed possible crash on connecting bluetooth mouse during gameplay on Android * VCMI will now write more detailed information to log file on crash due to uncaught exception * Fixed crash on transfer of multiple artifacts in a backpack to another hero on starting next campaign scenario without hero that held these artifacts before ### Mechanics + * Arrow tower will now prefer to attack more units that are viewed most dangerous instead of simply attacking top-most unit * Score in campaigns will now be correctly tracked for games loaded from a save * Fixed incorrect direction of Dragon Breath attack in some cases if wide creature attacks another wide creature @@ -49,6 +56,7 @@ * It is now possible to target empty hex for shooters with area attack, such as Magog or Lich ### Video / Audio + * Fixed playback of audio stream with different formats from video files in some Heroes 3 versions * Video playback will not be replaced by a black square when another dialogue box is on top of the video. * When resuming video playback, the video will now be continued instead of being restarted. @@ -66,6 +74,7 @@ * Added option to scale all in-game fonts when scalable true type fonts are in use ### Interface + * It is now possible to search for a map object using Ctrl+F hotkey * Added option to drag map with right-click * Added hotkeys to reorder list of owned towns or heroes @@ -78,7 +87,7 @@ * Semi-transparent shadows now correctly update their transparency during fading effects, such as resource pickups * Game will now save all names for human player in hotseat mode * Added unassigned by default shortcuts for toggling visibility of visitable and blocked tiles -* Spellbook button in battle is now blocked if hero has no spellbook +* Spellbook button in battle is now blocked if hero has no spellbook * Adventure map will no longer scroll if window is not in focus * Removed second info window when player loses his last town * Fixed hero path not updating correctly after hiring or dismissing creatures @@ -93,6 +102,7 @@ * Fixed incorrect display of names of VCMI maps in scenario selection if multiple VCMI map are present in list ### Random Maps Generator + * Implemented connection option 'forcePortal' * It is now possible to connect zone to itself using pair of portals * It is now possible for a random map template to change game settings @@ -102,15 +112,17 @@ * Fixed values of Pandora Boxes with creatures to be in line with H3:SoD ### Campaigns + * It is now possible to use .zip archive for VCMI campaigns instead of raw gzip stream * Fixed handling of hero placeholders in VCMI map format (.vmap) * Fixed not functioning hero carryover in VCMI campaigns * Added support for campaign outro videos, such as outro in "Song for the Father" campaign * Added support for rim image for intro video, such as opening videos in Heroes Chronicles * Added support for custom loading screen in campaigns -* Added support for custom region definitions (such as background images) for VCMI campaigns +* Added support for custom region definitions (such as background images) for VCMI campaigns ### AI + * VCMI will now use BattleAI for battles with neutral enemies by default * Fixed bug where BattleAI attempts to move double-wide unit to an unreachable hex * Fixed several cases where Nullkiller AI can count same dangerous object twice, doubling expected army loss. @@ -125,9 +137,11 @@ * Fixed possible crash on AI attempting to visit town that is already being visited by this hero ### Launcher + * Added Swedish translation ### Map Editor + * Implemented tracking of building requirements for Building Dialog * Added build/demolish/enable/disable all buildings options to Building Dialog in town properties * Implemented configuration of patrol radius for heroes @@ -142,6 +156,7 @@ * Timed events interfaces now counts days from 1, instead of from 0 ### Modding + * Added support for configurable flaggable objects that can provide bonuses or daily income to owning player * Added support for soft dependencies for mods, that only affect mod loading order (and as result - override order), without requiring dependent mod or allowing access to its identifiers * It is now possible to provide translations for mods that modify strings from original game, such as secondary skill descriptions @@ -176,7 +191,7 @@ * Json Validator will now attempt to detect typos when encountering unknown property in Json * Added `translate missing` command that will export only untranslated strings into `translationsMissing` directory, separated per mod -# 1.5.6 -> 1.5.7 +## 1.5.6 -> 1.5.7 * Fixed game freeze if player is attacked in online multiplayer game by another player when he has unread dialogs, such as new week notification * Fixed possible game crash after being attacked by enemy with artifact that blocks spellcasting @@ -188,14 +203,16 @@ * Fixed excessive removal of open dialogs such as new week or map events on new turn * Fixed objects like Mystical Gardens not resetting their state on new week correctly -# 1.5.5 -> 1.5.6 +## 1.5.5 -> 1.5.6 ### Stability + * Fixed possible crash on transferring hero to next campaign scenario if hero has combined artifact some components of which can be transferred * Fixed possible crash on transferring hero to next campaign scenario that has creature with faction limiter in his army * Fixed possible crash on application shutdown due to incorrect destruction order of UI entities ### Multiplayer + * Mod compatibility issues when joining a lobby room now use color coding to make them less easy to miss. * Incompatible mods are now placed before compatible mods when joining lobby room. * Fixed text overflow in online lobby interface @@ -203,21 +220,24 @@ * Fixed non-functioning slider in invite to game room dialog ### Interface + * Fixed some shortcuts that were not active during the enemy's turn, such as Thieves' Guild. * Game now correctly uses melee damage calculation when forcing a melee attack with a shooter. * Game will now close all open dialogs on start of our turn, to avoid bugs like locked right-click popups ### Map Objects + * Spells the hero can't learn are no longer hidden when received from a rewardable object, such as the Pandora Box * Spells that cannot be learned are now displayed with gray text in the name of the spell. * Configurable objects with scouted state such as Witch Hut in HotA now correctly show their reward on right click after vising them but refusing to accept reward * Right-click tooltip on map dwelling now always shows produced creatures. Player that owns the dwelling can also see number of creatures available for recruit ### Modding + * Fixed possible crash on invalid SPELL_LIKE_ATTACK bonus * Added compatibility check when loading maps with old names for boats -# 1.5.4 -> 1.5.5 +## 1.5.4 -> 1.5.5 * Fixed crash when advancing to the next scenario in campaigns when the hero not transferring has a combination artefact that can be transferred to the next scenario. * Fixed game not updating information such as hero path and current music on new day @@ -227,20 +247,23 @@ * Shift+left click now directly opens the hero window when two heroes are in town * Fixed handling of alternative actions for creatures that have more than two potential actions, such as move, shoot, and cast spells. -# 1.5.3 -> 1.5.4 +## 1.5.3 -> 1.5.4 ### Stability + * Fixed a possible crash when clicking on an adventure map when another player is taking a turn in multiplayer mode. * Failure to extract a mod will now display an error message instead of a silent crash. * Fixed crash on opening town hall screen of a town from a mod with invalid building identifier * Fixed crash when faerie dragons die after casting Ice Ring on themselves. ### Mechanics + * The scholar will now correctly upgrade a skill if the visiting hero has offered a skill at either the basic or advanced level. * Hero now reveals Fog of War when receiving new or upgraded secondary skills (such as scouting). * AI will now always act after all human players during simturns instead of acting after host player ### Interface + * Pressing the up and down keys on the town screen will now move to the next or previous town instead of scrolling through the list of towns. * Long text in scenario name and highscore screen now shortened to fit the interface * Game now moves cursor to tap event position when using software cursor with touch screen input @@ -248,16 +271,19 @@ * Damage estimation tooltip will no longer show damage greater than the targeted unit's health. ### Random Maps Generator + * Generator will try to place roads even further away from zone borders * Fixed rare crash when placing two quest artefacts in the same location at the same time ### AI + * Improved performance of Nullkiller AI * Stupid AI no longer overestimates damage when killing entire unit * Fixed a bug leading to Battle AI not using spells when sieging town with Citadel or Castle built * Fixed an unsigned integer overflow that caused the Nullkiller AI to overestimate the total army strength after merging two armies. ### Launcher + * Added button to reset touchscreen tutorial on mobile systems * Launcher will now warn if player selects Gog Galaxy installer instead of offline installer * Launcher will now ask for the .bin file first as it is usually listed first in the file system view @@ -267,16 +293,19 @@ * Fixed manual file installation on Android ### Map Editor + * Icons and translations now embedded in executable file ### Modding + * Improved bonus format validation * Validator now reports valid values for enumeration fields * Fixed missing addInfo field for bonuses that use the BONUS_OWNER_UPDATER propagation updater. -# 1.5.2 -> 1.5.3 +## 1.5.2 -> 1.5.3 ### Stability + * Fixed possible crash when hero class has no valid commander. * Fixed crash when pressing spacebar or enter during combat when hero has no tactics skill. * Fixed crash when receiving a commander level-up after winning a battle in a garrison owned by an enemy player. @@ -289,8 +318,9 @@ * Game will now display an error message instead of silent crash if game data directory is not accessible ### Mechanics + * Transport Artefact victory condition will no longer trigger if another player has completed it. -* Fixed wandering monster combat not triggering when landing in its zone of control when flying from above the monster using the Fly spell. +* Fixed wandering monster combat not triggering when landing in its zone of control when flying from above the monster using the Fly spell. * Fixed potentially infinite movement loop when the hero has Admiral's Hat whirlpool immunity and the hero tries to enter and exit the same whirlpool. * If game picks gold for a random resource pile that has predetermined by map amount, its amount will be correctly multiplied by 100 * Fixed hero not being able to learn spells from a mod in some cases, even if they are available from the town's mage guild. @@ -299,6 +329,7 @@ * If turn timer runs out during pve battle game will end player turn after a battle instead of forcing retreat ### Interface + * Fixed reversed button functions in Exchange Window * Fixed allied towns being missing from the list when using the advanced or expert Town Portal spell. * Fixed corrupted UI that could appear for a frame under certain conditions @@ -311,6 +342,7 @@ * It is now possible to scroll through artifacts backpack using mouse wheel or swipe ### Launcher + * Android now uses the same Qt-based launcher as other systems * Fixed attempt to install a submod when installing new mod that depends on a submod of another mod * Fixed wrong order of activating mods in chain when installing multiple mods at once @@ -324,15 +356,16 @@ * Replaced checkboxes with toggle buttons for easier of access on touchscreens. * Icons and translations now embedded in executable file * Added interface for configuring several previously existing but inaccessible options in Launcher: - * Selection of input tolerance precision for all input types - * Relative cursor mode for mobile systems (was only available on Android) - * Haptic feedback toggle for mobile systems (was only available on Android) - * Sound and music volume (was only available in game) - * Selection of long touch interval (was only available in game) - * Selection of upscaling filter used by SDL - * Controller input sensitivity and acceleration. + * Selection of input tolerance precision for all input types + * Relative cursor mode for mobile systems (was only available on Android) + * Haptic feedback toggle for mobile systems (was only available on Android) + * Sound and music volume (was only available in game) + * Selection of long touch interval (was only available in game) + * Selection of upscaling filter used by SDL + * Controller input sensitivity and acceleration. ### AI + * Fixed crash when Nullkiller AI tries to explore after losing the hero in combat. * Fixed rare crash when Nullkiller AI tries to use portals * Fixed potential crash when Nullkiller AI has access to Town Portal spell @@ -341,19 +374,23 @@ * Fixed bug leading to Battle AI doing nothing if targeted unit is unreachable ### Random Maps Generator + * Fixed crash when player selects a random number of players and selects a different colour to play, resulting in a non-continuous list of players. * Fixed rare crash when generating maps with water ### Map Editor + * Fixed crash on closing map editor ### Modding + * Added new building type 'thievesGuild' which implements HotA building in Cove. * Creature terrain limiter now actually accepts terrain as parameter -# 1.5.1 -> 1.5.2 +## 1.5.1 -> 1.5.2 ### Stability + * Fixed crash on closing game while combat or map animations are playing * Fixed crash on closing game while network thread is waiting for dialog to be closed * Fixed random crash on starting random map with 'random' number of players @@ -367,6 +404,7 @@ * Game will now abort loading if a corrupt mod is detected instead of crashing without explanation later ### Multiplayer + * Contact between allied players will no longer break simturns * Having hero in range of object owned by another player will now be registered as contact * Multiplayer saves are now visible when starting a single player game @@ -375,11 +413,13 @@ * All multiplayer chat commands now use a leading exclamation mark ### Campaigns + * If the hero attacks an enemy player and is defeated, he will be correctly registered as defeated by the defending player. * Allow standard victory condition on 'To kill a hero' campaign mission in line with H3 * Fixes Adrienne starting without Inferno spell in campaign ### Interface + * For artefacts that are part of a combined artefact, the game will now show which component of that artefact your hero has. * Fixed broken in 1.5.1 shortcut for artifact sets saving * Fixed full screen toggle (F4) not applying changes immediately @@ -391,37 +431,38 @@ * Added keyboard shortcuts to markets and altars. 'Space' to confirm deal and 'M' to trade maximum possible amount * Pressing 'Escape' in main menu will now trigger 'Back' and 'Quit' buttons * Added keyboard shortcuts to hero exchange window: - * 'F10' will now swap armies - * 'F11' will now swap artifacts. Additionally, 'Ctrl+F11' will swap equipped artifacts, and 'Shift+F11' will swap backpacks - * Added unassigned shortcuts to move armies or artifacts to left or right side + * 'F10' will now swap armies + * 'F11' will now swap artifacts. Additionally, 'Ctrl+F11' will swap equipped artifacts, and 'Shift+F11' will swap backpacks + * Added unassigned shortcuts to move armies or artifacts to left or right side * Added keyboard shortcuts to access buildings from town interface: - * 'F' will now open Fort window - * 'B' will now open Town Hall window - * 'G' will now open Mage Guild window - * 'M' will now open Marketplace - * 'R' will now open recruitment interface - * 'T' will now open Tavern window - * 'G' will now open Thieves Guild - * 'E' will now open hero exchange screen, if both heroes are present in town - * 'H' will now open hero screen. Additionally, 'Shift+H' will open garrisoned hero screen, and 'Ctrl+H' will open visiting hero screen - * 'Space' will now swap visiting and garrisoned heroes + * 'F' will now open Fort window + * 'B' will now open Town Hall window + * 'G' will now open Mage Guild window + * 'M' will now open Marketplace + * 'R' will now open recruitment interface + * 'T' will now open Tavern window + * 'G' will now open Thieves Guild + * 'E' will now open hero exchange screen, if both heroes are present in town + * 'H' will now open hero screen. Additionally, 'Shift+H' will open garrisoned hero screen, and 'Ctrl+H' will open visiting hero screen + * 'Space' will now swap visiting and garrisoned heroes * Added keyboard shortcuts to switch between tabs in Scenario Selection window: - * 'E' will open Extra Options tab - * 'T' will open Turn Options tab - * 'I' will open Invite Players window (only for lobby games) - * 'R' will now replay video in campaigns + * 'E' will open Extra Options tab + * 'T' will open Turn Options tab + * 'I' will open Invite Players window (only for lobby games) + * 'R' will now replay video in campaigns * Added keyboard shortcuts to Adventure map: - * 'Ctrl+L' will now prompt to open Load Game screen - * 'Ctrl+M' will now prompt to go to main menu - * 'Ctrl+N' will now prompt to go to New Game screen - * 'Ctrl+Q' will now prompt to quit game - * Page Up, Page Down, Home and End keys will now move hero on adventure map similar to numpad equivalents - * Fixed non-functioning shortcuts '+' and '-' on numpad to zoom adventure map + * 'Ctrl+L' will now prompt to open Load Game screen + * 'Ctrl+M' will now prompt to go to main menu + * 'Ctrl+N' will now prompt to go to New Game screen + * 'Ctrl+Q' will now prompt to quit game + * Page Up, Page Down, Home and End keys will now move hero on adventure map similar to numpad equivalents + * Fixed non-functioning shortcuts '+' and '-' on numpad to zoom adventure map * Added keyboard shortcuts to Battle interface: - * 'V' now allows to view information of hovered unit - * 'I' now allows to view information of active unit + * 'V' now allows to view information of hovered unit + * 'I' now allows to view information of active unit ### Mechanics + * Game will no longer pick creatures exclusive to AB campaigns for random creatures or for Refugee Camp, in line with H3 * If original movement rules are on, it is not possible to attack guards from visitable object directly, only from free tile * Fixed bug leading that allowed picking up objects while flying on top of water @@ -429,24 +470,29 @@ * Interface will now use same arrow for U-turns in path as H3 ### AI + * Nullkiller AI can now explore the map * Nullkiller AI will no longer use the map reveal cheat when allied with a human or when playing on low difficulty * Nullkiller AI is now used by default for allied players ### Launcher + * When extracting data from gog.com offline installer game will extract files directly into used data directory instead of temporary directory ### Map Editor + * Fixed victory / loss conditions widget initialization ### Modding + * Hero specialties with multiple bonuses that have TIMES_HERO_LEVEL updater now work as expected * Spells that apply multiple bonuses with same type and subtype but different value type now work as expected * Added option to toggle layout of guards in creature banks -# 1.5.0 -> 1.5.1 +## 1.5.0 -> 1.5.1 ### Stability + * Fixed possible crash on accessing faction description * Fixed possible thread race on exit to main menu * Game will now show error message instead of silent crash on corrupted H3 data @@ -459,6 +505,7 @@ * If json file specified in mod.json is missing, vcmi will now only log an error instead of crashing ### Interface + * Added retaliation damage and kills preview when hovering over units that can be attacked in melee during combat * Clicking on combat log would now open a window with full combat log history * Removed message length limit in text input fields, such as global lobby chat @@ -472,10 +519,12 @@ * Small windows no longer dim the entire screen by default ### Mechanics + * Recruiting a hero will now immediately reveal the fog of war around him * When both a visiting hero and a garrisoned hero are in town, the garrisoned hero will visit town buildings first. ### Multiplayer + * Fixed in-game chat text not being visible after switching from achannel with a long history * Fixed lag when switching to channel with long history * Game now automatically scrolls in-game chat on new messages @@ -490,23 +539,27 @@ * Fixed overflow in invite window when there are more than 8 players in the lobby ### Random Maps Generator + * Generator will now prefer to place roads away from zone borders ### AI + * Fixed possible crash when Nullkiller AI tries to upgrade army * Nullkiller AI will now recruit new heroes if he left with 0 heroes * AI in combat now knows when an enemy unit has used all of its retaliations. ### Map Editor + * Fixed setting up hero types of heroes in Prisons placed in map editor * Fixed crash on setting up Seer Hut in map editor * Added text auto-completion hints for army widget * Editor will now automatically add .vmap extensions when saving map * Fixed text size in map validation window -# 1.4.5 -> 1.5.0 +## 1.4.5 -> 1.5.0 ### General + * Added Portuguese (Brazilian) translation * Added basic support for game controllers * Added option to disable cheats in game @@ -515,6 +568,7 @@ * Implemented switchable artifact sets from HD Mod ### Stability + * Fixed possible crash in Altar of Sacrifice * Fixed possible crash on activation of 'Enchanted' bonus * Fixed possible race condition on random maps generation on placement treasures near border with water zone @@ -531,6 +585,7 @@ * Fixed possible hanging app on attempt to close game during loading ### Multiplayer + * Game map will no longer be locked during turn of other human players, allowing to change hero paths or inspect towns or heroes * Game will now correctly block most of player actions outside of their turn * Implemented new lobby, available in game with persistent accounts and chat @@ -543,6 +598,7 @@ * Implemented rolling and banning of towns before game start ### Interface + * Implemented configurable keyboard shortcuts, editable in file config/shortcutsConfig.json * Fixed broken keyboard shortcuts in main menu * If UI Enhancements are enabled, the game will skip confirmation dialogs when entering owned dwellings or refugee camp. @@ -580,6 +636,7 @@ * Recruitment costs that consist from 3 different resources should now fit recruitment window UI better ### Campaigns + * Game will now correctly track who defeated the hero or wandering monsters for related quests and victory conditions * Birth of a Barbarian: Yog will now start the third scenario with Angelic Alliance in his inventory * Birth of a Barbarian: Heroes with Angelic Alliance components are now considered to be mission-critical and can't be dismissed or lost in combat @@ -597,6 +654,7 @@ * Fixed invalid string on right-clicking secondary skill starting bonus ### Battles + * Added option to enable unlimited combat replays during game setup * Added option to instantly end battle using quick combat (shortcut: 'e') * Added option to replace auto-combat button action with instant end using quick combat @@ -605,6 +663,7 @@ * Fixed positioning of unit stack size label ### Mechanics + * It is no longer possible to learn spells from Pandora or events if hero can not learn them * Fixed behavior of 'Dimension Door' spell to be in line with H3:SoD * Fixed behavior of 'Fly' spell to be in line with H3:SoD @@ -627,6 +686,7 @@ * Fixed regression leading to large elemental dwellings being used as replacements for random dwellings ### Random Maps Generator + * Game will now save last used RMG settings in game and in editor * Reduced number of obstacles placed in water zones * Treasure values in water zone should now be similar to values from HotA, due to bugs in H3:SoD values @@ -643,6 +703,7 @@ * Windmill will now appear on top of all other objects ### Launcher + * Launcher now supports installation of Heroes 3 data using gog.com offline installer thanks to innoextract tool * Fixed loading of mod screenshots if player opens screenshots tab without any preloaded screenshots * Fixed installation of mods if it has non-installed submod as dependency @@ -652,6 +713,7 @@ * Added Portuguese translation to launcher ### Map Editor + * Added Chinese translation to map editor * Added Portuguese translation to map editor * Mod list in settings will now correctly show submods of submods @@ -661,6 +723,7 @@ * It is now possible to customize hero spells ### AI + * Fixed possible crash on updating NKAI pathfinding data * Fixed possible crash if hero has only commander left without army * Fixed possible crash on attempt to build tavern in a town @@ -671,15 +734,16 @@ * It is now possible to configure AI settings via config file * Improved parallelization when AI has multiple heroes * AI-controlled creatures will now correctly move across wide moat in Fortress -* Fixed system error messages caused by visitation of Trading Posts by VCAI +* Fixed system error messages caused by visitation of Trading Posts by VCAI * Patrolling heroes will never retreat from the battle * AI will now consider strength of town garrison and not just strength of visiting hero when deciding to attack town ### Modding + * Added new game setting that allows inviting heroes to taverns * It is now possible to add creature or faction description accessible via right-click of the icon * Fixed reversed Overlord and Warlock classes mapping -* Added 'selectAll' mode for configurable objects which grants all potential rewards +* Added 'selectAll' mode for configurable objects which grants all potential rewards * It is now possible to use most of json5 format in vcmi json files * Main mod.json file (including any submods) now requires strict json, without comments or extra commas * Replaced bonus MANA_PER_KNOWLEDGE with MANA_PER_KNOWLEDGE_PERCENTAGE to avoid rounding error with mysticism @@ -688,9 +752,10 @@ * Game will now report cases where minimal damage of a creature is greater than maximal damage * Added bonuses RESOURCES_CONSTANT_BOOST and RESOURCES_TOWN_MULTIPLYING_BOOST -# 1.4.4 -> 1.4.5 +## 1.4.4 -> 1.4.5 ### Stability + * Fixed crash on creature spellcasting * Fixed crash on unit entering magical obstacles such as quicksands * Fixed freeze on map loading on some systems @@ -698,24 +763,29 @@ * Fixed crash on opening creature information window with invalid SPELL_IMMUNITY bonus ### Random Maps Generator + * Fixed placement of guards sometimes resulting into open connection into third zone * Fixed rare crash on multithreaded access during placement of artifacts or wandering monsters ### Map Editor + * Fixed inspector using wrong editor for some values ### AI -* Fixed bug leading to AI not attacking wandering monsters in some cases -* Fixed crash on using StupidAI for autocombat or for enemy players -# 1.4.3 -> 1.4.4 +* Fixed bug leading to AI not attacking wandering monsters in some cases +* Fixed crash on using StupidAI for autocombat or for enemy players + +## 1.4.3 -> 1.4.4 ### General + * Fixed crash on generation of random maps -# 1.4.2 -> 1.4.3 +## 1.4.2 -> 1.4.3 ### General + * Fixed the synchronisation of the audio and video of the opening movies. * Fixed a bug that caused spells from mods to not show up in the Mage's Guild. * Changed the default SDL driver on Windows from opengl to autodetection @@ -723,6 +793,7 @@ * Movement and mana points are now replenished for new heroes in taverns. ### Multiplayer + * Simturn contact detection will now correctly check for hero moving range * Simturn contact detection will now ignore wandering monsters * Right-clicking the Simturns AI option now displays a tooltip @@ -732,12 +803,14 @@ * Ending a turn during simturns will now block the interface correctly. ### Campaigns + * Player will no longer start the United Front of Song for the Father campaign with two Nimbuses. * Fixed missing campaign description after loading saved game * Campaign completion checkmarks will now be displayed after the entire campaign has been completed, rather than just after the first scenario. * Fixed positioning of prologue and epilogue text during campaign scenario intros ### Interface + * Added an option to hide adventure map window when town or battle window are open * Fixed switching between pages on small version of spellbook * Saves with long filenames are now truncated in the UI to prevent overflow. @@ -748,10 +821,11 @@ * Fixed incorrect cursor display when hovering over water objects accessible from shore ### Stability + * Fixed a crash when using the 'vcmiobelisk' cheat more than once. * Fixed crash when reaching level 201. The maximum level is now limited to 197. * Fixed crash when accessing a spell with an invalid SPELLCASTER bonus -* Fixed crash when trying to play music for an inaccessible tile +* Fixed crash when trying to play music for an inaccessible tile * Fixed memory corruption on loading of old mods with illegal 'index' field * Fixed possible crash on server shutdown on Android * Fixed possible crash when the affinity of the hero class is set to an invalid value @@ -759,11 +833,13 @@ * Failure to initialise video subsystem now displays error message instead of silent crash ### Random Maps Generator + * Fixed possible creation of a duplicate hero in a random map when the player has chosen the starting hero. * Fixed banning of quest artifacts on random maps * Fixed banning of heroes in prison on random maps ### Battles + * Battle turn queue now displays current turn * Added option to show unit statistics sidebar in battle * Right-clicking on a unit in the battle turn queue now displays the unit details popup. @@ -774,6 +850,7 @@ * Coronius specialty will now correctly select affected units ### Launcher + * Welcome screen will automatically detect existing Heroes 3 installation on Windows * It is now possible to install mods by dragging and dropping onto the launcher. * It is now possible to install maps and campaigns by dragging and dropping onto the launcher. @@ -781,15 +858,18 @@ * Added option to select preferred SDL driver in launcher ### Map Editor + * Fixed saving of allowed abilities, spells, artifacts or heroes ### AI + * AI will no longer attempt to move immobilized units, such as those under the effect of Dendroid Bind. * Fixed shooters not shooting when they have a range penalty * Fixed Fire Elemental spell casting * Fixed rare bug where unit would sometimes do nothing in battle ### Modding + * Added better reporting of "invalid identifiers" errors with suggestions on how to fix them * Added FEROCITY bonus (HotA Aysiud) * Added ENEMY_ATTACK_REDUCTION bonus (HotA Nix) @@ -801,9 +881,10 @@ * BLOCKS_RETALIATION now also blocks FIRST_STRIKE bonus * Added 'canCastOnSelf' field for spells to allow creatures to cast spells on themselves. -# 1.4.1 -> 1.4.2 +## 1.4.1 -> 1.4.2 ### General + * Restored support for Windows 7 * Restored support for 32-bit builds * Implemented quick backpack window for slot-specific artifact selection, activated via mouse wheel / swipe gesture @@ -817,10 +898,12 @@ * added nwctheone / vcmigod cheat: reveals the whole map, gives 5 archangels in each empty slot, unlimited movement points and permanent flight to currently selected hero ### Launcher + * Launcher will now properly show mod installation progress * Launcher will now correctly select preferred language on first start ### Multiplayer + * Timers for all players will now be visible at once * Turn options menu will correctly open for guests when host switches to it * Guests will correctly see which roads are allowed for random maps by host @@ -831,6 +914,7 @@ * Game will now send notifications to players when simultaneous turns end ### Stability + * Fixed crash on clicking town or hero list on MacOS and iOS * Fixed crash on closing vcmi on Android * Fixed crash on disconnection from multiplayer game @@ -847,6 +931,7 @@ * Added check for presence of Armageddon Blade campaign files to avoid crash on some Heroes 3 versions ### Random Maps Generator + * Improved performance of random maps generation * Rebalance of treasure values and density * Improve junction zones generation by spacing Monoliths @@ -859,11 +944,12 @@ * Fixed spawning of Armageddon's Blade and Vial of Dragon Blood on random maps ### Interface + * Right-clicking hero icon during levelup dialog will now show hero status window * Added indicator of current turn to unit turn order panel in battles * Reduces upscaling artifacts on large spellbook * Game will now display correct date of saved games on Android -* Fixed black screen appearing during spellbook page flip animation +* Fixed black screen appearing during spellbook page flip animation * Fixed description of "Start map with hero" bonus in campaigns * Fixed invisible chat text input in game lobby * Fixed positioning of chat history in game lobby @@ -871,6 +957,7 @@ * "Large Spellbook" option is now enabled by default ### Mechanics + * Anti-magic garrison now actually blocks spell casting * Berserk spell will no longer cancel if affected unit performs counterattack * Frenzy spell can no longer be casted on units that should be immune to it @@ -878,12 +965,14 @@ * Vitality and damage skills of a commander will now correctly grow with level ### Modding + * Added UNTIL_OWN_ATTACK duration type for bonuses * Configurable objects with visit mode "first" and "random" now respect "canRefuse" flag -# 1.4.0 -> 1.4.1 +## 1.4.0 -> 1.4.1 ### General + * Fixed position for interaction with starting heroes * Fixed smooth map scrolling when running at high framerate * Fixed calculation of Fire Shield damage when caster has artifacts that increase its damage @@ -900,15 +989,17 @@ * Reverted ban on U-turns in pathfinder ### Stability + * Fixed crash on using mods made for VCMI 1.3 * Fixed crash on generating random map with large number of monoliths * Fixed crash on losing mission-critical hero in battle * Fixed crash on generating growth detalization in some localizations * Fixed crash on loading of some user-made maps -# 1.3.2 -> 1.4.0 +## 1.3.2 -> 1.4.0 ### General + * Implemented High Score screen * Implemented tracking of completed campaigns * "Secret" Heroes 3 campaigns now require completion of prerequisite campaigns first @@ -932,6 +1023,7 @@ * Spectator mode in single player is now disabled ### Multiplayer + * Implemented simultaneous turns * Implemented turn timers, including chess timers version * Game will now hide entire adventure map on hotseat turn transfer @@ -941,10 +1033,12 @@ * Multiple fixes to validation of player requests by server ### Android + * Heroes 3 data import now accepts files in any case * Fixed detection of Heroes 3 data presence when 'data' directory uses lower case ### Touchscreen + * Added tutorial video clips that explain supported touch gestures * Double tap will now be correctly interpreted as double click, e.g. to start scenario via double-click * Implemented snapping to 100% scale for adventure map zooming @@ -953,6 +1047,7 @@ * Implemented radial wheel for hero exchange in towns ### Launcher + * When a mod is being downloaded, the launcher will now correctly show progress as well as its total size * Double-clicking mod name will now perform expected action, e.g. install/update/enable or disable * Launcher will now show mod extraction progress instead of freezing @@ -964,6 +1059,7 @@ * Added option to reconnect to game lobby ### Editor + * It is now possible to configure rewards for Seer Hut, Pandora Boxes and Events * It is now possible to configure quest (limiter) in Seer Hut and Quest Guards * It is now possible to configure events and rumors in map editor @@ -971,14 +1067,15 @@ * Added option to customize hero skills * It is now possible to select object on map for win/loss conditions or for main town * Random dwellings can now be linked to a random town -* Added map editor zoom -* Added objects lock functionality +* Added map editor zoom +* Added objects lock functionality * It is now possible to configure hero placeholders in map editor -* Fixed duplicate artifact image on mouse drag +* Fixed duplicate artifact image on mouse drag * Lasso tool will no longer skip tiles * Fixed layout of roads and rivers ### Stability + * Fix possible crash on generating random map * Fixed multiple memory leaks in game client * Fixed crash on casting Hypnotize multiple times @@ -987,6 +1084,7 @@ * Fixed crash on clicking on empty Altar of Sacrifice slots ### AI + * BattleAI should now see strong stacks even if blocked by weak stacks. * BattleAI will now prefers targets slower than own stack even if they are not reachable this turn. * Improved BattleAI performance when selecting spell to cast @@ -995,11 +1093,13 @@ * Nullkiller AI can now use Fly and Water Walk spells ### Campaigns + * Implemented voice-over audio support for Heroes 3 campaigns -* Fixes victory condition on 1st scenario of "Long Live the King" campaign +* Fixes victory condition on 1st scenario of "Long Live the King" campaign * Fixed loading of defeat/victory icon and message for some campaign scenarios ### Interface + * Implemented adventure map dimming on opening windows * Clicking town hall icon on town screen will now open town hall * Clicking buildings in town hall will now show which resources are missing (if any) @@ -1014,6 +1114,7 @@ * Attempting to recruit creature in town with no free slots in garrisons will now correctly show error message ### Main Menu + * Implemented window for quick selection of starting hero, town and bonus * Implemented map preview in scenario selection and game load screen accessible via right click on map * Show exact map size in map selection @@ -1029,6 +1130,7 @@ * Main menu animation will no longer appear on top of new game / load game text ### Adventure Map Interface + * Picking up an artifact on adventure map will now show artifact assembly dialog if such option exists * Minimap will now preserve correct aspect ratio on rectangular maps * Fixed slot highlighting when an artifact is being assembled @@ -1046,6 +1148,7 @@ * Right-clicking objects that give bonus to hero will show object description ### Mechanics + * Heroes in tavern will correctly lose effects from spells or visited objects on new day * Fixed multiple bugs in offering of Wisdom and Spell Schools on levelup. Mechanic should now work identically to Heroes 3 * Retreated heroes will no longer restore their entire mana pool on new day @@ -1053,7 +1156,7 @@ * Added support for repeatable quests in Seer Huts * Using "Sacrifice All" on Altar will now correctly place all creatures but one on altar * Fixed probabilities of luck and morale -* Blinded stack no longer can get morale +* Blinded stack no longer can get morale * Creature that attacks while standing in moat will now correctly receive moat damage * Player resources are now limited to 1 000 000 000 to prevent overflow * It is no longer possible to escape from town without fort @@ -1065,6 +1168,7 @@ * Gundula is now Offense specialist and not Sorcery, as in H3 ### Random Maps Generator + * Increased tolerance for placement of Subterranean Gates * Game will now select random object template out of available options instead of picking first one * It is no longer possible to create map with a single team @@ -1075,6 +1179,7 @@ * Fixed bug leading to AI players defeated on day one. ### Modding + * All bonuses now require string as a subtype. See documentation for exact list of possible strings for each bonus. * Changes to existing objects parameters in mods will now be applied to ongoing saves * Fixed handling of engine version compatibility check @@ -1095,9 +1200,10 @@ * Object limiter now allows checking whether hero can learn skill * Object reward may now reveal terrain around visiting hero (e.g. Redwood Observatory) -# 1.3.1 -> 1.3.2 +## 1.3.1 -> 1.3.2 ### GENERAL + * VCMI now uses new application icon * Added initial version of Czech translation * Game will now use tile hero is moving from for movement cost calculations, in line with H3 @@ -1109,6 +1215,7 @@ * Added "vcmiartifacts angelWings" form to "give artifacts" cheat ### STABILITY + * Fixed freeze in Launcher on repository checkout and on mod install * Fixed crash on loading VCMI map with placed Abandoned Mine * Fixed crash on loading VCMI map with neutral towns @@ -1117,9 +1224,11 @@ * Fixed crash on switching fullscreen mode during AI turn ### CAMPAIGNS + * Fixed reorderging of hero primary skills after moving to next scenario in campaigns ### BATTLES + * Conquering a town will now correctly award additional 500 experience points * Quick combat is now enabled by default * Fixed invisible creatures from SUMMON_GUARDIANS and TRANSMUTATION bonuses @@ -1132,6 +1241,7 @@ * Long tap during spell casting will now properly abort the spell ### INTERFACE + * Added "Fill all empty slots with 1 creature" option to radial wheel in garrison windows * Context popup for adventure map monsters will now show creature icon * Game will now show correct victory message for gather troops victory condition @@ -1149,17 +1259,20 @@ * Removed invalid error message on attempting to move non-existing unit in exchange window ### RANDOM MAP GENERATOR + * Fixed bug leading to unreachable resources around mines ### MAP EDITOR + * Fixed crash on maps containing abandoned mines * Fixed crash on maps containing neutral objects * Fixed problem with random map initialized in map editor * Fixed problem with initialization of random dwellings -# 1.3.0 -> 1.3.1 +## 1.3.0 -> 1.3.1 + +### GENERAL -### GENERAL: * Fixed framerate drops on hero movement with active hota mod * Fade-out animations will now be skipped when instant hero movement speed is used * Restarting loaded campaign scenario will now correctly reapply starting bonus @@ -1171,7 +1284,8 @@ * Added option to configure reserved screen area in Launcher on iOS * Fixed border scrolling when game window is maximized -### AI PLAYER: +### AI PLAYER + * BattleAI: Improved performance of AI spell selection * NKAI: Fixed freeze on attempt to exchange army between garrisoned and visiting hero * NKAI: Fixed town threat calculation @@ -1179,13 +1293,15 @@ * VCAI: Added workaround to avoid freeze on attempting to reach unreachable location * VCAI: Fixed spellcasting by Archangels -### RANDOM MAP GENERATOR: +### RANDOM MAP GENERATOR + * Fixed placement of roads inside rock in underground * Fixed placement of shifted creature animations from HotA * Fixed placement of treasures at the boundary of wide connections * Added more potential locations for quest artifacts in zone -### STABILITY: +### STABILITY + * When starting client without H3 data game will now show message instead of silently crashing * When starting invalid map in campaign, game will now show message instead of silently crashing * Blocked loading of saves made with different set of mods to prevent crashes @@ -1205,9 +1321,10 @@ * Fixed possible crash on displaying animated main menu * Fixed crash on recruiting hero in town located on the border of map -# 1.2.1 -> 1.3.0 +## 1.2.1 -> 1.3.0 + +### GENERAL -### GENERAL: * Implemented automatic interface scaling to any resolution supported by monitor * Implemented UI scaling option to scale game interface * Game resolution and UI scaling can now be changed without game restart @@ -1225,7 +1342,8 @@ * Fixed artifact lock icon in localized versions of the game * Fixed possible crash on changing hardware cursor -### TOUCHSCREEN SUPPORT: +### TOUCHSCREEN SUPPORT + * VCMI will now properly recognizes touch screen input * Implemented long tap gesture that shows popup window. Tap once more to close popup * Long tap gesture duration can now be configured in settings @@ -1236,7 +1354,8 @@ * Implemented pinch gesture for zooming adventure map * Implemented haptic feedback (vibration) for long press gesture -### LAUNCHER: +### LAUNCHER + * Launcher will now attempt to automatically detect language of OS on first launch * Added "About" tab with information about project and environment * Added separate options for Allied AI and Enemy AI for adventure map @@ -1244,14 +1363,16 @@ * Fixed potential crash on opening mod information for mods with a changelog * Added option to configure number of autosaves -### MAP EDITOR: +### MAP EDITOR + * Fixed crash on cutting random town * Added option to export entire map as an image * Added validation for placing multiple heroes into starting town * It is now possible to have single player on a map * It is now possible to configure teams in editor -### AI PLAYER: +### AI PLAYER + * Fixed potential crash on accessing market (VCAI) * Fixed potentially infinite turns (VCAI) * Reworked object prioritizing @@ -1260,6 +1381,7 @@ * Various behavior fixes ### GAME MECHANICS + * Hero retreating after end of 7th turn will now correctly appear in tavern * Implemented hero backpack limit (disabled by default) * Fixed Admiral's Hat movement points calculation @@ -1275,7 +1397,8 @@ * Rescued hero from prison will now correctly reveal map around him * Lighthouses will no longer give movement bonus on land -### CAMPAIGNS: +### CAMPAIGNS + * Fixed transfer of artifacts into next scenario * Fixed crash on advancing to next scenario with heroes from mods * Fixed handling of "Start with building" campaign bonus @@ -1285,7 +1408,8 @@ * Fixed frequent crash on moving to next scenario during campaign * Fixed inability to dismiss heroes on maps with "capture town" victory condition -### RANDOM MAP GENERATOR: +### RANDOM MAP GENERATOR + * Improved zone placement, shape and connections * Improved zone passability for better gameplay * Improved treasure distribution and treasure values to match SoD closely @@ -1300,7 +1424,8 @@ * RMG will now run faster, utilizing many CPU cores * Removed random seed number from random map description -### INTERFACE: +### INTERFACE + * Adventure map is now scalable and can be used with any resolution without mods * Adventure map interface is now correctly blocked during enemy turn * Visiting creature banks will now show amount of guards in bank @@ -1321,7 +1446,8 @@ * Right-clicking in town fort window will now show creature information popup * Implemented pasting from clipboard (Ctrl+V) for text input -### BATTLES: +### BATTLES + * Implemented Tower moat (Land Mines) * Implemented defence reduction for units in moat * Added option to always show hero status window @@ -1333,7 +1459,8 @@ * Added distinct overlay image for showing movement range of highlighted unit * Added overlay for displaying shooting range penalties of units -### MODDING: +### MODDING + * Implemented initial version of VCMI campaign format * Implemented spell cast as possible reward for configurable object * Implemented support for configurable buildings in towns @@ -1356,9 +1483,10 @@ * Configurable objects can now be translated * Fixed loading of custom battlefield identifiers for map objects -# 1.2.0 -> 1.2.1 +## 1.2.0 -> 1.2.1 + +### GENERAL -### GENERAL: * Implemented spell range overlay for Dimension Door and Scuttle Boat * Fixed movement cost penalty from terrain * Fixed empty Black Market on game start @@ -1379,9 +1507,10 @@ * Map editor will now correctly save message property for events and pandoras * Fixed incorrect saving of heroes portraits in editor -# 1.1.1 -> 1.2.0 +## 1.1.1 -> 1.2.0 + +### GENERAL -### GENERAL: * Adventure map rendering was entirely rewritten with better, more functional code * Client battle code was heavily reworked, leading to better visual look & feel and fixing multiple minor battle bugs / glitches * Client mechanics are now framerate-independent, rather than speeding up with higher framerate @@ -1392,7 +1521,7 @@ * Fixed bonus values of heroes who specialize in secondary skills * Fixed bonus values of heroes who specialize in creatures * Fixed damage increase from Adela's Bless specialty -* Fixed missing obstacles in battles on subterranean terrain +* Fixed missing obstacles in battles on subterranean terrain * Video files now play at correct speed * Fixed crash on switching to second mission in campaigns * New cheat code: vcmiazure - give 5000 azure dragons in every empty slot @@ -1408,14 +1537,16 @@ * Default game difficulty is now set to "normal" instead of "easy" * Fixed crash on missing music files -### MAP EDITOR: +### MAP EDITOR + * Added translations to German, Polish, Russian, Spanish, Ukrainian * Implemented cut/copy/paste operations * Implemented lasso brush for terrain editing * Toolbar actions now have names * Added basic victory and lose conditions -### LAUNCHER: +### LAUNCHER + * Added initial Welcome/Setup screen for new players * Added option to install translation mod if such mod exists and player's H3 version has different language * Icons now have higher resolution, to prevent upscaling artifacts @@ -1428,7 +1559,8 @@ * Launcher now uses separate mod repository from vcmi-1.1 version to prevent mod updates to unsupported versions * Size of mod list and mod details sub-windows can now be adjusted by player -### AI PLAYER: +### AI PLAYER + * Nullkiller AI is now used by default * AI should now be more active in destroying heroes causing treat on AI towns * AI now has higher priority for resource-producing mines @@ -1444,6 +1576,7 @@ * AI will consider retreat during siege if it can not do anything (catapult is destroyed, no destroyed walls exist) ### RANDOM MAP GENERATOR + * Random map generator can now be used without vcmi-extras mod * RMG will no longer place shipyards or boats at very small lakes * Fixed placement of shipyards in invalid locations @@ -1461,7 +1594,8 @@ * Fixed amount of creatures found in Pandora Boxes to match H3 * Visitable objects will no longer be placed on top of the map, obscured by map border -### ADVENTURE MAP: +### ADVENTURE MAP + * Added option to replace popup messages on object visiting with messages in status window * Implemented different hero movement sounds for offroad movement * Cartographers now reveal terrain in the same way as in H3 @@ -1486,6 +1620,7 @@ * Seer Hut tooltips will now show messages for correct quest type ### INTERFACE + * Implemented new settings window * Added framerate display option * Fixed white status bar on server connection screen @@ -1498,12 +1633,14 @@ * Implemented extended options for random map tab: generate G+U size, select RMG template, manage teams and roads ### HERO SCREEN + * Fixed cases of incorrect artifact slot highlighting * Improved performance of artifact exchange operation * Picking up composite artifact will immediately unlock slots * It is now possible to swap two composite artifacts ### TOWN SCREEN + * Fixed gradual fade-in of a newly built building * Fixed duration of building fade-in to match H3 * Fixed rendering of Shipyard in Castle @@ -1513,7 +1650,8 @@ * Fixed missing left-click message popup for some town buildings * Moving hero from garrison by pressing space will now correctly show message "Cannot have more than 8 adventuring heroes" -### BATTLES: +### BATTLES + * Added settings for even faster animation speed than in H3 * Added display of potential kills numbers into attack tooltip in status bar * Added option to skip battle opening music entirely @@ -1532,7 +1670,7 @@ * Arrow Tower base damage should now match H3 * Destruction of wall segments will now remove ranged attack penalty * Force Field cast in front of drawbridge will now block it as in H3 -* Fixed computations for Behemoth defense reduction ability +* Fixed computations for Behemoth defense reduction ability * Bad luck (if enabled) will now multiple all damage by 50%, in line with other damage reducing mechanics * Fixed highlighting of movement range for creatures standing on a corpse * All battle animations now have same duration/speed as in H3 @@ -1540,7 +1678,7 @@ * Fixed visibility of blue border around targeted creature when spellcaster is making turn * Fixed selection highlight when in targeted creature spellcasting mode * Hovering over hero now correctly shows hero cursor -* Creature currently making turn is now highlighted in the Battle Queue +* Creature currently making turn is now highlighted in the Battle Queue * Hovering over creature icon in Battle Queue will highlight this creature in the battlefield * New battle UI extension allows control over creatures' special abilities * Fixed crash on activating auto-combat in battle @@ -1549,7 +1687,8 @@ * Unicorn Magic Damper Aura ability now works multiplicatively with Resistance * Orb of Vulnerability will now negate Resistance skill -### SPELLS: +### SPELLS + * Hero casting animation will play before spell effect * Fire Shield: added sound effect * Fire Shield: effect now correctly plays on defending creature @@ -1570,7 +1709,8 @@ * All spells that can affecte multiple targets will now highlight affected stacks * Bless and Curse now provide +1 or -1 to base damage on Advanced & Expert levels -### ABILITIES: +### ABILITIES + * Rebirth (Phoenix): Sound will now play in the same time as animation effect * Master Genie spellcasting: Sound will now play in the same time as animation effect * Power Lich, Magogs: Sound will now play in the same time as attack animation effect @@ -1580,13 +1720,14 @@ * Blind: Stacks will no longer retaliate on attack that blinds them * Demon Summon: Added animation effect for summoning * Fire shield will no longer trigger on non-adjacent attacks, e.g. from Dragon Breath -* Weakness now has correct visual effect +* Weakness now has correct visual effect * Added damage bonus for opposite elements for Elementals * Added damage reduction for Magic Elemental attacks against creatures immune to magic * Added incoming damage reduction to Petrify * Added counter-attack damage reduction for Paralyze -### MODDING: +### MODDING + * All configurable objects from H3 now have their configuration in json * Improvements to functionality of configurable objects * Replaced `SECONDARY_SKILL_PREMY` bonus with separate bonuses for each skill. @@ -1607,10 +1748,11 @@ * It is now possible for spellcaster units to have multiple spells (but only for targeting different units) * Fixed incorrect resolving of identifiers in commander abilities and stack experience definitions -# 1.1.0 -> 1.1.1 +## 1.1.0 -> 1.1.1 -### GENERAL: -* Fixed missing sound in Polish version from gog.com +### GENERAL + +* Fixed missing sound in Polish version from gog.com * Fixed positioning of main menu buttons in localized versions of H3 * Fixed crash on transferring artifact to commander * Fixed game freeze on receiving multiple artifact assembly dialogs after combat @@ -1621,27 +1763,32 @@ * Improved map loading speed * Ubuntu PPA: game will no longer crash on assertion failure -### ADVENTURE MAP: +### ADVENTURE MAP + * Fixed hero movement lag in single-player games * Fixed number of drowned troops on visiting Sirens to match H3 * iOS: pinch gesture visits current object (Spacebar behavior) instead of activating in-game console -### TOWNS: +### TOWNS + * Fixed displaying growth bonus from Statue of Legion * Growth bonus tooltip ordering now matches H3 * Buy All Units dialog will now buy units starting from the highest level -### LAUNCHER: +### LAUNCHER + * Local mods can be disabled or uninstalled * Fixed styling of Launcher interface -### MAP EDITOR: +### MAP EDITOR + * Fixed saving of roads and rivers * Fixed placement of heroes on map -# 1.0.0 -> 1.1.0 +## 1.0.0 -> 1.1.0 + +### GENERAL -### GENERAL: * iOS is supported * Mods and their versions and serialized into save files. Game checks mod compatibility before loading * Logs are stored in system default logs directory @@ -1649,7 +1796,8 @@ * FFMpeg dependency is optional now * Conan package manager is supported for MacOS and iOS -### MULTIPLAYER: +### MULTIPLAYER + * Map is passed over network, so different platforms are compatible with each other * Server self-killing is more robust * Unlock in-game console while opponent's turn @@ -1658,7 +1806,8 @@ * Reconnection mode for crashed client processes * Playing online is available using proxy server -### ADVENTURE MAP: +### ADVENTURE MAP + * Fix for digging while opponent's turn * Supported right click for quick recruit window * Fixed problem with quests are requiring identical artefacts @@ -1667,27 +1816,31 @@ * Feature to assemble/disassemble artefacts in backpack * Clickable status bar to send messages * Heroes no longer have chance to receive forbidden skill on leveling up -* Fixed visibility of newly recruited heroes near town +* Fixed visibility of newly recruited heroes near town * Fixed missing artifact slot in Artifact Merchant window -### BATTLES: +### BATTLES + * Fix healing/regeneration behaviour and effect * Fix crashes related to auto battle * Implemented ray projectiles for shooters * Introduced default tower shooter icons * Towers destroyed during battle will no longer be listed as casualties -### AI: +### AI + * BattleAI: Target prioritizing is now based on damage difference instead of health difference * Nullkiller AI can retreat and surrender * Nullkiller AI doesn't visit allied dwellings anymore * Fixed a few freezes in Nullkiller AI -### RANDOM MAP GENERATOR: +### RANDOM MAP GENERATOR + * Speedup generation of random maps * Necromancy cannot be learned in Witch Hut on random maps -### MODS: +### MODS + * Supported rewardable objects customization * Battleground obstacles are extendable now with VLC mechanism * Introduced "compatibility" section into mods settings @@ -1695,19 +1848,22 @@ * Supported customisable town entrance placement * Fixed validation of mods with new adventure map objects -### LAUNCHER: +### LAUNCHER + * Fixed problem with duplicated mods in the list * Launcher shows compatible mods only * Uninstall button was moved to the left of layout * Unsupported resolutions are not shown * Lobby for online gameplay is implemented -### MAP EDITOR: +### MAP EDITOR + * Basic version of Qt-based map editor -# 0.99 -> 1.0.0 +## 0.99 -> 1.0.0 + +### GENERAL -### GENERAL: * Spectator mode was implemented through command-line options * Some main menu settings get saved after returning to main menu - last selected map, save etc. * Restart scenario button should work correctly now @@ -1715,30 +1871,33 @@ * Lodestar Grail implemented * Fixed Gargoyles immunity * New bonuses: - * SOUL_STEAL - "WoG ghost" ability, should work somewhat same as in H3 - * TRANSMUTATION - "WoG werewolf"-like ability - * SUMMON_GUARDIANS - "WoG santa gremlin"-like ability + two-hex unit extension - * CATAPULT_EXTRA_SHOTS - defines number of extra wall attacks for units that can do so - * RANGED_RETALIATION - allows ranged counterattack - * BLOCKS_RANGED_RETALIATION - disallow enemy ranged counterattack - * SECONDARY_SKILL_VAL2 - set additional parameter for certain secondary skills - * MANUAL_CONTROL - grant manual control over war machine - * WIDE_BREATH - melee creature attacks affect many nearby hexes - * FIRST_STRIKE - creature counterattacks before attack if possible - * SYNERGY_TARGET - placeholder bonus for Mod Design Team (subject to removal in future) - * SHOOTS_ALL_ADJACENT - makes creature shots affect all neighbouring hexes - * BLOCK_MAGIC_BELOW - allows blocking spells below particular spell level. HotA cape artifact can be implemented with this - * DESTRUCTION - creature ability for killing extra units after hit, configurable + * SOUL_STEAL - "WoG ghost" ability, should work somewhat same as in H3 + * TRANSMUTATION - "WoG werewolf"-like ability + * SUMMON_GUARDIANS - "WoG santa gremlin"-like ability + two-hex unit extension + * CATAPULT_EXTRA_SHOTS - defines number of extra wall attacks for units that can do so + * RANGED_RETALIATION - allows ranged counterattack + * BLOCKS_RANGED_RETALIATION - disallow enemy ranged counterattack + * SECONDARY_SKILL_VAL2 - set additional parameter for certain secondary skills + * MANUAL_CONTROL - grant manual control over war machine + * WIDE_BREATH - melee creature attacks affect many nearby hexes + * FIRST_STRIKE - creature counterattacks before attack if possible + * SYNERGY_TARGET - placeholder bonus for Mod Design Team (subject to removal in future) + * SHOOTS_ALL_ADJACENT - makes creature shots affect all neighbouring hexes + * BLOCK_MAGIC_BELOW - allows blocking spells below particular spell level. HotA cape artifact can be implemented with this + * DESTRUCTION - creature ability for killing extra units after hit, configurable + +### MULTIPLAYER -### MULTIPLAYER: * Loading support. Save from single client could be used to load all clients. * Restart support. All clients will restart together on same server. * Hotseat mixed with network game. Multiple colors can be controlled by each client. -### SPELLS: +### SPELLS + * Implemented cumulative effects for spells -### MODS: +### MODS + * Improve support for WoG commander artifacts and skill descriptions * Added support for modding of original secondary skills and creation of new ones. * Map object sounds can now be configured via json @@ -1747,19 +1906,21 @@ * Added bonus limiters: alignment, faction and terrain * Supported new terrains, new battlefields, custom water and rock terrains * Following special buildings becomes available in the fan towns: - * attackVisitingBonus - * defenceVisitingBonus - * spellPowerVisitingBonus - * knowledgeVisitingBonus - * experienceVisitingBonus - * lighthouse - * treasury + * attackVisitingBonus + * defenceVisitingBonus + * spellPowerVisitingBonus + * knowledgeVisitingBonus + * experienceVisitingBonus + * lighthouse + * treasury + +### SOUND -### SOUND: * Fixed many missing or wrong pickup and visit sounds for map objects * All map objects now have ambient sounds identical to OH3 -### RANDOM MAP GENERATOR: +### RANDOM MAP GENERATOR + * Random map generator supports water modes (normal, islands) * Added config randomMap.json with settings for map generator * Added parameter for template allowedWaterContent @@ -1770,7 +1931,8 @@ * RMG works more stable, various crashes have been fixed * Treasures requiring guards are guaranteed to be protected -### VCAI: +### VCAI + * Reworked goal decomposition engine, fixing many loopholes. AI will now pick correct goals faster. * AI will now use universal pathfinding globally * AI can use Summon Boat and Town Portal @@ -1779,50 +1941,57 @@ * AI can distinguish the value of all map objects * General speed optimizations -### BATTLES: +### BATTLES + * Towers should block ranged retaliation * AI can bypass broken wall with moat instead of standing and waiting until gate is destroyed * Towers do not attack war machines automatically * Draw is possible now as battle outcome in case the battle ends with only summoned creatures (both sides loose) -### ADVENTURE MAP: +### ADVENTURE MAP + * Added buttons and keyboard shortcuts to quickly exchange army and artifacts between heroes * Fix: Captured town should not be duplicated on the UI -### LAUNCHER: +### LAUNCHER + * Implemented notifications about updates * Supported redirection links for downloading mods -# 0.98 -> 0.99 +## 0.98 -> 0.99 + +### GENERAL -### GENERAL: * New Bonus NO_TERRAIN_PENALTY * Nomads will remove Sand movement penalty from army * Flying and water walking is now supported in pathfinder * New artifacts supported - * Angel Wings - * Boots of Levitation + * Angel Wings + * Boots of Levitation * Implemented rumors in tavern window * New cheat codes: - * vcmiglaurung - gives 5000 crystal dragons into each slot - * vcmiungoliant - conceal fog of war for current player + * vcmiglaurung - gives 5000 crystal dragons into each slot + * vcmiungoliant - conceal fog of war for current player * New console commands: - * gosolo - AI take control over human players and vice versa - * controlai - give control of one or all AIs to player - * set hideSystemMessages on/off - suppress server messages in chat + * gosolo - AI take control over human players and vice versa + * controlai - give control of one or all AIs to player + * set hideSystemMessages on/off - suppress server messages in chat + +### BATTLES -### BATTLES: * Drawbridge mechanics implemented (animation still missing) * Merging of town and visiting hero armies on siege implemented * Hero info tooltip for skills and mana implemented -### ADVENTURE AI: +### ADVENTURE AI + * Fixed AI trying to go through underground rock * Fixed several cases causing AI wandering aimlessly * AI can again pick best artifacts and exchange artifacts between heroes * AI heroes with patrol enabled won't leave patrol area anymore -### RANDOM MAP GENERATOR: +### RANDOM MAP GENERATOR + * Changed fractalization algorithm so it can create cycles * Zones will not have straight paths anymore, they are totally random * Generated zones will have different size depending on template setting @@ -1830,94 +1999,112 @@ * Added Seer Huts with quests that match OH3 * RMG will guarantee at least 100 pairs of Monoliths are available even if there are not enough different defs -# 0.97 -> 0.98 +## 0.97 -> 0.98 + +### GENERAL -### GENERAL: * Pathfinder can now find way using Monoliths and Whirlpools (only used if hero has protection) -### ADVENTURE AI: +### ADVENTURE AI + * AI will try to use Monolith entrances for exploration * AI will now always revisit each exit of two way monolith if exit no longer visible * AI will eagerly pick guarded and blocked treasures -### ADVENTURE MAP: +### ADVENTURE MAP + * Implemented world view * Added graphical fading effects -### SPELLS: +### SPELLS + * New spells handled: - * Earthquake - * View Air - * View Earth - * Visions - * Disguise + * Earthquake + * View Air + * View Earth + * Visions + * Disguise * Implemented CURE spell negative dispel effect * Added LOCATION target for spells castable on any hex with new target modifiers -### BATTLES: +### BATTLES + * Implemented OH3 stack split / upgrade formulas according to AlexSpl -### RANDOM MAP GENERATOR: +### RANDOM MAP GENERATOR + * Underground tunnels are working now * Implemented "junction" zone type * Improved zone placing algorithm * More balanced distribution of treasure piles * More obstacles within zones -# 0.96 -> 0.97 (Nov 01 2014) +## 0.96 -> 0.97 (Nov 01 2014) + +### GENERAL -### GENERAL: * (windows) Moved VCMI data directory from '%userprofile%\vcmi' to '%userprofile%\Documents\My Games\vcmi' * (windows) (OSX) Moved VCMI save directory from 'VCMI_DATA\Games' to 'VCMI_DATA\Saves' * (linux) * Changes in used librries: - * VCMI can now be compiled with SDL2 - * Movies will use ffmpeg library - * change boost::bind to std::bind - * removed boost::assign - * Updated FuzzyLite to 5.0 + * VCMI can now be compiled with SDL2 + * Movies will use ffmpeg library + * change boost::bind to std::bind + * removed boost::assign + * Updated FuzzyLite to 5.0 * Multiplayer load support was implemented through command-line options -### ADVENTURE AI: +### ADVENTURE AI + * Significantly optimized execution time, AI should be much faster now. -### ADVENTURE MAP: +### ADVENTURE MAP + * Non-latin characters can now be entered in chat window or used for save names. * Implemented separate speed for owned heroes and heroes owned by other players -### GRAPHICS: +### GRAPHICS + * Better upscaling when running in fullscreen mode. * New creature/commader window * New resolutions and bonus icons are now part of a separate mod * Added graphics for GENERAL_DAMAGE_REDUCTION bonus (Kuririn) -### RANDOM MAP GENERATOR: +### RANDOM MAP GENERATOR + * Random map generator now creates complete and playable maps, should match original RMG * All important features from original map templates are implemented * Fixed major crash on removing objects * Undeground zones will look just like surface zones -### LAUNCHER: +### LAUNCHER + * Implemented switch to disable intro movies in game -# 0.95 -> 0.96 (Jul 01 2014) +## 0.95 -> 0.96 (Jul 01 2014) -### GENERAL: -* (linux) now VCMI follows XDG specifications. See http://forum.vcmi.eu/viewtopic.php?t=858 +### GENERAL + +* (linux) now VCMI follows XDG specifications. See + +### ADVENTURE AI -### ADVENTURE AI: * Optimized speed and removed various bottlenecks. -### ADVENTURE MAP: +### ADVENTURE MAP + * Heroes auto-level primary and secondary skill levels according to experience -### BATTLES: +### BATTLES + * Wall hit/miss sound will be played when using catapult during siege -### SPELLS: +### SPELLS + * New configuration format -### RANDOM MAP GENERATOR: +### RANDOM MAP GENERATOR + * Towns from mods can be used * Reading connections, terrains, towns and mines from template * Zone placement @@ -1925,31 +2112,35 @@ * Guard generation * Treasure piles generation (so far only few removable objects) -### MODS: +### MODS + * Support for submods - mod may have their own "submods" located in /Mods directory * Mods may provide their own changelogs and screenshots that will be visible in Launcher * Mods can now add new (offensive, buffs, debuffs) spells and change existing * Mods can use custom mage guild background pictures and videos for taverns, setting of resources daily income for buildings -### GENERAL: +### GENERAL + * Added configuring of heroes quantity per player allowed in game -# 0.94 -> 0.95 (Mar 01 2014) +## 0.94 -> 0.95 (Mar 01 2014) + +### GENERAL -### GENERAL: * Components of combined artifacts will now display info about entire set. * Implements level limit * Added WoG creature abilities by Kuririn -* Implemented a confirmation dialog when pressing Alt + F4 to quit the game +* Implemented a confirmation dialog when pressing Alt + F4 to quit the game * Added precompiled header compilation for CMake (can be enabled per flag) * VCMI will detect changes in text files using crc-32 checksum * Basic support for unicode. Internally vcmi always uses utf-8 * (linux) Launcher will be available as "VCMI" menu entry from system menu/launcher * (linux) Added a SIGSEV violation handler to vcmiserver executable for logging stacktrace (for convenience) -### ADVENTURE AI: +### ADVENTURE AI + * AI will use fuzzy logic to compare and choose multiple possible subgoals. -* AI will now use SectorMap to find a way to guarded / covered objects. +* AI will now use SectorMap to find a way to guarded / covered objects. * Significantly improved exploration algorithm. * Locked heroes now try to decompose their goals exhaustively. * Fixed (common) issue when AI found neutral stacks infinitely strong. @@ -1958,26 +2149,30 @@ * AI should now conquer map more aggressively and much faster * Fuzzy rules will be printed out at map launch (if AI log is enabled) -### CAMPAIGNS: +### CAMPAIGNS + * Implemented move heroes to next scenario * Support for non-standard victory conditions for H3 campaigns * Campaigns use window with bonus & scenario selection than scenario information window from normal maps * Implemented hero recreate handling (e.g. Xeron will be recreated on AB campaign) * Moved place bonus hero before normal random hero and starting hero placement -> same behaviour as in OH3 -* Moved placing campaign heroes before random object generation -> same behaviour as in OH3 +* Moved placing campaign heroes before random object generation -> same behaviour as in OH3 + +### TOWNS -### TOWNS: * Extended building dependencies support -### MODS: +### MODS + * Custom victory/loss conditions for maps or campaigns * 7 days without towns loss condition is no longer hardcoded * Only changed mods will be validated -# 0.93 -> 0.94 (Oct 01 2013) +## 0.93 -> 0.94 (Oct 01 2013) -### GENERAL: -* New Launcher application, see +### GENERAL + +* New Launcher application, see * Filesystem now supports zip archives. They can be loaded similarly to other archives in filesystem.json. Mods can use Content.zip instead of Content/ directory. * fixed "get txt" console command * command "extract" to extract file by name @@ -1988,12 +2183,14 @@ * Upgrade cost will never be negative. * support for Chinese fonts (GBK 2-byte encoding) -### ADVENTURE MAP: +### ADVENTURE MAP + * if Quick Combat option is turned on, battles will be resolved by AI * first hero is awakened on new turn * fixed 3000 gems reward in shipwreck -### BATTLES: +### BATTLES + * autofight implemented * most of the animations is time-based * simplified postioning of units in battle, should fix remaining issues with unit positioning @@ -2012,13 +2209,15 @@ * damage done by turrets is properly increased by built buldings * Wyverns will cast Poison instead of Stone Gaze. -### TOWN: +### TOWN + * Fixed issue that allowed to build multiple boats in town. * fix for lookout tower -# 0.92 -> 0.93 (Jun 01 2013) +## 0.92 -> 0.93 (Jun 01 2013) + +### GENERAL -### GENERAL: * Support for SoD-only installations, WoG becomes optional addition * New logging framework * Negative luck support, disabled by default @@ -2026,7 +2225,8 @@ * Fixed stack artifact (and related buttons) not displaying in creature window. * Fixed crash at month of double population. -### MODS: +### MODS + * Improved json validation. Now it support most of features from latest json schema draft. * Icons use path to icon instead of image indexes. * It is possible to edit data of another mod or H3 data via mods. @@ -2034,7 +2234,8 @@ * Removed no longer needed field "projectile spins" * Heroes: split heroes.json in manner similar to creatures\factions; string ID's for H3 heroes; h3 hero classes and artifacts can be modified via json. -### BATTLES: +### BATTLES + * Fixed Death Stare of Commanders * Projectile blitting should be closer to original H3. But still not perfect. * Fixed missing Mirth effects @@ -2043,34 +2244,39 @@ * Fixed abilities of Efreet. * Fixed broken again palette in some battle backgrounds -### TOWN: +### TOWN + * VCMI will not crash if building selection area is smaller than def * Detection of transparency on selection area is closer to H3 * Improved handling buildings with mode "auto": - * they will be properly processed (new creatures will be added if dwelling, spells learned if mage guild, and so on) - * transitive dependencies are handled (A makes B build, and B makes C and D) + * they will be properly processed (new creatures will be added if dwelling, spells learned if mage guild, and so on) + * transitive dependencies are handled (A makes B build, and B makes C and D) + +### SOUND -### SOUND: * Added missing WoG creature sounds (from Kuririn). * The Windows package comes with DLLs needed to play .ogg files * (linux) convertMP3 option for vcmibuilder for systems where SDL_Mixer can't play mp3's * some missing sounds for battle effects -### ARTIFACTS: +### ARTIFACTS + * Several fixes to combined artifacts added via mods. * Fixed Spellbinder's Hat giving level 1 spells instead of 5. * Fixed incorrect components of Cornucopia. * Cheat code with grant all artifacts, including the ones added by mods -# 0.91 -> 0.92 (Mar 01 2013) +## 0.91 -> 0.92 (Mar 01 2013) + +### GENERAL -### GENERAL: * hero crossover between missions in campaigns * introduction before missions in campaigns -### MODS: +### MODS + * Added CREATURE_SPELL_POWER for commanders -* Added spell modifiers to various spells: Hypnotize (Astral), Firewall (Luna), Landmine +* Added spell modifiers to various spells: Hypnotize (Astral), Firewall (Luna), Landmine * Fixed ENEMY_DEFENCE_REDUCTION, GENERAL_ATTACK_REDUCTION * Extended usefulness of ONLY_DISTANCE_FIGHT, ONLY_MELEE_FIGHT ranges * Double growth creatures are configurable now @@ -2078,55 +2284,61 @@ * Stack can use more than 2 attacks. Additional attacks can now be separated as "ONLY_MELEE_FIGHT and "ONLY_DISTANCE_FIGHT". * Moat damage configurable * More config options for spells: - * mind immunity handled by config - * direct damage immunity handled by config - * immunity icon configurable - * removed mind_spell flag -* creature config use string ids now. + * mind immunity handled by config + * direct damage immunity handled by config + * immunity icon configurable + * removed mind_spell flag +* creature config use string ids now. * support for string subtype id in short bonus format * primary skill identifiers for bonuses -# 0.9 -> 0.91 (Feb 01 2013) +## 0.9 -> 0.91 (Feb 01 2013) + +### GENERAL -### GENERAL: * VCMI build on OS X is now supported * Completely removed autotools * Added RMG interace and ability to generate simplest working maps * Added loading screen -### MODS: +### MODS + * Simplified mod structure. Mods from 0.9 will not be compatible. * Mods can be turned on and off in config/modSettings.json file * Support for new factions, including: - * New towns - * New hero classes - * New heroes - * New town-related external dwellings + * New towns + * New hero classes + * New heroes + * New town-related external dwellings * Support for new artifact, including combined, commander and stack artifacts * Extended configuration options - * All game objects are referenced by string identifiers - * Subtype resolution for bonuses + * All game objects are referenced by string identifiers + * Subtype resolution for bonuses + +### BATTLES -### BATTLES: * Support for "enchanted" WoG ability -### ADVENTURE AI: +### ADVENTURE AI + * AI will try to use Subterranean Gate, Redwood Observatory and Cartographer for exploration * Improved exploration algorithm * AI will prioritize dwellings and mines when there are no opponents visible -# 0.89 -> 0.9 (Oct 01 2012) +## 0.89 -> 0.9 (Oct 01 2012) + +### GENERAL -### GENERAL: * Provisional support creature-adding mods * New filesystem allowing easier resource adding/replacing * Reorganized package for better compatibility with HotA and not affecting the original game * Moved many hard-coded settings into text config files * Commander level-up dialog * New Quest Log window -* Fixed a number of bugs in campaigns, support for starting hero selection bonus. +* Fixed a number of bugs in campaigns, support for starting hero selection bonus. + +### BATTLES -### BATTLES: * New graphics for Stack Queue * Death Stare works identically to H3 * No explosion when catapult fails to damage the wall @@ -2134,9 +2346,10 @@ * Fixed crash when attacking stack dies in the Moat just before the attack * Fixed Orb of Inhibition and Recanter's Cloak (they were incorrectly implemented) * Fleeing hero won't lose artifacts. -* Spellbook won't be captured. +* Spellbook won't be captured. + +### ADVENTURE AI -### ADVENTURE AI: * support for quests (Seer Huts, Quest Guardians, and so) * AI will now wander with all the heroes that have spare movement points. It should prevent stalling. * AI will now understand threat of Abandoned Mine. @@ -2146,13 +2359,15 @@ * Fixed crash when hero assigned to goal was lost when attempting realizing it * Fixed a possible freeze when exchanging resources at marketplace -### BATTLE AI: +### BATTLE AI + * It is possible to select a battle AI module used by VCMI by typing into the console "setBattleAI ". The names of available modules are "StupidAI" and "BattleAI". BattleAI may be a little smarter but less stable. By the default, StupidAI will be used, as in previous releases. * New battle AI module: "BattleAI" that is smarter and capable of casting some offensive and enchantment spells -# 0.88 -> 0.89 (Jun 01 2012) +## 0.88 -> 0.89 (Jun 01 2012) + +### GENERAL -### GENERAL: * Mostly implemented Commanders feature (missing level-up dialog) * Support for stack artifacts * New creature window graphics contributed by fishkebab @@ -2164,11 +2379,13 @@ * Simple mechanism for detecting game desynchronization after init * 1280x800 resolution graphics, contributed by Topas -### ADVENTURE MAP: +### ADVENTURE MAP + * Fixed monsters regenerating casualties from battle at the start of new week. * T in adventure map will switch to next town -### BATTLES: +### BATTLES + * It's possible to switch active creature during tacts phase by clicking on stack * After battle artifacts of the defeated hero (and his army) will be taken by winner * Rewritten handling of battle obstacles. They will be now placed following H3 algorithm. @@ -2185,22 +2402,25 @@ * Fixed and simplified Teleport casting * Fixed Remove Obstacle spell * New spells supported: - * Chain Lightning - * Fire Wall - * Force Field - * Land Mine - * Quicksands - * Sacrifice + * Chain Lightning + * Fire Wall + * Force Field + * Land Mine + * Quicksands + * Sacrifice + +### TOWNS -### TOWNS: * T in castle window will open a tavern window (if available) -### PREGAME: +### PREGAME + * Pregame will use same resolution as main game * Support for scaling background image * Customization of graphics with config file. -### ADVENTURE AI: +### ADVENTURE AI + * basic rule system for threat evaluation * new town development logic * AI can now use external dwellings @@ -2209,7 +2429,7 @@ * AI will recruit multiple heroes for exploration * AI won't try attacking its own heroes -# 0.87 -> 0.88 (Mar 01 2012) +## 0.87 -> 0.88 (Mar 01 2012) * added an initial version of new adventure AI: VCAI * system settings window allows to change default resolution @@ -2218,202 +2438,226 @@ * Creature Window can handle descriptions of spellcasting abilities * Support for the clone spell -# 0.86 -> 0.87 (Dec 01 2011) +## 0.86 -> 0.87 (Dec 01 2011) + +### GENERAL -### GENERAL: * Pathfinder can find way using ships and subterranean gates * Hero reminder & sleep button -### PREGAME: +### PREGAME + * Credits are implemented -### BATTLES: +### BATTLES + * All attacked hexes will be highlighted * New combat abilities supported: - * Spell Resistance aura - * Random spellcaster (Genies) - * Mana channeling - * Daemon summoning - * Spellcaster (Archangel Ogre Mage, Elementals, Faerie Dragon) - * Fear - * Fearless - * No wall penalty - * Enchanter - * Bind - * Dispel helpful spells + * Spell Resistance aura + * Random spellcaster (Genies) + * Mana channeling + * Daemon summoning + * Spellcaster (Archangel Ogre Mage, Elementals, Faerie Dragon) + * Fear + * Fearless + * No wall penalty + * Enchanter + * Bind + * Dispel helpful spells -# 0.85 -> 0.86 (Sep 01 2011) +## 0.85 -> 0.86 (Sep 01 2011) + +### GENERAL -### GENERAL: * Reinstated music support * Bonus system optimizations (caching) * converted many config files to JSON * .tga file support * New artifacts supported - * Admiral's Hat - * Statue of Legion - * Titan's Thunder + * Admiral's Hat + * Statue of Legion + * Titan's Thunder + +### BATTLES -### BATTLES: * Correct handling of siege obstacles * Catapult animation * New combat abilities supported - * Dragon Breath - * Three-headed Attack - * Attack all around - * Death Cloud / Fireball area attack - * Death Blow - * Lightning Strike - * Rebirth + * Dragon Breath + * Three-headed Attack + * Attack all around + * Death Cloud / Fireball area attack + * Death Blow + * Lightning Strike + * Rebirth * New WoG abilities supported - * Defense Bonus - * Cast before attack - * Immunity to direct damage spells + * Defense Bonus + * Cast before attack + * Immunity to direct damage spells * New spells supported - * Magic Mirror - * Titan's Lightning Bolt + * Magic Mirror + * Titan's Lightning Bolt -# 0.84 -> 0.85 (Jun 01 2011) +## 0.84 -> 0.85 (Jun 01 2011) + +### GENERAL -### GENERAL: * Support for stack experience * Implemented original campaign selection screens * New artifacts supported: - * Statesman's Medal - * Diplomat's Ring - * Ambassador's Sash + * Statesman's Medal + * Diplomat's Ring + * Ambassador's Sash + +### TOWNS -### TOWNS: * Implemented animation for new town buildings * It's possible to sell artifacts at Artifact Merchants -### BATTLES: +### BATTLES + * Neutral monsters will be split into multiple stacks * Hero can surrender battle to keep army * Support for Death Stare, Support for Poison, Age, Disease, Acid Breath, Fire / Water / Earth / Air immunities and Receptiveness * Partial support for Stone Gaze, Paralyze, Mana drain -# 0.83 -> 0.84 (Mar 01 2011) +## 0.83 -> 0.84 (Mar 01 2011) + +### GENERAL -### GENERAL: * Bonus system has been rewritten * Partial support for running VCMI in duel mode (no adventure map, only one battle, ATM only AI-AI battles) * New artifacts supported: - * Angellic Alliance - * Bird of Perception - * Emblem of Cognizance - * Spell Scroll - * Stoic Watchman + * Angellic Alliance + * Bird of Perception + * Emblem of Cognizance + * Spell Scroll + * Stoic Watchman + +### BATTLES -### BATTLES: * Better animations handling * Defensive stance is supported -### HERO: -* New secondary skills supported: - * Artillery - * Eagle Eye - * Tactics +### HERO + +* New secondary skills supported: + * Artillery + * Eagle Eye + * Tactics + +### AI PLAYER -### AI PLAYER: * new AI leading neutral creatures in combat, slightly better then previous -# 0.82 -> 0.83 (Nov 01 2010) +## 0.82 -> 0.83 (Nov 01 2010) + +### GENERAL -### GENERAL: * Alliances support * Week of / Month of events * Mostly done pregame for MP games (temporarily only for local clients) * Support for 16bpp displays * Campaigns: - * support for building bonus - * moving to next map after victory + * support for building bonus + * moving to next map after victory * Town Portal supported * Vial of Dragon Blood and Statue of Legion supported -### HERO: +### HERO + * remaining specialities have been implemented -### TOWNS: -* town events supported -* Support for new town structures: Deiety of Fire and Escape Tunnel +### TOWNS + +* town events supported +* Support for new town structures: Deiety of Fire and Escape Tunnel + +### BATTLES -### BATTLES: * blocked retreating from castle -# 0.81 -> 0.82 (Aug 01 2010) +## 0.81 -> 0.82 (Aug 01 2010) + +### GENERAL -### GENERAL: * Some of the starting bonuses in campaigns are supported * It's possible to select difficulty level of mission in campaign * new cheat codes: - * vcmisilmaril - player wins - * vcmimelkor - player loses + * vcmisilmaril - player wins + * vcmimelkor - player loses + +### ADVENTURE MAP -### ADVENTURE MAP: * Neutral armies growth implemented (10% weekly) * Power rating of neutral stacks * Favourable Winds reduce sailing cost -### HERO: +### HERO + * Learning secondary skill supported. * Most of hero specialities are supported, including: - * Creature specialities (progressive, fixed, Sir Mullich) - * Spell damage specialities (Deemer), fixed bonus (Ciele) - * Secondary skill bonuses - * Creature Upgrades (Gelu) - * Resource generation - * Starting Skill (Adrienne) + * Creature specialities (progressive, fixed, Sir Mullich) + * Spell damage specialities (Deemer), fixed bonus (Ciele) + * Secondary skill bonuses + * Creature Upgrades (Gelu) + * Resource generation + * Starting Skill (Adrienne) + +### TOWNS -### TOWNS: * Support for new town structures: - * Artifact Merchant - * Aurora Borealis - * Castle Gates - * Magic University - * Portal of Summoning - * Skeleton transformer - * Veil of Darkness + * Artifact Merchant + * Aurora Borealis + * Castle Gates + * Magic University + * Portal of Summoning + * Skeleton transformer + * Veil of Darkness + +### OBJECTS -### OBJECTS: * Stables will now upgrade Cavaliers to Champions. * New object supported: - * Abandoned Mine - * Altar of Sacrifice - * Black Market - * Cover of Darkness - * Hill Fort - * Refugee Camp - * Sanctuary - * Tavern - * University - * Whirlpool + * Abandoned Mine + * Altar of Sacrifice + * Black Market + * Cover of Darkness + * Hill Fort + * Refugee Camp + * Sanctuary + * Tavern + * University + * Whirlpool -# 0.8 -> 0.81 (Jun 01 2010) +## 0.8 -> 0.81 (Jun 01 2010) + +### GENERAL -### GENERAL: * It's possible to start campaign * Support for build grail victory condition * New artifacts supported: - * Angel's Wings - * Boots of levitation - * Orb of Vulnerability - * Ammo cart - * Golden Bow - * Hourglass of Evil Hour - * Bow of Sharpshooter - * Armor of the Damned + * Angel's Wings + * Boots of levitation + * Orb of Vulnerability + * Ammo cart + * Golden Bow + * Hourglass of Evil Hour + * Bow of Sharpshooter + * Armor of the Damned + +### ADVENTURE MAP -### ADVENTURE MAP: * Creatures now guard surrounding tiles * New adventura map spells supported: - * Summon Boat - * Scuttle Boat - * Dimension Door - * Fly - * Water walk + * Summon Boat + * Scuttle Boat + * Dimension Door + * Fly + * Water walk + +### BATTLES -### BATTLES: * A number of new creature abilities supported * First Aid Tent is functional * Support for distance/wall/melee penalties & no * penalty abilities @@ -2421,107 +2665,123 @@ * Luck support * Teleportation spell -### HERO: +### HERO + * First Aid secondary skill * Improved formula for necromancy to match better OH3 -### TOWNS: +### TOWNS + * Sending resources to other players by marketplace * Support for new town structures: - * Lighthouse - * Colossus - * Freelancer's Guild - * Guardian Spirit - * Necromancy Amplifier - * Soul Prison + * Lighthouse + * Colossus + * Freelancer's Guild + * Guardian Spirit + * Necromancy Amplifier + * Soul Prison + +### OBJECTS -### OBJECTS: * New object supported: - * Freelancer's Guild - * Trading Post - * War Machine Factory + * Freelancer's Guild + * Trading Post + * War Machine Factory -# 0.75 -> 0.8 (Mar 01 2010) +## 0.75 -> 0.8 (Mar 01 2010) + +### GENERAL -### GENERAL: * Victory and loss conditions are supported. It's now possible to win or lose the game. * Implemented assembling and disassembling of combination artifacts. * Kingdom Overview screen is now available. * Implemented Grail (puzzle map, digging, constructing ultimate building) * Replaced TTF fonts with original ones. -### ADVENTURE MAP: +### ADVENTURE MAP + * Implemented rivers animations (thx to GrayFace). -### BATTLES: +### BATTLES + * Fire Shield spell (and creature ability) supported * affecting morale/luck and casting spell after attack creature abilities supported -### HERO: +### HERO + * Implementation of Scholar secondary skill -### TOWN: +### TOWN + * New left-bottom info panel functionalities. -### TOWNS: -* new town structures supported: - * Ballista Yard - * Blood Obelisk - * Brimstone Clouds - * Dwarven Treasury - * Fountain of Fortune - * Glyphs of Fear - * Mystic Pond - * Thieves Guild - * Special Grail functionalities for Dungeon, Stronghold and Fortress +### TOWNS + +* new town structures supported: + * Ballista Yard + * Blood Obelisk + * Brimstone Clouds + * Dwarven Treasury + * Fountain of Fortune + * Glyphs of Fear + * Mystic Pond + * Thieves Guild + * Special Grail functionalities for Dungeon, Stronghold and Fortress + +### OBJECTS -### OBJECTS: * New objects supported: - * Border gate - * Den of Thieves - * Lighthouse - * Obelisk - * Quest Guard - * Seer hut + * Border gate + * Den of Thieves + * Lighthouse + * Obelisk + * Quest Guard + * Seer hut A lot of of various bugfixes and improvements: -http://bugs.vcmi.eu/changelog_page.php?version_id=14 + -# 0.74 -> 0.75 (Dec 01 2009) +## 0.74 -> 0.75 (Dec 01 2009) + +### GENERAL -### GENERAL: * Implemented "main menu" in-game option. * Hide the mouse cursor while displaying a popup window. * Better handling of huge and empty message boxes (still needs more changes) * Fixed several crashes when exiting. -### ADVENTURE INTERFACE: +### ADVENTURE INTERFACE + * Movement cursor shown for unguarded enemy towns. * Battle cursor shown for guarded enemy garrisons. * Clicking on the border no longer opens an empty info windows -### HERO WINDOW: -* Improved artifact moving. Available slots are highlighted. Moved artifact is bound to mouse cursor. +### HERO WINDOW + +* Improved artifact moving. Available slots are highlighted. Moved artifact is bound to mouse cursor. + +### TOWNS -### TOWNS: * new special town structures supported: - * Academy of Battle Scholars - * Cage of Warlords - * Mana Vortex - * Stables - * Skyship (revealing entire map only) + * Academy of Battle Scholars + * Cage of Warlords + * Mana Vortex + * Stables + * Skyship (revealing entire map only) + +### OBJECTS -### OBJECTS: * External dwellings increase town growth * Right-click info window for castles and garrisons you do not own shows a rough amount of creatures instead of none * Scholar won't give unavailable spells anymore. A lot of of various bugfixes and improvements: -http://bugs.vcmi.eu/changelog_page.php?version_id=2 + -# 0.73 -> 0.74 (Oct 01 2009) +## 0.73 -> 0.74 (Oct 01 2009) + +### GENERAL -### GENERAL: * Scenario Information window * Save Game window * VCMI window should start centered @@ -2533,13 +2793,15 @@ http://bugs.vcmi.eu/changelog_page.php?version_id=2 * fixed issue when splitting stack to the hero with only one creatures * a few fixes for shipyard window -### ADVENTURE INTERFACE: +### ADVENTURE INTERFACE + * Cursor shows if tile is accessible and how many turns away * moving hero with arrow keys / numpad * fixed Next Hero button behaviour * fixed Surface/Underground switch button in higher resolutions -### BATTLES: +### BATTLES + * partial siege support * new stack queue for higher resolutions (graphics made by Dru, thx!) * 'Q' pressing toggles the stack queue displaying (so it can be enabled/disabled it with single key press) @@ -2549,72 +2811,77 @@ http://bugs.vcmi.eu/changelog_page.php?version_id=2 * fixed crash when clicking on enemy stack without moving mouse just after receiving action * even large stack numbers will fit the boxes * when active stack is killed by spell, game behaves properly -* shooters attacking twice (like Grand Elves) won't attack twice in melee -* ballista can shoot even if there's an enemy creature next to it +* shooters attacking twice (like Grand Elves) won't attack twice in melee +* ballista can shoot even if there's an enemy creature next to it * improved obstacles placement, so they'll better fit hexes (thx to Ivan!) * selecting attack directions works as in H3 * estimating damage that will be dealt while choosing stack to be attacked * modified the positioning of battle effects, they should look about right now. -* after selecting a spell during combat, l-click is locked for any action other than casting. +* after selecting a spell during combat, l-click is locked for any action other than casting. * flying creatures will be blitted over all other creatures, obstacles and wall * obstacles and units should be printed in better order (not tested) * fixed armageddon animation * new spells supported: - * Anti-Magic - * Cure - * Resurrection - * Animate Dead - * Counterstrike - * Berserk - * Hypnotize - * Blind - * Fire Elemental - * Earth Elemental - * Water Elemental - * Air Elemental - * Remove obstacle + * Anti-Magic + * Cure + * Resurrection + * Animate Dead + * Counterstrike + * Berserk + * Hypnotize + * Blind + * Fire Elemental + * Earth Elemental + * Water Elemental + * Air Elemental + * Remove obstacle + +### TOWNS -### TOWNS: * enemy castle can be taken over * only one capitol per player allowed (additional ones will be lost) * garrisoned hero can buy a spellbook * heroes available in tavern should be always different * ship bought in town will be correctly placed * new special town structures supported: - * Lookout Tower - * Temple of Valhalla - * Wall of Knowledge - * Order of Fire + * Lookout Tower + * Temple of Valhalla + * Wall of Knowledge + * Order of Fire + +### HERO WINDOW -### HERO WINDOW: * war machines cannot be unequiped -### PREGAME: +### PREGAME + * sorting: a second click on the column header sorts in descending order. * advanced options tab: r-click popups for selected town, hero and bonus * starting scenario / game by double click -* arrows in options tab are hidden when not available +* arrows in options tab are hidden when not available * subtitles for chosen hero/town/bonus in pregame -### OBJECTS: +### OBJECTS + * fixed pairing Subterranean Gates * New objects supported: - * Borderguard & Keymaster Tent - * Cartographer - * Creature banks - * Eye of the Magi & Hut of the Magi - * Garrison - * Stables - * Pandora Box - * Pyramid + * Borderguard & Keymaster Tent + * Cartographer + * Creature banks + * Eye of the Magi & Hut of the Magi + * Garrison + * Stables + * Pandora Box + * Pyramid -# 0.72 -> 0.73 (Aug 01 2009) +## 0.72 -> 0.73 (Aug 01 2009) + +### GENERAL -### GENERAL: * infowindow popup will be completely on screen * fixed possible crash with in game console * fixed crash when gaining artifact after r-click on hero in tavern -* Estates / hero bonuses won't give resources on first day. +* Estates / hero bonuses won't give resources on first day. * video handling (intro, main menu animation, tavern animation, spellbook animation, battle result window) * hero meeting window allowing exchanging armies and artifacts between heroes on adventure map * 'T' hotkey opens marketplace window @@ -2633,13 +2900,15 @@ http://bugs.vcmi.eu/changelog_page.php?version_id=2 * r-click popups on enemy heroes and towns * hero leveling formula matches the H3 -### ADVENTURE INTERFACE: +### ADVENTURE INTERFACE + * Garrisoning, then removing hero from garrison move him at the end of the heroes list * The size of the frame around the map depends on the screen size. * spellbook shows adventure spells when opened on adventure map * erasing path after picking objects with last movement point -### BATTLES: +### BATTLES + * spell resistance supported (secondary skill, artifacts, creature skill) * corrected damage inflicted by spells and ballista * added some missing projectile infos @@ -2648,49 +2917,54 @@ http://bugs.vcmi.eu/changelog_page.php?version_id=2 * non-living and undead creatures have now always 0 morale * displaying luck effect animation * support for battleground overlays: - * cursed ground - * magic plains - * fiery fields - * rock lands - * magic clouds - * lucid pools - * holy ground - * clover field - * evil fog + * cursed ground + * magic plains + * fiery fields + * rock lands + * magic clouds + * lucid pools + * holy ground + * clover field + * evil fog + +### TOWNS -### TOWNS: * fixes for horde buildings * garrisoned hero can buy a spellbook if he is selected or if there is no visiting hero * capitol bar in town hall is grey (not red) if already one exists * fixed crash on entering hall when town was near map edge -### HERO WINDOW: +### HERO WINDOW + * garrisoned heroes won't be shown on the list * artifacts will be present on morale/luck bonuses list -### PREGAME: +### PREGAME + * saves are sorted primary by map format, secondary by name * fixed displaying date of saved game (uses local time, removed square character) -### OBJECTS: +### OBJECTS + * Fixed primary/secondary skill levels given by a scholar. * fixed problems with 3-tiles monoliths * fixed crash with flaggable building next to map edge * fixed some descriptions for events * New objects supported: - * Buoy - * Creature Generators - * Flotsam - * Mermaid - * Ocean bottle - * Sea Chest - * Shipwreck Survivor - * Shipyard - * Sirens + * Buoy + * Creature Generators + * Flotsam + * Mermaid + * Ocean bottle + * Sea Chest + * Shipwreck Survivor + * Shipyard + * Sirens -# 0.71 -> 0.72 (Jun 1 2009) +## 0.71 -> 0.72 (Jun 1 2009) + +### GENERAL -### GENERAL: * many sound effects and music * autosave (to 5 subsequent files) * artifacts support (most of them) @@ -2706,7 +2980,8 @@ http://bugs.vcmi.eu/changelog_page.php?version_id=2 * redundant quotation marks from artifact descriptions are removed * no income at the first day -### ADVENTURE INTERFACE: +### ADVENTURE INTERFACE + * fixed crasbug occurring on revisiting objects (by pressing space) * always restoring default cursor when movng mouse out of the terrain * fixed map scrolling with ctrl+arrows when some windows are opened @@ -2714,7 +2989,8 @@ http://bugs.vcmi.eu/changelog_page.php?version_id=2 * pathfinder will now look for a path going via printed positions of roads when it's possible * enter can be used to open window with selected hero/town -### BATTLES: +### BATTLES + * many creatures special skills implemented * battle will end when one side has only war machines * fixed some problems with handling obstacles info @@ -2724,41 +3000,45 @@ http://bugs.vcmi.eu/changelog_page.php?version_id=2 * canceling of casting a spell by pressing Escape or R-click (R-click on a creatures does not cancel a spell) * spellbook cannot be opened by L-click on hero in battle when it shouldn't be possible * new spells: - * frost ring - * fireball - * inferno - * meteor shower - * death ripple - * destroy undead - * dispel - * armageddon - * disrupting ray - * protection from air - * protection from fire - * protection from water - * protection from earth - * precision - * slayer + * frost ring + * fireball + * inferno + * meteor shower + * death ripple + * destroy undead + * dispel + * armageddon + * disrupting ray + * protection from air + * protection from fire + * protection from water + * protection from earth + * precision + * slayer + +### TOWNS -### TOWNS: * resting in town with mage guild will replenih all the mana points * fixed Blacksmith * the number of creatures at the beginning of game is their base growth * it's possible to enter Tavern via Brotherhood of Sword -### HERO WINDOW: +### HERO WINDOW + * fixed mana limit info in the hero window * war machines can't be removed * fixed problems with removing artifacts when all visible slots in backpack are full -### PREGAME: +### PREGAME + * clicking on "advanced options" a second time now closes the tab instead of refreshing it. -* Fix position of maps names. +* Fix position of maps names. * Made the slider cursor much more responsive. Speedup the map select screen. * Try to behave when no maps/saves are present. * Page Up / Page Down / Home / End hotkeys for scrolling through scenarios / games list -### OBJECTS: +### OBJECTS + * Neutral creatures can join or escape depending on hero strength (escape formula needs to be improved) * leaving guardians in flagged mines. * support for Scholar object @@ -2772,46 +3052,49 @@ http://bugs.vcmi.eu/changelog_page.php?version_id=2 * support for Event * Corpse (Skeleton) will be accessible from all directions -# 0.7 -> 0.71 (Apr 01 2009) +## 0.7 -> 0.71 (Apr 01 2009) -### GENERAL: -* fixed scrolling behind window problem (now it's possible to scroll with CTRL + arrows) -* morale/luck system and corresponding sec. skills supported -* fixed crash when hero get level and has less than two sec. skills to choose between +### GENERAL + +* fixed scrolling behind window problem (now it's possible to scroll with CTRL + arrows) +* morale/luck system and corresponding sec. skills supported +* fixed crash when hero get level and has less than two sec. skills to choose between * added keybindings for components in selection window (eg. for treasure chest dialog): 1, 2, and so on. Selection dialog can be closed with Enter key * proper handling of custom portraits of heroes * fixed problems with non-hero/town defs not present in def list but present on map (occurring probably only in case of def substitution in map editor) -* fixed crash when there was no hero available to hire for some player +* fixed crash when there was no hero available to hire for some player * fixed problems with 1024x600 screen resolution -* updating blockmap/visitmap of randomized objects +* updating blockmap/visitmap of randomized objects * fixed crashes on loading maps with flag all mines/dwelling victory condition * further fixes for leveling-up (stability and identical offered skills bug) * splitting window allows to rebalance two stack with the same creatures * support for numpad keyboard * support for timed events -### ADVENTURE INTERFACE: +### ADVENTURE INTERFACE + * added "Next hero" button functionality * added missing path arrows -* corrected centering on hero's position +* corrected centering on hero's position * recalculating hero path after reselecting hero * further changes in pathfinder making it more like original one -* orientation of hero can't be change if movement points are exhausted +* orientation of hero can't be change if movement points are exhausted * campfire, borderguard, bordergate, questguard will be accessible from the top * new movement cost calculation algorithm * fixed sight radious calculation * it's possible to stop hero movement -* faster minimap refreshing +* faster minimap refreshing * provisional support for "Save" button in System Options Window * it's possible to revisit object under hero by pressing Space -### BATTLES: +### BATTLES + * partial support for battle obstacles * only one spell can be casted per turn * blocked opening sepllbook if hero doesn't have a one -* spells not known by hero can't be casted +* spells not known by hero can't be casted * spell books won't be placed in War Machine slots after battle -* attack is now possible when hex under cursor is not displayed +* attack is now possible when hex under cursor is not displayed * glowing effect of yellow border around creatures * blue glowing border around hovered creature * made animation on battlefield more smooth @@ -2825,82 +3108,90 @@ http://bugs.vcmi.eu/changelog_page.php?version_id=2 * correct handling of flying creatures in battles * a few tweaks in battle path/available hexes calculation (more of them is needed) * amounts of units taking actions / being an object of actions won't be shown until action ends -* fixed positions of stack queue and battle result window when resolution is != 800x600 -* corrected duration of frenzy spell which was incorrect in certain cases +* fixed positions of stack queue and battle result window when resolution is != 800x600 +* corrected duration of frenzy spell which was incorrect in certain cases * corrected hero spell casting animation -* better support for battle backgrounds -* blocked "save" command during battle +* better support for battle backgrounds +* blocked "save" command during battle * spellbook displays only spells known by Hero * New spells supported: - * Mirth - * Sorrow - * Fortune - * Misfortune + * Mirth + * Sorrow + * Fortune + * Misfortune + +### TOWN INTERFACE -### TOWN INTERFACE: * cannot build more than one capitol * cannot build shipyard if town is not near water -* Rampart's Treasury requires Miner's Guild +* Rampart's Treasury requires Miner's Guild * minor improvements in Recruitment Window * fixed crash occurring when clicking on hero portrait in Tavern Window, minor improvements for Tavern Window * proper updating resdatabar after building structure in town or buying creatures (non 800x600 res) -* fixed blinking resdatabar in town screen when buying (800x600) +* fixed blinking resdatabar in town screen when buying (800x600) * fixed horde buildings displaying in town hall * forbidden buildings will be shown as forbidden, even if there are no res / other conditions are not fulfilled -### PREGAME: +### PREGAME + * added scrolling scenario list with mouse wheel * fixed mouse slow downs -* cannot select heroes for computer player (pregame) +* cannot select heroes for computer player (pregame) * no crash if uses gives wrong resolution ID number * minor fixes -### OBJECTS: -* windmill gives 500 gold only during first week ever (not every month) -* After the first visit to the Witch Hut, right-click/hover tip mentions the skill available. -* New objects supported: - * Prison - * Magic Well - * Faerie Ring - * Swan Pond - * Idol of Fortune - * Fountain of Fortune - * Rally Flag - * Oasis - * Temple - * Watering Hole - * Fountain of Youth - * support for Redwood Observatory - * support for Shrine of Magic Incantation / Gesture / Thought - * support for Sign / Ocean Bottle +### OBJECTS + +* windmill gives 500 gold only during first week ever (not every month) +* After the first visit to the Witch Hut, right-click/hover tip mentions the skill available. +* New objects supported: + * Prison + * Magic Well + * Faerie Ring + * Swan Pond + * Idol of Fortune + * Fountain of Fortune + * Rally Flag + * Oasis + * Temple + * Watering Hole + * Fountain of Youth + * support for Redwood Observatory + * support for Shrine of Magic Incantation / Gesture / Thought + * support for Sign / Ocean Bottle + +### AI PLAYER -### AI PLAYER: * Minor improvements and fixes. -# 0.64 -> 0.7 (Feb 01 2009) +## 0.64 -> 0.7 (Feb 01 2009) + +### GENERAL -### GENERAL: * move some settings to the config/settings.txt file * partial support for new screen resolutions -* it's possible to set game resolution in pregame (type 'resolution' in the console) +* it's possible to set game resolution in pregame (type 'resolution' in the console) * /Data and /Sprites subfolders can be used for adding files not present in .lod archives * fixed crashbug occurring when hero levelled above 15 level * support for non-standard screen resolutions * F4 toggles between full-screen and windowed mode * minor improvements in creature card window -* splitting stacks with the shift+click -* creature card window contains info about modified speed +* splitting stacks with the shift+click +* creature card window contains info about modified speed + +### ADVENTURE INTERFACE -### ADVENTURE INTERFACE: * added water animation * speed of scrolling map and hero movement can be adjusted in the System Options Window * partial handling r-clicks on adventure map -### TOWN INTERFACE: +### TOWN INTERFACE + * the scroll tab won't remain hanged to our mouse position if we move the mouse is away from the scroll bar * fixed cloning creatures bug in garrisons (and related issues) -### BATTLES: +### BATTLES + * support for the Wait command * magic arrow *really* works * war machines support partially added @@ -2909,39 +3200,42 @@ http://bugs.vcmi.eu/changelog_page.php?version_id=2 * positive/negative spells cannot be cast on hostile/our stacks * showing spell effects affecting stack in creature info window * more appropriate coloring of stack amount box when stack is affected by a spell -* battle console displays notifications about wait/defend commands +* battle console displays notifications about wait/defend commands * several reported bugs fixed * new spells supported: - * Haste - * lightning bolt - * ice bolt - * slow - * implosion - * forgetfulness - * shield - * air shield - * bless - * curse - * bloodlust - * weakness - * stone skin - * prayer - * frenzy + * Haste + * lightning bolt + * ice bolt + * slow + * implosion + * forgetfulness + * shield + * air shield + * bless + * curse + * bloodlust + * weakness + * stone skin + * prayer + * frenzy + +### AI PLAYER -### AI PLAYER: * Genius AI (first VCMI AI) will control computer creatures during the combat. -### OBJECTS: +### OBJECTS + * Guardians property for resources is handled * support for Witch Hut * support for Arena -* support for Library of Enlightenment +* support for Library of Enlightenment And a lot of minor fixes -# 0.63 -> 0.64 (Nov 01 2008) +## 0.63 -> 0.64 (Nov 01 2008) + +### GENERAL -### GENERAL: * sprites from /Sprites folder are handled correctly * several fixes for pathfinder and path arrows * better handling disposed/predefined heroes @@ -2953,39 +3247,43 @@ And a lot of minor fixes * many minor improvements * Added some kind of simple chatting functionality through console. Implemented several WoG cheats equivalents: - * woggaladriel -> vcmiainur - * wogoliphaunt -> vcminoldor - * wogshadowfax -> vcminahar - * wogeyeofsauron -> vcmieagles - * wogisengard -> vcmiformenos - * wogsaruman -> vcmiistari - * wogpathofthedead -> vcmiangband - * woggandalfwhite -> vcmiglorfindel + * woggaladriel -> vcmiainur + * wogoliphaunt -> vcminoldor + * wogshadowfax -> vcminahar + * wogeyeofsauron -> vcmieagles + * wogisengard -> vcmiformenos + * wogsaruman -> vcmiistari + * wogpathofthedead -> vcmiangband + * woggandalfwhite -> vcmiglorfindel -### ADVENTURE INTERFACE: -* clicking on a tile in advmap view when a path is shown will not only hide it but also calculate a new one -* slowed map scrolling +### ADVENTURE INTERFACE + +* clicking on a tile in advmap view when a path is shown will not only hide it but also calculate a new one +* slowed map scrolling * blocked scrolling adventure map with mouse when left ctrl is pressed * blocked map scrolling when dialog window is opened * scholar will be accessible from the top -### TOWN INTERFACE: +### TOWN INTERFACE + * partially done tavern window (only hero hiring functionality) -### BATTLES: +### BATTLES + * water elemental will really be treated as 2 hex creature * potential infinite loop in reverseCreature removed -* better handling of battle cursor +* better handling of battle cursor * fixed blocked shooter behavior * it's possible in battles to check remeaining HP of neutral stacks * partial support for Magic Arrow spell * fixed bug with dying unit * stack queue hotkey is now 'Q' -* added shots limit +* added shots limit -# 0.62 -> 0.63 (Oct 01 2008) +## 0.62 -> 0.63 (Oct 01 2008) + +### GENERAL -### GENERAL: * coloured console output, logging all info to txt files * it's possible to use other port than 3030 by passing it as an additional argument * removed some redundant warnings @@ -2994,49 +3292,54 @@ And a lot of minor fixes * some crashbugs was fixed * added handling of navigation, logistics, pathfinding, scouting end estates secondary skill * magical hero are given spellbook at the beginning -* added initial secondary skills for heroes +* added initial secondary skills for heroes -### BATTLES: -* very significant optimization of battles +### BATTLES + +* very significant optimization of battles * battle summary window -* fixed crashbug occurring sometimes on exiting battle -* confirm window is shown before retreat +* fixed crashbug occurring sometimes on exiting battle +* confirm window is shown before retreat * graphic stack queue in battle (shows when 'c' key is pressed) * it's possible to attack enemy hero * neutral monster army disappears when defeated * casualties among hero army and neutral creatures are saved * better animation handling in battles -* directional attack in battles +* directional attack in battles * mostly done battle options (although they're not saved) -* added receiving exp (and leveling-up) after a won battle -* added support for archery, offence and armourer secondary abilities +* added receiving exp (and leveling-up) after a won battle +* added support for archery, offence and armourer secondary abilities * hero's primary skills accounted for damage dealt by creatures in battle -### TOWNS: -* mostly done marketplace +### TOWNS + +* mostly done marketplace * fixed crashbug with battles on swamps and rough terrain -* counterattacks +* counterattacks * heroes can learn new spells in towns * working resource silo * fixed bug with the mage guild when no spells available * it's possible to build lighthouse -### HERO WINDOW: +### HERO WINDOW + * setting army formation * tooltips for artifacts in backpack -### ADVENTURE INTERFACE: +### ADVENTURE INTERFACE + * fixed bug with disappearing head of a hero in adventure map -* some objects are no longer accessible from the top +* some objects are no longer accessible from the top * no tooltips for objects under FoW * events won't be shown * working Subterranean Gates, Monoliths -* minimap shows all flaggable objects (towns, mines, etc.) +* minimap shows all flaggable objects (towns, mines, etc.) * artifacts we pick up go to the appropriate slot (if free) -# 0.61 -> 0.62 (Sep 01 2008) +## 0.61 -> 0.62 (Sep 01 2008) + +### GENERAL -### GENERAL: * restructured to the server-client model * support for heroes placed in towns * upgrading creatures @@ -3045,7 +3348,8 @@ And a lot of minor fixes * showing creature amount in the creature info window * giving starting bonus -### CASTLES: +### CASTLES + * icon in infobox showing that there is hero in town garrison * fort/citadel/castle screen * taking last stack from the heroes army should be impossible (or at least harder) @@ -3053,20 +3357,23 @@ And a lot of minor fixes * randomizing spells in towns * viewing hero window in the town screen * possibility of moving hero into the garrison -* mage guild screen +* mage guild screen * support for blacksmith * if hero doesn't have a spell book, he can buy one in a mage guild * it's possible to build glyph of fear in fortress * creatures placeholders work properly -### ADVENTURE INTERFACE: +### ADVENTURE INTERFACE + * hopefully fixed problems with wrong town defs (village/fort/capitol) -### HERO WINDOW: +### HERO WINDOW + * bugfix: splitting stacks works in hero window * removed bug causing significant increase of CPU consumption -### BATTLES: +### BATTLES + * shooting * removed some displaying problems * showing last group of frames in creature animation won't crash @@ -3079,20 +3386,23 @@ And a lot of minor fixes * improved pathfinding in battles, removed problems with displaying movement, adventure map interface won't be called during battles. * minor optimizations -### PREGAME: +### PREGAME + * updates settings when selecting new map after changing sorting criteria * if sorting not by name, name will be used as a secondary criteria * when filter is applied a first available map is selected automatically * slider position updated after sorting in pregame -### OBJECTS: +### OBJECTS + * support for the Tree of knowledge * support for Campfires * added event message when picking artifact -# 0.6 -> 0.61 (Jun 15 2008) +## 0.6 -> 0.61 (Jun 15 2008) + +### IMPROVEMENTS -### IMPROVEMENTS: * improved attacking in the battles * it's possible to kill hostile stack * animations won't go in the same phase @@ -3108,7 +3418,8 @@ And a lot of minor fixes * battle log is scrolled down when new event occurs * console is closed when application exits -### BUGFIXES: +### BUGFIXES + * stack at the limit of unit's range can now be attacked * good background for the town hall screen in Stronghold * fixed typo in hall.txt @@ -3118,7 +3429,7 @@ And a lot of minor fixes * properly displaying two-hex creatures in recruit/split/info window * corrupted map file won't cause crash on initializing main menu -# 0.59 -> 0.6 (Jun 1 2008) +## 0.59 -> 0.6 (Jun 1 2008) * partially done attacking in battles * screen isn't now refreshed while blitting creature info window @@ -3131,7 +3442,7 @@ And a lot of minor fixes * new pathfinder * several minor improvements -# 0.58 -> 0.59 (May 24 2008 - closed, test release) +## 0.58 -> 0.59 (May 24 2008 - closed, test release) * fixed memory leak in battles * blitting creature animations to rects in the recruitment window @@ -3151,9 +3462,10 @@ And a lot of minor fixes * callback for buttons/lists based on boost::function * a lot of minor improvements -# 0.55 -> 0.58 (Apr 20 2008 - closed, test release) +## 0.55 -> 0.58 (Apr 20 2008 - closed, test release) + +### TOWNS -### TOWNS: * recruiting creatures * working creature growths (including castle and horde building influences) * towns give income @@ -3162,21 +3474,24 @@ And a lot of minor fixes * hints for structures * updating town infobox -### GARRISONS: +### GARRISONS + * merging stacks * splitting stacks -### BATTLES: +### BATTLES + * starting battles * displaying terrain, animations of heroes, units, grid, range of units, battle menu with console, amounts of units in stacks * leaving battle by pressing flee button * moving units in battles and displaying their ranges * defend command for units -### GENERAL: +### GENERAL + * a number of minor fixes and improvements -# 0.54 -> 0.55 (Feb 29 2008) +## 0.54 -> 0.55 (Feb 29 2008) * Sprites/ folder works for h3sprite.lod same as Data/ for h3bitmap.lod (but it's still experimental) * randomization quantity of creatures on the map @@ -3189,7 +3504,8 @@ And a lot of minor fixes * hints for most of creature generators * some minor stuff -# 0.53b -> 0.54 (Feb 23 2008 - first public release) +## 0.53b -> 0.54 (Feb 23 2008 - first public release) + * given hero is placed in the town entrance * some objects such as river delta won't be blitted "on" hero * tiles under FoW are inaccessible @@ -3202,12 +3518,12 @@ And a lot of minor fixes * added hints in town lists * eliminated square from city hints -# 0.53 - 0.53b (Feb 20 2008) +## 0.53 - 0.53b (Feb 20 2008) * added giving default buildings in towns * town infobox won't crash on empty town -# 0.52 - 0.53 (Feb 18 2008): +## 0.52 - 0.53 (Feb 18 2008) * hopefully the last bugfix of Pandora's Box * fixed blockmaps of generated heroes @@ -3224,7 +3540,7 @@ And a lot of minor fixes * mostly done town infobox * town daily income is properly calculated -# 0.51 - 0.52 (Feb 7 2008): +## 0.51 - 0.52 (Feb 7 2008) * [feature] giving starting hero * [feature] VCMI will try to use files from /Data folder instead of those from h3bitmap.lod @@ -3235,7 +3551,7 @@ And a lot of minor fixes * [bugfix] improved randomization * [bugfix] pathfinder can't be cheated (what caused errors) -# 0.5 - 0.51 (Feb 3 2008): +## 0.5 - 0.51 (Feb 3 2008) * close button properly closes (same does 'q' key) * two players can't have selected same hero @@ -3248,7 +3564,7 @@ And a lot of minor fixes * better console messages * map reading speed up (though it's still slow, especially on bigger maps) -# 0.0 -> 0.5 (Feb 2 2008 - first closed release): +## 0.0 -> 0.5 (Feb 2 2008 - first closed release) * Main menu and New game screens * Scenario selection, part of advanced options support diff --git a/docs/Readme.md b/docs/Readme.md index 284cf3c0b..68f3118cd 100644 --- a/docs/Readme.md +++ b/docs/Readme.md @@ -1,11 +1,11 @@ +# VCMI Project + [![VCMI](https://github.com/vcmi/vcmi/actions/workflows/github.yml/badge.svg?branch=develop&event=push)](https://github.com/vcmi/vcmi/actions/workflows/github.yml?query=branch%3Adevelop+event%3Apush) [![Github Downloads](https://img.shields.io/github/downloads/vcmi/vcmi/1.5.0/total)](https://github.com/vcmi/vcmi/releases/tag/1.5.0) [![Github Downloads](https://img.shields.io/github/downloads/vcmi/vcmi/1.5.6/total)](https://github.com/vcmi/vcmi/releases/tag/1.5.6) [![Github Downloads](https://img.shields.io/github/downloads/vcmi/vcmi/1.5.7/total)](https://github.com/vcmi/vcmi/releases/tag/1.5.7) [![Github Downloads](https://img.shields.io/github/downloads/vcmi/vcmi/total)](https://github.com/vcmi/vcmi/releases) -# VCMI Project - VCMI is an open-source recreation of Heroes of Might & Magic III engine, giving it new and extended possibilities.

@@ -15,14 +15,13 @@ VCMI is an open-source recreation of Heroes of Might & Magic III engine, giving New widget for Hero selection, featuring Pavillon Town

- ## Links - * Homepage: https://vcmi.eu/ - * Forums: https://forum.vcmi.eu/ - * Bugtracker: https://github.com/vcmi/vcmi/issues - * Discord: https://discord.gg/chBT42V - * GPT Store: https://chat.openai.com/g/g-1kNhX0mlO-vcmi-assistant +* Homepage: +* Forums: +* Bugtracker: +* Discord: +* GPT Store: ## Latest release @@ -31,6 +30,7 @@ Loading saves made with different major version of VCMI is usually **not** suppo Please see corresponding installation guide articles for details for your platform. ## Installation guides + - [Windows](players/Installation_Windows.md) - [macOS](players/Installation_macOS.md) - [Linux](players/Installation_Linux.md) @@ -70,6 +70,7 @@ See also installation guide for [Heroes Chronicles](players/Heroes_Chronicles.md ## Documentation and guidelines for developers Development environment setup instructions: + - [Building VCMI for Android](developers/Building_Android.md) - [Building VCMI for iOS](developers/Building_iOS.md) - [Building VCMI for Linux](developers/Building_Linux.md) @@ -78,6 +79,7 @@ Development environment setup instructions: - [Conan](developers/Conan.md) Engine documentation: (NOTE: may be outdated) + - [Development with Qt Creator](developers/Development_with_Qt_Creator.md) - [Coding Guidelines](developers/Coding_Guidelines.md) - [Bonus System](developers/Bonus_System.md) @@ -95,6 +97,6 @@ Engine documentation: (NOTE: may be outdated) ## Copyright and license VCMI Project source code is licensed under GPL version 2 or later. -VCMI Project assets are licensed under CC-BY-SA 4.0. Assets sources and information about contributors are available under following link: https://github.com/vcmi/vcmi-assets +VCMI Project assets are licensed under CC-BY-SA 4.0. Assets sources and information about contributors are available under following link: Copyright (C) 2007-2024 VCMI Team (check AUTHORS file for the contributors list) diff --git a/docs/developers/AI.md b/docs/developers/AI.md index b75ba539a..d5221bfda 100644 --- a/docs/developers/AI.md +++ b/docs/developers/AI.md @@ -6,12 +6,13 @@ There are two types of AI: adventure and battle. **Battle AIs** are responsible for fighting, i.e. moving stacks on the battlefield We have 3 battle AIs so far: + * BattleAI - strongest * StupidAI - for neutrals, should be simple so that experienced players can abuse it * Empty AI - should do nothing at all. If needed another battle AI can be introduced. -Each battle AI consist of a few classes, but the main class, kind of entry point usually has the same name as the package itself. In BattleAI it is the BattleAI class. It implements some battle specific interface, do not remember. Main method there is activeStack(battle::Unit* stack). It is invoked by the system when it's time to move your stack. The thing you use to interact with the game and receive the gamestate is usually referenced in the code as cb. CPlayerSpecificCallback it should be. It has a lot of methods and can do anything. For instance it has battleGetUnitsIf(), which returns all units on the battlefield matching some lambda condition. -Each side in a battle is represented by an CArmedInstance object. CHeroInstance and CGDwelling, CGMonster and more are subclasses of CArmedInstance. CArmedInstance contains a set of stacks. When the battle starts, these stacks are converted to battle stacks. Usually Battle AIs reference them using the interface battle::Unit *. +Each battle AI consist of a few classes, but the main class, kind of entry point usually has the same name as the package itself. In BattleAI it is the BattleAI class. It implements some battle specific interface, do not remember. Main method there is activeStack(battle::Unit*stack). It is invoked by the system when it's time to move your stack. The thing you use to interact with the game and receive the gamestate is usually referenced in the code as cb. CPlayerSpecificCallback it should be. It has a lot of methods and can do anything. For instance it has battleGetUnitsIf(), which returns all units on the battlefield matching some lambda condition. +Each side in a battle is represented by an CArmedInstance object. CHeroInstance and CGDwelling, CGMonster and more are subclasses of CArmedInstance. CArmedInstance contains a set of stacks. When the battle starts, these stacks are converted to battle stacks. Usually Battle AIs reference them using the interface battle::Unit*. Units have bonuses. Nearly everything aspect of a unit is configured in the form of bonuses. Attack, defense, health, retaliation, shooter or not, initial count of shots and so on. When you call unit->getAttack() it summarizes all these bonuses and returns the resulting value. @@ -38,17 +39,20 @@ BattleAI itself handles all the rest and issues actual commands Adventure AI responsible for moving heroes on map, gathering things, developing town. Main idea is to gather all possible tasks on map, prioritize them and select the best one for each heroes. Initially was a fork of VCAI ### Parts + Gateway - a callback for server used to invoke AI actions when server thinks it is time to do something. Through this callback AI is informed about various events like hero level up, tile revialed, blocking dialogs and so on. In order to do this Gaateway implements specific interface. The interface is exactly the same for human and AI Another important actor for server interaction is CCallback * cb. This one is used to retrieve gamestate information and ask server to do things like hero moving, spell casting and so on. Each AI has own instance of Gateway and it is a root object which holds all AI state. Gateway has an event method yourTurn which invokes makeTurn in another thread. The last passes control to Nullkiller engine. Nullkiller engine - place where actual AI logic is organized. It contains a main loop for gathering and prioritizing things. Its algorithm: + * reset AI state, it avoids keeping some memory about the game in general to reduce amount of things serialized into savefile state. The only serialized things are in nullkiller->memory. This helps reducing save incompatibility. It should be mostly enough for AI to analyze data avaialble in CCallback * main loop, loop iteration is called a pass -** update AI state, some state is lazy and updates once per day to avoid performance hit, some state is recalculated each loop iteration. At this stage analysers and pathfidner work +**update AI state, some state is lazy and updates once per day to avoid performance hit, some state is recalculated each loop iteration. At this stage analysers and pathfidner work ** gathering goals, prioritizing and decomposing them ** execute selected best goals Analyzer - a module gathering data from CCallback *. Its goal to make some statistics and avoid making any significant decissions. + * HeroAnalyser - decides upong which hero suits better to be main (army carrier and fighter) and which is better to be a scout (gathering unguarded resources, exploring) * BuildAnalyzer - prepares information on what we can build in our towns, and what resources we need to do this * DangerHitMapAnalyser - checks if enemy hero can rich each tile, how fast and what is their army strangth @@ -61,9 +65,11 @@ Analyzer - a module gathering data from CCallback *. Its goal to make some stati * PriorityEvaluator - gathers information on task rewards, evaluates their priority using Fuzzy Light library (fuzzy logic) ### Goals + Units of activity in AI. Can be AbstractGoal, Task, Marker and Behavior Task - simple thing which can be done right away in order to gain some reward. Or a composition of simple things in case if more than one action is needed to gain the reward. + * AdventureSpellCast - town portal, water walk, air walk, summon boat * BuildBoat - builds a boat in a specific shipyard * BuildThis - builds a building in a specified town @@ -78,6 +84,7 @@ Task - simple thing which can be done right away in order to gain some reward. O * StayAtTown - stay at town for the rest of the day (to regain mana) Behavior - a core game activity + * CaptureObjectsBehavior - generally it is about visiting map objects which give reward. It can capture any object, even those which are behind monsters and so on. But due to performance considerations it is not allowed to handle monsters and quests now. * ClusterBehavior - uses information of ObjectClusterizer to unblock objects hidden behind various blockers. It kills guards, completes quests, captures garrisons. * BuildingBehavior - develops our towns @@ -89,6 +96,7 @@ Behavior - a core game activity * DefenceBehavior - defend towns by eliminating treatening heroes or hiding in town garrison AbstractGoal - some goals can not be completed because it is not clear how to do this. They express desire to do something, not exact plan. DeepDecomposer is used to refine such goals until they are turned into such plan or discarded. Some examples: + * CaptureObject - you need to visit some object (flag a shipyard for instance) but do not know how * CompleteQuest - you need to bypass bordergate or borderguard or questguard but do not know how AbstractGoal usually comes in form of composition with some elementar task blocked by abstract objective. For instance CaptureObject(Shipyard), ExecuteHeroChain(visit x, build boat, visit enemy town). When such composition is decomposed it can turn into either a pair of herochains or into another abstract composition if path to shipyard is also blocked with something. diff --git a/docs/developers/Bonus_System.md b/docs/developers/Bonus_System.md index e594fff8e..6fef4d6e3 100644 --- a/docs/developers/Bonus_System.md +++ b/docs/developers/Bonus_System.md @@ -6,8 +6,8 @@ The bonus system of VCMI is a set of mechanisms that make handling of different Each bonus originates from some node in the bonus system, and may have propagator and limiter objects attached to it. Bonuses are shared around as follows: -1. Bonuses with propagator are propagated to "matching" descendants in the red DAG - which descendants match is determined by the propagator. Bonuses without a propagator will not be propagated. -2. Bonuses without limiters are inherited by all descendants in the black DAG. If limiters are present, they can restrict inheritance to certain nodes. +1. Bonuses with propagator are propagated to "matching" descendants in the red DAG - which descendants match is determined by the propagator. Bonuses without a propagator will not be propagated. +2. Bonuses without limiters are inherited by all descendants in the black DAG. If limiters are present, they can restrict inheritance to certain nodes. Inheritance is the default means of sharing bonuses. A typical example is an artefact granting a bonus to attack/defense stat, which is inherited by the hero wearing it, and then by creatures in the hero's army. A common limiter is by creature - e.g. the hero Eric has a specialty that grants bonuses to attack, defense and speed, but only to griffins. @@ -15,9 +15,9 @@ Propagation is used when bonuses need to be shared in a different direction than ### Technical Details -- Propagation is done by copying bonuses to the target nodes. This happens when bonuses are added. -- Inheritance is done on-the-fly when needed, by traversing the black DAG. Results are cached to improve performance. -- Whenever a node changes (e.g. bonus added), a global counter gets increased which is used to check whether cached results are still current. +- Propagation is done by copying bonuses to the target nodes. This happens when bonuses are added. +- Inheritance is done on-the-fly when needed, by traversing the black DAG. Results are cached to improve performance. +- Whenever a node changes (e.g. bonus added), a global counter gets increased which is used to check whether cached results are still current. ## Operations on the graph @@ -26,6 +26,7 @@ There are two basic types of operations that can be performed on the graph: ### Adding a new node When node is attached to a new black parent (the only possibility - adding parent is the same as adding a child to it), the propagation system is triggered and works as follows: + - For the attached node and its all red ancestors - For every bonus - Call propagator giving the new descendant - then attach appropriately bonuses to the red descendant of attached node (or the node itself). @@ -54,7 +55,7 @@ Updaters are objects attached to bonuses. They can modify a bonus (typically by The following example shows an artifact providing a bonus based on the level of the hero that wears it: -```javascript +```jsonc "core:greaterGnollsFlail": { "text" : { "description" : "This mighty flail increases the attack of all gnolls under the hero's command by twice the hero's level." }, diff --git a/docs/developers/Building_Android.md b/docs/developers/Building_Android.md index 5ce865f7b..5d1af915e 100644 --- a/docs/developers/Building_Android.md +++ b/docs/developers/Building_Android.md @@ -1,26 +1,26 @@ # Building Android -The following instructions apply to **v1.2 and later**. For earlier versions the best documentation is https://github.com/vcmi/vcmi-android/blob/master/building.txt (and reading scripts in that repo), however very limited to no support will be provided from our side if you wish to go down that rabbit hole. +The following instructions apply to **v1.2 and later**. For earlier versions the best documentation is (and reading scripts in that repo), however very limited to no support will be provided from our side if you wish to go down that rabbit hole. *Note*: building has been tested only on Linux and macOS. It may or may not work on Windows out of the box. ## Requirements -1. CMake 3.20+: download from your package manager or from https://cmake.org/download/ +1. CMake 3.20+: download from your package manager or from 2. JDK 11, not necessarily from Oracle -3. Android command line tools or Android Studio for your OS: https://developer.android.com/studio/ +3. Android command line tools or Android Studio for your OS: 4. Android NDK version **r25c (25.2.9519653)**, there're multiple ways to obtain it: - install with Android Studio - install with `sdkmanager` command line tool - - download from https://developer.android.com/ndk/downloads + - download from - download with Conan, see [#NDK and Conan](#ndk-and-conan) 5. Optional: - - Ninja: download from your package manager or from https://github.com/ninja-build/ninja/releases - - Ccache: download from your package manager or from https://github.com/ccache/ccache/releases + - Ninja: download from your package manager or from + - Ccache: download from your package manager or from ## Obtaining source code -Clone https://github.com/vcmi/vcmi with submodules. Example for command line: +Clone with submodules. Example for command line: ``` git clone --recurse-submodules https://github.com/vcmi/vcmi.git @@ -31,6 +31,7 @@ git clone --recurse-submodules https://github.com/vcmi/vcmi.git We use Conan package manager to build/consume dependencies, find detailed usage instructions [here](./Conan.md). Note that the link points to the state of the current branch, for the latest release check the same document in the [master branch](https://github.com/vcmi/vcmi/blob/master/docs/developers/Сonan.md). On the step where you need to replace **PROFILE**, choose: + - `android-32` to build for 32-bit architecture (armeabi-v7a) - `android-64` to build for 64-bit architecture (aarch64-v8a) @@ -38,7 +39,7 @@ On the step where you need to replace **PROFILE**, choose: Conan must be aware of the NDK location when you execute `conan install`. There're multiple ways to achieve that as written in the [Conan docs](https://docs.conan.io/1/integrations/cross_platform/android.html): -- the easiest is to download NDK from Conan (option 1 in the docs), then all the magic happens automatically. On the step where you need to replace **PROFILE**, choose _android-**X**-ndk_ where _**X**_ is either `32` or `64`. +- the easiest is to download NDK from Conan (option 1 in the docs), then all the magic happens automatically. On the step where you need to replace **PROFILE**, choose *android-**X**-ndk* where ***X*** is either `32` or `64`. - to use an already installed NDK, you can simply pass it on the command line to `conan install`: (note that this will work only when consuming the pre-built binaries) ``` diff --git a/docs/developers/Building_Linux.md b/docs/developers/Building_Linux.md index 4a9b42cf1..d4cabb57b 100644 --- a/docs/developers/Building_Linux.md +++ b/docs/developers/Building_Linux.md @@ -11,15 +11,15 @@ Older distributions and compilers might work, but they aren't tested by Github C To compile, the following packages (and their development counterparts) are needed to build: -- CMake -- SDL2 with devel packages: mixer, image, ttf -- zlib and zlib-devel -- Boost C++ libraries v1.48+: program-options, filesystem, system, thread, locale -- Recommended, if you want to build launcher or map editor: Qt 5, widget and network modules -- Recommended, FFmpeg libraries, if you want to watch in-game videos: libavformat and libswscale. Their name could be libavformat-devel and libswscale-devel, or ffmpeg-libs-devel or similar names. -- Optional: - - if you want to build scripting modules: LuaJIT - - to speed up recompilation: Ccache +- CMake +- SDL2 with devel packages: mixer, image, ttf +- zlib and zlib-devel +- Boost C++ libraries v1.48+: program-options, filesystem, system, thread, locale +- Recommended, if you want to build launcher or map editor: Qt 5, widget and network modules +- Recommended, FFmpeg libraries, if you want to watch in-game videos: libavformat and libswscale. Their name could be libavformat-devel and libswscale-devel, or ffmpeg-libs-devel or similar names. +- Optional: + - if you want to build scripting modules: LuaJIT + - to speed up recompilation: Ccache ### On Debian-based systems (e.g. Ubuntu) @@ -41,7 +41,7 @@ NOTE: `fuzzylite-devel` package is no longer available in recent version of Fedo On Arch-based distributions, there is a development package available for VCMI on the AUR. -It can be found at https://aur.archlinux.org/packages/vcmi-git/ +It can be found at Information about building packages from the Arch User Repository (AUR) can be found at the Arch wiki. @@ -109,9 +109,9 @@ This will generate `vcmiclient`, `vcmiserver`, `vcmilauncher` as well as .so lib ### RPM package -The first step is to prepare a RPM build environment. On Fedora systems you can follow this guide: http://fedoraproject.org/wiki/How_to_create_an_RPM_package#SPEC_file_overview +The first step is to prepare a RPM build environment. On Fedora systems you can follow this guide: -0. Enable RPMFusion free repo to access to ffmpeg libs: +1. Enable RPMFusion free repo to access to ffmpeg libs: ```sh sudo dnf install https://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm @@ -120,33 +120,34 @@ sudo dnf install https://download1.rpmfusion.org/free/fedora/rpmfusion-free-rele > [!NOTE] > The stock ffmpeg from Fedora repo is no good as it lacks a lots of codecs -1. Perform a git clone from a tagged branch for the right Fedora version from https://github.com/rpmfusion/vcmi; for example for Fedora 38: 
git clone -b f38 --single-branch https://github.com/rpmfusion/vcmi.git
+2. Perform a git clone from a tagged branch for the right Fedora version from ; for example for Fedora 38: 
git clone -b f38 --single-branch https://github.com/rpmfusion/vcmi.git
-2. Copy all files to ~/rpmbuild/SPECS with command: 
cp vcmi/*  ~/rpmbuild/SPECS
+3. Copy all files to ~/rpmbuild/SPECS with command: 
cp vcmi/*  ~/rpmbuild/SPECS
-3. Fetch all sources by using spectool: +4. Fetch all sources by using spectool: ```sh sudo dnf install rpmdevtools spectool -g -R ~/rpmbuild/SPECS/vcmi.spec ``` -4. Fetch all dependencies required to build the RPM: +5. Fetch all dependencies required to build the RPM: ```sh sudo dnf install dnf-plugins-core sudo dnf builddep ~/rpmbuild/SPECS/vcmi.spec ``` -4. Go to ~/rpmbuild/SPECS and open terminal in this folder and type: +6. Go to ~/rpmbuild/SPECS and open terminal in this folder and type: + ```sh rpmbuild -ba ~/rpmbuild/SPECS/vcmi.spec ``` -5. Generated RPM is in folder ~/rpmbuild/RPMS +7. Generated RPM is in folder ~/rpmbuild/RPMS If you want to package the generated RPM above for different processor architectures and operating systems you can use the tool mock. -Moreover, it is necessary to install mock-rpmfusion_free due to the packages ffmpeg-devel and ffmpeg-libs which aren't available in the standard RPM repositories(at least for Fedora). Go to ~/rpmbuild/SRPMS in terminal and type: +Moreover, it is necessary to install mock-rpmfusion_free due to the packages ffmpeg-devel and ffmpeg-libs which aren't available in the standard RPM repositories(at least for Fedora). Go to ~/rpmbuild/SRPMS in terminal and type: ```sh mock -r fedora-38-aarch64-rpmfusion_free path_to_source_RPM diff --git a/docs/developers/Building_Windows.md b/docs/developers/Building_Windows.md index e1f574125..70cef1fdd 100644 --- a/docs/developers/Building_Windows.md +++ b/docs/developers/Building_Windows.md @@ -12,8 +12,8 @@ Windows builds can be made in more than one way and with more than one tool. Thi - CMake [download link](https://cmake.org/download/). During install after accepting license agreement make sure to check "Add CMake to the system PATH for all users". - To unpack pre-build Vcpkg: [7-zip](http://www.7-zip.org/download.html) - Optional: - - To create installer: [NSIS](http://nsis.sourceforge.net/Main_Page) - - To speed up recompilation: [CCache](https://github.com/ccache/ccache/releases) + - To create installer: [NSIS](http://nsis.sourceforge.net/Main_Page) + - To speed up recompilation: [CCache](https://github.com/ccache/ccache/releases) ### Choose an installation directory @@ -21,12 +21,14 @@ Create a directory for VCMI development, eg. `C:\VCMI` We will call this directo 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. +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)` @@ -38,13 +40,14 @@ You have two options: to use pre-built libraries or build your own. We strongly #### Download and unpack archive -Vcpkg Archives are available at our GitHub: https://github.com/vcmi/vcmi-deps-windows/releases +Vcpkg Archives are available at our GitHub: - 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%` @@ -57,19 +60,19 @@ Be aware that building Vcpkg might take a lot of time depend on your CPU model a #### Clone vcpkg -1. open SourceTree -2. File -\> Clone -3. select **** as source -4. select **%VCMI_DIR%/vcpkg** as destination -5. click **Clone** +1. open SourceTree +2. File -\> Clone +3. select **** as source +4. select **%VCMI_DIR%/vcpkg** as destination +5. click **Clone** From command line use: - git clone https://github.com/microsoft/vcpkg.git %VCMI_DIR%/vcpkg +`git clone https://github.com/microsoft/vcpkg.git %VCMI_DIR%/vcpkg` #### Build vcpkg and dependencies -- Run +- Run `%VCMI_DIR%/vcpkg/bootstrap-vcpkg.bat` - For 32-bit build run: `%VCMI_DIR%/vcpkg/vcpkg.exe install tbb:x64-windows fuzzylite:x64-windows sdl2:x64-windows sdl2-image:x64-windows sdl2-ttf:x64-windows sdl2-mixer[mpg123]:x64-windows boost:x64-windows qt5-base:x64-windows ffmpeg:x64-windows luajit:x64-windows` @@ -85,6 +88,7 @@ Extract `ccache` to a folder of your choosing, add the folder to the `PATH` envi ## Build VCMI #### From GIT GUI + - Open SourceTree - File -> Clone - select `https://github.com/vcmi/vcmi/` as source @@ -94,26 +98,30 @@ Extract `ccache` to a folder of your choosing, add the folder to the `PATH` envi - 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` +- 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 the combobox - If you want to use ccache: - - Select `Manage Configurations...` in the combobox - - Specify the following CMake variable: `ENABLE_CCACHE=ON` - - See the [Visual Studio documentation](https://learn.microsoft.com/en-us/cpp/build/customize-cmake-settings?view=msvc-170#cmake-variables-and-cache) for details + - Select `Manage Configurations...` in the combobox + - Specify the following CMake variable: `ENABLE_CCACHE=ON` + - See the [Visual Studio documentation](https://learn.microsoft.com/en-us/cpp/build/customize-cmake-settings?view=msvc-170#cmake-variables-and-cache) for details - 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! ### Compile VCMI with MinGW via MSYS2 -- Install MSYS2 from https://www.msys2.org/ + +- Install MSYS2 from - Start the `MSYS MinGW x64`-shell - Install dependencies: `pacman -S mingw-w64-x86_64-SDL2 mingw-w64-x86_64-SDL2_image mingw-w64-x86_64-SDL2_mixer mingw-w64-x86_64-SDL2_ttf mingw-w64-x86_64-boost mingw-w64-x86_64-gcc mingw-w64-x86_64-ninja mingw-w64-x86_64-qt5-static mingw-w64-x86_64-qt5-tools mingw-w64-x86_64-tbb` - Generate and build solution from VCMI-root dir: `cmake --preset windows-mingw-release && cmake --build --preset windows-mingw-release` @@ -134,8 +142,10 @@ Vcpkg might be very unstable due to limited popularity and fact of using bleedin 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. -#$# Build is successful but can not start new game +### 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\` diff --git a/docs/developers/Building_iOS.md b/docs/developers/Building_iOS.md index a922e44a1..37591f212 100644 --- a/docs/developers/Building_iOS.md +++ b/docs/developers/Building_iOS.md @@ -6,7 +6,8 @@ 2. Xcode: 3. CMake 3.21+: `brew install --cask cmake` or get from 4. Optional: - - CCache to speed up recompilation: `brew install ccache` + +- CCache to speed up recompilation: `brew install ccache` ## Obtaining source code diff --git a/docs/developers/Building_macOS.md b/docs/developers/Building_macOS.md index 71a1ae644..916813dfe 100644 --- a/docs/developers/Building_macOS.md +++ b/docs/developers/Building_macOS.md @@ -91,7 +91,7 @@ Open `VCMI.xcodeproj` from the build directory, select `vcmiclient` scheme and h ## Packaging project into DMG file -After building, run `cpack` from the build directory. If using Xcode generator, also pass `-C ` with the same configuration that you used to build the project. +After building, run `cpack` from the build directory. If using Xcode generator, also pass `-C` with the same configuration that you used to build the project. If you use Conan, it's expected that you use **conan-generated** directory at step 4 of [Conan package manager](Conan.md). diff --git a/docs/developers/CMake.md b/docs/developers/CMake.md index 140d7ef89..4295bef1b 100644 --- a/docs/developers/CMake.md +++ b/docs/developers/CMake.md @@ -1,23 +1,21 @@ # CMake options * `-D CMAKE_BUILD_TYPE=Debug` - * Enables debug info and disables optimizations + * Enables debug info and disables optimizations * `-D CMAKE_EXPORT_COMPILE_COMMANDS=ON` - * Creates `compile_commands.json` for [clangd](https://clangd.llvm.org/) language server. - - For clangd to find the JSON, create a file named `.clangd` with this content - ``` - CompileFlags: - CompilationDatabase: build - ``` - and place it here: - ``` - . - ├── vcmi -> contains sources and is under git control - ├── build -> contains build output, makefiles, object files,... - └── .clangd - ``` + * Creates `compile_commands.json` for [clangd](https://clangd.llvm.org/) language server. For clangd to find the JSON, create a file named `.clangd` with this content + ``` + CompileFlags: + CompilationDatabase: build + ``` + and place it here: + ``` + . + ├── vcmi -> contains sources and is under git control + ├── build -> contains build output, makefiles, object files,... + └── .clangd + ``` * `-D ENABLE_CCACHE:BOOL=ON` - * Speeds up recompilation + * Speeds up recompilation * `-G Ninja` - * Use Ninja build system instead of Make, which speeds up the build and doesn't require a `-j` flag \ No newline at end of file + * Use Ninja build system instead of Make, which speeds up the build and doesn't require a `-j` flag diff --git a/docs/developers/Code_Structure.md b/docs/developers/Code_Structure.md index 9f3e2c802..ee3384670 100644 --- a/docs/developers/Code_Structure.md +++ b/docs/developers/Code_Structure.md @@ -29,9 +29,10 @@ Most of VCMI configuration files uses Json format and located in "config" direct ### Main purposes of client Client is responsible for: -- displaying state of game to human player -- capturing player's actions and sending requests to server -- displaying changes in state of game indicated by server + +- displaying state of game to human player +- capturing player's actions and sending requests to server +- displaying changes in state of game indicated by server ### Rendering of graphics @@ -44,9 +45,9 @@ In rendering, Interface object system is quite helpful. Its base is CIntObject c Server is responsible for: -- maintaining state of the game -- handling requests from all clients participating in game -- informing all clients about changes in state of the game that are +- maintaining state of the game +- handling requests from all clients participating in game +- informing all clients about changes in state of the game that are visible to them ## Lib @@ -59,11 +60,11 @@ iOS platform pioneered single process build, where server is a static library an Lib contains code responsible for: -- handling most of Heroes III files (.lod, .txt setting files) -- storing information common to server and client like state of the game -- managing armies, buildings, artifacts, spells, bonuses and other game objects -- handling general game mechanics and related actions (only adventure map objects; it's an unwanted remnant of past development - all game mechanics should be handled by the server) -- networking and serialization +- handling most of Heroes III files (.lod, .txt setting files) +- storing information common to server and client like state of the game +- managing armies, buildings, artifacts, spells, bonuses and other game objects +- handling general game mechanics and related actions (only adventure map objects; it's an unwanted remnant of past development - all game mechanics should be handled by the server) +- networking and serialization #### Serialization @@ -94,7 +95,6 @@ Forward declarations of the lib in headers of other parts of the project need to `` `` - ##### New project part If you're creating new project part, place `VCMI_LIB_USING_NAMESPACE` in its `StdInc.h` to be able to use lib classes without explicit namespace in implementation files. Example: @@ -121,4 +121,4 @@ VCMI includes [FuzzyLite](http://code.google.com/p/fuzzy-lite/) library to make ### Duels -### ERM parser \ No newline at end of file +### ERM parser diff --git a/docs/developers/Coding_Guidelines.md b/docs/developers/Coding_Guidelines.md index 89bad05a6..5c1706cc3 100644 --- a/docs/developers/Coding_Guidelines.md +++ b/docs/developers/Coding_Guidelines.md @@ -4,7 +4,7 @@ VCMI implementation bases on C++17 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. -Any compiler supporting C++17 should work, but this has not been thoroughly tested. You can find information about extensions and compiler support at http://en.cppreference.com/w/cpp/compiler_support +Any compiler supporting C++17 should work, but this has not been thoroughly tested. You can find information about extensions and compiler support at ## Style Guidelines @@ -20,7 +20,7 @@ Inside a code block put the opening brace on the next line after the current sta Good: -``` cpp +```cpp if(a) { code(); @@ -30,7 +30,7 @@ if(a) Bad: -``` cpp +```cpp if(a) { code(); code(); @@ -41,14 +41,14 @@ Avoid using unnecessary open/close braces, vertical space is usually limited: Good: -``` cpp +```cpp if(a) code(); ``` Bad: -``` cpp +```cpp if(a) { code(); } @@ -58,7 +58,7 @@ Unless there are either multiple hierarchical conditions being used or that the Good: -``` cpp +```cpp if(a) { if(b) @@ -68,7 +68,7 @@ if(a) Bad: -``` cpp +```cpp if(a) if(b) code(); @@ -78,7 +78,7 @@ If there are brackets inside the body, outside brackets are required. Good: -``` cpp +```cpp if(a) { for(auto elem : list) @@ -90,7 +90,7 @@ if(a) Bad: -``` cpp +```cpp if(a) for(auto elem : list) { @@ -102,7 +102,7 @@ If "else" branch has brackets then "if" should also have brackets even if it is Good: -``` cpp +```cpp if(a) { code(); @@ -118,7 +118,7 @@ else Bad: -``` cpp +```cpp if(a) code(); else @@ -134,7 +134,7 @@ If you intentionally want to avoid usage of "else if" and keep if body indent ma Good: -``` cpp +```cpp if(a) { code(); @@ -148,7 +148,7 @@ else Bad: -``` cpp +```cpp if(a) code(); else @@ -160,7 +160,7 @@ When defining a method, use a new line for the brace, like this: Good: -``` cpp +```cpp void method() { } @@ -168,7 +168,7 @@ void method() Bad: -``` cpp +```cpp void Method() { } ``` @@ -179,14 +179,14 @@ Use white space in expressions liberally, except in the presence of parenthesis. **Good:** -``` cpp +```cpp if(a + 5 > method(blah('a') + 4)) foo += 24; ``` **Bad:** -``` cpp +```cpp if(a+5>method(blah('a')+4)) foo+=24; ``` @@ -199,13 +199,13 @@ Use a space before and after the address or pointer character in a pointer decla Good: -``` cpp +```cpp CIntObject * images[100]; ``` Bad: -``` cpp +```cpp CIntObject* images[100]; or CIntObject *images[100]; ``` @@ -214,14 +214,14 @@ Do not use spaces before parentheses. Good: -``` cpp +```cpp if(a) code(); ``` Bad: -``` cpp +```cpp if (a) code(); ``` @@ -230,7 +230,7 @@ Do not use extra spaces around conditions inside parentheses. Good: -``` cpp +```cpp if(a && b) code(); @@ -240,7 +240,7 @@ if(a && (b || c)) Bad: -``` cpp +```cpp if( a && b ) code(); @@ -252,14 +252,14 @@ Do not use more than one space between operators. Good: -``` cpp +```cpp if((a && b) || (c + 1 == d)) code(); ``` Bad: -``` cpp +```cpp if((a && b) || (c + 1 == d)) code(); @@ -273,14 +273,14 @@ When allocating objects, don't use parentheses for creating stack-based objects Good: -``` cpp +```cpp std::vector v; CGBoat btn = new CGBoat(); ``` Bad: -``` cpp +```cpp std::vector v(); // shouldn't compile anyway CGBoat btn = new CGBoat; ``` @@ -289,14 +289,14 @@ Avoid overuse of parentheses: Good: -``` cpp +```cpp if(a && (b + 1)) return c == d; ``` Bad: -``` cpp +```cpp if((a && (b + 1))) return (c == d); ``` @@ -305,7 +305,7 @@ if((a && (b + 1))) Base class list must be on same line with class name. -``` cpp +```cpp class CClass : public CClassBaseOne, public CClassBaseOne { int id; @@ -321,7 +321,7 @@ When 'private:', 'public:' and other labels are not on the line after opening br Good: -``` cpp +```cpp class CClass { int id; @@ -333,7 +333,7 @@ public: Bad: -``` cpp +```cpp class CClass { int id; @@ -344,7 +344,7 @@ public: Good: -``` cpp +```cpp class CClass { protected: @@ -357,7 +357,7 @@ public: Bad: -``` cpp +```cpp class CClass { @@ -373,7 +373,7 @@ public: Constructor member and base class initialization must be on new line, indented with tab with leading colon. -``` cpp +```cpp CClass::CClass() : CClassBaseOne(true, nullptr), id(0), bool parameters(false) { @@ -387,7 +387,7 @@ Switch statements have the case at the same indentation as the switch. Good: -``` cpp +```cpp switch(alignment) { case EAlignment::EVIL: @@ -407,7 +407,7 @@ default: Bad: -``` cpp +```cpp switch(alignment) { case EAlignment::EVIL: @@ -447,7 +447,7 @@ break; Good: -``` cpp +```cpp auto lambda = [this, a, &b](int3 & tile, int index) -> bool { do_that(); @@ -456,7 +456,7 @@ auto lambda = [this, a, &b](int3 & tile, int index) -> bool Bad: -``` cpp +```cpp auto lambda = [this,a,&b](int3 & tile, int index)->bool{do_that();}; ``` @@ -464,7 +464,7 @@ Empty parameter list is required even if function takes no arguments. Good: -``` cpp +```cpp auto lambda = []() { do_that(); @@ -473,7 +473,7 @@ auto lambda = []() Bad: -``` cpp +```cpp auto lambda = [] { do_that(); @@ -484,7 +484,7 @@ Do not use inline lambda expressions inside if-else, for and other conditions. Good: -``` cpp +```cpp auto lambda = []() { do_that(); @@ -497,7 +497,7 @@ if(lambda) Bad: -``` cpp +```cpp if([]() { do_that(); @@ -511,7 +511,7 @@ Do not pass inline lambda expressions as parameter unless it's the last paramete Good: -``` cpp +```cpp auto lambda = []() { do_that(); @@ -521,7 +521,7 @@ obj->someMethod(lambda, true); Bad: -``` cpp +```cpp obj->someMethod([]() { do_that(); @@ -530,7 +530,7 @@ obj->someMethod([]() Good: -``` cpp +```cpp obj->someMethod(true, []() { do_that(); @@ -543,7 +543,7 @@ Serialization of each element must be on it's own line since this make debugging Good: -``` cpp +```cpp template void serialize(Handler & h, const int version) { h & identifier; @@ -555,7 +555,7 @@ template void serialize(Handler & h, const int version) Bad: -``` cpp +```cpp template void serialize(Handler & h, const int version) { h & identifier & description & name & dependencies; @@ -566,7 +566,7 @@ Save backward compatibility code is exception when extra brackets are always use Good: -``` cpp +```cpp template void serialize(Handler & h, const int version) { h & identifier; @@ -586,7 +586,7 @@ template void serialize(Handler & h, const int version) Bad: -``` cpp +```cpp template void serialize(Handler & h, const int version) { h & identifier; @@ -604,7 +604,7 @@ template void serialize(Handler & h, const int version) For any new files, please paste the following info block at the very top of the source file: -``` cpp +```cpp /* * Name_of_File.h, part of VCMI engine * @@ -622,13 +622,13 @@ The above notice have to be included both in header and source files (.h/.cpp). For any header or source file code must be in following order: -1. Licensing information -2. pragma once preprocessor directive -3. include directives -4. Forward declarations -5. All other code +1. Licensing information +2. pragma once preprocessor directive +3. include directives +4. Forward declarations +5. All other code -``` cpp +```cpp /* * Name_of_File.h, part of VCMI engine * @@ -652,7 +652,7 @@ If you comment on the same line with code there must be one single space between Good: -``` cpp +```cpp if(a) { code(); //Do something @@ -665,7 +665,7 @@ else // Do something. Bad: -``` cpp +```cpp if(a) { code();//Do something @@ -680,7 +680,7 @@ If you add single-line comment on own line slashes must have same indent as code Good: -``` cpp +```cpp // Do something if(a) { @@ -692,7 +692,7 @@ if(a) Bad: -``` cpp +```cpp // Do something if(a) { @@ -706,7 +706,7 @@ Avoid comments inside multi-line if-else conditions. If your conditions are too Good: -``` cpp +```cpp bool isMyHeroAlive = a && b || (c + 1 > 15); bool canMyHeroMove = myTurn && hero.movePoints > 0; if(isMyHeroAlive && canMyHeroMove) @@ -717,7 +717,7 @@ if(isMyHeroAlive && canMyHeroMove) Bad: -``` cpp +```cpp if((a && b || (c + 1 > 15)) //Check if hero still alive && myTurn && hero.movePoints > 0) //Check if hero can move { @@ -727,7 +727,7 @@ if((a && b || (c + 1 > 15)) //Check if hero still alive 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: ///. -``` cpp +```cpp /// Returns true if a debug/trace log message will be logged, false if not. /// Useful if performance is important and concatenating the log message is a expensive task. bool isDebugEnabled() const; @@ -738,7 +738,7 @@ The above example doesn't follow a strict scheme on how to comment a method. It If you need a more detailed description for a method you can use such style: -``` cpp +```cpp /// /// /// @@ -749,7 +749,7 @@ If you need a more detailed description for a method you can use such style: /// @return Description of the return value ``` -A good essay about writing comments: http://ardalis.com/when-to-comment-your-code +A good essay about writing comments: ### Casing @@ -775,7 +775,7 @@ Outdated. There is separate entry for [Logging API](Logging_API.md) 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: -``` cpp +```cpp LOG_TRACE_PARAMS(logGlobal, "hero '%s', spellId '%d', pos '%s'.", hero, spellId, pos); ``` @@ -797,14 +797,14 @@ Do not use uncommon abbreviations for class, method, parameter and global object Bad: -``` cpp +```cpp CArt * getRandomArt(...) class CIntObject ``` Good: -``` cpp +```cpp CArtifact * getRandomArtifact(...) class CInterfaceObject ``` @@ -827,7 +827,7 @@ The header StdInc.h should be included in every compilation unit. It has to be i 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: -``` cpp +```cpp enum class EAlignment { GOOD, @@ -848,7 +848,7 @@ namespace EAlignment If the comment duplicates the name of commented member, it's better if it wouldn't exist at all. It just increases maintenance cost. Bad: -``` cpp +```cpp size_t getHeroesCount(); //gets count of heroes (surprise?) ``` @@ -862,16 +862,16 @@ Don't return const objects or primitive types from functions -- it's pointless. Bad: -``` cpp +```cpp const std::vector guardingCreatures(int3 pos) const; ``` Good: -``` cpp +```cpp std::vector guardingCreatures(int3 pos) const; ``` ## Sources -[Mono project coding guidelines](http://www.mono-project.com/Coding_Guidelines) \ No newline at end of file +[Mono project coding guidelines](http://www.mono-project.com/Coding_Guidelines) diff --git a/docs/developers/Conan.md b/docs/developers/Conan.md index 8c754ce46..fb3ec206e 100644 --- a/docs/developers/Conan.md +++ b/docs/developers/Conan.md @@ -27,7 +27,7 @@ The following platforms are supported and known to work, others might require ch - **Windows**: libraries are built with x86_64-mingw-w64-gcc version 10 (which is available in repositories of Ubuntu 22.04) - **Android**: libraries are built with NDK r25c (25.2.9519653) -2. Download the binaries archive and unpack it to `~/.conan` directory from https://github.com/vcmi/vcmi-dependencies/releases/latest +2. Download the binaries archive and unpack it to `~/.conan` directory from - macOS: pick **dependencies-mac-intel.txz** if you have Intel Mac, otherwise - **dependencies-mac-arm.txz** - iOS: pick ***dependencies-ios.txz*** @@ -65,7 +65,7 @@ If you use `--build=never` and this command fails, then it means that you can't 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/1/reference/commands/consumer/install.html) or by executing `conan help install`. +*Note*: you can find full reference of this command [in the official documentation](https://docs.conan.io/1/reference/commands/consumer/install.html) or by executing `conan help install`. ### Using our prebuilt binaries for macOS/iOS @@ -86,7 +86,7 @@ This subsection describes platform specifics to build libraries from source prop #### Building for macOS/iOS -- To build Locale module of Boost in versions >= 1.81, you must use `compiler.cppstd=11` Conan setting (our profiles already contain it). To use it with another profile, either add this setting to your _host_ profile or pass `-s compiler.cppstd=11` on the command line. +- To build Locale module of Boost in versions >= 1.81, you must use `compiler.cppstd=11` Conan setting (our profiles already contain it). To use it with another profile, either add this setting to your *host* profile or pass `-s compiler.cppstd=11` on the command line. - If you wish to build dependencies against system libraries (like our prebuilt ones do), follow [below instructions](#using-recipes-for-system-libraries) executing `conan create` for all directories. Don't forget to pass `-o with_apple_system_libs=True` to `conan install` afterwards. #### Building for Android @@ -105,11 +105,11 @@ After applying patch(es): 2. Run `make` 3. Copy file `qtbase/jar/QtAndroid.jar` from the build directory to the **package directory**, e.g. `~/.conan/data/qt/5.15.14/_/_/package/SOME_HASH/jar`. -_Note_: if you plan to build Qt from source again, then you don't need to perform the above _After applying patch(es)_ steps after building. +*Note*: if you plan to build Qt from source again, then you don't need to perform the above *After applying patch(es)* steps after building. ##### Using recipes for system libraries -1. Clone/download https://github.com/kambala-decapitator/conan-system-libs +1. Clone/download 2. Execute `conan create PACKAGE vcmi/CHANNEL`, where `PACKAGE` is a directory path in that repository and `CHANNEL` is **apple** for macOS/iOS and **android** for Android. Do it for each library you need. 3. Now you can execute `conan install` to build all dependencies. diff --git a/docs/developers/Development_with_Qt_Creator.md b/docs/developers/Development_with_Qt_Creator.md index 4e3c96f8e..8f71b4387 100644 --- a/docs/developers/Development_with_Qt_Creator.md +++ b/docs/developers/Development_with_Qt_Creator.md @@ -6,7 +6,7 @@ Qt Creator is the recommended IDE for VCMI development on Linux distributions, b - Almost no manual configuration when used with CMake. Project configuration is read from CMake text files, - Easy to setup and use with multiple different compiler toolchains: GCC, Visual Studio, Clang -You can install Qt Creator from repository, but better to stick to latest version from Qt website: https://www.qt.io/download-qt-installer-oss +You can install Qt Creator from repository, but better to stick to latest version from Qt website: ## Configuration @@ -21,4 +21,4 @@ The build dir should be set to something like /trunk/build for the debug build a There is a problem with QtCreator when debugging both vcmiclient and vcmiserver. If you debug the vcmiclient, start a game, attach the vcmiserver process to the gdb debugger(Debug \> Start Debugging \> Attach to Running External Application...) then breakpoints which are set for vcmiserver will be ignored. This looks like a bug, in any case it's not intuitively. Two workarounds are available luckily: 1. Run vcmiclient (no debug mode), then attach server process to the debugger -2. Open two instances of QtCreator and debug vcmiserver and vcmiclient separately(it works!) \ No newline at end of file +2. Open two instances of QtCreator and debug vcmiserver and vcmiclient separately(it works!) diff --git a/docs/developers/Logging_API.md b/docs/developers/Logging_API.md index a3ce23b76..ec8bc1df0 100644 --- a/docs/developers/Logging_API.md +++ b/docs/developers/Logging_API.md @@ -2,14 +2,14 @@ ## Features -- A logger belongs to a "domain", this enables us to change log level settings more selectively -- The log format can be customized -- The color of a log entry can be customized based on logger domain and logger level -- Logger settings can be changed in the settings.json file -- No std::endl at the end of a log entry required -- Thread-safe -- Macros for tracing the application flow -- Provides stream-like and function-like logging +- A logger belongs to a "domain", this enables us to change log level settings more selectively +- The log format can be customized +- The color of a log entry can be customized based on logger domain and logger level +- Logger settings can be changed in the settings.json file +- No std::endl at the end of a log entry required +- Thread-safe +- Macros for tracing the application flow +- Provides stream-like and function-like logging ## Class diagram @@ -17,14 +17,14 @@ Some notes: -- There are two methods `configure` and `configureDefault` of the class `CBasicLogConfigurator` to initialize and setup the logging system. The latter one setups default logging and isn't dependent on VCMI's filesystem, whereas the first one setups logging based on the user's settings which can be configured in the settings.json. -- The methods `isDebugEnabled` and `isTraceEnabled` return true if a log record of level debug respectively trace will be logged. This can be useful if composing the log message is a expensive task and performance is important. +- There are two methods `configure` and `configureDefault` of the class `CBasicLogConfigurator` to initialize and setup the logging system. The latter one setups default logging and isn't dependent on VCMI's filesystem, whereas the first one setups logging based on the user's settings which can be configured in the settings.json. +- The methods `isDebugEnabled` and `isTraceEnabled` return true if a log record of level debug respectively trace will be logged. This can be useful if composing the log message is a expensive task and performance is important. ## Usage ### Setup settings.json -``` javascript +``` jsonc { "logging" : { "console" : { @@ -87,6 +87,7 @@ global -\> info ### How to get a logger There exist only one logger object per domain. A logger object cannot be copied. You can get access to a logger object by using the globally defined ones like `logGlobal` or `logAi`, etc... or by getting one manually: + ```cpp Logger * logger = CLogger::getLogger(CLoggerDomain("rmg")); ``` @@ -104,22 +105,22 @@ Don't include a '\n' or std::endl at the end of your log message, a new line wil The following list shows several log levels from the highest one to the lowest one: -- error -\> for errors, e.g. if resource is not available, if a initialization fault has occurred, if a exception has been thrown (can result in program termination) -- warn -\> for warnings, e.g. if sth. is wrong, but the program can continue execution "normally" -- info -\> informational messages, e.g. Filesystem initialized, Map loaded, Server started, etc... -- debug -\> for debugging, e.g. hero moved to (12,3,0), direction 3', 'following artifacts influence X: .. or pattern detected at pos (10,15,0), p-nr. 30, flip 1, repl. 'D' -- trace -\> for logging the control flow, the execution progress or fine-grained events, e.g. hero movement completed, entering CMapEditManager::updateTerrainViews: posx '10', posy '5', width '10', height '10', mapLevel '0',... +- error -\> for errors, e.g. if resource is not available, if a initialization fault has occurred, if a exception has been thrown (can result in program termination) +- warn -\> for warnings, e.g. if sth. is wrong, but the program can continue execution "normally" +- info -\> informational messages, e.g. Filesystem initialized, Map loaded, Server started, etc... +- debug -\> for debugging, e.g. hero moved to (12,3,0), direction 3', 'following artifacts influence X: .. or pattern detected at pos (10,15,0), p-nr. 30, flip 1, repl. 'D' +- trace -\> for logging the control flow, the execution progress or fine-grained events, e.g. hero movement completed, entering CMapEditManager::updateTerrainViews: posx '10', posy '5', width '10', height '10', mapLevel '0',... The following colors are available for console output: -- default -- green -- red -- magenta -- yellow -- white -- gray -- teal +- default +- green +- red +- magenta +- yellow +- white +- gray +- teal ### How to trace execution @@ -143,10 +144,10 @@ The program execution can be traced by using the macros TRACE_BEGIN, TRACE_END a A domain is a specific part of the software. In VCMI there exist several domains: -- network -- ai -- bonus -- network +- network +- ai +- bonus +- network In addition to these domains, there exist always a super domain called "global". Sub-domains can be created with "ai.battle" or "ai.adventure" for example. The dot between the "ai" and "battle" is important and notes the parent-child relationship of those two domains. A few examples how the log level will be inherited: diff --git a/docs/developers/Lua_Scripting_System.md b/docs/developers/Lua_Scripting_System.md index 16124c800..bfd994cb7 100644 --- a/docs/developers/Lua_Scripting_System.md +++ b/docs/developers/Lua_Scripting_System.md @@ -2,7 +2,7 @@ ## Configuration -``` javascript +``` jsonc { //general purpose script, Lua or ERM, runs on server "myScript": @@ -87,75 +87,75 @@ VCMI uses LuaJIT, which is Lua 5.1 API, see [upstream documentation](https://www Following libraries are supported -- base -- table -- string -- math -- bit +- base +- table +- string +- math +- bit ## ERM ### Features -- no strict limit on function/variable numbers (technical limit 32 bit integer except 0)) -- TODO semi compare -- DONE macros +- no strict limit on function/variable numbers (technical limit 32 bit integer except 0)) +- TODO semi compare +- DONE macros ### Bugs -- TODO Broken XOR support (clashes with \`X\` option) +- TODO Broken XOR support (clashes with \`X\` option) ### Triggers -- TODO **!?AE** Equip/Unequip artifact -- WIP **!?BA** when any battle occurs -- WIP **!?BF** when a battlefield is prepared for a battle -- TODO **!?BG** at every action taken by any stack or by the hero -- TODO **!?BR** at every turn of a battle -- *!?CM (client only) click the mouse button.* -- TODO **!?CO** Commander triggers -- TODO **!?DL** Custom dialogs -- DONE **!?FU** function -- TODO **!?GE** "global" event -- TODO **!?GM** Saving/Loading -- TODO **!?HE** when the hero \# is attacked by an enemy hero or +- TODO **!?AE** Equip/Unequip artifact +- WIP **!?BA** when any battle occurs +- WIP **!?BF** when a battlefield is prepared for a battle +- TODO **!?BG** at every action taken by any stack or by the hero +- TODO **!?BR** at every turn of a battle +- *!?CM (client only) click the mouse button.* +- TODO **!?CO** Commander triggers +- TODO **!?DL** Custom dialogs +- DONE **!?FU** function +- TODO **!?GE** "global" event +- TODO **!?GM** Saving/Loading +- TODO **!?HE** when the hero \# is attacked by an enemy hero or visited by an allied hero -- TODO **!?HL** hero gains a level -- TODO **!?HM** every step a hero \# takes -- *!?IP Multiplayer support.* -- TODO **!?LE** (!$LE) An Event on the map -- WIP **!?MF** stack taking physical damage(before an action) -- TODO **!?MG** casting on the adventure map -- *!?MM scroll text during a battle* -- TODO **!?MR** Magic resistance -- TODO **!?MW** Wandering Monsters -- WIP **!?OB** (!$OB) visiting objects -- DONE **!?PI** Post Instruction. -- TODO **!?SN** Sound and ERA extensions -- *!?TH town hall* -- TODO **!?TL** Real-Time Timer -- TODO **!?TM** timed events +- TODO **!?HL** hero gains a level +- TODO **!?HM** every step a hero \# takes +- *!?IP Multiplayer support.* +- TODO **!?LE** (!$LE) An Event on the map +- WIP **!?MF** stack taking physical damage(before an action) +- TODO **!?MG** casting on the adventure map +- *!?MM scroll text during a battle* +- TODO **!?MR** Magic resistance +- TODO **!?MW** Wandering Monsters +- WIP **!?OB** (!$OB) visiting objects +- DONE **!?PI** Post Instruction. +- TODO **!?SN** Sound and ERA extensions +- *!?TH town hall* +- TODO **!?TL** Real-Time Timer +- TODO **!?TM** timed events ### Receivers #### VCMI -- **!!MC:S@varName@** - declare new "normal" variable (technically +- **!!MC:S@varName@** - declare new "normal" variable (technically v-var with string key) -- TODO Identifier resolver -- WIP Bonus system +- TODO Identifier resolver +- WIP Bonus system #### ERA -- DONE !!if !!el !!en -- TODO !!br !!co -- TODO !!SN:X +- DONE !!if !!el !!en +- TODO !!br !!co +- TODO !!SN:X #### WoG - TODO !!AR Артефакт (ресурс) в определенной позиции - TODO !!BA Битва - - !!BA:A$ return 1 for battle evaluation +- !!BA:A$ return 1 for battle evaluation - TODO !!BF Препятствия на поле боя - TODO !!BG Действий монстров в бою - TODO !!BH Действия героя в бою @@ -201,4 +201,4 @@ Following libraries are supported - *!#VC Контроль переменных* - WIP !!VR Установка переменных -### Persistence \ No newline at end of file +### Persistence diff --git a/docs/developers/Networking.md b/docs/developers/Networking.md index 5c3736abe..7d7b1c386 100644 --- a/docs/developers/Networking.md +++ b/docs/developers/Networking.md @@ -5,12 +5,14 @@ For implementation details see files located at `lib/network` directory. VCMI uses connection using TCP to communicate with server, even in single-player games. However, even though TCP is stream-based protocol, VCMI uses atomic messages for communication. Each message is a serialized stream of bytes, preceded by 4-byte message size: + ``` int32_t messageSize; byte messagePayload[messageSize]; ``` Networking can be used by: + - game client (vcmiclient / VCMI_Client.exe). Actual application that player interacts with directly using UI. - match server (vcmiserver / VCMI_Server.exe / part of game client). This app controls game logic and coordinates multiplayer games. - lobby server (vcmilobby). This app provides access to global lobby through which players can play game over Internet. @@ -28,11 +30,13 @@ For gameplay, VCMI serializes data into a binary stream. See [Serialization](Ser ## Global lobby communication For implementation details see: + - game client: `client/globalLobby/GlobalLobbyClient.h - match server: `server/GlobalLobbyProcessor.h - lobby server: `client/globalLobby/GlobalLobbyClient.h In case of global lobby, message payload uses plaintext json format - utf-8 encoded string: + ``` int32_t messageSize; char jsonString[messageSize]; @@ -43,6 +47,7 @@ Every message must be a struct (json object) that contains "type" field. Unlike ### Communication flow Notes: + - invalid message, such as corrupted json format or failure to validate message will result in no reply from server - in addition to specified messages, match server will send `operationFailed` message on failure to apply player request @@ -51,7 +56,8 @@ Notes: - client -> lobby: `clientRegister` - lobby -> client: `accountCreated` -#### Login +#### Login + - client -> lobby: `clientLogin` - lobby -> client: `loginSuccess` - lobby -> client: `chatHistory` @@ -59,10 +65,12 @@ Notes: - lobby -> client: `activeGameRooms` #### Chat Message + - client -> lobby: `sendChatMessage` - lobby -> every client: `chatMessage` #### New Game Room + - client starts match server instance - match -> lobby: `serverLogin` - lobby -> match: `loginSuccess` @@ -73,19 +81,23 @@ Notes: - lobby -> every client: `activeGameRooms` #### Joining a game room + See [#Proxy mode](proxy-mode) #### Leaving a game room + - client closes connection to match server - match -> lobby: `leaveGameRoom` -#### Sending an invite: +#### Sending an invite + - client -> lobby: `sendInvite` - lobby -> target client: `inviteReceived` Note: there is no dedicated procedure to accept an invite. Instead, invited player will use same flow as when joining public game room #### Logout + - client closes connection - lobby -> every client: `activeAccounts` @@ -94,6 +106,7 @@ Note: there is no dedicated procedure to accept an invite. Instead, invited play In order to connect players located behind NAT, VCMI lobby can operate in "proxy" mode. In this mode, connection will be act as proxy and will transmit gameplay data from client to a match server, without any data processing on lobby server. Currently, process to establish connection using proxy mode is: + - Player attempt to join open game room using `joinGameRoom` message - Lobby server validates requests and on success - notifies match server about new player in lobby using control connection - Match server receives request, establishes new connection to game lobby, sends `serverProxyLogin` message to lobby server and immediately transfers this connection to VCMIServer class to use as connection for gameplay communication @@ -101,4 +114,4 @@ Currently, process to establish connection using proxy mode is: - Game client receives message and establishes own side of proxy connection - connects to lobby, sends `clientProxyLogin` message and transfers to ServerHandler class to use as connection for gameplay communication - Lobby server accepts new connection and moves it into a proxy mode - all packages that will be received by one side of this connection will be re-sent to another side without any processing. -Once the game is over (or if one side disconnects) lobby server will close another side of the connection and erase proxy connection \ No newline at end of file +Once the game is over (or if one side disconnects) lobby server will close another side of the connection and erase proxy connection diff --git a/docs/developers/RMG_Description.md b/docs/developers/RMG_Description.md index 59a6b683a..33dca93d7 100644 --- a/docs/developers/RMG_Description.md +++ b/docs/developers/RMG_Description.md @@ -74,4 +74,4 @@ For every zone, a few random obstacle sets are selected. [Details](https://githu ### Filling space -Tiles which need to be `blocked` but are not `used` are filled with obstacles. Largest obstacles which cover the most tiles are picked first, other than that they are chosen randomly. \ No newline at end of file +Tiles which need to be `blocked` but are not `used` are filled with obstacles. Largest obstacles which cover the most tiles are picked first, other than that they are chosen randomly. diff --git a/docs/developers/Serialization.md b/docs/developers/Serialization.md index 143eaf0ad..56b428f1e 100644 --- a/docs/developers/Serialization.md +++ b/docs/developers/Serialization.md @@ -140,7 +140,7 @@ CLoadFile/CSaveFile classes allow to read data to file and store data to file. T #### Networking -See [Networking](Networking.md) +See [Networking](Networking.md) ### Additional features @@ -259,4 +259,4 @@ Foo *loadedA, *loadedB; The feature recognizes pointers by addresses. Therefore it allows mixing pointers to base and derived classes. However, it does not allow serializing classes with multiple inheritance using a "non-first" base (other bases have a certain address offset from the actual object). -Pointer cycles are properly handled. This feature makes sense for savegames and is turned on for them. \ No newline at end of file +Pointer cycles are properly handled. This feature makes sense for savegames and is turned on for them. diff --git a/docs/maintainers/Project_Infrastructure.md b/docs/maintainers/Project_Infrastructure.md index a55e6ad41..3bf2bd562 100644 --- a/docs/maintainers/Project_Infrastructure.md +++ b/docs/maintainers/Project_Infrastructure.md @@ -9,30 +9,30 @@ So far we using following services: ### Most important - VCMI.eu domain paid until July of 2019. - - Owner: Tow - - Our main domain used by services. + - Owner: Tow + - Our main domain used by services. - VCMI.download paid until November of 2026. - - Owner: SXX - - Intended to be used for all assets downloads. - - Domain registered on GANDI and **can be renewed by anyone without access to account**. + - Owner: SXX + - Intended to be used for all assets downloads. + - Domain registered on GANDI and **can be renewed by anyone without access to account**. - [DigitalOcean](https://cloud.digitalocean.com/) team. - - Our hosting sponsor. - - Administrator access: SXX, Warmonger. - - User access: AVS, Tow. + - Our hosting sponsor. + - Administrator access: SXX, Warmonger. + - User access: AVS, Tow. - [CloudFlare](https://www.cloudflare.com/a/overview) account. - - Access through shared login / password. - - All of our infrastructure is behind CloudFlare and all our web. We manage our DNS there. + - Access through shared login / password. + - All of our infrastructure is behind CloudFlare and all our web. We manage our DNS there. - [Google Apps (G Suite)](https://admin.google.com/) account. - - It's only for vcmi.eu domain and limited to 5 users. Each account has limit of 500 emails / day. - - One administrative email used for other services registration. - - "noreply" email used for outgoing mail on Wiki and Bug Tracker. - - "forum" email used for outgoing mail on Forums. Since we authenticate everyone through forum it's should be separate email. - - Administrator access: Tow, SXX. -- [Google Play Console](https://play.google.com/apps/publish/) account. - - Hold ownership over VCMI Android App. - - Owner: SXX - - Administrator access: Warmonger, AVS, Ivan. - - Release manager access: Fay. + - It's only for vcmi.eu domain and limited to 5 users. Each account has limit of 500 emails / day. + - One administrative email used for other services registration. + - "noreply" email used for outgoing mail on Wiki and Bug Tracker. + - "forum" email used for outgoing mail on Forums. Since we authenticate everyone through forum it's should be separate email. +- Administrator access: Tow, SXX. + - [Google Play Console](https://play.google.com/apps/publish/) account. + - Hold ownership over VCMI Android App. + - Owner: SXX + - Administrator access: Warmonger, AVS, Ivan. + - Release manager access: Fay. 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. @@ -41,20 +41,20 @@ Not all services let us safely share login credentials, but at least when possib We want to notify players about updates on as many social services as possible. - Facebook page: - - Administrator access: SXX, Warmonger + - Administrator access: SXX, Warmonger - Twitter account: - - Administrator access: SXX. - - User access via TweetDeck: -- VK / VKontakte page: - - Owner: SXX - - Administrator access: AVS + - Administrator access: SXX. +- User access via TweetDeck: + - VK / VKontakte page: +- Owner: SXX + - Administrator access: AVS - Steam group: - - Administrator access: SXX - - Moderator access: Dydzio -- Reddit: - - Administrator access: SXX -- ModDB entry: - - Administrator access: SXX + - Administrator access: SXX +- Moderator access: Dydzio + - Reddit: +- Administrator access: SXX + - ModDB entry: +- Administrator access: SXX ### Communication channels @@ -70,48 +70,46 @@ We want to notify players about updates on as many social services as possible. ### Other services - Launchpad PPA: - - Member access: AVS - - Administrator access: Ivan, SXX + - Member access: AVS + - Administrator access: Ivan, SXX - Snapcraft Dashboard: - - Administrator access: SXX + - Administrator access: SXX - Coverity Scan page: - - Administrator access: SXX, Warmonger, AVS + - Administrator access: SXX, Warmonger, AVS - OpenHub page: - - Administrator access: Tow + - Administrator access: Tow - Docker Hub organization: - - Administrator access: SXX + - Administrator access: SXX Reserve accounts for other code hosting services: - GitLab organization: - - Administrator access: SXX + - Administrator access: SXX - BitBucket organization: - - Administrator access: SXX + - Administrator access: SXX ## What's to improve -1. Encourage Tow to transfer VCMI.eu to GANDI so it's can be also renewed without access. -2. Use 2FA on CloudFlare and just ask everyone to get FreeOTP and then use shared secret. -3. Centralized way to post news about game updates to all social media. +1. Encourage Tow to transfer VCMI.eu to GANDI so it's can be also renewed without access. +2. Use 2FA on CloudFlare and just ask everyone to get FreeOTP and then use shared secret. +3. Centralized way to post news about game updates to all social media. -# Project Servers Configuration +## Project Servers Configuration This section dedicated to explain specific configurations of our servers for anyone who might need to improve it in future. -## Droplet configuration - -### Droplet and hosted services +### Droplet configuration Currently we using two droplets: - First one serve all of our web services: - - [Forum](https://forum.vcmi.eu/) - - [Bug tracker](https://bugs.vcmi.eu/) - - [Wiki](https://wiki.vcmi.eu/) - - [Slack invite page](https://slack.vcmi.eu/) + - [Forum](https://forum.vcmi.eu/) + - [Bug tracker](https://bugs.vcmi.eu/) + - [Wiki](https://wiki.vcmi.eu/) + - [Slack invite page](https://slack.vcmi.eu/) - Second serve downloads: - - [Legacy download page](http://download.vcmi.eu/) - - [Build download page](https://builds.vcmi.download/) + - [Legacy download page](http://download.vcmi.eu/) + - [Build download page](https://builds.vcmi.download/) To keep everything secure we should always keep binary downloads separate from any web services. @@ -131,4 +129,4 @@ We only expose floating IP that can be detached from droplet in case of emergenc - Address: beholder.vcmi.eu (67.207.75.182) - Port 22 serve SFTP for file uploads as well as CI artifacts uploads. -If new services added firewall rules can be adjusted in [DO control panel](https://cloud.digitalocean.com/networking/firewalls). \ No newline at end of file +If new services added firewall rules can be adjusted in [DO control panel](https://cloud.digitalocean.com/networking/firewalls). diff --git a/docs/maintainers/Release_Process.md b/docs/maintainers/Release_Process.md index 51d7a8e1a..d7b9446b5 100644 --- a/docs/maintainers/Release_Process.md +++ b/docs/maintainers/Release_Process.md @@ -1,12 +1,16 @@ # Release Process ## Versioning + For releases VCMI uses version numbering in form "1.X.Y", where: + - 'X' indicates major release. Different major versions are generally not compatible with each other. Save format is different, network protocol is different, mod format likely different. - 'Y' indicates hotfix release. Despite its name this is usually not urgent, but planned release. Different hotfixes for same major version are fully compatible with each other. ## Branches + Our branching strategy is very similar to GitFlow: + - `master` branch has release commits. One commit - one release. Each release commit should be tagged with version `1.X.Y` when corresponding version is released. State of master branch represents state of latest public release. - `beta` branch is for stabilization of ongoing release. Beta branch is created when new major release enters stabilization stage and is used for both major release itself as well as for subsequent hotfixes. Only changes that are safe, have minimal chance of regressions and improve player experience should be targeted into this branch. Breaking changes (e.g. save format changes) are forbidden in beta. - `develop` branch is a main branch for ongoing development. Pull requests with new features should be targeted to this branch, `develop` version is one major release ahead of `beta`. @@ -14,12 +18,14 @@ Our branching strategy is very similar to GitFlow: ## Release process step-by-step ### Initial release setup (major releases only) + Should be done immediately after start of stabilization stage for previous release - Create project named `Release 1.X` - Add all features and bugs that should be fixed as part of this release into this project ### Start of stabilization stage (major releases only) + Should be done 2 weeks before planned release date. All major features should be finished at this point. - Create `beta` branch from `develop` @@ -34,6 +40,7 @@ Should be done 2 weeks before planned release date. All major features should be - Bump version and build ID for Android on `beta` branch ### Release preparation stage + Should be done 1 week before release. Release date should be decided at this point. - Make sure to announce codebase freeze deadline (1 day before release) to all developers @@ -45,21 +52,23 @@ Should be done 1 week before release. Release date should be decided at this poi - - Update downloads counter in `docs/readme.md` ### Release preparation stage + Should be done 1 day before release. At this point beta branch is in full freeze. - Merge release preparation PR into `beta` - Merge `beta` into `master`. This will trigger CI pipeline that will generate release packages - Create draft release page, specify `1.x.y` as tag for `master` after publishing - Check that artifacts for all platforms have been built by CI on `master` branch -- Download and rename all build artifacts to use form "VCMI-1.X.Y-Platform.xxx" +- Download and rename all build artifacts to use form "VCMI-1.X.Y-Platform.xxx" - Attach build artifacts for all platforms to release page - Manually extract Windows installer, remove `$PLUGINSDIR` directory which contains installer files and repackage data as .zip archive - Attach produced zip archive to release page as an alternative Windows installer - Upload built AAB to Google Play and send created release draft for review (usually takes several hours) - Prepare pull request for [vcmi-updates](https://github.com/vcmi/vcmi-updates) -- (major releases only) Prepare pull request with release update for web site https://github.com/vcmi/VCMI.eu +- (major releases only) Prepare pull request with release update for web site ### Release publishing phase + Should be done on release date - Trigger builds for new release on Ubuntu PPA diff --git a/docs/maintainers/Ubuntu_PPA.md b/docs/maintainers/Ubuntu_PPA.md index 8ada53d86..1dbd6a7d0 100644 --- a/docs/maintainers/Ubuntu_PPA.md +++ b/docs/maintainers/Ubuntu_PPA.md @@ -1,6 +1,7 @@ # Ubuntu PPA ## Main links + - [Team](https://launchpad.net/~vcmi) - [Project](https://launchpad.net/vcmi) - [Sources](https://code.launchpad.net/~vcmi/vcmi/+git/vcmi) @@ -14,31 +15,42 @@ ## 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. +- 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) \ No newline at end of file + +- [alexvins](https://github.com/alexvins) () +- [ArseniyShestakov](https://github.com/ArseniyShestakov) () +- [IvanSavenko](https://github.com/IvanSavenko) () +- (Not member of VCMI, creator of PPA) () diff --git a/docs/modders/Animation_Format.md b/docs/modders/Animation_Format.md index 2aece5165..c9d2a48b6 100644 --- a/docs/modders/Animation_Format.md +++ b/docs/modders/Animation_Format.md @@ -2,13 +2,13 @@ VCMI allows overriding HoMM3 .def files with .json replacement. Compared to .def this format allows: -- Overriding individual frames from json file (e.g. icons) -- Modern graphics formats (targa, png - all formats supported by VCMI image loader) -- Does not requires any special tools - all you need is text editor and images. +- Overriding individual frames from json file (e.g. icons) +- Modern graphics formats (targa, png - all formats supported by VCMI image loader) +- Does not requires any special tools - all you need is text editor and images. ## Format description -``` javascript +``` jsonc { // Base path of all images in animation. Optional. // Can be used to avoid using long path to images @@ -58,12 +58,13 @@ VCMI allows overriding HoMM3 .def files with .json replacement. Compared to .def ### Replacing a button This json file will allow replacing .def file for a button with png images. Buttons require following images: + 1. Active state. Button is active and can be pressed by player 2. Pressed state. Player pressed button but have not released it yet 3. Blocked state. Button is blocked and can not be interacted with. Note that some buttons are never blocked and can be used without this image 4. Highlighted state. This state is used by only some buttons and only in some cases. For example, in main menu buttons will appear highlighted when mouse cursor is on top of the image. Another example is buttons that can be selected, such as settings that can be toggled on or off -```javascript +```jsonc "basepath" : "interface/MyButton", // all images are located in this directory "images" : @@ -80,7 +81,7 @@ This json file will allow replacing .def file for a button with png images. Butt This json file allows defining one animation sequence, for example for adventure map objects or for town buildings. -```javascript +```jsonc "basepath" : "myTown/myBuilding", // all images are located in this directory "sequences" : diff --git a/docs/modders/Bonus/Bonus_Duration_Types.md b/docs/modders/Bonus/Bonus_Duration_Types.md index 3c20d0e7c..c82448116 100644 --- a/docs/modders/Bonus/Bonus_Duration_Types.md +++ b/docs/modders/Bonus/Bonus_Duration_Types.md @@ -4,14 +4,14 @@ Bonus may have any of these durations. They acts in disjunction. ## List of all bonus duration types -- PERMANENT -- ONE_BATTLE: at the end of battle -- ONE_DAY: at the end of day -- ONE_WEEK: at the end of week (bonus lasts till the end of week, NOT 7 days) -- N_TURNS: used during battles, after battle bonus is always removed -- N_DAYS -- UNTIL_BEING_ATTACKED: removed after any damage-inflicting attack -- UNTIL_ATTACK: removed after attack and counterattacks are performed -- STACK_GETS_TURN: removed when stack gets its turn - used for defensive stance -- COMMANDER_KILLED -- UNTIL_OWN_ATTACK: removed after attack (not counterattack) is performed \ No newline at end of file +- PERMANENT +- ONE_BATTLE: at the end of battle +- ONE_DAY: at the end of day +- ONE_WEEK: at the end of week (bonus lasts till the end of week, NOT 7 days) +- N_TURNS: used during battles, after battle bonus is always removed +- N_DAYS +- UNTIL_BEING_ATTACKED: removed after any damage-inflicting attack +- UNTIL_ATTACK: removed after attack and counterattacks are performed +- STACK_GETS_TURN: removed when stack gets its turn - used for defensive stance +- COMMANDER_KILLED +- UNTIL_OWN_ATTACK: removed after attack (not counterattack) is performed diff --git a/docs/modders/Bonus/Bonus_Limiters.md b/docs/modders/Bonus/Bonus_Limiters.md index 5dc9ee46a..922f7327a 100644 --- a/docs/modders/Bonus/Bonus_Limiters.md +++ b/docs/modders/Bonus/Bonus_Limiters.md @@ -15,7 +15,7 @@ The limiters take no parameters: Example: -``` javascript +``` jsonc "limiters" : [ "SHOOTER_ONLY" ] ``` @@ -25,12 +25,12 @@ Example: Parameters: -- Bonus type -- (optional) bonus subtype -- (optional) bonus sourceType and sourceId in struct -- example: (from Adele's bless): +- Bonus type +- (optional) bonus subtype +- (optional) bonus sourceType and sourceId in struct +- example: (from Adele's bless): -``` javascript +``` jsonc "limiters" : [ { "type" : "HAS_ANOTHER_BONUS_LIMITER", @@ -50,20 +50,21 @@ Parameters: Parameters: -- Creature id (string) -- (optional) include upgrades - default is false +- Creature id (string) +- (optional) include upgrades - default is false ### CREATURE_ALIGNMENT_LIMITER Parameters: -- Alignment identifier +- Alignment identifier ### CREATURE_LEVEL_LIMITER If parameters is empty, level limiter works as CREATURES_ONLY limiter Parameters: + - Minimal level - Maximal level @@ -71,24 +72,24 @@ Parameters: Parameters: -- Faction identifier +- Faction identifier ### CREATURE_TERRAIN_LIMITER Parameters: -- Terrain identifier +- Terrain identifier Example: -``` javascript +``` jsonc "limiters": [ { "type":"CREATURE_TYPE_LIMITER", "parameters": [ "angel", true ] } ], ``` -``` javascript +``` jsonc "limiters" : [ { "type" : "CREATURE_TERRAIN_LIMITER", "parameters" : ["sand"] @@ -106,13 +107,13 @@ Parameters: The following limiters must be specified as the first element of a list, and operate on the remaining limiters in that list: -- allOf (default when no aggregate limiter is specified) -- anyOf -- noneOf +- allOf (default when no aggregate limiter is specified) +- anyOf +- noneOf Example: -``` javascript +``` jsonc "limiters" : [ "noneOf", "IS_UNDEAD", @@ -121,4 +122,4 @@ Example: "parameters" : [ "SIEGE_WEAPON" ] } ] -``` \ No newline at end of file +``` diff --git a/docs/modders/Bonus/Bonus_Propagators.md b/docs/modders/Bonus/Bonus_Propagators.md index 90f09cf84..2a3e93e20 100644 --- a/docs/modders/Bonus/Bonus_Propagators.md +++ b/docs/modders/Bonus/Bonus_Propagators.md @@ -2,9 +2,9 @@ ## Available propagators -- BATTLE_WIDE: Affects both sides during battle -- VISITED_TOWN_AND_VISITOR: Used with Legion artifacts (town visited by hero) -- PLAYER_PROPAGATOR: Bonus will affect all objects owned by player. Used by Statue of Legion. -- HERO: Bonus will be transferred to hero (for example from stacks in his army). -- TEAM_PROPAGATOR: Bonus will affect all objects owned by player and his allies. -- GLOBAL_EFFECT: This effect will influence all creatures, heroes and towns on the map. \ No newline at end of file +- BATTLE_WIDE: Affects both sides during battle +- VISITED_TOWN_AND_VISITOR: Used with Legion artifacts (town visited by hero) +- PLAYER_PROPAGATOR: Bonus will affect all objects owned by player. Used by Statue of Legion. +- HERO: Bonus will be transferred to hero (for example from stacks in his army). +- TEAM_PROPAGATOR: Bonus will affect all objects owned by player and his allies. +- GLOBAL_EFFECT: This effect will influence all creatures, heroes and towns on the map. diff --git a/docs/modders/Bonus/Bonus_Range_Types.md b/docs/modders/Bonus/Bonus_Range_Types.md index 5be67c077..c1aeef280 100644 --- a/docs/modders/Bonus/Bonus_Range_Types.md +++ b/docs/modders/Bonus/Bonus_Range_Types.md @@ -16,4 +16,4 @@ For replacing ONLY_ENEMY_ARMY alias, you should use the following parameters of "limiters" : [ "OPPOSITE_SIDE" ] ``` -If some propagators was set before, it was actually ignored and should be replaced to code above. And OPPOSITE_SIDE limiter should be first, if any other limiters exists. \ No newline at end of file +If some propagators was set before, it was actually ignored and should be replaced to code above. And OPPOSITE_SIDE limiter should be first, if any other limiters exists. diff --git a/docs/modders/Bonus/Bonus_Sources.md b/docs/modders/Bonus/Bonus_Sources.md index 86754e407..c23140132 100644 --- a/docs/modders/Bonus/Bonus_Sources.md +++ b/docs/modders/Bonus/Bonus_Sources.md @@ -19,4 +19,4 @@ - STACK_EXPERIENCE - COMMANDER - GLOBAL -- OTHER \ No newline at end of file +- OTHER diff --git a/docs/modders/Bonus/Bonus_Types.md b/docs/modders/Bonus/Bonus_Types.md index 5d36ec149..6f93dc68a 100644 --- a/docs/modders/Bonus/Bonus_Types.md +++ b/docs/modders/Bonus/Bonus_Types.md @@ -57,9 +57,9 @@ Bonus that does not account for propagation and gives extra resources per day wi Increases amount of movement points available to affected hero on new turn -- subtype: - - heroMovementLand: only land movement will be affected - - heroMovementSea: only sea movement will be affected +- subtype: + - heroMovementLand: only land movement will be affected + - heroMovementSea: only sea movement will be affected - val: number of movement points (100 points for a tile) ### WATER_WALKING @@ -158,7 +158,7 @@ Allows affected heroes to learn spells from each other during hero exchange Reduces movement points penalty when moving on terrains with movement cost over 100 points. Can not reduce movement cost below 100 points -- val: penalty reduction, in movement points per tile. +- val: penalty reduction, in movement points per tile. ### WANDERING_CREATURES_JOIN_BONUS @@ -346,8 +346,8 @@ Heroes affected by this bonus can not retreat or surrender in battle (Shackles o Negates all natural immunities for affected stacks. (Orb of Vulnerability) - subtype: - - immunityBattleWide: Entire battle will be affected by bonus - - immunityEnemyHero: Only enemy hero will be affected by bonus + - immunityBattleWide: Entire battle will be affected by bonus + - immunityEnemyHero: Only enemy hero will be affected by bonus ### OPENING_BATTLE_SPELL @@ -383,9 +383,9 @@ Increases movement speed of units in battle Increases base damage of creature in battle - subtype: - - creatureDamageMin: increases only minimal damage - - creatureDamageMax: increases only maximal damage - - creatureDamageBoth: increases both minimal and maximal damage + - creatureDamageMin: increases only minimal damage + - creatureDamageMax: increases only maximal damage + - creatureDamageBoth: increases both minimal and maximal damage - val: additional damage points ### SHOTS @@ -447,8 +447,8 @@ Affected units can not receive good or bad morale Affected unit can fly on the battlefield - subtype: - - movementFlying: creature will fly (slowly move across battlefield) - - movementTeleporting: creature will instantly teleport to destination, skipping movement animation. + - movementFlying: creature will fly (slowly move across battlefield) + - movementTeleporting: creature will instantly teleport to destination, skipping movement animation. ### SHOOTER @@ -525,19 +525,19 @@ Affected unit will ignore specified percentage of attacked unit defense (Behemot Affected units will receive reduced damage from attacks by other units - val: damage reduction, percentage -- subtype: - - damageTypeMelee: only melee damage will be reduced - - damageTypeRanged: only ranged damage will be reduced - - damageTypeAll: all damage will be reduced +- subtype: + - damageTypeMelee: only melee damage will be reduced + - damageTypeRanged: only ranged damage will be reduced + - damageTypeAll: all damage will be reduced ### PERCENTAGE_DAMAGE_BOOST Affected units will deal increased damage when attacking other units - val: damage increase, percentage -- subtype: - - damageTypeMelee: only melee damage will increased - - damageTypeRanged: only ranged damage will increased +- subtype: + - damageTypeMelee: only melee damage will increased + - damageTypeRanged: only ranged damage will increased ### GENERAL_ATTACK_REDUCTION @@ -576,18 +576,18 @@ Affected unit will never receive retaliations when attacking Affected unit will gain new creatures for each enemy killed by this unit - val: number of units gained per enemy killed -- subtype: - - soulStealPermanent: creature will stay after the battle - - soulStealBattle: creature will be lost after the battle +- subtype: + - soulStealPermanent: creature will stay after the battle + - soulStealBattle: creature will be lost after the battle ### TRANSMUTATION Affected units have chance to transform attacked unit to other creature type - val: chance for ability to trigger, percentage -- subtype: - - transmutationPerHealth: transformed unit will have same HP pool as original stack, - - transmutationPerUnit: transformed unit will have same number of units as original stack +- subtype: + - transmutationPerHealth: transformed unit will have same HP pool as original stack, + - transmutationPerUnit: transformed unit will have same number of units as original stack - addInfo: creature to transform to. If not set, creature will transform to same unit as attacker ### SUMMON_GUARDIANS @@ -613,10 +613,10 @@ Affected unit will attack units on all hexes that surround attacked hex Affected unit will retaliate before enemy attacks, if able -- subtype: - - damageTypeMelee: only melee attacks affected - - damageTypeRanged: only ranged attacks affected. Note that unit also requires ability to retaliate in ranged, such as RANGED_RETALIATION bonus - - damageTypeAll: any attacks are affected +- subtype: + - damageTypeMelee: only melee attacks affected + - damageTypeRanged: only ranged attacks affected. Note that unit also requires ability to retaliate in ranged, such as RANGED_RETALIATION bonus + - damageTypeAll: any attacks are affected ### SHOOTS_ALL_ADJACENT @@ -627,9 +627,9 @@ Affected unit will attack units on all hexes that surround attacked hex in range Affected unit will kills additional units after attack - val: chance to trigger, percentage -- subtype: - - destructionKillPercentage: kill percentage of units, - - destructionKillAmount: kill amount +- subtype: + - destructionKillPercentage: kill percentage of units, + - destructionKillAmount: kill amount - addInfo: amount or percentage to kill ### LIMITED_SHOOTING_RANGE @@ -669,6 +669,7 @@ Affected unit can attack walls during siege battles (Cyclops) ### CATAPULT_EXTRA_SHOTS Defines spell mastery level for spell used by CATAPULT bonus + - subtype: affected spell - val: spell mastery level to use @@ -760,18 +761,18 @@ Affected unit will deal additional damage after attack Affected unit will kill additional units after attack. Used for Death stare (Mighty Gorgon) ability and for Accurate Shot (Pirates, HotA) -- subtype: - - deathStareGorgon: only melee attack, random amount of killed units - - deathStareNoRangePenalty: only ranged attacks without obstacle (walls) or range penalty - - deathStareRangePenalty: only ranged attacks with range penalty - - deathStareObstaclePenalty: only ranged attacks with obstacle (walls) penalty - - deathStareRangeObstaclePenalty: only ranged attacks with both range and obstacle penalty - - deathStareCommander: fixed amount, both melee and ranged attacks -- val: - - for deathStareCommander: number of creatures to kill, total amount of killed creatures is (attacker level / defender level) \* val - - for all other subtypes: chance to kill, counted separately for each unit in attacking stack, percentage. At most (stack size \* chance) units can be killed at once, rounded up +- subtype: + - deathStareGorgon: only melee attack, random amount of killed units + - deathStareNoRangePenalty: only ranged attacks without obstacle (walls) or range penalty + - deathStareRangePenalty: only ranged attacks with range penalty + - deathStareObstaclePenalty: only ranged attacks with obstacle (walls) penalty + - deathStareRangeObstaclePenalty: only ranged attacks with both range and obstacle penalty + - deathStareCommander: fixed amount, both melee and ranged attacks +- val: + - for deathStareCommander: number of creatures to kill, total amount of killed creatures is (attacker level / defender level) \* val + - for all other subtypes: chance to kill, counted separately for each unit in attacking stack, percentage. At most (stack size \* chance) units can be killed at once, rounded up - addInfo: - - SpellID to be used as hit effect. If not set - 'deathStare' spell will be used. If set to "accurateShot" battle log messages will use alternative description + - SpellID to be used as hit effect. If not set - 'deathStare' spell will be used. If set to "accurateShot" battle log messages will use alternative description ### SPECIAL_CRYSTAL_GENERATION @@ -816,9 +817,9 @@ Determines how many times per combat affected creature can cast its targeted spe - subtype - spell id, eg. spell.iceBolt - value - chance (percent) - additional info - \[X, Y, Z\] - - X - spell mastery level (1 - Basic, 3 - Expert) - - Y = 0 - all attacks, 1 - shot only, 2 - melee only - - Z (optional) - layer for multiple SPELL_AFTER_ATTACK bonuses and multi-turn casting. Empty or value less than 0 = not participating in layering. + - X - spell mastery level (1 - Basic, 3 - Expert) + - Y = 0 - all attacks, 1 - shot only, 2 - melee only + - Z (optional) - layer for multiple SPELL_AFTER_ATTACK bonuses and multi-turn casting. Empty or value less than 0 = not participating in layering. When enabled - spells from specific layer will not be cast until target has all spells from previous layer on him. Spell from last layer is on repeat if none of spells on lower layers expired. ### SPELL_BEFORE_ATTACK @@ -826,12 +827,12 @@ Determines how many times per combat affected creature can cast its targeted spe - subtype - spell id - value - chance % - additional info - \[X, Y, Z\] - - X - spell mastery level (1 - Basic, 3 - Expert) - - Y = 0 - all attacks, 1 - shot only, 2 - melee only - - Z (optional) - layer for multiple SPELL_BEFORE_ATTACK bonuses and multi-turn casting. Empty or value less than 0 = not participating in layering. + - X - spell mastery level (1 - Basic, 3 - Expert) + - Y = 0 - all attacks, 1 - shot only, 2 - melee only + - Z (optional) - layer for multiple SPELL_BEFORE_ATTACK bonuses and multi-turn casting. Empty or value less than 0 = not participating in layering. When enabled - spells from specific layer will not be cast until target has all spells from previous layer on him. Spell from last layer is on repeat if none of spells on lower layers expired. -### SPECIFIC_SPELL_POWER +### SPECIFIC_SPELL_POWER - value: Used for Thunderbolt and Resurrection cast by units (multiplied by stack size). Also used for Healing secondary skill (for core:spell.firstAid used by First Aid tent) - subtype - spell id @@ -842,16 +843,16 @@ Determines how many times per combat affected creature can cast its targeted spe ### CREATURE_ENCHANT_POWER - - val: Total duration of spells cast by creature, in turns +- val: Total duration of spells cast by creature, in turns ### REBIRTH Affected stack will resurrect after death -- val - percent of total stack HP restored, not rounded. For instance, when 4 Phoenixes with Rebirth chance of 20% die, there is 80% chance than one Phoenix will rise. +- val - percent of total stack HP restored, not rounded. For instance, when 4 Phoenixes with Rebirth chance of 20% die, there is 80% chance than one Phoenix will rise. - subtype: - - rebirthRegular: Phoenix, as described above. - - rebirthSpecial: At least one unit will always rise (Sacred Phoenix) + - rebirthRegular: Phoenix, as described above. + - rebirthSpecial: At least one unit will always rise (Sacred Phoenix) ### ENCHANTED @@ -1000,9 +1001,9 @@ Affected heroes will be under effect of Visions spell, revealing information of - val: multiplier to effect range. Information is revealed within (val \* hero spell power) range - subtype: - - visionsMonsters: reveal information on monsters, - - visionsHeroes: reveal information on heroes, - - visionsTowns: reveal information on towns + - visionsMonsters: reveal information on monsters, + - visionsHeroes: reveal information on heroes, + - visionsTowns: reveal information on towns ### BLOCK_MAGIC_BELOW diff --git a/docs/modders/Bonus/Bonus_Updaters.md b/docs/modders/Bonus/Bonus_Updaters.md index f0d95f940..39831b17e 100644 --- a/docs/modders/Bonus/Bonus_Updaters.md +++ b/docs/modders/Bonus/Bonus_Updaters.md @@ -10,45 +10,49 @@ Check the files in *config/heroes/* for additional usage examples. ## GROWS_WITH_LEVEL -- Type: Complex -- Parameters: valPer20, stepSize=1 -- Effect: Updates val to +- Type: Complex +- Parameters: valPer20, stepSize=1 +- Effect: Updates val to -` ceil(valPer20 * floor(heroLevel / stepSize) / 20)` +`ceil(valPer20 * floor(heroLevel / stepSize) / 20)` Example: The following updater will cause a bonus to grow by 6 for every 40 levels. At first level, rounding will cause the bonus to be 0. -` "updater" : {` -` "parameters" : [ 6, 2 ],` -` "type" : "GROWS_WITH_LEVEL"` -` }` +``` jsonc +"updater" : { + "parameters" : [ 6, 2 ], + "type" : "GROWS_WITH_LEVEL" +} +``` Example: The following updater will cause a bonus to grow by 3 for every 20 levels. At first level, rounding will cause the bonus to be 1. -` "updater" : {` -` "parameters" : [ 3 ],` -` "type" : "GROWS_WITH_LEVEL"` -` }` +``` jsonc +"updater" : { + "parameters" : [ 3 ], + "type" : "GROWS_WITH_LEVEL" +} +``` Remarks: -- The rounding rules are designed to match the attack/defense bonus +- The rounding rules are designed to match the attack/defense bonus progression for heroes with creature specialties in HMM3. -- There is no point in specifying val for a bonus with a +- There is no point in specifying val for a bonus with a GROWS_WITH_LEVEL updater. ## TIMES_HERO_LEVEL -- Type: Simple -- Effect: Updates val to +- Type: Simple +- Effect: Updates val to -` val * heroLevel` +`val * heroLevel` Usage: -` "updater" : "TIMES_HERO_LEVEL"` +`"updater" : "TIMES_HERO_LEVEL"` Remark: This updater is redundant, in the sense that GROWS_WITH_LEVEL can also express the desired scaling by setting valPer20 to 20\*val. It @@ -56,34 +60,36 @@ has been added for convenience. ## TIMES_STACK_LEVEL -- Type: Simple -- Effect: Updates val to +- Type: Simple +- Effect: Updates val to -` val * stackLevel` +`val * stackLevel` Usage: -` "updater" : "TIMES_STACK_LEVEL"` +`"updater" : "TIMES_STACK_LEVEL"` Remark: The stack level for war machines is 0. ## ARMY_MOVEMENT -- Type: Complex -- Parameters: basePerSpeed, dividePerSpeed, additionalMultiplier, +- Type: Complex +- Parameters: basePerSpeed, dividePerSpeed, additionalMultiplier, maxValue -- Effect: Updates val to val+= max((floor(basePerSpeed / +- Effect: Updates val to val+= max((floor(basePerSpeed / dividePerSpeed)\* additionalMultiplier), maxValue) -- Remark: this updater is designed for MOVEMENT bonus to match H3 army +- Remark: this updater is designed for MOVEMENT bonus to match H3 army movement rules (in the example - actual movement updater, which produces values same as in default movement.txt). -- Example: +- Example: -` "updater" : {` -` "parameters" : [ 20, 3, 10, 700 ],` -` "type" : "ARMY_MOVEMENT"` -` }` +``` jsonc +"updater" : { + "parameters" : [ 20, 3, 10, 700 ], + "type" : "ARMY_MOVEMENT" +} +``` ## BONUS_OWNER_UPDATER -TODO: document me \ No newline at end of file +TODO: document me diff --git a/docs/modders/Bonus/Bonus_Value_Types.md b/docs/modders/Bonus/Bonus_Value_Types.md index aca624516..28ae187fa 100644 --- a/docs/modders/Bonus/Bonus_Value_Types.md +++ b/docs/modders/Bonus/Bonus_Value_Types.md @@ -2,24 +2,24 @@ Total value of Bonus is calculated using the following: -- For each bonus source type we calculate new source value (for all bonus value types except PERCENT_TO_SOURCE and PERCENT_TO_TARGET_TYPE) using the following: -` newVal = (val * (100 + PERCENT_TO_SOURCE) / 100))` +- For each bonus source type we calculate new source value (for all bonus value types except PERCENT_TO_SOURCE and PERCENT_TO_TARGET_TYPE) using the following: +`newVal = (val * (100 + PERCENT_TO_SOURCE) / 100))` - PERCENT_TO_TARGET_TYPE applies as PERCENT_TO_SOURCE to targetSourceType of bonus. -- All bonus value types summarized and then used as subject of the following formula: +- All bonus value types summarized and then used as subject of the following formula: -` clamp(((BASE_NUMBER * (100 + PERCENT_TO_BASE) / 100) + ADDITIVE_VALUE) * (100 + PERCENT_TO_ALL) / 100), INDEPENDENT_MAX, INDEPENDENT_MIN)` +`clamp(((BASE_NUMBER * (100 + PERCENT_TO_BASE) / 100) + ADDITIVE_VALUE) * (100 + PERCENT_TO_ALL) / 100), INDEPENDENT_MAX, INDEPENDENT_MIN)` Semantics of INDEPENDENT_MAX and INDEPENDENT_MIN are wrapped, and first means than bonus total value will be at least INDEPENDENT_MAX, and second means than bonus value will be at most INDEPENDENT_MIN. ## List of all bonus value types -- ADDITIVE_VALUE -- BASE_NUMBER -- PERCENT_TO_ALL -- PERCENT_TO_BASE -- INDEPENDENT_MAX -- INDEPENDENT_MIN -- PERCENT_TO_SOURCE -- PERCENT_TO_TARGET_TYPE \ No newline at end of file +- ADDITIVE_VALUE +- BASE_NUMBER +- PERCENT_TO_ALL +- PERCENT_TO_BASE +- INDEPENDENT_MAX +- INDEPENDENT_MIN +- PERCENT_TO_SOURCE +- PERCENT_TO_TARGET_TYPE diff --git a/docs/modders/Bonus_Format.md b/docs/modders/Bonus_Format.md index 5dce1c1d0..59a9f4d8f 100644 --- a/docs/modders/Bonus_Format.md +++ b/docs/modders/Bonus_Format.md @@ -4,7 +4,7 @@ All parameters but type are optional. -``` javascript +``` jsonc { // Type of the bonus. See Bonus Types for full list "type": "BONUS_TYPE", @@ -78,10 +78,10 @@ All parameters but type are optional. All string identifiers of items can be used in "subtype" field. This allows cross-referencing between the mods and make config file more readable. See [Game Identifiers](Game_Identifiers.md) for full list of available identifiers - + ### Example -``` javascript +``` jsonc "bonus" : { "type" : "HATE", @@ -90,4 +90,4 @@ See [Game Identifiers](Game_Identifiers.md) for full list of available identifie } ``` -This bonus makes creature do 50% more damage to Enchanters. \ No newline at end of file +This bonus makes creature do 50% more damage to Enchanters. diff --git a/docs/modders/Building_Bonuses.md b/docs/modders/Building_Bonuses.md index ac4e0c7d9..d77669f50 100644 --- a/docs/modders/Building_Bonuses.md +++ b/docs/modders/Building_Bonuses.md @@ -12,17 +12,17 @@ should be moved to scripting. Includes: -- mystic pond -- treasury -- god of fire -- castle gates -- cover of darkness -- portal of summoning -- escape tunnel +- mystic pond +- treasury +- god of fire +- castle gates +- cover of darkness +- portal of summoning +- escape tunnel Function of all of these objects can be enabled by this: -``` javascript +``` jsonc "function" : "castleGates" ``` @@ -31,13 +31,13 @@ Function of all of these objects can be enabled by this: Hardcoded functionality for now due to complexity of these objects. Temporary can be handles as unique buildings. Includes: -- resource - resource -- resource - player -- artifact - resource -- resource - artifact -- creature - resource -- resource - skills -- creature - skeleton +- resource - resource +- resource - player +- artifact - resource +- resource - artifact +- creature - resource +- resource - skills +- creature - skeleton ### hero visitables @@ -46,10 +46,10 @@ handled via configurable objects system. Includes: -- gives mana points -- gives movement points -- give bonus to visitor -- permanent bonus to hero +- gives mana points +- gives movement points +- give bonus to visitor +- permanent bonus to hero ### generic functions @@ -58,31 +58,31 @@ CBuilding class. #### unlock guild level -``` javascript +``` jsonc "guildLevels" : 1 ``` #### unlock hero recruitment -``` javascript +``` jsonc "allowsHeroPurchase" : true ``` #### unlock ship purchase -``` javascript +``` jsonc "allowsShipPurchase" : true ``` #### unlock building purchase -``` javascript +``` jsonc "allowsBuildingPurchase" : true ``` #### unlocks creatures -``` javascript +``` jsonc "dwelling" : { "level" : 1, "creature" : "archer" } ``` @@ -92,31 +92,31 @@ Turn into town bonus? What about creature-specific bonuses from hordes? #### gives resources -``` javascript +``` jsonc "provides" : { "gold" : 500 } ``` #### gives guild spells -``` javascript +``` jsonc "guildSpells" : [5, 0, 0, 0, 0] ``` #### gives thieves guild -``` javascript +``` jsonc "thievesGuildLevels" : 1 ``` #### gives fortifications -``` javascript +``` jsonc "fortificationLevels" : 1 ``` #### gives war machine -``` javascript +``` jsonc "warMachine" : "ballista" ``` @@ -129,12 +129,12 @@ TODO: how to handle stackable bonuses like Necromancy Amplifier? Includes: -- bonus to defender -- bonus to alliance -- bonus to scouting range -- bonus to player +- bonus to defender +- bonus to alliance +- bonus to scouting range +- bonus to player -``` javascript +``` jsonc "bonuses" : { "moraleToDefenders" : @@ -162,12 +162,12 @@ Possible issue - with removing of fixed ID's buildings in different town may no longer share same ID. However Capitol must be unique across all town. Should be fixed somehow. -``` javascript +``` jsonc "onePerPlayer" : true ``` #### chance to be built on start -``` javascript +``` jsonc "prebuiltChance" : 75 -``` \ No newline at end of file +``` diff --git a/docs/modders/Campaign_Format.md b/docs/modders/Campaign_Format.md index 9fec41be2..8e071fcd6 100644 --- a/docs/modders/Campaign_Format.md +++ b/docs/modders/Campaign_Format.md @@ -3,11 +3,12 @@ ## 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) +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 `header.json`. See also [Packing campaign](#packing-campaign) Basic structure of this file is here, each section is described in details below + ```js { "version" : 1, @@ -32,6 +33,7 @@ Basic structure of this file is here, each section is described in details below ## Header properties In header are parameters describing campaign properties + ```js ... "regions": {...}, @@ -60,6 +62,7 @@ In header are parameters describing campaign properties ## Scenario description Scenario description looks like follow: + ```js { "map": "maps/SomeMap", @@ -77,7 +80,7 @@ Scenario description looks like follow: } ``` -- `"map"` map name without extension but with relative path. Both *.h3m and *.vmap maps are supported. If you will pack scenarios inside campaign, numerical map name should be used, see details in [packing campaign](#packing-campaign) +- `"map"` map name without extension but with relative path. Both `*.h3m` and `*.vmap` maps are supported. If you will pack scenarios inside campaign, numerical map name should be used, see details in [packing campaign](#packing-campaign) - `"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` @@ -96,6 +99,7 @@ Scenario description looks like follow: ### Prolog/Epilog Prolog and epilog properties are optional + ```js { "video": "NEUTRALA.smk", //video to show @@ -164,12 +168,14 @@ If `startOptions` is `crossover`, heroes from specific scenario will be moved to "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, @@ -201,7 +207,7 @@ Predefined campaign regions are located in file `campaign_regions.json` - `"background"` optional - use own image name for background instead of adding "_BG" to the prefix as name - `"prefix"` used to identify all images related to campaign. In this example (if background parameter wouldn't exists), background picture will be `G3_BG` - `"suffix"` optional - use other suffixes than the default `En`, `Se` and `Co` for the three different images -- `"infix"` used to identify all images related to region. In this example, it will be pictures whose files names begin with `G3A_..., G3B_..., G3C_..."` +- `"infix"` used to identify all images related to region. In this example, it will be pictures whose files names begin with `G3A_..., G3B_..., G3C_..."` - `"labelPos"` optional - to add scenario name as label on map - `"colorSuffixLength"` identifies suffix length for region colourful frames. 0 is no color suffix (no colorisation), 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` @@ -213,6 +219,7 @@ This file is a zip archive. The scenarios should be named as in `"map"` field from header. Subfolders are allowed. ## Compatibility table + | Version | Min VCMI | Max VCMI | Description | |---------|----------|----------|-------------| -| 1 | 1.3 | | Initial release | \ No newline at end of file +| 1 | 1.3 | | Initial release | diff --git a/docs/modders/Configurable_Widgets.md b/docs/modders/Configurable_Widgets.md index 883b249b1..ec2eccd11 100644 --- a/docs/modders/Configurable_Widgets.md +++ b/docs/modders/Configurable_Widgets.md @@ -21,6 +21,7 @@ In this tutorial we will recreate options tab to support chess timers UI. ### Creating mod structure To start making mod, create following folders structure; + ``` extendedLobby/ |- content/ @@ -31,6 +32,7 @@ extendedLobby/ ``` File `mod.json` is generic and could look like this: + ```json { "name" : "Configurable UI tutorial mod", @@ -44,7 +46,7 @@ File `mod.json` is generic and could look like this: } ``` -After that you can copy `extendedLobby/ folder to `mods/` folder and your mod will immediately appear in launcher but it does nothing for now. +After that you can copy `extendedLobby/` folder to `mods/` folder and your mod will immediately appear in launcher but it does nothing for now. ### Making layout for timer @@ -64,6 +66,7 @@ So we need to modify turn duration label and add combo box with timer types Open `optionsTab.json` and scroll it until you see comment `timer`. Three elements after this comment are related to timer. Let's find first element, which is label + ```json { "items" @@ -85,6 +88,7 @@ Let's find first element, which is label ``` And modify it a bit + ```json { "name": "labelTimer", //add name, only for convenience @@ -98,6 +102,7 @@ And modify it a bit ``` But we also need proper background image for this label. Add image widget BEFORE labelTimer widget: + ```json { "type": "picture", @@ -109,6 +114,7 @@ But we also need proper background image for this label. Add image widget BEFORE ... }, ``` + In order to make it work, add file `RmgTTBk.bmp` to `content/sprites/` Elements named `labelTurnDurationValue` and `sliderTurnDuration` we will keep without change - they are needed to configure classic timer. @@ -272,6 +278,7 @@ After view part is done, let's make behavioural part. Let's hide elements, related to classic timer when chess timer is selected and show them back if classic selected. To do that, find `"variables"` part inside `optionsTab.json` and add there `"timers"` array, containing 2 elements: + ```json "variables": { @@ -300,7 +307,7 @@ Now we show and hide elements, but visually you still can some "artifacts": Снимок экрана 2023-08-30 в 15 51 22 -It's because options tab background image we use has those elements drawn. Let's hide them with overlay image `timchebk.bmp`. +It's because options tab background image we use has those elements drawn. Let's hide them with overlay image `timchebk.bmp`. It should be drawn before all other timer elements: ```json @@ -328,8 +335,9 @@ It works and can switch elements, the only missing part is chess timer configura We should add text input fields, to specify different timers. We will use background for them `timerField.bmp`, copy it to `content/sprites/` folder of your mod. -There are 4 different timers: base, turn, battle and creature. Read about them here: https://github.com/vcmi/vcmi/issues/1364 +There are 4 different timers: base, turn, battle and creature. Read about them here: We can add editors for them into items list, their format will be following: + ```json { "name": "chessFieldBase", @@ -345,6 +353,7 @@ We can add editors for them into items list, their format will be following: ``` Add three remaining elements for different timers by yourself. You can play with all settings, except callback. There are 4 predefined callbacks to setup timers: + - `parseAndSetTimer_base` - `parseAndSetTimer_turn` - `parseAndSetTimer_battle` @@ -363,7 +372,7 @@ There are different basic types, which can be used as value. #### Primitive types -Read JSON documentation for primitive types description: https://www.json.org/json-en.html +Read JSON documentation for primitive types description: #### Text @@ -430,6 +439,7 @@ One of predefined values: ### Configurable objects Configurable object has following structure: + ```json { "items": [], @@ -621,7 +631,7 @@ Filling area with texture `"color"`: [color](#color), -`"text": string` optional, default text. Translations are not supported +`"text": string` optional, default text. Translations are not supported `"position"`: [position](#position) @@ -748,11 +758,13 @@ Used only as special object for [combo box](#combo-box) `"position"`: [position](#position) `"items": []` array of overlay widgets with certain types and names: - - `"name": "hoverImage"`, `"type": ` [picture](#picture) - image to be shown when cursor hovers elements - - `"name": "labelName"`, `"type": ` [label](#label) - element caption + +- `"name": "hoverImage"`, `"type":` [picture](#picture) - image to be shown when cursor hovers elements +- `"name": "labelName"`, `"type":` [label](#label) - element caption **Callbacks** - - `sliderMove` connect to slider callback to correctly navigate over elements + +- `sliderMove` connect to slider callback to correctly navigate over elements #### Layout @@ -769,7 +781,8 @@ Used only as special object for [combo box](#combo-box) While designing a new element, you can make it configurable to reuse all functionality described above. It will provide flexibility to further changes as well as modding capabilities. Class should inherit `InterfaceObjectConfigurable`. -```C++ + +```cpp #include "gui/InterfaceObjectConfigurable.h" //assuming we are in client folder class MyYesNoDialog: public InterfaceObjectConfigurable @@ -781,7 +794,7 @@ class MyYesNoDialog: public InterfaceObjectConfigurable To make new object work, it's sufficient to define constructor, which receives const reference to `JsonNode`. -```C++ +```cpp MyYesNoDialog::MyYesNoDialog(const JsonNode & config): InterfaceObjectConfigurable(), //you can pass arguments same as for CIntObject { @@ -808,13 +821,13 @@ MyYesNoDialog::MyYesNoDialog(const JsonNode & config): You can build custom widgets, related to your UI element specifically. Like in example above, there is Item widget, which can be also used on JSON config. -```C++ +```cpp REGISTER_BUILDER("myItem", &MyYesNoDialog::buildMyItem); ``` You have to define function, which takes JsonNode as an argument and return pointer to built widget -```C++ +```cpp std::shared_ptr MyYesNoDialog::buildMyItem(const JsonNode & config) { auto position = readPosition(config["position"]); @@ -840,7 +853,7 @@ After that, if your JSON file has items with type "MyItem", the new Item element After calling `build(config)` variables defined in config JSON file become available. You can interpret them and use in callbacks or in element code -```C++ +```cpp build(config); if(variables["colorfulText"].Bool()) diff --git a/docs/modders/Difficulty.md b/docs/modders/Difficulty.md index 91f78af9c..4d53552ff 100644 --- a/docs/modders/Difficulty.md +++ b/docs/modders/Difficulty.md @@ -7,7 +7,7 @@ Difficulty configuration is located in [config/difficulty.json](../config/diffic ## Format summary -``` javascript +``` jsonc { "human": //parameters impacting human players only { @@ -63,4 +63,4 @@ For both types of bonuses, `source` should be specified as `OTHER`. ## Compatibility Starting from VCMI 1.4 `startres.json` is not available anymore and will be ignored if present in any mod. -Thus, `Resourceful AI` mod of version 1.2 won't work anymore. \ No newline at end of file +Thus, `Resourceful AI` mod of version 1.2 won't work anymore. diff --git a/docs/modders/Entities_Format/Artifact_Format.md b/docs/modders/Entities_Format/Artifact_Format.md index 83b1adca2..a36499926 100644 --- a/docs/modders/Entities_Format/Artifact_Format.md +++ b/docs/modders/Entities_Format/Artifact_Format.md @@ -6,9 +6,9 @@ Artifact bonuses use [Bonus Format](../Bonus_Format.md) In order to make functional artifact you also need: -- Icon for hero inventory (1 image) -- Icon for popup windows (1 image, optional) -- Animation for adventure map (1 animation) +- Icon for hero inventory (1 image) +- Icon for popup windows (1 image, optional) +- Animation for adventure map (1 animation) ## Format diff --git a/docs/modders/Entities_Format/Battle_Obstacle_Format.md b/docs/modders/Entities_Format/Battle_Obstacle_Format.md index e9b00d3d6..f81390564 100644 --- a/docs/modders/Entities_Format/Battle_Obstacle_Format.md +++ b/docs/modders/Entities_Format/Battle_Obstacle_Format.md @@ -24,4 +24,4 @@ // If set to true, obstacle will appear in front of units or other battlefield objects "foreground" : false -``` \ No newline at end of file +``` diff --git a/docs/modders/Entities_Format/Battlefield_Format.md b/docs/modders/Entities_Format/Battlefield_Format.md index 21c219273..2ab1da12b 100644 --- a/docs/modders/Entities_Format/Battlefield_Format.md +++ b/docs/modders/Entities_Format/Battlefield_Format.md @@ -22,4 +22,4 @@ // List of battle hexes that will be always blocked on this battlefield (e.g. ship to ship battles) "impassableHexes" : [ 10, 20, 50 ], -``` \ No newline at end of file +``` diff --git a/docs/modders/Entities_Format/Biome_Format.md b/docs/modders/Entities_Format/Biome_Format.md index a0d2a3689..6338fc7a0 100644 --- a/docs/modders/Entities_Format/Biome_Format.md +++ b/docs/modders/Entities_Format/Biome_Format.md @@ -38,5 +38,3 @@ Currently algorithm picks randomly: - One or two sets of **rocks** (small objects) - One of each remaining types of object (**structure**, **animal**, **other**), until enough number of sets is picked. - Obstacles marked as **other** are picked last, and are generally rare. - - diff --git a/docs/modders/Entities_Format/Creature_Format.md b/docs/modders/Entities_Format/Creature_Format.md index 252a5e140..bad20d450 100644 --- a/docs/modders/Entities_Format/Creature_Format.md +++ b/docs/modders/Entities_Format/Creature_Format.md @@ -8,22 +8,22 @@ In order to make functional creature you also need: ### Animation -- Battle animation (1 def file) -- Set of rendered projectiles (1 def files, shooters only) -- Adventure map animation (1 def file) +- Battle animation (1 def file) +- Set of rendered projectiles (1 def files, shooters only) +- Adventure map animation (1 def file) ### Images -- Small portrait for hero exchange window (1 image) -- Large portrait for hero window (1 image) +- Small portrait for hero exchange window (1 image) +- Large portrait for hero window (1 image) ### Sounds -- Set of sounds (up to 8 sounds) +- Set of sounds (up to 8 sounds) ## Format -``` javascript +``` jsonc // camelCase unique creature identifier "creatureName" : { @@ -217,4 +217,4 @@ In order to make functional creature you also need: ... ] } -``` \ No newline at end of file +``` diff --git a/docs/modders/Entities_Format/Creature_Help.md b/docs/modders/Entities_Format/Creature_Help.md index d5ca1a590..a2234e40b 100644 --- a/docs/modders/Entities_Format/Creature_Help.md +++ b/docs/modders/Entities_Format/Creature_Help.md @@ -5,6 +5,7 @@ This page helps you to create a creature (i.e. a unit that fights in a battle) f ## Utilities You need to download the two utilities [`DefPreview`](https://sourceforge.net/projects/grayface-misc/files/DefPreview-1.2.1/) and [`H3DefTool`](https://sourceforge.net/projects/grayface-misc/files/H3DefTool-3.4.2/) from the internet: + - `DefPreview` converts a `.def` file to `.bmp` images - `H3DefTool` converts `.bmp` images to a `.def` file @@ -21,7 +22,9 @@ The sun is always at zenith, so the shadow is always behind. The reason is that We don't know the right elevation angle for the view. ### 3D render -You can render your creature using a 3D software like _Blender_. You can start with those free-licenced rigged 3D models: + +You can render your creature using a 3D software like *Blender*. You can start with those free-licenced rigged 3D models: + - [Fantasy-bandit](https://www.cgtrader.com/free-3d-models/character/man/fantasy-bandit) - [Monster-4](https://www.cgtrader.com/free-3d-models/character/fantasy-character/monster-4-f5757b92-dc9c-4f5e-ad0d-593203d14fe2) - [Crypt-fiend-modular-character](https://www.cgtrader.com/free-3d-models/character/fantasy-character/crypt-fiend-modular-character-demo-scene) @@ -33,57 +36,60 @@ You can render your creature using a 3D software like _Blender_. You can start w - [Shani](https://www.cgtrader.com/free-3d-models/character/woman/shani-3d-character) You can also create your 3D model from a single image: -- _Stable Fast 3D_: https://huggingface.co/spaces/stabilityai/stable-fast-3d -- _Unique3D_: https://huggingface.co/spaces/abreza/Unique3D -To use it in _Blender_, create a `.blend` project and import the file. To render the texture: -1. Add a _Principled BSDF_ material to the object -1. Create a _Color Attribute_ in the _Shader Editor_ view -1. Link the Color output of the _Color Attribute_ to the _Base color_ input of the _Principled BSDF_ +- *Stable Fast 3D*: +- *Unique3D*: -You can improve details by cropping the source image on a detail and generate a model for this detail. Once both imported in _Blender_, melt them together. +To use it in *Blender*, create a `.blend` project and import the file. To render the texture: -Render the images without background by selecting png RVBA and disabling background (_Film_ -> _Filter_ -> _Transparent_). It avoids the creatures to have an ugly dark border. Then, to correctly separate the creature from the cyan area, in _GIMP_, apply the threeshold on the transparency by clicking on _Layer_ -> _Transparency_ -> _Alpha threeshold_. +1. Add a *Principled BSDF* material to the object +1. Create a *Color Attribute* in the *Shader Editor* view +1. Link the Color output of the *Color Attribute* to the *Base color* input of the *Principled BSDF* + +You can improve details by cropping the source image on a detail and generate a model for this detail. Once both imported in *Blender*, melt them together. + +Render the images without background by selecting png RVBA and disabling background (*Film* -> *Filter* -> *Transparent*). It avoids the creatures to have an ugly dark border. Then, to correctly separate the creature from the cyan area, in *GIMP*, apply the threeshold on the transparency by clicking on *Layer* -> *Transparency* -> *Alpha threeshold*. The global FPS of the game is 10 f/s but you can render at a higher level and configure it in the `.json` files. We are not in the 1990's. ### IA render -You can also use an AI like _Flux_ to generate the main creature representation: https://huggingface.co/spaces/multimodalart/FLUX.1-merged +You can also use an AI like *Flux* to generate the main creature representation: -Then you can add random animations for idle states with _SVD_: https://huggingface.co/spaces/xi0v/Stable-Video-Diffusion-Img2Vid +Then you can add random animations for idle states with *SVD*: -Most of the time, the creatures do not move more than one pixel in an idle animation. The reason may be to avoid too much animation on screen and make the transition with the other animations always seamless. Use poses with _ControlNet_ or _OpenPose_. For specific animations, I recommend to use _Cinemo_ because it adds a description prompt but the resolution is smaller: https://huggingface.co/spaces/maxin-cn/Cinemo +Most of the time, the creatures do not move more than one pixel in an idle animation. The reason may be to avoid too much animation on screen and make the transition with the other animations always seamless. Use poses with *ControlNet* or *OpenPose*. For specific animations, I recommend to use *Cinemo* because it adds a description prompt but the resolution is smaller: -Make animations seamless from one to another. To do this, you can draw the first and the last images with a prompt with _ToonCrafter_: https://huggingface.co/spaces/ChristianHappy/tooncrafter +Make animations seamless from one to another. To do this, you can draw the first and the last images with a prompt with *ToonCrafter*: -Most of the time, you need to increase the resolution or the quality of your template image, so use _SUPIR_: https://huggingface.co/spaces/Fabrice-TIERCELIN/SUPIR +Most of the time, you need to increase the resolution or the quality of your template image, so use *SUPIR*: ## Battle sound effect -To create the audio effects, I recommend to use _Tango 2_: https://huggingface.co/spaces/declare-lab/tango2 +To create the audio effects, I recommend to use *Tango 2*: -The quality is better than _Stable Audio_. +The quality is better than *Stable Audio*. ## Map render We don't know the right elevation angle for the view but 45° elevation seems to be a good choice. For the sunlight direction, I would say 45° elevation and 45° azimut. -The map creatures are not rendered on the map with vanishing points but in isometric. You can [get an orthogonal render in Blender](https://blender.stackexchange.com/a/135384/2768). If you are creating a creature and its updated version, most of the time, the both creatures are not oriented to the same side on the map. I think that the animation on the map is usually the _Mouse Over_ animation on battle. +The map creatures are not rendered on the map with vanishing points but in isometric. You can [get an orthogonal render in Blender](https://blender.stackexchange.com/a/135384/2768). If you are creating a creature and its updated version, most of the time, the both creatures are not oriented to the same side on the map. I think that the animation on the map is usually the *Mouse Over* animation on battle. -You can see that the view angle is higher than on a battle. To change the angle from a battle sprite, you can use _Zero 1-to-3_: https://huggingface.co/spaces/cvlab/zero123-live +You can see that the view angle is higher than on a battle. To change the angle from a battle sprite, you can use *Zero 1-to-3*: -You can get higher resolution using this Video AI that can control the motion of the camera: https://huggingface.co/spaces/TencentARC/MotionCtrl_SVD +You can get higher resolution using this Video AI that can control the motion of the camera: -If you have a 3D software, you can get better quality by converting your image into 3D model and then render it from another angle using _Stable Fast 3D_: https://huggingface.co/spaces/stabilityai/stable-fast-3d +If you have a 3D software, you can get better quality by converting your image into 3D model and then render it from another angle using *Stable Fast 3D*: -Follow this comment to retrieve the color: https://huggingface.co/stabilityai/TripoSR/discussions/1#65e8a8e5e214f37d85dad366 +Follow this comment to retrieve the color: ### Shadow render There are no strong rules in the original game about the angle of the shadows on the map. Different buildings have inconsistent shadows. To draw the shadow, I recommend the following technique: Let's consider that the object is a vertical cone: + | | | | | | | | | | | |---|---|---|---|---|---|---|---|---|---| | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | @@ -98,6 +104,7 @@ Let's consider that the object is a vertical cone: | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | Locate the top and its projection to the ground: + | | | | | | | | | | | |---|---|---|---|---|---|---|---|---|---| | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | @@ -112,6 +119,7 @@ Locate the top and its projection to the ground: | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | Then draw a rectangle triangle on the left: + | | | | | | | | | | | |---|---|---|---|---|---|---|---|---|---| | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | @@ -126,6 +134,7 @@ Then draw a rectangle triangle on the left: | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | The square top is the projection of the shadow of the top of the cone: + | | | | | | | | | | | |---|---|---|---|---|---|---|---|---|---| | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | @@ -140,6 +149,7 @@ The square top is the projection of the shadow of the top of the cone: | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | Then you can draw the rest of the shadow: + | | | | | | | | | | | |---|---|---|---|---|---|---|---|---|---| | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | diff --git a/docs/modders/Entities_Format/Faction_Format.md b/docs/modders/Entities_Format/Faction_Format.md index 739086331..b51c8720b 100644 --- a/docs/modders/Entities_Format/Faction_Format.md +++ b/docs/modders/Entities_Format/Faction_Format.md @@ -8,42 +8,42 @@ In order to make functional town, you also need: ### Images -- Creature backgrounds images, 120x100 and 130x100 versions (2 images) -- Set of puzzle map pieces (48 images) -- Background scenery (1 image) -- Mage guild window view (1 image) -- Town hall background (1 image) +- Creature backgrounds images, 120x100 and 130x100 versions (2 images) +- Set of puzzle map pieces (48 images) +- Background scenery (1 image) +- Mage guild window view (1 image) +- Town hall background (1 image) -- Set of town icons, consists from all possible combinations of: (8 +- Set of town icons, consists from all possible combinations of: (8 images total) - - small and big icons - - village and fort icons - - built and normal icons + - small and big icons + - village and fort icons + - built and normal icons -- Set for castle siege screen, consists from: - - Background (1 image) - - Destructible towers (3 parts, 3 images each) - - Destructible walls (4 parts, 3 images each) - - Static walls (3 images) - - Town gates (5 images) - - Moat (2 images) +- Set for castle siege screen, consists from: + - Background (1 image) + - Destructible towers (3 parts, 3 images each) + - Destructible walls (4 parts, 3 images each) + - Static walls (3 images) + - Town gates (5 images) + - Moat (2 images) ### Animation -- Adventure map images for village, town and capitol (3 def files) +- Adventure map images for village, town and capitol (3 def files) ### Music -- Town theme music track (at least 1 music file) +- Town theme music track (at least 1 music file) ### Buildings Each town requires a set of buildings (Around 30-45 buildings) -- Town animation file (1 animation file) -- Selection highlight (1 image) -- Selection area (1 image) -- Town hall icon (1 image) +- Town animation file (1 animation file) +- Selection highlight (1 image) +- Selection area (1 image) +- Town hall icon (1 image) ## Faction node (root entry for town configuration) @@ -340,7 +340,9 @@ Each town requires a set of buildings (Around 30-45 buildings) ``` ## Building node + See [Town Building Format](Town_Building_Format.md) ## Structure node -See [Town Building Format](Town_Building_Format.md) \ No newline at end of file + +See [Town Building Format](Town_Building_Format.md) diff --git a/docs/modders/Entities_Format/Faction_Help.md b/docs/modders/Entities_Format/Faction_Help.md index c141a8673..ebbcd38fa 100644 --- a/docs/modders/Entities_Format/Faction_Help.md +++ b/docs/modders/Entities_Format/Faction_Help.md @@ -3,90 +3,109 @@ This page helps you to create from scratch a VCMI mod that adds a new faction. The faction mod structure is described [here](Faction_Format.md). ## Questioning the faction creation + Before creating a faction, be aware that creating a faction mod is lots of work. You can start [creating creatures](Creature_Help.md) in a creature mod that can be converted into a faction mod after. This way, you are sure to release something. The smallest contribution is a hero portrait that you can suggest on an existing mod. You can also restore the former version of the [Ruins faction](https://github.com/vcmi-mods/ruins-town/tree/1bea30a1d915770e2fd0f95d158030815ff462cd). You would only have to remake the similar parts to the new version. ## Make a playable faction mod -Before creating your content, retrieve the content of an existing faction mod like [Highlands town](https://github.com/vcmi-mods/highlands-town). To download the project, click on the _Code_ button and click on _Download ZIP_. The first thing to do is to change all the faction identifiers in the files following the [faction format](Faction_Format.md) and manage to play with the faction and the original without any conflict. To play to a faction, you have to add all the files in your _Mods_ folder. When it works, you will be able to modify the content step by step. + +Before creating your content, retrieve the content of an existing faction mod like [Highlands town](https://github.com/vcmi-mods/highlands-town). To download the project, click on the *Code* button and click on *Download ZIP*. The first thing to do is to change all the faction identifiers in the files following the [faction format](Faction_Format.md) and manage to play with the faction and the original without any conflict. To play to a faction, you have to add all the files in your *Mods* folder. When it works, you will be able to modify the content step by step. Keep in mind that the most important part of a faction mod, above the animations, the graphisms and the musics, is the concept because if you have to change it, you have to change everything else. All the remaining content can be improved by the community. ## Town screen -### Background -Beware to direct all the shadows to the same direction. The easiest way to create the background is to use a text-to-image AI. The free most powerful AI at the moment is _Flux_ available here: https://huggingface.co/spaces/multimodalart/FLUX.1-merged -In the _Advanced Options_, set the width to 800px and set the height to 374px. +### Background + +Beware to direct all the shadows to the same direction. The easiest way to create the background is to use a text-to-image AI. The free most powerful AI at the moment is *Flux* available here: + +In the *Advanced Options*, set the width to 800px and set the height to 374px. ### Buildings -To render a building upon the background, I recommend to use an inpainting AI like _BRIA Inpaint_: https://huggingface.co/spaces/briaai/BRIA-2.3-Inpainting + +To render a building upon the background, I recommend to use an inpainting AI like *BRIA Inpaint*: The idea is to select the area where you want to add the building. As a prompt, describe the new building. The advantage is a perfect match between the background and the building. Keep in mind that to correctly integrate a building image, it must contain the image of the background on its edges. It simulates the semi-transparency. -You can also animate the building or the background using _Stable Video Diffusion_: https://huggingface.co/spaces/multimodalart/stable-video-diffusion +You can also animate the building or the background using *Stable Video Diffusion*: ## Map dwellings -You may want to get the same render as in the town, so you have to change the angle and the shadows. If you handle a 3D model software, you can start with _Stable Fast 3D_: https://huggingface.co/spaces/stabilityai/stable-fast-3d + +You may want to get the same render as in the town, so you have to change the angle and the shadows. If you handle a 3D model software, you can start with *Stable Fast 3D*: The map dwellings are not rendered on the map with vanishing points but in isometric. You can [get an orthogonal render in Blender](https://blender.stackexchange.com/a/135384/2768). -Without 3D, you can use _Zero 1-to-3_: https://huggingface.co/spaces/cvlab/zero123-live +Without 3D, you can use *Zero 1-to-3*: -You can get higher resolution using this Video AI that can control the motion of the camera: https://huggingface.co/spaces/TencentARC/MotionCtrl_SVD +You can get higher resolution using this Video AI that can control the motion of the camera: -The buildings on the map are more satured than on town screen. If you have to reduce the size of an image, do not use interpolation (LANCZOS, Bilinear...) to get more details, not a blurred image. If you need to increase the resolution or the quality of your template image, use _SUPIR_: https://huggingface.co/spaces/Fabrice-TIERCELIN/SUPIR +The buildings on the map are more satured than on town screen. If you have to reduce the size of an image, do not use interpolation (LANCZOS, Bilinear...) to get more details, not a blurred image. If you need to increase the resolution or the quality of your template image, use *SUPIR*: ## Map buildings + The AIs badly understand the sun direction and the perspective angles. To generate the buildings on the adventure map: 1. Open the HOMM3 map editor 1. Put items all around a big empty area 1. Make a screenshot -1. Go on an AI like _BRIA Inpaint_: https://huggingface.co/spaces/briaai/BRIA-2.3-Inpainting +1. Go on an AI like *BRIA Inpaint*: 1. Inpaint the (big) empty middle with the brush 1. Use a prompt like: `A dark house, at the center of the image, map, isometric, parallel perspective, sunlight from the bottom right` ## Music + Here are unused available themes: * [Synthetic Horizon](https://github.com/Fabrice-TIERCELIN/forge/raw/theme/content/music/factions/theme.ogg) + 1. Prompt: `Dystopy, Cinematic classical, Science fiction, 160 bpm, Best quality, Futuristic` -1. Initially created for: _Forge town_ +1. Initially created for: *Forge town* * [Quantum Overture](https://github.com/Fabrice-TIERCELIN/asylum-town/raw/theme/asylum-town/content/Music/factions/AsylumTown.ogg) + 1. Prompt: `Clef shifting, Fantasy, Mystical, Overworldly, Cinematic classical` -1. Initially created for: _Asylum town_ +1. Initially created for: *Asylum town* * [Warrior s March](https://github.com/vcmi-mods/ruins-town/assets/20668759/964f27de-6feb-4ef6-9d25-455f52938cef) + 1. Prompt: `Powerful percussions, Drums, Battle Anthem, Rythm, Warrior, 160 bpm, Celtic, New age, Instrumental, Accoustic, Medieval` -1. Initially created for: _Ruins town_ +1. Initially created for: *Ruins town* * [Clan of Echoes](https://github.com/Fabrice-TIERCELIN/ruins-town/raw/theme/ruins-town/content/music/ruins.ogg) + 1. Prompt: `new age, medieval, celtic, warrior, battle, soundtrack, accoustic, drums, rythm` -1. Initially created for: _Ruins town_ +1. Initially created for: *Ruins town* * [Enchanted Reverie](https://github.com/Fabrice-TIERCELIN/grove/raw/theme/Grove/content/Music/factions/GroveTown.ogg) + 1. Prompt: `Classical music, Soundtrack, Score, Instrumental, 160 bpm, ((((fantasy)))), mystic` -1. Initially created for: _Grove town_ +1. Initially created for: *Grove town* * [World Discovery](https://github.com/vcmi-mods/asylum-town/assets/20668759/34438523-8a44-44ca-b493-127501b474a6) + 1. Prompt: `Clef shifting, fantasy, mystical, overworldly, Cinematic classical` -1. Initially created for: _Asylum town_ +1. Initially created for: *Asylum town* * [Enchanted Ballad](https://github.com/vcmi-mods/fairy-town/assets/20668759/619e6e33-d940-4899-8c76-9c1e8d3d20aa) + 1. Prompt: `Females vocalize, Cinematic classical, Harp, Fairy tale, Princess, 160 bpm` -1. Initially created for: _Fairy town_ +1. Initially created for: *Fairy town* * [Baroque Resurgence](https://github.com/Fabrice-TIERCELIN/courtyard_proposal/raw/theme/Courtyard/Content/music/factions/courtyard/CourtTown.ogg) + 1. Prompt: `Baroque, Instrumental, 160 bpm, Cinematic classical, Best quality` -1. Initially created for: _Courtyard town_ +1. Initially created for: *Courtyard town* * [Harvest Parade](https://github.com/Fabrice-TIERCELIN/greenhouse-town/raw/theme/Greenhouse/content/Music/town.ogg) -1. Prompt: `Marching band, Best quality, Happy, Vegetables` -1. Initially created for: _Green town_ -Those themes have been generated using _[Udio](https://udio.com)_. +1. Prompt: `Marching band, Best quality, Happy, Vegetables` +1. Initially created for: *Green town* + +Those themes have been generated using *[Udio](https://udio.com)*. ## Screenshots + Most of the time, the first screenshot is the townscreen because it's the most specific content. ## Recycle -Some mods contain neutral heroes or creatures. You can integrate them in your faction mod. Don't forget to remove the content from the original mod. \ No newline at end of file + +Some mods contain neutral heroes or creatures. You can integrate them in your faction mod. Don't forget to remove the content from the original mod. diff --git a/docs/modders/Entities_Format/Hero_Class_Format.md b/docs/modders/Entities_Format/Hero_Class_Format.md index 68833fa5d..5049cd2c1 100644 --- a/docs/modders/Entities_Format/Hero_Class_Format.md +++ b/docs/modders/Entities_Format/Hero_Class_Format.md @@ -4,12 +4,12 @@ In order to make functional hero class you also need: -- Adventure animation (1 def file) -- Battle animation, male and female version (2 def files) +- Adventure animation (1 def file) +- Battle animation, male and female version (2 def files) ## Format -``` javascript +``` jsonc // Unique identifier of hero class, camelCase "myClassName" : { @@ -106,4 +106,4 @@ In order to make functional hero class you also need: "conflux" : 6 } } -``` \ No newline at end of file +``` diff --git a/docs/modders/Entities_Format/Hero_Type_Format.md b/docs/modders/Entities_Format/Hero_Type_Format.md index b646c0e89..d3cb85762 100644 --- a/docs/modders/Entities_Format/Hero_Type_Format.md +++ b/docs/modders/Entities_Format/Hero_Type_Format.md @@ -4,12 +4,12 @@ In order to make functional hero you also need: -- Portraits, small and big versions (2 images) -- Specialty icons, small and big versions (2 images) +- Portraits, small and big versions (2 images) +- Specialty icons, small and big versions (2 images) ## Format -``` javascript +``` jsonc "myHeroName" : { // Identifier of class this hero belongs to. Such as knight or battleMage @@ -133,4 +133,4 @@ In order to make functional hero you also need: "creature" : "griffin" } } -``` \ No newline at end of file +``` diff --git a/docs/modders/Entities_Format/River_Format.md b/docs/modders/Entities_Format/River_Format.md index 35635768d..4cd67a3f7 100644 --- a/docs/modders/Entities_Format/River_Format.md +++ b/docs/modders/Entities_Format/River_Format.md @@ -28,4 +28,4 @@ ... ] } -``` \ No newline at end of file +``` diff --git a/docs/modders/Entities_Format/Road_Format.md b/docs/modders/Entities_Format/Road_Format.md index d78de9b10..69b57e75b 100644 --- a/docs/modders/Entities_Format/Road_Format.md +++ b/docs/modders/Entities_Format/Road_Format.md @@ -17,4 +17,4 @@ // How many movement points needed to move hero "moveCost" : 66 } -``` \ No newline at end of file +``` diff --git a/docs/modders/Entities_Format/Secondary_Skill_Format.md b/docs/modders/Entities_Format/Secondary_Skill_Format.md index f157359d4..bd7304b41 100644 --- a/docs/modders/Entities_Format/Secondary_Skill_Format.md +++ b/docs/modders/Entities_Format/Secondary_Skill_Format.md @@ -123,4 +123,4 @@ boost at advanced and expert levels. } } } -``` \ No newline at end of file +``` diff --git a/docs/modders/Entities_Format/Spell_Format.md b/docs/modders/Entities_Format/Spell_Format.md index e0910ca09..46d3a204c 100644 --- a/docs/modders/Entities_Format/Spell_Format.md +++ b/docs/modders/Entities_Format/Spell_Format.md @@ -2,7 +2,7 @@ ## Main format -``` javascript +``` jsonc { "spellName": { @@ -156,7 +156,7 @@ TODO -``` javascript +``` jsonc { "projectile": [ {"minimumAngle": 0 ,"defName":"C20SPX4"}, @@ -179,7 +179,7 @@ Json object with data common for all levels can be put here. These configuration This will make spell affect single target on all levels except expert, where it is massive spell. -``` javascript +``` jsonc "base":{ "range": 0 }, @@ -192,7 +192,7 @@ This will make spell affect single target on all levels except expert, where it TODO -``` javascript +``` jsonc { //Mandatory, localizable description. Use {xxx} for formatting @@ -262,7 +262,7 @@ Configurable spells ignore *offensive* flag, *effects* and *cumulativeEffects*. TODO -``` javascript +``` jsonc "mod:effectId":{ @@ -283,7 +283,7 @@ TODO TODO -``` javascript +``` jsonc "mod:effectId":{ @@ -304,7 +304,7 @@ TODO Configurable version of Clone spell. -``` javascript +``` jsonc "mod:effectId":{ @@ -320,7 +320,7 @@ TODO If effect is automatic, spell behave like offensive spell (uses power, levelPower etc) -``` javascript +``` jsonc "mod:effectId":{ @@ -368,7 +368,7 @@ TODO If effect is automatic, spell behave like \[de\]buff spell (effect and cumulativeEffects ignored) -``` javascript +``` jsonc "mod:effectId":{ @@ -389,21 +389,21 @@ cumulativeEffects ignored) TODO - CREATURE target (only battle spells) - - range 0: smart assumed single creature target - - range "X" + smart modifier = enchanter casting, expert massive spells - - range "X" + no smart modifier = armageddon, death ripple, destroy undead - - any other range (including chain effect) - - smart modifier: smth like cloud of confusion in H4 (if I remember correctly :) ) - - no smart modifier: like inferno, fireball etc. but target only creature +- range 0: smart assumed single creature target +- range "X" + smart modifier = enchanter casting, expert massive spells +- range "X" + no smart modifier = armageddon, death ripple, destroy undead +- any other range (including chain effect) +- smart modifier: smth like cloud of confusion in H4 (if I remember correctly :) ) +- no smart modifier: like inferno, fireball etc. but target only creature - NO_TARGET - - no target selection,(abilities, most adventure spells) +- no target selection,(abilities, most adventure spells) - LOCATION - - any tile on map/battlefield (inferno, fireball etc.), DD also here but with special handling - - clearTarget - destination hex must be clear (unused so far) - - clearAfffected - all affected hexes must be clear (forceField, fireWall) +- any tile on map/battlefield (inferno, fireball etc.), DD also here but with special handling +- clearTarget - destination hex must be clear (unused so far) +- clearAfffected - all affected hexes must be clear (forceField, fireWall) - OBSTACLE target - - range 0: any single obstacle - - range X: all obstacles \ No newline at end of file +- range 0: any single obstacle +- range X: all obstacles diff --git a/docs/modders/Entities_Format/Terrain_Format.md b/docs/modders/Entities_Format/Terrain_Format.md index d12a7f7cf..db7b0174f 100644 --- a/docs/modders/Entities_Format/Terrain_Format.md +++ b/docs/modders/Entities_Format/Terrain_Format.md @@ -75,4 +75,4 @@ "terrainViewPatterns" : "", } -``` \ No newline at end of file +``` diff --git a/docs/modders/Entities_Format/Town_Building_Format.md b/docs/modders/Entities_Format/Town_Building_Format.md index 67079fda4..9bbef202e 100644 --- a/docs/modders/Entities_Format/Town_Building_Format.md +++ b/docs/modders/Entities_Format/Town_Building_Format.md @@ -4,16 +4,19 @@ Each building requires following assets: -- Town animation file (1 animation file) -- Selection highlight (1 image) -- Selection area (1 image) -- Town hall icon (1 image) +- Town animation file (1 animation file) +- Selection highlight (1 image) +- Selection area (1 image) +- Town hall icon (1 image) ## Examples + These are just a couple of examples of what can be done in VCMI. See vcmi configuration files to check how buildings from Heroes III are implemented or other mods for more examples + #### -##### Order of Fire from Inferno: +##### Order of Fire from Inferno + ```jsonc "special4": { "requires" : [ "mageGuild1" ], @@ -34,9 +37,10 @@ These are just a couple of examples of what can be done in VCMI. See vcmi config ] } } -``` +``` ##### Mana Vortex from Dungeon + ```jsonc "special2": { "requires" : [ "mageGuild1" ], @@ -65,6 +69,7 @@ These are just a couple of examples of what can be done in VCMI. See vcmi config ``` #### Resource Silo with custom production + ```jsonc "resourceSilo": { "name" : "Wood Resource Silo", @@ -80,6 +85,7 @@ These are just a couple of examples of what can be done in VCMI. See vcmi config ``` #### Brotherhood of Sword - bonuses in siege + ```jsonc "special3": { // replaces +1 Morale bonus from Tavern @@ -96,6 +102,7 @@ These are just a couple of examples of what can be done in VCMI. See vcmi config ``` #### Lighthouse - bonus to all heroes under player control + ```jsonc "special1": { "bonuses": [ @@ -228,10 +235,13 @@ Building requirements can be described using logical expressions: ] ] ``` + ### List of unique town buildings #### Buildings from Heroes III + Following Heroes III buildings can be used as unique buildings for a town. Their functionality should be identical to a corresponding H3 building. H3 buildings that are not present in this list contain no hardcoded functionality. See vcmi json configuration to see how such buildings can be implemented in a mod. + - `mysticPond` - `artifactMerchant` - `freelancersGuild` @@ -244,12 +254,14 @@ Following Heroes III buildings can be used as unique buildings for a town. Their - `treasury` #### Buildings from other Heroes III mods + Following HotA buildings can be used as unique building for a town. Functionality should match corresponding HotA building: + - `bank` #### Custom buildings -In addition to above, it is possible to use same format as [Rewardable](../Map_Objects/Rewardable.md) map objects for town buildings. In order to do that, configuration of a rewardable object must be placed into `configuration` json node in building config. +In addition to above, it is possible to use same format as [Rewardable](../Map_Objects/Rewardable.md) map objects for town buildings. In order to do that, configuration of a rewardable object must be placed into `configuration` json node in building config. ### Town Structure node @@ -281,16 +293,18 @@ In addition to above, it is possible to use same format as [Rewardable](../Map_O } ``` - #### Markets in towns + Market buildings require list of available [modes](../Map_Objects/Market.md) ##### Marketplace + ```jsonc "marketplace": { "marketModes" : ["resource-resource", "resource-player"] }, ``` ##### Artifact merchant + ```jsonc "special1": { "type" : "artifactMerchant", "requires" : [ "marketplace" ], "marketModes" : ["resource-artifact", "artifact-resource"] }, -``` \ No newline at end of file +``` diff --git a/docs/modders/File_Formats.md b/docs/modders/File_Formats.md index b80188625..900c90a25 100644 --- a/docs/modders/File_Formats.md +++ b/docs/modders/File_Formats.md @@ -1,12 +1,13 @@ # File Formats -This page describes which file formats are supported by vcmi. +This page describes which file formats are supported by vcmi. In most cases, VCMI supports formats that were supported by Heroes III, with addition of new formats that are more convenient to use without specialized tools. See categories below for more details on specific formats ### Images For images VCMI supports: + - png. Recommended for usage in mods - bmp. While this format is supported, bmp images have no compressions leading to large file sizes - pcx (h3 version). Note that this is format that is specific to Heroes III and has nothing in common with widely known .pcx format. Files in this format generally can only be found inside of .lod archive of Heroes III and are usually extracted as .bmp files @@ -26,6 +27,7 @@ For animations VCMI supports .def format from Heroes III as well as alternative ### Sounds For sounds VCMI currently supports: + - .ogg/vorbis format - preferred for mods. Unlike wav, vorbis uses compression which may cause some data loss, however even 128kbit is generally undistinguishable from lossless formats - .wav format. This is format used by H3. It is supported by vcmi, but it may result in large file sizes (and as result - large mods) @@ -36,6 +38,7 @@ Support for additional formats, such as ogg/opus or flac may be added in future ### Music For music VCMI currently supports: + - .ogg/vorbis format - preferred for mods. Generally offers better quality and lower sizes compared to mp3 - .mp3 format. This is format used by H3 @@ -51,6 +54,7 @@ Starting from VCMI 1.6, following video container formats are supported by VCMI: - .webm - modern, free format that is recommended for modding. Supported video codecs: + - bink and smacker - formats used by Heroes III, should be used only to avoid re-encoding - theora - used by Heroes III: HD Edition - vp8 - modern format with way better compression compared to formats used by Heroes III @@ -59,6 +63,7 @@ Supported video codecs: Support for av1 video codec is likely to be added in future. Supported audio codecs: + - binkaudio and smackaud - formats used by Heroes III - vorbis - modern format with good compression level - opus - recommended, improvement over vorbis. Any bitrate is supported, with 128 kbit probably being the best option diff --git a/docs/modders/Game_Identifiers.md b/docs/modders/Game_Identifiers.md index 4e212fe01..24e95b530 100644 --- a/docs/modders/Game_Identifiers.md +++ b/docs/modders/Game_Identifiers.md @@ -493,7 +493,7 @@ This is a list of all game identifiers available to modders. Note that only iden - hero.thorgrim - hero.thunar - hero.tiva -- hero.torosar +- hero.torosar - hero.tyraxor - hero.tyris - hero.ufretin diff --git a/docs/modders/HD_Graphics.md b/docs/modders/HD_Graphics.md index fc0f155e8..d16b53d44 100644 --- a/docs/modders/HD_Graphics.md +++ b/docs/modders/HD_Graphics.md @@ -13,6 +13,7 @@ If user for example selects 3x resolution and only 2x exists in mod then the 2x ## Mod For upscaled images you have to use following folders (next to `sprites` and `data` folders): + - `sprites2x`, `sprites3x`, `sprites4x` for sprites - `data2x`, `data3x`, `data4x` for images @@ -24,11 +25,13 @@ It's also possible (but not necessary) to add high-definition shadows: Just plac In future, such shadows will likely become required to correctly exclude shadow from effects such as Clone spell. Shadow images are used only for animations of following objects: + - All adventure map objects - All creature animations in combat Same for overlays with `-overlay`. But overlays are **necessary** for some animation graphics. They will be colorized by VCMI. Currently needed for: + - Flaggable adventure map objects. Overlay must contain a transparent image with white flags on it and will be used to colorize flags to owning player - Creature battle animations, idle and mouse hover group. Overlay must contain a transparent image with white outline of creature for highlighting on mouse hover) diff --git a/docs/modders/Map_Editor.md b/docs/modders/Map_Editor.md index 3c472d8a3..3d5ca096b 100644 --- a/docs/modders/Map_Editor.md +++ b/docs/modders/Map_Editor.md @@ -38,7 +38,7 @@ Templates are dynamically filtered depending on parameters you choose. 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. +You can load both *.h3m and*.vmap formats but for saving *.vmap is allowed only. ## Views @@ -60,7 +60,7 @@ There are 3 buttons switching views Снимок экра <img width= -# Setup terrain +## Setup terrain 1. Select brush you want @@ -77,7 +77,7 @@ There are 3 buttons switching views Снимок экра #### 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. +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= @@ -85,9 +85,10 @@ To erase roads or rivers, you need to select tiles to be cleaned and press empty -_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_ +*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) @@ -171,7 +172,7 @@ You can modify general properties of the map ## Player settings -Open **Map** menu on the top and select **Player settings" +Open **Map** menu on the top and select **Player settings" @@ -208,6 +209,7 @@ vcmieditor loads set of mods using exactly same mechanism as game uses and mod m 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 @@ -233,4 +235,4 @@ You also may have other mods being activated in addition to what was used during #### 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 \ No newline at end of file +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 diff --git a/docs/modders/Map_Object_Format.md b/docs/modders/Map_Object_Format.md index 5f6472e6c..a42641fe6 100644 --- a/docs/modders/Map_Object_Format.md +++ b/docs/modders/Map_Object_Format.md @@ -4,11 +4,11 @@ Full object consists from 3 parts: -- Object group - set of objects that have similar behavior and share +- Object group - set of objects that have similar behavior and share same identifier in H3 (towns, heroes, mines, etc) -- Object type - object with fixed behavior but without fixed +- Object type - object with fixed behavior but without fixed appearance. Multiple objects types may share same group -- Object template - defines appearance of an object - image used to +- Object template - defines appearance of an object - image used to display it, its size & blockmap. These entries only describe templates that will be used when object is placed via map editor or generated by the game. When new object is created its starting @@ -16,7 +16,7 @@ Full object consists from 3 parts: ## Object group format -``` javascript +``` jsonc { "myCoolObjectGroup": @@ -42,6 +42,7 @@ Full object consists from 3 parts: ## Object types ### Moddable types + These are object types that are available for modding and have configurable properties - `configurable` - see [Rewardable](Map_Objects/Rewardable.md). Visitable object which grants all kinds of rewards (gold, experience, Bonuses etc...) @@ -55,6 +56,7 @@ These are object types that are available for modding and have configurable prop - `terrain` - Defines terrain overlays such as magic grounds. TODO: documentation. See config files in vcmi installation for reference ### Common types + These are types that don't have configurable properties, however it is possible to add additional map templates for this objects, for use in editor or in random maps generator - `static` - Defines unpassable static map obstacles that can be used by RMG @@ -79,6 +81,7 @@ These are types that don't have configurable properties, however it is possible - `monolith` ### Internal types + These are internal types that are generally not available for modding and are handled by vcmi internally. - `hero` @@ -96,7 +99,7 @@ These are internal types that are generally not available for modding and are ha ## Object type format -``` javascript +``` jsonc { "myCoolObject": { @@ -150,7 +153,7 @@ These are internal types that are generally not available for modding and are ha ## Object template format -``` javascript +``` jsonc { "myCoolObjectTemplate" : { diff --git a/docs/modders/Map_Objects/Boat.md b/docs/modders/Map_Objects/Boat.md index 8d67581a5..f88a980e4 100644 --- a/docs/modders/Map_Objects/Boat.md +++ b/docs/modders/Map_Objects/Boat.md @@ -1,6 +1,6 @@ # Boat -``` javascript +``` jsonc { // Layer on which this boat moves. Possible values: // "land" - same rules as movement of hero on land @@ -27,4 +27,4 @@ // List of bonuses that will be granted to hero located in the boat "bonuses" : { BONUS_FORMAT } } -``` \ No newline at end of file +``` diff --git a/docs/modders/Map_Objects/Creature_Bank.md b/docs/modders/Map_Objects/Creature_Bank.md index e5389846b..0fcbe3e4f 100644 --- a/docs/modders/Map_Objects/Creature_Bank.md +++ b/docs/modders/Map_Objects/Creature_Bank.md @@ -6,8 +6,10 @@ Format of rewards is same as in [Rewardable Objects](Rewardable.md) Deprecated in 1.6. Please use [Rewardable Objects](Rewardable.md) instead. See Conversion from 1.5 format section below for help with migration ### Example + This example defines a rewardable object with functionality similar of H3 creature bank. See [Rewardable Objects](Rewardable.md) for detailed documentation of these properties. + ```jsonc { "name" : "Cyclops Stockpile", @@ -93,6 +95,7 @@ See [Rewardable Objects](Rewardable.md) for detailed documentation of these prop ``` ### Conversion from 1.5 format + This is a list of changes that needs to be done to bank config to migrate it to 1.6 system. See [Rewardable Objects](Rewardable.md) documentation for description of new fields - If your object type has defined `handler`, change its value from `bank` to `configurable` diff --git a/docs/modders/Map_Objects/Dwelling.md b/docs/modders/Map_Objects/Dwelling.md index df369c502..04470a5b7 100644 --- a/docs/modders/Map_Objects/Dwelling.md +++ b/docs/modders/Map_Objects/Dwelling.md @@ -1,6 +1,6 @@ # Dwelling -``` javascript +``` jsonc { /// List of creatures in this bank. Each list represents one "level" of bank /// Creatures on the same level will have shared growth and available number (similar to towns) @@ -19,4 +19,4 @@ { "amount" : 12, "type" : "earthElemental" } ] } -``` \ No newline at end of file +``` diff --git a/docs/modders/Map_Objects/Flaggable.md b/docs/modders/Map_Objects/Flaggable.md index f11bfca79..2880a4d9e 100644 --- a/docs/modders/Map_Objects/Flaggable.md +++ b/docs/modders/Map_Objects/Flaggable.md @@ -3,6 +3,7 @@ Flaggable object are those that can be captured by a visiting hero. H3 examples are mines, dwellings, or lighthouse. Currently, it is possible to make flaggable objects that provide player with: + - Any [Bonus](Bonus_Format.md) supported by bonus system - Daily resources income (wood, ore, gold, etc) diff --git a/docs/modders/Map_Objects/Market.md b/docs/modders/Map_Objects/Market.md index 2b411dfb8..2e748e5a1 100644 --- a/docs/modders/Map_Objects/Market.md +++ b/docs/modders/Map_Objects/Market.md @@ -34,6 +34,7 @@ Here is schema describing such object 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 @@ -49,6 +50,7 @@ Following options are supported: ### 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"] ``` @@ -98,4 +100,4 @@ See [Secondary skills](Rewardable.md#secondary-skills) description for more deta { "noneOf" : ["necromancy"] }, { "noneOf" : ["necromancy"] } ] -``` \ No newline at end of file +``` diff --git a/docs/modders/Map_Objects/Rewardable.md b/docs/modders/Map_Objects/Rewardable.md index d7b1761d3..e26256567 100644 --- a/docs/modders/Map_Objects/Rewardable.md +++ b/docs/modders/Map_Objects/Rewardable.md @@ -1,7 +1,9 @@ # Rewardable ## Base object definition + Rewardable object is defined similarly to other objects, with key difference being `handler`. This field must be set to `"handler" : "configurable"` in order for vcmi to use this mode. + ```jsonc { "baseObjectName" : { @@ -34,6 +36,7 @@ Rewardable object is defined similarly to other objects, with key difference bei ``` ## Configurable object definition + ```jsonc // List of potential rewards "rewards" : [ @@ -173,6 +176,7 @@ This property allows defining "variables" that are shared between all rewards an Variables are randomized only once, so you can use them multiple times for example, to give skill only if hero does not have this skill (e.g. Witch Hut). Example of creation of a variable named "gainedSkill" of type "secondarySkill": + ```json "variables" : { "secondarySkill" : { @@ -187,6 +191,7 @@ Example of creation of a variable named "gainedSkill" of type "secondarySkill": ``` Possible variable types: + - number: can be used in any place that expects a number - artifact - spell @@ -194,6 +199,7 @@ Possible variable types: - secondarySkill To reference variable in limiter prepend variable name with '@' symbol: + ```json "secondary" : { "@gainedSkill" : 1 @@ -201,7 +207,9 @@ To reference variable in limiter prepend variable name with '@' symbol: ``` ## Reset Parameters definition + 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" @@ -215,9 +223,11 @@ This property describes how object state should be reset. Objects without this f ``` ## 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. Note that object that uses appearChance MUST have continuous range for every value in 0-99 range. For example, object with 3 different rewards may want to define them as + - `"min" : 0, "max" : 33` - `"min" : 33, "max" : 66` - `"min" : 66, "max" : 100` @@ -240,16 +250,19 @@ In other words, min chance of second reward must be equal to max chance of previ ``` ## Configurable Properties + Unless stated othervice, all numbers in this section can be replaced with random values, e.g. + ```jsonc "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. +In this case, actual value for minLevel will be picked randomly. Keep in mind, that all randomization is performed on map load and on object reset (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 ```jsonc @@ -263,6 +276,7 @@ Keep in mind, that all randomization is performed on map load and on object rese ``` ### 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 @@ -273,6 +287,7 @@ Keep in mind, that all randomization is performed on map load and on object rese "gold" : -1000, }, ``` + - Alternative format that allows random selection of a resource type ```jsonc @@ -289,6 +304,7 @@ Keep in mind, that all randomization is performed on map load and on object rese ``` ### Experience + - Can be used as limiter - Can be used as reward to grant experience to hero @@ -297,6 +313,7 @@ Keep in mind, that all randomization is performed on map load and on object rese ``` ### Hero Level + - Can be used as limiter. Hero requires to have at least specified level - 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) @@ -305,6 +322,7 @@ Keep in mind, that all randomization is performed on map load and on object rese ``` ### Mana Points + - 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 @@ -320,6 +338,7 @@ Keep in mind, that all randomization is performed on map load and on object rese ``` ### Mana Percentage + - 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) @@ -328,14 +347,16 @@ Keep in mind, that all randomization is performed on map load and on object rese ``` ### 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. ```jsonc "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 @@ -344,6 +365,7 @@ Keep in mind, that all randomization is performed on map load and on object rese ``` ### 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 @@ -376,12 +398,14 @@ Keep in mind, that all randomization is performed on map load and on object rese ``` ### 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) - Each secondary skill can be explicitly specified or randomly selected + ```jsonc "secondary": [ { @@ -416,6 +440,7 @@ Keep in mind, that all randomization is performed on map load and on object rese ``` ### Bonus System + - Can be used as reward, to grant bonus to player - if present, MORALE and LUCK bonus will add corresponding image component to UI. - Note that unlike most values, parameter of bonuses can NOT be randomized @@ -433,6 +458,7 @@ Keep in mind, that all randomization is performed on map load and on object rese ``` ### 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 - Artifacts added as reward will be used for text substitution. First `%s` in text string will be replaced with name of an artifact @@ -458,6 +484,7 @@ Keep in mind, that all randomization is performed on map load and on object rese ``` ### Spells + - Can be used as limiter - Can be used as reward, to give new spell to a hero - Spells added as reward will be used for text substitution. First `%s` in text string will be replaced with spell name @@ -485,7 +512,7 @@ Keep in mind, that all randomization is performed on map load and on object rese - Can be used as limiter. Hero must be able to learn spell to pass the limiter - Hero is considered to not able to learn the spell if: - - he already has specified spell -- - he does not have a spellbook +- - he does not have a spellbook - - he does not have sufficient Wisdom level for this spell ```json @@ -495,10 +522,12 @@ Keep in mind, that all randomization is performed on map load and on object rese ``` ### 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 probability to receive upgraded creature + ```jsonc "creatures" : [ { @@ -510,12 +539,14 @@ Keep in mind, that all randomization is performed on map load and on object rese ``` ### Guards + - When used in a reward, these creatures will be added to guards of the objects - Hero must defeat all guards before being able to receive rewards - Guards are only reset when object rewards are reset - Requires `guardsLayout` property to be set in main part of object configuration - It is possible to add up to 7 slots of creatures - Guards of the same creature type will never merge or rearrange their stacks + ```jsonc "guards" : [ { "type" : "archer", "amount" : 20 }, @@ -525,6 +556,7 @@ Keep in mind, that all randomization is performed on map load and on object rese ``` ### Creatures Change + - Can NOT be used as limiter - 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 - This parameter will not change creatures given by `creatures` parameter on the same visit @@ -536,6 +568,7 @@ Keep in mind, that all randomization is performed on map load and on object rese ``` ### Spell cast + - Can NOT be used as limiter - 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) @@ -567,6 +600,7 @@ Keep in mind, that all randomization is performed on map load and on object rese ``` ### Player color + - Can be used as limiter - Can NOT be used as reward - Only players with specific color can pass the limiter @@ -576,6 +610,7 @@ Keep in mind, that all randomization is performed on map load and on object rese ``` ### Hero types + - Can be used as limiter - Can NOT be used as reward - Only specific heroes can pass the limiter @@ -585,10 +620,11 @@ Keep in mind, that all randomization is performed on map load and on object rese ``` ### Hero classes + - Can be used as limiter - Can NOT be used as reward - Only heroes belonging to specific classes can pass the limiter ```jsonc "heroClasses" : [ "battlemage" ] -``` \ No newline at end of file +``` diff --git a/docs/modders/Mod_File_Format.md b/docs/modders/Mod_File_Format.md index 8a689ccf8..49ed6866e 100644 --- a/docs/modders/Mod_File_Format.md +++ b/docs/modders/Mod_File_Format.md @@ -2,7 +2,7 @@ ## Fields with description of mod -``` javascript +``` jsonc { // Name of your mod. While it does not have hard length limit // it should not be longer than ~30 symbols to fit into allowed space @@ -91,7 +91,7 @@ These are fields that are present only in local mod.json file -``` javascript +``` jsonc { // Following section describes configuration files with content added by mod @@ -228,4 +228,4 @@ These are fields that are present only in remote repository and are generally no For mod description it is possible to use certain subset of HTML as described here: - \ No newline at end of file + diff --git a/docs/modders/Random_Map_Template.md b/docs/modders/Random_Map_Template.md index 309d84e8e..7c02667ec 100644 --- a/docs/modders/Random_Map_Template.md +++ b/docs/modders/Random_Map_Template.md @@ -2,7 +2,7 @@ ## Template format -``` javascript +``` jsonc /// Unique template name "Triangle" : { @@ -56,7 +56,7 @@ ## Zone format -``` javascript +``` jsonc { // Type of this zone. Possible values are: // "playerStart", "cpuStart", "treasure", "junction" @@ -157,4 +157,4 @@ ] } } -``` \ No newline at end of file +``` diff --git a/docs/modders/Readme.md b/docs/modders/Readme.md index 5fba25113..13ac5fd98 100644 --- a/docs/modders/Readme.md +++ b/docs/modders/Readme.md @@ -21,8 +21,8 @@ Example of how directory structure of your mod may look like: sprites/ - animation, image sets (H3 .def files or VCMI .json files) video/ - video files, .bik, .smk, .ogv .webm ``` -See [File Formats](File_Formats.md) page for more information on which formats are supported or recommended for vcmi +See [File Formats](File_Formats.md) page for more information on which formats are supported or recommended for vcmi ## Creating mod file @@ -30,7 +30,7 @@ All VCMI configuration files use [JSON format](http://en.wikipedia.org/wiki/Json Mod.json is main file in your mod and must be present in any mod. This file contains basic description of your mod, dependencies or conflicting mods (if present), list of new content and so on. Minimalistic version of this file: -``` javascript +``` jsonc { "name" : "My test mod", "description" : "My test mod that add a lot of useless stuff into the game", @@ -45,6 +45,7 @@ See [Mod file Format](Mod_File_Format.md) for its full description. ## Creation of new objects In order to create new object use following steps: + 1. Create json file with definition of new object. See list of supported object types below. 2. Add any resources needed for this object, such as images, animations or sounds. 2. Add reference to new object in corresponding section of mod.json file @@ -52,9 +53,11 @@ In order to create new object use following steps: ### List of supported new object types Random Map Generator: + - [Random Map Template](Random_Map_Template.md) Game Entities: + - [Artifact](Entities_Format/Artifact_Format.md) - [Creature Requirement](Entities_Format/Creature_Format.md) - [Creature Help](Entities_Format/Creature_Help.md) @@ -66,6 +69,7 @@ Game Entities: - [Secondary Skill](Entities_Format/Secondary_Skill_Format.md) Map objects: + - [Map Objects](Map_Object_Format.md) - - [Rewardable](Map_Objects/Rewardable.md) - - [Creature Bank](Map_Objects/Creature_Bank.md) @@ -74,6 +78,7 @@ Map objects: - - [Boat](Map_Objects/Boat.md) Other: + - [Terrain](Entities_Format/Terrain_Format.md) - [River](Entities_Format/River_Format.md) - [Road](Entities_Format/Road_Format.md) @@ -96,7 +101,8 @@ VCMI uses strings to reference objects. Examples: ### Modifying existing objects Alternatively to creating new objects, you can edit existing objects. Normally, when creating new objects you specify object name as: -``` javascript + +``` jsonc "newCreature" : { // creature parameters } @@ -104,7 +110,7 @@ Alternatively to creating new objects, you can edit existing objects. Normally, In order to access and modify existing object you need to specify mod that you wish to edit: -``` javascript +``` jsonc /// "core" specifier refers to objects that exist in H3 "core:archer" : { /// This will set health of Archer to 10 @@ -123,6 +129,7 @@ In order to access and modify existing object you need to specify mod that you w "speed" : 10 }, ``` + Note that modification of existing objects does not requires a dependency on edited mod. Such definitions will only be used by game if corresponding mod is installed and active. This allows using objects editing not just for rebalancing mods but also to provide compatibility between two different mods or to add interaction between two mods. @@ -132,6 +139,7 @@ This allows using objects editing not just for rebalancing mods but also to prov Any graphical replacer mods fall under this category. In VCMI directory **/Content** acts as mod-specific game root directory. So for example file **/Content/Data/AISHIELD.PNG** will replace file with same name from **H3Bitmap.lod** game archive. Any other files can be replaced in exactly same way. Note that replacing files from archives requires placing them into specific location: + - H3Bitmap.lod -> Data - H3Sprite.lod -> Sprites - Heroes3.snd -> Sounds @@ -145,12 +153,13 @@ This includes archives added by expansions (e.g. **H3ab_bmp.lod** uses same rule Heroes III uses custom format for storing animation: def files. These files are used to store all in-game animations as well as for some GUI elements like buttons and for icon sets. These files can be replaced by another def file but in some cases original format can't be used. This includes but not limited to: -- Replacing one (or several) icons in set -- Replacing animation with fully-colored 32-bit images + +- Replacing one (or several) icons in set +- Replacing animation with fully-colored 32-bit images In VCMI these animation files can also be replaced by json description of their content. See [Animation Format](Animation_Format.md) for full description of this format. Example: replacing single icon -``` javascript +``` jsonc { // List of replaced images "images" : @@ -191,7 +200,7 @@ Same way we can also create special stable branch for every mod under "vcmi-mods ### Getting into vcmi-mods organization Before your mod can be accepted into official mod list you need to get it into repository under "vcmi-mods" organization umbrella. To do this contact one of mod repository maintainers. If needed you can get own team within "vcmi-mods" organization. -Link to our mod will looks like that: https://github.com/vcmi-mods/adventure-ai-trace +Link to our mod will looks like that: ## Rules of repository @@ -199,8 +208,8 @@ Link to our mod will looks like that: https://github.com/vcmi-mods/adventure-ai- For sanity reasons mod identifier must only contain lower-case English characters, numbers and hyphens. - my-mod-name - 2000-new-maps +`my-mod-name` +`2000-new-maps` Sub-mods can be named as you like, but we strongly encourage everyone to use proper identifiers for them as well. diff --git a/docs/players/Bug_Reporting_Guidelines.md b/docs/players/Bug_Reporting_Guidelines.md index eabe6b6af..067a59e84 100644 --- a/docs/players/Bug_Reporting_Guidelines.md +++ b/docs/players/Bug_Reporting_Guidelines.md @@ -23,9 +23,9 @@ First of all, if you encounter a crash, don't re-run VCMI immediately to see if By default, log files are written to: -- Windows: Documents\My Games\vcmi\\ -- Linux: ~/.cache/vcmi/ -- Android: Android/data/is.xyz.vcmi/files/vcmi-data/cache/ +- Windows: Documents\My Games\vcmi\\ +- Linux: ~/.cache/vcmi/ +- Android: Android/data/is.xyz.vcmi/files/vcmi-data/cache/ Now you should try to reproduce encountered issue. It's best when you write how to reproduce the issue by starting a new game and taking some steps (e.g. start Arrogance map as red player and attack monster Y with hero X). If you have troubles with reproducing it this way but you can do it from a savegame - that's good too. Finally, when you are not able to reproduce the issue at all, just upload the files mentioned above. To sum up, this is a list of what's the most desired for a developer: diff --git a/docs/players/Cheat_Codes.md b/docs/players/Cheat_Codes.md index 288c9f842..413c60c33 100644 --- a/docs/players/Cheat_Codes.md +++ b/docs/players/Cheat_Codes.md @@ -70,13 +70,15 @@ Alternative usage: `vcmiexp ` - gives selected hero specified amount of `nwcbluepill` or `vcmimelkor` or `vcmilose` - player loses ### Misc + `nwctheone` or `vcmigod` - reveals the whole map, gives 5 archangels in each empty slot, unlimited movement points and permanent flight ## Using cheat codes on other players + By default, all cheat codes apply to current player. Alternatively, it is possible to specify player that you want to target: - Specific players: `red`/`blue`/`green`... -- Only AI players: `ai` +- Only AI players: `ai` - All players: `all` ### Examples @@ -89,12 +91,14 @@ By default, all cheat codes apply to current player. Alternatively, it is possib ## Multiplayer chat commands Following commands can be used in multiplayer only by host player to control the session: + - `!exit` - finish the game - `!save ` - save the game into the specified file - `!kick red/blue/tan/green/orange/purple/teal/pink` - kick player of specified color from the 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`) +- `!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`) Following commands can be used by any player in multiplayer: + - `!help` - displays in-game list of available commands - `!cheaters` - lists players that have entered cheat at any point of the game - `!vote` - initiates voting to change one of the possible options: @@ -114,12 +118,14 @@ Windows builds of VCMI run separate console window by default, on other platform Below a list of supported commands, with their arguments wrapped in `<>` #### Game Commands + `die, fool` - quits game `save ` - 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 + `translate` - save game texts into json files `translate missing` - save untranslated game texts into json files `translate maps` - save map and campaign texts into json files @@ -131,15 +137,17 @@ Below a list of supported commands, with their arguments wrapped in `<>` `generate assets` - generate all assets at once #### AI commands + `setBattleAI ` - 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 ` - 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_ +-`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 @@ -147,6 +155,7 @@ Below a list of supported commands, with their arguments wrapped in `<>` -`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) diff --git a/docs/players/Game_Mechanics.md b/docs/players/Game_Mechanics.md index e64f7e94e..54df67881 100644 --- a/docs/players/Game_Mechanics.md +++ b/docs/players/Game_Mechanics.md @@ -58,7 +58,7 @@ These bugs were present in original Shadow of Death game, however the team decid Some of H3 mechanics can't be straight considered as bug, but default VCMI behaviour is different: - Pathfinding. Hero can't grab artifact while flying when all tiles around it are guarded without triggering attack from guard. -- Battles. Hero that won battle, but only have temporary summoned creatures alive going to appear in tavern like if he retreated. +- Battles. Hero that won battle, but only have temporary summoned creatures alive going to appear in tavern like if he retreated. - Battles. Spells from artifacts like AOTD are autocasted on beginning of the battle, not beginning of turn. ## Adventure map features @@ -106,7 +106,7 @@ In combat, some creatures, such as Dragon or Cerberi, may attack enemies on mult - [LCtrl] + LClick – splits a single unit from the selected stack into an empty slot. - [LCtrl] + [LShift] + LClick – split single units from the selected stack into all empty hero/garrison slots - [Alt] + LClick – merge all split single units into one stack -- [Alt] + [LCtrl] + LClick - move all units of selected stack to the city's garrison or to the met hero +- [Alt] + [LCtrl] + LClick - move all units of selected stack to the city's garrison or to the met hero - [Alt] + [LShift] + LClick - dismiss selected stack` - Directly type numbers in the Split Stack window to split them in any way you wish @@ -174,6 +174,7 @@ TODO Simultaneous turns allow multiple players to act at the same time, speeding up early game phase in multiplayer games. During this phase if different players (allies or not) attempt to interact with each other, such as capture objects owned by other players (mines, dwellings, towns) or attack their heroes, game will block such actions. Interaction with same map objects at the same time, such as attacking same wandering monster is also blocked. Following options can be used to configure simultaneous turns: + - Minimal duration (at least for): this is duration during which simultaneous turns will run unconditionally. Until specified number of days have passed, simultaneous turns will never break and game will not attempt to detect contacts. - Maximal duration (at most for): this is duration after which simultaneous turns will end unconditionally, even if players still have not contacted each other. However if contact detection discovers contact between two players, simultaneous turns between them might end before specified duration. - Simultaneous turns for AI: If this option is on, AI can act at the same time as human players. Note that AI shares settings for simultaneous turns with human players - if no simultaneous turns have been set up this option has no effect. @@ -185,6 +186,7 @@ Players are considered to be "in contact" if movement range of their heroes at t Once detected, contact can never be "lost". If game detected contact between two players, this contact will remain active till the end of the game, even if their heroes move far enough from each other. Game performs contact detection once per turn, at the very start of each in-game day. Once contact detection has been performed, players that are not in contact with each other can start making turn. For example, in game with 4 players: red, blue, brown and green. If game detected contact between red and blue following will happen: + - red, brown and green will all instantly start turn - once red ends his turn, blue will be able to start his own turn (even if brown or green are still making turn) @@ -197,4 +199,4 @@ Differences compared to HD Mod version: ## Manuals and guides -- https://heroes.thelazy.net/index.php/Main_Page Wiki that aims to be a complete reference to Heroes of Might and Magic III. +- Wiki that aims to be a complete reference to Heroes of Might and Magic III. diff --git a/docs/players/Installation_Linux.md b/docs/players/Installation_Linux.md index 9440246b3..c15df8c93 100644 --- a/docs/players/Installation_Linux.md +++ b/docs/players/Installation_Linux.md @@ -9,6 +9,7 @@ VCMI requires data from original Heroes 3: Shadow of Death or Complete editions. Up-to-date releases can be found in our PPA here: To install VCMI from PPA use: + ``` sudo apt-add-repository ppa:vcmi/ppa sudo apt update @@ -20,25 +21,30 @@ To install VCMI from PPA use: We also provide latest, unstable builds mostly suitable for testing here: In order to install from this PPA use: + ``` sudo add-apt-repository ppa:vcmi/vcmi-latest sudo apt update sudo apt install vcmi ``` + ### Ubuntu - From Ubuntu repository VCMI stable builds available in "multiverse" repository. Learn how to enable it in [Ubuntu wiki](https://help.ubuntu.com/community/Repositories/Ubuntu). Once enabled, you can install VCMI using Ubuntu Store or in terminal using following commands: + ``` sudo apt update sudo apt install vcmi ``` + Note that version available in Ubuntu is outdated. Install via PPA is preferred. ### Debian Stable VCMI version is available in "contrib" repository. Learn how to enable it in [Debian wiki](https://wiki.debian.org/SourcesList). To install VCMI from repository: + ``` sudo apt-get update sudo apt-get install vcmi @@ -52,6 +58,7 @@ Stable VCMI version is available in RPM Fusion repository. Learn how to enable i sudo dnf update sudo dnf install vcmi ``` + ### Flatpak (distribution-agnostic) Latest public release build can be installed via Flatpak. @@ -63,8 +70,8 @@ Once you have flatpak, you can install VCMI package which can be found here: -- Daily builds (unstable): -- Please report about problems on GitHub: [Bug Tracker](https://github.com/vcmi/vcmi/issues) +- Latest release (recommended): +- Daily builds (unstable): +- Please report about problems on GitHub: [Bug Tracker](https://github.com/vcmi/vcmi/issues) ## Step 2: Installing Heroes III data files **Since VCMI 1.2 you can skip this step, just run VCMI launcher and it will help you with importing H3 data. For older releases you can follow this step.** -- Install Heroes III from disk or using GOG installer. -- Place "Data", "Maps" and "Mp3" from Heroes III to: `Documents\My Games\vcmi\` +- Install Heroes III from disk or using GOG installer. +- Place "Data", "Maps" and "Mp3" from Heroes III to: `Documents\My Games\vcmi\` Create this folder if it doesnt exist yet ## Step 3: connect to the mod repository - If that's your first installation, connection to the mod repository will be configured automatically, you'll see mods available to install from VCMI launcher - -- We recommend you to install VCMI extras to support various helpful UI tweaks +- We recommend you to install VCMI extras to support various helpful UI tweaks diff --git a/docs/players/Installation_iOS.md b/docs/players/Installation_iOS.md index 4dfcd7478..54da2b7b4 100644 --- a/docs/players/Installation_iOS.md +++ b/docs/players/Installation_iOS.md @@ -6,7 +6,7 @@ You can run VCMI on iOS 12.0 and later, all devices are supported. If you wish t The easiest and recommended way to install on a non-jailbroken device is to install the [AltStore Classic](https://altstore.io/) or [Sideloadly](https://sideloadly.io/). We will use AltStore as an example below. Using this method means the VCMI certificate is auto-signed automatically. -i) Use [AltStore Windows](https://faq.altstore.io/altstore-classic/how-to-install-altstore-windows) or [AltStore macOS](https://faq.altstore.io/altstore-classic/how-to-install-altstore-macos) instructions to install the store depending on the operating system you are using. +i) Use [AltStore Windows](https://faq.altstore.io/altstore-classic/how-to-install-altstore-windows) or [AltStore macOS](https://faq.altstore.io/altstore-classic/how-to-install-altstore-macos) instructions to install the store depending on the operating system you are using. If you're having trouble enabling "sync with this iOS device over Wi-Fi" press on the rectangular shape below "Account". Windows example from iTunes shown below: @@ -19,15 +19,14 @@ iii) To install the .ipa file on your device do one of the following: - In AltStore go to >My Apps > press + in the top left corner. Select VCMI-iOS.ipa to install, - or drag and drop the .ipa file into your iOS device in iTunes - ## Step 2: Installing Heroes III data files -If you bought HoMM3 on [GOG](https://www.gog.com/de/game/heroes_of_might_and_magic_3_complete_edition), you can download the files directly from the browser in the device. - -Launch VCMI app on the device and the launcher will prompt two files to complete the installation. Select the **.bin** file first, then the **.exe** file. This may take a few seconds. Please be patient. +If you bought HoMM3 on [GOG](https://www.gog.com/de/game/heroes_of_might_and_magic_3_complete_edition), you can download the files directly from the browser in the device. +Launch VCMI app on the device and the launcher will prompt two files to complete the installation. Select the **.bin** file first, then the **.exe** file. This may take a few seconds. Please be patient. ## Step 3: Configuration settings + Once you have installed VCMI and have the launcher opened, select Settings on the left bar. The following Video settings are recommended: - Lower reserved screen area to zero. @@ -42,7 +41,7 @@ Together, the two options should eliminate black bars and enable full screen VCM To run on a non-jailbroken device you need to sign the IPA file, you have the following aternative options: -- if you're on iOS 14.0-15.4.1, you can try . +- if you're on iOS 14.0-15.4.1, you can try . - Get signer tool [here](https://dantheman827.github.io/ios-app-signer/) and a guide [here](https://forum.kodi.tv/showthread.php?tid=245978) (it's for Kodi, but the logic is the same). Signing with this app can only be done on macOS. - [Create signing assets on macOS from terminal](https://github.com/kambala-decapitator/xcode-auto-signing-assets). In the command replace `your.bundle.id` with something like `com.MY-NAME.vcmi`. After that use the above signer tool. - [Sign from any OS (Rust)](https://github.com/indygreg/PyOxidizer/tree/main/tugger-code-signing) / [alternative project (C++)](https://github.com/zhlynn/zsign). You'd still need to find a way to create signing assets (private key and provisioning profile) though. @@ -54,7 +53,7 @@ The easiest way to install the ipa on your device is to do one of the following: Alternatively, to install the signed ipa on your device, you can use Xcode or Apple Configurator (available on the Mac App Store for free). The latter also allows installing ipa from the command line, here's an example that assumes you have only 1 device connected to your Mac and the signed ipa is on your desktop: - /Applications/Apple\ Configurator.app/Contents/MacOS/cfgutil install-app ~/Desktop/vcmi.ipa +`/Applications/Apple\ Configurator.app/Contents/MacOS/cfgutil install-app ~/Desktop/vcmi.ipa` ## Alternative Step 2: Installing Heroes III data files @@ -79,7 +78,7 @@ You can also upload files with Xcode. You need to prepare "container" for that. 3. Open Devices and Simulators window: Cmd+Shift+2 or Menu - Window - Devices and Simulators 4. Select your device 5. Select VCMI -6. In the bottom find "three dots" or "cogwheel" button (it should be next to + - buttons) - click it - select Download Container... +6. In the bottom find "three dots" or "cogwheel" button (it should be next to + - buttons) - click it - select Download Container... 7. Place the game directories inside the downloaded container - AppData - Documents 8. Click the "three dots" / "cogwheel" button in Xcode again - Replace Container... - select the downloaded container 9. Wait until Xcode finishes copying, progress is visible (although it might be "indefinite") diff --git a/docs/players/Installation_macOS.md b/docs/players/Installation_macOS.md index 23c3def95..d327dc62e 100644 --- a/docs/players/Installation_macOS.md +++ b/docs/players/Installation_macOS.md @@ -5,7 +5,7 @@ - The latest release (recommended): - manually: - via Homebrew: `brew install --cask --no-quarantine vcmi/vcmi/vcmi` -- Daily builds (might be unstable) +- Daily builds (might be unstable) - Intel (x86_64) builds: - Apple Silicon (arm64) builds: @@ -21,5 +21,5 @@ If you bought HoMM3 on [GOG](https://www.gog.com/de/game/heroes_of_might_and_mag ### Step 2.b: Installing by the classic way -1. Find a way to unpack Windows Heroes III or GOG installer. For example, use `vcmibuilder` script inside app bundle or install the game with [CrossOver](https://www.codeweavers.com/crossover) or [Kegworks](https://github.com/Kegworks-App/Kegworks). -2. Place or symlink **Data**, **Maps** and **Mp3** directories from Heroes III to:`~/Library/Application\ Support/vcmi/` +1. Find a way to unpack Windows Heroes III or GOG installer. For example, use `vcmibuilder` script inside app bundle or install the game with [CrossOver](https://www.codeweavers.com/crossover) or [Kegworks](https://github.com/Kegworks-App/Kegworks). +2. Place or symlink **Data**, **Maps** and **Mp3** directories from Heroes III to:`~/Library/Application\ Support/vcmi/` diff --git a/docs/players/Privacy_Policy.md b/docs/players/Privacy_Policy.md index 5bd841505..b35074107 100644 --- a/docs/players/Privacy_Policy.md +++ b/docs/players/Privacy_Policy.md @@ -13,4 +13,4 @@ VCMI team does not collect any data produced by VCMI app. All game files, logs, ## 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. \ No newline at end of file +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. diff --git a/docs/translators/Translations.md b/docs/translators/Translations.md index c226a620a..1f0afdd82 100644 --- a/docs/translators/Translations.md +++ b/docs/translators/Translations.md @@ -23,6 +23,7 @@ This is list of all languages that are currently supported by VCMI. If your lang - Vietnamese ## Progress of the translations + You can see the current progress of the different translations here: [Translation progress](https://github.com/vcmi/vcmi-translation-status) @@ -32,17 +33,18 @@ The page will be automatically updated once a week. VCMI allows translating game data into languages other than English. In order to translate Heroes III in your language easiest approach is to: -- Copy existing translation, such as English translation from here: https://github.com/vcmi-mods/h3-for-vcmi-englisation (delete sound and video folders) -- Copy text-free images from here: https://github.com/vcmi-mods/empty-translation +- Copy existing translation, such as English translation from here: (delete sound and video folders) +- Copy text-free images from here: - Rename mod to indicate your language, preferred form is "(language)-translation" - Update mod.json to match your mod - Translate all texts strings from `game.json`, `campaigns.json` and `maps.json` - Replace images in data and sprites with translated ones (or delete it if you don't want to translate them) -- If unicode characters needed for language: Create a submod with a free font like here: https://github.com/vcmi-mods/vietnamese-translation/tree/vcmi-1.4/vietnamese-translation/mods/VietnameseTrueTypeFonts +- If unicode characters needed for language: Create a submod with a free font like here: If you can't produce some content on your own (like the images or the sounds): + - Create a `README.md` file at the root of the mod -- Write into the file the translations and the detailled location +- Write into the file the translations and the **detailled** location This way, a contributor that is not a native speaker can do it for you in the future. @@ -57,8 +59,10 @@ This will export all strings from game into `Documents/My Games/VCMI/extracted/t To export maps and campaigns, use '/translate maps' command instead. ### Video subtitles + It's possible to add video subtitles. Create a JSON file in `video` folder of translation mod with the name of the video (e.g. `H3Intro.json`): -``` + +```jsonc [ { "timeStart" : 5.640, // start time, seconds @@ -84,6 +88,7 @@ Before you start, make sure that you have copy of VCMI source code. If you are n ### Translation of in-game data In order to translate in-game data you need: + - Add section with your language to `/Mods/VCMI/mod.json`, similar to other languages - Copy English translation file in `/Mods/VCMI/config/vcmi/english.json` and rename it to name of your language. Note that while you can copy any language other than English, other files might not be up to date and may have missing strings. - Translate copied file to your language. @@ -94,7 +99,7 @@ After this, you can set language in Launcher to your language and start game. Al VCMI Launcher and Map Editor use translation system provided by Qt framework so it requires slightly different approach than in-game translations: -- Install Qt Linguist. You can find find standalone version here: https://download.qt.io/linguist_releases/ +- Install Qt Linguist. You can find find standalone version here: - Open `/launcher/translation/` directory, copy `english.ts` file and rename it to your language - Open `/launcher/CMakeLists.txt` file with a text editor. In there you need to find list of existing translation files and add new file to the list. - Launch Qt Linguist, select Open and navigate to your copied file @@ -112,23 +117,27 @@ TODO: how to test translation locally The [AppStream](https://freedesktop.org/software/appstream/docs/chap-Metadata.html) [metainfo file](https://github.com/vcmi/vcmi/blob/develop/launcher/eu.vcmi.VCMI.metainfo.xml) is used for Linux software centers. It can be translated using a text editor or using [jdAppStreamEdit](https://flathub.org/apps/page.codeberg.JakobDev.jdAppStreamEdit): + - Install jdAppStreamEdit - Open `/launcher/eu.vcmi.VCMI.metainfo.xml` - Translate and save the file ##### Desktop file + - Edit `/launcher/vcmilauncher.desktop` and `/launcher/vcmieditor.desktop` - Add `GenericName[xyz]` and `Comment[xyz]` with your language code and translation ##### Translation of Android Launcher + - Copy `/android/vcmi-app/src/main/res/values/strings.xml` to `/android/vcmi-app/src/main/res/values-xyz/strings.xml` (`xyz` is your language code) - Translate this file -See also here: https://developer.android.com/guide/topics/resources/localization +See also here: ### Submitting changes Once you have finished with translation you need to submit these changes to vcmi team using git or Github Desktop + - Commit all your changed files - Push changes to your forked repository - Create pull request in VCMI repository with your changes @@ -152,8 +161,10 @@ If your mod also contains maps or campaigns that you want to translate, then use If you want to update existing translation, you can use '/translate missing' command that will export only strings that were not translated ### Translating mod information + In order to display information in Launcher in language selected by user add following block into your `mod.json`: -``` + +```jsonc "" : { "name" : "", "description" : "", @@ -163,6 +174,7 @@ In order to display information in Launcher in language selected by user add fol ] }, ``` + 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. ### Translating in-game strings @@ -174,7 +186,9 @@ Use any text editor (Notepad++ is recommended for Windows) and translate all str ## Developers documentation ### 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 `lib/Languages.h` entry. This will trigger static_assert's in places that needs an update in code - Add new language into json schemas validation list - settings schema and mod schema @@ -187,7 +201,8 @@ Also, make full search for a name of an existing language to ensure that there a 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 -``` + +```sh lupdate -no-obsolete * -ts translation/*.ts ``` @@ -197,5 +212,6 @@ There *may* be a way to do the same via QtCreator UI or via CMake, if you find o ### 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` From 36fe8462c5d9142ec072998d26d1a3a6623f8b1c Mon Sep 17 00:00:00 2001 From: Ivan Savenko Date: Sun, 1 Dec 2024 11:15:13 +0000 Subject: [PATCH 2/5] Address code review, fix few more issues with formatting --- docs/developers/AI.md | 16 ++++++------ docs/developers/Building_Windows.md | 4 ++- docs/developers/Building_iOS.md | 3 +-- docs/developers/Building_macOS.md | 2 +- .../developers/Development_with_Qt_Creator.md | 2 +- docs/developers/Logging_API.md | 6 ++--- docs/maintainers/Project_Infrastructure.md | 4 +-- docs/maintainers/Release_Process.md | 2 +- docs/modders/Bonus/Bonus_Updaters.md | 26 +++++-------------- docs/modders/Bonus/Bonus_Value_Types.md | 9 +++++-- docs/modders/Campaign_Format.md | 2 +- docs/modders/Map_Editor.md | 2 +- docs/modders/Readme.md | 6 +++-- docs/players/Installation_iOS.md | 4 ++- 14 files changed, 43 insertions(+), 45 deletions(-) diff --git a/docs/developers/AI.md b/docs/developers/AI.md index d5221bfda..6fd7910ab 100644 --- a/docs/developers/AI.md +++ b/docs/developers/AI.md @@ -11,14 +11,14 @@ We have 3 battle AIs so far: * StupidAI - for neutrals, should be simple so that experienced players can abuse it * Empty AI - should do nothing at all. If needed another battle AI can be introduced. -Each battle AI consist of a few classes, but the main class, kind of entry point usually has the same name as the package itself. In BattleAI it is the BattleAI class. It implements some battle specific interface, do not remember. Main method there is activeStack(battle::Unit*stack). It is invoked by the system when it's time to move your stack. The thing you use to interact with the game and receive the gamestate is usually referenced in the code as cb. CPlayerSpecificCallback it should be. It has a lot of methods and can do anything. For instance it has battleGetUnitsIf(), which returns all units on the battlefield matching some lambda condition. -Each side in a battle is represented by an CArmedInstance object. CHeroInstance and CGDwelling, CGMonster and more are subclasses of CArmedInstance. CArmedInstance contains a set of stacks. When the battle starts, these stacks are converted to battle stacks. Usually Battle AIs reference them using the interface battle::Unit*. +Each battle AI consist of a few classes, but the main class, kind of entry point usually has the same name as the package itself. In BattleAI it is the BattleAI class. It implements some battle specific interface, do not remember. Main method there is `activeStack(battle::Unit * stack)`. It is invoked by the system when it's time to move your stack. The thing you use to interact with the game and receive the gamestate is usually referenced in the code as `cb`. `CPlayerSpecificCallback` it should be. It has a lot of methods and can do anything. For instance it has battleGetUnitsIf(), which returns all units on the battlefield matching some lambda condition. +Each side in a battle is represented by an `CArmedInstance` object. `CHeroInstance` and `CGDwelling`, `CGMonster` and more are subclasses of `CArmedInstance`. `CArmedInstance` contains a set of stacks. When the battle starts, these stacks are converted to battle stacks. Usually Battle AIs reference them using the interface `battle::Unit *`. Units have bonuses. Nearly everything aspect of a unit is configured in the form of bonuses. Attack, defense, health, retaliation, shooter or not, initial count of shots and so on. -When you call unit->getAttack() it summarizes all these bonuses and returns the resulting value. +When you call `unit->getAttack()` it summarizes all these bonuses and returns the resulting value. -One important class is HypotheticBattle. It is used to evaluate the effects of an action without changing the actual gamestate. It is a wrapper around CPlayerSpecificCallback or another HypotheticBattle so it can provide you data, Internally it has a set of modified unit states and intercepts some calls to underlying callback and returns these internal states instead. These states in turn are wrappers around original units and contain modified bonuses (CStackWithBonuses). So if you need to emulate an attack you can call hypotheticbattle.getforupdate() and it will return the CStackWithBonuses which you can safely change. +One important class is `HypotheticBattle`. It is used to evaluate the effects of an action without changing the actual gamestate. It is a wrapper around `CPlayerSpecificCallback` or another `HypotheticBattle` so it can provide you data, Internally it has a set of modified unit states and intercepts some calls to underlying callback and returns these internal states instead. These states in turn are wrappers around original units and contain modified bonuses (`CStackWithBonuses`). So if you need to emulate an attack you can call `hypotheticbattle.getforupdate()` and it will return the `CStackWithBonuses` which you can safely change. -## BattleAI +## BattleAI BattleAI's most important classes are the following: @@ -47,9 +47,9 @@ Nullkiller engine - place where actual AI logic is organized. It contains a main * reset AI state, it avoids keeping some memory about the game in general to reduce amount of things serialized into savefile state. The only serialized things are in nullkiller->memory. This helps reducing save incompatibility. It should be mostly enough for AI to analyze data avaialble in CCallback * main loop, loop iteration is called a pass -**update AI state, some state is lazy and updates once per day to avoid performance hit, some state is recalculated each loop iteration. At this stage analysers and pathfidner work -** gathering goals, prioritizing and decomposing them -** execute selected best goals + * update AI state, some state is lazy and updates once per day to avoid performance hit, some state is recalculated each loop iteration. At this stage analysers and pathfidner work + * gathering goals, prioritizing and decomposing them + * execute selected best goals Analyzer - a module gathering data from CCallback *. Its goal to make some statistics and avoid making any significant decissions. diff --git a/docs/developers/Building_Windows.md b/docs/developers/Building_Windows.md index 70cef1fdd..8df20783d 100644 --- a/docs/developers/Building_Windows.md +++ b/docs/developers/Building_Windows.md @@ -68,7 +68,9 @@ Be aware that building Vcpkg might take a lot of time depend on your CPU model a From command line use: -`git clone https://github.com/microsoft/vcpkg.git %VCMI_DIR%/vcpkg` +```sh +git clone https://github.com/microsoft/vcpkg.git %VCMI_DIR%/vcpkg +``` #### Build vcpkg and dependencies diff --git a/docs/developers/Building_iOS.md b/docs/developers/Building_iOS.md index 37591f212..d9e98073b 100644 --- a/docs/developers/Building_iOS.md +++ b/docs/developers/Building_iOS.md @@ -6,8 +6,7 @@ 2. Xcode: 3. CMake 3.21+: `brew install --cask cmake` or get from 4. Optional: - -- CCache to speed up recompilation: `brew install ccache` + - CCache to speed up recompilation: `brew install ccache` ## Obtaining source code diff --git a/docs/developers/Building_macOS.md b/docs/developers/Building_macOS.md index 916813dfe..0f3c40a43 100644 --- a/docs/developers/Building_macOS.md +++ b/docs/developers/Building_macOS.md @@ -91,7 +91,7 @@ Open `VCMI.xcodeproj` from the build directory, select `vcmiclient` scheme and h ## Packaging project into DMG file -After building, run `cpack` from the build directory. If using Xcode generator, also pass `-C` with the same configuration that you used to build the project. +After building, run `cpack` from the build directory. If using Xcode generator, also pass `-C ` with the same configuration that you used to build the project. If you use Conan, it's expected that you use **conan-generated** directory at step 4 of [Conan package manager](Conan.md). diff --git a/docs/developers/Development_with_Qt_Creator.md b/docs/developers/Development_with_Qt_Creator.md index 8f71b4387..66c621781 100644 --- a/docs/developers/Development_with_Qt_Creator.md +++ b/docs/developers/Development_with_Qt_Creator.md @@ -21,4 +21,4 @@ The build dir should be set to something like /trunk/build for the debug build a There is a problem with QtCreator when debugging both vcmiclient and vcmiserver. If you debug the vcmiclient, start a game, attach the vcmiserver process to the gdb debugger(Debug \> Start Debugging \> Attach to Running External Application...) then breakpoints which are set for vcmiserver will be ignored. This looks like a bug, in any case it's not intuitively. Two workarounds are available luckily: 1. Run vcmiclient (no debug mode), then attach server process to the debugger -2. Open two instances of QtCreator and debug vcmiserver and vcmiclient separately(it works!) +2. Open two instances of QtCreator and debug vcmiserver and vcmiclient separately (it works!) diff --git a/docs/developers/Logging_API.md b/docs/developers/Logging_API.md index ec8bc1df0..047882383 100644 --- a/docs/developers/Logging_API.md +++ b/docs/developers/Logging_API.md @@ -68,7 +68,7 @@ The following code shows how the logging system can be configured: If `configureDefault` or `configure` won't be called, then logs aren't written either to the console or to the file. The default logging setups a system like this: -**Console** +#### Console Format: %m Threshold: info @@ -76,11 +76,11 @@ coloredOutputEnabled: true colorMapping: trace -\> gray, debug -\> white, info -\> green, warn -\> yellow, error -\> red -**File** +#### File Format: %d %l %n \[%t\] - %m -**Loggers** +#### Loggers global -\> info diff --git a/docs/maintainers/Project_Infrastructure.md b/docs/maintainers/Project_Infrastructure.md index 3bf2bd562..41032fc54 100644 --- a/docs/maintainers/Project_Infrastructure.md +++ b/docs/maintainers/Project_Infrastructure.md @@ -27,8 +27,8 @@ So far we using following services: - One administrative email used for other services registration. - "noreply" email used for outgoing mail on Wiki and Bug Tracker. - "forum" email used for outgoing mail on Forums. Since we authenticate everyone through forum it's should be separate email. -- Administrator access: Tow, SXX. - - [Google Play Console](https://play.google.com/apps/publish/) account. + - Administrator access: Tow, SXX. +- [Google Play Console](https://play.google.com/apps/publish/) account. - Hold ownership over VCMI Android App. - Owner: SXX - Administrator access: Warmonger, AVS, Ivan. diff --git a/docs/maintainers/Release_Process.md b/docs/maintainers/Release_Process.md index d7b9446b5..32456c1a4 100644 --- a/docs/maintainers/Release_Process.md +++ b/docs/maintainers/Release_Process.md @@ -59,7 +59,7 @@ Should be done 1 day before release. At this point beta branch is in full freeze - Merge `beta` into `master`. This will trigger CI pipeline that will generate release packages - Create draft release page, specify `1.x.y` as tag for `master` after publishing - Check that artifacts for all platforms have been built by CI on `master` branch -- Download and rename all build artifacts to use form "VCMI-1.X.Y-Platform.xxx" +- Download and rename all build artifacts to use form `VCMI-1.X.Y-Platform.xxx` - Attach build artifacts for all platforms to release page - Manually extract Windows installer, remove `$PLUGINSDIR` directory which contains installer files and repackage data as .zip archive - Attach produced zip archive to release page as an alternative Windows installer diff --git a/docs/modders/Bonus/Bonus_Updaters.md b/docs/modders/Bonus/Bonus_Updaters.md index 39831b17e..984ed6385 100644 --- a/docs/modders/Bonus/Bonus_Updaters.md +++ b/docs/modders/Bonus/Bonus_Updaters.md @@ -12,9 +12,7 @@ Check the files in *config/heroes/* for additional usage examples. - Type: Complex - Parameters: valPer20, stepSize=1 -- Effect: Updates val to - -`ceil(valPer20 * floor(heroLevel / stepSize) / 20)` +- Effect: Updates val to `ceil(valPer20 * floor(heroLevel / stepSize) / 20)` Example: The following updater will cause a bonus to grow by 6 for every 40 levels. At first level, rounding will cause the bonus to be 0. @@ -46,13 +44,9 @@ Remarks: ## TIMES_HERO_LEVEL - Type: Simple -- Effect: Updates val to +- Effect: Updates val to `val * heroLevel` -`val * heroLevel` - -Usage: - -`"updater" : "TIMES_HERO_LEVEL"` +Usage: `"updater" : "TIMES_HERO_LEVEL"` Remark: This updater is redundant, in the sense that GROWS_WITH_LEVEL can also express the desired scaling by setting valPer20 to 20\*val. It @@ -61,9 +55,7 @@ has been added for convenience. ## TIMES_STACK_LEVEL - Type: Simple -- Effect: Updates val to - -`val * stackLevel` +- Effect: Updates val to `val * stackLevel` Usage: @@ -74,13 +66,9 @@ Remark: The stack level for war machines is 0. ## ARMY_MOVEMENT - Type: Complex -- Parameters: basePerSpeed, dividePerSpeed, additionalMultiplier, - maxValue -- Effect: Updates val to val+= max((floor(basePerSpeed / - dividePerSpeed)\* additionalMultiplier), maxValue) -- Remark: this updater is designed for MOVEMENT bonus to match H3 army - movement rules (in the example - actual movement updater, which - produces values same as in default movement.txt). +- Parameters: basePerSpeed, dividePerSpeed, additionalMultiplier, maxValue +- Effect: Updates val to `val+= max((floor(basePerSpeed / dividePerSpeed) * additionalMultiplier), maxValue)` +- Remark: this updater is designed for MOVEMENT bonus to match H3 army movement rules (in the example - actual movement updater, which produces values same as in default movement.txt). - Example: ``` jsonc diff --git a/docs/modders/Bonus/Bonus_Value_Types.md b/docs/modders/Bonus/Bonus_Value_Types.md index 28ae187fa..d9950a122 100644 --- a/docs/modders/Bonus/Bonus_Value_Types.md +++ b/docs/modders/Bonus/Bonus_Value_Types.md @@ -3,13 +3,18 @@ Total value of Bonus is calculated using the following: - For each bonus source type we calculate new source value (for all bonus value types except PERCENT_TO_SOURCE and PERCENT_TO_TARGET_TYPE) using the following: -`newVal = (val * (100 + PERCENT_TO_SOURCE) / 100))` + +``` +newVal = (val * (100 + PERCENT_TO_SOURCE) / 100)) +``` - PERCENT_TO_TARGET_TYPE applies as PERCENT_TO_SOURCE to targetSourceType of bonus. - All bonus value types summarized and then used as subject of the following formula: -`clamp(((BASE_NUMBER * (100 + PERCENT_TO_BASE) / 100) + ADDITIVE_VALUE) * (100 + PERCENT_TO_ALL) / 100), INDEPENDENT_MAX, INDEPENDENT_MIN)` +``` +clamp(((BASE_NUMBER * (100 + PERCENT_TO_BASE) / 100) + ADDITIVE_VALUE) * (100 + PERCENT_TO_ALL) / 100), INDEPENDENT_MAX, INDEPENDENT_MIN) +``` Semantics of INDEPENDENT_MAX and INDEPENDENT_MIN are wrapped, and first means than bonus total value will be at least INDEPENDENT_MAX, and second means than bonus value will be at most INDEPENDENT_MIN. diff --git a/docs/modders/Campaign_Format.md b/docs/modders/Campaign_Format.md index 8e071fcd6..4c16bcf13 100644 --- a/docs/modders/Campaign_Format.md +++ b/docs/modders/Campaign_Format.md @@ -3,7 +3,7 @@ ## 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`) +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 `header.json`. See also [Packing campaign](#packing-campaign) diff --git a/docs/modders/Map_Editor.md b/docs/modders/Map_Editor.md index 3d5ca096b..ceb6853a4 100644 --- a/docs/modders/Map_Editor.md +++ b/docs/modders/Map_Editor.md @@ -172,7 +172,7 @@ You can modify general properties of the map ## Player settings -Open **Map** menu on the top and select **Player settings" +Open **Map** menu on the top and select **Player settings** diff --git a/docs/modders/Readme.md b/docs/modders/Readme.md index 13ac5fd98..ab9716c46 100644 --- a/docs/modders/Readme.md +++ b/docs/modders/Readme.md @@ -208,8 +208,10 @@ Link to our mod will looks like that: Date: Sun, 1 Dec 2024 12:18:06 +0000 Subject: [PATCH 3/5] Always use json5 for syntax highlighting. --- docs/developers/Bonus_System.md | 2 +- docs/developers/Conan.md | 2 +- docs/developers/Logging_API.md | 2 +- docs/developers/Lua_Scripting_System.md | 2 +- docs/modders/Animation_Format.md | 6 +- docs/modders/Bonus/Bonus_Limiters.md | 10 +-- docs/modders/Bonus/Bonus_Types.md | 6 +- docs/modders/Bonus/Bonus_Updaters.md | 6 +- docs/modders/Bonus_Format.md | 4 +- docs/modders/Building_Bonuses.md | 28 ++++---- docs/modders/Configurable_Widgets.md | 26 +++---- docs/modders/Difficulty.md | 2 +- .../Entities_Format/Artifact_Format.md | 2 +- .../Entities_Format/Battle_Obstacle_Format.md | 2 +- .../Entities_Format/Battlefield_Format.md | 2 +- docs/modders/Entities_Format/Biome_Format.md | 2 +- .../Entities_Format/Creature_Format.md | 2 +- .../modders/Entities_Format/Faction_Format.md | 6 +- .../Entities_Format/Hero_Class_Format.md | 2 +- .../Entities_Format/Hero_Type_Format.md | 2 +- docs/modders/Entities_Format/River_Format.md | 2 +- docs/modders/Entities_Format/Road_Format.md | 2 +- .../Entities_Format/Secondary_Skill_Format.md | 8 +-- docs/modders/Entities_Format/Spell_Format.md | 18 ++--- .../modders/Entities_Format/Terrain_Format.md | 2 +- .../Entities_Format/Town_Building_Format.md | 20 +++--- docs/modders/Map_Object_Format.md | 6 +- docs/modders/Map_Objects/Boat.md | 2 +- docs/modders/Map_Objects/Creature_Bank.md | 4 +- docs/modders/Map_Objects/Dwelling.md | 2 +- docs/modders/Map_Objects/Flaggable.md | 2 +- docs/modders/Map_Objects/Market.md | 8 +-- docs/modders/Map_Objects/Rewardable.md | 70 +++++++++---------- docs/modders/Mod_File_Format.md | 6 +- docs/modders/Random_Map_Template.md | 4 +- docs/modders/Readme.md | 8 +-- docs/translators/Translations.md | 4 +- 37 files changed, 142 insertions(+), 142 deletions(-) diff --git a/docs/developers/Bonus_System.md b/docs/developers/Bonus_System.md index 6fef4d6e3..191acd4a0 100644 --- a/docs/developers/Bonus_System.md +++ b/docs/developers/Bonus_System.md @@ -55,7 +55,7 @@ Updaters are objects attached to bonuses. They can modify a bonus (typically by The following example shows an artifact providing a bonus based on the level of the hero that wears it: -```jsonc +```json5 "core:greaterGnollsFlail": { "text" : { "description" : "This mighty flail increases the attack of all gnolls under the hero's command by twice the hero's level." }, diff --git a/docs/developers/Conan.md b/docs/developers/Conan.md index fb3ec206e..0e8a1f162 100644 --- a/docs/developers/Conan.md +++ b/docs/developers/Conan.md @@ -172,7 +172,7 @@ cmake --preset ios-conan `CMakeUserPresets.json` file: -```json +```json5 { "version": 3, "cmakeMinimumRequired": { diff --git a/docs/developers/Logging_API.md b/docs/developers/Logging_API.md index 047882383..dd81fdeb2 100644 --- a/docs/developers/Logging_API.md +++ b/docs/developers/Logging_API.md @@ -24,7 +24,7 @@ Some notes: ### Setup settings.json -``` jsonc +```json5 { "logging" : { "console" : { diff --git a/docs/developers/Lua_Scripting_System.md b/docs/developers/Lua_Scripting_System.md index bfd994cb7..8542a3ea3 100644 --- a/docs/developers/Lua_Scripting_System.md +++ b/docs/developers/Lua_Scripting_System.md @@ -2,7 +2,7 @@ ## Configuration -``` jsonc +```json5 { //general purpose script, Lua or ERM, runs on server "myScript": diff --git a/docs/modders/Animation_Format.md b/docs/modders/Animation_Format.md index c9d2a48b6..c33202f7f 100644 --- a/docs/modders/Animation_Format.md +++ b/docs/modders/Animation_Format.md @@ -8,7 +8,7 @@ VCMI allows overriding HoMM3 .def files with .json replacement. Compared to .def ## Format description -``` jsonc +```json5 { // Base path of all images in animation. Optional. // Can be used to avoid using long path to images @@ -64,7 +64,7 @@ This json file will allow replacing .def file for a button with png images. Butt 3. Blocked state. Button is blocked and can not be interacted with. Note that some buttons are never blocked and can be used without this image 4. Highlighted state. This state is used by only some buttons and only in some cases. For example, in main menu buttons will appear highlighted when mouse cursor is on top of the image. Another example is buttons that can be selected, such as settings that can be toggled on or off -```jsonc +```json5 "basepath" : "interface/MyButton", // all images are located in this directory "images" : @@ -81,7 +81,7 @@ This json file will allow replacing .def file for a button with png images. Butt This json file allows defining one animation sequence, for example for adventure map objects or for town buildings. -```jsonc +```json5 "basepath" : "myTown/myBuilding", // all images are located in this directory "sequences" : diff --git a/docs/modders/Bonus/Bonus_Limiters.md b/docs/modders/Bonus/Bonus_Limiters.md index 922f7327a..daf33f3f1 100644 --- a/docs/modders/Bonus/Bonus_Limiters.md +++ b/docs/modders/Bonus/Bonus_Limiters.md @@ -15,7 +15,7 @@ The limiters take no parameters: Example: -``` jsonc +```json5 "limiters" : [ "SHOOTER_ONLY" ] ``` @@ -30,7 +30,7 @@ Parameters: - (optional) bonus sourceType and sourceId in struct - example: (from Adele's bless): -``` jsonc +```json5 "limiters" : [ { "type" : "HAS_ANOTHER_BONUS_LIMITER", @@ -82,14 +82,14 @@ Parameters: Example: -``` jsonc +```json5 "limiters": [ { "type":"CREATURE_TYPE_LIMITER", "parameters": [ "angel", true ] } ], ``` -``` jsonc +```json5 "limiters" : [ { "type" : "CREATURE_TERRAIN_LIMITER", "parameters" : ["sand"] @@ -113,7 +113,7 @@ and operate on the remaining limiters in that list: Example: -``` jsonc +```json5 "limiters" : [ "noneOf", "IS_UNDEAD", diff --git a/docs/modders/Bonus/Bonus_Types.md b/docs/modders/Bonus/Bonus_Types.md index 6f93dc68a..4370de7ba 100644 --- a/docs/modders/Bonus/Bonus_Types.md +++ b/docs/modders/Bonus/Bonus_Types.md @@ -128,7 +128,7 @@ Allows to raise different creatures than Skeletons after battle. - addInfo: Level of Necromancy secondary skill (1 - Basic, 3 - Expert) - Example (from Cloak Of The Undead King): -```jsonc +```json5 { "type" : "IMPROVED_NECROMANCY", "subtype" : "creature.walkingDead", @@ -256,7 +256,7 @@ Gives creature under effect of this spell additional bonus, which is hardcoded a Modifies 'val' parameter of spell effects that give bonuses by specified value. For example, Aenain makes Disrupting Ray decrease target's defense by additional 2 points: -```jsonc +```json5 "disruptingRay" : { "addInfo" : -2, "subtype" : "spell.disruptingRay", @@ -271,7 +271,7 @@ Modifies 'val' parameter of spell effects that give bonuses by specified value. Changes 'val' parameter of spell effects that give bonuses to a specified value. For example, Fortune cast by Melody always modifies luck by +3: -```jsonc +```json5 "fortune" : { "addInfo" : 3, "subtype" : "spell.fortune", diff --git a/docs/modders/Bonus/Bonus_Updaters.md b/docs/modders/Bonus/Bonus_Updaters.md index 984ed6385..a1c993b40 100644 --- a/docs/modders/Bonus/Bonus_Updaters.md +++ b/docs/modders/Bonus/Bonus_Updaters.md @@ -17,7 +17,7 @@ Check the files in *config/heroes/* for additional usage examples. Example: The following updater will cause a bonus to grow by 6 for every 40 levels. At first level, rounding will cause the bonus to be 0. -``` jsonc +```json5 "updater" : { "parameters" : [ 6, 2 ], "type" : "GROWS_WITH_LEVEL" @@ -27,7 +27,7 @@ Example: The following updater will cause a bonus to grow by 6 for every Example: The following updater will cause a bonus to grow by 3 for every 20 levels. At first level, rounding will cause the bonus to be 1. -``` jsonc +```json5 "updater" : { "parameters" : [ 3 ], "type" : "GROWS_WITH_LEVEL" @@ -71,7 +71,7 @@ Remark: The stack level for war machines is 0. - Remark: this updater is designed for MOVEMENT bonus to match H3 army movement rules (in the example - actual movement updater, which produces values same as in default movement.txt). - Example: -``` jsonc +```json5 "updater" : { "parameters" : [ 20, 3, 10, 700 ], "type" : "ARMY_MOVEMENT" diff --git a/docs/modders/Bonus_Format.md b/docs/modders/Bonus_Format.md index 59a9f4d8f..88c901f38 100644 --- a/docs/modders/Bonus_Format.md +++ b/docs/modders/Bonus_Format.md @@ -4,7 +4,7 @@ All parameters but type are optional. -``` jsonc +```json5 { // Type of the bonus. See Bonus Types for full list "type": "BONUS_TYPE", @@ -81,7 +81,7 @@ See [Game Identifiers](Game_Identifiers.md) for full list of available identifie ### Example -``` jsonc +```json5 "bonus" : { "type" : "HATE", diff --git a/docs/modders/Building_Bonuses.md b/docs/modders/Building_Bonuses.md index d77669f50..f5219e581 100644 --- a/docs/modders/Building_Bonuses.md +++ b/docs/modders/Building_Bonuses.md @@ -22,7 +22,7 @@ Includes: Function of all of these objects can be enabled by this: -``` jsonc +```json5 "function" : "castleGates" ``` @@ -58,31 +58,31 @@ CBuilding class. #### unlock guild level -``` jsonc +```json5 "guildLevels" : 1 ``` #### unlock hero recruitment -``` jsonc +```json5 "allowsHeroPurchase" : true ``` #### unlock ship purchase -``` jsonc +```json5 "allowsShipPurchase" : true ``` #### unlock building purchase -``` jsonc +```json5 "allowsBuildingPurchase" : true ``` #### unlocks creatures -``` jsonc +```json5 "dwelling" : { "level" : 1, "creature" : "archer" } ``` @@ -92,31 +92,31 @@ Turn into town bonus? What about creature-specific bonuses from hordes? #### gives resources -``` jsonc +```json5 "provides" : { "gold" : 500 } ``` #### gives guild spells -``` jsonc +```json5 "guildSpells" : [5, 0, 0, 0, 0] ``` #### gives thieves guild -``` jsonc +```json5 "thievesGuildLevels" : 1 ``` #### gives fortifications -``` jsonc +```json5 "fortificationLevels" : 1 ``` #### gives war machine -``` jsonc +```json5 "warMachine" : "ballista" ``` @@ -134,7 +134,7 @@ Includes: - bonus to scouting range - bonus to player -``` jsonc +```json5 "bonuses" : { "moraleToDefenders" : @@ -162,12 +162,12 @@ Possible issue - with removing of fixed ID's buildings in different town may no longer share same ID. However Capitol must be unique across all town. Should be fixed somehow. -``` jsonc +```json5 "onePerPlayer" : true ``` #### chance to be built on start -``` jsonc +```json5 "prebuiltChance" : 75 ``` diff --git a/docs/modders/Configurable_Widgets.md b/docs/modders/Configurable_Widgets.md index ec2eccd11..541e03e76 100644 --- a/docs/modders/Configurable_Widgets.md +++ b/docs/modders/Configurable_Widgets.md @@ -33,7 +33,7 @@ extendedLobby/ File `mod.json` is generic and could look like this: -```json +```json5 { "name" : "Configurable UI tutorial mod", "description" : "See tutorial here https://github.com/vcmi/vcmi/wiki/Configurable-UI-widgets", @@ -67,7 +67,7 @@ Open `optionsTab.json` and scroll it until you see comment `timer`. Three elemen Let's find first element, which is label -```json +```json5 { "items" [ @@ -89,7 +89,7 @@ Let's find first element, which is label And modify it a bit -```json +```json5 { "name": "labelTimer", //add name, only for convenience "type": "label", @@ -103,7 +103,7 @@ And modify it a bit But we also need proper background image for this label. Add image widget BEFORE labelTimer widget: -```json +```json5 { "type": "picture", "image": "RmgTTBk", @@ -127,7 +127,7 @@ Copy image `DrDoCoBk.bmp` to `content/sprites/`. Button objects use animated ima For normal, pressed, blocked and highlighted. Our combo box inherits this behavior, so let's convert image to animation. In order to do it, we need to create file `DrDoCoBk.json` in same folder `content/sprites/` with following content: -```json +```json5 { "sequences" : [ @@ -146,7 +146,7 @@ Thus we created file with animation, containing single frame which can be used f Let's add one more element after `//timer` comment: -```json +```json5 ... //timer { @@ -163,7 +163,7 @@ Let's add one more element after `//timer` comment: We also want to have label on the top of this combo box showing which element is selected. You need to add `items` array, where additional elements can be specified, label in our case: -```json +```json5 ... //timer { @@ -195,7 +195,7 @@ First of all, add images to `content/sprites/` folder: `List2Bk.bmp` for drop-do Now specify items inside `dropDown` field -```json +```json5 "dropDown": { "items": @@ -279,7 +279,7 @@ Let's hide elements, related to classic timer when chess timer is selected and s To do that, find `"variables"` part inside `optionsTab.json` and add there `"timers"` array, containing 2 elements: -```json +```json5 "variables": { "timers": @@ -310,7 +310,7 @@ Now we show and hide elements, but visually you still can some "artifacts": It's because options tab background image we use has those elements drawn. Let's hide them with overlay image `timchebk.bmp`. It should be drawn before all other timer elements: -```json +```json5 ... // timer { @@ -338,7 +338,7 @@ We should add text input fields, to specify different timers. We will use backgr There are 4 different timers: base, turn, battle and creature. Read about them here: We can add editors for them into items list, their format will be following: -```json +```json5 { "name": "chessFieldBase", "type": "textInput", @@ -440,7 +440,7 @@ One of predefined values: Configurable object has following structure: -```json +```json5 { "items": [], "variables": {}, //optional @@ -837,7 +837,7 @@ std::shared_ptr MyYesNoDialog::buildMyItem(const JsonNode & After that, if your JSON file has items with type "MyItem", the new Item element will be constructed. -```json +```json5 { "items": [ diff --git a/docs/modders/Difficulty.md b/docs/modders/Difficulty.md index 4d53552ff..1a70a10a2 100644 --- a/docs/modders/Difficulty.md +++ b/docs/modders/Difficulty.md @@ -7,7 +7,7 @@ Difficulty configuration is located in [config/difficulty.json](../config/diffic ## Format summary -``` jsonc +```json5 { "human": //parameters impacting human players only { diff --git a/docs/modders/Entities_Format/Artifact_Format.md b/docs/modders/Entities_Format/Artifact_Format.md index a36499926..e308e64e7 100644 --- a/docs/modders/Entities_Format/Artifact_Format.md +++ b/docs/modders/Entities_Format/Artifact_Format.md @@ -12,7 +12,7 @@ In order to make functional artifact you also need: ## Format -``` jsonc +```json5 { // Type of this artifact - creature, hero or commander "type": ["HERO", "CREATURE", "COMMANDER"] diff --git a/docs/modders/Entities_Format/Battle_Obstacle_Format.md b/docs/modders/Entities_Format/Battle_Obstacle_Format.md index f81390564..fb5319db0 100644 --- a/docs/modders/Entities_Format/Battle_Obstacle_Format.md +++ b/docs/modders/Entities_Format/Battle_Obstacle_Format.md @@ -1,6 +1,6 @@ # Battle Obstacle Format -```jsonc +```json5 // List of terrains on which this obstacle can be used "allowedTerrains" : [] diff --git a/docs/modders/Entities_Format/Battlefield_Format.md b/docs/modders/Entities_Format/Battlefield_Format.md index 2ab1da12b..7435400ad 100644 --- a/docs/modders/Entities_Format/Battlefield_Format.md +++ b/docs/modders/Entities_Format/Battlefield_Format.md @@ -1,6 +1,6 @@ # Battlefield Format -```jsonc +```json5 // Human-readable name of the battlefield "name" : "", diff --git a/docs/modders/Entities_Format/Biome_Format.md b/docs/modders/Entities_Format/Biome_Format.md index 6338fc7a0..d750a9dcd 100644 --- a/docs/modders/Entities_Format/Biome_Format.md +++ b/docs/modders/Entities_Format/Biome_Format.md @@ -8,7 +8,7 @@ The purpose is to create visually attractive and consistent maps, which will als If not enough biomes are defined for [terrain type](Terrain_Format.md), map generator will fall back to using all available templates that match this terrain, which was original behavior before 1.5.0. -``` json +```json5 "obstacleSetId" : { "biome" : { "terrain" : "grass", // Id or vector of Ids this obstacle set can spawn at diff --git a/docs/modders/Entities_Format/Creature_Format.md b/docs/modders/Entities_Format/Creature_Format.md index bad20d450..4dc65f157 100644 --- a/docs/modders/Entities_Format/Creature_Format.md +++ b/docs/modders/Entities_Format/Creature_Format.md @@ -23,7 +23,7 @@ In order to make functional creature you also need: ## Format -``` jsonc +```json5 // camelCase unique creature identifier "creatureName" : { diff --git a/docs/modders/Entities_Format/Faction_Format.md b/docs/modders/Entities_Format/Faction_Format.md index b51c8720b..7cb1e95e0 100644 --- a/docs/modders/Entities_Format/Faction_Format.md +++ b/docs/modders/Entities_Format/Faction_Format.md @@ -47,7 +47,7 @@ Each town requires a set of buildings (Around 30-45 buildings) ## Faction node (root entry for town configuration) -```jsonc +```json5 // Unique faction identifier. "myFaction" : { @@ -108,7 +108,7 @@ Each town requires a set of buildings (Around 30-45 buildings) ## Town node -```jsonc +```json5 { // Field that describes behavior of map object part of town. Town-specific part of object format "mapObject" : @@ -256,7 +256,7 @@ Each town requires a set of buildings (Around 30-45 buildings) ## Siege node -```jsonc +```json5 // Describes town siege screen // Comments in the end of each graphic position indicate specify required suffix for image // Note: one not included image is battlefield background with suffix "BACK" diff --git a/docs/modders/Entities_Format/Hero_Class_Format.md b/docs/modders/Entities_Format/Hero_Class_Format.md index 5049cd2c1..78e743ac1 100644 --- a/docs/modders/Entities_Format/Hero_Class_Format.md +++ b/docs/modders/Entities_Format/Hero_Class_Format.md @@ -9,7 +9,7 @@ In order to make functional hero class you also need: ## Format -``` jsonc +```json5 // Unique identifier of hero class, camelCase "myClassName" : { diff --git a/docs/modders/Entities_Format/Hero_Type_Format.md b/docs/modders/Entities_Format/Hero_Type_Format.md index d3cb85762..e0755d23f 100644 --- a/docs/modders/Entities_Format/Hero_Type_Format.md +++ b/docs/modders/Entities_Format/Hero_Type_Format.md @@ -9,7 +9,7 @@ In order to make functional hero you also need: ## Format -``` jsonc +```json5 "myHeroName" : { // Identifier of class this hero belongs to. Such as knight or battleMage diff --git a/docs/modders/Entities_Format/River_Format.md b/docs/modders/Entities_Format/River_Format.md index 4cd67a3f7..64e1e085f 100644 --- a/docs/modders/Entities_Format/River_Format.md +++ b/docs/modders/Entities_Format/River_Format.md @@ -2,7 +2,7 @@ ## Format -```jsonc +```json5 "newRiver" : { // Two-letters unique identifier for this river. Used in map format diff --git a/docs/modders/Entities_Format/Road_Format.md b/docs/modders/Entities_Format/Road_Format.md index 69b57e75b..59d384881 100644 --- a/docs/modders/Entities_Format/Road_Format.md +++ b/docs/modders/Entities_Format/Road_Format.md @@ -2,7 +2,7 @@ ## Format -```jsonc +```json5 "newRoad" : { // Two-letters unique identifier for this road. Used in map format diff --git a/docs/modders/Entities_Format/Secondary_Skill_Format.md b/docs/modders/Entities_Format/Secondary_Skill_Format.md index bd7304b41..09cbaf79f 100644 --- a/docs/modders/Entities_Format/Secondary_Skill_Format.md +++ b/docs/modders/Entities_Format/Secondary_Skill_Format.md @@ -2,7 +2,7 @@ ## Main format -```jsonc +```json5 { // Skill be only be available on maps with water "onlyOnWaterMap" : false, @@ -11,7 +11,7 @@ } ``` -```jsonc +```json5 { "skillName": { @@ -55,7 +55,7 @@ level fields become optional if they equal "base" configuration. ## Skill level format -```jsonc +```json5 { // Localizable description // Use {xxx} for formatting @@ -87,7 +87,7 @@ level fields become optional if they equal "base" configuration. The following modifies the tactics skill to grant an additional speed boost at advanced and expert levels. -```jsonc +```json5 "core:tactics" : { "base" : { "effects" : { diff --git a/docs/modders/Entities_Format/Spell_Format.md b/docs/modders/Entities_Format/Spell_Format.md index 46d3a204c..67a3a73ed 100644 --- a/docs/modders/Entities_Format/Spell_Format.md +++ b/docs/modders/Entities_Format/Spell_Format.md @@ -2,7 +2,7 @@ ## Main format -``` jsonc +```json5 { "spellName": { @@ -156,7 +156,7 @@ TODO -``` jsonc +```json5 { "projectile": [ {"minimumAngle": 0 ,"defName":"C20SPX4"}, @@ -179,7 +179,7 @@ Json object with data common for all levels can be put here. These configuration This will make spell affect single target on all levels except expert, where it is massive spell. -``` jsonc +```json5 "base":{ "range": 0 }, @@ -192,7 +192,7 @@ This will make spell affect single target on all levels except expert, where it TODO -``` jsonc +```json5 { //Mandatory, localizable description. Use {xxx} for formatting @@ -262,7 +262,7 @@ Configurable spells ignore *offensive* flag, *effects* and *cumulativeEffects*. TODO -``` jsonc +```json5 "mod:effectId":{ @@ -283,7 +283,7 @@ TODO TODO -``` jsonc +```json5 "mod:effectId":{ @@ -304,7 +304,7 @@ TODO Configurable version of Clone spell. -``` jsonc +```json5 "mod:effectId":{ @@ -320,7 +320,7 @@ TODO If effect is automatic, spell behave like offensive spell (uses power, levelPower etc) -``` jsonc +```json5 "mod:effectId":{ @@ -368,7 +368,7 @@ TODO If effect is automatic, spell behave like \[de\]buff spell (effect and cumulativeEffects ignored) -``` jsonc +```json5 "mod:effectId":{ diff --git a/docs/modders/Entities_Format/Terrain_Format.md b/docs/modders/Entities_Format/Terrain_Format.md index db7b0174f..1562d78c8 100644 --- a/docs/modders/Entities_Format/Terrain_Format.md +++ b/docs/modders/Entities_Format/Terrain_Format.md @@ -2,7 +2,7 @@ ## Format -```jsonc +```json5 "newTerrain" : { // Two-letters unique identifier for this terrain. Used in map format diff --git a/docs/modders/Entities_Format/Town_Building_Format.md b/docs/modders/Entities_Format/Town_Building_Format.md index 9bbef202e..e0586c6e8 100644 --- a/docs/modders/Entities_Format/Town_Building_Format.md +++ b/docs/modders/Entities_Format/Town_Building_Format.md @@ -17,7 +17,7 @@ These are just a couple of examples of what can be done in VCMI. See vcmi config ##### Order of Fire from Inferno -```jsonc +```json5 "special4": { "requires" : [ "mageGuild1" ], "name" : "Order of Fire", @@ -41,7 +41,7 @@ These are just a couple of examples of what can be done in VCMI. See vcmi config ##### Mana Vortex from Dungeon -```jsonc +```json5 "special2": { "requires" : [ "mageGuild1" ], "name" : "Mana Vortex", @@ -70,7 +70,7 @@ These are just a couple of examples of what can be done in VCMI. See vcmi config #### Resource Silo with custom production -```jsonc +```json5 "resourceSilo": { "name" : "Wood Resource Silo", "description" : "Produces 2 wood every day", @@ -86,7 +86,7 @@ These are just a couple of examples of what can be done in VCMI. See vcmi config #### Brotherhood of Sword - bonuses in siege -```jsonc +```json5 "special3": { // replaces +1 Morale bonus from Tavern "upgradeReplacesBonuses" : true, @@ -103,7 +103,7 @@ These are just a couple of examples of what can be done in VCMI. See vcmi config #### Lighthouse - bonus to all heroes under player control -```jsonc +```json5 "special1": { "bonuses": [ { @@ -119,7 +119,7 @@ These are just a couple of examples of what can be done in VCMI. See vcmi config ## Town Building node -```jsonc +```json5 { // Numeric identifier of this building "id" : 0, @@ -218,7 +218,7 @@ These are just a couple of examples of what can be done in VCMI. See vcmi config Building requirements can be described using logical expressions: -```jsonc +```json5 "requires" : [ "allOf", // Normal H3 "build all" mode @@ -265,7 +265,7 @@ In addition to above, it is possible to use same format as [Rewardable](../Map_O ### Town Structure node -```jsonc +```json5 { // Main animation file for this building "animation" : "", @@ -299,12 +299,12 @@ Market buildings require list of available [modes](../Map_Objects/Market.md) ##### Marketplace -```jsonc +```json5 "marketplace": { "marketModes" : ["resource-resource", "resource-player"] }, ``` ##### Artifact merchant -```jsonc +```json5 "special1": { "type" : "artifactMerchant", "requires" : [ "marketplace" ], "marketModes" : ["resource-artifact", "artifact-resource"] }, ``` diff --git a/docs/modders/Map_Object_Format.md b/docs/modders/Map_Object_Format.md index a42641fe6..93a8e3fbe 100644 --- a/docs/modders/Map_Object_Format.md +++ b/docs/modders/Map_Object_Format.md @@ -16,7 +16,7 @@ Full object consists from 3 parts: ## Object group format -``` jsonc +```json5 { "myCoolObjectGroup": @@ -99,7 +99,7 @@ These are internal types that are generally not available for modding and are ha ## Object type format -``` jsonc +```json5 { "myCoolObject": { @@ -153,7 +153,7 @@ These are internal types that are generally not available for modding and are ha ## Object template format -``` jsonc +```json5 { "myCoolObjectTemplate" : { diff --git a/docs/modders/Map_Objects/Boat.md b/docs/modders/Map_Objects/Boat.md index f88a980e4..cb827bad1 100644 --- a/docs/modders/Map_Objects/Boat.md +++ b/docs/modders/Map_Objects/Boat.md @@ -1,6 +1,6 @@ # Boat -``` jsonc +```json5 { // Layer on which this boat moves. Possible values: // "land" - same rules as movement of hero on land diff --git a/docs/modders/Map_Objects/Creature_Bank.md b/docs/modders/Map_Objects/Creature_Bank.md index 0fcbe3e4f..e75613266 100644 --- a/docs/modders/Map_Objects/Creature_Bank.md +++ b/docs/modders/Map_Objects/Creature_Bank.md @@ -10,7 +10,7 @@ Deprecated in 1.6. Please use [Rewardable Objects](Rewardable.md) instead. See C This example defines a rewardable object with functionality similar of H3 creature bank. See [Rewardable Objects](Rewardable.md) for detailed documentation of these properties. -```jsonc +```json5 { "name" : "Cyclops Stockpile", @@ -115,7 +115,7 @@ This is a list of changes that needs to be done to bank config to migrate it to ### Old format (1.5 or earlier) -``` jsonc +```json5 { /// If true, battle setup will be like normal - Attacking player on the left, enemy on the right "regularUnitPlacement" : true, diff --git a/docs/modders/Map_Objects/Dwelling.md b/docs/modders/Map_Objects/Dwelling.md index 04470a5b7..562f8f239 100644 --- a/docs/modders/Map_Objects/Dwelling.md +++ b/docs/modders/Map_Objects/Dwelling.md @@ -1,6 +1,6 @@ # Dwelling -``` jsonc +```json5 { /// List of creatures in this bank. Each list represents one "level" of bank /// Creatures on the same level will have shared growth and available number (similar to towns) diff --git a/docs/modders/Map_Objects/Flaggable.md b/docs/modders/Map_Objects/Flaggable.md index 2880a4d9e..69063baaf 100644 --- a/docs/modders/Map_Objects/Flaggable.md +++ b/docs/modders/Map_Objects/Flaggable.md @@ -9,7 +9,7 @@ Currently, it is possible to make flaggable objects that provide player with: ## Format description -```jsonc +```json5 { "baseObjectName" : { "name" : "Object name", diff --git a/docs/modders/Map_Objects/Market.md b/docs/modders/Map_Objects/Market.md index 2e748e5a1..90ef19b68 100644 --- a/docs/modders/Map_Objects/Market.md +++ b/docs/modders/Map_Objects/Market.md @@ -51,19 +51,19 @@ Following options are supported: Trading post allows to exchange resources and send resources to another player, so it shall be configured this way: -```json +```json5 "modes" : ["resource-resource", "resource-player"] ``` ### Black market -```json +```json5 "modes" : ["resource-artifact"] ``` ### Freelance guild -```json +```json5 "modes" : ["creature-resource"] ``` @@ -73,7 +73,7 @@ Altar of sacrifice allows exchange creatures for experience for evil factions an So both modes shall be available in the market. Game logic prohibits using modes unavailable for faction -```json +```json5 "modes" : ["creature-experience", "artifact-experience"] ``` diff --git a/docs/modders/Map_Objects/Rewardable.md b/docs/modders/Map_Objects/Rewardable.md index e26256567..60c3ebcb2 100644 --- a/docs/modders/Map_Objects/Rewardable.md +++ b/docs/modders/Map_Objects/Rewardable.md @@ -4,7 +4,7 @@ Rewardable object is defined similarly to other objects, with key difference being `handler`. This field must be set to `"handler" : "configurable"` in order for vcmi to use this mode. -```jsonc +```json5 { "baseObjectName" : { "name" : "Object name", @@ -37,7 +37,7 @@ Rewardable object is defined similarly to other objects, with key difference bei ## Configurable object definition -```jsonc +```json5 // List of potential rewards "rewards" : [ { @@ -177,7 +177,7 @@ Variables are randomized only once, so you can use them multiple times for examp Example of creation of a variable named "gainedSkill" of type "secondarySkill": -```json +```json5 "variables" : { "secondarySkill" : { "gainedSkill" : { @@ -200,7 +200,7 @@ Possible variable types: To reference variable in limiter prepend variable name with '@' symbol: -```json +```json5 "secondary" : { "@gainedSkill" : 1 }, @@ -214,7 +214,7 @@ This property describes how object state should be reset. Objects without this f - 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" -```jsonc +```json5 "resetParameters" : { "period" : 7, "visitors" : true, @@ -233,7 +233,7 @@ Note that object that uses appearChance MUST have continuous range for every val - `"min" : 66, "max" : 100` In other words, min chance of second reward must be equal to max chance of previous reward -```jsonc +```json5 "appearChance": { // (Advanced) rewards with different dice number will get different dice number @@ -253,7 +253,7 @@ In other words, min chance of second reward must be equal to max chance of previ Unless stated othervice, all numbers in this section can be replaced with random values, e.g. -```jsonc +```json5 "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 ``` @@ -265,13 +265,13 @@ Keep in mind, that all randomization is performed on map load and on object rese - 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 -```jsonc +```json5 "dayOfWeek" : 0 ``` - Can only be used as limiter. To pass, number of days since game started must be at equal or greater than this value -```jsonc +```json5 "daysPassed" : 8 ``` @@ -281,7 +281,7 @@ Keep in mind, that all randomization is performed on map load and on object rese - 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 -```jsonc +```json5 "resources": { "crystal" : 6, "gold" : -1000, @@ -290,7 +290,7 @@ Keep in mind, that all randomization is performed on map load and on object rese - Alternative format that allows random selection of a resource type -```jsonc +```json5 "resources": [ { "anyOf" : [ "wood", "ore" ], @@ -308,7 +308,7 @@ Keep in mind, that all randomization is performed on map load and on object rese - Can be used as limiter - Can be used as reward to grant experience to hero -```jsonc +```json5 "heroExperience" : 1000, ``` @@ -317,7 +317,7 @@ Keep in mind, that all randomization is performed on map load and on object rese - Can be used as limiter. Hero requires to have at least specified level - 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) -```jsonc +```json5 "heroLevel" : 1, ``` @@ -327,13 +327,13 @@ Keep in mind, that all randomization is performed on map load and on object rese - 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 -```jsonc +```json5 "manaPoints": -10, ``` - 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. -```jsonc +```json5 "manaOverflowFactor" : 50, ``` @@ -342,7 +342,7 @@ Keep in mind, that all randomization is performed on map load and on object rese - 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) -```jsonc +```json5 "manaPercentage": 200, ``` @@ -351,7 +351,7 @@ Keep in mind, that all randomization is performed on map load and on object rese - 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. -```jsonc +```json5 "movePoints": 200, ``` @@ -360,7 +360,7 @@ Keep in mind, that all randomization is performed on map load and on object rese - 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 -```jsonc +```json5 "movePercentage": 50, ``` @@ -372,7 +372,7 @@ Keep in mind, that all randomization is performed on map load and on object rese - Each primary skill can be explicitly specified or randomly selected - Possible values: `"attack", "defence", "spellpower", "knowledge"` -```jsonc +```json5 "primary": [ { // Specific primary skill @@ -406,7 +406,7 @@ Keep in mind, that all randomization is performed on map load and on object rese - Possible values: 1 (basic), 2 (advanced), 3 (expert) - Each secondary skill can be explicitly specified or randomly selected -```jsonc +```json5 "secondary": [ { // Specific skill @@ -435,7 +435,7 @@ Keep in mind, that all randomization is performed on map load and on object rese - Can be used as limiter. Hero must have free skill slot to pass limiter -```json +```json5 "canLearnSkills" : true ``` @@ -446,7 +446,7 @@ Keep in mind, that all randomization is performed on map load and on object rese - Note that unlike most values, parameter of bonuses can NOT be randomized - Description can be string or number of corresponding string from `arraytxt.txt` -```json +```json5 "bonuses" : [ { "type" : "MORALE", @@ -463,7 +463,7 @@ Keep in mind, that all randomization is performed on map load and on object rese - Can be used as reward, to give new artifact to a hero - Artifacts added as reward will be used for text substitution. First `%s` in text string will be replaced with name of an artifact -```jsonc +```json5 "artifacts": [ "ribCage" ], @@ -473,7 +473,7 @@ Keep in mind, that all randomization is performed on map load and on object rese - For artifact class possible values are "TREASURE", "MINOR", "MAJOR", "RELIC" - Artifact value range can be specified with min value and max value -```jsonc +```json5 "artifacts": [ { "class" : "TREASURE", @@ -489,7 +489,7 @@ Keep in mind, that all randomization is performed on map load and on object rese - Can be used as reward, to give new spell to a hero - Spells added as reward will be used for text substitution. First `%s` in text string will be replaced with spell name -```jsonc +```json5 "spells": [ "magicArrow" ], @@ -498,7 +498,7 @@ Keep in mind, that all randomization is performed on map load and on object rese - Alternative format, random spell selection - Spell can be selected from specifically selected school -```jsonc +```json5 "spells": [ { "level" : 1, @@ -515,7 +515,7 @@ Keep in mind, that all randomization is performed on map load and on object rese - - he does not have a spellbook - - he does not have sufficient Wisdom level for this spell -```json +```json5 "canLearnSpells" : [ "magicArrow" ], @@ -528,7 +528,7 @@ Keep in mind, that all randomization is performed on map load and on object rese - If hero does not have enough free slots, game will show selection dialog to pick troops to keep - It is possible to specify probability to receive upgraded creature -```jsonc +```json5 "creatures" : [ { "type" : "archer", @@ -547,7 +547,7 @@ Keep in mind, that all randomization is performed on map load and on object rese - It is possible to add up to 7 slots of creatures - Guards of the same creature type will never merge or rearrange their stacks -```jsonc +```json5 "guards" : [ { "type" : "archer", "amount" : 20 }, { "type" : "archer", "amount" : 20, "upgradeChance" : 30 }, @@ -561,7 +561,7 @@ Keep in mind, that all randomization is performed on map load and on object rese - 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 - This parameter will not change creatures given by `creatures` parameter on the same visit -```jsonc +```json5 "changeCreatures" : { "cavalier" : "champion" } @@ -573,7 +573,7 @@ Keep in mind, that all randomization is performed on map load and on object rese - 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) -```json +```json5 "spellCast" : { "spell" : "townPortal", "schoolLevel": 3 @@ -588,7 +588,7 @@ Keep in mind, that all randomization is performed on map load and on object rese - It is possible to specify which terrain classes should be affected. Tile will be affected if sum of values its classes is positive. For example, `"water" : 1` will affect all water tiles, while `"surface" : 1, "subterra" : -1` will include terrains that have "surface" flag but do not have "subterra" flag - If 'hide' is set to true, then instead of revealing terrain, game will hide affected tiles for all other players -```json +```json5 "revealTiles" : { "radius" : 20, "surface" : 1, @@ -605,7 +605,7 @@ Keep in mind, that all randomization is performed on map load and on object rese - Can NOT be used as reward - Only players with specific color can pass the limiter -```jsonc +```json5 "colors" : [ "red", "blue", "tan", "green", "orange", "purple", "teal", "pink" ] ``` @@ -615,7 +615,7 @@ Keep in mind, that all randomization is performed on map load and on object rese - Can NOT be used as reward - Only specific heroes can pass the limiter -```jsonc +```json5 "heroes" : [ "orrin" ] ``` @@ -625,6 +625,6 @@ Keep in mind, that all randomization is performed on map load and on object rese - Can NOT be used as reward - Only heroes belonging to specific classes can pass the limiter -```jsonc +```json5 "heroClasses" : [ "battlemage" ] ``` diff --git a/docs/modders/Mod_File_Format.md b/docs/modders/Mod_File_Format.md index 49ed6866e..514b1a231 100644 --- a/docs/modders/Mod_File_Format.md +++ b/docs/modders/Mod_File_Format.md @@ -2,7 +2,7 @@ ## Fields with description of mod -``` jsonc +```json5 { // Name of your mod. While it does not have hard length limit // it should not be longer than ~30 symbols to fit into allowed space @@ -91,7 +91,7 @@ These are fields that are present only in local mod.json file -``` jsonc +```json5 { // Following section describes configuration files with content added by mod @@ -210,7 +210,7 @@ See [Translations](Translations.md) for more information These are fields that are present only in remote repository and are generally not used in mod.json -```jsonc +```json5 { // URL to mod.json that describes this mod "mod" : "https://raw.githubusercontent.com/vcmi-mods/vcmi-extras/vcmi-1.4/mod.json", diff --git a/docs/modders/Random_Map_Template.md b/docs/modders/Random_Map_Template.md index 7c02667ec..1d7a0f5d9 100644 --- a/docs/modders/Random_Map_Template.md +++ b/docs/modders/Random_Map_Template.md @@ -2,7 +2,7 @@ ## Template format -``` jsonc +```json5 /// Unique template name "Triangle" : { @@ -56,7 +56,7 @@ ## Zone format -``` jsonc +```json5 { // Type of this zone. Possible values are: // "playerStart", "cpuStart", "treasure", "junction" diff --git a/docs/modders/Readme.md b/docs/modders/Readme.md index ab9716c46..6bc87cd6e 100644 --- a/docs/modders/Readme.md +++ b/docs/modders/Readme.md @@ -30,7 +30,7 @@ All VCMI configuration files use [JSON format](http://en.wikipedia.org/wiki/Json Mod.json is main file in your mod and must be present in any mod. This file contains basic description of your mod, dependencies or conflicting mods (if present), list of new content and so on. Minimalistic version of this file: -``` jsonc +```json5 { "name" : "My test mod", "description" : "My test mod that add a lot of useless stuff into the game", @@ -102,7 +102,7 @@ VCMI uses strings to reference objects. Examples: Alternatively to creating new objects, you can edit existing objects. Normally, when creating new objects you specify object name as: -``` jsonc +```json5 "newCreature" : { // creature parameters } @@ -110,7 +110,7 @@ Alternatively to creating new objects, you can edit existing objects. Normally, In order to access and modify existing object you need to specify mod that you wish to edit: -``` jsonc +```json5 /// "core" specifier refers to objects that exist in H3 "core:archer" : { /// This will set health of Archer to 10 @@ -159,7 +159,7 @@ These files can be replaced by another def file but in some cases original forma In VCMI these animation files can also be replaced by json description of their content. See [Animation Format](Animation_Format.md) for full description of this format. Example: replacing single icon -``` jsonc +```json5 { // List of replaced images "images" : diff --git a/docs/translators/Translations.md b/docs/translators/Translations.md index 1f0afdd82..3bcc6397c 100644 --- a/docs/translators/Translations.md +++ b/docs/translators/Translations.md @@ -62,7 +62,7 @@ To export maps and campaigns, use '/translate maps' command instead. It's possible to add video subtitles. Create a JSON file in `video` folder of translation mod with the name of the video (e.g. `H3Intro.json`): -```jsonc +```json5 [ { "timeStart" : 5.640, // start time, seconds @@ -164,7 +164,7 @@ If you want to update existing translation, you can use '/translate missing' com In order to display information in Launcher in language selected by user add following block into your `mod.json`: -```jsonc +```json5 "" : { "name" : "", "description" : "", From 5e57582c47e8fd62723a5d33249f0608c0b67221 Mon Sep 17 00:00:00 2001 From: Ivan Savenko Date: Sun, 1 Dec 2024 19:06:04 +0000 Subject: [PATCH 4/5] Replace js -> json5 code blocks --- CI/example.markdownlint-cli2.jsonc | 2 +- docs/modders/Campaign_Format.md | 16 ++++++++-------- docs/modders/Difficulty.md | 2 +- docs/modders/Map_Objects/Market.md | 6 +++--- 4 files changed, 13 insertions(+), 13 deletions(-) diff --git a/CI/example.markdownlint-cli2.jsonc b/CI/example.markdownlint-cli2.jsonc index 9b009818f..13e8155eb 100644 --- a/CI/example.markdownlint-cli2.jsonc +++ b/CI/example.markdownlint-cli2.jsonc @@ -186,7 +186,7 @@ // FIXME: enable and consider fixing //{ //// List of languages - // "allowed_languages": [ "cpp", "json", "jsonc", "json5", "sh" ], + // "allowed_languages": [ "cpp", "json5", "sh" ], //// Require language only // "language_only": true //}, diff --git a/docs/modders/Campaign_Format.md b/docs/modders/Campaign_Format.md index 4c16bcf13..1f8b811a4 100644 --- a/docs/modders/Campaign_Format.md +++ b/docs/modders/Campaign_Format.md @@ -9,7 +9,7 @@ To start making campaign, create file named `header.json`. See also [Packing cam Basic structure of this file is here, each section is described in details below -```js +```json5 { "version" : 1, @@ -34,7 +34,7 @@ Basic structure of this file is here, each section is described in details below In header are parameters describing campaign properties -```js +```json5 ... "regions": {...}, "name": "Campaign name", @@ -63,7 +63,7 @@ In header are parameters describing campaign properties Scenario description looks like follow: -```js +```json5 { "map": "maps/SomeMap", "preconditions": [], @@ -100,7 +100,7 @@ Scenario description looks like follow: Prolog and epilog properties are optional -```js +```json5 { "video": "NEUTRALA.smk", //video to show "music": "musicFile.ogg", //music to play, should be located in music directory @@ -119,7 +119,7 @@ If `startOptions` is `none`, `bonuses` field will be ignored If `startOptions` is `bonus`, bonus format may vary depending on its type. -```js +```json5 { "what": "", @@ -162,7 +162,7 @@ If `startOptions` is `bonus`, bonus format may vary depending on its type. If `startOptions` is `crossover`, heroes from specific scenario will be moved to this scenario. Bonus format is following -```js +```json5 { "playerColor": 0, "scenario": 0 @@ -176,7 +176,7 @@ If `startOptions` is `crossover`, heroes from specific scenario will be moved to If `startOptions` is `hero`, hero can be chosen as a starting bonus. Bonus format is following -```js +```json5 { "playerColor": 0, "hero": "random" @@ -190,7 +190,7 @@ If `startOptions` is `hero`, hero can be chosen as a starting bonus. Bonus forma Predefined campaign regions are located in file `campaign_regions.json` -```js +```json5 { "background": "ownRegionBackground.png", "suffix": ["Enabled", "Selected", "Conquered"], diff --git a/docs/modders/Difficulty.md b/docs/modders/Difficulty.md index 1a70a10a2..52e265807 100644 --- a/docs/modders/Difficulty.md +++ b/docs/modders/Difficulty.md @@ -50,7 +50,7 @@ For both types of bonuses, `source` should be specified as `OTHER`. ## Example -```js +```json5 { //will give 150% extra health to all players' creatures if specified in "battleBonuses" array "type" : "STACK_HEALTH", "val" : 150, diff --git a/docs/modders/Map_Objects/Market.md b/docs/modders/Map_Objects/Market.md index 90ef19b68..18c07d6f6 100644 --- a/docs/modders/Map_Objects/Market.md +++ b/docs/modders/Map_Objects/Market.md @@ -7,7 +7,7 @@ Markets can be added as any other object with special handler called "market". Here is schema describing such object -```js +```json5 "seafaringAcademy" : //object name { "handler" : "market", //market handler @@ -85,14 +85,14 @@ See [Secondary skills](Rewardable.md#secondary-skills) description for more deta ### Example for University of magic (e.g conflux building) -```js +```json5 "modes" : ["resource-skill"], "offer" : ["airMagic", "waterMagic", "earthMagic", "fireMagic"] ``` ### Example for regular University -```js +```json5 "modes" : ["resource-skill"], "offer" : [ //4 random skills except necromancy { "noneOf" : ["necromancy"] }, From 54e2dc4bf857dfc718c7c0077ed74d653aec98ce Mon Sep 17 00:00:00 2001 From: Ivan Savenko Date: Sun, 1 Dec 2024 19:12:07 +0000 Subject: [PATCH 5/5] Fix json in examples --- docs/modders/Animation_Format.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/modders/Animation_Format.md b/docs/modders/Animation_Format.md index c33202f7f..2abb72805 100644 --- a/docs/modders/Animation_Format.md +++ b/docs/modders/Animation_Format.md @@ -65,6 +65,7 @@ This json file will allow replacing .def file for a button with png images. Butt 4. Highlighted state. This state is used by only some buttons and only in some cases. For example, in main menu buttons will appear highlighted when mouse cursor is on top of the image. Another example is buttons that can be selected, such as settings that can be toggled on or off ```json5 +{ "basepath" : "interface/MyButton", // all images are located in this directory "images" : @@ -82,6 +83,7 @@ This json file will allow replacing .def file for a button with png images. Butt This json file allows defining one animation sequence, for example for adventure map objects or for town buildings. ```json5 +{ "basepath" : "myTown/myBuilding", // all images are located in this directory "sequences" :