add app library docs

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
+}
+```
+
+Возвращает таблицу с информацией о настройке. Бросает исключение, если настройки не существует.