# Discord Viper (ViperBridge) ViperBridge is a high-performance, **server-side only** bidirectional gateway bridging **Minecraft**, **Discord**, and **REST APIs**. No client mods required - vanilla players connect normally. ## What the mod does **Chat relay** - Two-way chat between a Discord channel and in-game chat, plus rich embed alerts for joins, leaves, deaths (with the real death reason), advancements (real announcements only, no recipe spam), and server start/stop. **45 Discord commands** - Every command works as a native slash `/command` and as a `!prefix` command. All slash replies are private (ephemeral): only the person who ran the command sees the answer. **Moderation system** - Kick, ban, IP-ban, timed tempbans with automatic pardon (survives restarts), server-side mutes, numbered warnings, pardons, kick-all, and ban/whitelist lists. Mutes, warnings, and tempbans persist in `viperbridge_punishments.json`. **Player lookups** - Online players read live; offline players read their saved player data: coordinates, slot-accurate inventory grids, cracked-vs-premium profile checks with skin renders, and last-seen times. **Per-command permissions** - Each command has its own Discord roles/users/Minecraft-player allowlist, on/off switch, and Discord client visibility flag. `/help` only lists commands the requester may use. **Account linking** - Players link Discord and Minecraft accounts with a one-time code (`/link` in Discord, `/viperbridge link

