Configuration

Tous les parametres se trouvent dans HZ-Television/config.lua. Cette page couvre chaque section — general, affichage, placement, CarPlay, panneaux d'affichage, chaines, localisation.

La detection framework / target / menu / notification / inventaire est geree de maniere centralisee par HZ-Bridge — voir Configuration HZ-Bridge. Le config.lua de HZ-Television ne contient plus de section Bridge.

General

Config.Locale = 'en'   -- 'en' | 'fr' | 'es' | 'de'
Config.Debug  = false  -- logs console detailles

Permissions

Config.Permissions = {
    ConfiguratorCommand = 'admin',    -- /tvcfg
    BillboardCommand    = 'admin',    -- /billboard
    UseTV               = 'everyone', -- interagir avec n'importe quelle TV
    PlaceTV             = 'everyone', -- placer depuis l'inventaire
}

Format	Signification
`'everyone'`	tout le monde peut utiliser
`'admin'`	admins framework / ACE uniquement
`'job:police'`	restriction a un seul job
`'job:ambulance,police'`	restriction multi-jobs (separes par virgule)

Affichage & Audio

Config.Display = {
    MaxSoundDistance          = 15.0,  -- metres ; portee max pour entendre la TV
    MinSoundDistance          = 2.0,   -- metres ; zone de volume maximum
    DefaultVolume             = 0.5,   -- 0.0 – 1.0
    RenderDistance            = 50.0,  -- metres ; coupe le rendu au-dela
    DefaultRange              = 25.0,  -- portee de detection (v3.1+)
    InteractionMode           = 'raycast', -- 'raycast' (curseur libre) | 'camera' (verrouille)
    RaycastMaxDistance        = 5.0,   -- augmente auto a distance-cam x 2 sur les grands props
    SpritePolyScaleMultiplier = 32.0,  -- facteur d'echelle de rendu interne
    ClockMode                 = 'game',-- 'game' | 'real'
}

Le volume diminue lineairement entre MinSoundDistance (volume max) et MaxSoundDistance (silence).

Placement TV & Protection abandon

Nouveau en v3.4 — protection route + champs de protection abandon ci-dessous.

Config.Placer = {
    Enabled                 = true,
    Persistence             = true,   -- necessite oxmysql

-- Protection abandon (v3.4)
    MaxPerPlayer            = 0,      -- 0 = illimite ; N = limite stricte par identifiant
    AutoCleanupDays         = 0,      -- 0 = desactive ; N = suppression auto apres N jours d'inactivite
    AutoCleanupInterval     = 6,      -- heures entre les cycles de nettoyage (0 = au demarrage uniquement)
    CleanupAdminPermission  = 'admin',-- permission ACE pour /tvclean

-- Protection route (v3.4)
    BlockOnRoad             = false,  -- true = apercu rouge + blocage Entree quand sur une route
                                      -- Le placement CarPlay en vehicule est toujours exempt

-- Legacy
    AllowPickup             = true,
    OnlyOwnerPickup         = true,   -- un admin peut toujours ramasser

-- Correspondance item → modele (pre-remplie avec les 10 items fournis)
    Items = {
        ['hz_tv_s']        = 'hz_tv_s',
        ['hz_tv_m']        = 'hz_tv_m',
        ['hz_tv_l']        = 'hz_tv_l',
        ['hz_tv_s_stand']  = 'hz_tv_s_stand',
        ['hz_tv_m_stand']  = 'hz_tv_m_stand',
        ['hz_tv_l_stand']  = 'hz_tv_l_stand',
        ['curved_screen_s'] = 'prop_curved_screen_s',
        ['curved_screen_m'] = 'prop_curved_screen_m',
        ['curved_screen_l'] = 'prop_curved_screen_l',
        ['hz_carplay']     = 'hz_carplay',   -- CarPlay — 11 variantes supplementaires auto-enregistrees
    },
}

Protection route

