Configuration Guide

IMPORTANT: This guide is for a future 2.0 version of CommandBlockerUltimate and does not apply in the current release version. Do not attempt to use this format with any version less than 2.0!

General

CommandBlockerUltimate uses the YAML format for its configuration, which is pretty standard among Spigot and Bungee plugins. If you need a reminder on the basics of the format, see TODO. (For now: this)

On both platforms, the configuration file is located at config.yml in the plugin folder. (Usually plugins/CommandBlockerUltimate/)

Please save the file with UTF-8 encoding. Do not attempt to edit it with a full word processor like Microsoft Word or LibreOffice Writer, but instead use a plain text editor such as notepad.exe, vim, nano or Notepad++ (recommended for Windows users). Do never place a tab character in the file, only ever use two spaces for indentation.

It is strongly recommended to check the whole file using a YAML Checker such as https://yaml-online-parser.appspot.com/ to make sure its syntax is correct before using it with CommandBlockerUltimate. Invalid syntax may cause loss of configuration and will force the plugin to fall back to the defaults. It is recommended to always reload the configuration using /cbu reloadcfg or /gcbu reloadcfg, respectively, because that allows you to notice and correct errors before the configuration is used.

It is further recommended to install Yamler along with CBU because that allows much more flexibility regarding configuration. If you don't install it, your configuration won't have new options as they are added in new updates.

You may inspect the default configuration here.

Actions

The config starts with defining what to do by default if a command is blocked. You'll define which commands are blocked later, and it's also possible to use a different action for some commands.

# encoding: UTF-8
#  Command Blocker Ultimate config file
#  Configuration Guide: https://github.com/xxyy/commandblockerultimate/wiki/Configuration-Guide
#  Get further help at https://github.com/xxyy/commandblockerultimate/issues

#####################
### BLOCK ACTIONS ###
#####################

## What to do by default when a command is blocked.
## You may also configure separate actions for individual filters.
## If any values are omitted, the specified defaults are used.
default-block-action:

  # Should the plugin send an error message if one is not allowed to execute a command?
  # Default: true
  show-error-message: true

  # What should that message be? (Use & for color codes, HTML escape codes accepted)
  # <command> will be replaced with the blocked command's name
  # Example: '&c&lError message &euro;&auml;&#00A7;'
  # Default: '&cYou are not permitted to execute this command.'
  error-message: '&cYou are not permitted to execute this command.'

  # Whether to display a message when executing an otherwise blocked command to permitted users
  # Default: false
  notify-bypass: false

  # The message to display when executing an otherwise blocked command (permitted users only, see notify-bypass)
  # <command> will be replaced with the blocked command's name
  # Default: '&c[CBU] /<command> is blocked. Executing anyways since you have permission.'
  bypass-message: '&c[CBU] /<command> is blocked. Executing anyways since you have permission.'

## What to do by default when tab completion is blocked for a command.
## You may also configure separate actions for individual filters.
## If any values are omitted, the specified defaults are used.
## IMPORTANT: Blocking tab-complete only works when you have ProtocolLib installed!
default-tab-block-action:

  # Should the plugin send an error message if one is not allowed to tab-complete a command?
  # Default: true
  show-error-message: true

  # What should that message be? (Use & for color codes, HTML escape codes accepted)
  # <command> will be replaced with the blocked command's name
  # Example: '&c&lError message &euro;&auml;&#00A7;'
  # Default: '&cYou are not permitted to execute this command.'
  error-message: '&cYou are not permitted to do this.'

  # Whether to display a message when tab-completing an otherwise blocked command to permitted users
  # Default: false
  notify-bypass: false

  # The message to display when tab-completing an otherwise blocked command (permitted users only)
  # <command> will be replaced with the blocked command's name
  # Default: '&c[CBU] /<command> is blocked. Executing anyways since you have permission.'
  bypass-message: '&c[CBU] Tab-completion for /<command> is blocked, but you have permission.'


###############
### FILTERS ###
###############

## This section defines which commands should be blocked.
filters:

  # This is a default filter.
  # For most configurations, this filter should be sufficient.
  # Examples with more complex filters are provided in the Configuration Guide.
  # If any values are omitted, the specified defaults are used.
  default:

    # Players with this permission will not be affected by this filter.
    # Default: cmdblock.bypass
    bypass-permission: cmdblock.bypass

    # Whether to prevent execution for commands blocked by this filter.
    # Only set this to false if you want to block tab-completion ONLY.
    # Default: true
    prevent-exec: true
    # What to do when a blocked command is executed.
    # This follows the same format as the default-block-action section.
    # A more comprehensive example is provided in the Configuration Guide.
    # Default: 'default' (use default-block-action)
    exec-action: 'default'

    # Whether to prevent tab-completion for commands blocked by this filter.
    # Note: Requires ProtocolLib!
    # Default: true
    prevent-tab: true
    # What strategy to use when blocking tab-complete replies from the server. (in this filter)
    # true: block all completions returning a targeted command (for example, if /p is typed and /pl is blocked, print error message)
    # false: just remove blocked commands from list (in the above example, other commands starting with p would still be shown without notice)
    # Default value: false
    tab-restrictive-mode: false
    # What to do when a blocked command is tab-completed.
    # This follows the same format as the default-tab-block-action section.
    # A more comprehensive example is provided in the Configuration Guide.
    # Default: 'default' (use default-tab-block-action)
    tab-action: 'default'

    # The criteria to determine whether a command is blocked.
    # This is a list, so multiple may be specified.
    # These are processed in order of definition.
    criteria:
    # This is a criterion
    # For more advanced configurations, refer to the Configuration Guide.
    - type: set
      # Commands to block. Plugin prefixes are ignored, so blocking 'tell' also blocks 'bukkit:tell'.
      blocked-commands:
      - help
      - plugins
      - version
      # If true, the plugin will attempt to resolve aliases of the blocked commands and block these too.
      # Note that, if you run this plugin on Bungee, it will not resolve Spigot aliases,
      # and the Spigot plugin cannot block Bungee's commands at all.
      # Details: https://github.com/xxyy/commandblockerultimate/wiki#small-print
      # Default: true
      resolve-aliases: true