Vintage Story Server Setup Guide

This guide covers how to set up and configure your Vintage Story dedicated server hosted with Legion Hosting, including first-time startup, GPanel variables, version management, server configuration, world settings, connecting players, and save management. For mod installation, see Vintage Story Mod Installation. For admin setup and commands, see Vintage Story Admin Commands.

Before you begin: Make sure your server is created in GPanel. If you need help finding your server's IP address and port, see How to Find Your Server IP and Port.

First Start

When you start your Vintage Story server for the first time from GPanel, the server will automatically download the game files from the official Vintage Story API and generate a default world. This initial startup may take several minutes while files are downloaded and extracted.

Log in to GPanel and select your Vintage Story server.
Before starting, review the Startup tab to confirm your preferred version branch (stable, unstable, or pre-release).
Click Start on the Console tab. Watch the console output for progress messages as the server downloads and installs game files.
Once you see a message indicating the server is listening for connections, the server is ready. A default serverconfig.json file will be generated automatically.

First start takes longer than usual. The server must download the full Vintage Story server package before it can start. Subsequent starts will be much faster unless you change the version or branch.

GPanel Startup Variables

Core server settings are controlled through the Startup tab in GPanel. Review and adjust these before starting your server.

Variable	Default	Description
`SERVER_PORT`	(assigned)	The game port players use to connect. This is automatically assigned by GPanel -- check the Network tab for your assigned port.
`MAX_CLIENTS`	`16`	Maximum number of simultaneous players. Can be set up to 256. Should match your hosting plan's resources.
`FILES_BRANCH`	`stable`	Which release branch to use. Options: `stable`, `unstable`, or `pre`. See the Version Management section below for details.
`RELEASE_VERSION`	`latest`	The specific version to install. Set to `latest` to always use the newest release on your chosen branch, or enter a specific version number (e.g. `1.19.8`) to pin to that version.
`OPTIONS`	(empty)	Additional command-line arguments passed to the server process on startup. Leave empty unless you need specific startup flags.
`SQLITE_TMPDIR`	(auto)	Temporary directory used by SQLite for database operations. Typically does not need to be changed.

After updating startup variables, restart the server from GPanel for the changes to take effect.

Version Management

Vintage Story offers three release branches. Your choice of branch is set via the FILES_BRANCH startup variable in GPanel.

Branch	Value	Description
Stable	`stable`	The recommended branch for most servers. These releases have been thoroughly tested and are the most reliable for long-term worlds.
Unstable	`unstable`	Beta releases with new features and changes that are still being tested. May contain bugs. Use this if you want early access to new content and accept some instability.
Pre-release	`pre`	Early development builds. These are the least tested and may have significant issues. Only recommended for testing purposes -- not for production servers.

Pinning a Specific Version

By default, RELEASE_VERSION is set to latest, which means the server will download and install the newest version available on your chosen branch every time the server starts (if a newer version is available). To prevent automatic updates and lock your server to a specific version:

Go to the Startup tab in GPanel.
Change RELEASE_VERSION from latest to the exact version number you want (e.g. 1.19.8).
Restart the server. It will use only the pinned version regardless of newer releases.

Mod compatibility: If you are running mods, pinning a specific version is recommended. Game updates can break mod compatibility, and updating mid-playthrough can cause issues. Check that your mods support the target version before updating. See Vintage Story Mod Installation for details.

Switching branches may require a world reset. Moving between stable and unstable branches can introduce world format changes. Always back up your world before changing branches. If the new version is incompatible with your existing world, you may need to start a new one.

serverconfig.json

The primary server configuration file is serverconfig.json, located in the server root directory. This file is generated automatically on first start. Stop the server before editing it, then restart for changes to take effect.

Stop the server from the GPanel Console tab.
Open the Files tab and click serverconfig.json to edit it.
Modify the settings you need (see the table below).
Save the file and start the server.

Key Settings

Setting	Example Value	Description
`ServerName`	`"My Legion VS Server"`	The name displayed in the in-game server browser. Make it descriptive so players can find your server.
`WelcomeMessage`	`"Welcome to the server!"`	Message shown to players when they join. Supports basic formatting.
`MaxClients`	`16`	Maximum number of simultaneous players. Should match the `MAX_CLIENTS` startup variable.
`Password`	`"mysecretpass"`	Password required to join the server. Leave as an empty string (`""`) for a public server.
`AllowPvP`	`true`	Set to `true` to enable player vs player combat, or `false` for a PvE-only server.
`SpawnRadius`	`50`	Radius (in blocks) around the world spawn point where new players can spawn. A larger value spreads players out more on join.
`MapSizeX`	`1024000`	World width in blocks. The default value creates a very large world. Reducing this limits how far players can travel east-west.
`MapSizeZ`	`1024000`	World depth in blocks. The default value creates a very large world. Reducing this limits how far players can travel north-south.
`WorldSeed`	`"myseed123"`	Seed used for world generation. The same seed produces the same world. Leave as an empty string for a random seed.

