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

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.

-- server
if Player(src).state.onCallWith then ... end

-- client, about somebody else
if 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

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 mode
exports.mic_phone:GetDevice(src)            --> the phone item's id, or nil
exports.mic_phone:HasPhone(src)             --> are they carrying one at all
exports.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 number
exports.mic_phone:NumberOf(identifier)      --> works for somebody who is not online
exports.mic_phone:IdentifierOf(number)

exports.mic_phone:Call(src, number)         --> rings it from their phone, exactly as dialling would
exports.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

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 all
exports.mic_phone:SetBattery(src, 40)       --> your own charger, or a story that drains one
exports.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 bag
exports.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 reboot
exports.mic_phone:GetContacts(src)

exports.mic_phone:GetInvoices(src)          --> every invoice on that phone, paid and unpaid
exports.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 up
exports.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 nil
exports.mic_phone:SetRadioChannel(src, 12)  --> 0 takes them off it

Le 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

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, history
exports.mic_phone:CoinPrice('santo')        --> 42137.55, in money. nil when there is no such coin
exports.mic_phone:GetCrypto(src, 'santo')   --> 0.4218
exports.mic_phone:GetCryptoValue(src)       --> what their whole portfolio is worth, in money

exports.mic_phone:AddCrypto(src, 'omen', 12.5)     --> true when it landed
exports.mic_phone:RemoveCrypto(src, 'omen', 12.5)  --> false when they did not have it, and nothing moves
exports.mic_phone:SetCoinPrice('omen', 0.4)        --> move the market for a story

RemoveCrypto 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) end

Le 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

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 off
exports.mic_phone:IsPhoneCharging(src)
exports.mic_phone:ChargePhone(src, true)   -- plug in; false unplugs

Un 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

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

(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 end

L’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

exports.mic_phone:Open()  /  Close()  /  Toggle()  /  IsOpen()
exports.mic_phone:CanOpen()        --> ok, reason
exports.mic_phone:Restricted()     --> 'Dead' | 'Cuffed' | 'Swimming' | … | nil
exports.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

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.