Modding:Mod Packaging: Difference between revisions

From Vintage Story Wiki
(Added info about loading bare DLLs)
(Marked this version for translation)
(25 intermediate revisions by 10 users not shown)
Line 1: Line 1:
== Zip Files ==
<languages/><translate>
<!--T:1-->
{{GameVersion|1.15}}


To make your mod easy to install and use, it should be packed into a [https://en.wikipedia.org/wiki/Zip_(file_format) zip file]. Any assets (images, .json files, etc) go in a "assets" directory in the root of the zip, any C# DLLs (and optionally, PDB files) go directly into the zip file root as well.
<!--T:2-->
If your mod changes only visuals, sounds, and other "theming" assets, refer also to the [[Modding:Theme_Pack|Theme Pack]] page.


Please note that if you have a code mod that has no assets (AKA, your mod is a single C# DLL), it is possible to ship the bare DLL without packing it into a zip. This is not really a good idea though, as when distributed this way it is hard to include a PDB file and downloading DLLs directly in Windows can lead to issues with you mod loading due to security policies applied to files downloaded from the internet.
== Zip Files == <!--T:3-->


== Info file ==
<!--T:4-->
To make your mod easy to install and use, it should be packed into a [https://en.wikipedia.org/wiki/Zip_(file_format) zip file]. Any assets (images, .json files, etc) go in a "assets" directory in the root of the zip, any source files into the "src" folder and any DLLs (and optionally, PDB files) go directly into the zip file root folder.


<!--T:5-->
Please note that if you have a code mod that has no assets (AKA, your mod is a single C# DLL), it is possible to ship the bare DLL without packing it into a zip. This is not really a good idea though, as when distributed this way it is hard to include a PDB file and downloading DLLs directly in Windows can lead to issues with your mod failing to load due to security policies applied to files downloaded from the internet.
<!--T:6-->
<table id="treeviewtable" class="table table-bordered tt-table" style='table-layout: fixed'>
  <tr style='background-color: rgba(180, 160, 128, 0.15);'>
    <th width='500px' align='left'>Zip File Structure</th>
  </tr>
  <tr>
    <td><div class="tt" data-tt-id="root">.zip</div></td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="assets" data-tt-parent="root" data-hide="false">assets</div></td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="your-domain" data-tt-parent="assets" data-hide="false">domain</div></td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="stuff" data-tt-parent="your-domain">asset files ([[The Asset System|tree overview]])</div></td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="modinfo.json" data-tt-parent="root">modinfo.json</div></td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="modicon.png" data-tt-parent="root">modicon.png</div></td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="dll" data-tt-parent="root">compiled sources files (*.dll and *.pdb)</div></td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="src" data-tt-parent="root" data-hide="false">src</div></td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="src-dll" data-tt-parent="src">source code files - folders allowed (*.cs)</div></td>
  </tr>
</table>
== Info file == <!--T:7-->
<!--T:8-->
Every zip-file mod requires a <code>modinfo.json</code> inside the root directory of the archive. Otherwise the entire mod will be ignored. This info file specifies what kind of mod it is, its name, author, etc.
Every zip-file mod requires a <code>modinfo.json</code> inside the root directory of the archive. Otherwise the entire mod will be ignored. This info file specifies what kind of mod it is, its name, author, etc.


<!--T:9-->
An example of a theme pack info file (<code>modinfo.json</code>):
An example of a theme pack info file (<code>modinfo.json</code>):
<syntaxhighlight lang=json>
<syntaxhighlight lang=json>
{
{
   "type": "content",
   "type": "content",
  "modid": "creativemdexamplemod",
   "name": "My Example Content Mod",
   "name": "My Example Content Mod",
   "description" : "This is an example mod, which does nothing",
   "description" : "This is an example mod, which does nothing",
   "author": "CreativeMD",
   "authors": ["CreativeMD"],
   "version": "1.0",
   "version": "1.0",
   "gameversions": [ "1.5.0.3+" ],
   "dependencies": {
"game": "",
"survival": ""
  },
   "website": "http://example.com"
   "website": "http://example.com"
}
}
</syntaxhighlight>
</syntaxhighlight>


<!--T:10-->
----
----


<!--T:11-->
<syntaxhighlight lang=json>
<syntaxhighlight lang=json>
   "type": "content",
   "type": "content",
</syntaxhighlight>
</syntaxhighlight>


<!--T:12-->
Besides <code>"type": "content"</code>, there is also <code>"type": "theme"</code> and <code>"type": "code"</code>.
Besides <code>"type": "content"</code>, there is also <code>"type": "theme"</code> and <code>"type": "code"</code>.


* <code>"type": "content"</code>: Defines this mod as being a '''ContentMod'''. Therefore it cannot any scripts or mod classes (it might contain some, but they will be ignored).
<!--T:13-->
* <code>"type": "theme"</code>: Defines this mod as being a '''ThemePack'''. Therefore it cannot override gameplay affecting assets categories (such as blocktypes, itemtypes and so on) and no scripts or mod classes will be loaded.
* <code>"type": "content"</code>: Defines this mod as being a '''Content Mod'''. Content Mods cannot contain any C# code (if it does they will be ignored).
* <code>"type": "code"</code>: Defines this mod as being a '''CodeMod'''. This is the same as a ContentMod, except it can also load C# code to do things that are not possible with JSON.
* <code>"type": "theme"</code>: Defines this mod as being a '''Theme Pack'''. Theme Packs cannot override gameplay affecting assets categories (such as blocktypes, itemtypes and so on) and no C# code will be loaded.
* <code>"type": "code"</code>: Defines this mod as being a '''Code Mod'''. Code Mods are the same as a Content Mods, except they can also load C# code to do things that are not possible with JSON.


<!--T:14-->
<syntaxhighlight lang=json>
<syntaxhighlight lang=json>
   "gameversions": [ "1.5.0.3+" ],
   "dependencies": {
    "game": "1.5.3"
  },
</syntaxhighlight>
</syntaxhighlight>


Means it requires at least VintageStory v1.5.0.3 or a newer version.
<!--T:15-->
Means it requires at least VintageStory v1.5.3 or a newer version. For more info see [[Modinfo]].


== Icon ==
== Icon == <!--T:16-->


<!--T:17-->
'''Note:''' Mod icons supported starting from 1.16.
The file <code>modicon.png</code> (if it exists) will be used and shown in the mod manager menu.
The file <code>modicon.png</code> (if it exists) will be used and shown in the mod manager menu.


<!--T:18-->
[[File:Example Mod.png]]
[[File:Example Mod.png]]


== Distribution ==
== Distribution and Installation == <!--T:19-->
 
<!--T:20-->
To install a mod simply place the zip file in the <code>Mods</code> directory in your [[Vintagestory folder|Vintagestory directory]].
 
<!--T:21-->
You can upload your mod to the [https://mods.vintagestory.at/ Vintage Story Mod Database] so people can find it.
 


Feel free to share your creation in our [https://www.vintagestory.at/forums/forum/17-modifications/ forums]. We would love to see what you come up with.
<!--T:22-->
{{Navbox/modding|Vintage Story}}
</translate>

Revision as of 20:49, 20 February 2022

Other languages:

This page was last verified for Vintage Story version 1.15.


If your mod changes only visuals, sounds, and other "theming" assets, refer also to the Theme Pack page.

Zip Files

To make your mod easy to install and use, it should be packed into a zip file. Any assets (images, .json files, etc) go in a "assets" directory in the root of the zip, any source files into the "src" folder and any DLLs (and optionally, PDB files) go directly into the zip file root folder.

Please note that if you have a code mod that has no assets (AKA, your mod is a single C# DLL), it is possible to ship the bare DLL without packing it into a zip. This is not really a good idea though, as when distributed this way it is hard to include a PDB file and downloading DLLs directly in Windows can lead to issues with your mod failing to load due to security policies applied to files downloaded from the internet.

Zip File Structure
.zip
assets
domain
asset files (tree overview)
modinfo.json
modicon.png
compiled sources files (*.dll and *.pdb)
src
source code files - folders allowed (*.cs)

Info file

Every zip-file mod requires a modinfo.json inside the root directory of the archive. Otherwise the entire mod will be ignored. This info file specifies what kind of mod it is, its name, author, etc.

An example of a theme pack info file (modinfo.json):

{
  "type": "content",
  "modid": "creativemdexamplemod",
  "name": "My Example Content Mod",
  "description" : "This is an example mod, which does nothing",
  "authors": ["CreativeMD"],
  "version": "1.0",
  "dependencies": { 
	"game": "",
	"survival": ""
  },
  "website": "http://example.com"
}

  "type": "content",

Besides "type": "content", there is also "type": "theme" and "type": "code".

  • "type": "content": Defines this mod as being a Content Mod. Content Mods cannot contain any C# code (if it does they will be ignored).
  • "type": "theme": Defines this mod as being a Theme Pack. Theme Packs cannot override gameplay affecting assets categories (such as blocktypes, itemtypes and so on) and no C# code will be loaded.
  • "type": "code": Defines this mod as being a Code Mod. Code Mods are the same as a Content Mods, except they can also load C# code to do things that are not possible with JSON.
  "dependencies": {
    "game": "1.5.3"
  },

Means it requires at least VintageStory v1.5.3 or a newer version. For more info see Modinfo.

Icon

Note: Mod icons supported starting from 1.16.

The file modicon.png (if it exists) will be used and shown in the mod manager menu.

Example Mod.png

Distribution and Installation

To install a mod simply place the zip file in the Mods directory in your Vintagestory directory.

You can upload your mod to the Vintage Story Mod Database so people can find it.


Icon Sign.png

Wondering where some links have gone?
The modding navbox is going through some changes! Check out Navigation Box Updates for more info and help finding specific pages.