From 561f6f0ea74ba628d828a5a2c09312a4f4d5ba6e Mon Sep 17 00:00:00 2001
From: MihailRis <mexaruc@gmail.com>
Date: Thu, 13 Jun 2024 20:27:55 +0300
Subject: [PATCH] add doc/en/console.md

---
 doc/en/console.md | 109 ++++++++++++++++++++++++++++++++++++++++++++++
 doc/ru/console.md |   4 +-
 2 files changed, 111 insertions(+), 2 deletions(-)
 create mode 100644 doc/en/console.md

diff --git a/doc/en/console.md b/doc/en/console.md
new file mode 100644
index 00000000..04d3d48d
--- /dev/null
+++ b/doc/en/console.md
@@ -0,0 +1,109 @@
+# Console
+
+To work with the command interpreter, use the **console** library.
+
+## 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.
diff --git a/doc/ru/console.md b/doc/ru/console.md
index a279be61..a142f84f 100644
--- a/doc/ru/console.md
+++ b/doc/ru/console.md
@@ -1,6 +1,6 @@
 # Консоль
 
-Для работы с командным интерпретатором предоставляется библиотека **console**
+Для работы с командным интерпретатором предоставляется библиотека **console**.
 
 ## Создание команд
 
@@ -83,7 +83,7 @@ eval name:str="World" {greeting:str='Hello'}
 
 ## Примеры схем команд
 
-Схемы существующих команд можно найти в файле `res/script/stdcmd.lua`.
+Схемы стандартных команд можно найти в файле `res/script/stdcmd.lua`.
 
 Пример - команда **tp**: