VideoLib

Движок Minecraft с самого начала обладал довольно специфическими особенностями. В нём отсутствуют многие стандартные функции, включая кэширование мешей на GPU и, что особенно важно для нашего случая, простой воспроизведение видео. Данный мод призван исправить эту ситуацию, предлагая разработчикам других модов удобный API для интеграции предварительно записанных видеороликов в свои проекты.

Важное замечание: сам по себе этот мод не добавляет никакого функционала в игру. Это исключительно библиотека для использования другими модами.

Настройка

Руководство по установке будет предоставлено после настройки Maven зависимостей. Стоит отметить, что стандартная реализация требует наличия VLC Media Player на компьютере пользователя.

Использование

Для работы с VideoLib необходимо получить ссылку на VideoManager. Этот менеджер видео является основой для всех взаимодействий с библиотекой и критически важен для функционирования мода:

VideoManager videoManager = VideoLib.getInstance().getVideoManager();

VideoManager позволяет создавать несколько экземпляров VideoPlayer. Из-за высокой нагрузки при воспроизведении видео каждый видеоплеер регистрируется в менеджере с уникальным идентификатором. Только видеоменеджер может создавать новые экземпляры VideoPlayer.

VideoPlayer videoPlayer = videoManager.getOrCreate(new Identifier("mymod", "my_video_player"));

Каждый VideoPlayer имеет функцию getTexture(), которая возвращает идентификатор текстуры Minecraft, используемый в рендерере сущностей (или в любом другом месте, где применяются текстуры вне атласа). Эта текстура автоматически обновляется для каждого кадра видео и может применяться как любая другая текстура.

Identifier texture = videoPlayer.getTexture();
VertexConsumer consumer = vertexConsumers.getBuffer(RenderLayer.getEntityCutout(texture));

// рендеринг геометрии любым удобным способом

Видеодескрипторы

Существует несколько способов запустить воспроизведение видео в видеоплеере, но большинство из них связаны с VideoHandle. Видеодескриптор по сути является указателем на видеофайл, хранящийся во внешнем расположении - будь то локальный диск или интернет-ресурс. Для создания VideoHandle необходим VideoHandleFactory, который можно получить от VideoManager.

Важно отметить, что не все видеодескрипторы будут работать со всеми видеоменеджерами. Убедитесь, что используете только видеодескрипторы, предоставленные фабрикой видеоменеджера. (Большинство API функций уже делают это автоматически).

VideoHandleFactory factory = videoManager.getVideoHandleFactory();

VideoHandleFactory предоставляет две основные функции: getVideoHandle(Identifier) и getVideoHandle(URL).

• getVideoHandle(Identifier) ожидает идентификатор ресурса видеофайла из любого мода. Этот файл должен находиться в папке videos вашего ресурспака (например: mymod:videos/myvideo.mp4)

• getVideoHandle(URL) ожидает URL-адрес, по которому можно найти видео. Это может быть интернет-ресурс или локальная файловая система (например: http://mywebsite.com/myvideo.mp4). Файл должен быть доступен напрямую через GET запрос. Ссылки на Google Drive и другие сервисы, где пользователь должен пройти через страницу загрузки, не поддерживаются.

Видеодескриптор затем можно передать видеоплееру для воспроизведения.

VideoHandle idHandle = factory.getVideoHandle(new Identifier("mymod", "videos/myvideo.mp4"))
VideoHandle urlHandle = factory.getVideoHandle(new URL("http://mywebsite.com/myvideo.mp4"));

videoPlayer.getMediaInterface().play(idHandle);

Медиаплееры также предоставляют перегруженные версии play(), которые принимают идентификаторы и URL напрямую. Это просто сокращения для создания видеодескрипторов и их воспроизведения.

Управление воспроизведением

Видеоплееры предоставляют набор интерфейсов для тонкого управления медиавоспроизведением: MediaInterface, ControlsInterface и CodecInterface. Доступ к ним осуществляется следующим образом:

MediaInterface mediaInterface = videoPlayer.getMediaInterface();
ControlsInterface controlsInterface = videoPlayer.getControlsInterface();
CodecInterface codecInterface = videoPlayer.getCodecInterface();

Эти три интерфейса предоставляют множество важных функций, таких как pause, play и setTime. Подробности об этих возможностях API можно найти в javadoc.

События

VideoLib предоставляет несколько обратных вызовов, которые срабатывают при определённых событиях во время воспроизведения видео. Независимо от того, где они вызываются в нативном коде, все обработчики событий выполняются в потоке клиента Minecraft.

VideoEvents events = videoPlayer.getEvents();
events.onBuffering(e -> {
    LogManager.getLogger().info("Буферизация!");
})

Как и интерфейсы воспроизведения, функции событий подробно описаны в javadoc.

О лицензиях

Стандартная реализация VideoLib зависит от VLCJ, который лицензирован под GNU GPL. Это означает, что всё в пакете vlc лицензировано под GPL. Остальная часть репозитория, при условии что она не зависит напрямую от пакета vlc, лицензирована под MIT лицензией. Кроме того, пакет vlc не считается частью публичного API и может быть перемещён в отдельный Gradle проект в будущем.

Планируемые функции

• Управление аудио
  • В настоящее время VLC напрямую передаёт аудио в операционную систему, обходя Minecraft. Я планирую изменить это.
• Стандартизация поддерживаемых форматов
• Предупреждение пользователей при неудачной инициализации VideoLib (обычно из-за отсутствия нативных библиотек)
• Вспомогательные функции для рендеринга

Эта библиотека предназначена для Minecraft 1.18.2. Порты для других версий появятся со временем. Если вы хотите портировать её самостоятельно, pull requests приветствуются!