HxBlockerCMD

Lightweight Paper 1.21+ command blocker plugin with vanilla-style error messages, tab-completion hide, and optional LuckPerms integration.

Block, hide, and protect your server commands with a clean vanilla experience.

---

📋 Table of Contents

• Features
• Requirements
• Installation
• Configuration
  • Config.yml Full Breakdown
  • Title Settings
  • Sound Settings
  • Mode Settings
  • Blocked Commands
  • Bypass Groups
• Permissions
• Commands
• How It Works
  • Hide Mode
  • Block Mode
  • Bypass System
• LuckPerms Integration
• Vanilla Error Message
• FAQ & Troubleshooting
• Changelog
• License

---

✨ Features

• 🔒 Block Commands — Cancel blocked commands and show a vanilla-style error message (red, underlined, italic) that looks exactly like Minecraft's native "Unknown or incomplete command".
• 👁️ Hide from Tab — Remove blocked commands from the / suggestion list so players don't even know the command exists.
• 🔤 Tab-Complete Filter — Blocked commands won't appear in tab completion when typing.
• 🛡️ LuckPerms Support (Optional) — Group-based bypass via reflection (no hard dependency — plugin works perfectly without LuckPerms).
• 🎬 Title Effects — Show a configurable title + subtitle when a player tries to execute a blocked command.
• 🔊 Sound Effects — Play a configurable sound to alert the player.
• 🔄 In-Game Reload — /hxbc reload updates everything instantly without restarting the server.
• ⚡ Tab Refresh on Reload — Automatically calls player.updateCommands() so the tab suggestion list refreshes immediately after reload.
• 🔀 Namespace Support — Blocks namespaced commands like /bukkit:plugins, /minecraft:plugins, etc.

---

📋 Requirements

Requirement	Version	Notes
Server	Paper 1.21+	Also works on Purpur, Pufferfish, Folia (Paper forks)
Java	21+	Compiled with Java 21 release target
LuckPerms	5.4+	Optional — only needed for group bypass feature

⚠️ Not compatible with Spigot or Bukkit — this plugin uses Paper's Adventure API (MiniMessage, Components, Titles) which is not available in Spigot.

---

📥 Installation

1. Download the latest HxBlockerCMD.jar from the Releases page.
2. Drop the .jar file into your server's plugins/ folder.
3. Start your server (or restart if already running).
4. Edit plugins/HxBlockerCMD/config.yml to customize blocked commands and settings.
5. Run /hxbc reload in-game or restart the server to apply changes.

---

⚙️ Configuration

config.yml Full Breakdown

# ============================================
# HxBlockerCMD Configuration
# ============================================

# Enable or disable the entire plugin
enable: true

mode:
  # Hide blocked commands from tab suggestion (/ menu)
  # When true: players won't see blocked commands when pressing TAB or typing /
  # When false: commands still appear in tab but will be blocked when executed
  hide: true

  # Block execution of blocked commands
  # When true: executing a blocked command shows vanilla error + title + sound
  # When false: command is not blocked (only hide works if enabled above)
  block: true

# ============================================
# Title Settings
# ============================================
# Shown when a player tries to execute a blocked command
# Uses MiniMessage format for colors (https://docs.advntr.dev/minimessage/format.html)
title:
  # Main title text (supports MiniMessage & color codes)
  # Examples:
  #   text: '&c&lDamn'              → Red bold "Damn"
  #   text: '<red><bold>STOP!</bold>' → Red bold "STOP!"
  #   text: '<gradient:red:blue>Blocked</gradient>' → Gradient text
  text: '&c&lDamn'

  # Subtitle text (optional, leave empty '' for no subtitle)
  subtitle: ''

  # Title timing (in ticks, 1 tick = 50ms)
  # fade-in:  How long to fade in (5 ticks = 250ms)
  # stay:     How long to stay on screen (40 ticks = 2 seconds)
  # fade-out: How long to fade out (5 ticks = 250ms)
  fade-in: 5
  stay: 40
  fade-out: 5

