Disclaimer: This project interacts with Hypixel in an unintended way by simulating a minecraft client and processes packets which might get you banned if you over-abuse it too much.
Just like any other modification and service that interacts with Hypixel servers, this goes without saying: "Use at your own risk"
- Connect multiple guilds chats together
- Bind hypixel guilds chats to discord channels
- Send and receive Chat from other guilds/discord servers via Webhooks
- Supports Public and Officer Chat
- Supports in-game moderation commands from discord
- Share events with discord such as online/offline/join/leave/mute notification/etc.
- Allows executing commands
- Logs all Chats/Events/etc
- Quality Of Life such as
/listcommand listing online members and their current game-mode - Provides a detailed metrics for every instance
- Supports custom plugins
- Supports Proxies for Minecraft instances
| Name | Description |
|---|---|
| Anyone | Anything that usually can be seen in-game guild chat e.g. Public Chat, Join/Leave Notification, etc |
| Helper | Anything that requires special permission to see in-game guild chat e.g. Officer Chat, Mute notification, etc. |
| Officer | Superset of Helper role. Given to trusted members |
| Admin | Special Permission that is used to administrate the service. Note: Only ONE person can have this permission! |
| Command | Description | Permission |
|---|---|---|
/ping |
Show Discord response latency | Anyone |
/list |
List all online members and their current game-mode | Anyone |
/about |
Display basic info about the client | Anyone |
/promote & /demote & /setrank |
Equivalent to /guild promote/demote/setrank |
Helper |
/mute & /unmute |
Equivalent to /guild mute/unmute |
Helper |
/invite & /accept |
Equivalent to /guild invite/accept |
Helper |
/reconnect |
Reconnect an in-game instance | Helper |
/kick |
Equivalent to /guild kick |
Officer |
/restart |
Restart the entire bridge service | Admin |
/override |
Send direct commands to all minecraft clients | Admin |
| Event | Description | Who can see it |
|---|---|---|
| Online/Offline | Member logging in/off | Anyone |
| Join/Leave | Member joins/leaves the guild | Anyone |
| Request | Member requesting to join the guild | Anyone |
| Repeat | Warn about "can't repeat message" when writing from discord channel |
Anyone |
| Block | Warn about discord user saying something that breaks Hypixel rules | Anyone |
| Kick | Notify when someone is kicked from the guild | Public |
| Mute / Unmute | Notify when someone gets muted in the guild | Helper |
| Command | Description | Permission |
|---|---|---|
| !explain | Explain what the bridge does and how it works | Anyone |
| !fact | Give a random fun fact about the guild members | Anyone |
| !calculate | Calculate a math expression: !calculate 1+2*3 |
Anyone |
| !8ball | Replica of 8 ball.!8ball Will I win? |
Anyone |
| !iq | Give a random IQ number to the guild member | Anyone |
| !weight | Calculate Senither Weights of players | Anyone |
| !networth | Calculate the in-game networth of players | Anyone |
| !guild | Give a summary of the guild for a given user | Anyone |
| !roulette | Has a 1 in 6 chance of muting a member | Anyone |
| !rps | Play rock paper scissors !rps rock |
Anyone |
| !kuudra | Get a player's kuudra completions !kuudra hot |
Anyone |
| !skill | Returns player's skill level !skill mining |
Anyone |
| !runs | Returns dungeon floor completions !runs m7 |
Anyone |
| !secrets | Returns a player's total dungeon secrets | Anyone |
| !slayer | Returns a player's slayer stats !slayer wolf |
Anyone |
Note: Only the one person who holds administrator permission can execute command!
From In-game: /msg username /guild party
From Discord: /override /guild party
"Webhooks can send messages to a text channel without having to log in as a bot."
It is used if the targeted community isn't within the admins' jurisdiction.
Used to avoid giving any account login information (e.g. password, tokens, etc.) or running the cluster in one server.
To receive messages, you need to
- Create a Discord webhook in the used guild public chat channel
- Register the webhook id in
config.yaml(messages will be filtered otherwise) - Give the FULL webhook id to the targeted community to send messages through
- Receive the full webhook url
- Register it in
config.yaml(messages won't be sent over otherwise)
It is best to exchange both send and receive keys and set up a two-way road for both community.
config.yaml Supports name for each community.
hypixel-guild-discord-bridge supports Prometheus metrics, and it is
enabled by default on port 9095.
Many metrics are automatically collected in memory and await prometheus to scrap them.
These are the currently monitored metrics. No usernames or anything personal is monitored. All metrics have the default
prefix guild_bridge_. It can be changed in config.yaml under metrics.
| Metric | Description | Source | metadata |
|---|---|---|---|
PREFIX_guild_exp_total |
Guild total experience | Hypixel API /guild end point |
name: Guild name |
PREFIX_guild_exp_game |
Guild experience per game | Hypixel API /guild end point |
name: Guild name, type: game type |
PREFIX_guild_members |
Guild members count | Hypixel API /guild end point |
name: Guild name |
PREFIX_chat |
Messages count of all Chat | In-game guild chat/discord bot | location: discord, webhook, in-game.scope: private, officer, public chat.instance: name of the source registered in config.yaml |
PREFIX_command |
Commands usage count | Discord commands interactions and in-game chat commands | Same as chat metrics + command: command name |
PREFIX_event |
Events count | Discord server events and in-game chat | same as chat metrics + event: event name (e.g. offline, join, mute, etc.) |
PREFIX_guild_members_online |
Guild current online members | In-game interval execution of /guild list |
name: Guild name |
All metrics config are in ./config/metrics-config.json.
In-game interval commands execution for metrics are disabled by default. Automatically sending commands non-stop to Hypixel might get the client banned for "botting". Although the chance is next to non-existent, it is disabled for safe measures.
Metrics can directly be used from Prometheus server by querying directly. However, to visualise the data, another server is required to do the job. Grafana is one of the most popular and easy to use out there. Many tutorials exist on the internet showcasing Grafana setups and settings.
Here are examples of Prometheus query and their results displayed using Grafana:
- Guild Chat:
sum(increase(guild_bridge_chat[1h])) by (scope,location)
- Guild Total Experience:
increase(guild_bridge_guild_exp_total[10m])
- Guild Current Online Members:
guild_bridge_guild_members_online
- Nodejs version 1.16 or later
- npm (usually installed by default with
Nodejs) - Minecraft Alt Account
- (Optional) Git
Clone and download the complete project by using Git tool:
git clone https://github.com/aidn3/hypixel-guild-discord-bridgeAlternatively, download the source code directly without any revisions. (Updating the service will be difficult)
- Explore the project files and duplicate
.config_example.yamlfile intoconfig.yaml - Open
config.yamland fill the information (Security:config.yamlfile is like a password. Keep it safe!) - In
config.yamlfill outgeneral/hypixelApiKeyanddiscordandminecraft/instances - (Optional) for Advanced users only: Edit other options in
config.yamlto fine tune the bridge
Install dependencies and libraries by executing the command:
npm installNew dictionary node_modules will be generated containing all required files.
Start the service by executing command:
npm startThis section is for advanced users who wish to run a bridge that supports thousands of online players with dozens of connected guilds.
Bridge supports cluster mode. That means, bridge can be divided into smaller parts and be hosted on different servers
and all be connected together via sockets.
When to use cluster mode:
- If more than 2 Minecraft accounts are connected from same host server. Hypixel will IP "nuke" ban all accounts for " compromised account"
- If a Minecraft account owner wishes to hold the login details by hosting a part of the bridge on their server
Each node supports two modes: client and server.
Only one Server can exist and all Clients will connect to it (Server must also not be behind a firewall).
- Server mode is just an extension of Client mode. It supports instances as well as discord bridge and minecraft bots
- Server's goal is to only forward all events and data and distribute it to all clients
- Server will not wait for client to reconnect when forwarding events. Clients however will wait to re-sync with server
All configurations will be in config.yaml under socket section.
- Follow Setup process for each node, but don't start them yet
- set config
enabledto true. - Choose a secure password in config and set it under
key. (Security: Anyone can hijack the bridge if not set to a secure one) - Choose which node to become the "Server" and set it under config
type - Name each node under config
instanceName(Warning: Duplicate names might result in race condition or other odd behaviors) - Set the config
urito the server node socket to connect to - Start all nodes
- The Project is a duplicate of hypixel-discord-chat-bridge by Senither.
- Aura#5051 for in-game commands: Calculate, 8ball, IQ, Networth, Weight, Bitches