FAQ

HZ-Television suporta QBCore, QBox, ESX e Standalone. A deteccao e gerenciada pelo hz_lib — configure uma unica vez la e o HZ-Television (+ cada outro Hz-Script) herda automaticamente.

Sim — esse e um dos principais diferenciais. Cada TV proxima exibe seu proprio conteudo independente (sem mais limite de 5 telas desde v2.3, sem mais limite de 12 TVs desde a reescrita DrawSpritePoly). Ate a funcionalidade DashScreen — cada veiculo com um item hz_dashscreen recebe sua propria variante com textura isolada, entao passar por 12 carros no transito = 12 Smart TVs diferentes.

Ilimitado. A sincronizacao em tempo real e gerenciada via eventos baseados em placa e coordenadas (heartbeat 5 s, tolerancia de desvio 1.5 s, precisao 0.1 s, seek/play/pause instantaneo). Jogadores que chegam atrasados recebem a posicao exata de reproducao na conexao.

Totalmente compativel com routing bucket desde v3.1.2. TVs, paineis publicitarios, travas de operador e loops de playlist sao todos isolados por instancia. Duas TVs nas mesmas coordenadas em instancias diferentes nunca se sobrepoe.

Cliente em repouso: ~0.01 ms. Seis TVs ativas na tela: ~0.03 ms (dados de vertices DrawSpritePoly em cache). Servidor: ~0.00 ms. Veja Desempenho.

hz_televisionprops e fornecido com seu download do HZ-Television (v3.4+) mas deve ter ensure separadamente no server.cfg. Adicione ensure hz_televisionprops antes de ensure hz_television. Sem isso, as 12 variantes de props DashScreen nao sao transmitidas e a colocacao de DashScreen fica bloqueada silenciosamente em lib.requestModel.

O script requer ox_lib (recomendado) ou qb-menu + qb-input. Instale um deles e coloque ensure antes do hz_lib (que por sua vez inicia antes do HZ-Television).

Voce precisa adicionar manualmente os itens no arquivo de itens do seu inventario. Trechos pre-configurados estao em hz_television/items/:

• ox_inventory.txt → ox_inventory/data/items.lua


• qb-inventory.txt → qb-core/shared/items.lua (ou qbx_core/shared/items.lua)


• qs-inventory.txt → qs-inventory/shared/items.lua

ak47_inventory nao faz parte da lista auto-detectada do hz_lib (ox_inventory, qb-inventory, qs-inventory, ps-inventory, codem-inventory, origen_inventory, core_inventory, tgiann-inventory). O bridge cai no ESX nativo, mas o ak47 intercepta os eventos de uso de item antes que o ESX os veja, entao RegisterUsableItem nunca dispara.

Correcao conforme a documentacao ak47_inventory: conecte o callback diretamente na definicao do item com server.onUse. Abra a config de itens do ak47 (tipicamente ak47_inventory/shared/items.lua ou ak47_inventory/configs/items.lua) e adicione:

["hz_dashscreen"] = {
    name   = "hz_dashscreen",
    label  = "DashScreen Screen",
    weight = 3000,
    type   = "item",
    close  = true,
    server = {
        onUse = function(source, item)
            TriggerClientEvent('hz_television:useItem', source, { name = 'hz_dashscreen' })
        end,
    },
},

Repita para hz_television_screen se voce tambem usa as TVs de parede / cinema. Coloque o .png correspondente na pasta de imagens UI do seu ak47. Depois ensure ak47_inventory e ensure hz_television.

Ambos sao rejeicoes de modo strict do MariaDB corrigidas na v3.4.6:

• Error 1067 em last_login — timestamp DEFAULT NULL requer uma declaracao NULL explicita em modo strict. Agora timestamp NULL DEFAULT NULL
• Error 1075 em hz_dashscreen_placed — a coluna id AUTO_INCREMENT precisava de uma PRIMARY KEY. Agora declarada

1. Baixe a versao mais recente em keymaster.fivem.net
2. Faca backup do seu config.lua e tv_config.json
3. Substitua todos os arquivos exceto esses dois
4. Consulte o Changelog para novas chaves de configuracao
5. Reinicie o servidor

