From e46d83e092204dc2c3df593b892c86b3f5368673 Mon Sep 17 00:00:00 2001
From: MihailRis <mexaruc@gmail.com>
Date: Sat, 20 Sep 2025 11:29:34 +0300
Subject: [PATCH] add doc/ru/scripting/core_components.md

---
 doc/ru/scripting.md                 |  1 +
 doc/ru/scripting/core_components.md | 89 +++++++++++++++++++++++++++++
 2 files changed, 90 insertions(+)
 create mode 100644 doc/ru/scripting/core_components.md

diff --git a/doc/ru/scripting.md b/doc/ru/scripting.md
index d8f1b3be..95a62007 100644
--- a/doc/ru/scripting.md
+++ b/doc/ru/scripting.md
@@ -45,6 +45,7 @@
 - [Модуль core:bit_converter](scripting/modules/core_bit_converter.md)
 - [Модуль core:data_buffer](scripting/modules/core_data_buffer.md)
 - [Модули core:vector2, core:vector3](scripting/modules/core_vector2_vector3.md)
+- [Встроенные компоненты сущностей](scripting/core_components.md)
 
 ## Аннотации типов данных
 
diff --git a/doc/ru/scripting/core_components.md b/doc/ru/scripting/core_components.md
new file mode 100644
index 00000000..a90cf1d8
--- /dev/null
+++ b/doc/ru/scripting/core_components.md
@@ -0,0 +1,89 @@
+# Встроенные компоненты
+
+## *core:pathfinding*
+
+Компонент для построение путей движения мобов.
+
+```lua
+local pathfinding = entity:require_component("core:pathfinding")
+
+-- Устанавливает цель движения, не сбрасывая текущий маршрут
+pathfinding.set_target(target: vec3)
+
+-- Возвращает текущую цель движения
+pathfinding.get_target() --> vec3
+
+-- Устанавливает высоту преодолимого прыжком препятствия
+pathfinding.set_jump_height(height: number)
+
+-- Возвращает текущий построенный маршрут или nil
+pathfinding.get_route()
+
+-- Сбрасывает текущий построенный маршрут
+pathfinding.reset_route()
+
+-- Возвращает следующую точку маршрута, по текущим координатам.
+-- (следует использовать компонент core:mob - функция mob.follow_waypoints)
+pathfinding.next_waypoint() --> vec3 или nil
+
+-- Устанавливает интервал перестройки маршрута в тактах обновления.
+pathfinding.set_refresh_interval(interval: number)
+```
+
+## *core:mob*
+
+Компонент для управления движением (включая полёт) и вращением мобов.
+
+```lua
+local mob = entity:require_component("core:mob")
+
+-- Выполняет прыжок с силой jump_force * multiplier
+mob.jump([опционально] multiplier: number = 1.0)
+
+
+-- Вертикальное движение (работает в полёте или в плавании (в будущем))
+mob.move_vertical(
+    -- Скорость вертикального движения
+    speed: number,
+    -- Текущая скорость сущности (для минимизации вызовов rigidbody:get_vel())
+    [опционально] current_velocity
+)
+
+-- Горизонтальное движение
+mob.go(
+    -- 2D вектор направления движения
+    dir: vec2,
+    -- Множитель скорости
+    speed_multiplier: number,
+    -- Бег
+    sprint: bool,
+    -- Присядь
+    crouch: bool,
+    -- Текущая скорость сущности (для минимизации вызовов rigidbody:get_vel())
+    [опционально] current_velocity
+)
+
+-- Меняет направление взгляда сущности, направляя на указанную точку
+mob.look_at(
+    -- Целевая точка
+    point: vec3,
+    -- Менять ли направление всей сущности
+    change_dir: bool = false
+)
+
+-- Движение по построенному маршруту.
+-- Если не указан pathfinding, требуется наличие у сущности компонента core:pathfinding
+mob.follow_waypoints(
+    -- Возможная замена компонента pathfinding
+    [опционально] pathfinding
+)
+
+-- Устанавливает направление всей сущности
+mob.set_dir(dir: vec3)
+
+-- Проверяет, включён ли режим полёта
+mob.is_flight() --> bool
+
+-- Включает/выключает режим полёта
+mob.set_flight(flag: bool)
+```