Exports y Eventos

HZ-AudioMixer incluye una API completa del lado del cliente para integrar el mezclador (o tu propia interfaz personalizada) en cualquier otro recurso. Todos los exports están bajo el nombre de recurso hz_audiomixer.

El motor de audio interno (mapeo, activación de la escena, persistencia KVP) permanece dentro del client.lua cifrado. Los exports son la superficie pública — todo lo demás está sellado por Asset Escrow.

Control de la interfaz

open()

Abre la interfaz del mezclador incluida.

exports['hz_audiomixer']:open()

close()

Cierra la interfaz del mezclador incluida.

exports['hz_audiomixer']:close()

toggle()

Alterna la interfaz del mezclador incluida (abre/cierra).

exports['hz_audiomixer']:toggle()

isOpen()

Devuelve true si la interfaz del mezclador incluida está abierta en ese momento.

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

API de lectura

getCategories()

Devuelve un array con los IDs de las categorías activas.

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

getCategoriesData()

Devuelve los metadatos completos de las categorías — úsalo para construir tu propia interfaz. Las etiquetas y descripciones vienen ya traducidas según Config.Locale.

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

Estructura devuelta:

{
    {
        id    = 'weather',
        label = 'Clima',             -- traducido
        desc  = 'Lluvia, truenos, viento', -- traducido
        icon  = 'weather',
        value = 70,                  -- 0-100 (precisión 1%)
        min   = 0,
        max   = 100,
        step  = 1,
    },
    -- ... 8 más
}

getVolume(categoryId)

Devuelve el volumen actual de una categoría (0–100), o nil si el ID no es válido o está desactivado en Config.Categories.

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

getAllVolumes()

Devuelve un mapa { categoryId = volume } con todas las categorías activas.

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

API de escritura

setVolume(categoryId, value)

Define el volumen de una categoría. Lo guarda en el KVP, aplica el cambio de audio de inmediato y dispara el evento volumeChanged.

-- Los volúmenes van de 0 a 100 (precisión 1%)
local ok = exports['hz_audiomixer']:setVolume('weather', 30)

setVolumes(map)

Define varios volúmenes a la vez. Ignora en silencio las claves no válidas. Devuelve el número de cambios aplicados con éxito.

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

resetAll()

Restablece todas las categorías activas a Config.DefaultVolume y lo guarda en el KVP.

exports['hz_audiomixer']:resetAll()

Eventos

hz-audiomixer:volumeChanged

Se dispara cada vez que cambia un volumen (desde cualquier origen: interfaz incluida, exports, resetAll). Úsalo para mantener sincronizada tu interfaz personalizada.

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

Ejemplos de integración

Abrir el mezclador desde un menú de pausa personalizado

-- En el Lua de tu menú de pausa personalizado
RegisterCommand('mymenu_open_mixer', function()
    exports['hz_audiomixer']:open()
end)

Construir tus propios controles deslizantes en tu 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)

-- Envía las actualizaciones a tu NUI cuando el volumen cambie desde cualquier lugar
AddEventHandler('hz-audiomixer:volumeChanged', function(id, value)
    SendNUIMessage({
        action = 'audioVolumeUpdate',
        id     = id,
        value  = value,
    })
end)

// Al abrir el menú — obtener las categorías
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)
    })
})

// Al mover un control deslizante
slider.oninput = (e) => {
    fetch('https://my-pausemenu/mymenu:setMixerVolume', {
        method: 'POST',
        body:   JSON.stringify({
            id:    'weather',
            value: parseInt(e.target.value, 10),
        }),
    })
}

// Escuchar las actualizaciones 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 las armas durante una cinemática

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

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

Silencio rápido para streamers

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

IDs de categoría disponibles

Paso siguiente

• FAQ
• Changelog