Custom Commands

What are custom commands?

Custom commands let you extend the script runtime with your own functionality. Once created, they work just like built-in commands.

Key features

• Persistent: Commands remain available across different scripts until explicitly removed
• Reusable: Register once, use in multiple scripts
• Full access: Leverage internal APIs in your commands

Usage

Registering a custom command

// Register a command with:
//   cmd.register_command(name, commandFactory);
//
// Where:
// - name: name of the command
// - commandFactory: factory function that is called with the Command base class, and should return a subclass of Command

cmd.register_command("name", (Command) => {
  return class MyNewCommand extends Command {
    /**
      * Implementation of the command execution logic, called when the command is invoked.
      * @param signal AbortSignal to check for cancellation
      */
    executeImpl(signal) { /* required */
      // this.bot -> Bot
      // this.args -> [] ; arguments passed to the command
      // this.ctx -> CommandExecutor (undocumented)
    }

    toString() { /* required */
      return "Command description";
    }
  }
});

Note

Custom commands don’t have any input validation. Typically, we would do this before a command is registered. As the creator, it’s assumed you understand what’s needed.

Unregistering a custom command

cmd.unregister_command(name);

Example

cmd.register_command('is_in_bank_or_inventory', (Command) => {
  return class IsInBankOrInventoryCommand extends Command {
    executeImpl() {
      // this.args = ["Barber", "hello", "world", ["how", "are", "you"], "today"]
      const item = this.args[0]

      const isInBank = this.bot.bank.contains(item)
      const isInInventory = this.bot.inventory.contains(item)

      if (!(isInBank || isInInventory)) this.ctx.commandIndex++
    }

    toString() {
      return `Item is in bank or inventory: ${this.args[0]}`
    }
  }
})

cmd.is_in_bank_or_inventory(
  'Barber',
  'hello',
  'world',
  ['how', 'are', 'you'],
  'today',
)
cmd.goto_label('yes')
cmd.goto_label('no')

cmd.label('yes')
cmd.log('yes in inventory or bank')
cmd.goto_label('stop')

cmd.label('no')
cmd.log('no in inventory or bank')
cmd.goto_label('stop')

cmd.label('stop')
cmd.log('stop!')
cmd.stop_bot()