Généralités

Présentation

Ce chapitre présente MasterLadder, l'échelle pivotante pompiers (EPAN / EPA) de MasterMods pour FiveM.

MasterLadder transforme un véhicule à échelle en véritable engin d'intervention : calage au sol, manœuvre de l'échelle depuis le poste de la tourelle ou depuis la nacelle, montée à pied par l'échelle et deux pupitres de commande au choix. Toute l'échelle est synchronisée pour l'ensemble des joueurs, sans saccades.

Ce que fait le script

Compatibilité

Licence

MasterLadder est gratuit. Il nécessite une MasterKey, gratuite elle aussi : voir Installation.

Support : discord.mastermods.dev

Dépendances

Ce document liste ce dont MasterLadder a besoin pour fonctionner.

Obligatoire

Optionnel

⚠️ Démarrez le framework, le target et la ressource du véhicule avant MasterLadder dans server.cfg.

Installation

Ce chapitre décrit la mise en place de MasterLadder sur votre serveur.

1. Fichiers

  1. Téléchargez MasterLadder-vX.Y.Z.zip.
  2. Décompressez le dossier MasterLadder dans votre dossier resources/ (par exemple resources/[mastermods]/MasterLadder).

⚠️ Ne renommez pas les fichiers à l'intérieur du dossier.

2. server.cfg

ensure ox_target          # si vous utilisez un target
ensure votre-vehicule-epan # la ressource qui stream le véhicule et les props
ensure MasterLadder

3. MasterKey

Créez votre clé gratuite sur ressources.mastermods.dev/CreerMasterKey.php, puis renseignez-la à un seul de ces deux endroits :

Au démarrage, la console serveur affiche Licence MasterMods validée pour : <nom du serveur>. La clé est revérifiée toutes les 30 minutes.

⚠️ Une même MasterKey peut servir sur 3 serveurs différents maximum par 24 h. Au-delà, elle est bloquée 1 jour.

En cas de problème, voir En cas d'erreur.

4. Configuration

5. Administration (optionnel)

Pour autoriser vos administrateurs à utiliser /mladmin :

add_ace group.admin command.mladmin allow

Mise à jour

Remplacez tout le dossier sauf config/config.lua et config/ladders.lua, puis comparez-les avec ceux de la nouvelle version : les nouvelles options sont listées dans les Journaux des changements. Une option absente de votre config prend sa valeur par défaut.

Guide d'utilisation

Ce chapitre explique comment utiliser l'échelle en jeu, du calage au repli. Les touches indiquées sont celles par défaut : chaque joueur peut les changer dans Paramètres > Raccourcis > FiveM, et le serveur peut modifier les valeurs par défaut (voir Configuration générale).

Avec un système de visée (ox_target / qb-target), les actions « à pied » se font à l'œil (ALT) sur le véhicule ou sur l'échelle. Sans target, une aide en haut de l'écran indique la touche à utiliser.

1. Déployer l'échelle

  1. Garez le véhicule sur un sol le plus plat possible (pente maximale : 8° par défaut).
  2. À l'arrière du véhicule, allumez l'écran de commande : visée « Allumer / éteindre l'écran » ou touche E.
  3. Déployez : visée « Déployer l'échelle » ou touche U devant l'écran.
    • Depuis la cabine, U déploie aussi directement.
  4. Les stabilisateurs se calent (7 secondes par défaut). Le véhicule est immobilisé et ses portes verrouillées.

⚠️ Le déploiement est refusé si la pente est trop forte ou si le sol n'est pas trouvé sous un stabilisateur.

2. Prendre place

