Advanced Features

Advanced Features

The Custom Commands plugin includes powerful advanced features that allow you to create complex command structures with nested subcommands, argument validation, player-specific arguments, and flexible command execution types.

New Features

These features were added in version 1.0.2 and provide enhanced functionality for creating sophisticated command systems.

🔗 Nested Subcommands

The nested subcommands feature allows you to create hierarchical command structures where subcommands can have their own subcommands, creating unlimited depth levels.

How It Works

Subcommands can contain their own subcommands section, allowing you to build complex command trees like /admin player kick <player> or /admin server restart.

Basic Structure

commands:
  admin:
    permission: "customcommands.admin"
    subcommands:
      player:                              # /admin player
        permission: "customcommands.admin.player"
        subcommands:                      # Nested subcommands!
          kick:                           # /admin player kick
            permission: "customcommands.admin.player.kick"
            message:
              - "&cKicking player..."
          ban:                            # /admin player ban
            permission: "customcommands.admin.player.ban"
            message:
              - "&cBanning player..."
      server:                             # /admin server
        permission: "customcommands.admin.server"
        subcommands:                      # More nested subcommands!
          restart:                        # /admin server restart
            permission: "customcommands.admin.server.restart"
            message:
              - "&cRestarting server..."

Key Features

Nested Subcommands Benefits

• Unlimited Depth - Create as many levels as needed
• Individual Permissions - Each level has its own permission
• Tab Completion - Full tab completion support for all levels
• Type Override - Subcommands can override parent command execution type

Permission Structure

Permissions follow a hierarchical structure matching the command path:

customcommands.admin                           # Main command
customcommands.admin.player                    # First level subcommand
customcommands.admin.player.kick               # Second level subcommand
customcommands.admin.server.restart            # Another second level subcommand

Real-World Example

commands:
  admin:
    permission: "customcommands.admin"
    alias: ["a", "adm"]
    description: "Admin command with nested subcommands"
    enabled: true
    cooldown: 0
    type: "Console"
    message:
      - "&c&l=== Admin Panel ==="
      - "&7Use &e/admin help &7to see available commands"
    subcommands:
      player:                                 # /admin player
        permission: "customcommands.admin.player"
        message:
          - "&6&lPlayer Management"
          - "&7Use &e/admin player help &7for more options"
        subcommands:                          # Nested!
          kick:                               # /admin player kick <player>
            permission: "customcommands.admin.player.kick"
            message:
              - "&cKicking player: {args}"
            arguments:
              whitelist: []
              whitelist-only: false
              no-arguments: false
              player-args: [0]                # First argument must be player
              invalid-message: "&cUsage: /admin player kick <player>"
            commands:
              - "kick {args} Kicked by {player}"
          ban:                                # /admin player ban <player>
            permission: "customcommands.admin.player.ban"
            message:
              - "&cBanning player: {args}"
            arguments:
              whitelist: []
              whitelist-only: false
              no-arguments: false
              player-args: [0]                # First argument must be player
              invalid-message: "&cUsage: /admin player ban <player>"
            commands:
              - "ban {args} Banned by {player}"
      server:                                 # /admin server
        permission: "customcommands.admin.server"
        message:
          - "&6&lServer Management"
          - "&7Use &e/admin server help &7for more options"
        subcommands:                          # More nested subcommands!
          restart:                            # /admin server restart
            permission: "customcommands.admin.server.restart"
            message:
              - "&c&lRestarting server in 10 seconds..."
            commands:
              - "say Server restarting in 10 seconds!"
              - "schedule function minecraft:load 10s"
          reload:                             # /admin server reload
            permission: "customcommands.admin.server.reload"
            message:
              - "&eReloading server..."
            commands:
              - "reload"

Usage Examples

/admin player kick Steve      → Kicks player "Steve"
/admin player ban Alex        → Bans player "Alex"
/admin server restart         → Restarts the server
/admin server reload          → Reloads the server

