Difference between revisions of "Modding guidelines"

From VCMI Project Wiki
Jump to: navigation, search
(Split page into players/modders sections. TODO: better style for tables.)
(VCMI Repository)
 
(18 intermediate revisions by 6 users not shown)
Line 1: Line 1:
= For players =
+
If you just want to play see [[mod list]].
== Installing mod ==
 
To install mod unpack archive in <data directory>/Mods. This should result in such directory structure:
 
<pre>
 
<data directory>/Mods/<name of mod>/mod.json
 
</pre>
 
 
 
There is no need to activate newly installed mods.
 
== List of currently available mods ==
 
{|
 
! Name !! Download URL !! Author
 
|-
 
! Cove town || [https://dl.dropbox.com/s/98pm5ibk9ni7gei/cove.rar?dl=1 URL] || HotA Crew
 
|-
 
! New artifacts pack || [https://dl.dropbox.com/s/r7uwzfinydw8q0d/witchking-arts.rar?dl=1 URL ] || Witchking
 
|-
 
! High resolution main menu || [https://dl.dropbox.com/u/22372764/vcmi/mods/new-menu.zip URL ] || Dru
 
|}
 
== Managing mods ==
 
To activate or deactivate mod open file '''<data dir>/config/modSettings.json'''. Set mod state to "false" for disabling it or to "true" for enabling.
 
  
Note that removing mod from this list will not deactivate or remove mod from the game - any mods not present in this file will be considered by game as newly installed and will be (re-)inserted in this file on startup.
 
 
To remove mod delete its folder (<data dir>/Mods/modname).
 
== Notes ==
 
* Data directory location is system-specific:
 
** Windows : Same as your Heroes III directory
 
** Unix-like : Inside home directory: '''~/.vcmi'''
 
 
= For modders =
 
 
== Creating mod ==
 
== Creating mod ==
To make your own mod you need to create subdirectory in "Mods" with name that will be used as identifier for your mod.
+
To make your own mod you need to create subdirectory in '''<data dir>/Mods/''' with name that will be used as identifier for your mod.
  
Main mod file called '''mod.json''' and should be placed into main folder of your mod, e.g. '''Mods/myMod/mod.json'''
+
Main mod is file called '''mod.json''' and should be placed into main folder of your mod, e.g. '''Mods/myMod/mod.json'''
  
All content of your mod should go into "Override" directory, e.g. '''Mods/myMod/Override/'''
+
All content of your mod should go into '''Content''' directory, e.g. '''Mods/myMod/Content/'''. In future it will be possible to replace this directory with single .zip archive.
 
 
* '''TODO''': separate '''content''' and '''override''' folders
 
* '''TODO''': support for .zip archives
 
  
 
Example of how directory structure of your mod may look like:
 
Example of how directory structure of your mod may look like:
 
 
<pre>
 
<pre>
 
Mods/
 
Mods/
 
     myMod/
 
     myMod/
 
           mod.json
 
           mod.json
           Override/
+
           Content/
 
                     data/    - unorganized files, mostly bitmap images (.bmp, .png, .pcx)
 
                     data/    - unorganized files, mostly bitmap images (.bmp, .png, .pcx)
 
                     config/  - json configuration files
 
                     config/  - json configuration files
Line 54: Line 22:
 
                     video/  - video files, .bik or .smk
 
                     video/  - video files, .bik or .smk
 
</pre>
 
</pre>
 
+
== Updating mod to next version of VCMI ==
 +
See [[Modding changelog]]
 
== Creating mod file ==
 
== Creating mod file ==
 
All VCMI configuration files use [http://en.wikipedia.org/wiki/Json JSON format] so you may want to familiarize yourself with it first.
 
All VCMI configuration files use [http://en.wikipedia.org/wiki/Json JSON format] so you may want to familiarize yourself with it first.
  
Example of how mod.json should look like:
+
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.
  
<syntaxhighlight lang="javascript">  
+
Minimalistic version of this file:
 +
<syntaxhighlight lang="javascript">
 
{
 
{
    // 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
 
 
     "name" : "My test mod",
 
     "name" : "My test mod",
 +
    "description" : "My test mod that add a lot of useless stuff into the game"
 +
}
 +
</syntaxhighlight>
 +
See [[Mod file Format]] for its full description.
 +
 +
== Overriding graphical files from Heroes III ==
 +
 +
Any graphical replacer mods fall under this category. In VCMI directory '''<mod name>/Content''' acts as mod-specific game root directory.
 +
So for example file '''<mod name>/Content/Data/AISHIELD.PNG''' will replace file with same name from '''H3Bitmap.lod''' game archive.
 +
 +
Any other files can be replaced in exactly same way.
 +
 +
Note that replacing files from archives requires placing them into specific location:
 +
<pre>
 +
H3Bitmap.lod -> Data
 +
H3Sprite.lod -> Sprites
 +
Heroes3.snd  -> Sounds
 +
Video.vid    -> Video
 +
</pre>
 +
This includes archives added by expansions (e.g. '''H3ab_bmp.lod''' uses same rules as '''H3Bitmap.lod''')
 +
 +
=== Replacing .def animation files ===
 +
Heroes III uses custom format for storing animation: def files. These files are used to store all in-game animations as well as for some GUI elements like buttons and for icon sets.
 +
 +
These files can be replaced by another def file but in some cases original format can't be used. This includes but not limited to:
 +
* 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]] for full description of this format.
 +
 +
Example: replacing single icon
 +
<syntaxhighlight lang="javascript">
 +
{
 +
// List of replaced images
 +
"images" :
 +
[   // Index of replaced frame
 +
{ "frame" : 0, "file" : "HPS000KN.bmp"}
 +
              //name of file that will be used as replacement
 +
]
 +
}
 +
</syntaxhighlight>
 +
 +
 +
"High resolution main menu" mod can be used as example of file replacer mod.
 +
== Packaging mod into archive ==
 +
For distribution it is recommended to package mod into .zip archives. To create .zip archive you need to have file archiver like [http://www.7-zip.org 7zip]
 +
 +
File structure of packaged mod should look like this
 +
<pre>
 +
<modname>.zip/  <- Zip archive with high compression ratio
 +
  modname/      <- Archive contains main mod directory
 +
    mod.json    <- main mod file
 +
    Content.zip/ <- Uncompressed archive with all mod data
 +
      Data/
 +
      ...      <- Identical to Content directory
 +
      Sprites/
 +
</pre>
 +
 +
You can create such structure using following instructions:
 +
* Go to Mods/<modname>/Content directory
 +
* Select all files in this directory and create archive with following parameters:
 +
** Archive name: Content.zip
 +
** Format: ZIP
 +
** Compression level: None/Store only
 +
* Move created archive into Mods/<modname> directory and remove no longer needed Content directory.
 +
* Go to Mods/ directory
 +
* Create archive from your mod with following parameters:
 +
** Archive name: <modname>.zip
 +
** Format: ZIP
 +
** Compression level: Maximum
  
    // More lengthy description of mod. No hard limit
+
Resulting archive is recommended form for distributing mods for VCMI
    // TODO: show it in some kind of mod manager
+
== Releasing mods ==
    "description" : "My test mod that add a lot of useless stuff into the game",
+
Right now there are 3 ways to bring your mod to players:
 +
* Manual download
 +
* VCMI Repository
 +
* Private repository
 +
=== Manual download ===
 +
You can upload mod into some online file hosting and add link with description of your mod into [[mod list]].
 +
 
 +
Note: Avoid using services that require registration or remove files after certain period of time (examples are Wikisend and 4shared). Instead you may use any of the services listed below:
 +
<!-- Note to editors: do not add any more entries in this list - please, keep it short, no more than 5 links -->
 +
* [http://mediafire.com MediaFire]
 +
* [https://dropbox.com Dropbox]
 +
* [https://drive.google.com Google Drive]
 +
* Any other service that does not has aforementioned problems
 +
 
 +
=== VCMI Repository ===
 +
Another option is to add mod into VCMI repository. This will allow players to install mods directly from VCMI Launcher without visiting any 3rd-party sites.
  
    // List of mods that are required to run this one
+
Check for more details in [[Mods repository]].
    "depends" :
 
    [
 
        "baseMod"
 
    ],
 
 
    // List of mods that can't be enabled in the same time as this one
 
    "conflicts" :
 
    [
 
        "badMod"
 
    ],
 
  
    // Following section describes configuration files with content added by mod
+
=== Private repository ===
    // It can be split into several files in any way you want but recommended organization is
+
It it also possible to create your own repository. To do this you need to own your own server capable of file hosting or use file service that provide direct download links (e.g. Dropbox with enabled public directory).
    // to keep one file per object (creature/hero/etc) and, if applicable, add separate file
 
    // with translatable strings for each type of content
 
    // See "additional links" at the bottom of page for descriptions of each of these formats
 
  
    // list of factions/towns configuration files
+
Providing own repository allows you to deliver any new mods or updates almost instantly and on the same level of integration with VCMI as mods from VCMI repository.
    "factions" :
 
    [
 
        "config/myMod/faction.json"
 
    ]
 
  
    // List of hero classes configuration files
+
To create empty repository you need to:
    "heroClasses" :
+
* Create directory that will contain repository
    [
+
* Create file named "repository.json" in it
        "config/myMod/heroClasses.json"
 
    ],
 
  
    // List of heroes configuration files
+
To add mods into such repository you need to:
    "heroes" :
+
* Copy packaged archive <modname>.zip into repository directory
    [
+
* Copy mod information from mod.json into repository.json
        "config/myMod/heroes.json"
+
* Add two extra fields about this mod into repository.json:
    ],
+
** "download" - public link that can be used to download the mod, including http:// prefix
 +
** "size" - size of mod, in kilobytes. VCMI will use this number to inform player on size of the mod.
  
     // list of creature configuration files
+
Example on how mod entry should look in repository.json
     "creatures" :
+
<syntaxhighlight lang="javascript">
 +
{
 +
  ...
 +
  "exampleMod" // ID of the mod, lowercase version of mod directory name
 +
  {
 +
    "name" : "My test mod",
 +
    "description" : "My test mod that add a lot of useless stuff into the game",
 +
    "author" : "Anonymous",
 +
     "contact" : "http://example.com",
 +
    "modType" : "Graphical",
 +
     "depends" :
 
     [
 
     [
         "config/myMod/creatures.json"
+
         "baseMod"
 
     ],
 
     ],
  
    // List of artifacts configuration files
+
     "download" : "http://example.com/vcmi/repository/exampleMod.zip",
     "artifacts" :
+
     "size" : 1234 //size, in kilobytes
    [
 
        "config/myMod/artifacts.json"
 
     ],
 
  
     // Optional, description on how files are organized in your mod
+
     //Note that entries that refer to files, e.g. "heroes". "creatures", "artifacts" and such
    // In most cases you do not need to used this field
+
    //are not necessary in repository.json and therefore can be removed
    // Needed mostly to port any existing mods to vcmi (e.g. WoG distributed with Era)
+
  },
    // Example below is default value, which is "Content" directory that acts as H3 root directory
+
  ...
    "filesystem":
 
    {
 
        "":
 
            [
 
                {"type" : "dir", "path" : "/Content"}
 
            ]
 
    }
 
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
== Additional links ==
+
When repository is ready you can share public link to repository.json with players. New repositories can added to vcmi launcher from settings tab.
* [[Animation Format|Def file replacement format]]
+
==== Dropbox: enabling public directory ====
* [[Creature Format]]
+
New accounts create on Dropbox no longer have Public directory enabled by default. You can enable it using this [https://www.dropbox.com/enable_public_folder link]
* [[Town Format]]
+
 
* [[Hero Classes Format]]
+
This will give you directory named "Public" as well as option "get public link" for all files inside this directory.
* [[Hero Format]]
+
 
* [[Artifact Format]]
+
{{Modding}}
* [[Object Format]]
 
* [[Spell Format]] (WiP)
 

Latest revision as of 06:45, 21 February 2018

If you just want to play see mod list.

Creating mod

To make your own mod you need to create subdirectory in /Mods/ with name that will be used as identifier for your mod.

Main mod is file called mod.json and should be placed into main folder of your mod, e.g. Mods/myMod/mod.json

All content of your mod should go into Content directory, e.g. Mods/myMod/Content/. In future it will be possible to replace this directory with single .zip archive.

Example of how directory structure of your mod may look like:

Mods/
     myMod/
           mod.json
           Content/
                    data/    - unorganized files, mostly bitmap images (.bmp, .png, .pcx)
                    config/  - json configuration files
                    maps/    - h3m maps added or modified by mod
                    music/   - music files. Mp3 is fully supported, ogg may be added if needed
                    sounds/  - sound files, in wav format.
                    sprites/ - animation, image sets (H3 .def files or VCMI .json files)
                    video/   - video files, .bik or .smk

Updating mod to next version of VCMI

See Modding changelog

Creating mod file

All VCMI configuration files use JSON format so you may want to familiarize yourself with it first.

Mod.json is main file in your mod and must be present in any mod. This file contains basic description of your mod, dependencies or conflicting mods (if present), list of new content and so on.

Minimalistic version of this file:

{
    "name" : "My test mod",
    "description" : "My test mod that add a lot of useless stuff into the game"
}

See Mod file Format for its full description.

Overriding graphical files from Heroes III

Any graphical replacer mods fall under this category. In VCMI directory <mod name>/Content acts as mod-specific game root directory. So for example file <mod name>/Content/Data/AISHIELD.PNG will replace file with same name from H3Bitmap.lod game archive.

Any other files can be replaced in exactly same way.

Note that replacing files from archives requires placing them into specific location:

H3Bitmap.lod -> Data
H3Sprite.lod -> Sprites
Heroes3.snd  -> Sounds
Video.vid    -> Video

This includes archives added by expansions (e.g. H3ab_bmp.lod uses same rules as H3Bitmap.lod)

Replacing .def animation files

Heroes III uses custom format for storing animation: def files. These files are used to store all in-game animations as well as for some GUI elements like buttons and for icon sets.

These files can be replaced by another def file but in some cases original format can't be used. This includes but not limited to:

  • 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 for full description of this format.

Example: replacing single icon

{
	// List of replaced images
	"images" : 
	[	  // Index of replaced frame
		{ "frame" : 0, "file" : "HPS000KN.bmp"} 
		               //name of file that will be used as replacement
	]
}


"High resolution main menu" mod can be used as example of file replacer mod.

Packaging mod into archive

For distribution it is recommended to package mod into .zip archives. To create .zip archive you need to have file archiver like 7zip

File structure of packaged mod should look like this

<modname>.zip/   <- Zip archive with high compression ratio
  modname/       <- Archive contains main mod directory 
    mod.json     <- main mod file
    Content.zip/ <- Uncompressed archive with all mod data
      Data/ 
       ...       <- Identical to Content directory
      Sprites/

You can create such structure using following instructions:

  • Go to Mods/<modname>/Content directory
  • Select all files in this directory and create archive with following parameters:
    • Archive name: Content.zip
    • Format: ZIP
    • Compression level: None/Store only
  • Move created archive into Mods/<modname> directory and remove no longer needed Content directory.
  • Go to Mods/ directory
  • Create archive from your mod with following parameters:
    • Archive name: <modname>.zip
    • Format: ZIP
    • Compression level: Maximum

Resulting archive is recommended form for distributing mods for VCMI

Releasing mods

Right now there are 3 ways to bring your mod to players:

  • Manual download
  • VCMI Repository
  • Private repository

Manual download

You can upload mod into some online file hosting and add link with description of your mod into mod list.

Note: Avoid using services that require registration or remove files after certain period of time (examples are Wikisend and 4shared). Instead you may use any of the services listed below:

VCMI Repository

Another option is to add mod into VCMI repository. This will allow players to install mods directly from VCMI Launcher without visiting any 3rd-party sites.

Check for more details in Mods repository.

Private repository

It it also possible to create your own repository. To do this you need to own your own server capable of file hosting or use file service that provide direct download links (e.g. Dropbox with enabled public directory).

Providing own repository allows you to deliver any new mods or updates almost instantly and on the same level of integration with VCMI as mods from VCMI repository.

To create empty repository you need to:

  • Create directory that will contain repository
  • Create file named "repository.json" in it

To add mods into such repository you need to:

  • Copy packaged archive <modname>.zip into repository directory
  • Copy mod information from mod.json into repository.json
  • Add two extra fields about this mod into repository.json:
    • "download" - public link that can be used to download the mod, including http:// prefix
    • "size" - size of mod, in kilobytes. VCMI will use this number to inform player on size of the mod.

Example on how mod entry should look in repository.json

{
  ...
  "exampleMod" // ID of the mod, lowercase version of mod directory name
  {
    "name" : "My test mod",
    "description" : "My test mod that add a lot of useless stuff into the game",
    "author" : "Anonymous",
    "contact" : "http://example.com",
    "modType" : "Graphical",
    "depends" :
    [
        "baseMod"
    ],

    "download" : "http://example.com/vcmi/repository/exampleMod.zip",
    "size" : 1234 //size, in kilobytes

    //Note that entries that refer to files, e.g. "heroes". "creatures", "artifacts" and such
    //are not necessary in repository.json and therefore can be removed
  },
  ...
}

When repository is ready you can share public link to repository.json with players. New repositories can added to vcmi launcher from settings tab.

Dropbox: enabling public directory

New accounts create on Dropbox no longer have Public directory enabled by default. You can enable it using this link

This will give you directory named "Public" as well as option "get public link" for all files inside this directory.


Modding related articles

Main articles
Modding changelog Modding guidelines Mod Handler


Formats
Mod file Format
Town Format Creature Format Hero Classes Format
Artifact Format Animation Format Hero Format
Bonus Format Object Format Spell Format


Work-in-progress formats
Building bonuses Map format
Bonus Type Format Random map template


Outdated pages
Mod system proposal