1. Coloque o item hz_dashscreen no seu inventario
2. Entre em um veiculo (banco do motorista)
3. Use o item — um prop de preview aparece no painel e um gizmo de teclado assume o controle
4. Setas = posicao, Scroll = altura, Q/D (ou A/D) = rotacao, Z/S (ou W/S) = inclinacao, Enter = confirmar, Esc = cancelar
5. Uma vez colocado, use seu sistema de target (ox\_target / qb-target) no carro para Turn On DashScreen → Smart TV

Corrigido na v3.4 — o veiculo agora e automaticamente congelado durante toda a duracao do gizmo (FreezeEntityPosition + velocidade zerada + controles desativados). Descongelado na confirmacao / cancelamento.

Corrigido na v3.4 — a camera em primeira pessoa agora se fixa em heading=0 / pitch=0 ao mudar para vista de cockpit, independentemente da direcao que o jogador olhava antes.

Isso e intencional — o DashScreen e um audio de cabine, nao um alto-falante. O pipeline de oclusao Web Audio (v3.3) corta completamente alem de 5 m do veiculo. Dentro do carro (motorista + passageiros), o audio e totalmente limpo e nao filtrado. Ouvintes em uma bolha de 5 m fora recebem uma versao filtrada em lowpass e atenuada em volume de acordo com o numero de portas abertas.

Ajuste Config.DashScreen.AudioCabinRange se quiser um tamanho de bolha diferente.

Sim — colocacoes ilimitadas. Cada cliente exibe os 12 mais proximos (um por variante com textura isolada), entao alem de 12 simultaneamente visiveis no mesmo cliente, os mais distantes ficam invisiveis ate voce se aproximar.

Desative-a de forma limpa via config.lua (v3.4.5+):

Config.DashScreen = { Enabled = false }

Isso ignora o loop RegisterUsableItem dos hz_dashscreen*, o registro de opcoes de target, o prompt de colocacao, o tick de reconciliacao — tudo que e especifico do DashScreen. As TVs de parede / cinema / paineis publicitarios continuam funcionando normalmente.

Corrigido na v3.4.6 — o invariante not-attached do tick de reconciliacao detecta quando IsEntityAttached(prop) retorna false (o prop foi destacado pela fisica de colisao), libera o slot e o readquire na proxima passagem (≤ 500 ms). O prop se recoloca no mesmo veiculo nos seus offsets originais, e o DUI se reativa automaticamente pois PoweredOn[cpId] e preservado durante o ciclo de liberacao.

Ative Config.Debug = true para ver a razao de liberacao (not-attached) no console F8.

1. A TV esta ligada? (Turn On via menu de target)
2. O modelo foi calibrado? Use /tvcfg perto do prop — o preview ciano ao vivo mostra exatamente onde esta a zona de clique do cursor
3. Para grandes paineis vanilla, adicione o modelo em Config.BillboardUseSmartTV (a deteccao automatica do render target na v3.3 os gerencia automaticamente)
4. Teste primeiro com um simples arquivo de video direto, nao um livestream
5. Verifique o console F8 para erros JS

• Props planos: use /tvcfg e ajuste Scale / Offset / Rotation. O preview ciano corresponde exatamente a zona de clique.
• Props curvos: certifique-se de que o modelo tem uma entrada Curve = { Radius, Arc, Invert } e que o preview em arco (16 segmentos cianos) se alinha com a superficie real. Defina Curve.Invert = true para props que curvam em direcao ao espectador.

• Ligue a TV
• Aproxime-se — o volume diminui linearmente entre MinSoundDistance e MaxSoundDistance
• Aumente Config.Display.MaxSoundDistance para um alcance de audio maior
• Para o DashScreen: o audio so toca dentro do carro (+ uma bolha de 5 m ao redor)

A TV de cada jogador e sua propria instancia independente de navegador CEF com seus proprios cookies e sua propria sessao. O script sincroniza a URL para todos os espectadores, mas nao o estado da sessao — isso e uma limitacao fundamental do isolamento de navegadores relacionada ao funcionamento dos DUI, nao um bug do script.

Uma URL que depende de uma conta e renderizada por jogador, cada um vendo o que sua propria sessao retorna. Apenas URLs publicamente acessiveis sao exibidas de forma identica para todos.

A sincronizacao em tempo real (heartbeat 5 s, tolerancia de desvio 1.5 s) os alcanca quando eles transmitem a TV — eles recebem automaticamente a posicao de reproducao atual.

