# Библиотека *app*

Библиотека для высокоуровневого управления работой движка, доступная только в режиме сценария или теста.

Имя сценария/теста без пути и расширения доступен как `app.script`. Путь к файлу можно получить как:
```lua
local filename = "script:"..app.script..".lua"
```

Так как управляющий сценарий может не принадлежать ни одному из паков, он не относиться к своему паку и имеет собственное пространство имён, в котором доступны все глобальные функции и таблицы, а также библиотека `app`.

## Функции

```lua
app.tick()
```

Выполняет один такт основного цикла движка.

```lua
app.sleep(time: number)
```

Ожидает указанное время в секундах, выполняя основной цикл движка.

```lua
app.sleep_until(
    -- функция, проверяющее условия завершения ожидания
    predicate: function() -> bool,
    -- максимальное количество тактов цикла движка, после истечения которых
    -- будет брошено исключение "max ticks exceed"
    [опционально] max_ticks = 1e9,
    -- максимальное длительность ожидания в секундах. 
    -- (работает с системным временем, включая test-режим)
    [опционально] timeout = 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.config_packs(
    -- ожидаемый набор паков (без учёта зависимостей)
    packs: table
)
```

Обновляет конфигурацию паков, автоматически удаляя лишние, добавляя отсутствующие в прошлой конфигурации.
Использует app.reconfig_packs.

```lua
app.is_content_loaded() -> bool
```

Проверяет, загружен ли контент.

```lua
app.new_world(
    -- название мира, пустая строка приведёт к созданию безымянного мира
    name: str,
    -- зерно генерации
    seed: str,
    -- название генератора
    generator: str
    -- id локального игрока
    [опционально] local_player: int=0
)
```

Создаёт новый мир и открывает его.

```lua
app.open_world(name: str)
```

Открывает мир по названию.

```lua
app.reopen_world()
```

Переоткрывает мир.

```lua
app.save_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
}
```

Возвращает таблицу с информацией о настройке. Бросает исключение, если настройки не существует.