Place Comment
Poste de commande (tourelle) Visée sur la tourelle « Monter au poste de commande », ou F près de la tourelle
Nacelle (jusqu'à 3) Visée sur la nacelle « Monter dans la nacelle », ou F près de la nacelle
Échelle (jusqu'à 2) Voir « 4. Monter par l'échelle » ci-dessous

3. Manœuvrer

Depuis le poste ou la nacelle, appuyez sur R pour prendre les commandes (une seule personne à la fois). Le pupitre s'affiche.

Touche Action
Q / D Rotation gauche / droite
Z / S Monter / baisser l'échelle (inclinaison)
Maj / Ctrl Sortir / rentrer l'échelle (longueur)
E / A Lever / baisser le bras de nacelle
Flèches Orienter le projecteur
Y Allumer / éteindre le projecteur
U Verrouiller / déverrouiller la nacelle
H Caméra opérateur (molette : distance)
R Lâcher les commandes

Les mouvements démarrent et s'arrêtent progressivement, et ralentissent à l'approche des butées. Le pupitre affiche :

Sécurités automatiques :

4. Monter par l'échelle

  1. Échelle déployée, placez-vous au pied de l'échelle, sur le porteur.
  2. Visée « Gravir l'échelle » ou touche G.
  3. Z pour monter, S pour descendre.
  4. Arrivé en haut, Z fait entrer dans la nacelle, même si elle est verrouillée.

Pour redescendre depuis la nacelle : visée « Redescendre par l'échelle » (au bord de la nacelle, côté échelle) ou touche G. En bas, S fait descendre de l'échelle.

💡 En cas de blocage, /mlexit détache le joueur (échelle, poste ou nacelle).

5. Coffres, portes et écran

6. Replier l'échelle

  1. Ramenez l'échelle en position de route : rotation à 0°, inclinaison à 0°, longueur rentrée, bras de nacelle relevé.
  2. Tout le monde descend (poste, nacelle, échelle).
  3. À l'arrière : visée « Replier l'échelle » ou U devant l'écran (ou U depuis la cabine).

Le repli est refusé tant qu'une condition n'est pas remplie, avec un message qui précise quoi corriger (par exemple « L'échelle n'est pas rangée (rot, ext) »).

7. Choisir son interface

/mlui ouvre les réglages du pupitre :

Les réglages sont gardés d'une session à l'autre. Le serveur peut imposer une interface pour certaines échelles.

Configuration générale

Ce chapitre détaille toutes les options de config/config.lua. C'est ici que vous adaptez MasterLadder à votre serveur : framework, permissions, interface, touches, vitesses, sons et distances. Les échelles elles-mêmes se règlent dans config/ladders.lua (voir Configuration des échelles).

💡 Toute option absente ou invalide reprend sa valeur par défaut, avec un avertissement dans la console : une faute de frappe ne fait jamais planter le script.

1. Licence

2. Langue

3. Framework & permissions

Config.AuthorizedJobs = {
    ['pompier'] = {
        deploy  = 1, -- déployer / replier
        enter   = 0, -- monter au poste ou dans la nacelle
        control = 1, -- manœuvrer l'échelle
        lock    = 0, -- verrouiller les portes
        locker  = 0, -- coffres et écran arrière
    },
}

Le chiffre correspond au grade minimum requis.

Config.CustomPermission = function(source, action, ladder)
    return IsPlayerAceAllowed(source, 'masterladder.use')
end

4. Interface

Une échelle peut aussi imposer son interface : voir interface dans Configuration des échelles.

5. Commandes & touches

Clé Défaut Action
set mlset Déployer / replier (verrou nacelle pendant la manœuvre)
enter mlenter Monter / descendre / changer de place
control mlcontrol Prendre / lâcher les commandes
light mllight Projecteur
lock mllock Verrouiller les portes
camera mlcam Caméra opérateur
ui mlui Réglages de l'interface
climb mlclimb Gravir / redescendre l'échelle
exit mlexit Dépannage : se détacher de l'échelle
admin mladmin Administration

⚠️ FiveM lie les touches au nom de la commande : si vous renommez une commande, les touches personnalisées des joueurs reviennent à la valeur par défaut.

6. Gameplay & mouvement

Vitesses maximales

Inertie et butées

Nacelle

Montée par l'échelle

Caméra opérateur

7. Audio

8. Rendu & réseau

9. Distances

Côté joueur

Côté serveur (anti-triche) : distances maximales tolérées, un peu plus larges que côté joueur.

10. Debug

⚠️ Laissez Config.Debug = false en production : le journal est très bavard.

Configuration des échelles

Ce chapitre explique config/ladders.lua : la liste des véhicules à échelle reconnus par le script, avec leurs props, leurs butées, leurs extras et leurs places. C'est le chapitre le plus technique, mais c'est lui qui permet d'utiliser MasterLadder avec n'importe quel véhicule à échelle.

Principe

Config.Ladders = {
    ['epabspp'] = {
        label = "EPA BSPP",
        props = {
            turntable = "prop_tl2_base",
            D         = "prop_tl2_ladder1",
            C         = "prop_tl2_ladder2",
            B         = "prop_tl2_ladder3",
            A         = "prop_tl2_ladder4",
            S         = "prop_tl2_ladder5",
            basket    = "prop_tl2_cage",
            stab      = "prop_tl2_outriggers",
        },
        interface = { theme = nil, forced = false, model = "ML 32", serial = "N° de série 2004-1187" },
        seat = { angle = 143.24, distance = 1.3, height = 0.24 },
        -- le reste reprend Config.LadderDefaults
    },
}

Identité et props

Déploiement

Butées

Extras du véhicule

💡 Les extras sont appliqués sans réparer le véhicule : les dégâts et les portes ouvertes sont conservés.

Places

Collisions des props

Interface

Ajouter un véhicule

  1. Vérifiez que la ressource du véhicule stream bien le véhicule et les 8 props de l'échelle.
  2. Copiez une entrée existante et renommez la clé avec le nom de spawn du véhicule.
  3. Renseignez label et props.
  4. Ajustez les numéros d'extras du modèle (extras) et l'état de spawn (spawnExtras).
  5. Redémarrez la ressource, déployez, puis ajustez en jeu seat, basketSpots et les butées.

💡 Avec Config.Debug = true, la console signale les props introuvables par leur nom, et /mldebug affiche au-dessus de l'échelle son état complet.

Permissions & Administration

Ce chapitre explique qui peut faire quoi avec l'échelle, et les outils des administrateurs.

Actions contrôlées

Action Ce qu'elle autorise
deploy Déployer et replier l'échelle
enter Monter au poste, dans la nacelle ou sur l'échelle
control Manœuvrer l'échelle
lock Verrouiller les portes du véhicule
locker Ouvrir les coffres, allumer l'écran arrière

Trois façons de gérer les permissions

  1. Tout le monde : Config.JobRestriction = false (par défaut), ou framework standalone.
  2. Par métier et par grade : Config.JobRestriction = true et Config.AuthorizedJobs (voir Configuration générale). Avec QBCore / QBox, Config.RequireOnDuty = true exige d'être en service.
  3. Votre propre règle : Config.CustomPermission, une fonction qui reçoit le joueur, l'action et l'échelle, et retourne false pour refuser. Elle remplace la restriction par métier.

💡 Toutes les vérifications sont faites côté serveur : un joueur ne peut pas les contourner en modifiant son client.

Commande d'administration

Autorisation (dans server.cfg) :

add_ace group.admin command.mladmin allow
Commande Effet
/mladmin list Liste les échelles déployées et leurs occupants
/mladmin evict <netId|cl> [all|op|seat|b1|b2|b3|c1|c2] Fait descendre les occupants (tous par défaut) ; op retire l'opérateur
/mladmin del <netId|cl> Replie instantanément l'échelle et libère le véhicule

cl désigne l'échelle la plus proche de l'administrateur. La commande fonctionne aussi depuis la console serveur (avec un netId).

Dépannage joueur

/mlexit détache le joueur (échelle, poste ou nacelle) s'il reste bloqué.

Débogage & Erreurs

Ce chapitre regroupe les problèmes les plus courants et l'outil de diagnostic intégré.

Le mode debug

Passez Config.Debug = true dans config/config.lua et redémarrez la ressource. MasterLadder écrit alors tout ce qu'il fait :

Exemples de lignes :

[ML:deny] mladder:enter ← Jean #12 : pied de l'échelle à 6.2 m (max 5.0 m)
[ML:deny] mladder:set ← Jean #12 : déploiement : pente 9.4° (véhicule 9.1°) > 8.0° max
[ML:deny] mladder:control ← Jean #12 : « control » : pompier grade 0 < 1 requis
[ML:state] EPAN 42 tl (rév 18) : occ.b1: 0 → 12

Commandes de diagnostic

Pour ne garder qu'une partie du journal : Config.DebugCategories = { "license", "deny", "perm" }.

⚠️ Remettez Config.Debug = false une fois le problème trouvé.

Problèmes fréquents

« Licence MasterMods refusée : script inactif »

« API MasterMods injoignable (code 0) »

Les props de l'échelle n'apparaissent pas

Rien ne se passe en visant le véhicule

« Pente trop forte » / déploiement refusé

Impossible de replier

Le joueur est mal placé sur l'échelle (dans les barreaux, flotte, penché en arrière)

Un joueur est bloqué (attaché, figé)

Les portes du véhicule se referment toutes seules

Support

Si le problème persiste, passez sur discord.mastermods.dev avec :

⚠️ Ne partagez jamais votre MasterKey en entier : les journaux l'affichent toujours masquée.

Formation pour vos joueurs

Voir pièce jointe