Add Your Own Checks

HackedServer’s detection system is fully configurable through the generic.toml file. You can add custom checks to detect any client or mod that sends plugin messages.

Understanding Plugin Messages

Minecraft clients communicate with servers through plugin message channels. Modified clients and mods often register custom channels or send specific data through standard channels. HackedServer intercepts these messages to detect what clients are being used.

Check Structure

Each check in generic.toml follows this structure:


[check_id]
name = "Display Name"
channels = ["channel1", "minecraft:channel2"]
message_has = "optional_filter"
actions = ["alert"]

Properties Explained

Property	Required	Description
`check_id`	Yes	Unique identifier (use snake_case)
`name`	Yes	Name displayed in alerts and commands
`channels`	Yes	List of plugin message channels to monitor
`message_has`	No	Only trigger if message contains this text (case-insensitive)
`actions`	Yes	List of action IDs from `actions.toml` to execute

Example: Detecting a Custom Client

Let’s say you want to detect a hypothetical client called “ExampleClient” that sends messages on the channel example:main:


[example_client]
name = "ExampleClient"
channels = ["example:main"]
actions = ["alert"]

With Message Filtering

If the client sends multiple message types on the same channel, you can filter by content:


[example_client]
name = "ExampleClient"
channels = ["example:main"]
message_has = "client_hello"
actions = ["alert"]

Example: Detecting via MC|Brand

Many clients identify themselves through the MC|Brand or minecraft:brand channel. Here’s how to detect a client by its brand string:


[custom_brand_client]
name = "Custom Client"
channels = ["MC|Brand", "minecraft:brand"]
message_has = "customclient"
actions = ["alert"]

The message_has filter is case-insensitive. “customclient” will match “CustomClient”, “CUSTOMCLIENT”, etc.

Detecting Mods via REGISTER Channel

Mods often announce their presence by registering channels. You can detect this:


[custom_mod]
name = "Custom Mod"
channels = ["REGISTER", "minecraft:register"]
message_has = "custommod"
actions = ["alert"]

Creating Custom Actions

Before referencing an action, define it in actions.toml:


# Silent logging - just alert staff
[silent_log]
send_alert = "<gray>[LOG] <yellow><player> <gray>is using <yellow><name>"
[silent_log.commands]
console = []
player = []
opped_player = []
 
# Kick the player
[kick]
send_alert = "<red><player> <gray>was kicked for using <red><name>"
[kick.commands]
console = ["kick <player> This client/mod is not allowed!"]
player = []
opped_player = []
 
# Ban the player
[ban]
send_alert = "<dark_red><player> <gray>was banned for using <dark_red><name>"
[ban.commands]
console = ["ban <player> Using forbidden modifications"]
player = []
opped_player = []

Then reference these actions in your checks:


[whitelisted_mod]
name = "Allowed Mod"
channels = ["allowed:channel"]
actions = ["silent_log"]
 
[blacklisted_client]
name = "Hacked Client"
channels = ["hacked:channel"]
actions = ["kick", "silent_log"]

Finding Channels with Debug Mode

To discover what channels a client uses:

Enable debug mode in config.toml:


[settings]
debug = true

Reload the plugin: /hs reload
Have a player join with the client you want to detect
Check the console for debug messages showing all plugin messages:


HS-Debug | PlayerName channel: "example:channel", message: "example_data"

Use this information to create your check

Remember to disable debug mode in production! It generates a lot of console output.

Multiple Channels Per Check

A single check can monitor multiple channels. The check triggers if a message is received on ANY of the listed channels:


[multi_channel_mod]
name = "Multi-Channel Mod"
channels = [
    "mod:channel1",
    "mod:channel2",
    "mod:legacy"
]
actions = ["alert"]

Multiple Actions Per Check

Checks can trigger multiple actions simultaneously:


[dangerous_client]
name = "Dangerous Client"
channels = ["danger:main"]
actions = ["alert", "kick", "log_to_discord"]

This will execute all listed actions when the client is detected.

Complete Example

Here’s a complete example adding detection for a fictional mod ecosystem:

actions.toml:


[modpack_alert]
send_alert = "<green><player> <gray>joined with approved modpack: <green><name>"
[modpack_alert.commands]
console = []
player = []
opped_player = []
 
[unapproved_mod]
send_alert = "<red><player> <gray>has unapproved mod: <red><name>"
[unapproved_mod.commands]
console = ["kick <player> Please remove unapproved mods"]
player = []
opped_player = []

generic.toml:


enabled = true
 
# Approved mods
[approved_modpack]
name = "Server Modpack"
channels = ["modpack:verify"]
message_has = "approved_v2"
actions = ["modpack_alert"]
 
# Unapproved mods
[cheat_mod_x]
name = "CheatMod X"
channels = ["MC|Brand", "minecraft:brand"]
message_has = "cheatmod"
actions = ["unapproved_mod"]
 
[exploit_mod]
name = "Exploit Mod"
channels = ["exploit:main", "REGISTER"]
message_has = "exploitmod"
actions = ["unapproved_mod"]

Tips for Writing Checks

Use specific channel names when possible for accurate detection
Use message_has filters to avoid false positives on shared channels
Test with debug mode to verify your checks work correctly
Start with alert action before adding punishment actions
Document your custom checks with comments in the TOML file

For more detailed examples and community-contributed checks, check the HackedServer GitHub repository .