Difference between revisions of "Modding guidelines"

From VCMI Project Wiki
Jump to: navigation, search
(→‎Creating mod)
(→‎For modders: Some examples and fixes)
Line 30: Line 30:
 
= For modders =
 
= For modders =
 
== Creating mod ==
 
== Creating 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.
+
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''': 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 57: Line 54:
 
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.
  
−
Mod.json is main file in your mod and must be present in any mod. See [[Mod file Format]] for its full description.
+
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:
 
Minimalistic version of this file:
−
<syntaxhighlight lang="javascript">  
+
<syntaxhighlight lang="javascript">
 
{
 
{
 
     "name" : "My test mod",
 
     "name" : "My test mod",
Line 66: Line 63:
 
}
 
}
 
</syntaxhighlight>
 
</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.
 +
== Mod with new content: Artifact ==
 +
TODO
 +
== Mod with new content: Creature ==
 +
TODO
 +
== Custom filesystem format. Porting Era Mod to VCMI ==
 +
TODO
 
== Additional links ==
 
== Additional links ==
 
* [[Mod file Format]]
 
* [[Mod file Format]]

Revision as of 23:17, 23 January 2013

For players

Installing mod

To install mod unpack archive in /Mods. This should result in such directory structure: 

<data directory>/Mods/<name of mod>/mod.json

There is no need to activate newly installed mods.

List of currently available mods

Name Download URL Author
Cove town URL HotA Crew
New artifacts pack URL Witchking
High resolution main menu 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

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 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

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.

Mod with new content: Artifact

TODO

Mod with new content: Creature

TODO

Custom filesystem format. Porting Era Mod to VCMI

TODO

Additional links

Retrieved from "https://wiki.vcmi.eu/index.php?title=Modding_guidelines&oldid=914"