117 lines
2.8 KiB
Markdown
117 lines
2.8 KiB
Markdown
# 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:
|
||
|
||
```python
|
||
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:
|
||
|
||
```python
|
||
x:num~pos.x
|
||
```
|
||
|
||
Variables may be specified as default values using the `$` prefix:
|
||
|
||
```python
|
||
t:int=$time
|
||
```
|
||
|
||
Enumerations are declared the following way:
|
||
|
||
```python
|
||
mode:[replace|destruct|none]
|
||
```
|
||
|
||
Or with a variable:
|
||
|
||
```python
|
||
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:
|
||
|
||
```python
|
||
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:
|
||
|
||
```python
|
||
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**:
|
||
|
||
```python
|
||
tp obj:sel=$obj.id x:num~pos.x y:num~pos.y z:num~pos.z
|
||
```
|
||
|
||
Full lua code of the command creation:
|
||
|
||
```lua
|
||
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.
|