Installation#

Viscord is a server-side mod. Install it on the dedicated server; never on clients. Two players on the same server do not need matching jars, and a vanilla client connects normally.

Pick the jar for your cell#

Nine lane directories produce thirteen jars. Each release asset is named viscord-<minecraft>-<loader>-<version>.jar. Download exactly one.

Load the server with the Java major version in the last column. The 1.18.2, 1.19.2, and 1.20.1 lanes compile with --release 17; 1.21.1 uses 21; the 26.x lanes declare java_version=25 and the Fabric metadata requires java >=25. A too-old JVM fails at class-load time with an UnsupportedClassVersionError before Viscord logs anything.

Install#

1. Stop the server.
2. Drop the single matching jar into the server's mods/ directory.
3. Add the matching Architectury API jar to mods/ if it is not already there.
4. Start the server once and let it reach the point where it would accept players, then stop it.

First boot creates the config directory and file:

<server>/config/viscord/viscord.toml

The file is generated with general.enabled = false, so nothing connects on that first boot. That is intentional: the file has to exist before you can fill in a token, and writing a token into a config the mod has not yet validated is how people end up with a half-configured bot. Stop the server before editing.

If the file does not appear, the server process could not create config/viscord/ — see Troubleshooting.

Verify the download#

Every release publishes a SHA256SUMS file next to the jars. Check the jar you downloaded before it goes anywhere near a server.

curl -LO https://github.com/Vonix-Network/Viscord-Architectury/releases/download/v5.2.1/viscord-1.21.1-neoforge-5.2.1.jar
curl -LO https://github.com/Vonix-Network/Viscord-Architectury/releases/download/v5.2.1/SHA256SUMS
sha256sum -c SHA256SUMS --ignore-missing

A good download prints OK for the jar you fetched:

viscord-1.21.1-neoforge-5.2.1.jar: OK

A FAILED line means the file is corrupt or was tampered with. Delete it and download again. Do not skip this on a jar that will hold a bot token.

Minimal working config#

This is the smallest viscord.toml that bridges Minecraft chat to one Discord channel. Every value below is a placeholder — replace them with your own. Never paste a real token into a support thread.

[general]
enabled  = true
platform = "discord"

[discord]
bot_token   = "YOUR_BOT_TOKEN_HERE"
channel_id  = "123456789012345678"
webhook_url = "https://discord.com/api/webhooks/123456789012345678/YOUR_WEBHOOK_TOKEN_HERE"

[server]
prefix = "[MC]"
name   = "My Server"

What each line does:

• general.enabled is the master switch. With it false, Viscord initialises nothing and logs Disabled in config.
• general.platform selects discord, fluxer, or both.
• discord.bot_token connects the gateway so Viscord can read the channel.
• discord.channel_id is the channel Viscord watches and posts to. Accepts a comma-separated list.
• discord.webhook_url is how Minecraft messages get per-player names and avatars. Leave it empty and Minecraft chat is silently dropped on the way out — the bot reads the channel but never writes chat to it.
• server.prefix is the tag that identifies this server in a shared channel, and it also feeds the echo-loop guard.

Restart, or run /viscord reload as an op-4 operator, then say something in game. With everything above correct the line appears in Discord under the player's name, and a Discord message appears in game as [Discord] username: message.

Files Viscord writes#

Two of those names differ from older documentation. The link map is viscord-links.json and the preference map is viscord-preferences.json, both resolved against the same config/viscord/ directory. If you are backing up account bindings, back up viscord-links.json.