lvc — Manual

Luxart Vehicle Control: controlador de sirenes, luzes e setas para veículos de emergência, com menu RageUI, HUD em NUI e perfis salvos por veículo no lado do cliente.

Sumário

1. Dependências
2. Instalação
3. Configuração
4. Controles
5. Comandos
6. Sirenes e perfis de veículo
7. Armazenamento (KVP)
8. Plug-ins
9. Entrypoints para outros recursos
10. Localização
11. Estrutura de arquivos

Dependências

O recurso é standalone quanto a framework: não usa qb-core, ESX, inventário nem target.

Instalação

1. Copie o recurso para resources/ com o nome de pasta exatamente lvc. O cl_lvc.lua verifica GetCurrentResourceName() == 'lvc' e se recusa a funcionar com outro nome.
2. Adicione ao server.cfg, com o RageUI iniciado antes:

   ensure RageUI
   ensure lvc
3. Conflito — não rode junto com o lux_vehcontrol. O LVC detecta o recurso rodando, aborta a inicialização e imprime um erro no console.
4. Defina o community_id em SETTINGS.lua antes de subir em produção (ver abaixo).
5. Não há SQL nem itens de inventário a cadastrar.

Configuração

Arquivo principal: SETTINGS.lua.

Identidade e menu

Lockout

HUD

Sirene principal

Tons manuais, auxiliar e teclas numéricas

Setas e pisca-alerta

Áudio

Plug-ins

Metadados do fxmanifest.lua

Três valores de comportamento ficam no manifesto, não no SETTINGS.lua:

Controles

Os controles só respondem se o jogador for motorista de um veículo de classe 18 (emergência) e o controlador não estiver travado.

Os controls 85, 19, 172, 80 e 86 são interceptados pelo LVC via DisableControlAction, então respondem à tecla que o jogador tiver mapeada para eles no GTA V. As teclas registradas via keybind (menu, lock e tons 1–0) podem ser remapeadas em Configurações > Teclas > FiveM.

Comandos

Os nomes de /lvclock e /lvcdebug vêm do arquivo de locale (command.lock_command e command.debug_command) e mudam se o locale for trocado.

Além desses, o recurso registra dinamicamente os comandos _lvc_siren_1 até _lvc_siren_13, um por tom possível. Eles existem apenas para servir de alvo dos keybinds — não são feitos para serem digitados.

Sirenes e perfis de veículo

Arquivo: SIRENS.lua.

Catálogo de tons (SIRENS)

Lista fixa de 14 tons, cada um com Name (nome exibido no menu), String (o som do jogo) e Ref. Você pode renomear e trocar os sons, mas a ordem dos índices é o que o SIREN_ASSIGNMENTS referencia.

Atribuição por veículo (SIREN_ASSIGNMENTS)

Define quais tons cada veículo pode usar, por gameName. A chave DEFAULT vale para qualquer veículo de emergência sem entrada própria.

SIREN_ASSIGNMENTS = {
    ['DEFAULT']  = { 1, 2, 3, 4 },
    ['FIRETRUK'] = { 12, 13, 14, 11 },
    ['AMBULAN']  = { 1, 2, 3, 4, 11 },
    ['LGUARD']   = { 1, 2, 3, 4, 11 },
}

Para liberar tons específicos a um veículo, adicione uma linha com o gameName dele e a lista de IDs do catálogo. O primeiro item da lista é sempre o airhorn/manual; os demais viram os tons acessíveis pelas teclas numéricas, na ordem em que aparecem.

Armazenamento (KVP)

O LVC não usa banco de dados. Todas as preferências do jogador (volume, esquema de SFX, HUD, nomes de tons, perfis por veículo) são gravadas no client-side KVP do FiveM, com o prefixo definido em community_id.

Consequências práticas:

• as configurações acompanham o jogador, não o personagem;
• trocar o community_id depois do servidor no ar apaga o acesso a tudo que já foi salvo;
• /lvcfactoryreset é a única forma de o jogador limpar esses dados.

