# VCM

Текстовый формат описания 3D моделей, являющийся заменой устаревшего свойства `model-primitives`.

Синтаксис:

```
@примитив атрибут (значение1,значение2,...) атрибут2 "значение3" {
    @внутренний_примитив ...
}
```

Аналогичная структура в XML:

```xml
<примитив атрибут="значение1,значение2,..." атрибут2="значение3">
    <внутренний_примитив .../>
</примитив>
```

В отличие от XML в корне может находиться несколько элементов.

На данный момент существует три вида примитивов: tri, box и rect, а также, part (описывает часть примитива, такую как, например, сторона куба).

> [!NOTE]
> По-умолчанию текстурные координаты определяются размерами примитивов. 
> При размерах более 1.0 результат не определён и может измениться в последующих обновлениях.
> Используйте `region` или `region-scale` для ручной настройки.

## Примитивы

### Свойства `tri`

Примитив описывает треугольник.

- `a` - точка A. Пример: `a (0,0,0)`
- `b` - точка B. Пример: `b (1,0,0)`
- `c` - точка С. Пример: `c (1,1,0)`
- `uv` - нормализованные текстурные координаты точек (6 чисел, по 2 на точку). Пример: `uv (0,0, 1,0, 1,1)`
- `texture` - отображаемая текстура. По-умолчанию: `$0`. Пример: `texture "blocks:sand"`
- `region` - UV регион в границах выбранной текстуры, определяется позициями противоположных углов квадрата нормализованных текстурных координат. Пример: `region (0,0,1,1)`
- `region-scale` вектор-множитель для UV региона. Пример: `region-scale (0.5,1)`
- `shading` определяет возможность затенения на примитиве. Пример: `shading off`
- `normal` переопределяет вектор нормали. Пример: `normal (0,1,0)`
- `cull-face` - определяет, какая сторона будет отсечена. Пример: `cull-face front` или `cull-face off` (отлючает отсечение сторон)

Текстурные координаты по-умолчанию не зависят от формы из размера, в отличие от других примитивов.

### Свойства `rect`

Примитив описывает параллелограмм через векторы right и up.

- `from` - точка начала примитива. Пример: `from (0,0.5,0.125)`
- `right` - вектор X, также определяющий ширину примитива. Пример: `right (1,0,0)`
- `up` - вектор Y, также определяющий высоту примитива. Пример: `up (0,1,0)`
- `texture` - отображаемая текстура. По-умолчанию: `$0`. Пример: `texture "blocks:sand"`
- `region` - UV регион в границах выбранной текстуры, определяется позициями противоположных углов. Пример: `region (0,0,1,1)`
- `region-scale` - вектор-множитель для автоматически выбранного UV региона. Пример: `region-scale (0.5,1)`
- `shading` - определяет возможность затенения на примитиве. Пример: `shading off`
- `flip` - отражает UV регион по горизонтали или вертикали. Пример: `flip v`
- `normal` -  переопределяет вектор нормали. Пример: `normal (0,1,0)`
- `cull-face` - определяет, какая сторона будет отсечена. Пример: `cull-face front` или `cull-face off` (отлючает отсечение сторон)

### Свойства `box`

Примитив описывает прямоугольный параллелепипед.

- `from` - точка начала примитива. Пример: `from (0,0,0)`
- `to` - противоположная от начала точка. Пример: `to (1,1,1)`
- `origin` - точка, относительно которой будет применено вращение. По-умолчанию: центр примитива. Пример: `origin (0.5,0.5,0.5)`
- `rotate` - вращение вокруг осей (x,y,z) в градусах, или кватернион (x,y,z,w). Пример: `rotate (45,0,0)` или `rotate (0.3826834, 0, 0, 0.9238795)`
- `texture` - отображаемая текстура для всех сторон по-умолчанию.
- `shading` - определяет возможность затенения на примитиве. Пример: `shading off`
- `delete` - удаляет стороны по именам (top, bottom, east, west, north, south)

### Свойства `part` (вложен в `box`)

Примитив описывает свойства сторон прямоугольного параллелепипеда с указанными тегами (top/bottom/north/south/east/west).

- `tags` - определяет то, на какаие из сторон будут применены свойства. Пример: `tags (top,bottom)`
- `texture` - отображаемая текстура. По-умолчанию: `$индекс_стороны`.
- `region` - UV регион в границах выбранной текстуры, определяется позициями противоположных углов. Пример: `region (0,0,1,1)`
- `region-scale` - вектор-множитель для автоматически выбранного UV региона. Пример: `region-scale (0.5,1)`

## Скелет

VCM позволяет описывать [скелет](rigging.md) модели. Для этого используется элемент `@bone` (кость).

Существует два вида костей:
- безымянные - используются только для трансформаций на влюженные примитивы, не попадает в итоговый скелет.
- именованные - будет включено в итоговый скелет. Имя указывается через атрибут `name`.

Главная кость (`root`) создаётся автоматически для всей модели.
При наличии явно указанных костей модель будет разделена на несколько частей именованных в формате `имя_модели.имя_кости`.
Так как модель относится к ассетам и не имеет префикса, загруженный скелет получает имя модели, так же, без префикса.
Загруженный скелет можно использовать у [сущности](entity-properties.md#имя-скелета---skeleton-name) через свойство `skeleton-name`.

В списке `пак/preload.json` при указании параметра `"squash": true` vcm будет загружен как единая модель, без скелета.

### Свойства `bone`

- `name` - имя кости, при отсутствии которого кость будет "растворена" и не попадёт в итоговый скелет, при этом, трансформации будут применены.
- `move` - смещение вложенных элементов.
- `scale` - масштабирование вложенных элементов. Применяется перед смещением.
- `rotate` - вращение вложенных элементов вокруг осей (x,y,z) в градусах, или кватернион (x,y,z,w). Пример: `rotate (45,0,0)` или `rotate (0.3826834, 0, 0, 0.9238795)`