Exports & Événements

HZ-Television expose un ensemble d'exports client et serveur couvrant le contrôle TV, l'automatisation de playlist, le mode silencieux, les médias locaux et l'outillage de nettoyage abandon. Tout ce qui suit est sous le nom de ressource hz_television — l'utilisation est exports['hz_television']:<fn>(...).

Contrôle TV

StartTelevision(coords)

Allume la TV aux coordonnées données.

exports['hz_television']:StartTelevision(vector3(215.7, -810.1, 30.9))

StopTelevision(coords)

Éteint la TV aux coordonnées données.

exports['hz_television']:StopTelevision(vector3(215.7, -810.1, 30.9))

PlayVideoOnTelevision(coords, url, mode?)

Diffuse du contenu arbitraire sur une TV allumée.

exports['hz_television']:PlayVideoOnTelevision(coords, 'https://example.com/video.mp4')
exports['hz_television']:PlayVideoOnTelevision(coords, 'https://example.com', 'browser')
exports['hz_television']:PlayVideoOnTelevision(coords, 'https://i.imgur.com/alert.png', 'image')

StopContentOnTelevision(coords)

Supprime le contenu mais laisse la TV allumée.

exports['hz_television']:StopContentOnTelevision(coords)

SetVolumeOnTelevision(coords, volume)

Le volume est un entier entre 0..100.

exports['hz_television']:SetVolumeOnTelevision(coords, 40)

SetChannelOnTelevision(coords, channelIndex)

Bascule vers une chaîne pre-enregistree par index base 1 dans Config.Channels.

exports['hz_television']:SetChannelOnTelevision(coords, 2)  -- 2eme entree dans Config.Channels

Playlist personnelle (v3.1)

Démarre programmatiquement une playlist en boucle sur une TV spécifique. Utile pour les campagnes automatisées de panneaux d'affichage déclenchées depuis d'autres scripts.

StartPlaylistOnTelevision(coords, items)

exports['hz_television']:StartPlaylistOnTelevision(coords, {
    { url = 'https://youtu.be/abc', type = 'video', title = 'Clip 1', duration = 30 },
    { url = 'https://i.imgur.com/x.png', type = 'image', title = 'Menu',   duration = 10 },
    { url = 'https://youtu.be/xyz', type = 'video', title = 'Clip 2', duration = 45 },
})

Le serveur parcourt les éléments dans l'ordre, en respectant la duration de chaque élément (secondes). Boucle indéfiniment jusqu'a ce que StopPlaylistOnTelevision soit appelé ou qu'un joueur changé manuellement le contenu.

StopPlaylistOnTelevision(coords)

exports['hz_television']:StopPlaylistOnTelevision(coords)

Mode silencieux

Rend muettes toutes les TV à proximité pour le joueur local — conçu pour les créateurs de contenu qui doivent couper l'audio du jeu de leur stream sans toucher l'expérience des autres joueurs.

SetStreamerMode(enabled)

exports['hz_television']:SetStreamerMode(true)   -- mute
exports['hz_television']:SetStreamerMode(false)  -- unmute (restaure les volumes precedents)

IsStreamerMode()

Retourne boolean.

if exports['hz_television']:IsStreamerMode() then
    print('Silent mode active')
end

Médias locaux

GetLocalMedia()

Retourne la liste des fichiers de médias locaux déclarés dans Config.LocalMedia.

local media = exports['hz_television']:GetLocalMedia()
for _, item in ipairs(media) do
    print(item.title, item.file, item.type)
end

Helpers DashScreen (v3.2)

GetDashScreenOnVehicle(vehicle)

Retourne l'entité prop DashScreen actuellement attachée au vehicle, ou nil.

local dashScreenEntity = exports['hz_television']:GetDashScreenOnVehicle(vehicle)
if dashScreenEntity then
    print('DashScreen attached at entity #' .. dashScreenEntity)
end

IsDashScreenPoweredOn(vehicle)

if exports['hz_television']:IsDashScreenPoweredOn(vehicle) then
    -- Le DashScreen est actuellement allume
end

Admin / Nettoyage abandon (v3.4)

RunHZTVCleanup()

