FiveM Music and Radio Player Scripts: xSound и другое

Почему кастомное радио важно в ролевой игре

Музыка и радио являются важными атмосферными элементами, которые оживляют сервер FiveM roleplay. Хотя в GTA V есть собственные радиостанции, кастомные радиосистемы позволяют владельцам серверов создавать тематические станции, соответствующие идентичности их сообщества, транслировать живые DJ-сеты, проигрывать плейлисты, составленные сообществом, и даже вещать новости от персонажей. Хорошо построенная музыкальная система выходит за рамки простого воспроизведения аудио. Она обеспечивает синхронизированное прослушивание для игроков в одном транспортном средстве, пространственное аудио от бумбоксов и клубных колонок, персональные плейлисты, которыми игроки могут управлять через приложение на телефоне, и интеграцию DJ-стойки для ролевой игры в ночных клубах. Техническая основа опирается на возможности NUI аудио, которые позволяют использовать полный потенциал браузерных аудио API внутри клиента FiveM.

Аудиоархитектура и интеграция NUI

NUI слой FiveM запускает встроенный в игровой клиент браузер на базе Chromium, что даёт доступ к Web Audio API, HTML5 аудиоэлементам и даже MediaSource API для адаптивного стриминга. Архитектура делится на три компонента: Lua клиентский скрипт обрабатывает взаимодействия с игровым миром, такие как посадка в транспорт или приближение к динамикам, NUI HTML и JavaScript слой управляет воспроизведением и визуализацией аудио, а сервер координирует синхронизированное воспроизведение между несколькими клиентами. Когда игрок садится в транспорт, клиентский скрипт отправляет NUI сообщение для запуска текущей станции. NUI слой создаёт аудиоэлемент, задаёт URL источника и начинает воспроизведение. Управление громкостью полностью реализовано в NUI слое с использованием GainNode Web Audio API для плавных переходов громкости:

-- Client-side: Vehicle radio controller
local currentStation = nil
local radioActive = false

CreateThread(function()
    while true do
        Wait(500)
        local ped = PlayerPedId()

        if IsPedInAnyVehicle(ped, false) then
            local vehicle = GetVehiclePedIsIn(ped, false)

            if not radioActive then
                radioActive = true
                -- Disable default GTA radio
                SetVehicleRadioEnabled(vehicle, false)

                -- Load saved station preference
                local savedStation = LocalPlayer.state.radioStation or 'station_1'
                SetStation(savedStation)
            end
        elseif radioActive then
            radioActive = false
            SendNUIMessage({action = 'stopRadio'})
            currentStation = nil
        end
    end
end)

function SetStation(stationId)
    local station = Config.Stations[stationId]
    if not station then return end

    currentStation = stationId
    SendNUIMessage({
        action = 'playStation',
        url = station.url,
        name = station.name,
        volume = LocalPlayer.state.radioVolume or 0.5,
    })
end

Настройка NUI аудиоплеера

Сторона NUI нуждается в надёжном аудиоплеере, который обрабатывает потоковые подключения, буферизацию, восстановление после ошибок и управление громкостью. Используйте Web Audio API вместо простых HTML5 аудиоэлементов, так как он даёт контроль над маршрутизацией звука, позволяет создавать визуализации на основе частотных данных и поддерживает пространственную обработку звука. Создайте AudioContext с GainNode для управления громкостью и AnalyserNode для визуализации:

// NUI JavaScript: Audio engine
class RadioPlayer {
    constructor() {
        this.audioContext = new (window.AudioContext || window.webkitAudioContext)();
        this.gainNode = this.audioContext.createGain();
        this.analyser = this.audioContext.createAnalyser();
        this.analyser.fftSize = 256;

        this.gainNode.connect(this.analyser);
        this.analyser.connect(this.audioContext.destination);

        this.audio = new Audio();
        this.audio.crossOrigin = 'anonymous';
        this.source = null;
        this.isPlaying = false;
    }

    play(url, volume) {
        this.stop();
        this.audio = new Audio(url);
        this.audio.crossOrigin = 'anonymous';
        this.audio.volume = 1.0;

        this.source = this.audioContext.createMediaElementSource(this.audio);
        this.source.connect(this.gainNode);
        this.gainNode.gain.value = volume;

        this.audio.play().then(() => {
            this.isPlaying = true;
        }).catch(err => {
            console.error('Radio playback failed:', err);
            setTimeout(() => this.play(url, volume), 3000);
        });
    }

    stop() {
        if (this.audio) {
            this.audio.pause();
            this.audio.src = '';
            this.isPlaying = false;
        }
    }

    setVolume(vol) {
        this.gainNode.gain.linearRampToValueAtTime(
            vol, this.audioContext.currentTime + 0.1
        );
    }

    getFrequencyData() {
        const data = new Uint8Array(this.analyser.frequencyBinCount);
        this.analyser.getByteFrequencyData(data);
        return data;
    }
}

const radio = new RadioPlayer();

Конфигурация станции и стриминг

Определите ваши радиостанции с URL потоков, метаданными и категориями жанров. Большинство кастомных радиосистем FiveM используют интернет-радиопотоки в формате MP3 или AAC, так как они широко поддерживаются и легко настраиваются. Вы можете разместить собственный сервер Icecast или Shoutcast для полного контроля или использовать публичные URL радиопотоков. Для каждой станции храните URL потока, отображаемое имя, тег жанра и, опционально, логотип для UI. Рассмотрите возможность добавления поддержки URL YouTube и SoundCloud через прокси-сервисы, но учитывайте условия использования и ограничения авторских прав. Для функции живого диджея интегрируйтесь с сервисами, предоставляющими конвертацию RTMP в HTTP, чтобы диджеи могли транслировать с помощью OBS или аналогичного ПО:

Config.Stations = {
    ['station_1'] = {
        name = 'Agency Radio',
        genre = 'Hip Hop',
        url = 'https://stream.example.com/hiphop',
        logo = 'station_hiphop.webp',
        description = 'The freshest beats in Los Santos',
    },
    ['station_2'] = {
        name = 'LS Rock Radio',
        genre = 'Rock',
        url = 'https://stream.example.com/rock',
        logo = 'station_rock.webp',
        description = 'Classic and modern rock anthems',
    },
    ['station_3'] = {
        name = 'Vinewood Lounge',
        genre = 'Jazz / Lofi',
        url = 'https://stream.example.com/lofi',
        logo = 'station_lofi.webp',
        description = 'Smooth vibes for the night drive',
    },
    ['station_live'] = {
        name = 'Live DJ',
        genre = 'Live',
        url = 'https://stream.example.com/live',
        logo = 'station_live.webp',
        description = 'Live DJ sets from the community',
        isLive = true,
    },
}

Синхронизированное радио транспортных средств

Когда в одном транспортном средстве едет несколько игроков, все они должны слышать одну радиостанцию. Это требует серверной координации через state bags или сетевые события. Когда водитель меняет станцию, сервер рассылает новую станцию всем пассажирам. Используйте систему state bag FiveM для эффективной синхронизации, так как она автоматически обрабатывает сетевое реплицирование без ручного управления событиями. Устанавливайте станцию в state bag объекта транспорта, чтобы любой игрок, заходящий в машину, автоматически получал текущую станцию. Обрабатывайте крайние случаи: пассажиры заходят в машину с уже играющей станцией, водитель уходит, а пассажиры остаются, и конфликтующие изменения станции от пассажиров, если вы разрешаете управление не только водителю:

-- Server-side: Sync radio state via state bags
RegisterNetEvent('radio:server:setStation', function(vehicleNet, stationId)
    local src = source
    local vehicle = NetworkGetEntityFromNetworkId(vehicleNet)
    if not DoesEntityExist(vehicle) then return end

    -- Verify player is the driver
    local ped = GetPlayerPed(src)
    if GetPedInVehicleSeat(vehicle, -1) ~= ped then return end

    -- Set station on vehicle state bag
    Entity(vehicle).state:set('radioStation', stationId, true)
end)

-- Client-side: Listen for state bag changes
AddStateBagChangeHandler('radioStation', nil, function(bagName, key, value)
    if not value then return end
    local entity = GetEntityFromStateBagName(bagName)
    if not DoesEntityExist(entity) then return end

    local ped = PlayerPedId()
    if not IsPedInVehicle(ped, entity, false) then return end

    SetStation(value)
end)

Пространственное аудио и системы Boombox

Пространственное аудио добавляет уровень погружения, который не может обеспечить плоское воспроизведение звука. Boombox, клубные колонки и автомобильные стереосистемы должны издавать звук, который затухает с расстоянием и панорамируется в зависимости от положения слушателя относительно источника. FiveM предоставляет нативные аудиофункции, такие как PlaySoundFromCoord для простых пространственных звуков, но для потокового аудио необходимо реализовать масштабирование громкости в зависимости от расстояния на уровне NUI. Вычисляйте расстояние между игроком и источником звука каждый кадр, затем отображайте это расстояние на кривую громкости. Используйте обратное квадратное затухание для реалистичного ослабления звука с настраиваемыми минимальными и максимальными расстояниями слышимости. Для бумбоксов, которые игроки могут размещать в мире, создайте развертываемый предмет, который спавнит объект в позиции игрока и регистрирует его как источник звука. Другие игроки в радиусе автоматически слышат музыку с масштабированием громкости в зависимости от расстояния до объекта бумбокса.

Плейлист игрока и интеграция с телефоном

Дайте игрокам личный контроль над их музыкальным опытом через систему плейлистов, интегрированную с ресурсом телефона вашего сервера. Игроки должны иметь возможность создавать пользовательские плейлисты, добавляя URL отдельных треков, менять порядок песен перетаскиванием, устанавливать плейлист на случайное воспроизведение или повтор, а также делиться плейлистами с другими игроками. Храните плейлисты в базе данных, связанной с идентификатором игрока, чтобы они сохранялись между сессиями. Интерфейс приложения телефона должен отображать текущий проигрываемый трек с метаданными исполнителя и названия, элементы управления воспроизведением: воспроизведение, пауза, пропуск и предыдущий трек, ползунок громкости и список сохранённых плейлистов. Когда игрок находится в транспортном средстве, плеер телефона должен автоматически направлять звук через радиосистему автомобиля, чтобы пассажиры могли слышать музыку. Когда игрок идёт пешком с наушниками, экипированными как предмет, музыка воспроизводится приватно с маленькой иконкой наушников, видимой другим игрокам, указывающей, что персонаж слушает музыку, но она не слышна окружающим.

Визуализатор и дизайн интерфейса

UI музыкального плеера должен быть живым и отзывчивым к проигрываемому аудио. Используйте AnalyserNode из Web Audio API для извлечения частотных данных в реальном времени и отображения аудиовизуализатора. Визуализаторы в виде полос, формы волны и круговые спектральные анализаторы хорошо работают в зависимости от эстетики UI. Отрисовывайте визуализатор с помощью canvas для производительности, обновляя 30 или 60 кадров в секунду в зависимости от сложности. Сам радио UI должен быть минималистичным и ненавязчивым, появляясь как маленький виджет в углу экрана с названием станции, названием трека (если доступно из метаданных потока) и базовыми элементами управления воспроизведением. При открытии полного меню радио для переключения станций отображайте сетку или список доступных станций с логотипами, жанрами и количеством слушателей. Включите строку поиска для серверов с большим количеством станций и систему избранного, чтобы игроки могли быстро получить доступ к любимым станциям без прокрутки всего списка.

Вопросы производительности

Аудио стриминг потребляет пропускную способность и ресурсы клиента, поэтому оптимизируйте реализацию тщательно. Ограничьте количество одновременных аудио потоков на клиента, чтобы предотвратить утечки памяти и скачки CPU. Когда игрок не в транспортном средстве и рядом нет бумбокса, полностью уничтожайте аудио контекст, а не просто ставьте на паузу. Для пространственного звука от нескольких бумбоксов создавайте аудио потоки только для источников в зоне слышимости и очищайте потоки, когда источники выходят из зоны. Используйте низкобитрейтные потоки для фоновой музыки и резервируйте потоки высокого качества для основного прослушивания. На стороне сервера избегайте отправки URL потоков напрямую в события, так как их могут перехватить и использовать злоумышленники. Вместо этого используйте систему обратных вызовов, где клиент запрашивает URL потока для конкретного ID станции, а сервер отвечает временным подписанным URL. Отслеживайте ошибки воспроизведения, сообщаемые клиентом, и автоматически переподключайте потоки, которые прерываются из-за сетевых проблем, с экспоненциальным увеличением интервалов, чтобы не перегружать сервер потоков.