Exports et state bags
Deux portes d’entrée, et la plus économique d’abord.
phoneapi <id> affiche tout ce qui suit pour un joueur, dans la console du serveur. Si quelque chose ne renvoie pas le résultat attendu, exécutez cette commande avant d’aller plus loin — c’est bien plus rapide que de deviner de quel côté vient l’erreur.
State bags — les réponses qui ne coûtent rien
Section intitulée « State bags — les réponses qui ne coûtent rien »Un state bag ne nécessite aucun callback, aucun événement et aucun accord avec cette ressource. Il s’agit d’une table lue localement sur la machine qui pose la question, elle survit au redémarrage de cette ressource en arrière-plan, et elle fonctionne de la même manière côté client et côté serveur.
-- serverif Player(src).state.onCallWith then ... end
-- client, about somebody elseif Player(GetPlayerFromServerId(id)).state.phoneOpen then ... end| Bag | Type | |
|---|---|---|
phoneNumber | string | le numéro du téléphone transporté |
phoneName | string | le nom affiché par ce téléphone lorsqu’il appelle quelqu’un |
phoneDevice | string | nil | identifiant de l’item téléphone en mode item. nil quand le téléphone appartient au personnage |
phoneOpen | boolean | le téléphone est sorti et visible à l’écran |
onCallWith | number | nil | la source du correspondant à l’autre bout |
callAnswered | boolean | quelqu’un a décroché. false tant que la sonnerie retentit |
speakerphone | boolean | haut-parleur activé |
mutedCall | boolean | le joueur s’est mis en sourdine |
otherMutedCall | boolean | le correspondant s’est mis en sourdine |
flashlight | boolean | la lampe torche est allumée. Chaque client affiche le faisceau sur ce ped |
phoneCamera | boolean | le viseur est ouvert : le joueur est sur le point de prendre une photo |
phoneSignal | number | nombre de barres, de 0 à Config.Signal.Bars. 0 signifie téléphone injoignable |
Trois points importants :
Ils sont renseignés par le serveur. Le client en a également connaissance et pourrait les publier en moins de lignes, mais un client peut mentir sur chacune de ces valeurs, et un state bag lu par un anticheat doit être digne de confiance.
La sonnerie compte comme un appel en cours. onCallWith est défini dès qu’un téléphone commence à sonner, car la ligne est occupée — ce qui n’est pas encore acquis est que quelqu’un ait décroché, ce qui correspond à callAnswered.
onCallWith peut valoir nil au cours d’un appel réel. L’autre correspondant peut utiliser son navigateur web plutôt que d’être un joueur présent dans la ville. callAnswered reste true ; il n’y a simplement aucun ID de source FiveM à désigner.
Le state bag flashlight n’a été implémenté que lorsque la torche a réellement éclairé la scène, partant du principe qu’un bag valant constamment false est pire qu’un bag absent — l’un est une fonctionnalité manquante, l’autre est une fausse information. La torche éclaire désormais, l’état est donc publié.
Exports serveur
Section intitulée « Exports serveur »exports.mic_phone:GetNumber(src) --> '555-010-2048'exports.mic_phone:GetName(src) --> 'Jean Dupont'exports.mic_phone:GetIdentifier(src) --> 'char1:abc…' or 'device:abc…' in item modeexports.mic_phone:GetDevice(src) --> the phone item's id, or nilexports.mic_phone:HasPhone(src) --> are they carrying one at allexports.mic_phone:IsOpen(src)exports.mic_phone:IsInCall(src)exports.mic_phone:CallWith(src) --> the other source, or nil
exports.mic_phone:GetSource(number) --> src, for a numberexports.mic_phone:NumberOf(identifier) --> works for somebody who is not onlineexports.mic_phone:IdentifierOf(number)
exports.mic_phone:Call(src, number) --> rings it from their phone, exactly as dialling wouldexports.mic_phone:EndCall(src)exports.mic_phone:AddContact(src, name, number, { email =, notes =, favorite = })exports.mic_phone:RemoveContact(src, number)exports.mic_phone:SendNotification(src, { app =, title =, body = })exports.mic_phone:OpenApp(src, 'messages')exports.mic_phone:OpenPhone(src) / ClosePhone(src)
exports.mic_phone:SendMessage(number, text, from)exports.mic_phone:SendMail(identifierOrNumber, fromName, fromAddress, subject, body)exports.mic_phone:SendInvoice(senderSrc, targetNumber, label, amount, society)Call renvoie ce qui aurait été signifié au téléphone lui-même — { ok = false, reason = 'busy' }, 'airplane', 'unknown', 'offline' — car il emprunte le même gestionnaire que le composeur natif du téléphone. Il n’existe qu’une seule branche de code et un seul ensemble de règles susceptibles d’échouer.
Un export dont la réponse est nil ne renvoie aucune valeur, et non une valeur nil. Placé directement dans une liste d’arguments, il ne devient pas "nil" — il raccourcit la liste. Stockez-le d’abord dans une variable locale :
local with = exports.mic_phone:CallWith(src) -- and not print(exports.mic_phone:CallWith(src), x)Le téléphone lui-même
Section intitulée « Le téléphone lui-même »Les questions qu’une autre ressource devait sans cesse trancher par ses propres moyens. Chacune correspond à une vérification que le téléphone effectue déjà, garantissant un comportement strictement identique.
exports.mic_phone:GetBattery(src) --> 0-100, or nil when this city has no battery at allexports.mic_phone:SetBattery(src, 40) --> your own charger, or a story that drains oneexports.mic_phone:IsCharging(src)exports.mic_phone:HasAirplaneMode(src) --> the city cannot reach them; their own phone still works
exports.mic_phone:GetSignal(src) --> 0 to Config.Signal.Bars. Also the `phoneSignal` state bagexports.mic_phone:SetJammed(src, true) --> takes their bars away: a heist, a prison, a story
exports.mic_phone:GetGallery(src) --> every picture: { id, url, width, height, kind, created }exports.mic_phone:AddPhoto(src, url, w, h) --> puts one in it, and it appears without a rebootexports.mic_phone:GetContacts(src)
exports.mic_phone:GetInvoices(src) --> every invoice on that phone, paid and unpaidexports.mic_phone:UnpaidInvoices(src) --> count, total
exports.mic_phone:SendLocation(number, x, y, 'The docks', from) --> a map pin in a conversation
exports.mic_phone:GetSocialHandle(src, 'instapic') --> 'nightshift', or nil if they never signed upexports.mic_phone:SocialPost(src, 'twixel', { text = 'Anybody seen a blue Sultan?' })exports.mic_phone:SetVerified(src, 'twixel', true) --> the tick beside their name, per app
exports.mic_phone:GetRadioChannel(src) --> 12, or nilexports.mic_phone:SetRadioChannel(src, 12) --> 0 takes them off itLe fait que GetBattery réponde nil n’est pas équivalent à répondre 0 : nil indique que ce serveur n’a jamais activé la gestion de la batterie. Un script traitant les deux cas de la même manière empêcherait d’appeler les secours dans une ville où les téléphones ne se déchargent jamais.
AddPhoto valide l’URL par rapport aux hébergeurs autorisés par ce serveur, exactement comme le cliché pris depuis l’appareil photo. Une galerie capable d’afficher n’importe quelle adresse serait une faille permettant d’afficher n’importe quoi.
SocialPost et SetRadioChannel appellent les gestionnaires internes du téléphone, et respectent donc les mêmes règles que l’interface : l’absence de compte sur cette application empêche la publication, et un canal interdit à ce métier est également refusé ici.
Le marché crypto
Section intitulée « Le marché crypto »Six devises tarifées par le serveur via une minuterie inaccessible depuis un client. Tout ce qui suit est formulé en devises entières et en argent — jamais dans les millionièmes utilisés pour les calculs internes —, ainsi un script versant un quart d’unité transmettra 0.25.
exports.mic_phone:Coins() --> every coin: id, name, symbol, price, change, window, historyexports.mic_phone:CoinPrice('santo') --> 42137.55, in money. nil when there is no such coinexports.mic_phone:GetCrypto(src, 'santo') --> 0.4218exports.mic_phone:GetCryptoValue(src) --> what their whole portfolio is worth, in money
exports.mic_phone:AddCrypto(src, 'omen', 12.5) --> true when it landedexports.mic_phone:RemoveCrypto(src, 'omen', 12.5) --> false when they did not have it, and nothing movesexports.mic_phone:SetCoinPrice('omen', 0.4) --> move the market for a storyRemoveCrypto rejette la transaction plutôt que de créer un solde négatif, sa réponse indique donc également si le joueur était en mesure de payer — ce qui est exactement la question qu’une boutique acceptant la cryptomonnaie souhaite poser :
if exports.mic_phone:RemoveCrypto(src, 'omen', price) then giveThem(thing) endLe portefeuille est rattaché soit au personnage soit au téléphone, selon la configuration de Config.Apps.Crypto.Wallet. En mode appareil, voler un téléphone subtilise le portefeuille d’actifs ; en mode personnage, un téléphone volé présente une application vide au voleur. Les exports acceptent un ID source dans les deux cas et n’ont pas besoin de connaître ce mode.
phonecrypto dans la console affiche l’état du marché, phonecrypto <id> détaille les avoirs d’un joueur, et phonecrypto price <coin> <money> ajuste le cours manuellement.
Batterie et lampe torche
Section intitulée « Batterie et lampe torche »Toutes deux s’activent ou se désactivent depuis la configuration — shared/config/battery.lua et Config.Flashlight — la batterie étant désactivée par défaut et la torche activée.
exports.mic_phone:BatteryLevel(src) --> 0-100, or 100 when the battery is switched offexports.mic_phone:IsPhoneCharging(src)exports.mic_phone:ChargePhone(src, true) -- plug in; false unplugsUn chargeur n’a pas nécessairement besoin d’être un item dans une poche. Config.Battery.Charger.Item en fournit un clé en main, et ChargePhone couvre toutes les autres intégrations : câble allume-cigare en véhicule, prise murale, accessoire de bureau.
phonebattery [charge|unplug|full|empty] <id> force l’état, idéal pour tester la batterie sans mettre sa propre patience à l’épreuve.
Commandes d’administration
Section intitulée « Commandes d’administration »Les administrateurs en jeu (ainsi que la console) disposent de quelques commandes pour diagnostiquer un comportement inattendu. Elles permettent d’inspecter ou de modifier délibérément le téléphone d’un joueur ; aucune n’invente de données.
phoneapi <id> | state bags, exports et batterie d’un joueur |
phoneapps | liste des applications telles que résolues par la config |
phonedevice [backup|restore] <id> | quel téléphone le joueur possède et sauvegardes associées |
phonebattery [charge|unplug|full|empty] <id> |
phoneapi affiche également si ce téléphone capte du réseau et les données en attente d’acheminement, ce qui résume la chaîne d’événements entre “aucun signal” et “la notification est arrivée” en deux lignes. Ce flux traversant quatre étapes, il était auparavant complexe d’identifier laquelle bloquait.
Le niveau n’est pas un compte à rebours. Une ligne enregistre le niveau précédent, l’horodatage et l’état du téléphone — ouvert, en poche ou en charge — et le niveau actuel est calculé mathématiquement à l’instant T. Cent joueurs mobilisent cent nombres au lieu de cent timers actifs, et un téléphone laissé en charge pendant un redémarrage du serveur revient rechargé plutôt que figé.
Empêcher votre interface d’apparaître dans les photos des joueurs
Section intitulée « Empêcher votre interface d’apparaître dans les photos des joueurs »(Cette notion ainsi que les règles de cohabitation — le ped, le prop, le mode item — sont rassemblées dans votre ressource à ses côtés.)
Une photo capture l’écran entier. Tout ce que votre ressource affichait au moment du déclenchement — texte d’aide, marqueur 3D, barre de progression — figurera sur l’image, et cette ressource ne peut pas vous empêcher de l’afficher.
phoneCamera est mis à disposition pour vous permettre de suspendre ces affichages. Ce state bag est true dès l’ouverture du viseur jusqu’à sa fermeture ; une seule condition dans votre boucle de rendu résout le problème :
if LocalPlayer.state.phoneCamera then goto skip endL’interface propre au téléphone s’efface d’elle-même : Config.Apps.Camera.HideHud masque la mini-carte et les jauges de vie du jeu tant que l’appareil photo est actif, assurant que le cliché obtenu corresponde fidèlement au cadrage du joueur.
La torche s’appuie sur le state bag flashlight, de sorte que tous les autres clients projettent le faisceau lumineux depuis le ped de ce joueur. Elle ne reste allumée que lorsque le téléphone est sorti et s’éteint dès qu’il est rangé.
Exports client
Section intitulée « Exports client »exports.mic_phone:Open() / Close() / Toggle() / IsOpen()exports.mic_phone:CanOpen() --> ok, reasonexports.mic_phone:Restricted() --> 'Dead' | 'Cuffed' | 'Swimming' | … | nilexports.mic_phone:OpenApp('bank') / CloseApp()exports.mic_phone:GetNumber() / GetDevice() / HasPhone() / IsBooted()exports.mic_phone:IsInCall() / IsTablet() / SetTablet(true)exports.mic_phone:Notify({ app =, title =, body = })Rien ici ne contourne les contrôles que le téléphone s’applique à lui-même. Open et OpenApp rencontrent les mêmes refus qu’un joueur appuyant sur F1, pour les mêmes raisons — un téléphone qui s’ouvrirait alors que son propriétaire est mort sous prétexte qu’une ressource le demande poliment n’est pas un système fiable. CanOpen et Restricted existent pour vous permettre de vérifier l’éligibilité en amont, afin de griser une option plutôt que de proposer un bouton inopérant.
Noms de clés
Section intitulée « Noms de clés »Les noms de state bags correspondent à ceux de lb-phone lorsque la signification est identique, permettant à un script conçu pour ce dernier de fonctionner ici sans la moindre modification.