Exports & Evenements

HZ-Television expose un ensemble d'exports client et serveur couvrant le controle TV, l'automatisation de playlist, le mode streamer, les medias 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']:(...).

Controle TV

StartTelevision(coords)

Allume la TV aux coordonnees donnees.

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

StopTelevision(coords)

Eteint la TV aux coordonnees donnees.

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

PlayVideoOnTelevision(coords, url, mode?)

Diffuse du contenu arbitraire sur une TV allumee.

exports['HZ-Television']:PlayVideoOnTelevision(coords, 'https://www.youtube.com/watch?v=dQw4w9WgXcQ')
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 allumee.

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 chaine pre-enregistree par index base 1 dans Config.Channels.

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

Playlist personnelle (v3.1)

Demarre programmatiquement une playlist en boucle sur une TV specifique. Utile pour les campagnes automatisees de panneaux d'affichage declenchees 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 elements dans l'ordre, en respectant la duration de chaque element (secondes). Boucle indefiniment jusqu'a ce que StopPlaylistOnTelevision soit appele ou qu'un joueur change manuellement le contenu.

StopPlaylistOnTelevision(coords)

exports['HZ-Television']:StopPlaylistOnTelevision(coords)

Mode streamer

Rend muettes toutes les TV a proximite pour le joueur local — concu pour les createurs de contenu qui doivent couper l'audio du jeu de leur stream sans toucher l'experience 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('Streamer mode active')
end

Medias locaux

GetLocalMedia()

Retourne la liste des fichiers de medias locaux declares dans Config.LocalMedia.

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

Helpers CarPlay (v3.2)

GetCarplayOnVehicle(vehicle)

Retourne l'entite prop CarPlay actuellement attachee au vehicle, ou nil.

local carplayEntity = exports['HZ-Television']:GetCarplayOnVehicle(vehicle)
if carplayEntity then
    print('CarPlay attached at entity #' .. carplayEntity)
end

IsCarplayPoweredOn(vehicle)

if exports['HZ-Television']:IsCarplayPoweredOn(vehicle) then
    -- Le CarPlay est actuellement allume
end

Admin / Nettoyage abandon (v3.4)

RunHZTVCleanup()

Declenche le cycle de nettoyage automatique a la demande (cote serveur). Respecte Config.Placer.AutoCleanupDays. Retourne true quand demarre.

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

Egalement expose comme commande cote serveur : /tvclean run (protege par ACE via Config.Placer.CleanupAdminPermission).

Commande /tvclean

Evenements

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:placeCarplay

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

AddEventHandler('HZ-Television:placeCarplay', 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 placee.

AddEventHandler('HZ-Television:pickupTV', function(tvId)
    local src = source
end)

HZ-Television:removeCarplay

Se declenche quand un joueur retire un CarPlay de son vehicule.

AddEventHandler('HZ-Television:removeCarplay', function(plate)
    local src = source
end)

Serveur → Client

HZ-Television:updateTV

Force la mise a jour d'une TV cote client.

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

HZ-Television:powerOff

Eteint une TV pour tous les clients.

TriggerClientEvent('HZ-Television:powerOff', -1, tvEntity)

Exemples d'integration

Automatisation cinema

-- 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://www.youtube.com/watch?v=' .. (args[1] or 'dQw4w9WgXcQ')
    )
    TriggerClientEvent('chat:addMessage', -1, { args = { 'Cinema', 'The show is starting!' } })
end, false)

Restriction par propriete

-- 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)