` in game). Links power per-player permissions and work with cracked (offline-mode) accounts.

**Extras** - Console forwarding to Discord in ~1000-character chunks with IPs spoiler-masked, live player-count channel, bot presence, and a bearer-token REST API (health, players, player info, remote commands).

## Command list

| Slash | Prefix | Default access | Description |
|-------|--------|---------------|-------------|
| `/help` | `!help` | Authorized | Show only the commands you may use |
| `/players` | `!players` | Authorized | List online players with ping |
| `/player ` | `!player ` | Authorized | Health, hunger, XP, gamemode, IP, inventory |
| `/coords ` | `!coords ` | Authorized | Dimension + XYZ, online or from saved data |
| `/inventory ` | `!inventory ` | Authorized | Slot-accurate grid: armor, offhand, hotbar, main |
| `/profile ` | `!profile ` | Authorized | Cracked/premium check, skin avatar, link status |
| `/skin ` | `!skin ` | Authorized | Full-body skin render |
| `/link ` | `!link ` | Everyone | Start linking, code delivered by DM |
| `/unlink` | `!unlink` | Authorized | Remove your account link |
| `/kick  [reason]` | `!kick  [reason]` | Authorized | Kick a player |
| `/ban  [reason]` | `!ban  [reason]` | Authorized | Ban a player |
| `/ipban  [reason]` | `!ipban  [reason]` | Authorized | IP-ban a player |
| `/tempban   [reason]` | `!tempban   [reason]` | Authorized | Timed ban, auto-pardon (30s/10m/2h/7d) |
| `/mute  [dur]` | `!mute  [dur]` | Authorized | Block chat + commands (empty = forever) |
| `/unmute ` | `!unmute ` | Authorized | Remove a mute |
| `/mutes` | `!mutes` | Authorized | Muted players with remaining time |
| `/warn  [reason]` | `!warn  [reason]` | Authorized | Numbered warning, player notified in game |
| `/warnings ` | `!warnings ` | Authorized | Show a player's warnings |
| `/clearwarns ` | `!clearwarns ` | Authorized | Clear a player's warnings |
| `/pardon ` | `!pardon ` | Authorized | Unban a player |
| `/pardonip ` | `!pardonip ` | Authorized | Unban an IP address |
| `/kickall [reason]` | `!kickall [reason]` | Authorized | Kick every online player |
| `/banlist` | `!banlist` | Authorized | Banned players with reasons |
| `/kill ` | `!kill ` | Authorized | Kill a player (must be online) |
| `/say ` | `!say ` | Authorized | Broadcast to all players |
| `/command ` | `!cmd ` | Authorized | Execute any Minecraft command |
| `/stop` | `!stop` | Authorized | Stop the server |
| `/op ` | `!op ` | Authorized | Grant operator status |
| `/deop ` | `!deop ` | Authorized | Remove operator status |
| `/whitelist  [name]` | `!whitelist  [name]` | Authorized | add/remove/on/off/list the whitelist |
| `/gamemode  [player]` | `!gamemode  [player]` | Authorized | Change gamemode |
| `/give   [count]` | `!give   [count]` | Authorized | Give items |
| `/tp  ` | `!tp  ` | Authorized | Teleport to a player or coordinates |
| `/heal ` | `!heal ` | Authorized | Restore health (must be online) |
| `/feed ` | `!feed ` | Authorized | Restore hunger (must be online) |
| `/seen ` | `!seen ` | Authorized | Last-online time (or online now) |
| `/time ` | `!time ` | Authorized | day/noon/night/midnight/ticks |
| `/weather  [sec]` | `!weather  [sec]` | Authorized | clear/rain/thunder |
| `/save` | `!save` | Authorized | Save all worlds to disk |
| `/status` | `!status` | Authorized | Players, uptime, memory, ticks overview |
| `/uptime` | `!uptime` | Authorized | Server uptime |
| `/tps` | `!tps` | Authorized | Tick info |
| `/memory` | `!memory` | Authorized | RAM usage |
| `/seed` | `!seed` | Authorized | World seed |
| `/ping` | `!ping` | Authorized | Bot latency |
| `/effect   [sec] [lvl]` | `!effect   [sec] [lvl]` | Authorized | Give a status effect |
| `/clear  [item]` | `!clear  [item]` | Authorized | Clear inventory |
| `/difficulty ` | `!difficulty ` | Authorized | peaceful/easy/normal/hard |
| `/gamerule  [value]` | `!gamerule  [value]` | Authorized | Set or query a gamerule |
| `/spawnpoint  [x y z]` | `!spawnpoint  [x y z]` | Authorized | Set spawn point |
| `/setworldspawn [x y z]` | `!setworldspawn [x y z]` | Authorized | Set world spawn |
| `/defaultgamemode ` | `!defaultgamemode ` | Authorized | Default gamemode |
| `/sudo  ` | `!sudo  ` | Authorized | Run a command as a player |

In-game commands: `/viperbridge reload` (reload config), `/viperbridge status`, `/viperbridge discord reconnect`, `/viperbridge link ` (usable by every player, no OP needed).

## Configuration

Edit `world/viperbridge/viperbridge.json` after first launch (reload in game with `/viperbridge reload`).

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `discordBotToken` | string | `""` | Discord bot token from the Developer Portal. Required. |
| `discordGuildId` | string | `""` | Discord server ID. Enables instant slash-command registration and role features. |
| `channels.chatRelayChannelId` | string | `""` | Chat relay + prefix-command channel. |
| `channels.consoleForwardChannelId` | string | `""` | Server console output channel. |
| `channels.liveStatusChannelId` | string | `""` | Channel renamed with the live player count. |
| `webApi.enabled` | boolean | `false` | Enable the REST API. |
| `webApi.port` | number | `8080` | REST API port. |
| `webApi.apiSecretToken` | string | `""` | Bearer token for REST API auth. |
| `forwardConsole` | boolean | `true` | Master switch for console forwarding. |
| `privacyMode` | boolean | `false` | Full IP redaction, offline coords/inventory blocked, REST IPs hidden. |
| `directRoleSync.syncEnabled` | boolean | `false` | Sync Discord roles to MC teams. |
| `directRoleSync.mappings` | object | `{}` | Discord role ID to MC team mappings. |
| `commandPrefix` | string | `"!"` | Prefix for text commands. |
| `enableDiscordCommands` | boolean | `true` | Master switch for Discord commands. |
| `allowedRoles` | string[] | `[]` | Global Discord role IDs allowed to use commands. |
| `allowedUsers` | string[] | `[]` | Global Discord user IDs allowed to use commands. |
| `botActivityText` | string | `"online players"` | Bot status text (`%count%`, `%max%` placeholders). |
| `linkCodeExpiryMinutes` | number | `10` | How long link codes stay valid. |
| `commandPermissions..enabled` | boolean | `true` | Per-command on/off switch. |
| `commandPermissions..roles` | string[] | `[]` | Discord role IDs allowed for this command. |
| `commandPermissions..users` | string[] | `[]` | Discord user IDs allowed for this command. |
| `commandPermissions..players` | string[] | `[]` | Minecraft usernames allowed (matched via linked accounts). |
| `commandPermissions..minPermission` | string | `"NONE"` | Discord-side slash visibility: NONE, KICK_MEMBERS, BAN_MEMBERS, MODERATE_MEMBERS, MANAGE_SERVER, ADMINISTRATOR. |
| `commandPermissions..open` | boolean | `false` | Anyone may use the command (`link` is open by default). |

Checks run in order per command: `open`, then `players` (linked MC name), then command `roles`/`users`, then the global fallback. Denied attempts get a private error visible only to the requester.

Note: the 1.21.x build uses numeric channel/guild IDs and an extra `discordInviteLink` field; everything else is identical.

## Privacy mode

Set `"privacyMode": true` to lock the mod down: every IP in Discord output (console, player lookups) is fully redacted instead of spoiler-masked, REST API IP fields return `"hidden"`, and `coords`/`inventory` refuse offline-player lookups (online players still work). Public chat relay and announcements are unaffected.

## REST API

Auth header: `Authorization: Bearer `.

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| GET | `/api/health` | Optional | Status, player count, ticks |
| GET | `/api/players` | Required | All online players with stats |
| GET | `/api/player/{name}` | Required | Single player info |
| POST | `/api/command` | Required | Run a command: `{"command": "say hello"}` |

## Installation

1. Install **Fabric Loader** (0.16.x+ for 1.21.x, 0.17.x+ for 26.x) and **Fabric API** on your server.
2. Download the JAR matching your Minecraft version (1.21.x, 26.1.x, 26.2.x, or 26.3) and drop it into the server `mods` folder.
3. Start the server once so `world/viperbridge/viperbridge.json` is created, then stop it.
4. Edit the config: set `discordBotToken`, the channel IDs under `channels`, and command permissions.
5. In the Discord Developer Portal, enable **MESSAGE CONTENT INTENT** and **SERVER MEMBERS INTENT**, then invite the bot.
6. Restart the server.

Discord Viper

Compatibility

Minecraft: Java Edition

Platforms

Supported environments

Links

Tags

Creators

Details