ConditionalVideos - Видео-катсцены по событиям для Майнкрафт

ConditionalVideos - клиент-серверный мод для Майнкрафт, который превращает обычные игровые события в кино. Первый вход, смерть, убийство моба, полученный предмет, выполненное достижение, переход в Незер, порог по scoreboard - на каждое условие вешается свой ролик или целый плейлист. Задумано это в первую очередь для серверов, сюжетных карт, квестовых сборок и ролевых сценариев, где кат-сцены держат погружение лучше любых титров.

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

Как это работает

Мод живёт сразу на двух сторонах. Сервер отслеживает условия и говорит нужному клиенту, что именно проиграть. Клиент берёт на себя воспроизведение. Такая схема и делает ConditionalVideos удобным для мультиплеера: правила держатся в одном месте, а ролики синхронно показываются всем, кому надо.

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

Кому пригодится

• Авторам сюжетных карт - кат-сцена на старте и на ключевых точках сценария.
• Админам RP-серверов - эффектные входы, смерти и поздравления на событиях.
• Сборщикам квестовых модпаков - видео-награда за прогресс.
• Всем, кому нужен cinematic-фидбэк в духе приключенческих кампаний.

Совместимость и требования

Minecraft	Загрузчики	Java
1.20.1	Fabric, Forge	17+
1.21.1	Fabric, NeoForge	21+
1.21.11	Fabric, NeoForge	21+
26.1.2	Fabric, NeoForge	25+
26.2	Fabric, NeoForge	25+

Важный нюанс: на 26.2 игра умеет работать с двумя рендерами. Видео играются на обоих, но поддержка Vulkan пока экспериментальная. Minecraft поставляет его как opt-in превью, так что при проблемах безопаснее остаться на OpenGL.

Нужно на клиенте:

• WATERMeDIA: Multimedia API - версия 3.0.0.23+
• WATERMeDIA: Native Binaries - версия 3.0.0.6+
• Fabric API - любая (только для Fabric)

Без WATERMeDIA воспроизведение просто не заведётся - это его движок и есть. На Fabric не забудьте про Fabric API, иначе мод не поднимется.

Конфиги

• config/conditionalvideos.json - правила для клиента и одиночной игры;
• config/conditionalvideos-server.json - главные правила для выделенного сервера;
• config/conditionalvideos-common.json - поведение воспроизведения на клиенте (серверы тоже читают его для синхронизируемых опций).

В мультиплеере именно сервер владеет конфигом, раздаёт локальные файлы и остаётся источником правды для контента. Всё, что в сюжете про conditionalvideos-server.json, - закон.

Поддерживаемые условия

Каждое условие настраивается через плейлист. Простые условия - это один ключ в конфиге, keyed-условия - это карта id → condition.

Simple (один ключ):

• firstJoin - играет при входе в мир/сессию. Всегда в приоритете: если во время загрузки мира сработали другие условия, firstJoin играет первым, остальные уходят в очередь.
• playerDeath - запасная кат-сцена на любую смерть.
• totemUsed - тотем бессмертия спас игрока.
• bedSleep - игрок начинает спать в кровати.

Keyed (карта id → condition):

• deathByEntity - смерть от конкретного существа-убийцы (перебивает playerDeath).
• entityKilled - игрок одолел заданный ID сущности.
• advancementCompleted - выполнено заданное достижение.
• dimensionChanged - игрок вошёл в заданное измерение.
• itemObtained - получен предмет (подбор, крафт или результат плавки).
• itemCrafted - предмет именно скрафчен (независимо от itemObtained).
• recipeUnlocked - рецепт впервые открылся в книге рецептов.
• scoreboard - счёт игрока по цели удовлетворяет сравнению.
• custom - встроенного детектора нет, срабатывает только через API или команду play.

Сравнения для scoreboard

Каждая запись scoreboard сравнивает счёт игрока со value через comparator:

