🎮 BubbleCommand v2.0

---

📖 Overview

BubbleCommand is a powerful yet incredibly simple Spigot/Paper/Purpur plugin that lets you create custom commands using just a config file. Perfect for server owners who want to add custom functionality without writing a single line of code!

✨ Why BubbleCommand?

• 🎯 Zero Coding Required - Everything is done through a simple config file
• 🚀 Super Easy to Use - Copy, paste, edit. Done!
• 💪 Production Ready - Battle-tested with comprehensive error handling
• 🔥 Feature Rich - Cooldowns, multi-actions, permissions, placeholders, and more
• 📚 Well Documented - Tons of examples included in the config
• 🔧 Highly Flexible - Create any command you can imagine
• ⚡ Performance Optimized - Minimal server impact
• 🎨 Modern Design - Beautiful messages with color codes and titles

---

🌟 Features

Core Features

• ✅ Custom Commands - Create unlimited custom commands
• ✅ Command Aliases - Add multiple aliases to any command
• ✅ Multi-Action Support - Execute multiple actions per command
• ✅ Permission System - Control who can use each command
• ✅ Cooldown System - Prevent command spam with per-command cooldowns
• ✅ Player-Only Option - Restrict commands to players only
• ✅ Console Commands - Run commands with console permissions
• ✅ Hot Reload - Reload config without restarting the server

Action Types

• 🎮 Console Commands - Execute commands as console
• 👤 Player Commands - Execute commands as player
• 💬 Messages - Send colored messages to players
• 📢 Broadcasts - Broadcast messages to all online players
• 🔊 Sounds - Play sounds to players
• 📺 Titles - Display titles and subtitles
• 📱 Actionbar - Show actionbar messages

Placeholders

• %player% - Player's name
• %displayname% - Player's display name
• %uuid% - Player's UUID
• %world% - Player's current world
• %x%, %y%, %z% - Player's coordinates
• %health% - Player's health
• %food% - Player's food level
• %level% - Player's level
• %exp% - Player's experience
• %gamemode% - Player's gamemode
• %sender% - Command sender's name
• %arg0%, %arg1%, etc. - Command arguments
• %args% - All arguments joined

---

📦 Installation

Requirements

• Minecraft Server: 1.19+ (Spigot, Paper, Purpur, or any fork)
• Java: 17 or higher

Steps

1. Download the latest BubbleCommand-x.x.x.jar

2. Place the JAR file in your server's plugins folder

3. Restart your server

4. Configure your custom commands in plugins/BubbleCommand/config.yml

5. Reload with /bubblecommand reload (or restart)

That's it! 🎉

---

🚀 Quick Start

For the SUPER Lazy (30 seconds setup)

1. Open plugins/BubbleCommand/config.yml
2. Find the heal: command example
3. Remove the # at the start of each line to uncomment it
4. Run /bubblecommand reload in-game
5. Use /heal command!

For the Slightly Less Lazy (2 minutes setup)

Copy this template and add it to your config:

custom-commands:
  mycommand:
    aliases: [mc]
    description: "My awesome command"
    permission: "bubblecommand.mycommand"
    player-only: true
    cooldown: 60
    actions:
      - "message: &aHello, %player%!"
      - "sound: ENTITY_PLAYER_LEVELUP"

Then:

1. Change mycommand to whatever you want
2. Edit the message
3. Save and run /bubblecommand reload
4. Use your command!

---

📚 Documentation

Basic Command Structure

custom-commands:
  commandname:              # The command name (use lowercase)
    aliases: [alias1, alias2]  # Optional command aliases
    description: "Description"  # Command description
    permission: "perm.node"     # Optional permission
    player-only: true           # true = players only, false = anyone
    cooldown: 60                # Cooldown in seconds (0 = no cooldown)
    actions:                    # List of actions to execute
      - "action1"
      - "action2"

Action Types Explained

1. Console Commands

Run commands with console permissions (bypasses permission checks):

actions:
  - "console: give %player% diamond 64"
  - "console: tp %player% 0 100 0"

2. Player Commands

Run commands as the player (respects permissions):

actions:
  - "player: warp spawn"
  - "player: home"

3. Messages

Send colored messages to the player:

actions:
  - "message: &a&lSUCCESS! &7You did it!"
  - "message: &cError: Invalid command!"

4. Broadcasts

Broadcast to all online players:

actions:
  - "broadcast: &6[Server] &e%player% &7just did something cool!"

5. Sounds

Play sounds to the player:

actions:
  - "sound: ENTITY_PLAYER_LEVELUP"
  - "sound: BLOCK_NOTE_BLOCK_PLING"
  - "sound: UI_TOAST_CHALLENGE_COMPLETE"

6. Titles

Display title and subtitle:

actions:
  - "title: &6Welcome!|&eEnjoy your stay|10|70|20"
  # Format: title|subtitle|fadeIn|stay|fadeOut (times in ticks)

7. Actionbar

Show actionbar message:

actions:
  - "actionbar: &eYou received a reward!"

Real-World Examples

Example 1: Heal Command

heal:
  aliases: [h]
  description: "Heal yourself to full health"
  permission: "bubblecommand.heal"
  player-only: true
  cooldown: 60
  actions:
    - "console: effect give %player% minecraft:instant_health 1 10"
    - "console: effect give %player% minecraft:saturation 1 10"
    - "message: &a&lHEALED! &7You have been healed to full health!"
    - "sound: ENTITY_PLAYER_LEVELUP"

