A service that connects multiple Hypixel guilds and Discord servers together. This project is made to be fully flexible and customisable, offering a high quality user experience while keeping it simple.
DISCLAIMER: This project interacts with Hypixel in an unintended way by simulating a minecraft client and by processing packets which might get you banned if over-abused too much.
Just like any other modification and service that interacts with Hypixel servers, this goes without saying: "Use at your own risk"
Breaking changes:
config.yaml
has been reformatted. Check the new config_example.yaml
and compare it with the old config file.config.yaml
. Only enable one instance when using websocket../configs/
to save its state as a file. The ./configs/
directory is now git-ignored./list
- lists online members and their current game modeName | 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 |
/connectivity |
Send an echo to all Minecraft instances to check status | Anyone |
/about |
Display basic info about the client | Anyone |
/promote & /demote & /setrank |
Equivalent to /guild promote/demote/setrank |
Helper |
/invite & /accept |
Equivalent to /guild invite/accept |
Helper |
/reconnect |
Reconnect an in-game instance to Hypixel | Helper |
/punishments |
Equivalent to /guild mute/unmute/kick . Can also ban |
Helper/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 on/off | Anyone |
Join/Leave | Member joins/leaves the guild | Anyone |
Promote/Demote | Member promoted/demoted in the guild | Anyone |
Request | Member requesting to join the guild | Anyone |
Quest | Guild quest milestone reached | Anyone |
Repeat | Warn about "can't repeat message" when writing from a Discord channel |
Anyone |
Block | Warn about a Discord user saying something that breaks Hypixel's rules | Anyone |
Kick | Notify when someone is kicked from the guild | Public |
Mute / Unmute | Notify when someone gets muted in the guild | Helper |
These commands can be executed from any chat channel the bridge can see.
This includes guild/officer chat as well as private /msg
and direct messaging channels.
Most Soopy commands are supported and can be used by executing !soopy rtca
.
A shorter version can also be used: !- rtca
Command | Description | Permission |
---|---|---|
!8ball | Replica of 8 ball.!8ball Will I win? |
Anyone |
!bits | Returns the best bit items to purchase for the most profit | Anyone" |
!calculate | Calculate a math expression: !calculate 1+2*3 |
Anyone |
!catacomb | Get a player's catacombs and class level | Anyone |
!darkauction | Show the remaining time till next dark auction | Anyone |
!explain | Explain what the bridge does and how it works | Anyone |
!guild | Give a summary of the guild of a given user | Anyone |
!help | Show a command usage !help runs |
Anyone |
!iq | Give a random IQ number to the guild member | Anyone |
!kuudra | Get a player's kuudra completions !kuudra hot |
Anyone |
!level | Get a player's skyblock level | Anyone |
!networth | Calculate the in-game networth of a player | Anyone |
!rps | Play rock paper scissors !rps rock |
Anyone |
!roulette | Has a chance of muting a player | Anyone |
!runs | Return a plauer's floor completions !runs m7 |
Anyone |
!rtca | Return runs count to reach an average class level | Anyone |
!secrets | Return a player's total dungeon secrets | Anyone |
!skill | Return player's skill level !skill mining |
Anyone |
!slayer | Return a player's slayer stats !slayer wolf |
Anyone |
!soopy | Use Soopy API to execute commands !- purse |
Anyone |
!weight | Calculate the Senither Weight of a player | Anyone |
!toggle | Enable/disable commands !toggle 8ball |
Officer |
!override | Run a command directly !overide /guild party |
Admin |
Application has an official public API and supports custom plugins to enhance potential.
Loaded plugins can be configured in the config.yaml
file when configuring the app.
To create custom plugins see Documentation And Tutorials.
These are the supported official plugins that come bundled with the application:
Plugin | Description | Importance | Notice |
---|---|---|---|
auto-restart | Schedule restarting every 24 hours | Essential | A process monitor is required to restart the application after it shuts down. Not periodically restarting can lead to high RAM usage. |
limbo-plugin | Forces Minecraft client to stay in Hypixel limbo | Essential | Being outside of limbo for prolonged periods can lead to the account being banned. Only disable if required. |
punishment-plugin | Enforces punishments and prevents punishment evasion | Recommended | Plugin will mute users but won't ban them, instead it will send a notification in officer chat. |
warp-plugin | Warp players out of their lobbies | Quality of Life | Incompatible with limbo-plugin . Disable one before enabling the other one. |
reaction-plugin | Send a greeting/reaction message when a member joins/leaves or is kicked from the guild | Quality of Life | N/A |
dark-auction | Send a reminder when a skyblock dark auction is starting | Quality of Life | Sends a reminder 5 minutes and 1 minute before the dark auction. |
starfall-cult | Send a reminder when the skyblock starfall cult gathers | Quality of Life | N/A |
Note: Only the one person who has administrator permissions can execute commands!
From In-game: /gc !override /guild party
From Discord: /override /guild party
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 periodic execution of /guild list |
name : Guild name |
In-game periodic command execution for metrics are disabled by default. Automatically sending commands non-stop to Hypixel might get the client banned for blatant automation. Although the chance is next to none, it is disabled for safe measures.
Metrics can be directly used from the Prometheus server by querying it 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 configs.
Here are examples of Prometheus queries and their results displayed using Grafana:
sum(increase(guild_bridge_chat[1h])) by (scope,location)
increase(guild_bridge_guild_exp_total[10m])
guild_bridge_guild_members_online
Nodejs
)Clone and download the complete project by using Git
tool:
git clone https://github.com/aidn3/hypixel-guild-discord-bridge
Alternatively, download the source code directly without any revisions. (Updating the service will be difficult)
.config_example.yaml
into config.yaml
config.yaml
and fill in the information (Security: config.yaml
contains sensitive information. Keep it safe!)config.yaml
fill out general.hypixelApiKey
and discord
and minecraft.instances
config.yaml
to fine tune the bridgeInstall dependencies and libraries by executing the command:
npm install
New dictionary node_modules
will be generated containing all required files.
Start the service by executing command:
npm start
Alternatively, Docker image is available to use at GitHub Container Service. Image is usually up to date.
To start, first prepare the configuration as instructed in this section. Then execute:
sudo docker container run -it --rm -v ./config.yaml:/app/config.yaml ghcr.io/aidn3/hypixel-guild-discord-bridge:latest
Note that the path of the configuration source file must either be relative (with the ./
) or absolute.
Alternatively, providing the path as an argument to the docker container is also possible:
sudo docker container run -it --rm -v ./config.yaml:/config/config.yaml ghcr.io/aidn3/hypixel-guild-discord-bridge:latest /config/config.yaml
This 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, the bridge can be divided into smaller parts and be hosted on different servers
and all be connected via sockets.
When to use cluster mode:
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).
All configurations will be in config.yaml
under socket
section.
enabled
to true.key
. (Security: Anyone can hijack the bridge if it is easily guessable)type
uri
to the server node socket to connect to