mirror of
https://github.com/MihailRis/voxelcore.git
synced 2026-10-04 10:31:50 +00:00
142 lines
7.6 KiB
Markdown
142 lines
7.6 KiB
Markdown
# 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]
|
||
> Использование незадокументированных функций может иметь иметь любые незадокументированные последствия.
|
||
|