commands.yml Structure

This page explains the structure expected by the plugin when it loads commands.yml.

Top-level layout

The file has two top-level sections:

settings:
  useLegacyColours: false
 
commands:
  example:
    type: "message_self"
    command: /example [text:greedy_string]
    message: "<green>%text%"
    enabled: true

• settings contains global plugin settings
• commands contains every custom command you want to register

If the commands section is missing entirely, the plugin logs an error and does not load your command definitions.

settings

useLegacyColours

settings:
  useLegacyColours: false

This controls how message text is parsed:

• false uses MiniMessage formatting such as <red>, <bold>, and gradients
• true uses legacy & colour codes such as &6 and &c

Keep your formatting style consistent across the file. Mixing styles usually leads to confusing output.

commands

Each child key under commands: is one command definition.

commands:
  hello:
    type: "message_self"
    command: /hello
    message: "<green>Hello"
    enabled: true

Here:

• hello is the command’s internal name in the config
• /hello is the syntax shown to the user
• the plugin registers the command using the internal key name, so it is best to keep the key and the label aligned

Fields used across command types

Required on every command

type: "message_self"
command: /hello [text:greedy_string]
enabled: true

• type decides which command implementation is used
• command defines the syntax and parameters
• enabled controls whether the command is loaded

Common optional fields

aliases: ["helloalias", "hi"]
permission: "velocitycommands.hello"
sound: "ui.toast.in"

• aliases adds extra command labels
• permission limits who can use the command
• sound plays a sound to the executor after the command runs

Type-specific fields

message_self

Requires:

message: "..."

message_other_player

Requires:

message: "..."

broadcast

Requires:

message: "..."

Optional:

view_permission: "your.permission.node"

console_command

Requires:

to_run:
  1:
    executes-on: player
    runs-on: backend
    command: /example

Example based on the bundled file

settings:
  useLegacyColours: false
 
commands:
  alert:
    type: "broadcast"
    aliases: ["broadcast"]
    command: /alert [message:greedy_string]
    message: "<dark_gray>[<aqua>ALERT</aqua><dark_gray>] <white>%message%"
    permission: "velocitycommands.alert"
    view_permission: "velocitycommands.view"
    enabled: true
 
  messageself:
    type: "message_self"
    command: /messageself [category:word] [message:greedy_string]
    message: "<white>Category: <gray>%category%<br><white>Message: <gray>%message%"
    enabled: true
    sound: "ui.toast.in"

Best practices

Keep the key name and command label close together

This makes logs, support, and admin commands easier to understand.

Good:

commands:
  alert:
    command: /alert [message:greedy_string]

Build commands one at a time

Because the plugin supports reloads, the safest workflow is:

1. add or edit one command
2. reload the plugin
3. test it in game
4. check console output

Keep your command: field readable

The plugin uses it as the usage message when a player runs the command incorrectly.

Use enabled: false while drafting

Disabled commands are skipped cleanly, which makes it easier to keep unfinished ideas in the file without registering them.