BS CustomJukebox

BS CustomJukebox превращает игровые проигрыватели в полноценную музыкальную систему с поддержкой кастомных дисков, плейлистов и автоматических зон воспроизведения.

BS CustomJukebox превращает стандартные проигрыватели в комплексную систему управления аудиоконтентом. Проект позволяет добавлять собственные музыкальные диски с использованием файлов формата .ogg из ресурс-пака, создавая уникальную атмосферу без замены ванильных дисков.

Плагин поддерживает создание плейлистов, автоматических зон воспроизведения (Ambient Zones) и радиостанций. Игроки могут управлять личными настройками, такими как громкость, пропуск треков и список избранного.

🎵 Кастомные музыкальные диски
Добавление собственных дисков происходит через ресурс-пак. Каждый диск можно настроить по параметрам: название, автор, описание (lore) и CustomModelData. Система автоматически останавливает воспроизведение по достижении длительности трека.

📻 Эмбиент-зоны и серверное радио
Фоновая музыка включается автоматически при входе игрока в область. Поддерживаются четыре типа зон: радиус, параллелепипед (cuboid), регионы WorldGuard или глобальная зона (радио), охватывающая весь сервер.

• Два режима воспроизведения: synced (синхронное прослушивание для всех) и individual (индивидуальное прослушивание для каждого входа).
• Настройка приоритета зон: если области пересекаются, приоритет определяет, какая зона будет активна.
• Возможность ограничения высоты воспроизведения в 3D-пространстве.
• Поддержка цикличного и случайного воспроизведения с настройкой громкости на каждую зону.
• Интеграция с попугаями: птицы реагируют на музыку в заданном радиусе.

🎶 Плейлисты и категории
Диски можно группировать по категориям и объединять в плейлисты. Для каждого плейлиста настраивается радиус действия: от локального до серверного.

Плагин включает механику сбора фрагментов дисков, которые можно объединять в полноценные записи. Фрагменты могут выпадать из криперов (при убийстве скелетами или игроками) и встречаться в структурах: данжах, бастионах, городах Края и руинах троп.

Для удобства управления предусмотрены графические интерфейсы (GUI):

• Интерфейс проигрывателя: позволяет выбирать диск через ПКМ по пустому проигрывателю.
• Панель администратора (/cjb gui): позволяет создавать, редактировать и удалять диски, плейлисты и категории без правки конфигурационных файлов.
• Редактор зон: визуальный помощник, указывающий причины, по которым зона может не воспроизводиться.

Доступные псевдонимы: /customjukebox, /jukebox, /jb.

• WorldGuard: учитывает флаг USE и позволяет привязывать зоны к регионам.
• GriefPrevention: учитывает права на контейнеры.
• PlaceholderAPI: предоставляет 16 различных плейсхолдеров (громкость, статус беззвучия, информация о текущем диске и др.).
• Developer API: предоставляет события DiscPlaybackStart/Stop и DiscRegistered/Removed.
• Geyser/Floodgate: для поддержки игроков на Bedrock рекомендуется установить дополнение BS-CustomJukebox Bedrock Extension.

Основные настройки хранятся в config.json. Все данные пишутся асинхронно и атомарно, что предотвращает зависание игровых тиков при сохранении.

{
  "settings": {
    "enabled": true,
    "language": "en",
    "enable-gui": true,
    "debug": false,
    "max-backups": 5,
    "backup-min-interval-minutes": 5
  },
  "discs": {
    "creeper-drops": true,
    "creeper-drop-chance": 0.05,
    "dungeon-loot": true,
    "trail-ruins-loot": true,
    "max-loot-discs": 2,
    "loot-chance": 0.15,
    "enable-crafting": true,
    "fragments-per-disc": 9
  },
  "playback": {
    "volume": 4.0,
    "default-loop": false,
    "jukebox-hearing-radius": 64,
    "show-title": true,
    "show-actionbar": true,
    "show-progress-bar": true,
    "progress-update-ticks": 20
  },
  "parrots": {
    "enable-dancing": true,
    "dance-radius": 3
  },
  "ambient-zones": {
    "enabled": true,
    "sound-category": "RECORDS"
  },
  "integrations": {
    "worldguard": true,
    "griefprevention": true
  }
}

Для корректной работы кастомных звуков критически важно совпадение четырех параметров: путь к .ogg файлу, ключ события в sounds.json, имя внутри него и параметр sound в disc.json. Любое несовпадение приведет к тишине без вывода ошибок.