Configuration for server admins

The CommandAPI has a few configuration options to change how it functions. These options can be set in the plugins/CommandAPI/config.yml file, which is generated automatically when the CommandAPI runs for the first time.

Default config.yml file

The default config.yml is shown below:

config.yml

# Verbose outputs (default: false)
# If "true", outputs command registration and unregistration logs in the console
verbose-outputs: false

# Silent logs (default: false)
# If "true", turns off all logging from the CommandAPI, except for errors.
silent-logs: false

# Messages
# Controls messages that the CommandAPI displays to players
messages:

    # Missing executor implementation (default: "This command has no implementations for %s")
    # The message to display to senders when a command has no executor. Available
    # parameters are:
    #   %s - the executor class (lowercase)
    #   %S - the executor class (normal case)
    missing-executor-implementation: This command has no implementations for %s

# Create dispatcher JSON (default: false)
# If "true", the CommandAPI creates a command_registration.json file showing the
# mapping of registered commands. This is designed to be used by developers -
# setting this to "false" will improve command registration performance.
create-dispatcher-json: false

# Fallback to latest version (default: true)
# If "true", the CommandAPI will fall back to the latest available NMS
# implementation when the CommandAPI is used and no implementation for the
# current Minecraft version was found.
fallback-to-latest-nms: true

# Skips the initial datapack reload when the server loads (default: true)
# If "true", the CommandAPI will not reload datapacks when the server has finished
# loading. Datapacks will still be reloaded if performed manually when "hook-paper-reload"
# is set to "true" and /minecraft:reload is run.
skip-initial-datapack-reload: true

# Hook into Paper's ServerResourcesReloadedEvent (default: false)
# If "true", the CommandAPI will hook into Paper's ServerResourcesReloadedEvent to detect when
# /minecraft:reload is run. This allows the CommandAPI to automatically call its custom datapack-reloading
# function which allows CommandAPI commands to be used in datapacks.
hook-paper-reload: false

# Plugins to convert (default: [])
# Controls the list of plugins to process for command conversion.
plugins-to-convert: []

# Other commands to convert (default: [])
# A list of other commands to convert. This should be used for commands which
# are not declared in a plugin.yml file.
other-commands-to-convert: []

# Skip sender proxy (default: [])
# Determines whether the proxy sender should be skipped when converting a
# command. If you are having issues with plugin command conversion, add the
# plugin to this list.
skip-sender-proxy: []

# Verbose outputs (default: false)
# If "true", outputs command registration and unregistration logs in the console
verbose-outputs: false

# Silent logs (default: false)
# If "true", turns off all logging from the CommandAPI, except for errors.
silent-logs: false

# Messages
# Controls messages that the CommandAPI displays to players
messages:

    # Missing executor implementation (default: "This command has no implementations for %s")
    # The message to display to senders when a command has no executor. Available
    # parameters are:
    #   %s - the executor class (lowercase)
    #   %S - the executor class (normal case)
    missing-executor-implementation: This command has no implementations for %s

# Create dispatcher JSON (default: false)
# If "true", the CommandAPI creates a command_registration.json file showing the
# mapping of registered commands. This is designed to be used by developers -
# setting this to "false" will improve command registration performance.
create-dispatcher-json: false

# Fallback to latest version (default: false)
# If "true", the CommandAPI will fall back to the latest available NMS
# implementation when the CommandAPI is used and no implementation for the
# current Minecraft version was found.
fallback-to-latest-nms: false

# Skips the initial datapack reload when the server loads (default: true)
# If "true", the CommandAPI will not reload datapacks when the server has finished
# loading. Datapacks will still be reloaded if performed manually when "hook-paper-reload"
# is set to "true" and /minecraft:reload is run.
skip-initial-datapack-reload: true

# Plugins to convert (default: [])
# Controls the list of plugins to process for command conversion.
plugins-to-convert: []

# Other commands to convert (default: [])
# A list of other commands to convert. This should be used for commands which
# are not declared in a plugin.yml file.
other-commands-to-convert: []

# Skip sender proxy (default: [])
# Determines whether the proxy sender should be skipped when converting a
# command. If you are having issues with plugin command conversion, add the
# plugin to this list.
skip-sender-proxy: []

Configuration settings

verbose-outputs

If true, outputs command registration and unregistration logs in the console. This is primarily used for developers to identify issues with command registration.

Default value

verbose-outputs: false

Example value

