Skip to content

RU RU 1 Startup

Jump to bottom
J-RAP edited this page Nov 7, 2026 · 3 revisions

1. ЗАПУСК

На Forge, NeoForge и Fabric загрузчик запускает WATERMeDIA за вас: пропустите этот раздел.

ПРИМЕР:

import org.watermedia.WaterMedia;

WaterMedia.start("My application", temporaryDirectory, workingDirectory, true);
boolean ready = WaterMedia.loaded(); // true ONCE EVERY MODULE FINISHED; CHECK THE CAPABILITY YOU NEED TOO
String module = WaterMedia.loading(); // MODULE CURRENTLY LOADING
int step = WaterMedia.step(); // CURRENT LOADING STEP
int steps = WaterMedia.steps(); // TOTAL LOADING STEPS

Она загружает в таком порядке:

  • Конфигурацию (watermedia.toml)
  • Binaries (только если его JAR присутствует)
  • NetworkAPI
  • CodecsAPI
  • PlayerAPI

steps() равен 5 с Binaries и 4 без него. loading(), step() и steps() можно читать из любого потока для экрана загрузки.

  • start выполняется один раз на процесс: остановки нет, повторный start бросает исключение, а неудавшийся запуск нельзя повторить.
  • При null временной директорией становится <java.io.tmpdir>/watermedia, а рабочей директорией текущая. Последний аргумент говорит, клиент ли это; на выделенных серверах Binaries, кодеки и плеер не запускаются.
  • Если необязательная часть (файловый сервер, FFmpeg) падает, она остаётся выключенной, а загрузка продолжается: проверяйте то, что вам нужно, например CodecsAPI.ffmpegLoaded().
  • Любая другая ошибка (конфигурация, установленный Binaries) заставляет start бросить IllegalStateException с этой ошибкой в качестве причины, а loaded() остаётся false.
  • Никогда не вызывайте start из потока или колбэка WATERMeDIA: он откажется работать.

Каждый API знает, загрузился ли его модуль:

  • PlayerAPI.mrl бросает IllegalStateException, пока не запустится плеер, а на выделенных серверах всегда.
  • NetworkAPI.upload бросает исключение, пока не запустится сеть или если ему передали что-то, кроме существующего файла; недоступный или неправильно настроенный сервер виден в возвращённом статусе.
  • PlatformAPI не требует запуска: register, fetch и search работают всегда. Платформы, которые используют Binaries (YouTube, yt-dlp), падают с PlatformException, пока он не загрузится, а на выделенных серверах всегда; без JAR Binaries fetch возвращает null для их ссылок.
  • Декодирование изображений на чистой Java через CodecsAPI, ServerMediaPlayer, MathUtil и MathEases не требуют запуска.

Плеер владеет движками, которые создают ваши поставщики. Передавайте поставщики, а не уже созданные движки: если источника нет, ничего нативного не останется висеть. Контексты OpenGL, Vulkan и OpenAL принадлежат вам: освобождайте каждый плеер до их уничтожения и создавайте новые движки, когда перезагружаете устройство или контекст. Нативные библиотеки никогда не выгружаются и не меняют версию, пока работает JVM.

1.1 ПРОГРАММНЫЕ ОГРАНИЧЕНИЯ

Заблокированные лаунчеры

WATERMeDIA не запускается в Minecraft, если игру запустил TLauncher, а в сообщении об ошибке указано, по каким признакам его определили. Остатки старой установки лишь записывают предупреждение в лог, а встраивающие приложения эту проверку пропускают.

Совместимые версии

Forge, NeoForge и Fabric загружают WATERMeDIA на клиентах и выделенных серверах этих версий и отклоняют остальные:

Minecraft Forge NeoForge Fabric Loader
1.18.2 40.3.10 или новее (40.x) ⛔ 0.14 или новее (0.x)
1.19.2 43.5.0 или новее (43.x) ⛔ 0.14 или новее (0.x)
1.20.1 47.4.2 или новее (47.x) ⛔ 0.14 или новее (0.x)
1.21.1 52.1.1 или новее (52.x) 21.1.0 или новее (21.1.x) 0.14 или новее (0.x)
1.21.11 61.0.5 или новее (61.x) 21.11.0 или новее (21.11.x) 0.14 или новее (0.x)
26.1.2 64.x 26.1.2.x 0.14 или новее (0.x)
26.2 65.x 26.2.0.x 0.14 или новее (0.x)
26.3 66.x 26.3.0.x 0.14 или новее (0.x)
  • В Minecraft принимается Java от 17 до 25.
  • WATERMeDIA и Binaries принимают друг друга от 3.0.0 до 3.1.0 (не включая); старые сборки 3.0.0 BETA отклоняются.
  • Fabric не умеет требовать зависимость только на клиентах, поэтому там bootstrap сам требует Binaries на клиентах.

1.2 ПУБЛИЧНЫЕ И ВНУТРЕННИЕ ПАКЕТЫ

Публичный API составляют пакеты org.watermedia, api.codecs, api.network, api.platform, api.player и api.util, без их подпакетов. Всё остальное внутреннее.

Доступ к внутренним пакетам ничем не закрыт, но, пожалуйста, используйте публичные точки входа, такие как PlayerAPI.player и PlatformAPI.fetch, и не трогайте то, что за ними. Если вы участвуете в разработке, gradle javadocInventory покажет публичные методы без документации.

Warning

CodecsAPI экспериментальный: decode, reader, sniff, encoder и связанные с ними ридеры, энкодеры и фильтры могут измениться в любом обновлении без соблюдения схемы версий. Пока не используйте их в своих модах; плееры уже используют их за вас. Проверки статуса (ffmpegLoaded(), ffmpegError(), vulkanDecode()) использовать безопасно.

1.3 ДИАГНОСТИКА И ПРИМЕРЫ

Логгеры проекта называются watermedia и watermedia_binaries; для диагностики выставьте этим именам уровень DEBUG.

  • Логи показывают ссылки полностью, чтобы помогать при отладке, но скрывают секреты: пароли в ссылках, JWT-токены, Authorization, Cookie, сессию Minecraft и любую пару key=value, похожую на секрет. Отправка логов из приложения проходит через тот же фильтр.
  • Повторяющаяся проблема (короткий буфер, отклонённая раскладка, падающий колбэк, отклонённая загрузка) попадает в лог только в первый раз в каждом движке, плеере, сервере или кэше. Медленные итерации подсчитываются и выводятся один раз в конце.
  • FFmpeg по-прежнему пишет свои логи в поток ошибок, в обход логгеров проекта и их фильтра секретов.
  • -Dwatermedia.glchecks=true включает проверки ошибок OpenGL при загрузке кадров.

src/test/java/org/watermedia/ApiGuideExample.java содержит компилируемые примеры для каждого движка и для синхронного воспроизведения (часы и ведомый плеер); пример с изображениями выполняется в ApiGuideExampleTest. Если вы участвуете в разработке, с -Prequire_natives=true тесты падают, а не пропускаются, когда нативных библиотек FFmpeg нет.

🌐 Языки

Clone this wiki locally