update docs

doc/en/scripting.md

@@ -31,6 +31,7 @@ Subsections:
     - [mat4](scripting/builtins/libmat4.md)
     - [network](scripting/builtins/libnetwork.md)
     - [pack](scripting/builtins/libpack.md)
+    - [pathfinding](scripting/builtins/libpathfinding.md)
     - [player](scripting/builtins/libplayer.md)
     - [quat](scripting/builtins/libquat.md)
     - [rules](scripting/builtins/librules.md)

doc/en/scripting/builtins/libpathfinding.md

@@ -0,0 +1,57 @@
+# *pathfinding* library
+
+The *pathfinding* library provides functions for working with the pathfinding system in the game world. It allows you to create and manage agents finding routes between points in the world.
+
+When used in entity logic, the `core:pathfinding` component should be used.
+
+## `core:pathfinding` component
+
+```lua
+local pf = entity:get_component("core:pathfinding")
+
+--- ...
+local x = ...
+local y = ...
+local z = ...
+
+--- Set the target for the agent
+pf.set_target({x, y, z})
+
+--- Get the current target of the agent
+local target = pf.get_target() --> vec3 or nil
+--- ...
+
+--- Get the current route of the agent
+local route = pf.get_route() --> table<vec3> or nil
+--- ...
+```
+
+## Library functions
+
+```lua
+--- Create a new agent. Returns the ID of the created agent
+local agent = pathfinding.create_agent() --> int
+
+--- Delete an agent by ID. Returns true if the agent existed, otherwise false
+pathfinding.remove_agent(agent: int) --> bool
+
+--- Set the agent state (enabled/disabled)
+pathfinding.set_enabled(agent: int, enabled: bool)
+
+--- Check the agent state. Returns true if the agent is enabled, otherwise false
+pathfinding.is_enabled(agent: int) --> bool
+
+--- Create a route based on the given points. Returns an array of route points
+pathfinding.make_route(start: vec3, target: vec3) --> table<vec3>
+
+--- Asynchronously create a route based on the given points.
+--- This function allows to perform pathfinding in the background without blocking the main thread of execution
+pathfinding.make_route_async(agent: int, start: vec3, target: vec3)
+
+--- Get the route that the agent has already found. Used to get the route after an asynchronous search.
+--- If the search has not yet completed, returns nil. If the route is not found, returns an empty table.
+pathfinding.pull_route(agent: int) --> table<vec3> or nil
+
+--- Set the maximum number of visited blocks for the agent. Used to limit the amount of work of the pathfinding algorithm.
+pathfinding.set_max_visited(agent: int, max_visited: int)
+```

doc/ru/scripting.md

@@ -31,6 +31,7 @@
     - [mat4](scripting/builtins/libmat4.md)
     - [network](scripting/builtins/libnetwork.md)
     - [pack](scripting/builtins/libpack.md)
+    - [pathfinding](scripting/builtins/libpathfinding.md)
     - [player](scripting/builtins/libplayer.md)
     - [quat](scripting/builtins/libquat.md)
     - [rules](scripting/builtins/librules.md)

doc/ru/scripting/builtins/libpathfinding.md

@@ -0,0 +1,57 @@
+# Библиотека *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)
+```