# Live2D Cubism — анимированные 2D-персонажи

Live2D Cubism приносит в игру модели Live2D: нарисованных персонажей, которые дышат, моргают, следят за точкой, двигаются по законам физики (волосы, одежда) и исполняют движения и выражения лица, которые сделал их художник. Мод содержит рантайм Cubism для C# и его нативные библиотеки ядра; другие моды используют его, чтобы показать модель в сцене.

Это необязательный блок игры Cthangover. Нынешний сюжетный контент всё ещё пользуется статичными портретами, и ни одна встроенная игра пока не поставляет Live2D-модель; собственная демо-сцена мода показывает работающую модель.

![Пример модели Ren в отрисовке этого мода: руки опущены, а после поднятия одного параметра (ParamArmR01) поднята правая рука.](assets/arm-parameter.jpg)

## Что умеет модель

- **Жизнь в покое** — автоматическое моргание (включено по умолчанию) и дыхание (выключено по умолчанию).
- **Физика** — волосы и одежда колышутся по правилам из `physics3.json` модели.
- **Взгляд** — голова и глаза поворачиваются к целевой точке; в демо за персонажем можно «водить» мышью, перетаскивая её по нему.
- **Движения и выражения** — проиграть движение из группы (`mtn_01`…) или установить выражение (`exp_01`…), заданные в модели.
- **Параметры** — задать любой параметр модели напрямую, как на картинке выше, где правую руку поднял один параметр.
- **Размещение** — модель сама вписывается в свою область или ставится в заданную позицию с заданным масштабом.

## Требования к модели

Модель — это стандартная папка экспорта Cubism, лежащая внутри мода:

```filestree
my_mod/
└── models/
    └── runtime/
        ├── ren.model3.json       входной файл, на который вы указываете
        ├── ren.moc3
        ├── ren.physics3.json
        ├── ren.cdi3.json
        ├── ren.4096/texture_00.png
        ├── expressions/exp_01.exp3.json …
        └── motions/mtn_01.motion3.json …
```

- Модель — это модель Cubism (`.moc3` с `model3.json`). Демо-модель сделана в Cubism 5.3 и использует его маски и рисование вне экрана.
- Нативное ядро Cubism входит в состав для Windows (`.dll`) и Linux (`.so`).
- Примеры моделей идут под собственной лицензией Live2D; перед публикацией прочитайте `ReadMe.txt` модели.

## Показ модели из сценария

Действие `add_live2d_model` ставит модель в вид сцены:

```scenario
action add_live2d_model model_path=models/runtime/ren.model3.json mod_id=my_mod node_name=Ren x=960 y=540 scale=0.5
```

- `model_path` — `model3.json`, путь относительно папки мода;
- `mod_id` — мод, в котором она лежит;
- `node_name` — имя этой модели в сцене (второе действие с тем же именем игнорируется);
- `x`, `y`, `scale` — необязательные позиция и размер; без них модель вписывается автоматически.

Мод с кодом может создать модель через `Live2DService.CreateModel(...)` и вызвать у неё `StartMotion(group, number)`, `StartExpression(id)`, `SetLiveParameter(id, value)` или `SetTargetPoint(x, y)`.

## Демонстрация

Тестовый набор **avatar** этого мода содержит пример модели Ren. Когда он включён, Ren появляется возле виллы в Cthangover и следует за перетаскиванием мыши; его автоматическая проверка поднимает правую руку и сравнивает кадры. Это демо для разработчиков, в обычной игре оно выключено.

## Если что-то пошло не так

1. **Модели нет, а в логе сообщение о `model_path` или о моде.** Путь задаётся относительно папки мода и должен указывать на `model3.json`; `mod_id` должен быть id того мода, где модель лежит.
2. **Модель оказалась не в том месте или не того размера.** Задайте `x`, `y` и `scale` — или не задавайте ни одного из трёх, чтобы модель вписалась сама.
3. **Модель не загружается на платформе.** Ядро Cubism поставляется только для Windows и Linux.