Plug-ins

Com plugins_installed = true, o menu do LVC ganha uma aba de plug-ins, e PLUGINS/cl_plugins.lua monta os botões dos plug-ins encontrados (traffic advisor, extra controls, blackout, etc.).

Nesta fork os plug-ins estão desabilitados: plugins_installed = false no SETTINGS.lua e, no fxmanifest.lua, as linhas que carregam os arquivos dos plug-ins estão comentadas:

-- 'PLUGINS/**/*.json'
-- '/PLUGINS/**/SETTINGS.lua',
-- '/PLUGINS/**/cl_*.lua',
-- '/PLUGINS/**/sv_*.lua'

Para usar plug-ins, descomente essas linhas, coloque o plug-in em PLUGINS/ e ligue o plugins_installed.

Entrypoints para outros recursos

O LVC não expõe exports. A comunicação é feita por eventos de rede, usados internamente para sincronizar o estado dos veículos entre os clientes.

-- Cliente: força o LVC a recarregar o perfil, os tons e a HUD do veículo atual.
-- É o gancho usado quando outro recurso troca o veículo do jogador.
TriggerEvent('lvc:onVehicleChange')

Os demais eventos (lvc:GetRepoVersion_s e os de broadcast de estado de sirene/setas) são internos ao par cliente-servidor do próprio recurso.

Localização

Os arquivos de idioma ficam em UI/locale/:

• en.lua — inglês
• de.lua — alemão
• pt-br.lua — português do Brasil (o que está ativo nesta fork)

Diferente dos recursos que usam ox_lib, o idioma não é escolhido por convar: o arquivo é carregado direto no fxmanifest.lua. Para trocar, edite a linha do shared_script e reinicie o recurso:

shared_script {
    '/UTIL/semver.lua',
    '/UI/cl_locale.lua',
    '/UI/locale/pt-br.lua',	-- Set locale / language file here.
    'SETTINGS.lua',
}

Lembre que os nomes dos comandos /lvclock e /lvcdebug vêm do arquivo de locale — trocar o idioma pode trocar os comandos.

Estrutura de arquivos

lvc/
├── SETTINGS.lua              — community_id, teclas, masterswitches, volumes e plug-ins
├── SIRENS.lua                — catálogo dos 14 tons e atribuição de tons por veículo
├── UTIL/
│   ├── cl_lvc.lua            — núcleo: input do jogador, estado das sirenes e setas, broadcast, comandos e keybinds
│   ├── cl_storage.lua        — leitura/gravação de KVP, perfis de veículo, /lvcfactoryreset e /lvcdumpkvp
│   ├── cl_utils.lua          — tons aprovados por veículo, prints e helpers
│   ├── sv_lvc.lua            — sincronia de estado entre clientes e checagem de versão no repositório
│   └── semver.lua            — comparação de versões
├── UI/
│   ├── cl_ragemenu.lua       — menu RageUI e registro da tecla de abertura
│   ├── cl_hud.lua            — HUD em NUI e notificações
│   ├── cl_audio.lua          — reprodução dos SFX e volumes
│   ├── cl_locale.lua         — motor de tradução (Lang:t)
│   ├── locale/               — en.lua, de.lua, pt-br.lua
│   ├── html/                 — index.html, lvc.js, style.css da HUD
│   ├── sounds/               — SFX por esquema (SSP2000, SSP3000, Cencom, ST300) e sons gerais
│   └── textures/             — ícones da HUD (variantes day/night)
├── PLUGINS/
│   └── cl_plugins.lua        — monta a aba de plug-ins do menu (inativo enquanto plugins_installed = false)
├── stream/
│   └── lvc.ytd               — texturas da HUD
└── fxmanifest.lua            — versão, beta_checking, experimental, debug_mode e arquivo de locale ativo