ViperBridge

ViperBridge is a high-performance, server-side only bidirectional gateway bridging Minecraft, Discord, and REST APIs for Minecraft 1.21.x, 26.1.x, and 26.2.x. Chat relay, moderation commands from Discord, player info queries, and full server control -- no client mods required.

Supported Versions

Purpose and Function

The core mission of this project is to give server administrators total control over their server through Discord and REST API integration.

• Bridge Chat: Minecraft <-> Discord chat relay in real time with rich embeds and colored formatting.
• Moderation From Discord: Kick, ban, and IP-ban players directly from your Discord server using simple commands.
• Player Info on Demand: Query player health, hunger, XP, inventory, IP, and ping from Discord or the REST API.
• Execute Any Command: Run any Minecraft command remotely via Discord or the REST API -- no console access needed.
• Private by Default: IPs in console output are spoiler-masked, and every Discord command has its own role/user allowlist.

Key Features

Discord Commands

Commands work two ways: classic prefix commands (!... in the chatRelayChannelId channel) and native Discord slash commands (/... anywhere -- the bot registers them automatically on startup; instant when discordGuildId is set, otherwise global registration can take up to an hour to appear).

Per-Command Permissions

Every command has its own entry in commandPermissions:

• enabled -- set false to disable that command completely.
• roles / users -- Discord role IDs / user IDs allowed to use it. When both lists are empty, the global allowedRoles / allowedUsers lists apply instead. Example: moderators get kick and players, only admins get stop and command.
• minPermission -- controls who sees the slash command in the Discord client: NONE (everyone), KICK_MEMBERS, BAN_MEMBERS, MODERATE_MEMBERS, MANAGE_SERVER, MANAGE_CHANNELS, ADMINISTRATOR. Members without it will not see that slash command. Runtime checks still apply to everyone.
• /help only lists the commands the requester may actually use, and denied attempts reply with a private (ephemeral) error that only the requester sees.

Example -- moderators can kick and look up players, but only admins can stop the server or run raw commands:

"commandPermissions": {
  "players": { "enabled": true, "roles": ["moderator-role-id"], "users": [], "minPermission": "NONE" },
  "player":  { "enabled": true, "roles": ["moderator-role-id"], "users": [], "minPermission": "NONE" },
  "kick":    { "enabled": true, "roles": ["moderator-role-id"], "users": [], "minPermission": "KICK_MEMBERS" },
  "ban":     { "enabled": true, "roles": ["admin-role-id"], "users": [], "minPermission": "BAN_MEMBERS" },
  "stop":    { "enabled": true, "roles": ["admin-role-id"], "users": [], "minPermission": "ADMINISTRATOR" },
  "command": { "enabled": true, "roles": [], "users": ["owner-user-id"], "minPermission": "ADMINISTRATOR" }
}

Omitted commands fall back to defaults (enabled, global allowlists, visible to everyone).

Set "open": true on a command to let everyone use it without any role (used by default for link). minPermission only affects slash-command visibility in the Discord client; role/user lists are always enforced by the bot at runtime.

Each command also accepts a players list of Minecraft usernames. Anyone whose linked account matches (case-insensitive) may use that command -- useful when moderators don't share a single Discord role:

"kick": { "enabled": true, "roles": [], "users": [], "players": ["Steve", "Alex"], "minPermission": "NONE", "open": false }

Checks run in order: open, then players (via linked account), then command-specific roles/users, then the global allowedRoles/allowedUsers fallback.

Punishments

Mutes, warnings, and tempbans persist in viperbridge_punishments.json (Fabric config folder) across restarts.

• mute blocks the player's chat messages and chat-sent commands server-wide; /viperbridge link is always allowed through so mutes can't lock anyone out of linking. Durations use 30s / 10m / 2h / 7d format, empty means forever.
• tempban bans immediately and pardons automatically when the timer ends, including timers that span a server restart.
• warn numbers each warning and notifies the player in game; warnings and clearwarns manage the record.

Account Linking

Links a Discord user to a Minecraft account. The link record (Discord ID, Discord name, MC UUID, MC name) is stored for future features such as Discord-based display names.

1. In Discord, run /link <mcname> (open to everyone). The bot replies with a 6-character code.
2. In game, run /viperbridge link <code> as that Minecraft account.
3. The code expires after linkCodeExpiryMinutes (default 10) and is single-use. A wrong MC name is rejected with a hint.
4. /unlink removes the link. /profile <name> shows the linked Discord tag.

"linkCodeExpiryMinutes": 10,
"commandPermissions": {
  "link":   { "enabled": true, "roles": [], "users": [], "minPermission": "NONE", "open": true },
  "unlink": { "enabled": true, "roles": [], "users": [], "minPermission": "NONE", "open": false }
}

IP Masking

Every IPv4 address forwarded to the console Discord channel is wrapped in spoiler tags, so it stays hidden until clicked. This covers log lines (for example Player[/127.0.0.1:62790] logged in) and the IP field of /player lookups. No configuration needed.

REST API Endpoints

Auth header: Authorization: Bearer <apiSecretToken>

Configuration

Edit world/viperbridge/viperbridge.json after first launch:

{
  "discordBotToken": "YOUR_BOT_TOKEN",
  "discordGuildId": "your-guild-id",
  "channels": {
    "chatRelayChannelId": "channel-id",
    "consoleForwardChannelId": "channel-id",
    "liveStatusChannelId": "channel-id"
  },
  "webApi": {
    "enabled": false,
    "port": 8080,
    "apiSecretToken": "your-secret"
  },
  "commandPrefix": "!",
  "enableDiscordCommands": true,
  "allowedRoles": ["role-id-1", "role-id-2"],
  "allowedUsers": ["user-id-1"],
  "botActivityText": "%count%/%max% players online",
  "linkCodeExpiryMinutes": 10,
  "commandPermissions": {
    "help":    { "enabled": true, "roles": [], "users": [], "minPermission": "NONE", "open": false },
    "players": { "enabled": true, "roles": [], "users": [], "minPermission": "NONE", "open": false },
    "stop":    { "enabled": true, "roles": ["admin-role-id"], "users": [], "minPermission": "ADMINISTRATOR", "open": false }
  }
}

Hot-reload config in-game: /viperbridge reload

Installation

1. Drop the JAR into your server's mods/ folder
2. Install Fabric Loader (0.16.x+ for 1.21.x, 0.17.x+ for 26.x)
3. Install Fabric API (required on all versions)
4. Start the server -- config auto-creates at world/viperbridge/viperbridge.json
5. Edit the config with your Discord bot token and channel IDs
6. Enable MESSAGE CONTENT INTENT and SERVER MEMBERS INTENT in the Discord Developer Portal
7. Restart the server

Built for administrators who demand seamless Discord-Minecraft integration with zero client overhead. Every message, command, and query flows through secure, authorized channels.