Live2D Cubism

Live2D Cubism — это система, которая позволяет анимировать 2D-изображения, например, спрайты персонажей в визуальной новелле. Эти изображения рисуются в виде набора слоёв — например, слой для зрачков и радужной оболочки, слой для белков глаз, слой для бровей и так далее.

Программное обеспечение Live2D позволяет связывать меши (meshes) с каждым из этих слоёв, а затем указывать, как меши деформируются (изменяется форма каждого меша) при изменении параметров. ПО Live2D позволяет создавать файлы движений (motion files), которые определяют, как эти параметры изменяются со временем, и файлы выражений (expression files), которые определяют выражения лиц.

Интеграция Live2D в Ren'Py заключается в использовании файлов, созданных Live2D, и использовании их для определения анимаций, которые могут быть отображены в Ren'Py. Ren'Py обрабатывает движения и выражения, чтобы определить значения параметров. Эти значения передаются в Cubism SDK for Native, который, в свою очередь, возвращает Ren'Py список мешей для отображения. Затем Ren'Py отрисовывает эти меши, и в результате на экране появляется персонаж Live2D.

Ren'Py поддерживает анимации Live2D в форматах Cubism 3, 4 и 5. Он поддерживает воспроизведение выражений и движений.

Предупреждение

Установка Live2D на iOS требует ручного копирования статических библиотек в ваш iOS-проект.

Установка Live2D

Прежде чем вы сможете использовать Live2D, вам нужно будет загрузить и установить Cubism SDK for Native, который можно найти на веб-сайте Live2D. Обратите внимание, что вам может потребоваться приобрести лицензию на использование Live2D, если ваш бизнес приносит доход выше определённой суммы в год.

После того как вы загрузите Live2D, вы можете установить его из лаунчера Ren'Py. Для установки перейдите в «preferences», затем нажмите «Install libraries». Поместите файл CubismSdkForNative-5-r.1.zip в директорию Ren'Py SDK, в которую можно перейти, нажав кнопку в правом нижнем углу экрана установки библиотек. Затем нажмите «Install Live2D Cubism SDK for Native». Через некоторое время Live2D будет установлен.

Определение анимаций

Анимации Live2D определяются с помощью отображаемого объекта Live2D и инструкции image:

Live2D(filename, zoom=None, top=0.0, base=1.0, height=1.0, alias={}, loop=False, fade=None, seamless=None, attribute_function=None, attribute_filter=None, update_function=None, **properties)

Этот отображаемый объект (displayable) показывает анимацию Live2D.

filename

Это может быть либо файл model3.json, определяющий анимацию Live2D, либо директория, содержащая эту анимацию. В последнем случае берётся последний компонент пути к директории, и к нему добавляется .model3.json для поиска файла.

Например, «Resources/Hiyori» и «Resources/Hiyori/Hiyori.model3.json» эквивалентны.

zoom

Если не None, применяемый коэффициент масштабирования. Этот параметр имеет приоритет над top и base.

top

Верхняя граница изображения для определения размеров. Это доля от высоты изображения, где 0.0 — это верх, а 1.0 — низ.

base

Нижняя граница изображения для определения размеров. Это доля от высоты изображения, где 0.0 — это верх, а 1.0 — низ. Это значение также становится значением по умолчанию для yanchor.

height

Высота, до которой масштабируется изображение. Это доля от виртуальной высоты экрана.

loop

True, если последнее движение должно зацикливаться, иначе False.

alias

Словарь, сопоставляющий псевдонимы (aliases) с движениями или выражениями, для которых они создаются.

fade

True, если плавный переход между движениями (fading) должен быть включен, False, если он должен быть выключен, и None, чтобы использовать значение _live2d_fade.

nonexclusive

Если не None, это должен быть список имён невзаимоисключающих выражений. По умолчанию выражения являются взаимоисключающими, с отображением только одного в один момент времени. Если выражения перечислены здесь, любое их количество может быть показано одновременно, вдобавок к одному взаимоисключающему выражению.

seamless

Определяет, следует ли использовать бесшовное зацикливание. Бесшовное зацикливание позволяет избежать плавного перехода (fading) между повторениями одного и того же движения. Может быть True для постоянного включения, False для постоянного выключения, или набором движений, которые нужно зацикливать.

default_fade