# ============================================
# Sound Settings
# ============================================
# Sound played when a player tries a blocked command
# Must be a valid Bukkit Sound enum name (case-insensitive)
# Full list: https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Sound.html
#
# Popular choices:
#   ENTITY_ENDER_DRAGON_GROWL  → Deep dragon growl
#   BLOCK_NOTE_BLOCK_BASS      → Note block bass
#   ENTITY_VILLAGER_NO         → Villager disagree
#   BLOCK_ANVIL_LAND           → Anvil landing
#   ENTITY_GENERIC_EXPLODE     → Explosion
#   UI_BUTTON_CLICK            → Simple click
#
# Set to '' (empty) to disable sound
sound: ENTITY_ENDER_DRAGON_GROWL

# ============================================
# Bypass Groups (LuckPerms)
# ============================================
# Players in these LuckPerms groups will bypass ALL blocks
# Case-insensitive
# Requires LuckPerms to be installed
# If LuckPerms is not installed, this section is ignored
groups:
  - admin
  - moderator

# ============================================
# Blocked Commands List (Default)
# ============================================
# These commands are blocked/hidden by default.
# You can add more or remove some as needed.
#
# Format: write with or without leading slash (both work)
# Namespaced variants are auto-blocked:
#   If "plugins" is blocked, then /plugins, /bukkit:plugins, /minecraft:plugins are ALL blocked
#
commands:
  # Bukkit namespace variants
  - /bukkit:?
  - /bukkit:about
  - /bukkit:help
  - /bukkit:pl
  - /bukkit:plugins
  - /bukkit:ver
  - /bukkit:version

  # Minecraft namespace variants
  - /minecraft:help
  - /minecraft:me
  - /minecraft:msg
  - /minecraft:teammsg
  - /minecraft:tell
  - /minecraft:tm
  - /minecraft:trigger
  - /minecraft:w

  # Classic Bukkit memes
  - /icanhasbukkit

  # Base commands (these also catch /bukkit:xxx and /minecraft:xxx automatically)
  - /?
  - /pl
  - /plugins
  - /teammsg
  - /tm
  - /trigger
  - /ver
  - /version

---

Title Settings

When a player tries a blocked command, a title appears on their screen. You can customize:

Setting	Default	Description
title.text	&c&lDamn	Main title text. Supports MiniMessage tags and & color codes.
title.subtitle	''	Subtitle text. Leave empty for no subtitle.
title.fade-in	5	Fade-in duration in ticks (5 = 250ms).
title.stay	40	How long the title stays in ticks (40 = 2 seconds).
title.fade-out	5	Fade-out duration in ticks (5 = 250ms).

Color Code Reference (& format):

• &0-&f — Colors (black, dark blue, green, etc.)
• &l — Bold
• &n — Underlined
• &o — Italic
• &k — Obfuscated
• &r — Reset

MiniMessage Tags (advanced):

• <red>, <green>, <blue> — Named colors
• <bold>, <italic>, <underlined> — Decorations
• <gradient:red:blue>Text</gradient> — Gradient text
• <rainbow>Text</rainbow> — Rainbow text

---

Sound Settings

Setting	Default	Description
sound	ENTITY_ENDER_DRAGON_GROWL	Sound played when command is blocked.

How to find sounds:

1. Visit Bukkit Sound API
2. Pick any enum name (e.g., ENTITY_VILLAGER_NO)
3. Write it in config (case-insensitive, so entity_villager_no also works)

To disable sound: Set sound: '' (empty string)

Popular Sound Examples:

sound: ENTITY_ENDER_DRAGON_GROWL    # Deep scary growl
sound: BLOCK_NOTE_BLOCK_BASS         # Musical note
sound: ENTITY_VILLAGER_NO            # Villager "No" sound
sound: BLOCK_ANVIL_LAND             # Heavy anvil sound
sound: UI_BUTTON_CLICK               # Simple click (subtle)
sound: ''                            # No sound

---

Mode Settings

Mode	Default	What It Does
mode.hide	true	Hides blocked commands from the / tab suggestion menu. Players won't see them when pressing TAB or typing /.
mode.block	true	Actually blocks the command execution. Shows vanilla error message + title + sound.

Combinations:

• hide: true + block: true → Hide + block (recommended)
• hide: true + block: false → Hide only (command still works if typed manually)
• hide: false + block: true → Block only (command visible in tab but blocked when executed)
• hide: false + block: false → Plugin does nothing (why?)