A minimal example of key settings in serverconfig.json:

{
  "ServerName": "My Legion VS Server",
  "WelcomeMessage": "Welcome! Enjoy your stay.",
  "MaxClients": 16,
  "Password": "",
  "AllowPvP": true,
  "SpawnRadius": 50,
  "MapSizeX": 1024000,
  "MapSizeZ": 1024000,
  "WorldSeed": ""
}

The file must be valid JSON. Make sure all strings are enclosed in double quotes, booleans are lowercase (true/false), and there are no trailing commas after the last item in an object or array. If the server fails to start after editing, check for JSON syntax errors.

World Configuration

Vintage Story generates its world based on settings in serverconfig.json. World generation only occurs on the first start with a given world -- changing generation settings after the world has been created will not retroactively alter existing terrain.

World Generation Settings

WorldSeed: Determines the terrain layout, biome placement, and resource distribution. Set a specific seed to share the same world layout with others, or leave it empty for a randomly generated world.
MapSizeX / MapSizeZ: Control the maximum playable area. Smaller values create a more contained world and can reduce resource usage. Players who reach the edge of the map will not be able to travel further in that direction.
WorldConfig: The WorldConfig object within serverconfig.json allows you to fine-tune world generation parameters such as landform scale, climate patterns, and geological features. These are advanced settings -- the defaults work well for most servers.

World generation settings are locked after creation. Settings like WorldSeed, MapSizeX, and MapSizeZ only take effect when the world is first generated. To apply new generation settings, you must create a new world (see Save Management below).

Choosing a Seed

The seed can be any text string or number. Players in the Vintage Story community share seeds for interesting world layouts. If you want a specific type of terrain or spawn location, search the Vintage Story forums or community sites for recommended seeds.

How to Connect

Players connect to your Vintage Story server through the in-game multiplayer menu.

Direct Connect

Launch Vintage Story and click Multiplayer from the main menu.
Click Direct Connect.
Enter your server's IP address and game port in the format:
```
your.server.ip:port
```
Check the Network tab in GPanel for your assigned IP and port.
Click Connect. If the server has a password, enter it when prompted.

Server Browser

Launch Vintage Story and click Multiplayer from the main menu.
The server browser will load a list of public servers. Use the search bar to find your server by name (the ServerName value from serverconfig.json).
Click your server in the list and click Join.

Server not appearing in the browser? The server browser can take several minutes to index a newly started server. Use Direct Connect for immediate access. Also confirm that you have not set a password -- password-protected servers may not appear in the public browser depending on server settings.

Save Management

Vintage Story world data is stored on your server and saved automatically during gameplay.

World Data Location

World save files are stored in the data/ directory on your server. The exact path depends on your world name. You can access these files through the GPanel Files tab or via SFTP.

Backing Up Your World

Stop the server to ensure a clean backup (no files being written mid-save).
Connect to your server via SFTP. See How to Upload Files via SFTP for connection instructions.
Download the entire data/ directory to your local machine.
Store the backup in a safe location. Consider keeping multiple dated backups in case you need to roll back to a specific point.

Regular backups are strongly recommended. World corruption, accidental griefing, or failed mod updates can all result in data loss. Back up your world before making any significant changes such as updating the game version, adding or removing mods, or changing world settings.

Resetting the World

To start a completely fresh world:

Stop the server from the GPanel Console tab.
Back up the existing world data if you want to keep it (see above).
Navigate to the data/ directory in the GPanel file manager and delete the world save files.
Optionally update the WorldSeed in serverconfig.json to generate a different world layout.
Start the server. A new world will be generated from scratch using your current configuration settings.

Deleting world files is permanent. Once deleted, the world cannot be recovered unless you have a backup. Always download a backup before performing a world reset.

Need Help?

If you run into an issue not covered in this guide, open a support ticket and include your server's IP address, a description of the problem, and any relevant console output from GPanel.

Vintage Story Server Setup Guide - مكتبة الشروحات

الدعم

التصنيفات

Vintage Story Server Setup Guide