Vintage Story

In-Game Vintage Story server lister

Vintage Story

Vintage Story is a voxel-based wilderness survival game written in C#.

Server listing protocol

For a server to get listed, all Vintage Story servers need to first register on the server list and then periodically send a heartbeat HTTP request. Clients will then retrieve the server list. This all happens through HTTP endpoints. A re-implementation of the masterserver made in Python is available on GitHub:

https://github.com/CDWimmer/VintageStoryMasterServer

(HTTP POST) Register server

Endpoint: https://masterserver.vintagestory.at/api/v1/servers/register

Sample JSON payload:

{
    "port":42424,
    "name":"My cool vintage story server",
    "icon":"",
    "playstyle":{
        "id":"surviveandbuild",
        "langCode":"preset-surviveandbuild"
    },
    "maxPlayers":48,
    "gameVersion":"1.20.3",
    "hasPassword":false,
    "Mods":[
        {
            "id":"signs",
            "version":"1.0.2"
        },
        [ ... ]
    ],
    "serverUrl":"https://lolcat.ca",
    "gameDescription":"Some description here",
    "whitelisted":true
}

The gameDescription attribute can contain basic HTML markup like <h1> tags and links.
Sample successful response:

{
    "data": "server-token-here",
    "status": "ok"
}

The server token consists of 32 random bytes encoded as base64.
Sample bad response from the server:

{
    "status": "bad",
    "data": "port not opened"
}

If you have any deduction skills, you will see that in order to get listed, you need to host a Vintage Story server on the same host the request is originating from before attempting to create a list entry.

(HTTP POST) Heartbeat request

https://masterserver.vintagestory.at/api/v1/servers/heartbeat

Sample JSON payload:

{
    "token": "your-token-here",
    "players": 500
}

Sample successful response:

{
    "status": "ok"
}

Sample bad response from the server:

{
    "status": "timeout",
    "data": "timeout"
}

When the masterserver replies with a timeout response, the Vintage Story server should re-register their server.

(HTTP GET) View server list

https://masterserver.vintagestory.at/api/v1/servers/list

Sample JSON response:

{
    "status": "ok",
    "data": {
        [
            "serverName": "Vintage Story Server",
            "serverIP": "1.1.1.1:25209",
            "playstyle": {
                "id": "surviveandbuild",
                "langCode": "preset-surviveandbuild"
            },
            "mods": {
                [
                    "id": "primitivesurvival",
                    "version": "3.7.5"
                ],
                [ ... ]
            }
            "maxPlayers": "16",
            "players": 10,
            "gameVersion": "1.20.1",
            "hasPassword": false,
            "whitelisted": true,
            "gameDescription": "Some description here"
        ],
        [ ... ]
    }
}