HZ Scripts

FAQ

Geral

O HZ-AudioMixer reproduz sons personalizados?

Nao. O HZ-AudioMixer nao reproduz, nao toca e nao modifica nenhum arquivo de som. Ele controla as categorias de audio nativas do GTA V que o jogo utiliza. Zero impacto no tamanho dos arquivos, zero conflito com outros recursos de audio (xSound, interact-sound, etc.).

Isso interfere com meu chat de voz (pma-voice / saltychat / mumble)?

Nao. O audio do chat de voz passa por um sistema de submix separado e nao e afetado pelo HZ-AudioMixer. Voce pode continuar falando e ouvindo outros jogadores exatamente como antes.

Funciona em servidores standalone / vMenu / vanilla?

Sim. Nenhum framework necessario. O script nao precisa detectar nada porque nao precisa de nada — puro padrao FiveM.

Preciso de um banco de dados?

Nao. As configuracoes dos jogadores sao salvas no lado do cliente via FiveM KVP (Key-Value Persistence). As preferencias de cada jogador ficam na propria maquina e persistem entre reinicializacoes do servidor e reconexoes.

E compativel com QBCore / QBox / ESX?

Sim. Todos os frameworks sao suportados — mas o script na verdade nao utiliza nenhuma funcionalidade de framework. Simplesmente funciona.

Interface & Personalizacao

Posso modificar o design da interface?

Sim. O HTML/CSS em html/index.html esta intencionalmente fora do Asset Escrow para que voce possa reestilizar completamente. Apenas a logica do motor de audio (client.lua) e criptografada.

Posso adicionar meus proprios controles no meu menu de pausa?

Sim. O HZ-AudioMixer expoe uma API completa (getCategoriesData, setVolume, evento volumeChanged) para que voce possa construir seus proprios controles em qualquer NUI personalizada. Veja Exports & Eventos para exemplos de integracao completos.

Posso desativar categorias especificas?

Sim. Defina Config.Categories.<categoria> = false e o controle desaparece da interface, e o patch de cena de audio correspondente e ignorado. Veja Configuracao.

Posso adicionar minhas proprias traducoes?

Sim. Coloque um arquivo locales/<codigo>.lua no recurso. Use qualquer locale existente como modelo. 14 idiomas estao incluidos por padrao.

Posso alterar a tecla de atalho?

Sim — por voce (padrao do servidor) e por cada jogador individualmente. O padrao do servidor esta em Config.OpenKey (padrao F7). Cada jogador pode modifica-lo no menu de pausa do FiveM (Configuracoes → Atalhos → FiveM → "Mixer Audio HZ").

Tecnico

Quais categorias de audio ele controla?

9 categorias do motor RAGE: weapons, vehicles, ambience, weather, speech, peds, scripted, music, radio. Sao categorias principais — ajustar vehicles afeta motores, buzinas, sirenes, helicopteros, etc. todos juntos.

E compativel com mods de audio personalizados (pacotes de sons de veiculos, mods de sons de armas)?

Sim. Desde que os sons personalizados passem pelas categorias de audio RAGE padrao (o que e sempre o caso para sons de gameplay), eles responderao ao mixer.

Isso afeta a musica do radio nos veiculos?

Sim — o controle radio controla o radio do veiculo independentemente do controle music (que e a musica ambiente/trilha sonora do jogo).

As configuracoes dos meus jogadores serao redefinidas quando eu reiniciar o servidor?

Nao. As configuracoes sao armazenadas no KVP do FiveM na maquina do cliente. Elas sobrevivem a reinicializacoes de recursos, reinicializacoes do servidor e desconexoes.

O que acontece na primeira conexao?

Cada categoria tem o padrao Config.DefaultVolume (100 = volume maximo). Os jogadores veem o mixer com todos os controles em 100% no primeiro uso.

O que fazer se um jogador nao tem som apos o spawn?

Muito raro, mas se acontecer: a cena de audio leva alguns segundos para se registrar na primeira conexao. O script tem um loop de recuperacao agressivo de 15 segundos que reaplica os valores a cada frame. Se o som nao voltar, peca ao jogador para pressionar F7 e verificar se os controles nao estao em 0%.

Desempenho

Consome muitos FPS?

Nao. UI fechada = 0.00ms. UI aberta = <0.05ms. Motor de audio em segundo plano = <0.02ms. Testado em servidores de 32 jogadores com mais de 200 recursos, zero impacto nos FPS.

Isso roda no servidor?

Nenhuma logica no lado do servidor. Tudo e executado no lado do cliente. As configuracoes de cada jogador sao proprias dele.

Conflita com outros scripts de audio?

Nao. O mixer utiliza o sistema de cena de audio RAGE no nivel do motor — nao toca em nenhum recurso sonoro, chamada nativa ou submix de audio. Coexiste com qualquer outro script de audio.

Seguranca & Licenca

O script e protegido contra roubo?

Sim. A logica do motor de audio (client.lua) e criptografada via FiveM Asset Escrow. Os arquivos audioconfig/*.rel contem nomes de categorias ofuscados (ex: _v_a3f em vez de weapons) — sem o mapeamento Lua criptografado, os arquivos binarios sao inuteis.

Posso compartilhar com o servidor de um amigo?

Nao. Licenca para servidor unico. A revenda, redistribuicao ou compartilhamento do codigo-fonte e proibido. Violacoes do Asset Escrow sao rastreadas e reportadas.

Vai funcionar em um servidor compartilhado Tebex?

O script esta vinculado a sua conta CFX/Keymaster. Se o seu servidor compartilhado usa a sua conta, funciona. Se usa a de outra pessoa, nao.

Solucao de problemas

WARN: Scene non active no F8

Os arquivos dat15.rel / dat151.rel nao foram carregados a tempo. Verifique:

  1. A pasta audioconfig/ existe no recurso
  2. data_file 'AUDIO_DYNAMIXDATA' e data_file 'AUDIO_GAMEDATA' estao no fxmanifest.lua
  3. Reinicie o servidor inteiro (nao apenas restart hz-audiomixer) — os arquivos de dados de audio necessitam de uma inicializacao limpa para se registrarem

F7 conflita com outro recurso

Abra Menu de Pausa → Configuracoes → Atalhos → FiveM → Procure "Mixer Audio HZ" → Reatribua para uma tecla livre.

O mixer abre mas mover os controles nao altera nada

Verifique se mixerReady e true — abra o F8 com Config.Debug = true e procure [hz_audiomixer] Scene active. Se voce ver WARN: Scene non active, a cena de audio nao se registrou (veja acima).

Apos a conexao, todos os sons ficam mudos por alguns segundos

Essa e a fase de recuperacao agressiva de 15 segundos no spawn. O mixer aplica seus valores salvos frame a frame para garantir que eles surtem efeito. Se o silencio persistir alem de 15 segundos, verifique se seus valores KVP salvos nao estao todos em 0 (abra o mixer com F7 e verifique).

Proxima etapa