Référence API TS-Lib - Bibliothèque de Pont FiveM

Cette page donne une vue d’ensemble pratique de ce que TS-Lib expose à l’exécution une fois @ts-lib/import.lua inclus dans votre ressource.

Utilitaires principaux

TS-Lib attache quelques helpers à une table globale TS, réutilisés dans les scripts Thunder Scripts.

Journalisation

Utils.Print(message, resourceName?)
Utils.DebugPrint(message, resourceName?)
Utils.ErrorPrint(message, resourceName?)
Utils.SuccessPrint(message, resourceName?)

Utils.DebugPrint('Mon script a démarré', GetCurrentResourceName())

Utilitaires génériques

Exemples de helpers courants :

Utils.IsRessourceLoaded(resourceName): boolean
Utils.IsTableEmpty(tbl): boolean

if not Utils.IsRessourceLoaded('qb-core') then
    Utils.ErrorPrint('qb-core est manquant, les ponts TS-Lib ne fonctionneront pas correctement')
end

Intervalles

TS-Lib embarque un helper d’intervalles pour simplifier les callbacks répétés :

TS.Intervals.Set(callback, ms, ...): id
TS.Intervals.Clear(id)

local id = TS.Intervals.Set(function()
    Utils.DebugPrint('Toujours actif')
end, 5000)

-- plus tard
TS.Intervals.Clear(id)

Helpers UI

TS-Lib expose des helpers UI agnostiques du framework via TS.Lib.*. Ils sont rendus via le NUI intégré (ui/build).

Sous-titre

TS.Lib.Subtitle.Show(text: string)
TS.Lib.Subtitle.Hide()

Depuis un script client ayant inclus @ts-lib/import.lua :

TS.Lib.Subtitle.Show('Appuyez sur E pour interagir')

-- plus tard
TS.Lib.Subtitle.Hide()

Depuis une autre ressource via exports uniquement :

exports['ts-lib']:SendSubtitle('Appuyez sur E pour interagir')

-- plus tard
exports['ts-lib']:HideSubtitle()

Text UI (texte d’aide)

TS.Lib.TextUI.Show(text: string, position?: string)
TS.Lib.TextUI.Hide()

position vaut par défaut 'top-left'. Positions courantes :

top-left
top-center

Exemple côté client :

TS.Lib.TextUI.Show('Appuyez sur E pour ouvrir le garage', 'top-center')

-- plus tard
TS.Lib.TextUI.Hide()

Ou via exports :

exports['ts-lib']:SendTextUI('Appuyez sur E pour ouvrir le garage', 'top-center')

-- plus tard
exports['ts-lib']:HideTextUI()

Text Input (input texte)

TS.Lib.TextInput(data: table): table

Ouvre une boîte de dialogue NUI pour la saisie texte et retourne la valeur entrée par l’utilisateur.

local result = TS.Lib.TextInput({
    title = "Entrez la plaque du véhicule",
    placeholder = "ABC 123",
    type = "text",  -- "text", "number", ou "password"
    value = ""
})

if result.receivedData then
    if result.hasCanceled then
        print("Utilisateur a annulé")
    else
        print("Entrée:", result.data)
    end
end

Ou via exports :

local result = exports['ts-lib']:TextInput({
    title = "Entrez la plaque du véhicule",
    placeholder = "ABC 123",
    type = "text"
})

Système de commandes

TS-Lib fournit un système unifié d’enregistrement de commandes avec validation de type intégrée et support des permissions.

TS.Lib.Command.add(nomCommande, proprietes, callback)

TS.Lib.Command.add('givecar', {
    help = 'Donner une voiture à un joueur',
    params = {
        { name = 'playerId', help = 'ID du joueur cible', type = 'playerId' },
        { name = 'model', help = 'Nom du modèle de véhicule', type = 'string' },
    },
    restricted = 'admin'  -- Peut être boolean, string, ou table de groupes
}, function(source, args, raw)
    print(('Admin %d a donné %s au joueur %d'):format(source, args.model, args.playerId))
end)

Types de paramètres

Type	Description
`number`	Convertit l’argument en nombre
`playerId`	Accepte ‘me’ ou l’ID joueur; valide que le joueur existe
`string`	S’assure que l’argument n’est pas un nombre
`longString`	Capture tout le texte restant (doit être le dernier paramètre)
`boolean`	Accepte `true`/`false`, `yes`/`no`, `1`/`0`, `on`/`off`

Utilitaires serveur

Vérificateur de mises à jour

TS.CheckUpdate(versionUrl, changelogUrl?)

Vérifie les mises à jour en récupérant un JSON de version depuis une URL distante. Affiche une boîte formatée dans la console si obsolète.

-- Dans votre script après avoir inclus ts-lib
TS.CheckUpdate(
    'https://raw.githubusercontent.com/votrenom/votrescript/main/version.json',
    'https://docs.thunder-studio.net/scripts/votre-script/changelog'
)

Le JSON de version doit ressembler à :

{ "version": "1.0.7" }

Helpers de pont