Время по умолчанию, затрачиваемое на плавный переход в движение или выражение, или из него. По умолчанию 1.0, согласно спецификации Live2D, что может приводить к неожиданным переходам. Установите в 0.0, чтобы переходы происходили только тогда, когда это явно запрошено.

attribute_function

Если не None, это функция, которая принимает кортеж атрибутов и возвращает второй кортеж атрибутов. Это можно использовать для замены атрибутов только для целей отображения — возвращаемые атрибуты не используются при показе изображения. Она должна гарантировать, что задан не более чем один атрибут, соответствующий выражению.

attribute_filter

Если не None, это функция, которая принимает кортеж атрибутов и возвращает второй кортеж атрибутов. Обычно используется для разрешения конфликтов между невзаимоисключающими атрибутами. Атрибуты упорядочены так, что более свежие запрошенные атрибуты идут первыми, что означает, что в случае конфликта должен победить первый атрибут.

update_function

Если не None, это функция, которая вызывается при рендеринге анимации после обновления параметров текущим движением и выражениями. Функция вызывается с двумя аргументами:

Объект Live2D.
Отображаемая временная база в секундах.

Эта функция используется для динамического изменения параметров с помощью метода blend_parameter переданного объекта Live2D. Функция должна возвращать задержку в секундах, через которую она будет вызвана снова, или None, чтобы быть вызванной в начале следующего взаимодействия. Функция также вызывается всякий раз, когда отображаемый объект перерисовывается.

Разница между attribute_function и attribute_filter заключается в том, что первая обычно используется для вычисления замены — наличие двух атрибутов означает, что один должен быть заменён третьим. Вторая используется для разрешения конфликтов между атрибутами, например, когда есть группа атрибутов, из которых действителен только один.

Только filename следует передавать как позиционный аргумент, и все другие аргументы должны быть переданы как именованные.

Значения alias, fade, nonexclusive, seamless, default_fade, attribute_function, attribute_filter и update_function являются общими для всех объектов Live2D, использующих один и тот же filename, так что их нужно указывать только один раз как часть первого объекта Live2D, использующего filename.

blend_parameter(name, blend, value, weight=1.0)

Этот метод смешивает текущее значение параметра со value. Это не имеет эффекта вне update_function.

name: Строка, задающая имя изменяемого параметра.
blend: Один из "Add", "Multiply" или "Overwrite". Тип смешивания, который будет использоваться.
value: Число с плавающей точкой, задающее значение, которое будет смешано.
weight: Число с плавающей точкой от 0.0 до 1.0, вес, с которым новое значение изменит текущее.

blend_opacity(name, blend, value, weight=1.0)

Этот метод смешивает текущее значение непрозрачности части модели со value. Это не имеет эффекта вне update_function.

name: Имя параметра для изменения, определенное для этой модели.
blend: Один из "Add", "Multiply" или "Overwrite". Тип смешивания, который будет использоваться.
value: Число с плавающей точкой, задающее значение непрозрачности, которое будет смешано.
weight: Число с плавающей точкой от 0.0 до 1.0, вес, с которым новое значение изменит текущее.

Есть конфигурационная переменная, которая может помочь в отладке того, какие движения и выражения были загружены из файлов .model3.json:

define config.log_live2d_loading = False: Если True, загруженный путь и использованные движения и выражения будут записаны в log.txt при запуске.

Отображаемые объекты Live2D следует присваивать инструкции image:

image hiyori = Live2D("Resources/Hiyori", base=.6)

Также возможно определять атрибуты, и это очень полезно при определении различных уровней приближения и масштабирования.

image hiyori close = Live2D("Resources/Hiyori", base=.6)
image hiyori far = Live2D("Resources/Hiyori", base=.9)

Имейте в виду, что аппаратное обеспечение пользователя может быть не в состоянии инициализировать Live2D, и в этом случае один вызов Live2D() может помешать загрузке всего проекта. То же самое происходит в случае игры, распространяемой в виде веб-версии. Если ваша игра должна быть способна работать даже без Live2D, вы можете использовать обёртку или обходной путь, например:

init python:
    def MyLive2D(*args, fallback=Placeholder(text="no live2d"), **kwargs):
        if renpy.has_live2d():
            return Live2D(*args, **kwargs)
        else:
            return fallback

image kobayashi = MyLive2D(...)
image eileen moving = MyLive2D(..., fallback="eileen happy")

