Guide: Dedicated Server

This page is under construction.
This page is being created, or is in the process of extensive expansion or major restructuring. Until this notice is removed, please do not translate this page. Expect the content of this page to change significantly.

Note
When (default) appears before a piece of information, it's a reminder that the instructions need to be adjusted if the reader did not use the default settings.
When (example) appears before a piece of information, it's a reminder that if the reader used the example provided earlier, then they should have the outcome displayed at this point.

Dedicated server on Windows

Below is a detailed guide for creating a multiplayer server on a computer using Windows operating system.

Last verified for
Windows 11 Home
version 23H2
64-bit operating system

Install Vintage Story

The default install location for Vintage Story is the Roaming folder of AppData. If you copy-paste %AppData%/Vintagestory into the address bar of File Explorer and hit the Enter key, you should be directed to that folder (if it exists). Presumably you already downloaded the game for singleplayer use and have updated to the latest version.

When you install Vintage Story for singleplayer, you get more than one program file. Inside (default) %AppData%/Vintagestory should be both Vintagestory.exe and VintagestoryServer.exe.

If you intend to host from a computer separate than the one you play on, you also need to install the game on the host machine; the process is no different. However, I'm going to refer to the singleplayer installation as %AppData%/Vintagestory and to the host installation as %AppData%/VSserver, regardless of whether the host is a separate machine.

Reminder: Forum and game accounts are currently separate. Log in to account.vintagestory.at rather than vintagestory.at to go directly to the downloads area.

Unless you specifically want to use an older version of the game, use the Recommended Download buttons.

Set data path

If you intend to host from the same machine that you play on, it's highly advisable to designate a separate area for the server data, so it doesn't get mixed up with your singleplayer data (save files, settings, etc). If you're hosting on a separate machine, you can skip this section. But keep in mind that the directions here assume distinct file paths for singleplayer data and server data.

Shortcut method:

1. Navigate to the location where you will store the server's data, such as a new VSserver folder created in C:\Users\YourUsername\AppData\Roaming
2. Create a folder for the server's data and give it a clear name, such as VSserverData
3. Open that folder and copy the entire path from the address bar of File Explorer. (example: C:\Users\YourUsername\AppData\Roaming\VintagestoryServer\VSserverData)
4. Open the game's application folder; it is %appdata%/VintageStory by default.
5. Create a shortcut of VintagestoryServer.exe. This can usually be accomplished through the right-click menu; google instructions specific to your operating system version if needed.
6. Open the Properties of the new shortcut. This can usually be accomplished through the right-click menu.
7. Click in the Target field of the shortcut's Properties, then go to the very end of what's written there. Add one space, then --dataPath=, then Paste the folder path you copied earlier, in quotes. The entire contents of the Target field should now be something like this: "C:\Users\YourUsername\AppData\Roaming\Vintagestory\VintagestoryServer.exe" --dataPath="C:\Users\YourUsername\AppData\Roaming\VintagestoryServer\VSserverData"

Optional: you can move/copy the shortcut, to your desktop and/or your new VintagestoryServer folder

While the following tutorial is for using different versions of the game on a single machine, the latter half deals with setting a dataPath; skip to 2:57:

How do I...? by Shi No Hakobi-te

Batch script method (functionally equivalent to the shortcut method above):

1. To create a batch script, simply create a blank text document and rename it with the .bat file extension.
2. You can edit it by right clicking and selecting edit. Then just type %appdata%/Vintagestory/VintagestoryServer.exe --dataPath "[PATH]" replacing [PATH] with the desired path for the server's data, then save and close.

Running the script will run the server with the alternate datapath, and will generate its own collection of config files there. This is functionally equivalent to the modified link.

Next:

• Run the shortcut you made of VintagestoryServer.exe or the batch script. This should create an array of subfolders (such as Mods) inside the VSserverData folder.
• Close the server for now.

Configure router/firewall

Presumably you want to share a world with players who don't live at your address and use the same local network. A firewall is a device or program that controls the flow of network traffic involving different security levels. If you want the server to be accessible from outside of your local network, you need to configure your internet router to permit Vintage Story to use a port.

The process for opening a port varies significantly and cannot be effectively detailed here. Google "port forward" with your router's make and model for instructions. Examples: "port forward TP-Link AC1200" or "port forward ASUS RT-AX1800S".

Router settings

For the above example, here's what you should put:

Port Forwarding
Name: Vintage Story
Global Port Range: 42420 - 42420
Base: 42420
Protocol: TCP

While TCP/UDP shouldn't prevent TCP from working, change the dropdown to just TCP if UPnP isn't an option.

While permanently open ports, like a 24/7 game server, are more prone to experience malicious efforts such as port scanning bots and brute attack bots than temporarily open ports, the risk is minor. If I get information on safeguard mechanisms like fail2ban on linux to block after too-frequent login attempts, I'll add them here.