comparator	Срабатывает, когда
equal	score == value
less	score < value
greater	score > value
lessOrEqual	score <= value
greaterOrEqual	score >= value (по умолчанию)

Срабатывание по фронту: выполненное сравнение стреляет один раз и взводится заново только после того, как станет ложным и снова вернётся в истину. Так как счёт хранится вместе с миром, сравнение, которое уже было выполнено до выхода из игры, при повторном входе не сработает заново.

Настройка conditionalvideos.json

Каждая запись условия держит плейлист в videos: [...] плюс пару общих флагов. Элемент в videos - это VideoEntry с описанием клипа и его оверлеев, пропуска, зацикливания и переходов. Предзаполнен только firstJoin, остальные условия стартуют как пустой {}, пока не добавишь ролики.

Общие поля условия

Свойство	Тип	Обязательно	Описание
repeatableInSameSession	boolean	Да	Если false, условие срабатывает один раз за сессию. Если true - повторяется.
playlistLoop	boolean	Нет	При true плейлист рестартует с первого элемента после последнего. По умолчанию false.
videos	VideoEntry[]	Да	Один или больше элементов, играются по порядку. Одного достаточно.

Записи scoreboard добавляют два поля на уровне условия: value (int, обязателен - порог) и comparator (string, необязателен - по умолчанию greaterOrEqual).

Поля VideoEntry

