Overview

Velocity Commands

Velocity Commands is a configurable command system for the Velocity proxy. It lets you define custom commands in commands.yml without writing your own plugin logic for each one.

This documentation is written for server owners and administrators who will be configuring and maintaining the plugin.

What you can build

With Velocity Commands, you can create commands that:

  • send a message to the player who ran the command
  • send a message to another online player
  • broadcast a message to players across the proxy
  • execute one or more commands as the player or as the proxy console

The plugin also includes:

  • hot reloading for commands.yml
  • built-in placeholders such as %player_name% and %server_name%
  • custom parameter placeholders from your command syntax
  • MiniMessage support
  • legacy & colour support
  • automatic clickable links in output messages
  • optional per-command sounds
  • per-command permissions
  • broadcast view permissions
  • execution on Velocity or backend servers, depending on the command type

How the plugin is configured

Everything is defined in commands.yml.

settings:
  useLegacyColours: false

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

At a high level:

  • settings controls global behaviour
  • commands contains every custom command you want to register
  • each command has a type, a command syntax, and type-specific fields

Recommended reading order

If you are setting the plugin up for the first time, this is the best order to read the docs:

  1. commands.yml Structure
  2. Command Syntax & Parameters
  3. message_self
  4. message_other_player
  5. broadcast
  6. console_command
  7. Placeholders
  8. Permissions, Formatting, Links & Sounds
  9. Reloading & Admin Commands
  10. Troubleshooting

Important code-based notes

These behaviours come directly from the plugin code and are worth knowing before you start:

greedy_string must be the last parameter

The command registration code enforces this. If you place a greedy_string before another parameter, registration fails.

message_other_player adds the target player automatically

This command type injects an internal player argument named otherPlayer at the start of the parameter list. In practice, users will always type a target player before the rest of the arguments.

console_command uses to_run

In the code, the plugin loads to_run, not to-run.

Use this:

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

Not this:

to-run:

Supported parameter types are limited

The code only accepts these parameter types:

  • string
  • greedy_string
  • player
  • word

If you invent another type, it will not work.

Built-in placeholders are resolved from the command executor

Placeholders like %player_name%, %player_ping%, and %server_name% are generated from the player who ran the command.

Helpful links

commands.yml Structure