> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunder-studio.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Contribuer

> Comment étendre TS-Lib et ses ponts en toute sécurité.

TS-Lib alimente plusieurs scripts Thunder et centralise les intégrations **framework / garage / clés véhicule / notifications**.
Les contributions sont les bienvenues, notamment pour de nouveaux ponts, des correctifs et des améliorations d'ergonomie.

***

## Quels types de contribution ?

* **Nouveaux ponts**
  * Support d'un autre framework ou fork (fork `qbcore`, build ESX custom, etc.).
  * Support d'un autre système de garage.
  * Support d'un autre système de clés.
  * Support d'un autre système de notifications.

* **Amélioration des ponts existants**
  * Gestion d'erreurs et validation des entrées plus robustes.
  * Meilleurs logs quand une dépendance manque ou est mal configurée.
  * Petites optimisations perfs ou BDD sans changer le comportement.

* **Utilitaires cœur**
  * Helpers génériques clairement réutilisables entre plusieurs scripts.
  * Documentation et exemples de code.

***

## Principes de conception

* **Responsabilité unique**
  * TS-Lib doit rester petit et ciblé. Ce n'est *pas* un framework et ne remplace pas vos bibliothèques utilitaires.

* **Les ponts d'abord**
  * La logique spécifique au framework vit dans :
    * `Bridge.Framework.*`
    * `Bridge.Garages.*`
    * `Bridge.VehicleKeys.*`
    * `Bridge.Notify.*`

* **Piloté par la configuration**
  * Les nouvelles intégrations passent par `ts-lib/config.lua` :
    * Ajouter une clé dans `Config.Data.Framework`, `Config.Data.Garages`, `Config.Data.VehicleKeys`, ou `Config.Data.Notify`.
    * Ne pas coder en dur les noms de ressources hors de cette config.

* **Dégradation propre**
  * Si la ressource cible n'est pas démarrée ou est mal configurée :
    * Logger clairement avec `TS.ErrorPrint`.
    * Échouer proprement sans faire planter les autres scripts.

***

## Ajouter un nouveau pont (vue d'ensemble)

1. **Étendre la config**

   Modifiez `ts-lib/config.lua` et ajoutez votre option :

   ```lua theme={null}
   Config.Data.Garages['my-garage'] = 'my-garage-resource-name'
   ```

   Pour les frameworks, clés ou notifications, utilisez `Config.Data.Framework`, `Config.Data.VehicleKeys` ou `Config.Data.Notify`.

2. **Créer les fichiers du pont**

   Suivez la structure existante :

   * Frameworks : `shared/bridge/framework/<name>/shared.lua|client.lua|server.lua`
   * Garages : `shared/bridge/garages/<name>/shared.lua|client.lua|server.lua`
   * Clés : `shared/bridge/vehiclekeys/<name>/shared.lua|client.lua|server.lua`
   * Notifications : `shared/bridge/notify/<name>/client.lua` (généralement côté client uniquement)

3. **Implémenter les fonctions requises**

   * Pour un garage :
     * `Bridge.Garages.Server.Functions.IsVehicleOwned(plate, netId?)`
     * `Bridge.Garages.Server.Functions.SetVehicleOutsideState(plate, state)`

   * Pour les clés véhicule :
     * `Bridge.VehicleKeys.Client.Functions.SetDoorStatus(entity, lockStatus)`

   * Pour les notifications :
     * `Bridge.Notify.Client.Functions.Notify(message, type?)`

   * Pour les frameworks :
     * Voir [Pont Framework](/fr/scripts/ts-lib/bridges-framework) pour la surface attendue.

4. **Protéger l'absence de ressources**

   * Utilisez `TS.Utils.IsRessourceLoaded` (ou des natives FiveM) avant d'appeler d'autres ressources.
   * Loggez des messages utiles si quelque chose n'est pas démarré ou est mal configuré.

5. **Mettre à jour la doc**

   * Ajoutez votre pont dans la section « Systèmes pris en charge » concernée.
   * Mettez à jour le tableau « Statut et tests » avec l'état initial (souvent `Expérimental`) et, si besoin, votre pseudo.

***

## Flux pour les pull requests

1. **Fork** du dépôt TS-Lib sur GitHub.
2. **Branche feature** au nom clair (ex. `feat/my-garage-bridge` ou `fix/esx-owner-query`).
3. Implémentez vos changements :
   * Restez focalisé et raisonnable en taille.
   * Évitez les refactors hors sujet dans la même PR.
4. **Testez** sur au moins une combinaison réelle framework / garage / clés.
5. Ouvrez une **pull request** :
   * Décrivez le problème et l'approche.
   * Listez les ressources externes (noms + versions si possible).
   * Joignez logs ou captures si utile.

En cas de doute sur la pertinence d'une idée, ouvrez une discussion ou contactez le support sur [Discord](https://store.thunder-studio.net/discord).

***

## Signaler des bugs et demander des fonctionnalités

* **Bugs**
  * Incluez :
    * OS (Windows / Linux), framework et scripts principaux.
    * Erreurs console / F8 exactes.
    * Étapes de reproduction et, si possible, un repro minimal.

* **Demandes de fonctionnalités**
  * Partez du **cas d'usage** (ex. « Je veux supporter le garage X ») plutôt que d'un nom de fonction.
  * Souvent la meilleure réponse est un petit helper générique utilisable par plusieurs scripts.

Vous pouvez tout envoyer via le [Discord](https://store.thunder-studio.net/discord).