-
Notifications
You must be signed in to change notification settings - Fork 0
Discord Integration
This document covers everything you need to set up and use the Discord integration feature included in the VSVanillaPlus mod for Vintage Story.
- Overview
- Setting Up a Discord Application
- Configuring the Mod
- All Configurable Options Reference
- Vintage Story Slash Commands
- Discord Slash Commands
- Account Linking — Full Walkthrough
- Player Group Channel Linking
- Troubleshooting
The Discord integration connects your Vintage Story server to a Discord server (guild). Once configured, it provides:
- Bidirectional chat relay — messages sent in VS global chat appear in a Discord channel, and messages sent in that Discord channel appear in VS chat.
- Identity-preserving relay — when a player has linked their Discord account, their VS chat messages are relayed to Discord under their own Discord display name and avatar (requires the bot to have the Manage Webhooks permission in the relay channel).
- Player group relay — link any VS player group to a dedicated Discord channel for group-specific chat.
- System notifications — Discord embeds for server start/shutdown, player join/leave, new players, and game-mode changes.
- Game event notifications — Discord embeds for player deaths, respawns, and temporal storm warnings.
- Discord slash commands — query player lists, in-game date, server info, broadcast announcements, and more — directly from Discord.
- Account linking — link a Discord account to a VS player account for cross-platform identity.
The bot runs entirely server-side. Clients do not need a Discord account. Only the server operator needs to configure it.
No prior Discord developer experience required. Follow these steps exactly and you will have a working bot at the end.
- Open your web browser and go to the Discord Developer Portal.
- Log in with your Discord account if prompted.
- Click the "New Application" button in the top-right corner.
- Enter a name for your application (e.g. "My VS Server Bot"). This is an internal label — it can be anything you like.
- Accept the Terms of Service and click "Create".
You will be taken to the General Information page for your new application.
- In the left-hand sidebar, click "Bot".
- Click the "Add Bot" button and confirm by clicking "Yes, do it!".
Your application now has a bot user attached to it. The bot's username will default to your application name — you can change it here if you wish.
Tip: You can also upload a custom avatar for your bot on this page.
The bot needs permission to read messages in channels (so it can relay Discord messages into VS chat). This is a Privileged Intent that must be manually enabled.
On the Bot page, scroll down to the "Privileged Gateway Intents" section and enable the following toggle:
- ✅ Message Content Intent — Required for the bot to read the content of messages sent in channels.
Leave all other intents at their defaults. Click "Save Changes".
Why is this needed? Discord requires bot developers to explicitly opt in to reading message content for privacy reasons. Without this intent, the Discord → VS chat relay will not work. See the Gateway Intents documentation for more detail.
The Bot Token is the password the mod uses to connect to Discord on behalf of your bot. It must be kept secret.
- On the Bot page, click the "Reset Token" button (you may need to confirm with 2FA if enabled).
- Click "Copy" to copy the token to your clipboard.
⚠️ Important: Never share your bot token with anyone. If it is ever exposed, click "Reset Token" immediately to invalidate it and generate a new one.
You will paste this token into the mod's settings panel in Step 6.
The bot must be a member of your Discord server before it can post messages or respond to slash commands.
- In the left-hand sidebar, click "OAuth2", then click "URL Generator".
- Under "Scopes", tick both:
- ✅
bot - ✅
applications.commands
- ✅
- Under "Bot Permissions" (which appears after ticking
bot), tick:- ✅
View Channels— Required to see and read the channels you configure. - ✅
Send Messages— Required to post chat relay messages and embed notifications. - ✅
Embed Links— Required for rich embed notifications (join/leave, server info, deaths, etc.). - ✅
Read Message History— Required to receive Discord messages for the chat relay. - ✅
Manage Webhooks— Required for identity-preserving relay. When a player has linked their Discord account, the bot uses a webhook to post their VS chat messages under their own Discord username and avatar. Without this permission the relay falls back to bot messages for all players (linked accounts included).
- ✅
Note on Manage Webhooks: This permission is scoped per-channel in Discord. If you grant it at the server level here in the URL Generator it applies server-wide, which is the simplest setup. Alternatively you can grant it only on the specific relay channel(s) after the bot has joined — the bot will report whether it has this permission in each channel when it connects.
- Scroll to the bottom and copy the generated URL.
- Paste the URL into your browser, select your Discord server from the dropdown, and click "Authorise".
The bot will now appear in your Discord server's member list (likely shown as offline until the mod connects it).
More detail: See the official Adding a Bot to Your Server guide in the Discord documentation.
You will need three pieces of information to configure the mod:
| Value | What it is | How to find it |
|---|---|---|
| Bot Token | The secret key for your bot | Copied in Step 4 |
| Guild (Server) ID | The unique ID of your Discord server | See below |
| Channel ID(s) | The unique ID(s) of the channel(s) you want to use | See below |
Discord hides IDs by default. You must enable Developer Mode to copy them:
- Open Discord and go to Settings (the gear icon near your username).
- Click "Advanced" in the left-hand sidebar.
- Toggle "Developer Mode" to ON.
Right-click on your server's icon in the left-hand server list and select "Copy Server ID".
Right-click on the text channel you want to use (e.g. #general) and select "Copy Channel ID".
Repeat this for each channel you intend to configure (chat relay, system notifications, game events).
- Join your Vintage Story server (or start a single-player world with the mod active).
- Open the pause menu (press Escape).
- Click "VSVP Settings".
- Click the "Discord" button.
Note: The Discord settings panel requires the
controlserverprivilege on the server. Regular players will see an access-denied message. On a single-player world, you are always the operator.
Click the "Server Settings..." button inside the Discord settings panel to open the server configuration sub-dialog.
| Field | Description |
|---|---|
| Bot Token | Your bot's secret token (leave blank to keep the existing token). |
| Guild (Server) ID | The numeric ID of your Discord server. |
| Chat Relay Channel ID | The channel ID where VS ↔ Discord general chat is relayed. |
| System Channel ID | The channel ID for system notifications (join/leave/startup/shutdown). Set to 0 to use the Chat Relay Channel. |
| Game Event Channel ID | The channel ID for game-event notifications (deaths, respawns, storms). Set to 0 to use the Chat Relay Channel. |
| Public Server Address | The address displayed in the server-info embed (e.g. play.example.com:42420). Optional. |
| Ephemeral Slash Command Responses | When ON, slash command responses are only visible to the person who ran the command. Default: ON. |
| Auto-Register Slash Commands on Connect | When ON, slash commands are automatically registered with Discord each time the bot connects. Default: OFF. |
After filling in all fields, click "Save Server Settings". Then use the "Connect" button to start the bot.
Manual slash command registration: If Auto-Register Slash Commands is OFF, click "Register Commands" in the main Discord settings panel after connecting the bot. This needs to be done at least once (or after adding new commands).
These settings are visible to all players with access to the settings panel and are shared server-wide.
| Setting | Description | Default |
|---|---|---|
| Enable Chat Relay | Relay VS global chat to Discord and Discord messages to VS chat. | ON |
| Discord Chat Colour (hex) | The colour (hex code without #) used to format Discord messages when they appear in VS chat. |
7289DA (Discord Blurple) |
Click "Event Notifications..." to open the event configuration sub-dialog.
| Setting | Description | Default |
|---|---|---|
| Game Event Notifications | Master toggle for all in-game event notifications: player deaths, respawns, and temporal storms. | ON |
| Setting | Description | Default |
|---|---|---|
| Server Starting | Send a notification when the server begins starting up. | ON |
| Server Ready | Send a server info embed when the server is open for connections. | ON |
| Server Shutdown | Send a notification when the server is shutting down. | ON |
| New Player | Send a notification when a brand-new player joins for the first time. | ON |
| Player Join | Send a notification when a player joins the server. | ON |
| Player Leave | Send a notification when a player leaves the server. | ON |
| Game Mode Change | Send a notification when a player changes their game mode. | ON |
This section is a complete reference for every configurable option in the Discord feature, including server-only settings stored in vsvanillaplus_discord.json.
| Option | Type | Default | Description |
|---|---|---|---|
EnableChatRelay |
bool | true |
Relay VS global chat ↔ Discord chat relay channel. |
DiscordChatColor |
string (hex) | 7289DA |
Hex colour for Discord messages displayed in VS chat. |
ShowGameEvents |
bool | true |
Master toggle for player death, respawn, and temporal storm notifications. |
ShowSystemEventServerStart |
bool | true |
Notify Discord when the server is starting. |
ShowSystemEventServerReady |
bool | true |
Send a server info embed when the server is ready for players. |
ShowSystemEventServerShutdown |
bool | true |
Notify Discord when the server is shutting down. |
ShowSystemEventPlayerCreate |
bool | true |
Notify Discord when a first-time player joins. |
ShowSystemEventPlayerJoin |
bool | true |
Notify Discord when a player joins. |
ShowSystemEventPlayerLeave |
bool | true |
Notify Discord when a player leaves. |
ShowSystemEventGameMode |
bool | true |
Notify Discord when a player changes their game mode. |
⚠️ This file lives on the server and is never sent to clients. It contains your bot token — keep it secure.
| Option | Type | Default | Description |
|---|---|---|---|
BotToken |
string | null |
Your Discord bot token. Required to connect. |
GuildId |
ulong | 0 |
The Discord server (guild) ID the bot operates in. |
ChatRelayChannelId |
ulong | 0 |
Channel ID for bidirectional VS ↔ Discord chat relay. |
ChatRelayWebhookId |
ulong | 0 |
Webhook ID for the main relay channel. Populated automatically by the bot on first connect (if it has Manage Webhooks). Do not edit manually. |
ChatRelayWebhookToken |
string | "" |
Webhook token for the main relay channel. Populated automatically. Do not edit manually. |
SystemChannelId |
ulong | 0 |
Channel ID for system notifications. Falls back to ChatRelayChannelId if 0. |
GameEventChannelId |
ulong | 0 |
Channel ID for game event notifications. Falls back to ChatRelayChannelId if 0. |
ServerAddress |
string | "" |
Public server address shown in the server-info embed (e.g. play.example.com:42420). |
UseEphemeralResponses |
bool | true |
When true, slash command responses are only visible to the invoker. |
AutoRegisterSlashCommands |
bool | false |
Automatically register guild slash commands each time the bot connects. |
ModerationRoles |
list of ulong | null |
Discord Role IDs whose members can use moderation slash commands (/announce, /shutdown). Server administrators always have these permissions. |
GroupChannelMappings |
dictionary | {} |
VS player group ↔ Discord channel connections. Each entry also stores a WebhookId and WebhookToken populated automatically for identity-preserving relay. Managed via the /dcchannel in-game command. |
LinkedAccounts |
dictionary | null |
VS player UID ↔ Discord user ID links. Managed via /auth (Discord) and /dclink (in-game). |
These commands are typed in the in-game chat. They are prefixed with /.
Description: Links your Vintage Story player account to your Discord account. This is the second step of the account-linking process — the first step is running /auth connect in Discord to generate a token.
Required Privilege: chat (all players have this by default)
Syntax:
/dclink <token>
| Parameter | Description |
|---|---|
token |
The 8-character uppercase token generated by the Discord /auth connect command. |
Examples:
/dclink A1B2C3D4
Notes:
- The token is single-use and expires when the server restarts. If you miss the window, run
/auth connectin Discord again to get a new token. - Once linked, your Discord account is associated with your VS player UID server-side. This enables messages to post as your Discord Username, and allows you to use Discord-linked features like Player Group chat relay.
- See Account Linking — Full Walkthrough for the complete two-step process.
Description: Manages bidirectional chat relay between Vintage Story player groups and Discord channels. Sub-commands allow connecting, disconnecting, and customising the display colour for each group-channel pair.
Required Privilege: manageotherplayergroups (server operators / admins)
Description: Link a VS player group to a Discord channel. Messages sent in the group chat will be relayed to the Discord channel, and messages sent in that Discord channel will appear in the VS group chat.
Syntax:
/dcchannel connect <group_name> <discord_channel_id>
| Parameter | Description |
|---|---|
group_name |
The exact name of the VS player group (case-sensitive). |
discord_channel_id |
The numeric Discord channel ID to relay to. |
Example:
/dcchannel connect Adventurers 1234567890123456789
Notes:
- The Discord bot must be connected before running this command.
- The bot must have access to the specified Discord channel.
- A group can only be linked to one channel at a time. Disconnect first before re-linking.
Description: Remove the link between a VS player group and its Discord channel.
Syntax:
/dcchannel disconnect <group_name>
| Parameter | Description |
|---|---|
group_name |
The exact name of the VS player group to disconnect. |
Example:
/dcchannel disconnect Adventurers
Description: Change the colour used to display Discord messages in the VS player group chat.
Syntax:
/dcchannel color <group_name> <hex_color_code>
| Parameter | Description |
|---|---|
group_name |
The exact name of the VS player group. |
hex_color_code |
A 3 or 6 character hex colour code, with or without a leading # (e.g. 7289DA or #FF5500). |
Examples:
/dcchannel color Adventurers 7289DA
/dcchannel color Adventurers #FF5500
/dcchannel color Adventurers FFF
Notes:
- The group must already be linked to a Discord channel before setting a colour.
- The default colour is
7289DA(Discord Blurple).
These commands are run inside Discord using the / command interface. They interact with your Vintage Story server in real time.
How to use Discord slash commands: In any text channel on your Discord server, type
/followed by the command name. Discord will show an autocomplete menu — select the command and fill in any required options before pressing Enter.
Prerequisites: Slash commands must be registered before they can be used. Enable "Auto-Register Slash Commands on Connect" in the server settings, or click "Register Commands" in the mod's Discord settings panel after connecting the bot.
Description: Lists the players currently online on the Vintage Story server.
Syntax:
/players [ping: true/false]
| Option | Required | Description |
|---|---|---|
ping |
No | If set to true, each player's current network ping (in milliseconds) is shown next to their name. |
Examples:
/players
/players ping:true
Example output (no ping):
Steve
Alex
Notch
Example output (with ping):
Steve (42ms)
Alex (118ms)
Notch (7ms)
If no players are online, the response will be:
No players are currently online.
Permissions: Available to all Discord server members.
Description: Displays the current in-game date and time.
Syntax:
/date
Example output:
15th of Harvest, Year 3
Permissions: Available to all Discord server members.
Description: Shows the game version and a list of all mods currently loaded on the server.
Syntax:
/serverinfo
Example output:
Vintage Story 1.21.0
Loaded Mods:
VSVanillaPlus v1.2.0 | Universal
SomeOtherMod v0.5.1 | Server
...
Notes:
- If many mods are loaded, the response may be split into multiple follow-up messages to stay within Discord's character limit.
Permissions: Available to all Discord server members.
Description: Broadcasts a message to all players currently in the Vintage Story server. Only players with moderation permission can use this command.
Syntax:
/announce message:<text> show:<true/false> [color:<color>]
| Option | Required | Description |
|---|---|---|
message |
Yes | The text to broadcast to all players in-game. |
show |
Yes | If true, the message is also echoed back to the Discord channel (visible to everyone). If false, only you see the confirmation. |
color |
No | The colour of the text as displayed in VS chat. Choose from: Orange, Red, Yellow, Green, Blue, White, Gold. Defaults to Orange. |
Examples:
/announce message:Server restart in 10 minutes! show:true color:Red
/announce message:Welcome to the server! show:false color:Green
/announce message:Treasure hunt starting at spawn! show:true
Notes:
-
@hereand@everyoneare automatically neutralised to prevent abuse. - HTML-like tags (
<and>) are escaped before being sent in-game. - All announcements are logged to the server audit log.
Permissions: Discord server Administrator, or a member of one of the configured Moderation Roles (set in vsvanillaplus_discord.json).
Description: Gracefully shuts down the Vintage Story server. Requires confirmation via an interactive button to prevent accidental shutdowns.
Syntax:
/shutdown
After running the command, a confirmation prompt will appear with a "Confirm Shutdown" button. Only click this if you are sure — the server will begin shutting down immediately.
Example flow:
- You type
/shutdown. - The bot responds: "Are you sure you want to shut down the server?" with a red Confirm Shutdown button.
- You click the button.
- The bot responds: "Server is shutting down." and the server begins its shutdown sequence.
Permissions: Discord server Administrator, or a member of one of the configured Moderation Roles.
Description: Sets the chat relay channel directly from Discord, without needing to open the in-game settings panel. The channel you run this command in (or the channel you select) becomes the new chat relay channel.
Syntax:
/setchannel channel:<#channel>
| Option | Required | Description |
|---|---|---|
channel |
Yes | The Discord text channel to use as the chat relay channel. Select it using the # channel picker. |
Example:
/setchannel channel:#vintage-story-chat
Example output:
Chat relay channel set to #vintage-story-chat.
Notes:
- This command updates the same setting as "Chat Relay Channel ID" in the Server Settings panel.
- The change takes effect immediately — no bot restart is required.
Permissions: Discord server Administrator only.
Description: Links or unlinks your Discord account to your Vintage Story player account. Linking enables cross-platform account features and is required for Player Group relay attribution.
Syntax:
/auth mode:<connect|disconnect>
| Option | Required | Description |
|---|---|---|
mode |
Yes |
connect to begin the linking process; disconnect to remove an existing link. |
/auth mode:connect
Example output:
Run /dclink A1B2C3D4 in-game to complete linking. The token expires when the server restarts.
You must then log into Vintage Story and run /dclink A1B2C3D4 (using your specific token) in the in-game chat. See Account Linking — Full Walkthrough.
/auth mode:disconnect
Example output:
Your accounts have been unlinked.
Permissions: Available to all Discord server members.
Account linking ties your Discord identity to your Vintage Story player account on the server. Here is the full process from start to finish:
-
In Discord, run the following slash command in any channel on your server:
/auth mode:connect - The bot will respond with a unique 8-character token (e.g.
A1B2C3D4). This response is ephemeral (only visible to you) if ephemeral responses are enabled. -
In Vintage Story, open the chat (press
TorEnter) and type:Replace/dclink A1B2C3D4A1B2C3D4with your actual token from the previous step. - If the token is valid, you will see a success message in VS chat confirming that your accounts are now linked.
To unlink your accounts, run /auth mode:disconnect in Discord at any time.
Important: The linking token is generated fresh each time and expires when the server restarts. If you do not complete the
/dclinkstep before a restart, simply run/auth mode:connectin Discord again to get a new token.
Once your accounts are linked, your VS chat messages are relayed to Discord under your own Discord display name and avatar — the message appears to come from you directly, not from the bot. Players without a linked account continue to be relayed as a plain bot message (**PlayerName:** ...).
This feature relies on a Discord webhook in the relay channel. The bot creates the webhook automatically on first connect, provided it has the Manage Webhooks permission in that channel. If the permission is missing, the server log will show a warning and all players will fall back to bot messages until the permission is granted and the bot is reconnected.
You can bridge a Vintage Story player group to a dedicated Discord text channel, allowing group members to communicate with Discord users and vice versa. This is separate from the global chat relay.
Setup steps:
- Ensure the Discord bot is connected.
- In VS chat (as an operator), run:
/dcchannel connect <group_name> <discord_channel_id> - Messages sent in the VS player group chat will appear in the Discord channel, and messages sent in that Discord channel will appear in the VS group chat.
Customise the display colour for messages from Discord in VS group chat:
/dcchannel color <group_name> <hex_color>
Remove the link:
/dcchannel disconnect <group_name>
Finding the Channel ID: Right-click the Discord channel and select "Copy Channel ID" (requires Developer Mode — see Step 6).
| Problem | Solution |
|---|---|
| Bot appears offline / "Disconnected" in the settings panel | Check that the Bot Token is correct and that the token has not been reset in the Developer Portal. Click "Connect" in the settings panel. |
| "No players are currently online" even when players are online | The bot may have lost its connection. Open the settings panel and check the status indicator. If disconnected, click "Connect". |
| Discord messages don't appear in VS chat | Ensure Enable Chat Relay is ON, the Chat Relay Channel ID is correct, and the bot has Send Messages and View Channel permissions in that channel. |
| VS chat messages don't appear in Discord | Check that the Message Content Intent is enabled in the Discord Developer Portal (see Step 3). |
| Linked players' messages still appear as bot messages (not as themselves) | The bot lacks the Manage Webhooks permission in the relay channel. Grant it in Discord (Channel Settings → Permissions, or re-invite the bot with the permission via the URL Generator), then reconnect the bot. A webhook will be created automatically on the next connect and the server log will confirm it. |
| Linked players' messages suddenly stopped appearing as themselves | The webhook was likely deleted manually in Discord. Open Channel Settings → Integrations → Webhooks and check if the VSVP Chat Relay webhook is present. If it was deleted, you can either recreate it manually and update ChatRelayWebhookId / ChatRelayWebhookToken in vsvanillaplus_discord.json, or simply reset both values to 0 / "" and reconnect the bot — it will create a new one automatically (requires Manage Webhooks). |
| Slash commands don't show up in Discord | Click "Register Commands" in the mod settings panel, or enable Auto-Register Slash Commands on Connect and reconnect the bot. Note: Discord can take up to an hour to propagate new commands globally. Guild commands are instant. |
"You do not have permission to do that" on /announce or /shutdown |
Your Discord account does not have the Administrator permission and is not in any of the configured Moderation Roles. Ask a server admin to add your role to ModerationRoles in the server secrets file. |
| "/dclink" says "Invalid or expired token" | The token expires on server restart. Run /auth mode:connect in Discord again to generate a fresh token, then use /dclink in-game immediately. |
| "Discord channel ID is invalid or not accessible by the bot" | The bot is not in the channel or lacks permissions to see it. Ensure the bot has View Channel permission for that channel. |
| Settings panel shows "Access Denied" | You do not have the controlserver privilege on the server. This panel is for server operators only. |
| Settings panel shows "Failed to retrieve information from the server" | The server did not respond within 8 seconds. Close the panel and try opening it again. If the problem persists, check your connection. |