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

Библиотека *pathfinding* предоставляет функции для работы с системой поиска пути в игровом мире. Она позволяет создавать и управлять агентами, которые могут находить маршруты между точками в мире.

При использовании в логике сущностей следует использовать компонент `core:pathfinding`.

## Компонент `core:pathfinding`

```lua
local pf = entity:get_component("core:pathfinding")

--- ...
local x = ...
local y = ...
local z = ...

--- Установка цели для агента
pf.set_target({x, y, z})

--- Получение текущей цели агента
local target = pf.get_target() --> vec3 или nil
--- ...

--- Получение текущего маршрута агента
local route = pf.get_route() --> table<vec3> или nil
--- ...
```

## Функции библиотеки

```lua
--- Создание нового агента. Возвращает идентификатор созданного агента
local agent = pathfinding.create_agent() --> int

--- Удаление агента по идентификатору. Возвращает true, если агент существовал, иначе false
pathfinding.remove_agent(agent: int) --> bool

--- Установка состояния агента (включен/выключен)
pathfinding.set_enabled(agent: int, enabled: bool)

--- Проверка состояния агента. Возвращает true, если агент включен, иначе false
pathfinding.is_enabled(agent: int) --> bool

--- Создание маршрута на основе заданных точек. Возвращает массив точек маршрута
pathfinding.make_route(start: vec3, target: vec3) --> table<vec3>

--- Асинхронное создание маршрута на основе заданных точек.
--- Функция позволяет выполнять поиск пути в фоновом режиме, не блокируя основной поток выполнения
pathfinding.make_route_async(agent: int, start: vec3, target: vec3)

--- Получение маршрута, который агент уже нашел. Используется для получения маршрута после асинхронного поиска.
--- Если поиск ещё не завершён, возвращает nil. Если маршрут не найден, возвращает пустую таблицу.
pathfinding.pull_route(agent: int) --> table<vec3> или nil

--- Установка максимального количества посещенных блоков для агента. Используется для ограничения объема работы алгоритма поиска пути.
pathfinding.set_max_visited(agent: int, max_visited: int)

--- Установка перечня тегов, определяющих избегаемые блоки
pathfinding.set_avoided_tags(agent: int, tags: table<string>)
```