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

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

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

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

## Содержание:
Методы для работы с:
- [основными процессами движка](#основные-процессы-движка)
- [контент-паками](#контент-паки) 
- [мирами](#миры)
- [свойствами и настройками](#свойства-и-настройки-движка)
- [точками входа и путями](#точки-входа-и-пути)

## Основные процессы движка
```lua
-- Выполняет один такт основного цикла движка.
app.tick()

-- Ожидает указанное время в секундах, выполняя основной цикл движка.
app.sleep(time: number)

-- Завершает выполнение движка, выводя стек вызовов для ослеживания места вызова функции.
app.quit()

-- Ожидает истинности утверждения (условия), проверяемого функцией,
-- выполняя основной цикл движка.
app.sleep_until(
    -- функция, проверяющее условия завершения ожидания
    predicate: function() -> boolean,
    -- максимальное количество тактов цикла движка, после истечения которых
    -- будет брошено исключение "max ticks exceed"
    [опционально] max_ticks: int = 1e9,
    -- максимальное длительность ожидания в секундах. 
    -- (работает с системным временем, включая test-режим)
    [опционально] timeout: number = 1e9
)
```

## Контент-паки
```lua
-- Проверяет, загружен ли контент.
app.is_content_loaded() -> boolean

-- Возвращает текущую конфигурацию контента (список id паков в порядке загрузки)
app.get_content() -> table<string>

-- Загружает контент на основе текущей конфигурации.
-- Не может быть использован, если контент уже загружен (см. app.reset_content).
app.load_content()

-- Выгружает весь контент, сбрасывая до единственного пака ядра (`core`).
app.reset_content(
    -- Паки, для которых не будут сброшены модули, ивенты и окружение
    [опционально] non_reset_packs: table
)

-- Обновляет конфигурацию паков, проверяя её корректность (зависимости и доступность паков). 
-- Автоматически добавляет и упорядочивает паки в соответствии с зависимостями.
-- Для удаления ВСЕХ паков из конфигурации можно использовать `pack.get_installed()`
app.reconfig_packs(
    -- добавляемые паки
    add_packs: table,
    -- удаляемые паки
    remove_packs: table
)

-- Обновляет конфигурацию паков, автоматически удаляя лишние, добавляя отсутствующие в прошлой конфигурации.
-- Использует app.reconfig_packs.
app.config_packs(
    -- ожидаемый набор паков (без учёта зависимостей)
    packs: table
)
```

## Миры

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

-- Удаляет мир по названию.
app.delete_world(name: string)

-- Открывает мир по названию.
app.open_world(name: string)

-- Переоткрывает мир.
app.reopen_world()

-- Сохраняет мир.
app.save_world()

-- Закрывает мир.
app.close_world(
    -- сохранить мир перед закрытием
    [опционально] save_world: boolean = false
)
```

## Свойства и настройки движка

```lua
-- Возвращает мажорную и минорную версии движка.
app.get_version() -> int, int

-- Возвращает значение настройки.
-- Бросает исключение, если настройки не существует.
app.get_setting(name: string) -> any

-- Устанавливает значение настройки.
-- Бросает исключение, если настройки не существует.
app.set_setting(name: string, value: any)

-- Возвращает таблицу с информацией о настройке.
-- Бросает исключение, если настройки не существует.
app.get_setting_info(name: string) -> table

-- Переводит окно на передний план и устанавливает фокус ввода.
app.focus()
```

## Точки входа и пути

```lua
-- Создаёт файловую систему в памяти.
app.create_memory_device(
    -- имя точки входа
    name: string
)

-- Возвращает список источников контента (путей), в порядке убывания приоритета.
app.get_content_sources() -> table<string>

-- Устанавливает список источников контента (путей). Указывается в порядке убывания приоритета.
app.set_content_sources(sources: table<string>)

-- Сбрасывает список источников контента.
app.reset_content_sources()
```

## Под-экземпляры

```lua
-- Создаёт headless-экземпляр движка с текущим проектом и указанным сценарием.
-- Возвращает id экземпляра. Число живых под-экземпляров, на данный момент, ограничено одним.
app.start_background_instance(
    -- файл сценария
    app_script: string,
    -- файл лога
    output_file: string,
    -- параметры проекта, что будут доступны через vc.get_project_arg(name)
    project_args: table<string, string> | nil,
) -> int

-- Проверяет, жив ли под-экземпляр движка.
app.is_instance_alive(handle: int) -> boolean

-- Останавливает под-экземпляр движка.
-- Возвращает true если экземпляр был жив в момент вызова.
app.terminate_instance(handle: int) -> boolean
```