verbose-outputs: true

silent-logs

If true, turns off all logging from the CommandAPI, except for errors.

Default value

silent-logs: false

Example value

silent-logs: true

messages

Controls messages that the CommandAPI displays to players. Available messages:

• missing-executor-implementation - the message to display to senders when a command has no executor. This message supports format parameters:
  • %s - the executor class (lowercase). For example craftplayer
  • %S - the executor class (normal case). For example CraftPlayer

Default value

messages:
  missing-executor-implementation: "This command has no implementations for %s"

create-dispatcher-json

Controls whether the CommandAPI should generate a command_registration.json file showing the mapping of registered commands.

This is primarily designed to be used by developers. Setting this to false will slightly improve command registration performance.

The command_registration.json JSON representation of commands is in the same format as Minecraft's Data Generators Commands report. The format is Brigadier's command graph - more information about the JSON format can be found here.

Default value

create-dispatcher-json: false

Example value

create-dispatcher-json: true

fallback-to-latest-nms

Controls whether the CommandAPI should use the latest NMS implementation for command registration and execution if no matching CommandAPI implementation for the version used is found.

This setting can be used to run the CommandAPI on Minecraft versions higher than it can support. For example, if the CommandAPI supports Minecraft 1.18 and Minecraft 1.18.1 comes out, you can use this to enable support for 1.18.1 before an official CommandAPI release comes out that supports 1.18.1.

WARNING

Using fallback-to-latest-nms is not guaranteed to work and can cause unexpected side effects! However, since we expect very few major breaking changes, we decided to set this value to true by default.

Default value

fallback-to-latest-nms: true

Example value

fallback-to-latest-nms: false

DANGER

This feature is very experimental and should only be used if you know what you’re doing. In almost every case, it is better to wait for an official CommandAPI release that supports the latest version of Minecraft. Using fallback-to-latest-nms is not guaranteed to work and can cause unexpected side effects!

Default value

fallback-to-latest-nms: false

Example value

fallback-to-latest-nms: true

skip-initial-datapack-reload

Controls whether the CommandAPI should perform its initial datapack reload when the server has finished loading.

If set to false, the CommandAPI reloads all datapacks in a similar fashion to /minecraft:reload in order to propagate CommandAPI commands into datapack functions and tags. This operation may cause a slight delay to server startup and is not necessary if you aren’t using datapacks or functions that use CommandAPI commands.

Note that datapacks will still be reloaded if performed manually when hook-paper-reload is set to true and you run /minecraft:reload.

Default value

skip-initial-datapack-reload: true

Example value

skip-initial-datapack-reload: false

hook-paper-reload

Controls whether the CommandAPI hooks into the Paper-exclusive ServerResourcesReloadedEvent when available.

When the CommandAPI detects it is running on a Paper-based server, this config option controls if the CommandAPI hooks into the ServerResourcesReloadedEvent, which triggers when /minecraft:reload is run. During this event, the CommandAPI runs a custom datapack reloading sequence that helps commands registered with the CommandAPI work within datapacks. See Reloading datapacks for more information on this process.

By default, this value is set to false and the CommandAPI will not hook into the ServerResourcesReloadedEvent. If you want, you can set this to true, and the CommandAPI will hook into this event.

Default value

hook-paper-reload: false

Example value

hook-paper-reload: true

plugins-to-convert

Controls the list of plugins to process for command conversion. See Command conversion for more information.

Default value

plugins-to-convert: []

Example value

plugins-to-convert:
  - Essentials: ~

plugins-to-convert:
  - Essentials:
    - speed
    - hat
  - MyPlugin:
    - mycommand
  - MyOtherPlugin: ~

plugins-to-convert:
  - Essentials:
    - speed <speed>[0..10]
    - speed <target>[minecraft:game_profile]
    - speed (walk|fly) <speed>[0..10]
    - speed (walk|fly) <speed>[0..10] <target>[minecraft:game_profile]

skip-sender-proxy

Determines whether the proxy sender should be skipped when converting a command. See Skipping proxy senders for more information.

Default value

skip-sender-proxy: []

Example value

skip-sender-proxy:
  - SkinsRestorer
  - MyPlugin

other-commands-to-convert

A list of other commands to convert. This should be used for commands which aren’t declared in a plugin.yml file. See Arbitrary command conversion for more information.

Default value

other-commands-to-convert: []

Example value

other-commands-to-convert:
  - /set
  - mycommand