Se voce notar que jogadores atrasados recebem tela preta no modo navegador especificamente, o problema geralmente e uma condicao de corrida entre a criacao do DUI e a primeira chamada SetDuiUrl quando o jogador transmite. Certifique-se de que seu hz_television esta atualizado (a sincronizacao do navegador para chegadas tardias foi reforcada em versoes recentes com passadas de retry).

Outros pontos a verificar:

• OneSync deve estar ativo (set onesync on no server.cfg)


• Se voce esta em um routing bucket, os dois jogadores devem estar no mesmo bucket — os eventos de sincronizacao sao isolados por bucket por design

1. Adicione uma entrada em Config.Models indexada por nome de modelo com valores Scale / Offset / Rotation iniciais razoaveis
2. Carregue no jogo, aproxime-se do prop
3. Execute /tvcfg → escolha o modelo → calibre com o gizmo 3D; o preview ciano mostra a zona de clique em tempo real
4. Para telas curvas, marque Curve + defina Radius / Arc / Invert
5. Salve — os valores sao escritos em tv_config.json

Ative a protecao de estrada v3.4:

Config.Placer.BlockOnRoad = true

O preview de colocacao fica vermelho ao mirar uma superficie de estrada e Enter e bloqueado. A colocacao de DashScreen no veiculo e sempre isenta — e o principio do DashScreen.

Use os campos de protecao de abandono v3.4:

Config.Placer = {
    MaxPerPlayer        = 5,   -- limite estrito por proprietario
    AutoCleanupDays     = 45,  -- remocao apos 45 dias de inatividade
    AutoCleanupInterval = 6,   -- re-scan a cada 6 horas
}

Tambem disponivel sob demanda via /tvclean run (comando admin) ou exports['hz_television']:RunHZTVCleanup().

/tvclean purge <identifier>

Tambem: /tvclean list exibe o top 20 de proprietarios por inatividade para ajudar a encontrar contas abandonadas.

Ative a persistencia:

Config.Placer.Persistence = true

Requer oxmysql. As tabelas hz_television_placed e hz_dashscreen_placed sao criadas (+ migradas para a coluna last_seen) automaticamente.

Config.Channels = {
    { name = 'Weazel News', url = 'https://example.com/stream.m3u8', category = 'news'  },
    { name = 'LS Rock Radio',url = 'https://example.com/stream.m3u8', category = 'music' },
}

Aparece em uma secao "Channels" na interface Smart TV.

Config.Permissions = {
    UseTV   = 'admin',
    PlaceTV = 'admin',
}

Config.Permissions = {
    UseTV   = 'job:police,ambulance',
    PlaceTV = 'job:estate',
}

Formato: 'job:nomedoemprego' ou 'job:emprego1,emprego2' para varios.

Ative OneSync — set onesync on no server.cfg. Certifique-se tambem de estar em um build do FiveM razoavelmente recente (2802+).

Desde v3.1, o motor de renderizacao faz cache dos dados de vertices, entao 6 TVs na tela custam aproximadamente o mesmo que 1 TV antes do cache. Se voce ainda tiver problemas, diminua Config.Display.RenderDistance (ex. 30 m) e Config.Display.DefaultRange (ex. 20 m).

Geralmente uma restricao de incorporacao, bloqueio regional ou video removido. Teste a URL em um navegador normal em aba anonima. Se a URL requer renderizacao de navegador, passe mode = 'browser' ao chamar PlayVideoOnTelevision.

Remova os modelos de paineis de Config.BillboardUseSmartTV E de Config.Models. Os paineis publicitarios vanilla do GTA V (prop_huge_display_01/02) voltarao ao conteudo render target padrao (que geralmente e nada no jogo).

Use os eventos do servidor para restringir a colocacao — veja Exports & Eventos para exemplos completos.

AddEventHandler('hz_television:placeTV', function(model, coords, heading)
    local src = source
    if not exports['esx_property']:IsPlayerInOwnedProperty(src) then
        TriggerClientEvent('esx:showNotification', src, 'You must be in your property')
        CancelEvent()
    end
end)

Use PlayVideoOnTelevision na lista obtida via GetAllPlacedTVs — veja os exemplos de Exports.