Свойство	Тип	Обязательно	Описание
source	string	Да	Путь к локальному файлу (относительно игровой папки или абсолютный) или URL (http://, https://, ссылка YouTube).
skippable	boolean	Нет	Если true, игрок может пропустить. По умолчанию true. Принудительно true при videoLoop = true.
videoLoop	boolean	Нет	Если true, элемент зацикливается без швов до пропуска. По умолчанию false. Требует skippable = true.
enableBackground	boolean	Нет	Рисует однотонный полноэкранный фон за видео. По умолчанию true.
colorBackground	string	Нет	HEX-цвет в формате #RRGGBB или #AARRGGBB. По умолчанию #000000.
videoTitle	string	Нет	Необязательный заголовок-оверлей. Поддерживает legacy-коды (&6, &l, &r, ...).
videoTitlePosition	string	Нет	topLeft, topRight, bottomLeft, bottomRight. По умолчанию bottomLeft.
videoDescription	string	Нет	Необязательное описание-оверлей. Поддерживает legacy-коды.
videoDescriptionPosition	string	Нет	topLeft, topRight, bottomLeft, bottomRight. По умолчанию bottomLeft.
titleTextScale	float	Нет	Множитель шрифта заголовка. По умолчанию 1.0.
descriptionTextScale	float	Нет	Множитель шрифта описания. По умолчанию 1.0.
textBoxOpacity	float	Нет	Прозрачность плашки за текстом, 0.0-1.0. Без него - старый авто-альфа.
videoVolume	float	Нет	Громкость этого элемента, 0.0-1.0. По умолчанию 1.0.
transition	string	Нет	Переход при входе в этот элемент из предыдущего. cut (по умолчанию) или fadeOut/In. Игнорируется для первого элемента.
nextAt	float	Нет	Время в секундах от старта элемента, когда надо перейти к следующему. Без него ждём естественного конца.

Совет: transition принадлежит входящему элементу. Если videos[1].transition = "fadeOut/In", игрок плавно гасит videos[0] и проявляет videos[1]. А cut - это мгновенная покадровая смена без сюрпризов для глаза.

Пример конфига

{
  "configVersion": 3,
  "firstJoin": {
    "repeatableInSameSession": false,
    "playlistLoop": false,
    "videos": [
      {
        "source": "videos/intro_part1.mp4",
        "skippable": true,
        "enableBackground": true,
        "colorBackground": "#FF000000",
        "videoTitle": "&6&lWelcome",
        "videoTitlePosition": "topLeft",
        "videoDescription": "&fEnjoy your journey",
        "videoDescriptionPosition": "topLeft",
        "titleTextScale": 1.4,
        "textBoxOpacity": 0.5,
        "videoVolume": 0.8,
        "nextAt": 8.0
      },
      {
        "source": "https://www.youtube.com/watch?v=XXXXXXXXXXX",
        "skippable": true,
        "videoVolume": 1.0,
        "transition": "fadeOut/In"
      }
    ]
  },
  "playerDeath": {
    "repeatableInSameSession": true,
    "videos": [
      { "source": "videos/death/default_death.mp4", "videoTitle": "&cYou Died" }
    ]
  },
  "totemUsed": {
    "repeatableInSameSession": true,
    "videos": [
      { "source": "videos/totem.mp4", "videoTitle": "&eSaved by a Totem" }
    ]
  },
  "bedSleep": {},
  "entityKilled": {
    "minecraft:warden": {
      "repeatableInSameSession": false,
      "videos": [
        { "source": "videos/kills/warden.mp4", "skippable": false, "videoTitle": "&5&lEpic Victory" }
      ]
    }
  },
  "deathByEntity": {
    "minecraft:creeper": {
      "repeatableInSameSession": false,
      "videos": [
        { "source": "videos/death/creeper_death.mp4", "videoTitle": "&aBoom..." }
      ]
    }
  },
  "advancementCompleted": {
    "minecraft:story/mine_diamond": {
      "repeatableInSameSession": false,
      "videos": [
        { "source": "videos/advancements/diamond.mp4", "videoTitle": "&bDiamonds!" }
      ]
    }
  },
  "dimensionChanged": {
    "minecraft:the_nether": {
      "repeatableInSameSession": true,
      "playlistLoop": true,
      "videos": [
        { "source": "videos/dimensions/nether_loop.mp4", "videoLoop": true, "videoTitle": "&cEntered the Nether" }
      ]
    }
  },
  "itemObtained": {
    "minecraft:diamond": {
      "repeatableInSameSession": false,
      "videos": [
        { "source": "videos/items/first_diamond.mp4", "videoTitle": "&bFirst Diamond" }
      ]
    }
  },
  "itemCrafted": {
    "minecraft:crafting_table": {
      "repeatableInSameSession": false,
      "videos": [
        { "source": "videos/items/first_table.mp4", "videoTitle": "&6Crafting Table" }
      ]
    }
  },
  "recipeUnlocked": {
    "minecraft:furnace": {
      "repeatableInSameSession": false,
      "videos": [
        { "source": "videos/recipes/furnace.mp4", "videoTitle": "&7Furnace Unlocked" }
      ]
    }
  },
  "scoreboard": {
    "kills": {
      "repeatableInSameSession": false,
      "value": 100,
      "comparator": "greaterOrEqual",
      "videos": [
        { "source": "videos/scoreboard/100_kills.mp4", "videoTitle": "&c100 Kills!" }
      ]
    }
  },
  "custom": {},
  "consumedConditionSessions": []
}

Важный нюанс про безопасность конфига: одна кривая запись не затирает файл целиком. Разбор идёт мягко - плохой элемент пропускается и логируется, а все валидные остаются на месте. При синтаксической ошибке JSON файл не трогается вообще, а дефолты подставляются только в памяти на текущую сессию. Так что опечатку можно спокойно починить, не теряя работу.

Общий конфиг conditionalvideos-common.json

Управляет воспроизведением на клиенте. Создаётся автоматически с безопасными значениями.

Свойство	Тип	По умолчанию	Описание
videoQuality	string	AUTO	AUTO берёт лучший доступный поток. Любое другое (LOWEST, LOW, MEDIUM, HIGH, HIGHEST) форсит качество. Работает только на многоверсионных источниках вроде YouTube.
alwaysShowCursor	boolean	false	При true экран воспроизведения не прячет курсор.
allowGameSounds	boolean	false	При true ванильные звуки Майнкрафт продолжают играть поверх видео (по умолчанию глушатся).
blockMatureContent	boolean	true	При true источники для взрослых блокируются. Только клиент - сервер это не перебивает.
debugLogging	boolean	false	При true пишет подробную диагностику [CV/...]. Для обычной игры держите выключенным.

В мультиплеере videoQuality, alwaysShowCursor и allowGameSounds приходят из общего конфига сервера, а blockMatureContent и debugLogging всегда читаются из локального файла клиента.

Управление в игре

По умолчанию клавиша пропуска не назначена, и работает откат на ESC. Свою клавишу можно задать в Настройки → Управление → Conditional Videos - тогда она становится единственной активной клавишей пропуска, и подсказка на экране показывает именно её название.

• Тап по клавише пропуска - переход к следующему элементу плейлиста (или закрытие, если он последний). Зацикленные элементы тоже прерываются.
• Удержание - заполняется короткая белая полоса. Отпустить после полного заполнения - пропустить весь плейлист и закрыть воспроизведение. Когда полоса полна, появляется сообщение про сброс плейлиста. Отпустить раньше - отмена, ничего не пропускается.
• skippable = false отключает оба жеста на этом элементе и убирает подсказку - игрок ждёт конца или перехода плейлиста дальше.

Ещё мелочи: курсор сам прячется после нескольких секунд простоя (если не включён alwaysShowCursor), ванильные звуки глушатся на время видео (если не включён allowGameSounds), а всплывающие уведомления во время проигрывания скрываются.

Команды сервера

Доступны с уровнем прав 2+ (командные блоки, операторы) и из консоли сервера:

/conditionalvideos play <targets> <condition>
/conditionalvideos stop <targets>
/conditionalvideos pause <targets>

• play форсит условие для каждого таргета, игнорируя ограничение "раз за сессию". <condition> автодополняется ключами, у которых есть хотя бы одно видео.
• stop закрывает активное воспроизведение и очищает очередь.
• pause переключает паузу и продолжение на текущем видео.

Ключи условий для простых случаев - голые (firstJoin, playerDeath, totemUsed, bedSleep). Для keyed - форма type/key, например entityKilled/minecraft:warden, advancement/minecraft:story/mine_diamond, dimension/minecraft:the_nether, scoreboard/kills, custom/my_event.

Совет: для достижений и измерений команда и API используют префиксы advancement/... и dimension/..., а сам конфиг JSON хранит их в картах advancementCompleted и dimensionChanged. Это частая точка путаницы - не перепутайте при ручной правке.

Локализация

Строки интерфейса и команд идут на en_us, es_es, es_ar и es_mx. Добавить свой язык просто: положите <locale>.json в ресурспак по пути assets/conditionalvideos/lang/.

API для разработчиков

Другие моды могут регистрировать свои условия и запускать / управлять воспроизведением через небольшой стабильный публичный API в пакете org.mateof24.conditionalvideos.api. Это открывает дорогу кастомным триггерам под механики конкретного проекта.

Стоит ли ставить

ConditionalVideos - это узкий, но очень острый инструмент. Для обычного выживания он не нужен. А вот если вы собираете сюжетный сервер или квестовую сборку модов - это почти must-have. Плейлисты с переходами, зацикливание, текстовые оверлеи, тонкая громкость, очередь без перебивания друг друга и API для интеграций закрывают почти все сценарии кат-сцен в Майнкрафт.

Актуальная версия - 1.5.1: в ней починили поломку воспроизведения после обновления WATERMeDIA, а ветка 1.5 принесла поддержку Minecraft 26.1.2 и 26.2, экспериментальный Vulkan и воспроизведение в исходном разрешении. Скачать мод ConditionalVideos стоит тем, кто хочет добавить в свой проект живые кат-сцены, а не сухой текст в чате.

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