By the way: configuring the router only needs to happen before launching VintagestoryServer.exe if you want to advertise to the master server.

Run VintagestoryServer.exe

If you set a new dataPath, instead run the shortcut you made of VintagestoryServer.exe or the batch script. If Windows Firewall asks for permission, grant any necessary access. A console should open, with white text on a black background. If it closes right away, you might have another instance of Vintage Story already running; close that and try again.

Server console

You don't need to understand everything that's printed in the console, but do skim it. A message along the lines of DATE TIME [Server Event] Dedicated Server now running on Port 42420 and all ips! is a good indicator that the server is ready for players to log in.

Share IP address with playerbase

An IP address (Internet Protocol address) is a numeric label assigned by your internet service provider. While it's not risky to give your home address or phone number to most people, some are malicious or will sell your data. Similarly, it's good to be selective about who you share your IP address with: don't post it publicly on the internet in conjunction with identifying personal information. Do give it to friends you want to spend time with, and to Vintage Story community members (staff or volunteers in the Discord server) assisting with technical issues.

Simply googling "what's my IP" will yield several sites providing your public IP address. Unless you pay for a static IP address, your IP address will likely chance a few times over the course of your server's lifetime. If players suddenly become unable to connect to your server, re-google your IP address and provide players with the new number.

Public IP, also known as an external IP, is the address provided by your internet service provider. Devices on the same network share this IP address when accessing the internet. For specific details, such as location, you can perform an IP lookup check. On the other hand, private, or local, IPs are assigned to each device on your network by your router.

Find your IP address, and give it to the people who will be joining (external IP or local IP)

While your IP address won’t give away sensitive information like your phone number or exact location, hackers can still use your IP against you. If a cybercriminal knows your IP address, the can use it for malicious purposes

Add server to Multiplayer menu

1. From the main menu, select Multiplayer. You might already have some servers listed that you joined previously.
2. Click the Add new server button.
3. Give your server a name; you can easily change it later.
   1. In the next field, put your IP address. In most cases, you do not need to put the port number after the IP address.
   2. The password field is irrelevant unless the host set a password (see Guide:_Dedicated_Server#Set protections.
   3. Save.
4. Click the name of the server to join.

For any friends who wish to join, they need to complete these same steps except for step 2 they need to put the host's IP address. It's not important if the name they give the server matches the name the host gave it.

Set protections

It's highly advisable to put measures in place to prevent people with bad intentions from being able to harm your world. You can do this via commands in the console or (if you have admin permissions) the in-game chat overlay, or by editing the serverconfig.json file, located in (Example) C:\Users\YourUsername\AppData\Roaming\VintagestoryServer\VSserverData.

Serverconfig changes do not take effect until the server is relaunched. When you've put in place all of the strategies desired from the suggestions below, save the serverconfig.json file or do /autosavenow. Then do /stop and relaunch Vintagestoryserver.exe

Don't advertise

If you don't want strangers to join, you might as well prevent your server showing in the list when somebody selects "Browse public servers".

• Edit serverconfig.json: Change "AdvertiseServer": true, to "AdvertiseServer": false,. Be sure to end the line with a comma.

OR

• Run a command: /serverconfig advertise false.

Set a password

• Edit serverconfig.json: Change "Password": null, to "Password": "thisisnotastrongpw",. Be sure to enclose the password with quotation marks and end the line with a comma.

OR

• Run a command: /serverconfig password thisisnotastrongpw. No spaces permitted.
• Tell the password to your friends. They should open the settings for your server (click the pencil icon next to the server name in Multiplayer menu) and type it in the Password field, then Save.

Use a whitelist

Only individuals added to a "whitelist" will be able to connect to the server. Similarly, a blacklist prevents specific people or mods.

• Edit serverconfig.json: Change "OnlyWhitelisted": false, to "OnlyWhitelisted": true,. Be sure to end the line with a comma.

OR

• Run a command: /serverconfig onlywhitelist true.
• Get the exact spelling of your friends' usernames for the game. For each, run this command: /player [username] whitelist on (replace [username] with their username and don't type the brackets). The server does not need to be restarted after whitelisting an individual. It's impractical to whitelist via json file.

Change default role

Instead of default survival player abilities, somebody who joins will only have the abilities described by the role you assign. Suvisitor role "can only visit this world and chat but not use/place/break anything."

• Edit serverconfig.json: Change "DefaultRoleCode": "suplayer", to "DefaultRoleCode": "suvisitor",. Be sure to enclose the role with quotation marks and end the line with a comma.
• Run a command: A command to set the default role code is not currently available. To adjust a player's role from suvisitor to full suplayer, do /player [username] role suplayer (replace [username] with their username and don't type the brackets). You can do this while they are online or offline. The server does not need to be restarted after changing somebody's role.