---

Blocked Commands

Default blocked commands:

Command	Why It's Blocked	Also Blocks
/?	Bukkit help alias	—
/pl	Short for plugins	/bukkit:pl
/plugins	Lists server plugins	/bukkit:plugins
/ver	Short for version	/bukkit:ver
/version	Shows server version	/bukkit:version
/teammsg	Team message	/minecraft:teammsg, /tm
/tm	Short for teammsg	/minecraft:tm
/trigger	Scoreboard trigger	/minecraft:trigger
/icanhasbukkit	Bukkit easter egg	—
/bukkit:?	Bukkit help	/?
/bukkit:about	Bukkit about	—
/bukkit:help	Bukkit help	/help
/bukkit:pl	Bukkit plugins	/pl
/bukkit:plugins	Bukkit plugins	/plugins
/bukkit:ver	Bukkit version	/ver
/bukkit:version	Bukkit version	/version
/minecraft:help	Minecraft help	/help
/minecraft:me	Minecraft me	/me
/minecraft:msg	Minecraft msg	/msg, /tell, /w
/minecraft:teammsg	Minecraft teammsg	/teammsg, /tm
/minecraft:tell	Minecraft tell	/tell, /msg, /w
/minecraft:tm	Minecraft teammsg	/tm, /teammsg
/minecraft:trigger	Minecraft trigger	/trigger
/minecraft:w	Minecraft whisper	/w, /msg, /tell

How it works:

• Commands are stored without the leading /
• Example: - plugins in config blocks /plugins
• Namespaced commands are auto-detected:
  • If plugins is blocked → /plugins, /bukkit:plugins, /minecraft:plugins are ALL blocked
  • If trigger is blocked → /trigger, /minecraft:trigger are ALL blocked

Adding custom commands:

commands:
  - mysecretcommand      # blocks /mysecretcommand
  - warp                 # blocks /warp
  - home                 # blocks /home
  - tpa                  # blocks /tpa

Removing commands: Simply delete the line from the list and /hxbc reload.

💡 Tip: After removing a command from the list, run /hxbc reload and the command will instantly reappear in tab suggestions (thanks to updateCommands()).

---

Bypass Groups

If LuckPerms is installed, players in these groups will bypass ALL restrictions:

groups:
  - admin
  - moderator

How it checks:

1. Primary group (e.g., admin)
2. Inherited groups (e.g., player has default but inherits moderator)

Case-insensitive: Admin, ADMIN, admin are all treated the same.

Without LuckPerms: This section is silently ignored. Plugin still works 100%.

---

🔐 Permissions

Permission	Default	Description
hxblockercmd.admin	op	Access to /hxbc command (list, reload, author, version).
hxblockercmd.bypass	op	Bypass ALL blocked commands and hide restrictions. Player sees everything and can execute everything.

Who bypasses automatically?

1. OP players (player.isOp())
2. Players with hxblockercmd.bypass permission
3. Players in LuckPerms bypass groups (if LuckPerms installed)

⚠️ Deop alone is not enough if the player still has hxblockercmd.bypass permission or is in a bypass group. Use /lp user <name> permission unset hxblockercmd.bypass to remove.

---

🛠️ Commands

Command	Permission	Description
/hxbc	hxblockercmd.admin	Show help menu
/hxbc list	hxblockercmd.admin	Show all blocked commands
/hxbc author	hxblockercmd.admin	Show plugin author
/hxbc version	hxblockercmd.admin	Show plugin version
/hxbc reload	hxblockercmd.admin	Reload config without restart

Aliases: /hxblockercmd also works.

---

🔧 How It Works

Hide Mode

When mode.hide: true:

1. Player joins server → PlayerCommandSendEvent fires
2. Plugin checks: is player bypassed? (op / permission / group)
3. If NOT bypassed → remove blocked commands from the player's command list
4. Player never sees blocked commands in / tab menu

Important: PlayerCommandSendEvent only fires on join and when permissions change. That's why /hxbc reload calls player.updateCommands() to force a refresh.

Block Mode

When mode.block: true:

1. Player types /plugins → PlayerCommandPreprocessEvent fires
2. Plugin checks: is command blocked? (including namespaced variants)
3. If blocked AND player not bypassed:
   • Cancel the event (command doesn't execute)
   • Send vanilla-style error message (red, underlined, italic)
   • Show title (if configured)
   • Play sound (if configured)

Bypass System

Bypass priority (any one = bypass):

1. player.isOp()                        → OP status
2. hxblockercmd.bypass permission       → Explicit permission
3. LuckPerms group match                → Group bypass (optional)

---

🔗 LuckPerms Integration

Optional. Plugin uses reflection to interact with LuckPerms, so:

• ✅ No crash if LuckPerms is missing
• ✅ No hard dependency in plugin.yml
• ✅ Clean class loading

Setup:

1. Install LuckPerms on your server
2. Add bypass groups to config.yml:

   groups:
     - admin
     - moderator

3. /hxbc reload

How it works internally:

// Reflection-based group check (no direct LuckPerms imports)
Object userManager = luckPerms.getClass().getMethod("getUserManager").invoke(luckPerms);
Object user = userManager.getClass().getMethod("getUser", UUID.class).invoke(userManager, uuid);
String primaryGroup = (String) user.getClass().getMethod("getPrimaryGroup").invoke(user);

This ensures the plugin loads even when LuckPerms classes don't exist in the classpath.

---

💬 Vanilla Error Message

When a blocked command is executed, the player sees:

Unknown or incomplete command, see below for error
plugins<--[HERE]

Formatting:

• Unknown or incomplete command, see below for error → Red color
• plugins → Red + Underlined
• <--[HERE] → Red + Italic

This mimics Minecraft's native command parser error format exactly.

---

❓ FAQ & Troubleshooting

Q: I deopped myself but commands still work!

A: Check three things:

1. Do you still have hxblockercmd.bypass permission? → Remove it with LuckPerms or permission plugin.
2. Are you in a LuckPerms bypass group? → Check /lp user <you> info and remove from admin/moderator if listed in config.
3. Did you rejoin the server after deop? PlayerCommandSendEvent only refreshes on join or /hxbc reload.

Q: I removed a command from config but it still doesn't show in tab!

A: Run /hxbc reload. The plugin calls player.updateCommands() automatically on reload to refresh the tab list. If still not showing, rejoin the server.

Q: The plugin crashes on startup with "ClassNotFoundException: net/luckperms/api/model/group/Group"

A: This was a bug in v1. Fixed in v2.0.0. The current version uses reflection and works without LuckPerms. Update to the latest release.

Q: Can I use this on Spigot?

A: No. This plugin requires Paper (or Paper forks) because it uses the Adventure API (MiniMessage, Components, Titles). Spigot does not have Adventure built-in.

Q: Does this work on Folia?

A: Yes. The plugin does not use Bukkit schedulers or async tasks. All operations are event-based and run on the main thread, which is Folia-compatible.

Q: How do I disable the title/sound?

A:

• Disable title: set title.text: '' and title.subtitle: ''
• Disable sound: set sound: '' (empty string)

Q: Can I block commands from specific plugins only?

A: Yes. Add the namespaced variant:

commands:
  - essentials:home      # Only blocks /essentials:home, not /home from other plugins

Q: The error message shows my command but it's not underlined/italic!

A: Make sure your server is Paper 1.21+. MiniMessage (the formatting library) requires Paper. On older versions or Spigot, formatting will not work.

---

📝 Changelog

v2.0.0

• Fixed: Plugin crash when LuckPerms is not installed (reflection-based group check)
• Fixed: Namespaced commands (/bukkit:plugins, /minecraft:plugins) now properly blocked
• Fixed: Vanilla-style error message with underline + italic formatting using MiniMessage
• Fixed: Tab suggestion not updating after /hxbc reload (added player.updateCommands())
• Added: Auto tab refresh for all online players on reload
• Added: Full MiniMessage support for titles
• Improved: Better namespace handling in isBlocked()

---

📄 License

This project is licensed under the MIT License.

---

👤 Authors

• Lebynut - Development Studio
• handxt - Lead Developer

---

⭐ Support

If you find this plugin useful, consider starring the repository!

Issues & Bugs: GitHub Issues

Latest Release: Releases