Permission Requirements

Each level of nesting requires its own permission. Make sure players have the correct permission for the specific subcommand path they want to use.

📝 Arguments System

The arguments system allows you to accept and validate arguments passed to your custom commands, with support for whitelisting, validation, and custom error messages.

Configuration Options

arguments:
  whitelist: []                    # List of allowed arguments
  whitelist-only: false            # Only allow whitelisted arguments
  no-arguments: true              # Allow command without arguments
  invalid-message: "&cInvalid arguments."  # Custom error message
  player-args: []                  # Arguments that must be player names (0-based)
  required-args: []                # Arguments that are required (0-based)

Argument Options Explained

Option	Type	Description
whitelist	List<String>	List of allowed arguments for autocomplete
whitelist-only	boolean	true = only whitelisted args, false = any args
no-arguments	boolean	true = allow without args, false = require args
invalid-message	String	Message shown when arguments are invalid
player-args	List<Integer>	Argument indices that must be player names (0-based)
required-args	List<Integer>	Argument indices that are required (0-based)

Using Arguments in Commands

Arguments can be accessed in two ways:

All Arguments Together

Use {args} to get all arguments as a single string:

message:
  - "&eYou said: {args}"           # Shows all arguments
commands:
  - "say {player}: {args}"          # Broadcasts arguments

Individual Arguments

Use {arg:1}, {arg:2}, {arg:3}, etc. to access individual arguments (1-based index):

message:
  - "&eFirst: {arg:1}, Second: {arg:2}"  # Individual arguments
commands:
  - "tellraw {player} [\"\",{\"text\":\"Price: \",\"color\":\"gold\"},{\"text\":\"{arg:1}\",\"color\":\"green\"}]"

Variable Index System:

• {arg:1} = First argument (index 0)
• {arg:2} = Second argument (index 1)
• {arg:3} = Third argument (index 2)
• {arg:N} = Nth argument
• {args} = All arguments as string (backward compatible)

Index System

Individual argument variables use 1-based indexing ({arg:1} = first argument), while configuration options like required-args and player-args use 0-based indexing ([0] = first argument). The variable {arg:0} is also supported for backward compatibility and is equivalent to {arg:1}.

Example 1: Simple Arguments

tellraw:
  permission: "customcommands.tellraw"
  alias: ["tr", "raw"]
  description: "Send a raw JSON message"
  enabled: true
  cooldown: 0
  type: "Console"
  arguments:
    whitelist: []                   # Empty = any arguments allowed
    whitelist-only: false           # Allow any arguments
    no-arguments: false             # Arguments required
    invalid-message: "&cUsage: /tellraw <message>"
  message:
    - "&6&lTellraw Command"
    - "&eMessage sent: &7{args}"
  commands:
    - "tellraw {player} [\"\",{\"text\":\"[Tellraw] \",\"color\":\"gold\"},{\"text\":\"{args}\",\"color\":\"yellow\"}]"

Usage:

/tellraw Hello World!     → Valid (sends "Hello World!")
/tellraw                  → Invalid (shows error message)

Example 2: Whitelisted Arguments

say:
  permission: "customcommands.say"
  message:
    - "&eYou said: {args}"
  arguments:
    whitelist: ["hello", "goodbye", "help"]  # Only these allowed
    whitelist-only: true                      # Only whitelisted
    no-arguments: true                        # Can be used without args
  commands:
    - "say {player}: {args}"

Usage:

/say hello      → Valid
/say goodbye    → Valid
/say test       → Invalid (not in whitelist)
/say            → Valid (no-arguments: true)

Example 3: Arguments with Spaces

broadcast:
  permission: "customcommands.broadcast"
  message:
    - "&6Broadcasting: {args}"
  arguments:
    whitelist: ["Server restart in 5 minutes", "Maintenance starting soon", ""]
    whitelist-only: true
    no-arguments: true
  commands:
    - "say {args}"

Usage:

/broadcast Server restart in 5 minutes    → Valid
/broadcast Maintenance starting soon       → Valid
/broadcast                                → Valid (empty string in whitelist)

Example 4: Required and Optional Arguments

ah:
  permission: "customcommands.ah"
  subcommands:
    sell:                                    # /ah sell <price> [amount]
      permission: "customcommands.ah.sell"
      arguments:
        required-args: [0]                   # First argument (price) is REQUIRED
        no-arguments: false                 # Arguments required
        invalid-message: "&cUsage: /ah sell <price> [amount]"
      commands:
        - "tellraw {player} [\"\",{\"text\":\"Price: \",\"color\":\"gold\"},{\"text\":\"{arg:1}\",\"color\":\"green\"},{\"text\":\", Amount: \",\"color\":\"gold\"},{\"text\":\"{arg:2}\",\"color\":\"yellow\"}]"
        # {arg:1} = price (required)
        # {arg:2} = amount (optional, empty string if not provided)

Usage:

/ah sell 100          → Valid: {arg:1} = "100", {arg:2} = ""
/ah sell 100 64       → Valid: {arg:1} = "100", {arg:2} = "64"
/ah sell              → Invalid: Shows error message

Example 5: Multiple Required Arguments

transfer:
  permission: "customcommands.transfer"
  arguments:
    required-args: [0, 1]                   # First AND second arguments required
    no-arguments: false
    invalid-message: "&cUsage: /transfer <player1> <player2>"
  commands:
    - "transfer {arg:1} {arg:2}"            # Use individual arguments

Usage:

/transfer Steve Alex        → Valid: {arg:1} = "Steve", {arg:2} = "Alex"
/transfer Steve             → Invalid: Missing second required argument
/transfer                   → Invalid: Missing both required arguments

Required vs Optional Arguments

You can mark specific arguments as required using required-args. This allows you to create commands where some arguments are required and others are optional.

Example: /ah sell <price> [amount] - price is required, amount is optional

ah:
  subcommands:
    sell:
      arguments:
        required-args: [0]           # First argument (index 0) is REQUIRED
        no-arguments: false          # Command requires arguments
        invalid-message: "&cUsage: /ah sell <price> [amount]"
      commands:
        - "tellraw {player} [\"\",{\"text\":\"Price: \",\"color\":\"gold\"},{\"text\":\"{arg:1}\",\"color\":\"green\"}]"
        # {arg:1} = price (required)
        # {arg:2} = amount (optional, empty string if not provided)

Usage:

• ✅ /ah sell 100 → {arg:1} = "100", {arg:2} = ""
• ✅ /ah sell 100 64 → {arg:1} = "100", {arg:2} = "64"
• ❌ /ah sell → Error: “Usage: /ah sell <price> [amount]”

Required Arguments

The required-args option uses 0-based indexing. To make the first argument required, use required-args: [0]. To make the first and third arguments required, use required-args: [0, 2].

Default Behavior

If no arguments section is specified:

• Commands don’t accept any arguments
• Default whitelist contains one empty string (command can be used without arguments)
• Default whitelist-only is true
• Default no-arguments is true
• No arguments are required by default

Argument Extraction

Arguments are extracted from everything after the command/subcommand. For /command subcommand arg1 arg2, {args} will be "arg1 arg2", {arg:1} will be "arg1", and {arg:2} will be "arg2".

👤 Player Arguments

The player-args feature allows you to specify which arguments must be valid player names, with automatic validation and tab-completion.

How It Works

When you specify player-args, the plugin:

1. Validates that the specified argument positions contain valid player names
2. Checks if the player exists and is online
3. Provides tab-completion showing all online players
4. Shows clear error messages for invalid players

Index System

Arguments are indexed starting from 0:

• Index 0 = First argument after command/subcommand
• Index 1 = Second argument
• Index 2 = Third argument
• etc.

Configuration

