Exports & Eventos

O HZ-AudioMixer oferece uma API completa no lado do cliente para integrar o mixer (ou a sua própria interface personalizada) em qualquer outro recurso. Todos os exports ficam sob o nome de recurso hz_audiomixer.

O motor de áudio interno (mapeamento, ativação da cena, persistência KVP) fica dentro do client.lua criptografado. Os exports são a superfície pública — todo o resto é selado pelo Asset Escrow.

Controle da interface

open()

Abre a interface do mixer incluída.

exports['hz_audiomixer']:open()

close()

Fecha a interface do mixer.

exports['hz_audiomixer']:close()

toggle()

Alterna a interface do mixer (abre/fecha).

exports['hz_audiomixer']:toggle()

isOpen()

Retorna true se a interface do mixer estiver aberta no momento.

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

API de leitura

getCategories()

Retorna um array com os IDs das categorias ativas.

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

getCategoriesData()

Retorna os metadados completos das categorias — use isto para construir a sua própria interface. Os rótulos e as descrições já vêm traduzidos de acordo com Config.Locale.

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

Estrutura retornada:

{
    {
        id    = 'weather',
        label = 'Clima',             -- localizado
        desc  = 'Chuva, trovões, vento', -- localizado
        icon  = 'weather',
        value = 70,                  -- 0-100 (precisão de 1%)
        min   = 0,
        max   = 100,
        step  = 1,
    },
    -- ... mais 8
}

getVolume(categoryId)

Retorna o volume atual de uma categoria (0–100), ou nil se o ID for inválido ou estiver desativado em Config.Categories.

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

getAllVolumes()

Retorna um mapa { categoryId = volume } com todas as categorias ativas.

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

API de escrita

setVolume(categoryId, value)

Define o volume de uma categoria. Salva no KVP, aplica a mudança de áudio imediatamente e dispara o evento volumeChanged.

-- Os volumes vão de 0 a 100 (precisão de 1%)
local ok = exports['hz_audiomixer']:setVolume('weather', 30)

setVolumes(map)

Define vários volumes de uma vez. Ignora as chaves inválidas sem erro. Retorna o número de mudanças aplicadas com sucesso.

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

resetAll()

Redefine cada categoria ativa para Config.DefaultVolume e salva no KVP.

exports['hz_audiomixer']:resetAll()

Eventos

hz-audiomixer:volumeChanged

Disparado a cada mudança de volume (de qualquer origem: interface incluída, exports, resetAll). Use-o para manter a sua interface personalizada sincronizada.

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

Exemplos de integração

Abrir o mixer a partir de um menu de pausa personalizado

-- No Lua do seu menu de pausa personalizado
RegisterCommand('mymenu_open_mixer', function()
    exports['hz_audiomixer']:open()
end)

Construir os seus próprios controles na sua NUI

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)

-- Envia as atualizações para a sua NUI quando um volume muda
AddEventHandler('hz-audiomixer:volumeChanged', function(id, value)
    SendNUIMessage({
        action = 'audioVolumeUpdate',
        id     = id,
        value  = value,
    })
end)

// Ao abrir o menu — buscar as categorias
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)
    })
})

// Ao mudar o controle
slider.oninput = (e) => {
    fetch('https://my-pausemenu/mymenu:setMixerVolume', {
        method: 'POST',
        body:   JSON.stringify({
            id:    'weather',
            value: parseInt(e.target.value, 10),
        }),
    })
}

// Escutar as atualizações externas
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
    }
})

Silenciar as armas durante uma cutscene

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

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

Modo streamer com silêncio rápido

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

IDs de categoria disponíveis

Próxima etapa

• FAQ
• Changelog