Exports & Events

HZ-AudioMixer bietet eine vollständige clientseitige API, um den Mixer (oder Ihre eigene Oberfläche) in jede andere Ressource einzubinden. Alle Exports laufen unter dem Ressourcennamen hz_audiomixer.

Die interne Audio-Engine (Mapping, Aktivierung der Szene, KVP-Persistenz) bleibt in der verschlüsselten client.lua. Die Exports sind die öffentliche Schnittstelle, alles andere ist durch Asset Escrow geschützt.

Steuerung der Oberfläche

open()

Öffnet die mitgelieferte Mixer-Oberfläche.

exports['hz_audiomixer']:open()

close()

Schließt die mitgelieferte Mixer-Oberfläche.

exports['hz_audiomixer']:close()

toggle()

Öffnet oder schließt die mitgelieferte Mixer-Oberfläche.

exports['hz_audiomixer']:toggle()

isOpen()

Gibt true zurück, wenn die mitgelieferte Mixer-Oberfläche gerade geöffnet ist.

local open = exports['hz_audiomixer']:isOpen()

Lese-API

getCategories()

Gibt ein Array der aktivierten Kategorie-IDs zurück.

local ids = exports['hz_audiomixer']:getCategories()
-- { 'weapons', 'vehicles', 'ambience', 'weather', 'speech', 'peds', 'scripted', 'music', 'radio' }

getCategoriesData()

Gibt die vollständigen Metadaten der Kategorien zurück. Verwenden Sie diesen Export, um Ihre eigene Oberfläche zu bauen. Bezeichnungen und Beschreibungen sind bereits gemäß Config.Locale übersetzt.

local data = exports['hz_audiomixer']:getCategoriesData()

Rückgabestruktur:

{
    {
        id    = 'weather',
        label = 'Weather',           -- lokalisiert
        desc  = 'Rain, thunder, wind', -- lokalisiert
        icon  = 'weather',
        value = 70,                  -- 0-100 (1% Genauigkeit)
        min   = 0,
        max   = 100,
        step  = 1,
    },
    -- ... 8 weitere
}

getVolume(categoryId)

Gibt die aktuelle Lautstärke einer einzelnen Kategorie zurück (0–100), oder nil, wenn die ID ungültig ist oder in Config.Categories deaktiviert wurde.

local vol = exports['hz_audiomixer']:getVolume('weather')  -- z. B. 70

getAllVolumes()

Gibt eine Map { categoryId = volume } für alle aktivierten Kategorien zurück.

local volumes = exports['hz_audiomixer']:getAllVolumes()
-- { weapons = 100, vehicles = 80, weather = 30, ... }

Schreib-API

setVolume(categoryId, value)

Setzt die Lautstärke einer einzelnen Kategorie. Speichert sie im KVP, wendet die Audioänderung sofort an und löst das Event volumeChanged aus.

-- Lautstärken gehen von 0 bis 100 (1% Genauigkeit)
local ok = exports['hz_audiomixer']:setVolume('weather', 30)

setVolumes(map)

Setzt mehrere Lautstärken auf einmal. Ungültige Schlüssel werden stillschweigend übersprungen. Gibt die Anzahl der erfolgreich angewendeten Änderungen zurück.

local count = exports['hz_audiomixer']:setVolumes({
    weather  = 30,
    weapons  = 100,
    vehicles = 70,
})

resetAll()

Setzt jede aktivierte Kategorie auf Config.DefaultVolume zurück und speichert im KVP.

exports['hz_audiomixer']:resetAll()

Events

hz-audiomixer:volumeChanged

Wird bei jeder Lautstärkeänderung ausgelöst, egal aus welcher Quelle (mitgelieferte Oberfläche, Exports, resetAll). Nutzen Sie es, um Ihre eigene Oberfläche synchron zu halten.

AddEventHandler('hz-audiomixer:volumeChanged', function(categoryId, value)
    print(('%s set to %d%%'):format(categoryId, value))
end)

Integrationsbeispiele

Den Mixer aus einem eigenen Pause-Menü öffnen

-- Im Lua-Code Ihres eigenen Pause-Menüs
RegisterCommand('mymenu_open_mixer', function()
    exports['hz_audiomixer']:open()
end)

Eigene Regler in Ihrem NUI bauen

RegisterNUICallback('mymenu:getMixerData', function(_, cb)
    cb({
        categories = exports['hz_audiomixer']:getCategoriesData()
    })
end)

RegisterNUICallback('mymenu:setMixerVolume', function(data, cb)
    exports['hz_audiomixer']:setVolume(data.id, data.value)
    cb('ok')
end)

-- Updates an Ihr NUI senden, wenn sich irgendwo eine Lautstärke ändert
AddEventHandler('hz-audiomixer:volumeChanged', function(id, value)
    SendNUIMessage({
        action = 'audioVolumeUpdate',
        id     = id,
        value  = value,
    })
end)

// Beim Öffnen des Menüs: Kategorien abrufen
fetch('https://my-pausemenu/mymenu:getMixerData', {
    method: 'POST',
    body:   '{}'
})
.then(r => r.json())
.then(data => {
    data.categories.forEach(cat => {
        // cat = { id, label, desc, icon, value (0-100), min:0, max:100, step:1 }
        renderSlider(cat)
    })
})

// Bei Änderung des Reglers
slider.oninput = (e) => {
    fetch('https://my-pausemenu/mymenu:setMixerVolume', {
        method: 'POST',
        body:   JSON.stringify({
            id:    'weather',
            value: parseInt(e.target.value, 10),
        }),
    })
}

// Auf externe Updates hören
window.addEventListener('message', (e) => {
    if (e.data.action === 'audioVolumeUpdate') {
        const slider = document.querySelector(`[data-id="${e.data.id}"]`)
        if (slider) slider.value = e.data.value
    }
})

Waffen während einer Zwischensequenz stummschalten

local backup = exports['hz_audiomixer']:getVolume('weapons')

exports['hz_audiomixer']:setVolume('weapons', 0)
PlayCutscene(...)
Wait(cutsceneDuration)
exports['hz_audiomixer']:setVolume('weapons', backup)

Schnelle Stummschaltung für Streamer

RegisterCommand('streamerMode', function()
    exports['hz_audiomixer']:setVolumes({
        music = 0,
        radio = 0,
    })
    print('Streamer mode: music + radio muted')
end)

Verfügbare Kategorie-IDs

Nächster Schritt

• FAQ
• Changelog