arguments:
  player-args: [0]        # First argument (index 0) must be a player name
  player-args: [0, 2]      # First (0) and third (2) arguments must be player names
  player-args: [1]         # Second argument (index 1) must be a player name

Example 1: Simple Kick Command

kick:
  permission: "customcommands.kick"
  message:
    - "&cKicking player: {args}"
  arguments:
    whitelist: []
    whitelist-only: false
    no-arguments: false
    player-args: [0]                    # First argument = player name
    invalid-message: "&cUsage: /kick <player>"
  commands:
    - "kick {args} Kicked by {player}"

Usage:

/kick Steve          → Valid (if Steve is online)
/kick InvalidPlayer  → Error: "Player InvalidPlayer is not online or does not exist!"
/kick                → Error: "Usage: /kick <player>"

Tab Completion: After typing /kick , all online players are shown.

Example 2: Teleport with Player + Coordinates

teleport:
  permission: "customcommands.teleport"
  message:
    - "&6Teleporting player..."
  arguments:
    whitelist: []
    whitelist-only: false
    no-arguments: false
    player-args: [0]                    # First argument = player name
    invalid-message: "&cUsage: /teleport <player> [x] [y] [z]"
  commands:
    - "tp {args}"                        # {args} = "Steve 100 64 200"

Usage:

/teleport Steve 100 64 200           → Valid (if Steve is online)
/teleport InvalidPlayer 100 64 200  → Error: "Player InvalidPlayer is not online or does not exist!"

Tab Completion: After typing /teleport , all online players are shown.

Example 3: Transfer with Two Player Arguments

transfer:
  permission: "customcommands.transfer"
  message:
    - "&6Transferring player..."
  arguments:
    whitelist: []
    whitelist-only: false
    no-arguments: false
    player-args: [0, 1]                 # First AND second = player names
    invalid-message: "&cUsage: /transfer <player1> <player2>"
  commands:
    - "transfer {args}"                  # {args} = "Steve Alex"

Usage:

/transfer Steve Alex              → Valid (if both are online)
/transfer Steve InvalidPlayer    → Error: "Player InvalidPlayer is not online or does not exist!"
/transfer InvalidPlayer Alex     → Error: "Player InvalidPlayer is not online or does not exist!"

Tab Completion:

• After /transfer → Shows all online players (for first player)
• After /transfer Steve → Shows all online players (for second player)

Example 6: Nested Subcommand with Player Argument

admin:
  permission: "customcommands.admin"
  subcommands:
    player:
      permission: "customcommands.admin.player"
      subcommands:
        kick:
          permission: "customcommands.admin.player.kick"
          message:
            - "&cKicking: {args}"
          arguments:
            whitelist: []
            whitelist-only: false
            no-arguments: false
            player-args: [0]              # First argument after "kick" = player name
            invalid-message: "&cUsage: /admin player kick <player>"
          commands:
            - "kick {args} Kicked by admin"

Usage:

/admin player kick Steve          → Valid (if Steve is online)
/admin player kick InvalidPlayer  → Error: "Player InvalidPlayer is not online or does not exist!"

Tab Completion: After typing /admin player kick , all online players are shown.

Important Notes

Player Validation Rules

• Online Only - Only ONLINE players are considered valid (offline players will show error)
• Case Sensitive - Player names must match exactly (case-sensitive)
• Tab Completion - Only shows players that are currently online
• Error Override - Player-specific errors override invalid-message

Validation Timing

Player validation happens BEFORE the command is executed, preventing invalid commands from running.

⚙️ Command Execution Types

The command execution type feature allows you to control whether commands are executed as the server console or as the player who used the command.

Available Types

Type	Description	Use Case
Console	Commands executed as server console	Admin commands, effects, teleportation
Player	Commands executed as the player	Player commands like /home, /warp

Console Type (Default)

Commands executed as console have full permissions and bypass player restrictions.