Example 2: Starter Kit

starterkit:
  aliases: [kit, starter]
  description: "Get a starter kit"
  permission: "bubblecommand.kit.starter"
  player-only: true
  cooldown: 86400  # 24 hours
  actions:
    - "console: give %player% minecraft:iron_sword 1"
    - "console: give %player% minecraft:iron_pickaxe 1"
    - "console: give %player% minecraft:cooked_beef 32"
    - "message: &e&lSTARTER KIT! &7You received your starter items!"
    - "title: &6Welcome!|&eEnjoy your kit|10|40|10"
    - "sound: ENTITY_PLAYER_LEVELUP"

Example 3: Report Command

report:
  aliases: []
  description: "Report a player"
  permission: "bubblecommand.report"
  player-only: true
  cooldown: 300  # 5 minutes
  actions:
    - "console: execute as @a[permission=bubblecommand.staff] run tellraw @s {\"text\":\"[REPORT] %player% reported: %args%\",\"color\":\"red\"}"
    - "message: &c&lREPORT SENT! &7Thank you for reporting."
    - "sound: BLOCK_NOTE_BLOCK_PLING"

Example 4: Broadcast Command

announce:
  aliases: [broadcast, bc]
  description: "Broadcast a message"
  permission: "bubblecommand.broadcast"
  player-only: false
  actions:
    - "broadcast: &6&l[ANNOUNCEMENT] &e%args%"
    - "sound: BLOCK_NOTE_BLOCK_PLING"

Color Codes

Use & for color codes in messages:

Code	Color	Code	Format
&0	Black	&l	Bold
&1	Dark Blue	&m	Strikethrough
&2	Dark Green	&n	Underline
&3	Dark Aqua	&o	Italic
&4	Dark Red	&r	Reset
&5	Dark Purple
&6	Gold
&7	Gray
&8	Dark Gray
&9	Blue
&a	Green
&b	Aqua
&c	Red
&d	Light Purple
&e	Yellow
&f	White

---

🎮 Commands & Permissions

Main Commands

Command	Description	Permission
/bubblecommand	Show plugin information	-
/bubblecommand reload	Reload configuration	bubblecommand.admin
/bcommand	Alias for bubblecommand	-
/bc	Alias for bubblecommand	-

Permissions

Permission	Description	Default
bubblecommand.*	All permissions	op
bubblecommand.admin	Admin commands (reload)	op
bubblecommand.use	Basic command usage	true

Custom commands use their own permissions as defined in config.

---

⚙️ Configuration

General Settings

settings:
  debug: false  # Enable debug messages in console
  default-permission: ""  # Default permission for all commands
  save-data: true  # Save player data (cooldowns)
  cooldown-message: "&cYou must wait %time% seconds before using this command again!"
  no-permission-message: "&cYou don't have permission to use this command!"
  player-only-message: "&cThis command can only be used by players!"

---

🔧 Advanced Features

Multiple Actions

Execute multiple actions in sequence:

actions:
  - "message: &eStarting teleport..."
  - "sound: BLOCK_NOTE_BLOCK_PLING"
  - "console: tp %player% 0 100 0"
  - "message: &aTeleported!"

Command Arguments

Use arguments in your commands:

givemoney:
  actions:
    - "console: eco give %arg0% %arg1%"
    - "message: &aGave &e$%arg1% &ato &e%arg0%"
# Usage: /givemoney PlayerName 1000

Conditional Execution

Use player placeholders for dynamic commands:

hometp:
  actions:
    - "player: home %arg0%"
    - "message: &aTeleporting to %arg0%'s home..."

---

📊 Performance

BubbleCommand is designed for production environments:

• ✅ Async cooldown saves - No server lag
• ✅ Concurrent hashmap - Thread-safe cooldowns
• ✅ Minimal memory footprint - Only stores active cooldowns
• ✅ Efficient command registration - Smart dynamic registration
• ✅ Optimized placeholder replacement - Fast text processing

---

🐛 Troubleshooting

Common Issues

Q: My command doesn't work!

• Make sure you removed the # to uncomment the command
• Check for proper YAML indentation (use spaces, not tabs)
• Verify the command name doesn't conflict with existing commands
• Run /bubblecommand reload after making changes

Q: Cooldown isn't working!

• Ensure save-data: true in settings
• Check file permissions on data.yml
• Cooldown only applies to players, not console

Q: Colors aren't showing!

• Use & not § for color codes
• Make sure the text is in quotes if it contains special characters

Q: Command says "Unknown command"!

• Run /bubblecommand reload after editing config
• Check console for errors during reload
• Verify YAML syntax is correct (use online YAML validator)

---

📝 Tips & Tricks

Best Practices

1. Test commands before giving them to players
2. Use cooldowns to prevent spam
3. Add permissions to control access
4. Use descriptive names for easy management
5. Comment your config to remember what commands do
6. Backup your config before major changes

Pro Tips

• Use console: for commands that need admin permissions
• Chain multiple actions for complex commands
• Use sounds for better user feedback
• Combine titles with messages for important notifications
• Use placeholders to make commands dynamic
• Set appropriate cooldowns based on command power

---

📜 License

BubbleCommand is licensed under the MIT License.

---