Declenche le cycle de nettoyage automatique à la demande (côté serveur). Respecte Config.Placer.AutoCleanupDays. Retourne true quand démarre.

-- Cote serveur, depuis un script admin personnalise :
exports['hz_television']:RunHZTVCleanup()

Également expose comme commande côté serveur : /tvclean run (protégé par ACE via Config.Placer.CleanupAdminPermission).

Commande /tvclean

Événements

Client → Serveur

HZ-Television:placeTV

Se declenche quand un joueur place une TV statique depuis son inventaire.

-- Cote serveur
AddEventHandler('hz_television:placeTV', function(model, coords, heading)
    local src = source
    -- logs personnalises, restrictions, verifications de propriete, etc.
end)

HZ-Television:placeDashScreen

Se declenche quand un joueur place un DashScreen dans un véhicule (v3.2). Le payload inclut la plaque du véhicule, l'index du bone, et les offsets / rotations par axe.

AddEventHandler('hz_television:placeDashScreen', function(data)
    -- data = { plate, bone, offset_x, offset_y, offset_z, rot_x, rot_y, rot_z }
end)

HZ-Television:pickupTV

Se declenche quand un joueur ramasse une TV placée.

AddEventHandler('hz_television:pickupTV', function(tvId)
    local src = source
end)

HZ-Television:removeDashScreen

Se declenche quand un joueur retire un DashScreen de son véhicule.

AddEventHandler('hz_television:removeDashScreen', function(plate)
    local src = source
end)

Serveur → Client

HZ-Television:updateTV

Force la mise à jour d'une TV côté client.

TriggerClientEvent('hz_television:updateTV', -1, tvEntity, {
    url    = 'https://youtu.be/xxx',
    power  = true,
    volume = 0.8,
})

HZ-Television:powerOff

Éteint une TV pour tous les clients.

TriggerClientEvent('hz_television:powerOff', -1, tvEntity)

Exemples d'intégration

Automatisation cinéma

-- Cote serveur : diffuser un film sur un panneau a une heure programmee
RegisterCommand('startmovie', function(source, args)
    if not IsPlayerAceAllowed(source, 'admin') then return end
    local billboardCoords = vector3(...)
    exports['hz_television']:PlayVideoOnTelevision(
        billboardCoords,
        'https://example.com/' .. (args[1] or 'video.mp4')
    )
    TriggerClientEvent('chat:addMessage', -1, { args = { 'Cinema', 'The show is starting!' } })
end, false)

Restriction par propriété

-- N'autoriser le placement de TV que dans une propriete possedee
AddEventHandler('hz_television:placeTV', function(model, coords, heading)
    local src = source
    local inOwned = exports['esx_property']:IsPlayerInOwnedProperty(src)
    if not inOwned then
        TriggerClientEvent('esx:showNotification', src, 'Must be in your property')
        CancelEvent()
    end
end)

Diffusion d'urgence

RegisterCommand('emergency', function(source, args)
    if not IsPlayerAceAllowed(source, 'admin') then return end
    local msg = table.concat(args, ' ')
    -- Pousser une image d'alerte sur chaque TV placee
    local tvs = exports['hz_television']:GetAllPlacedTVs()
    for _, tv in ipairs(tvs or {}) do
        exports['hz_television']:PlayVideoOnTelevision(tv.coords, 'https://i.imgur.com/alert.png', 'image')
    end
    TriggerClientEvent('chat:addMessage', -1, { color = { 255, 0, 0 }, args = { 'ALERT', msg } })
end, false)

Job reporter / journaliste

-- QBCore : le job reporter peut diffuser en direct sur tous les panneaux
RegisterNetEvent('reporter:broadcastNews', function(url)
    local src = source
    local Player = QBCore.Functions.GetPlayer(src)
    if Player.PlayerData.job.name ~= 'reporter' then
        TriggerClientEvent('QBCore:Notify', src, 'Not a reporter', 'error')
        return
    end
    local tvs = exports['hz_television']:GetAllPlacedTVs()
    for _, tv in ipairs(tvs or {}) do
        if tv.type == 'billboard' then
            exports['hz_television']:PlayVideoOnTelevision(tv.coords, url)
        end
    end
end)