# VCA

Текстовый формат анимации, использующий синтаксис [VCM](vcm.md).

VCA файл состоит из набора директив, порядок следования которых не влияет на порядок применение трансформаций.

Директивы применяются к переданной цели, которая может быть скелетом сущности и камерой.
При использовании скелета, в директиве указывается имя кости через атрибут `bone`:

```vcd
@move bone имя_кости ...
```

Директивы отвечают за отдельные скалярные значения, такие как x, y, z и т.д., указываемые через атрибут `by`:

```vcd
@move bone hand by y ...
```

На данный момент доступны два вида описания кривых, дающих значение `f(t) = x` где t - время:
- [кривые с ключевыми кадрами (curve)](#кривые-с-ключевыми-кадрами)
- [кривые через выражения (func)](#кривые-через-выражения)

## Директивы анимации

- `@move` - смещение объекта/кости
- `@rotate` - поворот объекта/кости
- `@scale` - масштабирование объекта/кости (множитель)
- `@zoom` - масштаб камеры (множитель)
- `@texture` - смена динамически-назначаемой текстуры (см. [skeleton:set_texture](scripting/ecs.md#skeleton))

## Мета-информация

Информация о анимации в файле настраивается через директиву `configure`:
- `fps` - частота кадров, являющаяся делителем при рассчёте длительности
- `frames` - число кадров анимации, являющееся делимым при рассчёте длительности
- `duration` - явно указанная длительность в секундах (требуется указание fps при наличии ключевых кадров)
- `rotation-order` - указывает порядок применения углов Эйлера при вращении (так как порядок директив не учитывается форматом). Примеры: XYZ, ZYX, YZX.

Мета-информация применяется глобально. Поведение не зависит от её положения в файле, но рекомендуется располагать её в начале.

## Дополнительно

- `curve` - объявляет пользовательский тип кривой. Указывается имя кривой `name` и выражение вычисления значения `func`.

В выражении доступны два ключа `kl`, `kr` и значение `t` в диапазоне [0..1].

Пример:

`@curve test-linear func (kl.value + (kr.value - kl.value) * t)`

Пользовательские кривые указываются с префиксом `.`. Пример: `@move by y curve .test-linear {...}`.

## Кривые с ключевыми кадрами

Требуется через атрибут `curve` указать тип кривой:
- `const` - значения не интерполируются, сменяясь в момент достижения ключевого кадра
- `linear` - ломанная линия, используется линейная интерполяция
- `bezier` - ключевые кадры кривой Безье с явно указанными левой и правой касательными (lx, ly, rx, ry)

Ключевые кадры описываются в последующем `{...}` блоке в виде упорядоченных `@key` директив:

```vcd
@rotate by z curve linear {
    @key ...
    @key ...
}
```

Ключевой кадр должен содержать номер кадра `frame` и значенин `value`. Для `bezier` кадров также описываются касательные.

Пример для `curve bezier`: 
```vcd
@key frame 138 value 53.00411 lx 127.067 ly 53.00411 rx 138.001 ry 53.00411
```

Для директивы texture всё проще. Пример:

```vcd
@texture name $0 {
    @key frame 0 value entities/tireman:face_0
    @key frame 24 value entities/tireman:face_1
}
```

> entities/tireman здесь - имя текстурного атласа, в котором находятся face_\* текстуры.
> Текстура не обязательно должна находиться в атласе.

Если вы не хотите ограничивать длительность анимации через `configure`, но хотите зациклить анимацию по ключевым кадрам для конкретной линии, то можно использовать параметр `period` для указания периода повторения анимации в кадрах. Пример:

```vcd
@move by y curve linear period 24 {
    @key frame 0 value 0
    @key frame 12 value 1
    @key frame 24 value 0
}
```

## Кривые через выражения

Через атрибут описывается функция `f(t) = x` где t - время в секундах.

Пример: `func (sin(t * 2.5) + pi)`.

Операции доступные в выражениях:

- `a + b` - сложение
- `a * b` - умножение
- `a / b` - деление
- `a % b` - деление по модулю
- `a ^ b` - возведение в степень

Константы доступные в выражениях:

- `pi` число π
- `e` число Эйлера

Функции доступные в выражениях:

- `sin(x)` - синус от x
- `cos(x)` - косинус от x
- `tan(x)` - тангенс от x
- `noise(x, octaves)` - быстрый одномерный шум от x с указанным числом октав
- `noise2d(x, y, octaves)` - двумерный шум от x,y с указанным числом октав
- `sign(x)` - целое число, указывающее знак x (-1/0/1)
- `rand(low, high)` - псевдослучайное дробное число в диапазоне от low до high
- `round(x, places)` - округляет значение x до указанного количества знаков после запятой places (опционально).
- `floor(x)` - округляет значение x до ближайшего меньшего целого
- `ceil(x)` - округляет значение x до ближайшего большего целого
- `exp(x)` - $e^{x}$
- `min(x, ...)` - выбирает наименьшее значение из переданных аргументов
- `max(x, ...)` - выбирает наибольшее значение из переданных аргументов
- `sqrt(x)` - квадратный корень от x
- `log(x)` - $ln({x})$
- `log10(x)` - $log_{10}({x})$
- `deg(x)` - конвертирует радианы в градусы
- `rad(x)` - конвертирует градусы в радианы


>[!WARNING]
> Использование незадокументированных функций может иметь иметь любые незадокументированные последствия.