Documentation

Learn how to install and use LiquidBounce with our comprehensive guides

Creating Commands

Commands created using the script API work like the built-in client commands. In contrast to modules, commands are intended to perform one well-defined action once when they are executed.

Registering a command

Just like modules, commands have to be registered with the client. This must be done by calling registerCommand on your script's instance passing an object containing various options.

script.registerCommand(options);

The object passed to registerCommand may contain the following options:

PropertyDescriptionRequiredTypeDefault
namePrimary name of the command.Yesstring
onExecuteFunction called when the command is executed. Without it, the command only holds subcommands.Nofunction
aliasesArray containing additional names of the command.Noarray[]
parametersArray containing parameters of the command. Refer to 'Creating parameters'.Noarray[]
subcommandsArray containing additional subcommands.Noarray[]

Creating parameters

Parameters accept arguments passed in by the user. By default, no validation is performed. Arguments given by the user will be passed to onExecute as strings, in the order of the parameters. Optional parameters the user left out are not passed.

Required parameters cannot follow optional ones, and parameter names must be unique. A vararg parameter with a validate function passes an array of the validated values; without validate it passes the rest of the input as one string.

Parameters are created as JavaScript objects and may have the following options:

PropertyDescriptionRequiredTypeDefault
nameName of the parameter.Yesstring
requiredWhether the parameter is required or optional.Nobooleanfalse
varargWhether this parameter accepts a variable amount of arguments. Only possible with the last parameter.Nobooleanfalse
getCompletionsFunction returning completion candidates for partial input.Nofunction
validateFunction validating the parameter and possibly applying transformations.Nofunction

Using validators

Validators may be used to ensure an argument provided by the user is of the expected format. They may also be used to perform a parameter transformation substituting the string argument with one that has been processed in some way. To enable parameter validation, set a validate function in a parameter's options.

Using builtin validators

LiquidBounce's script API provides a set of builtin validators for common use cases. For more information on builtin validators, see ParameterValidator.

Example: Command using the built-in module validator.

script.registerCommand({
  name: "description",
  parameters: [{
    name: "module",
    required: true,
    validate: ParameterValidator.module,
  }],
  onExecute(mod) {
    Client.displayChatMessage(`Description of module ${mod.name} is '${mod.description.get()}'`);
  }
});

Writing custom validators

Validators are functions that accept an argument given by the user and validate its integrity. They may also substitute it with a processed value which will be passed to onExecute instead.

Writing a custom validator involves creating a function which accepts the raw string argument as a parameter and returns an object indicating whether the argument has been accepted and either a substitution value or an error message to display.

If the argument has been accepted, an object of the following structure has to be returned:

{
  accept: true,
  value: processedArgument
}

If the argument has been rejected, an object of the following structure has to be returned instead:


{
  accept: false,
  error: "Argument did not fulfill expected criteria"
}

Example: Implementing an integer validator. The script API also has a built-in validator for this.

script.registerCommand({
  name: "integer",
  parameters: [{
    name: "value",
    required: true,
    validate(arg) {
      const integerRegex = /^-?\d+$/;
      if (integerRegex.test(arg)) {
        return {
          accept: true,
          value: parseInt(arg),
        };
      } else {
        return {
          accept: false,
          error: `'${arg}' is not a valid integer`
        };
      }
    }
  }],
  onExecute(integer) {
    Client.displayChatMessage(`typeof ${integer} is ${typeof integer}`);
  }
});

Using auto completion

Command parameters support tab completion. To use it, set getCompletions. It expects a function accepting two parameters, the partial input for the current parameter (what the user has entered so far) and an array with the command's name (and parent command names), the arguments entered before this parameter and the partial input, and returns an array of completion candidates.

Example: A command accepting only Axolotl, Capybara, and Snek as its first parameter.

const acceptedAnimals = ["Axolotl", "Capybara", "Snek"];
script.registerCommand({
  name: "animal",
  parameters: [{
    name: "value",
    required: true,
    validate(arg) {
      if (acceptedAnimals.includes(arg)) {
        return {
          accept: true,
          value: arg,
        };
      } else {
        return {
          accept: false,
          error: `Only the following animals are acceptable: ${acceptedAnimals.join(", ")}`,
        };
      }
    },
    getCompletions(begin, args) {
      return acceptedAnimals.filter(a => a.startsWith(begin));
    }
  }],
  onExecute(animal) {
    Client.displayChatMessage(`Petting the ${animal}`);
  }
});

Complex example

The following example command uses all supported API features. It may be used as a reference when developing.

const acceptedAnimals = ["Axolotl", "Capybara", "Snek"];
script.registerCommand({
  name: "myCommand",
  aliases: ["exampleCommand", "sampleCMD"], // .exampleCommand and .sampleCMD will both work to execute this command.
  // No onExecute: .myCommand is not executable directly. It only holds subcommands.
  subcommands: [{
      name: "math",
      subcommands: [{
          name: "div",
          aliases: ["divide"],
          parameters: [{
              name: "x",
              required: true,
              validate: ParameterValidator.integer
            },
            {
              name: "y",
              required: true,
              validate: ParameterValidator.integer
            }
          ],
          onExecute(x, y) {
            Client.displayChatMessage(`${x} divided by ${y} is ${x / y}`);
          }
        },
        {
          name: "sqrt",
          parameters: [{
            name: "x",
            required: true,
            validate: ParameterValidator.positiveInteger
          }],
          onExecute(x) {
            Client.displayChatMessage(`Square root of ${x} is ${Math.sqrt(x)}`);
          }
        },
        {
          name: "sum",
          parameters: [{
            name: "numbers",
            required: true,
            vararg: true,
            validate: ParameterValidator.integer
          }],
          onExecute(args) {
            Client.displayChatMessage(`Sum ${args.join(" + ")} is ${args.reduce((s, a) => s + a, 0)}`);
          }
        }
      ]
    },
    {
      name: "animal",
      parameters: [{
        name: "value",
        required: true,
        validate(arg) {
          if (acceptedAnimals.includes(arg)) {
            return {
              accept: true,
              value: arg,
            };
          } else {
            return {
              accept: false,
              error: `Only the following animals are acceptable: ${acceptedAnimals.join(", ")}`,
            };
          }
        },
        getCompletions(begin, args) {
          return acceptedAnimals.filter(a => a.startsWith(begin));
        }
      }],
      onExecute(animal) {
        Client.displayChatMessage(`Petting the ${animal}`);
      }
    }
  ]
});

Last updated: 2026-11-11, based on source code