TS.Bridge.GetPlayers(): table - Retourne une liste des sources des joueurs
TS.Bridge.HasPermission(source, permission): boolean - Vérifie si le joueur a une permission (utilise le pont framework ou ACE en fallback)

-- Récupérer tous les joueurs
local players = TS.Bridge.GetPlayers()

-- Vérifier la permission
local canSpawn = TS.Bridge.HasPermission(source, 'admin')

Vue d’ensemble des ponts

L’intérêt principal de TS-Lib est ses modules pont. Ils exposent des API normalisées qui cachent les détails propres au framework ou au script.

Bridge.Framework.* → dialogue avec votre framework (QBCore / ESX / QBox / standalone)
Bridge.Garages.* → dialogue avec votre script de garage
Bridge.VehicleKeys.* → dialogue avec votre script de clés véhicule
Bridge.Notify.* → système de notifications unifié

Chaque pont a sa page dédiée :

Ci-dessous les usages les plus courants depuis un script dépendant de TS-Lib.

Pont framework (rappel rapide)

Client

Bridge.Framework.Client.PlayerData Données joueur unifiées, mises à jour automatiquement au chargement / déchargement / changement de métier.
Bridge.Framework.Client.Functions.GetPlayerJob() -> ok, jobOrError

local ok, job = Bridge.Framework.Client.Functions.GetPlayerJob()
if ok then
    print(('Métier : %s (%s)'):format(job.name, job.label))
end

Bridge.Framework.Client.Functions.Notify(message, type?)

Bridge.Framework.Client.Functions.Notify('Véhicule sauvegardé avec succès', 'success')

Serveur

Bridge.Framework.Server.Functions.GetPlayerJob(source)
Bridge.Framework.Server.Functions.GetPlayersByJobName(jobName, checkOnDuty?)
Bridge.Framework.Server.Functions.GetPlayers()
Bridge.Framework.Server.Functions.GetVehicleType(model)
Bridge.Framework.Server.Functions.HasPermission(source, permission)

Voir Pont Framework pour les détails par framework et les noms d’événements.

Pont garage (rappel rapide)

Serveur

Bridge.Garages.Server.Functions.IsVehicleOwned(plate, netId?) -> boolean
Bridge.Garages.Server.Functions.SetVehicleOutsideState(plate, state)

local owned = Bridge.Garages.Server.Functions.IsVehicleOwned(plate, netId)
if not owned then return end

-- marquer le véhicule comme dehors
Bridge.Garages.Server.Functions.SetVehicleOutsideState(plate, true)

Voir Ponts Garage pour le comportement exact par système.

Pont clés véhicule (rappel rapide)

Le pont clés se concentre sur le verrouillage / déverrouillage depuis un point d’entrée unique.

Client

Bridge.VehicleKeys.Client.Functions.SetDoorStatus(entity, lockStatus)

-- Exemple : verrouiller depuis un autre script
Bridge.VehicleKeys.Client.Functions.SetDoorStatus(vehicle, 2) -- 2 = verrouillé

Les états suivent la sémantique des natives GTA (1 = déverrouillé, 2 = verrouillé, 4 = verrouillé pour tous les joueurs, etc.). Voir Ponts Clés véhicule pour le comportement par système (qb-vehiclekeys, qs-vehiclekeys, standalone).

Pont notifications (rappel rapide)

Le pont notifications fournit un moyen unifié d’envoyer des notifications entre différents frameworks.

Client

Bridge.Notify.Client.Functions.Notify(message, type?)

-- Afficher une notification de succès
Bridge.Notify.Client.Functions.Notify('Véhicule sauvegardé avec succès', 'success')

-- Afficher une notification d'erreur
Bridge.Notify.Client.Functions.Notify('Véhicule non trouvé', 'error')

Types supportés selon le framework :

QBCore : success, error, warning, info (ou tout type personnalisé)
ESX : Utilise le système de notification ESX

Voir Pont Notifications pour plus de détails.

​Utilitaires principaux

​Journalisation

​Utilitaires génériques

​Intervalles

​Helpers UI

​Sous-titre

​Text UI (texte d’aide)

​Text Input (input texte)

​Système de commandes

​Types de paramètres

​Utilitaires serveur

​Vérificateur de mises à jour

​Helpers de pont

​Vue d’ensemble des ponts

​Pont framework (rappel rapide)

​Client

​Serveur

​Pont garage (rappel rapide)

​Serveur

​Pont clés véhicule (rappel rapide)

​Client

​Pont notifications (rappel rapide)

​Client

Utilitaires principaux

Journalisation

Utilitaires génériques

Intervalles

Helpers UI

Sous-titre

Text UI (texte d’aide)

Text Input (input texte)

Système de commandes

Types de paramètres

Utilitaires serveur

Vérificateur de mises à jour

Helpers de pont

Vue d’ensemble des ponts

Pont framework (rappel rapide)

Client

Serveur

Pont garage (rappel rapide)

Serveur

Pont clés véhicule (rappel rapide)

Client

Pont notifications (rappel rapide)

Client