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

Version	Java	Status
1.21.x	21	Supported
26.1.x	25	Supported
26.2.x	25	Supported

---

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

Feature	Description	Default
Chat Relay	Bidirectional chat between Discord and Minecraft	ON
Join/Leave Alerts	Embed notifications when players join/leave	ON
Death Messages	Death announcements with embeds and death reason	ON
Advancement Alerts	Announced advancement completions only (no recipe spam)	ON
Server Start/Stop	Embeds posted when the server starts/stops	ON
Discord Moderation	Kick, ban, IP-ban from Discord	OFF
Player List	List online players with ping from Discord	ON
Player Info	Health, hunger, XP, IP, inventory via Discord	ON
Coords Lookup	Dimension + coordinates for online and offline players	ON
Inventory View	Visual slot grid (armor, offhand, hotbar, main), online and offline	ON
Profile Check	Cracked vs premium detection, skin avatar, link status	ON
Skin Render	Full-body skin image	ON
Account Linking	Code-based Discord/MC linking (/link + /viperbridge link <code>)	ON
Admin Commands	op/deop, whitelist, pardon, gamemode, give, tp via Discord	OFF
Player Care	heal, feed, last-seen lookup via Discord	ON
World Commands	time, weather, save via Discord	ON
Server Status	One-embed overview (players, uptime, memory, ticks)	ON
Tempbans	Timed bans with automatic pardon, survive restarts	ON
Mutes	Block muted players' chat and commands (link command always allowed)	ON
Warnings	Numbered warnings per player, viewable and clearable	ON
Broadcast	Send server-wide messages from Discord	ON
Remote Stop	Stop the server from Discord	OFF
Custom Commands	Execute any MC command from Discord	OFF
Uptime	Check server uptime from Discord	ON
Performance	Server ticks and uptime info	ON
Memory	RAM usage stats	ON
World Seed	Get world seed from Discord	ON
Bot Ping	Discord bot latency	ON
Bot Presence	Shows online player count in bot status (auto-updates)	ON
Console Forwarding	Server console to Discord, ~1000-char chunks, IPs spoiler-masked	OFF
IP Masking	All IPs in console output hidden behind click-to-reveal spoilers	ON
Per-Command Permissions	Each command has its own roles/users/enabled flag	ON
Slash Visibility	Slash commands hidden in Discord UI by Discord permission flag	--
REST API	Health, players, player info, command execution	OFF
Rich Embeds	Colored Discord embeds for all events	ON

---

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).

Slash	Prefix	Default Access	Description
/help	!help	Authorized	Show only the commands you may use
/players	!players	Authorized	List online players with ping
/player <name>	!player <name>	Authorized	Player health, hunger, XP, gamemode, IP, inventory
/kick <name> [reason]	!kick <name> [reason]	Authorized	Kick a player from the server
/ban <name> [reason]	!ban <name> [reason]	Authorized	Ban a player
/ipban <name> [reason]	!ipban <name> [reason]	Authorized	IP ban a player
/say <message>	!say <message>	Authorized	Broadcast a message to all players
/command <command>	!cmd <command>	Authorized	Execute any Minecraft command
/stop	!stop	Authorized	Stop the Minecraft server
/uptime	!uptime	Authorized	Show server uptime
/tps	!tps	Authorized	Server ticks and uptime info
/memory	!memory	Authorized	RAM usage statistics
/seed	!seed	Authorized	Display the world seed
/ping	!ping	Authorized	Discord bot latency
/status	!status	Authorized	Combined overview: players, uptime, memory, ticks
/seen <name>	!seen <name>	Authorized	When a player was last online (or online now)
/coords <name>	!coords <name>	Authorized	Player dimension + XYZ, online or offline (reads saved player data)
/whitelist <action> [name]	!whitelist <action> [name]	Authorized	add/remove/on/off/list the server whitelist
/op <name>	!op <name>	Authorized	Give operator status
/deop <name>	!deop <name>	Authorized	Remove operator status
/pardon <name>	!pardon <name>	Authorized	Unban a player
/pardonip <ip>	!pardonip <ip>	Authorized	Unban an IP address
/gamemode <mode> [player]	!gamemode <mode> [player]	Authorized	Change gamemode
/give <player> <item> [count]	!give <player> <item> [count]	Authorized	Give items
/tp <player> <target>	!tp <player> <target>	Authorized	Teleport to a player or coordinates
/kill <name>	!kill <name>	Authorized	Kill a player (must be online)
/heal <name>	!heal <name>	Authorized	Restore health (must be online)
/feed <name>	!feed <name>	Authorized	Restore hunger (must be online)
/time <value>	!time <value>	Authorized	Set world time (day/noon/night/midnight/ticks)
/weather <type> [sec]	!weather <type> [sec]	Authorized	Set weather (clear/rain/thunder)
/save	!save	Authorized	Save all worlds to disk
/tempban <name> <dur> [reason]	!tempban <name> <dur> [reason]	Authorized	Ban with auto-pardon (durations like 30s, 10m, 2h, 7d)
/mute <name> [dur]	!mute <name> [dur]	Authorized	Mute chat + commands (no duration = forever)
/unmute <name>	!unmute <name>	Authorized	Remove a mute
/mutes	!mutes	Authorized	List muted players with remaining time
/warn <name> [reason]	!warn <name> [reason]	Authorized	Warn a player (warns accumulate, player is notified)
/warnings <name>	!warnings <name>	Authorized	Show a player's warnings
/clearwarns <name>	!clearwarns <name>	Authorized	Clear a player's warnings
/kickall [reason]	!kickall [reason]	Authorized	Kick every online player
/banlist	!banlist	Authorized	List banned players with reasons
/inventory <name>	!inventory <name>	Authorized	Slot-accurate inventory grid (armor, offhand, hotbar, main)
/profile <name>	!profile <name>	Authorized	Cracked/premium check, skin avatar, status, UUID, linked Discord
/skin <name>	!skin <name>	Authorized	Full-body skin render
/link <mcname>	!link <mcname>	Everyone (open)	Start account linking, returns a one-time code
/unlink	!unlink	Authorized	Remove your Discord/MC account link

---

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

Method	Endpoint	Auth	Description
GET	/api/health	Optional	Server status, player count, tick count
GET	/api/players	Required	All online players with full stats
GET	/api/player/{name}	Required	Single player health, hunger, XP, IP, inventory
POST	/api/command	Required	Execute any MC command {"command": "say hello"}

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.