Modding:Setting up your Development Environment: Difference between revisions

From Vintage Story Wiki
(40 intermediate revisions by 5 users not shown)
Line 1: Line 1:
When you are ready to begin coding mods for Vintage Story, you probably would want to set up a development environment that simplifies the process of coding and testing your creations. But if you feel hardcore, you can even create your code mods with your most basic text editor. The game engine will compile your raw source files when it finds them in your mod folder. Otherwise continue to read this tutorial.


= Software Installation =
== Software ==


== Install VintageStory ==
When you are ready to begin coding mods for Vintage Story, you probably would want to set up a development environment that simplifies the process of coding and testing your creations. There are several applications that aid you in the development of mods. Here are some suggestions:


First of all download VintageStory and make sure you have installed the newest version of the game, otherwise errors may occur.
* [https://www.visualstudio.com/de/vs/community/ Visual Studio Community] is a free and very powerful development environment and covered in below guide. This is also the tool the Vintage Story Team uses to build the game. It also has a [https://www.visualstudio.com/vs/mac/ MacOS Version].


== Install Development Tool ==
* [https://code.visualstudio.com/ Visual Studio Code] is very a lightweight version of Visual Studio. Our precious community member [https://twitter.com/koppeh?lang=en copygirl] is using this tool and also [https://github.com/copygirl/howto-example-mod wrote a set up guide on github]


VintageStory is developed in C#. Now it's about to install a development program, which allows you to write and compile mods. There is a tutorial for each platform.
* [https://www.monodevelop.com/ MonoDevelop] is another IDE that is more lightweight than Visual Studio Community.


=== Windows ===
* [https://notepad-plus-plus.org/ Notepad++] your very basic text editing tool with some extra features. You can code mods in any text editor, really. It does however lack instant context sensitive feedback while programming, which is very helpful. If you choose this way, you can use the game itself to trial and error mods by reloading them while the game is running.


VintageStory is developed using VisualStudio. Luckily you can get VisualStudio Community for free [https://www.visualstudio.com/de/vs/community/ here]. Installation should be simple and straight forward to do, but depending on your internet connection it may take a while.
== Install Development Tool ==


----
VintageStory is developed in C#. Choose one of the above IDEs or other alternatives. We suggest using '''Visual Studio Community''' for Windows. For Linux you may want to use '''MonoDevelop''' or '''Visual Studio Code'''.


=== Linux ===
=== Installation Guide on Linux with MonoDevelop ===
 
There are multiple programs you could use. The following tutorials will use '''MonoDevelop''', but you can also use '''VisualStudio Code''' which is a light-weight, cross-platform development tool ([https://github.com/copygirl/howto-example-mod tutorial]). If you want to use MonoDevelop, just stay here and continue the tutorial.


'''1. Install FlatPak'''
'''1. Install FlatPak'''
Line 33: Line 30:
To open up MonoDevelop enter <code>flatpak run com.xamarin.MonoDevelop</code> in the terminal.
To open up MonoDevelop enter <code>flatpak run com.xamarin.MonoDevelop</code> in the terminal.


----
=== Installation Guide on Windows with Visual Studio ===


=== Mac OS ===
1. Go to https://visualstudio.microsoft.com/vs/community/ and install Visual Studio Community. Is free and fully functional


Download and install '''VisualStudio for Mac''' [https://www.visualstudio.com/vs/mac/ here]. Unfortunately nobody in our team has a mac, so we don't know for sure if the following tutorials work on mac without any problems.
2. You can now either get the mod template project or manually set up a mod project. The mod template offers a convenience tool to set up multiple mod projects and to quickly pack up and have a ready-to-ship mod


= Project Setup (SRC) =
== Setup using Mod template ==


The source mod system lets you build mods that shipped with source code that is compiled during run-time by the modloader engine. This has the great advantage of being open and easy to modify on the run but also (as of 1.6) comes with 2 major disadvantages. Up until version 1.6.x you only have a hardcoded list of library references available to you (System.dll, System.Core.dll, System.Drawing.dll, System.Xml.dll, System.Net.Http.dll, VintagestoryAPI.dll, Newtonsoft.Json.dll, protobuf-net.dll, Tavis.JsonPatch.dll, cairo-sharp.dll), any other reference will not get loaded and thus your mod would fail to compile. The second major disadvantage, affect all game versions, is that the inbuilt source compiler can only compile C# language features up until C# 6.0. If either of these disadvantages are a showstopper to you, we advice you to build a compiled mod.
To get started download the VSModTemplate solution ([https://github.com/anegostudios/vsmodtemplate/releases/download/1.5.4/VSModTemplate-v1.5.4.zip here]). Now you simply need to extract the zip archive to your desired place:
== Get the Modtemplate ==
 
To get started download the VSModTemplate solution ([https://github.com/anegostudios/vsmodtemplate/releases/download/1.3/VSModTemplate-v1.3.zip here]). Now you simply need to extract the zip archive to your desired place:


[[File:VSMods9.png]]
[[File:VSMods9.png]]
Line 50: Line 44:
Navigate to <code>VSMods</code> and double click <code>VSMods.sln</code> (only works if VisualStudio is installed). Alternatively you can also start VisualStudio hit <code>Open Project/ Solution</code>, navigate to the extracted folder and select <code>VSMods.sln</code>.
Navigate to <code>VSMods</code> and double click <code>VSMods.sln</code> (only works if VisualStudio is installed). Alternatively you can also start VisualStudio hit <code>Open Project/ Solution</code>, navigate to the extracted folder and select <code>VSMods.sln</code>.


But before you can start to work, you have to setup the ModTools first.
But before you can start to work, you have to set up the ModTools first.


== Run ModTools ==
=== Run ModTools ===


The ModTools allow you to do various tasks rather easily by typing in a command. Each platform requires a different way to start it.
The ModTools allow you to do various tasks rather easily by typing in a command. Each platform requires a different way to start it.
Please note, the mod tools have only been tested with Visual Studio and MonoDevelop, but they are not required to mod the game, it merely simplifies some of the tasks.
Please note, the mod tools have only been tested with Visual Studio and MonoDevelop, but they are not required to mod the game, it merely simplifies some of the tasks.


=== Windows ===
==== Windows ====


Double-click <code>vsmodtools.exe</code>.
Double-click <code>vsmodtools.exe</code>.


=== Linux ===
==== Linux ====


Open a terminal and navigate to this folder and enter <code>mono vsmodtools.exe</code>.
Open a terminal and navigate to this folder and enter <code>mono vsmodtools.exe</code>.


=== Mac OS ===
==== Mac OS ====


Double-click <code>modtools.command</code>.
Double-click <code>modtools.command</code>.
Line 71: Line 65:
[[File:ModTools.png]]
[[File:ModTools.png]]


== Setup ==
=== Setup ===


''Syntax: <code>setup [optional path]</code>''
''Syntax: <code>setup [optional path]</code>''
Line 77: Line 71:
Before doing anything else you have to setup your workspace. Just type in <code>setup</code> and it will automatically try to locate your VintageStory installation directory. If it cannot find it, you will be asked to type in the full path. Once you have entered your path, it will update your project files so you can start to work with it. Now open the project again and run your first test by hitting <code>start</code> [[File:VSMods10.png]]. If everything has been done correctly VintageStory should start.
Before doing anything else you have to setup your workspace. Just type in <code>setup</code> and it will automatically try to locate your VintageStory installation directory. If it cannot find it, you will be asked to type in the full path. Once you have entered your path, it will update your project files so you can start to work with it. Now open the project again and run your first test by hitting <code>start</code> [[File:VSMods10.png]]. If everything has been done correctly VintageStory should start.


== Add Mod ==
=== Project Setup (ZIP) ===
 
The source mod system lets you build zip mods that can ship source code besides their assets. The source code is compiled during run-time by the modloader engine. This has the great advantage of being open and easy to modify on the run but also comes with 2 major disadvantages. Up until game version 1.7.x you only have a hardcoded list of library references available to you (System.dll, System.Core.dll, System.Drawing.dll, System.Xml.dll, System.Net.Http.dll, VintagestoryAPI.dll, VSCreativeMod.dll, VSSurvivalMod.dll, VSEssentials.dll, Newtonsoft.Json.dll, protobuf-net.dll, Tavis.JsonPatch.dll, cairo-sharp.dll), any other reference will not get loaded and thus your mod would fail to compile. The second major disadvantage, affecting all game versions, is that the inbuilt source code compiler can only compile code only up until C# 6.0, so newer language features are not supported. If either of these disadvantages are a showstopper to you, we advise you to build a compiled mod.
 
==== Add Mod ====


''Syntax: <code>add <modid></code>''
''Syntax: <code>add <modid></code>''
Line 83: Line 81:
Adds a new mod project to your workspace, also generates an <code>assets</code>, a <code>src</code> folder and a <code>modinfo.json</code> file. The mod will be added to your visual studio solution and will be loaded by VintageStory. Make sure to fill in all additional information in <code>modinfo.json</code>.
Adds a new mod project to your workspace, also generates an <code>assets</code>, a <code>src</code> folder and a <code>modinfo.json</code> file. The mod will be added to your visual studio solution and will be loaded by VintageStory. Make sure to fill in all additional information in <code>modinfo.json</code>.


== Delete Mod ==
==== Delete Mod ====


''Syntax: <code>delete <modid></code>''
''Syntax: <code>delete <modid></code>''
Line 89: Line 87:
Before executing, make sure your project is closed, otherwise you might run into some difficulties. Running this command will delete the given mod completely (irreversible).
Before executing, make sure your project is closed, otherwise you might run into some difficulties. Running this command will delete the given mod completely (irreversible).


== Pack Mod ==
==== Pack Mod ====
''Syntax: <code>pack <modid></code>''
''Syntax: <code>pack <modid></code>''


Line 98: Line 96:
Packs all mods in your workspace at once.
Packs all mods in your workspace at once.


= Project Setup (DLL) =
=== Project Setup (Compiled Zip) ===
 
Both dll and zip mods have their advantages and disadvantages, so why not combine them together? This project setup is very similar to zip. Instead of adding the source code to the zip file, it uses the compiled dll. This allows you to have all the dll benefits while still having the zip mod asset structure.
 
==== Add Mod ====
 
''Syntax: <code>add <modid> compiled</code>''
 
Adds a compiled zip mod template to your workspace. The difference is that it uses a compiled dll instead of the actual source code. All other commands are equal to the zip ones.
 
==== Set Mod ====
 
''Syntax: <code>set <modid> <source|compiled></code>''
 
Sets the given zip mod either to source or compiled. This can be useful if you want to change the type of your mod later on.
 
=== Project Setup (DLL) ===
 
Dll mods are way more powerful than source mods, but they have two major downsides. Firstly, they are not able to carry assets which will be loaded by the game, secondly because they are so powerful they can be dangerous. Besides that dll mods can (unlike the others) have cross mod references, provide APIs and use C# 7. We recommend this type of mod for more experienced mod developers.
 
==== Add Mod ====
 
''Syntax: <code>add-dll <modid></code>''
 
Adds a new mod project to your workspace. A generated <code>AssemblyInfo.cs</code> file will be in your properties folder, it contains the mod information (name, author, version, description etc.) so make sure to change them before you spread the mod to other people. The mod will be added to your visual studio solution and will be loaded by VintageStory.
 
==== Delete Mod ====
 
''Syntax: <code>delete <modid></code>''
 
Before executing, make sure your project is closed, otherwise you might run into some difficulties. Running this command will delete the given mod completely (irreversible).
 
==== Release Mod ====
 
Once you launch VintageStory in your workspace, the dll mod will be compiled. You can find it in your <code>mods</code> folder, with the give name: <code><modid>.dll</code>. If you want to upload this mod or share it with your friends this is the file you need to use.
 
 
== Manual setup ==
 
* Create a new project
* Add at least a library reference to the VintageStoryApi.dll (on windows its located in %appdata%/VintageStory)
* Open the project properties. Under debug select "Start external program" select the VintageStory.exe. Also adjust the working directory to where the VintageStory.exe is located
* If you compile to a .dll file, set up a ModInfo attribute in your AssemblyInfo.cs ([https://github.com/anegostudios/vsmodexamples/blob/master/Properties/AssemblyInfo.cs example])
** Add the following command line arguments: <code>-openWorld="modsamplestest" -p3 --addModPath="C:\path\to\your\bin\folder" --addOrigin="C:\path\to\your\assets\folder\if\you\have\any"</code>
* If want to ship a source mod or mod with assets, set up a modinfo.json ([https://github.com/copygirl/CarryCapacity/blob/master/resources/modinfo.json example]). Make sure your folders are set up in a way that the modPath contains the modinfo.json and a folder named "src" containg your source files. Optionally it can also contain an assets folder for your assets.
** Add the following command line arguments: <code>-openWorld="modsamplestest" -p3 --addModPath="C:\path\to\your\modPath"</code>
* I recommend adding the [https://github.com/anegostudios/vsmodexamples/blob/master/RedirectLogs.cs RedirectLogs.cs] file to your project, so that you can see the log output in your visual studio output window. You should not ship your mod with it though.
* Run the project and hope for the best :D
* To ship a mod have a look at [[Mod Packaging]]
 
If you are having troubles the vsmodexamples you might be able to learn from the [https://github.com/anegostudios/vsmodexamples vsmodexamples project]
 
= Moving Forward =
 
If you've successfully managed to setup your development environment and can run Vintage Story through the '''VSMods''' project in your IDE then it's time to get started on your first code mod. At this point there are many options you can choose from as code mods can alter almost any aspect of the game. However, the best place to start is likely one again with Blocks and Items (since you should be familiar with making them using JSONS by this point).
 
Head over to the '''[[Modding:Advanced Blocks | Advanced Blocks]]''' page to make your first advanced code block.
 
Or head over to the '''[[Modding:Advanced Items | Advanced Items]]''' page to make your first advanced code item.
 
{{Navbox/modding|Vintage Story}}

Revision as of 00:23, 15 May 2020

Software

When you are ready to begin coding mods for Vintage Story, you probably would want to set up a development environment that simplifies the process of coding and testing your creations. There are several applications that aid you in the development of mods. Here are some suggestions:

  • Visual Studio Community is a free and very powerful development environment and covered in below guide. This is also the tool the Vintage Story Team uses to build the game. It also has a MacOS Version.
  • MonoDevelop is another IDE that is more lightweight than Visual Studio Community.
  • Notepad++ your very basic text editing tool with some extra features. You can code mods in any text editor, really. It does however lack instant context sensitive feedback while programming, which is very helpful. If you choose this way, you can use the game itself to trial and error mods by reloading them while the game is running.

Install Development Tool

VintageStory is developed in C#. Choose one of the above IDEs or other alternatives. We suggest using Visual Studio Community for Windows. For Linux you may want to use MonoDevelop or Visual Studio Code.

Installation Guide on Linux with MonoDevelop

1. Install FlatPak

It is required to install MonoDevelop so if you already have FlatPak then you can skip this step. FlatPak have their own guides of how to install it for many distributions here.

2. Install MonoDevelop

Simply open up a terminal and run the following command: flatpak install --user --from https://download.mono-project.com/repo/monodevelop.flatpakref
This might take a few minutes depending on your internet connection. (The latest version at the time of writing was around 275MB.) To open up MonoDevelop enter flatpak run com.xamarin.MonoDevelop in the terminal.

Installation Guide on Windows with Visual Studio

1. Go to https://visualstudio.microsoft.com/vs/community/ and install Visual Studio Community. Is free and fully functional

2. You can now either get the mod template project or manually set up a mod project. The mod template offers a convenience tool to set up multiple mod projects and to quickly pack up and have a ready-to-ship mod

Setup using Mod template

To get started download the VSModTemplate solution (here). Now you simply need to extract the zip archive to your desired place:

VSMods9.png

Navigate to VSMods and double click VSMods.sln (only works if VisualStudio is installed). Alternatively you can also start VisualStudio hit Open Project/ Solution, navigate to the extracted folder and select VSMods.sln.

But before you can start to work, you have to set up the ModTools first.

Run ModTools

The ModTools allow you to do various tasks rather easily by typing in a command. Each platform requires a different way to start it. Please note, the mod tools have only been tested with Visual Studio and MonoDevelop, but they are not required to mod the game, it merely simplifies some of the tasks.

Windows

Double-click vsmodtools.exe.

Linux

Open a terminal and navigate to this folder and enter mono vsmodtools.exe.

Mac OS

Double-click modtools.command.

ModTools.png

Setup

Syntax: setup [optional path]

Before doing anything else you have to setup your workspace. Just type in setup and it will automatically try to locate your VintageStory installation directory. If it cannot find it, you will be asked to type in the full path. Once you have entered your path, it will update your project files so you can start to work with it. Now open the project again and run your first test by hitting start VSMods10.png. If everything has been done correctly VintageStory should start.

Project Setup (ZIP)

The source mod system lets you build zip mods that can ship source code besides their assets. The source code is compiled during run-time by the modloader engine. This has the great advantage of being open and easy to modify on the run but also comes with 2 major disadvantages. Up until game version 1.7.x you only have a hardcoded list of library references available to you (System.dll, System.Core.dll, System.Drawing.dll, System.Xml.dll, System.Net.Http.dll, VintagestoryAPI.dll, VSCreativeMod.dll, VSSurvivalMod.dll, VSEssentials.dll, Newtonsoft.Json.dll, protobuf-net.dll, Tavis.JsonPatch.dll, cairo-sharp.dll), any other reference will not get loaded and thus your mod would fail to compile. The second major disadvantage, affecting all game versions, is that the inbuilt source code compiler can only compile code only up until C# 6.0, so newer language features are not supported. If either of these disadvantages are a showstopper to you, we advise you to build a compiled mod.

Add Mod

Syntax: add <modid>

Adds a new mod project to your workspace, also generates an assets, a src folder and a modinfo.json file. The mod will be added to your visual studio solution and will be loaded by VintageStory. Make sure to fill in all additional information in modinfo.json.

Delete Mod

Syntax: delete <modid>

Before executing, make sure your project is closed, otherwise you might run into some difficulties. Running this command will delete the given mod completely (irreversible).

Pack Mod

Syntax: pack <modid>

Creates a mod zip file and places it in /releases/<modid>/<modid>_v<modversion>.zip. This file is ready for use and can be shared with other people.

Syntax: pack-all

Packs all mods in your workspace at once.

Project Setup (Compiled Zip)

Both dll and zip mods have their advantages and disadvantages, so why not combine them together? This project setup is very similar to zip. Instead of adding the source code to the zip file, it uses the compiled dll. This allows you to have all the dll benefits while still having the zip mod asset structure.

Add Mod

Syntax: add <modid> compiled

Adds a compiled zip mod template to your workspace. The difference is that it uses a compiled dll instead of the actual source code. All other commands are equal to the zip ones.

Set Mod

Syntax: set <modid> <source|compiled>

Sets the given zip mod either to source or compiled. This can be useful if you want to change the type of your mod later on.

Project Setup (DLL)

Dll mods are way more powerful than source mods, but they have two major downsides. Firstly, they are not able to carry assets which will be loaded by the game, secondly because they are so powerful they can be dangerous. Besides that dll mods can (unlike the others) have cross mod references, provide APIs and use C# 7. We recommend this type of mod for more experienced mod developers.

Add Mod

Syntax: add-dll <modid>

Adds a new mod project to your workspace. A generated AssemblyInfo.cs file will be in your properties folder, it contains the mod information (name, author, version, description etc.) so make sure to change them before you spread the mod to other people. The mod will be added to your visual studio solution and will be loaded by VintageStory.

Delete Mod

Syntax: delete <modid>

Before executing, make sure your project is closed, otherwise you might run into some difficulties. Running this command will delete the given mod completely (irreversible).

Release Mod

Once you launch VintageStory in your workspace, the dll mod will be compiled. You can find it in your mods folder, with the give name: <modid>.dll. If you want to upload this mod or share it with your friends this is the file you need to use.


Manual setup

  • Create a new project
  • Add at least a library reference to the VintageStoryApi.dll (on windows its located in %appdata%/VintageStory)
  • Open the project properties. Under debug select "Start external program" select the VintageStory.exe. Also adjust the working directory to where the VintageStory.exe is located
  • If you compile to a .dll file, set up a ModInfo attribute in your AssemblyInfo.cs (example)
    • Add the following command line arguments: -openWorld="modsamplestest" -p3 --addModPath="C:\path\to\your\bin\folder" --addOrigin="C:\path\to\your\assets\folder\if\you\have\any"
  • If want to ship a source mod or mod with assets, set up a modinfo.json (example). Make sure your folders are set up in a way that the modPath contains the modinfo.json and a folder named "src" containg your source files. Optionally it can also contain an assets folder for your assets.
    • Add the following command line arguments: -openWorld="modsamplestest" -p3 --addModPath="C:\path\to\your\modPath"
  • I recommend adding the RedirectLogs.cs file to your project, so that you can see the log output in your visual studio output window. You should not ship your mod with it though.
  • Run the project and hope for the best :D
  • To ship a mod have a look at Mod Packaging

If you are having troubles the vsmodexamples you might be able to learn from the vsmodexamples project

Moving Forward

If you've successfully managed to setup your development environment and can run Vintage Story through the VSMods project in your IDE then it's time to get started on your first code mod. At this point there are many options you can choose from as code mods can alter almost any aspect of the game. However, the best place to start is likely one again with Blocks and Items (since you should be familiar with making them using JSONS by this point).

Head over to the Advanced Blocks page to make your first advanced code block.

Or head over to the Advanced Items page to make your first advanced code item.

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.