add app library docs

doc/en/scripting/builtins/libapp.md

@@ -0,0 +1,130 @@
+# *app* library
+
+A library for high-level engine control, available only in script/test mode.
+
+The script/test name without path and extension is available as `app.script`. The file path can be obtained as:
+```lua
+local filename = "script:"..app.script..".lua"
+```
+
+## Functions
+
+```lua
+app.tick()
+```
+
+Executes one tick of the engine main loop.
+
+```lua
+app.sleep(time: number)
+```
+
+Waits for the specified time in seconds, executing the engine main loop.
+
+```lua
+app.sleep_until(
+    -- function that checks the wait finishing condition
+    predicate: function() -> bool,
+    -- maximum number of engine cycle ticks, after which
+    -- an exception "max ticks exceed" will be thrown
+    [optional] max_ticks = 1e9
+)
+```
+
+Waits for the condition checked by the function to be true, executing the engine main loop.
+
+```lua
+app.quit()
+```
+
+Quits the engine, printing the call stack to track where the function was called.
+
+```lua
+app.reconfig_packs(
+    -- packs to add
+    add_packs: table,
+    -- packs to remove
+    remove_packs: table
+)
+```
+
+Updates the packs configuration, checking its correctness (dependencies and packs existence).
+
+To remove all packs from the configuration, you can use `pack.get_installed()`:
+
+```lua
+app.reconfig_packs({}, pack.get_installed())
+```
+
+In this case, `base` will also be removed from the configuration.
+
+```lua
+app.new_world(
+    -- world name
+    name: str,
+    -- seed of generation
+    seed: str,
+    -- name of generator
+    generator: str
+)
+```
+
+Creates a new world and opens it.
+
+```lua
+app.open_world(name: str)
+```
+
+Opens a world by name.
+
+```lua
+app.reopen_world()
+```
+
+Reopens the world.
+
+```lua
+app.close_world(
+    -- save the world before closing
+    [optional] save_world: bool=false
+)
+```
+
+Closes the world.
+
+```lua
+app.delete_world(name: str)
+```
+
+Deletes a world by name.
+
+```lua
+app.get_version() -> int, int
+```
+
+Returns the major and minor engine versions.
+
+```lua
+app.get_setting(name: str) -> value
+```
+
+Returns the value of a setting. Throws an exception if the setting does not exist.
+
+```lua
+app.set_setting(name: str, value: value)
+```
+
+Sets the value of a setting. Throws an exception if the setting does not exist.
+
+```lua
+app.get_setting_info(name: str) -> {
+    -- default value
+    def: value
+    -- minimum value
+    [numeric settings only] min: number,
+    -- maximum value
+    [numeric settings only] max: number
+}
+```
+
+Returns a table with information about the setting. Throws an exception if the setting does not exist.

doc/ru/scripting/builtins/libapp.md

@@ -0,0 +1,131 @@
+# Библиотека *app*
+
+Библиотека для высокоуровневого управления работой движка, доступная только в режиме сценария или теста.
+
+Имя сценария/теста без пути и расширения доступен как `app.script`. Путь к файлу можно получить как:
+```lua
+local filename = "script:"..app.script..".lua"
+```
+
+## Функции
+
+```lua
+app.tick()
+```
+
+Выполняет один такт основного цикла движка.
+
+```lua
+app.sleep(time: number)
+```
+
+Ожидает указанное время в секундах, выполняя основной цикл движка.
+
+```lua
+app.sleep_until(
+    -- функция, проверяющее условия завершения ожидания
+    predicate: function() -> bool,
+    -- максимальное количество тактов цикла движка, после истечения которых
+    -- будет брошено исключение "max ticks exceed"
+    [опционально] max_ticks = 1e9
+)
+```
+
+Ожидает истинности утверждения (условия), проверяемого функцией, выполнячя основной цикл движка.
+
+```lua
+app.quit()
+```
+
+Завершает выполнение движка, выводя стек вызовов для ослеживания места вызова функции.
+
+```lua
+app.reconfig_packs(
+    -- добавляемые паки
+    add_packs: table,
+    -- удаляемые паки
+    remove_packs: table
+)
+```
+
+Обновляет конфигурацию паков, проверяя её корректность (зависимости и доступность паков).
+
+Для удаления всех паков из конфигурации можно использовать `pack.get_installed()`:
+
+```lua
+app.reconfig_packs({}, pack.get_installed())
+```
+
+В этом случае из конфигурации будет удалён и `base`.
+
+```lua
+app.new_world(
+    -- название мира
+    name: str,
+    -- зерно генерации
+    seed: str,
+    -- название генератора
+    generator: str
+)
+```
+
+Создаёт новый мир и открывает его.
+
+```lua
+app.open_world(name: str)
+```
+
+Открывает мир по названию.
+
+```lua
+app.reopen_world()
+```
+
+Переоткрывает мир.
+
+```lua
+app.close_world(
+    -- сохранить мир перед закрытием
+    [опционально] save_world: bool=false
+)
+```
+
+Закрывает мир.
+
+```lua
+app.delete_world(name: str)
+```
+
+Удаляет мир по названию.
+
+```lua
+app.get_version() -> int, int
+```
+
+Возвращает мажорную и минорную версии движка.
+
+```lua
+app.get_setting(name: str) -> value
+```
+
+Возвращает значение настройки. Бросает исключение, если настройки не существует.
+
+```lua
+app.set_setting(name: str, value: value)
+```
+
+Устанавливает значение настройки. Бросает исключение, если настройки не существует.
+
+
+```lua
+app.get_setting_info(name: str) -> {
+    -- значение по-умолчанию
+    def: value
+    -- минимальное значение
+    [только числовые настройки] min: number,
+    -- максимальное значение
+    [только числовые настройки] max: number
+}
+```
+
+Возвращает таблицу с информацией о настройке. Бросает исключение, если настройки не существует.