Использование анимаций

Обычный способ отобразить изображение Live2D — использовать инструкцию show. В дополнение к любым атрибутам, добавленным как часть инструкции image, можно использовать имена выражений и движений.

Вот несколько примеров:

show natori exp_00 mtn_01
show hiyori m10
show hiyori m10 m01

Здесь используются имена по умолчанию, найденные в примерах имён Cubism SDK. Имена движений и выражений берутся из файлов Live2D, приводятся к нижнему регистру, и если они начинаются с имени файла model3.json (без директорий и расширений), за которым следует подчёркивание, то этот префикс удаляется. (Например, «Hiyori_Motion01» становится просто motion01.)

Можно использовать не более одного взаимоисключающего выражения и любое количество невзаимоисключающих выражений и движений. Когда задано более одного движения, они воспроизводятся по порядку, и последнее движение зацикливается, если loop равно True. Это позволяет сначала воспроизвести одно движение, а за ним — анимацию бездействия. Каждое движение может появиться только один раз, если только для него не создано несколько псевдонимов.

Есть два специальных атрибута null и still. Атрибут null означает, что не следует применять никакой файл взаимоисключающего выражения, что приводит к отображению стандартного выражения персонажа. Движение still останавливает все движения.

Невзаимоисключающие выражения сохраняются до тех пор, пока не будут удалены с помощью отрицания атрибута:

show hiyori -wave

Масштабирование

Многие модели Live2D определены в высоких разрешениях, по крайней мере, во внутренней системе координат, которую они используют. Чтобы компенсировать это, Ren'Py включает два способа уменьшения масштаба модели Live2D.

Первый — это аргумент zoom. Он может напрямую установить коэффициент масштабирования модели. Если используется zoom, то остальные параметры масштабирования игнорируются.

В противном случае используются аргументы top, base и height. Первые два задают две линии относительно верха и низа изображения. (Как и в других местах в Ren'Py, 0.0 — это верх, а 1.0 — низ.) Когда используются эти аргументы, происходят две вещи:

Изображение масштабируется так, чтобы область между top и base занимала height, где height — это доля высоты экрана.
Якорная точка (anchor) настраивается так, чтобы base располагалась внизу экрана.

При настройке масштабирования анимации Live2D, я сначала настраиваю параметр base, пока нужная часть анимации не окажется вровень с низом экрана. Затем:

Если изображение слишком большое, уменьшайте height, пока оно не станет нужного размера.
Если изображение слишком маленькое, увеличивайте top, чтобы уменьшить количество пустого пространства над анимацией.

Плавный переход движений (Motion Fading)

Поддержка Live2D в Ren'Py включает плавные переходы между движениями. Обычно, когда Ren'Py переключается с одной анимации на другую, переход происходит резко — одна анимация останавливается, а другая начинается. Если происходит переход (transition), обе анимации воспроизводятся одновременно.

Live2D поддерживает другую модель, в которой старая анимация может плавно переходить в новую путём интерполяции параметров. Представьте это так, будто персонаж плавно перемещает руки в новое положение, а не растворяется из одной позиции в другую.

Плавный переход движений управляется аргументом fade. Если он True, используется плавный переход, а если False, происходят резкие смены. Если None, переход управляется переменной _live2d_fade:

_live2d_fade = True: Если True, анимации Live2D используют плавный переход. Если False, анимации сменяются резко.

Псевдонимы (Aliasing)

Параметр alias позволяет вам задавать собственные имена для движений, которые в противном случае были бы определены автоматически. Например, можно сделать так:

image hiyori = Live2D("Resources/Hiyori", base=.6, aliases={"idle" : "m01"})

Чтобы иметь возможность использовать:

show hiyori idle

Вместо:

show hiyori m01

Зацикливание и предзагрузка изображений

Поддержка Live2D в Ren'Py может зацикливать последнюю анимацию, если параметр loop установлен в True. Если анимация зацикливается, важно добавлять паузы продолжительностью более 0.2 секунды, которые Ren'Py может использовать для выполнения ресурсоёмкой предзагрузки изображений. (Это может быть не нужно, если предзагрузка и загрузка изображений могут происходить в другое время.)

Функции

renpy.has_live2d(): Возвращает True, если Live2D поддерживается на текущей платформе, и False в противном случае.