Reminder: save changes and relaunch the server for the changes to take effect.

Customize world

See Preset_playstyles

Add/remove mods

Assuming that you set a custom data path (such as %AppData%/VSserverData) and launched the server, there should now be a Mods folder within %AppData%/VSserverData.

Inside %AppData%/VSserverData should also be a serverconfig.json file, which can be edited with a program such as Notepad++. The ModPaths key indicates where the server should look for mods to load. For instance, "ModPaths": [

   "Mods",
   "\\AppData\\VSserverData\\Mods"
 ],/

Option 1) You can download/paste mod zip files into %AppData%/VSserverData/Mods. This is best done while the server is offline. Change made will take effect when the server is re-launched. Option 2) You can use commands to install/remove mods, or list currently-installed mods. See List_of_server_commands/moddb

When a player attempts to join your server, they will be prompted to download your list of mods. Only mods that are tagged as Server-side or Universal will be auto-downloaded in this way. Client-side mods would need to be manually added by the player to the server-specific subfolder within (default) %AppData%/VintagestoryData/ModsByServer.

Errors

Unable to connect to server

1kb downloaded

If it takes more than 30 seconds to download the first kilobyte, use the Cancel button and try again. The next attempt is usually normal-fast.

host has failed to respond

"A connection attempt failed because the connected party did not properly respond after a period of time, or established connect failed because connected host has failed to respond." Problem: likely an error in the port forwarding Solution: if UPnP isn't an option, try TCP. TCP/UDP is unlikely to work although logically it should.

Gain admin powers

See List_of_server_commands#Privilege_Control

Dedicated server on Linux

This describes how to set up the server as a service on Linux systems.
Note: This section only works for x64 processors; if using ARM, please refer to the following section.

Requirements

• .NET Runtime 7.0 This should be all needed to run a Vintagestory server. Everything else is just for convenience to start and manage it.
• install pgrep, screen and wget using your systems package manager.

Setup the server

1. Download the game

Advice: Create a separate directory for Vintage Story as the tar.gz does not contain a subfolder.

 mkdir server && cd server

Goto http://account.vintagestory.at/downloads
Copy the link of the newest "vs_server_linux-x64_*.*.*.tar.gz" package (Linux Server (.tar.gz) under Show other available downloads of Vintage Story)
Download with "wget" via console (Vintage Story version 1.18.8 in this example).

wget https://cdn.vintagestory.at/gamefiles/stable/vs_server_linux-x64_1.18.8.tar.gz

2. Extract tar.gz package

tar xzf vs_server_linux-x64_*.*.*.tar.gz

3. Make server.sh script executable

chmod +x server.sh

4. Edit server.sh file

For security reasons you should not run the server as root user, so by default USERNAME is set to vintagestory. On most linux operating systems you can create a user with the command adduser.

adduser vintagestory

Then change these options for your needs:

USERNAME='<your-vs-server-username>'

 VSPATH='<your-vs-directory>'

5. Open the port at the firewall (if needed)

firewalld

 firewall-cmd --permanent --zone=public --add-port=42420/tcp
 firewall-cmd --reload

iptables

 iptables -A INPUT -p tcp -m tcp --dport 42420 -j ACCEPT

ufw

 sudo ufw allow 42420/tcp

6. Server start and first steps

 ./server.sh start
 
 Wait for the startup to finish, then you can give yourself OP with
 ./server.sh command "/op <youusername>"

7. Connect to your IP/Domain and have fun

---

Dedicated Servers on ARM64

Note: Please note the ARM64 version is EXPERIMENTAL please report any issues to the discord .

Currently (in game version 1.19.3 - 1.19.4, February 2024) no ARM64 .NET7 version of the Harmony patching library is available. Therefore coded mods which use Harmony will not work on an ARM64 server. If a beta of the Harmony library becomes available in future, server owners can try installing it for themselves.

The ARM64 version is available on GitHub

I recommend using the install script located on the GitHub. The following is a step by step guide on how to use the script on a Debian based system (Ubuntu, Debian, Rasbian, etc).

1. Install the required dependencies to use this script by doing apt -y install curl jq

2. Create a new file named arminstall.sh by running vim arminstall.sh or nano arminstall.sh

3. Copy the contents of the arminstall.sh file from GitHub to your newly created file and save it by using :wq with Vim or Ctrl + X, then Y, then Enter with Nano.

4. Make the script executable by running chmod +x arminstall.sh

5. Run the script by doing ./arminstall.sh

6. Start the server by using ./VintagestoryServer or dotnet VintagestoryServer.dll

This will download the latest version of Vintagestory to the current working directory, then replace the needed files to work with ARM.

If at any time you want to update to the latest version of Vintage Story, simply run the script again.

---