Commands

Plugins can add console commands. A command is typed with the plugin name as a prefix: a command spawn registered by the plugin my-plugin is typed as my-plugin_spawn. The full name is lowercase, and spaces in the plugin name become _.

Commands are removed when the plugin unloads.

Functions

Balltze.registerCommand

Balltze.registerCommand(name, help, paramsHelp, autosave, minArgs, maxArgs, canCallFromConsole, isPublic, callback)

Parameter	Type	Description
name	string	Name of the command, without the plugin prefix.
help	string	Description of the command. Must not be empty.
paramsHelp	string or nil	Description of the parameters, such as "<name: string> <count: integer>".
autosave	boolean	Save the arguments of every successful call. See Saved values.
minArgs	integer	Minimum number of arguments.
maxArgs	integer	Maximum number of arguments.
canCallFromConsole	boolean	Whether the command shows up in the console's TAB completion.
isPublic	boolean	Whether other plugins can call the command with Balltze.executeCommand.
callback	function(args)	Runs the command.

callback receives a table with the arguments, as strings. It must return a true value when the command succeeded; false or nil prints an error in the console. Calls with too few or too many arguments are rejected before the callback runs. Arguments with spaces can be quoted.

Balltze.registerCommand("greet", "Greets someone", "<name: string>", false, 1, 1, true, false,
    function(args)
        Engine.terminal.print("Hello, {}!", args[1])
        return true
    end
)

Balltze.executeCommand

Balltze.executeCommand(command)

Runs a command line, such as "my-plugin_greet John". The command must be written with its full name. Only plugin commands can be run this way, not the game's script functions (use Engine.script.execute for those) nor Balltze's own balltze_ commands. Commands of other plugins must be public. Raises an error when the command does not exist.

Balltze.loadSettings

Balltze.loadSettings()

Calls every command of the plugin that has a saved value, with that value as its arguments. It is not called automatically; call it at the end of the main file to restore the plugin's settings.

Saved values

When autosave is true and the command takes at least one argument:

• Every successful call saves its arguments in settings.json, in the plugin folder, under commands.<name>.
• Typing the command without arguments prints its saved value instead of running it.
• Balltze.loadSettings() replays the saved values.

Balltze.registerCommand("volume", "Sets the volume", "<volume: number>", true, 1, 1, true, false,
    function(args)
        volume = tonumber(args[1])
        return volume ~= nil
    end
)

-- Restore the saved volume.
Balltze.loadSettings()

Built-in commands

balltze_reload_plugins

Syntax: balltze_reload_plugins

Reloads every loaded plugin whose manifest has "reloadable": true. See Reloading.