example:
  permission: "customcommands.example"
  type: "Console"                    # Executed as console
  commands:
    - "effect give {player} minecraft:glowing 10 1 true"  # Works without player permission
    - "teleport {player} 0 64 0"                          # Works without player permission
    - "kick {player} You were kicked!"                    # Works without player permission

Benefits:

• ✅ Full permission access
• ✅ Bypasses player restrictions
• ✅ Works for admin commands
• ✅ Can execute any server command

Player Type

Commands executed as player respect player permissions and restrictions.

home:
  permission: "customcommands.home"
  type: "Player"                    # Executed as player
  commands:
    - "/home"                        # Player executes /home (needs permission)
    - "/warp spawn"                  # Player executes /warp spawn (needs permission)
    - "/spawn"                       # Player executes /spawn (needs permission)

Benefits:

• ✅ Respects player permissions
• ✅ Works with permission-based plugins
• ✅ Player-specific command execution
• ✅ Natural command behavior

Type Inheritance

Subcommands can override the parent command’s type:

admin:
  permission: "customcommands.admin"
  type: "Console"                    # Default: Console
  subcommands:
    kick:
      permission: "customcommands.admin.kick"
      type: "Console"                # Explicitly Console (inherits from parent)
      commands:
        - "kick {args} Kicked by {player}"
    home:
      permission: "customcommands.admin.home"
      type: "Player"                 # Override: Player type
      commands:
        - "/home"                    # Executed as player

Default Behavior

• If type is not specified, defaults to "Console"
• If type is "Player" and sender is not a player (e.g., console), commands still execute as console
• Subcommands inherit parent type unless explicitly overridden

Real-World Example

example:
  permission: "customcommands.example"
  alias: ["ex", "demo"]
  description: "Example command with console execution"
  enabled: true
  cooldown: 5
  type: "Console"                     # Console execution
  commands:
    - "say {player} used the example command!"
    - "tellraw @a [\"\",{\"text\":\"Player \",\"color\":\"yellow\"},{\"text\":\"{player}\",\"color\":\"green\"},{\"text\":\" is at \",\"color\":\"yellow\"},{\"text\":\"{x}, {y}, {z}\",\"color\":\"aqua\"},{\"text\":\" in \",\"color\":\"yellow\"},{\"text\":\"{world}\",\"color\":\"gold\"}]"
    - "effect give {player} minecraft:glowing 10 1 true"
    - "title {player} title [\"\",{\"text\":\"Example Command!\",\"color\":\"gold\"}]"
    - "title {player} subtitle [\"\",{\"text\":\"You are at {x}, {y}, {z}\",\"color\":\"gray\"}]"
  message:
    - "&6&l=== Example Command ==="
    - "&eThis command demonstrates console command execution!"
    - "&7Check the console for executed commands!"
    - "&7You should see a glowing effect and title!"

Variable Support

All variables work in both Console and Player execution types:

commands:
  - "say {player} used the command!"           # {player} = player name
  - "tp {player} {x} {y} {z}"                 # Location variables
  - "tellraw {player} [\"\",{\"text\":\"Hello {player}!\",\"color\":\"green\"}]"  # JSON with variables
  - "kick {args} Kicked by {player}"           # {args} for all arguments
  - "say Price: {arg:1}, Amount: {arg:2}"     # Individual arguments

Argument Variables:

• {args} - All arguments as a single string (backward compatible)
• {arg:1} - First argument (1-based index)
• {arg:2} - Second argument (empty string if not provided)
• {arg:N} - Nth argument (empty string if not provided)

Console Sender Variables

When commands are executed by console (not a player), player variables default to:

• {player} → "Console"
• {displayname} → "Console"
• {world} → "world"
• {x}, {y}, {z} → "0"

🎯 Complete Example

Here’s a complete example combining all advanced features:

commands:
  admin:
    permission: "customcommands.admin"
    alias: ["a", "adm"]
    description: "Admin command with all advanced features"
    enabled: true
    cooldown: 0
    type: "Console"                              # Console execution
    message:
      - "&c&l=== Admin Panel ==="
      - "&7Use &e/admin help &7to see available commands"
    subcommands:                                 # Nested subcommands
      player:                                    # /admin player
        permission: "customcommands.admin.player"
        type: "Console"                          # Inherits from parent
        message:
          - "&6&lPlayer Management"
        subcommands:                             # Nested subcommands!
          kick:                                  # /admin player kick <player>
            permission: "customcommands.admin.player.kick"
            type: "Console"
            message:
              - "&cKicking player: {args}"
            arguments:                           # Arguments configuration
              whitelist: []
              whitelist-only: false
              no-arguments: false
              player-args: [0]                    # First argument = player name
              invalid-message: "&cUsage: /admin player kick <player>"
            commands:                            # Console commands
              - "kick {args} Kicked by {player}"
          ban:                                   # /admin player ban <player>
            permission: "customcommands.admin.player.ban"
            type: "Console"
            message:
              - "&cBanning player: {args}"
            arguments:
              whitelist: []
              whitelist-only: false
              no-arguments: false
              player-args: [0]                    # First argument = player name
              invalid-message: "&cUsage: /admin player ban <player>"
            commands:
              - "ban {args} Banned by {player}"
          teleport:                              # /admin player teleport <player> [target]
            permission: "customcommands.admin.player.teleport"
            type: "Console"
            message:
              - "&6Teleporting player..."
            arguments:
              whitelist: []
              whitelist-only: false
              no-arguments: false
              invalid-message: "&cUsage: /admin player teleport <player> [target]"
            commands:
              - "tp {args}"
      server:                                    # /admin server
        permission: "customcommands.admin.server"
        type: "Console"
        message:
          - "&6&lServer Management"
        subcommands:                             # More nested subcommands!
          restart:                               # /admin server restart
            permission: "customcommands.admin.server.restart"
            type: "Console"
            message:
              - "&c&lRestarting server in 10 seconds..."
            commands:
              - "say Server restarting in 10 seconds!"
              - "schedule function minecraft:load 10s"
          reload:                                # /admin server reload
            permission: "customcommands.admin.server.reload"
            type: "Console"
            message:
              - "&eReloading server..."
            commands:
              - "reload"
          broadcast:                             # /admin server broadcast <message>
            permission: "customcommands.admin.server.broadcast"
            type: "Console"
            message:
              - "&6Broadcasting message..."
            arguments:                            # Arguments with message
              whitelist: []
              whitelist-only: false
              no-arguments: false
              invalid-message: "&cUsage: /admin server broadcast <message>"
            commands:
              - "say [Broadcast] {args}"
      help:                                      # /admin help
        permission: "customcommands.admin.help"
        message:
          - "&6&l=== Admin Help ==="
          - "&eAvailable commands:"
          - "&7/admin player kick &lt;player&gt; - Kick a player"
          - "&7/admin player ban &lt;player&gt; - Ban a player"
          - "&7/admin player teleport &lt;player&gt; [target] - Teleport player"
          - "&7/admin server restart - Restart the server"
          - "&7/admin server reload - Reload the server"
          - "&7/admin server broadcast &lt;message&gt; - Broadcast a message"
          - "&7/admin help - Show this help"

🚀 Best Practices

Performance Tips

• Use whitelist-only: false only when necessary (allows any arguments)
• Limit nested subcommand depth for better performance
• Use player-args for automatic validation instead of manual checks

Security Considerations

• Always validate player arguments when using player-args
• Use Console type carefully - it bypasses all permission checks
• Set appropriate permissions for each subcommand level

Testing Recommendations

• Test all argument combinations before deploying
• Verify player validation works correctly
• Test nested subcommands at all levels
• Check tab completion for all command paths

---

Next Steps

Now that you understand the advanced features, check out:

• Configuration Guide - Learn more about configuration options
• Examples - See real-world examples
• Troubleshooting - Common issues and solutions

For support and updates, join our Discord server.