VoxelEngine/doc/en/console.md

Console

To work with the command interpreter, use the console library.

When sending a command via the standard console (core:console layout):

1. the allow-cheats rule is checked
2. the player, pos.x|y|z, entity.id, entity.selected variables are automatically set.
3. the command handler is called - console.submit or the default one.

The default handler calls console.execute, passing the result to the console.log call.

Commands creation

To create a console command, use the following function:

console.add_command(scheme: str, executor: function)

Scheme has the following syntax:

name positional arguments {keyword arguments}

Name may contain:

• latin letters
• digits (except the first character)
• ., _, -

Positional arguments are separated by spaces and have the following syntax:

name:type                        (option 1)
name:type=default                (option 2)
name:type~origin                 (option 3)
name:type=default~origin         (option 4)

Available types:

• int - integer
• num - floating-point number
• str - string
• sel - selector (object id represented by an integer)
• enum - enumeration

Options 3 and 4 show the ~ operator that allows you to use relative values. Origin - the value relative to which the user will be specified. For example, the player's position.

The relative operator only works with numbers (num or int)

Variables assigned via console.set can be specified as origin values.

Example:

x:num~pos.x

Variables may be specified as default values ​​using the $ prefix:

t:int=$time

Enumerations are declared the following way:

mode:[replace|destruct|none]

Or with a variable:

mode:enum $modes

Selectors are specified with the @ prefix. At the moment they are unused due to the lack of an object model. Should be made optional and use variables:

obj:sel=$obj.id # obj.id - player id

Keyword arguments are specified in a special block, delimited by curly braces { }, following the same pattern as positional arguments.

Example:

eval name:str="World" {greeting:str='Hello'}

Command scheme examples

Schemes of standard commands can be found in the file res/script/stdcmd.lua.

Example - command tp:

tp obj:sel=$obj.id x:num~pos.x y:num~pos.y z:num~pos.z

Full lua code of the command creation:

console.add_command(
    "tp obj:sel=$obj.id x:num~pos.x y:num~pos.y z:num~pos.z",
    "Teleport object",
    function (args, kwargs)
        player.set_pos(unpack(args))
    end
)

• Checked values ​​of positional arguments are passed to args.
• A table of keyword argument values ​​is passed to kwargs.

The command interpreter performs type checking and casting automatically.