Modding:Developing a Content Mod: Difference between revisions

<languages/><translate>

{{GameVersion|1.19.4}}

__TOC__

Developing a content mod can be simple, but certain files and folders need to be setup correctly. For more information on what can be achieved with a content mod, see [[Modding:Content Mods|Content Mods]].

When creating a content mod, you will likely be using a lot of JSON files. Although JSON is a human-readable format, it can still be beneficial to equip yourself with an '''Integrated Development Environment''' (IDE). Simply put, for the purpose of modifying JSON files, an IDE works as a fancy text editor that helps with formatting.

It is recommended to select from one of the IDEs below.

{| class="wikitable sortable"

|}

As stated above, content mods require a certain file and folder structure to function.

If you want to get into modding and do not wish to manually setup your folders, there are two options. The ''template'' file contains a modinfo, modicon, and folder structure for your mod. The ''example'' file is identical, however contains a number of existing assets which are used within the wiki's tutorials. Both files can be found and downloaded [https://github.com/Nateonus/vsmodexamples/releases/latest from GitHub]. Simply unzip them into your game's mod folder.  

If you wish to setup a content mod on your own, or want more understanding of the files, follow the instructions below.  

To start setting up your mod, navigate to your Vintage Story install location, and enter the mods folder. Create a new folder with your mod's name - This will be where all mod-related files will be placed. It is recommended to open this folder in your selected IDE.

'''Note that creating JSON files may require changing file extensions. If you do not know how to do this, [https://www.indeed.com/career-advice/career-development/how-to-change-file-type follow these instructions].'''

To register our mod, we have to tell Vintage Story that our mod exists and some details about it. To do this, create a new file called '<nowiki/>''modinfo.json''' inside your mod workspace, either using your IDE or through Windows. Open the file, and paste the following json code:<syntaxhighlight lang="json">

{

</syntaxhighlight>This file is a very good example of how a json file is formatted, and you will notice that nearly every asset uses this file format. Json files list a set of "key": "value" entries, allowing you to change those values to fit what is desired. In this case, the following keys represent:

* '''"type": "content"''' - This tells Vintage Story that the mod is a content mod, and should load the provided assets. The options here are "theme", "content", or "code", however for this mod type we will use "content".

* '''"modid": "examplecontentmod"''' - This is your '''unique''' mod ID, which can be any combination of '''lowercase''' letters and numbers.

* '''"version": "1.0.0"''' - This is your mod's version. It follows the format of "major.minor.patch", called [https://semver.org/ semantic versioning].

Also note that our file starts and ends with curly brackets ('''{ })'''. This tells us that this file contains a ''single'' object. If a json file starts with square brackets ('''[ ]'''), this tells us that we can register multiple objects within that single file.

You can fill in the values above with your own mod info, or keep them the same. Most tutorials on the wiki will use this modinfo file.

This is just a basic modinfo file. For more information, and a more comprehensive list of available properties, visit the [[Modinfo]] page.

If desired, an image file called '<nowiki/>''modicon.png''' can be placed or created inside your mod workspace. This will automatically be loaded into Vintage Story, and be displayed next to your mod on the mod manager menu.

To actually create and modify game assets, Vintage Story searches for specific filepaths. Inside your mod workspace, create a folder called '<nowiki/>''assets''<nowiki/>'. This is where we place our different mod ''domains''. More information on domains can be found in '''Domains''<nowiki/>' section on this page.

Inside the new assets folder, create another new folder with the same name as your mod id. For example, my folder would be called '<nowiki/>''examplecontentmod''', as this is my mod id. Similar to your mod id, domains must be lowercase. This new folder is where your mod assets will be created! If a tutorial refers to your 'mod assets' folder, it is likely referring to this folder.

When your mod assets folder has been created, you are officially ready to start modding! Check out the '<nowiki/>''What's Next''' section to link to tutorials, and come back here when you need a reminder of how to organise your content mod.

When Vintage Story loads your mod, it looks inside your mod's root assets folder to find subfolders. Each one of these subfolders dictates a mod ''domain.'' A domain works as an identifier to seperate assets from multiple mods, and must be lowercase.

For example, imagine there exists two mods which both add in a new metal called 'Natium', but with slightly different functionality. Mod A adds the metal to work as a beginner-level metal, however Mod B adds the metal as an endgame metal. Without domains, Vintage Story would not be able to isolate these items based on the code alone, so it prefixes the domain to every asset. The code for Natium in Mod A now becomes "''moda:natium''", and the code for Mod B now becomes "''modb:natium''".

When creating content mods, you will access many different assets from inside your files, and it is important to understand how domains affect this. If you reference '''Asset A''<nowiki/>' in another asset's file, Vintage Story will automatically prefix your domain onto that reference. However, if you wish to reference an asset that exists in another domain, including the base game, you will need to add that prefix yourself.

For example, let us assume that '<nowiki/>''Asset A''<nowiki/>' in the '<nowiki/>''examplecontentmod'<nowiki/>'' domain wishes to access the default copper texture, which is located at '''block/metal/ingot/copper'.'' If you put that reference inside ''Asset A,'' Vintage Story will change that to "''examplecontentmod:block/metal/ingot/copper','' which will proceed to not work due to the file not existing in that domain. To counter this, you need to prefix that reference manually with the default game prefix, and place it as "''game:block/metal/ingot/copper''". This can also be used with other mod domains to use assets from other mods.

Note that all base game assets are placed under the '<nowiki/>''game''' domain.

If you want to distribute your mod for others to play, it is a good idea to pack your mod into a zip file. The best way to achieve this is to use the [https://www.7-zip.org/download.html 7zip program], or another zip program of your choice.

To pack your mod on Windows, select your modinfo, modicon, and assets folder, and right click on one of the files. In the context window, hover over "''7-zip''", and then select "''Add to archive...''". When entering a name for your zip file, most mods follow the format of "''modid-version".'' This allows users of your mod to easily differentiate between the version of mod you are using. Select '<nowiki/>''OK''' and your zip file will be created.

This file can then be uploaded for people to use on the [https://mods.vintagestory.at/ Vintage Story ModDB].

After each publish, it is recommended to increase your version number in your modinfo file.

As the base game is built using the content mod system, it is highly unlikely that your content mod will need modifying for newer versions. When a new major version is released, there may be rare instances where some formatting changes can cause side-effects, however these are very rare and would mainly happen when using more complex functionality.

Now your content mod has been setup, see what's next on the [[Modding:Content Mods#Following the Wiki Tutorials|Content Mod]] page.{{Navbox/modding|Vintage Story}}

</translate>