From bd9f3d86cac457ad11244b728d83ac8ba9912336 Mon Sep 17 00:00:00 2001
From: MihailRis <mexaruc@gmail.com>
Date: Tue, 8 Sep 2026 21:08:28 +0300
Subject: [PATCH] add initial animation docs (test)

---
 doc/ru/animation.md                       | 34 +++++++++++++++++++++++
 doc/ru/main-page.md                       |  1 +
 doc/ru/scripting.md                       |  1 +
 doc/ru/scripting/builtins/libanimation.md | 21 ++++++++++++++
 doc/ru/vca.md                             |  2 ++
 5 files changed, 59 insertions(+)
 create mode 100644 doc/ru/animation.md
 create mode 100644 doc/ru/scripting/builtins/libanimation.md

diff --git a/doc/ru/animation.md b/doc/ru/animation.md
new file mode 100644
index 000000000..45e69a0e3
--- /dev/null
+++ b/doc/ru/animation.md
@@ -0,0 +1,34 @@
+# Анимация
+
+Для того, чтобы загрузить дорожку анимации для скелета сущности ([см. риггинг](rigging.md)) или камеры ([см. камеры](scripting/builtins/libcameras.md)) её, как любой, незагружаемый по-умолчанию, следует указать в [preload.json пака](assets-preload.md) в секции animation.
+
+На данный момент, движком поддерживается один формат описания анимации - [VCA](vca.md).
+
+Общий API для работы с анимацией, как и другими продолжительными событиями, существует библиотека animation, доступная в виде глобальной переменной.
+
+Самый простой способ анимировать что-то:
+
+```lua
+animation.play("имя_анимации", цель)
+```
+
+Где цель может быть камерой:
+
+```lua
+local camera = cameras.get(cameras.index("пак:имя_камеры"))
+animation.play("имя_анимации", camera)
+```
+
+Или скелет сущности:
+
+```lua
+animation.play("имя_анимации", entity.skeleton)
+```
+
+Но для скелетов, подразумевающих переключение между состояниями (те же мобы), лучше использовать [компонент](scripting/ecs.md), реализующий простую машину состояний для анимации - [core:animator](#компонент-coreanimator)
+
+Более подробно функциональность библиотеки animation описана [в соответствующем разделе](scripting/builtins/libanimation.md)
+
+## Компонент core:animator
+
+Компонент находится в работе. Зайдите позже.
diff --git a/doc/ru/main-page.md b/doc/ru/main-page.md
index 6f264ea87..916202151 100644
--- a/doc/ru/main-page.md
+++ b/doc/ru/main-page.md
@@ -6,6 +6,7 @@
 ## Разделы
 
 - [XML разметка интерфейса](xml-ui-layouts.md)
+- [Анимация](animation.md)
 - [Аудио](audio.md)
 - [Движок генерации мира](world-generator.md)
 - [Консоль](console.md)
diff --git a/doc/ru/scripting.md b/doc/ru/scripting.md
index 1e6d73098..1959c4649 100644
--- a/doc/ru/scripting.md
+++ b/doc/ru/scripting.md
@@ -9,6 +9,7 @@
 - [Свойства и методы UI элементов](scripting/ui.md)
 - [Сущности и компоненты](scripting/ecs.md)
 - [Библиотеки](#)
+    - [animation](scripting/builtins/libanimation.md)
     - [app](scripting/builtins/libapp.md)
     - [assets](scripting/builtins/libassets.md)
     - [base64](scripting/builtins/libbase64.md)
diff --git a/doc/ru/scripting/builtins/libanimation.md b/doc/ru/scripting/builtins/libanimation.md
new file mode 100644
index 000000000..25048c151
--- /dev/null
+++ b/doc/ru/scripting/builtins/libanimation.md
@@ -0,0 +1,21 @@
+# Библиотека *animation*
+
+Библиотека для работы с анимацией и решения некоторых сопутствующих задач.
+
+```lua
+-- Воспроизводит анимацию на указанном объекте
+animation.play(
+    -- Имя дорожки анимации
+    name: string,
+    -- Цель, что будет анимирована
+    target: Skeleton | Camera
+)
+```
+
+```lua
+-- Запускает корутину, обновляющуюся вне паузы и завершающуюся вместе с выходом из мира.
+animation.action(
+    -- Целевая асинхронная функция
+    func: function()
+)
+```
diff --git a/doc/ru/vca.md b/doc/ru/vca.md
index 719474c0a..eb1f77b07 100644
--- a/doc/ru/vca.md
+++ b/doc/ru/vca.md
@@ -36,6 +36,8 @@ VCA файл состоит из набора директив, порядок 
 - `duration` - явно указанная длительность в секундах (требуется указание fps при наличии ключевых кадров)
 - `rotation-order` - указывает порядок применения углов Эйлера при вращении (так как порядок директив не учитывается форматом). Примеры: XYZ, ZYX, YZX.
 
+Мета-информация применяется глобально. Поведение не зависит от её положения в файле, но рекомендуется располагать её в начале.
+
 ## Кривые с ключевыми кадрами
 
 Требуется через атрибут `curve` указать тип кривой: