Modding:Setting up your Development Environment/es

This page was last verified for Vintage Story version 1.16.4.

Software

Cuando estés listo para empezar a programar mods para Vintage Story, probablemente quieras configurar un entorno de desarrollo que simplifique el proceso de programar y probar tus creaciones. Existen varias aplicaciones que te ayudarán en el desarrollo de mods. Aquí tienes algunas sugerencias:

• Comunidad de Visual Studio es un entorno de desarrollo gratuito y muy potente que se describe en la siguiente guía. También es la herramienta que utiliza el equipo de Vintage Story para crear el juego. También tiene una Versión MacOS .

• Jetbrains Rider es un entorno de desarrollo freemium y moderno, con soporte sin fisuras para proyectos, keybindings y layouts de Visual Studio. Es un producto empresarial y algunas características están bloqueadas detrás de una licencia (comprobación de duplicación de código, herramientas de desarrollo web), pero las características que usted necesita para el desarrollo de VS mod son todas gratuitas. La indexación / ir a las características de referencia y características incorporadas descompilación son muy poderosos, ya que son capaces de hacer clic en un método Vintage Story utiliza y que le mostrará el código detrás de él. Tenga en cuenta que actualmente tiene un error + solución documentada aquí.

• Visual Studio Code es una versión muy ligera de Visual Studio. Nuestro preciado miembro de la comunidad copygirl está utilizando esta herramienta y también escribió una guía de configuración en github.

• MonoDevelop es otro IDE más ligero que Visual Studio Community.

• Notepad++ es una herramienta de edición de texto muy básica con algunas características extra. Usted puede codificar mods en cualquier editor de texto, en realidad. Sin embargo, carece de retroalimentación instantánea sensible al contexto mientras se programa, lo cual es muy útil. Si eliges este modo, puedes usar el propio juego para probar mods recargándolos mientras el juego se está ejecutando.

Instalar la herramienta de desarrollo

VintageStory está desarrollado en C#. Elige uno de los IDEs anteriores u otras alternativas. Sugerimos usar Visual Studio Community para Windows. Para Linux puede usar Visual Studio Code, Rider o MonoDevelop.

Después de descargar un IDE, ahora puede obtener el proyecto mod template o configurar manualmente un proyecto mod. La plantilla mod ofrece una herramienta práctica para configurar múltiples proyectos mod y para empaquetar rápidamente y tener un mod listo para enviar.

Guía de instalación en Windows / macOS con Visual Studio

OS	Repo	Command
Windows	download exe	Run archivo descargado
macOS	download dmg	Run archivo descargado

Installation Guide on Linux / macOS with MonoDevelop

You can use the MonoDevelop IDE to make VS mods on Linux. The download instructions are below, choose your OS and follow the link to add the repo, then run the install command.

OS	Repo	Command
Debian 8-10	repo	sudo apt-get install monodevelop
Ubuntu 14.04-20.04	repo	sudo apt-get install monodevelop
CentOS / RedHat	repo	yum install monodevelop
Using Flatpak	Download Flatpak	flatpak install --user --from https://download.mono-project.com/repo/monodevelop.flatpakref
macOS	build guide	Use Visual Studio or build from source
Other	compile from source	Follow the instructions to compile from source

Installation Guide on Linux / macOS with Visual Studio Code

You can use Visual Studio Code to make VS mods on Linux. The download instructions are below, choose your OS and follow the link to download it.

OS	Download	Command
Debian 8-10	download deb	sudo dpkg -i /path/to/vscode/file.deb && sudo apt-get install -f
Ubuntu 18.04-20.04	download deb	sudo apt install /path/to/vscode/file.deb
CentOS / RedHat / Fedora / SUSE	download rpm	rpm -ih /path/to/vscode/file.rpm
Arch	package	yay -S visual-studio-code-bin
Using Snap	Download snapd	sudo snap install code --classic
macOS	download zip	Run downloaded file
Other	compile from source	Follow the instructions to compile from source

Installation Guide on Windows / Linux / macOS with JetBrains Rider

You can use Jetbrains Rider to make VS mods on Linux. The download instructions are below, choose your OS and follow the link to download it.

OS	Download	Command
Windows	download exe	Run downloaded file
Arch	package	yay -S rider mono mono-msbuild
Using Toolbox	Download Toolbox	Follow the given instructions for your OS
Using Snap	Download snapd	sudo snap install rider --classic
macOS	download dmg	Run downloaded file
Other	download .tar.gz	sudo tar -xzf ideaIU.tar.gz -C /opt && cd /opt/idea-dir-edit-me && sudo ./idea.sh

Plantillas de Mods

• La plantilla oficial de Mod para Visual Studio que está cubierta en este artículo.
• Configuración VSCode de copygirl

Configuración con la plantilla oficial de Mod

Para empezar, descargue la plantilla VSModTemplate desde GitHub. Ahora sólo tienes que extraer el archivo zip en el destino deseado.

Navega hacia vsmodtemplate-x.y.z y haga doble clic en VSMods.sln (sólo funciona si Visual Studio está instalado). También puede iniciar Visual Studio pulsando Archivo -> Abrir -> Proyecto/Solución..., navegue hasta la carpeta extraída y seleccione VSMods.sln.

Pero antes de ponerte manos a la obra, tienes que configurar primero las ModTools.

Ejecutar el ModTools

Las ModTools te permiten realizar diversas tareas con bastante facilidad tecleando un comando. Cada plataforma requiere una forma diferente de iniciarlo. Por favor, ten en cuenta que las herramientas mod sólo han sido probadas con Visual Studio y MonoDevelop, pero no son necesarias para modificar el juego, simplemente simplifican algunas de las tareas.

Windows

Doble-click vsmodtools.exe.

Linux

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

Mac OS

Double-click modtools.command.

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 Vintage Story 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 clicking Start . If everything has been set up correctly, Vintage Story 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 one major disadvantage, which is that the inbuilt source code compiler can only compile code up until C# 6.0, so newer language features are not supported. If this is a showstopper for 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 Vintage Story. 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 it's located in the installation directory)
• Open the project properties. Under debug select "Start external program" select the VintageStory.exe. Also adjust the working directory to where the executable 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" -pcreativebuilding --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" containing your source files. Optionally it can also contain an assets folder for your assets.
  • Add the following command line arguments: -openWorld="modsamplestest" -pcreativebuilding --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. Be sure not to 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, 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.

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.