Setting up your Development Environment

From Vintage Story Wiki
Jump to: navigation, search

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

Install VintageStory

First of all download VintageStory and make sure you have installed the newest version of the game, otherwise errors may occur.

Install Development Tool

VintageStory is developed in C#. Programming is most efficiently done in an IDE (integrated development environment). Let's install one!

Windows

VintageStory is developed using VisualStudio. You can get VisualStudio Community for free here. Installation should be simple and straightforward to do, but depending on your internet connection it may take a while.

Linux

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 (tutorial). If you want to use MonoDevelop, just stay here and continue the tutorial.

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.

Mac OS

Download and install VisualStudio for 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.

Get the Modtemplate

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