Verifie GetClosestVehicleNode autour des coordonnees de l'apercu. Si le prop se trouve sur une route :

Le contour devient rouge (au lieu du cyan normal)

Entree / Confirmer est bloque — le joueur doit deplacer le prop hors de la route d'abord

Le placement CarPlay en vehicule est exempt (le principe meme du CarPlay est de monter sur un vehicule en mouvement)

Protection abandon

Empeche les serveurs longue duree de se remplir de TV et de CarPlays laisses par des joueurs qui ne reviennent jamais.

MaxPerPlayer — limite stricte par identifiant proprietaire. Pour le CarPlay, les upserts par plaque comptent comme un remplacement (le re-placement sur la meme voiture n'incremente pas)
AutoCleanupDays — les proprietaires qui ne se sont pas connectes depuis N jours voient leurs placements supprimes. Recommande 30–60
AutoCleanupInterval — frequence de re-scan par le serveur (en heures ; 0 = au demarrage uniquement)
Colonne last_seen sur hz_television_placed et hz_carplay_placed — rafraichie a playerJoining et a chaque interaction. La migration additive s'execute au demarrage (ALTER TABLE ADD COLUMN IF NOT EXISTS)

Commande admin `/tvclean`

Sous-commande	Action
`/tvclean list`	Top 20 des proprietaires par inactivite — identifiant, nombre de placements, jours d'inactivite
`/tvclean run`	Declencher un cycle de nettoyage automatique immediatement (respecte `AutoCleanupDays`)
`/tvclean purge`	Supprimer TOUS les placements (TV + CarPlays) pour un identifiant specifique

Protege via Config.Placer.CleanupAdminPermission (ACE). Aussi exports["HZ-Television"]:RunHZTVCleanup().

Modeles TV

Chaque ecran interactif est une entree dans Config.Models indexee par nom de modele :

Config.Models = {
    ['hz_tv_m'] = {
        Offset   = vector3(0.0, -0.02, 0.55),
        Scale    = { x = 0.42, y = 0.236 },       -- demi-largeur / demi-hauteur
        Rotation = { x = 0.0, y = 0.0, z = 0.0 },
        RenderTexture = { dict = 'hz_tv_m', name = 'hz_tv_m_screen' },
    },

-- Ecran cinema courbe (v3.3)
    ['prop_curved_screen_m'] = {
        Offset = vector3(0.0, -0.2, 2.7),
        Scale  = { x = 2.80, y = 1.575 },
        Rotation = { x = 0.0, y = 0.0, z = 0.0 },
        Curve  = {
            Radius = 23.00,   -- rayon de l'arc physique (metres)
            Arc    = 25.11,   -- angle de balayage de l'arc (degres)
            Invert = false,   -- true = concave vers le spectateur
        },
        RenderTexture = { dict = 'prop_curved_screen_m', name = 'curved_screen_m' },
    },

-- Grand panneau d'affichage vanilla GTA V (render target detecte automatiquement)
    ['prop_huge_display_01'] = {
        Offset   = vector3(0.0, 0.15, 0.0),
        Scale    = { x = 8.0, y = 4.5 },
        Rotation = { x = 0.0, y = 0.0, z = 0.0 },
        RenderTexture = { dict = 'big_disp', name = 'big_disp' },  -- meme dict/name = render target
    },
}

Ajouter un modele personnalise

Ajoutez une entree indexee par nom de modele dans Config.Models
Lancez-vous en jeu, approchez-vous du prop
Executez /tvcfg → selectionnez le modele → le gizmo 3D vous permet de calibrer Scale / Offset / Rotation en direct
Pour les props courbes, activez le raycast cylindrique : cochez Curve, definissez Radius + Arc + (optionnellement) Invert. Un apercu cyan en arc montre la zone de clic exacte
Sauvegarder ecrit la calibration dans tv_config.json (persiste entre les redemarrages)

L'apercu en direct utilise la meme formule que RaycastTVCylinder — donc "l'arc cyan aligne avec la surface du prop" ↔ "le clic est precis". Si l'apercu est decale, le curseur l'est aussi.

SmartTV sur panneaux d'affichage & cinema (v3.3)

Opt-in par modele : quels ecrans panneau / cinema utilisent l'interface Smart TV complete au lieu du panneau Ghost Protocol cyberpunk.

Config.BillboardUseSmartTV = {
    -- Ecrans cinema courbes — toujours opt-in
    ['prop_curved_screen_s'] = true,
    ['prop_curved_screen_m'] = true,
    ['prop_curved_screen_l'] = true,

-- Grands panneaux vanilla GTA V — detection automatique render target en v3.3
    ['prop_huge_display_01'] = true,
    ['prop_huge_display_02'] = true,

-- Ajoutez tout autre modele RenderTexture ici pour activer la Smart TV dessus
}

Tout ce qui n'est pas dans cette liste garde le panneau NUI classique Ghost Protocol (toujours entierement fonctionnel pour les panneaux configures une fois pour toutes).

CarPlay (v3.2 + v3.3 audio + v3.4 QoL gizmo)

Le CarPlay ne vit pas uniquement dans Config.Placer.Items — le bloc de configuration dedie regle l'UX de placement, l'occlusion audio et le gizmo.

Activer / Desactiver CarPlay (v3.4.5)

Interrupteur principal — definissez Enabled = false pour ignorer entierement la fonctionnalite CarPlay (enregistrement des items, options target, invite de placement, tick de reconciliation). Les TV murales / cinema / panneaux ne sont pas affectees.

Config.Carplay = {
    Enabled = true,  -- v3.4.5+ ; mettre false pour desactiver la variante CarPlay en vehicule
}

Occlusion audio cabine (v3.3)

Le pipeline Web Audio a l'interieur du DUI CarPlay simule le filtre sonore natif RAGE du vehicule (lowpass + bass shelf) car l'audio DUI contourne l'occlusion propre du moteur. Aucune configuration generalement necessaire — les valeurs par defaut correspondent au comportement RAGE — mais les plages peuvent etre ajustees :

Config.Carplay = {
    Enabled          = true,  -- v3.4.5+ ; interrupteur principal
    AudioCabinRange  = 5.0,   -- metres ; au-dela, les auditeurs hors du vehicule entendent le silence
    SealedLowpass    = 600,   -- frequence de coupure Hz quand toutes les portieres sont fermees
    OpenLowpass      = 2200,  -- frequence de coupure Hz quand toutes les portieres sont ouvertes
    SealedBassBoost  = 6,     -- dB peaking shelf a 80 Hz quand scelle (diminue avec l'ouverture des portieres)
    SealedGain       = 0.25,  -- multiplicateur de volume master quand scelle
    OpenGain         = 0.70,  -- multiplicateur de volume master toutes portieres ouvertes
    TransitionMs     = 80,    -- lissage linearRampToValueAtTime pour les changements d'etat des portieres
}

UX de placement (v3.4)

Pendant que le gizmo clavier est ouvert dans un vehicule :

Vehicule fige — FreezeEntityPosition(vehicle, true) + vitesse mise a zero, defige a la confirmation / annulation. Pas de derive
Controles vehicule desactives — accelerateur, frein, direction, frein a main coupes (keepVehicleControls = false)
Reset de la camera premiere personne — SetGameplayCamRelativeHeading(0.0) + SetGameplayCamRelativePitch(0.0, 1.0) pour que la camera regarde vers l'avant quelle que soit la direction visee par le joueur avant

Chaines pre-enregistrees

Config.Channels = {
    {
        name     = 'Weazel News',
        url      = 'https://www.youtube.com/watch?v=example',
        category = 'news',      -- regroupement optionnel dans l'interface Smart TV
        thumbnail = 'https://...', -- image de carte optionnelle
    },
    {
        name     = 'Los Santos Rock Radio',
        url      = 'https://www.youtube.com/watch?v=jfKfPfyJRdk',
        category = 'music',
    },
}

Apparait dans une section "Channels" sur l'ecran d'accueil Smart TV. Les chaines respectent les routing buckets et la synchronisation multi-joueur comme tout contenu URL.

Medias locaux

Hebergez des fichiers MP4 / MP3 directement dans HZ-Television/media/ et exposez-les comme section "Local Media" dans la Smart TV et l'application compagnon LB Phone :

Config.LocalMedia = {
    { title = "Server Intro",  file = "intro.mp4",  type = "video" },
    { title = "Ambient Radio", file = "radio.mp3",  type = "audio" },
    { title = "Event Clip",    file = "event.mp4",  type = "video" },
}

Un seul appui lit le fichier sur la TV active. Ideal pour les intros serveur, clips d'evenements, boucles radio d'ambiance, publicites personnalisees.

Mode streamer

Mute en un clic toutes les TV a proximite — pour les createurs de contenu qui doivent couper l'audio du jeu de leur stream sans toucher l'experience des autres joueurs.

Config.Streamer = {
    Enabled            = true,
    DefaultMute        = false,
    ToggleCommand      = 'streamermode',  -- /streamermode
    AffectsNewScreens  = true,            -- mute automatiquement les ecrans nouvellement detectes (v3.3)
}

Controlable depuis d'autres scripts via exports["HZ-Television"]:SetStreamerMode(true/false) — voir Exports.

Commandes

Config.Commands = {
    Configurator = 'tvcfg',        -- ouvrir le calibrateur gizmo en direct
    Billboard    = 'billboard',    -- modifier le contenu du panneau a proximite
    Carplay      = 'carplay',      -- raccourci F5 — interagir avec le CarPlay du vehicule actuel
    CarplayOn    = 'carplay_on',   -- allumer + ouvrir la SmartTV
    CarplayRemove = 'carplayremove', -- retirer le CarPlay du vehicule actuel
    Cleanup      = 'tvclean',      -- CLI de nettoyage admin (v3.4)
    Streamer     = 'streamermode', -- basculer le mode streamer
}

Webhooks Discord (optionnel)

Config.Webhooks = {
    Enabled  = false,
    PlaceTV  = 'https://discord.com/api/webhooks/...',
    ConfigTV = 'https://discord.com/api/webhooks/...',
    Cleanup  = 'https://discord.com/api/webhooks/...',  -- v3.4 log d'audit /tvclean
}

Exemples avances

Serveur RP strict

Config.Permissions = {
    ConfiguratorCommand = 'admin',
    BillboardCommand    = 'job:police,admin',
    UseTV               = 'everyone',
    PlaceTV             = 'job:estate,admin',
}

Config.Placer = {
    Persistence          = true,
    MaxPerPlayer         = 3,        -- limite stricte
    AutoCleanupDays      = 30,       -- nettoyage apres 30 jours d'inactivite
    AutoCleanupInterval  = 6,
    BlockOnRoad          = true,     -- empeche l'encombrement des routes
    OnlyOwnerPickup      = true,
}

Serveur creatif / sandbox

Config.Permissions = {
    ConfiguratorCommand = 'everyone',
    BillboardCommand    = 'everyone',
    UseTV               = 'everyone',
    PlaceTV             = 'everyone',
}

Config.Placer = {
    Persistence          = true,
    MaxPerPlayer         = 0,         -- illimite
    AutoCleanupDays      = 0,         -- desactive
    BlockOnRoad          = false,
    OnlyOwnerPickup      = false,     -- n'importe qui peut ramasser
}

Apres avoir modifie config.lua, executez restart HZ-Television depuis la console serveur — la plupart des parametres prennent effet immediatement sans redemarrage complet.