Features

Wallet

ID card, licences, job badge and custom cards, and how players show or hand them over.

The Wallet app holds the character's cards: the ID card, the licences, a job badge, and the tickets, coupons and passes that other scripts hand out. A player can show any card to someone standing next to them, and hand over the cards that allow it.

Everything is switched with Config.Wallet.

#The cards

Card Where it comes from Can be changed on the phone
Identity Card The character: name, date of birth, sex, nationality, blood type, document number No
Licences The licences the framework says the character holds, one card each No
Staff ID (job badge) The character's current job and grade No
Custom cards Other scripts, through the AddCard export Only removed

The first three are built-in cards. They are not stored anywhere: the server reads them from the character every time the Wallet opens. A player who loses a licence in the framework loses the card the next time the app loads. These cards carry the note "Built from your character; it cannot be changed on the phone."

Each built-in card has a document number and a barcode code (ID-…, LIC-…, JOB-…). They are made from the character id, so the same character always shows the same numbers.

#Identity Card

Shows the name, date of birth, sex, nationality, the blood type and the document number, with the player's profile picture. Fields the framework does not have stay empty (Qbox and QBCore have a nationality; ESX only when the character has one set).

#Licences

The licence cards come from the framework:

Framework Where licences are read
QBCore, Qbox metadata.licences of the character. Every licence set to true gives a card
ESX The user_licenses table of esx_license. Without esx_license started there are none
Standalone, custom None

Only licences listed in Licences get a card. The list maps the framework's licence name to the title the card uses (the locale key wallet.licences.<key>):

luaLicences = { driver = 'driver', weapon = 'weapon', business = 'business', hunting = 'hunting', fishing = 'fishing', pilot = 'pilot' },

If your framework calls the driving licence drive (ESX uses names like drive, drive_bike, weapon), add it: drive = 'driver'. A licence that is not in the list is ignored.

#Staff ID

Every character with a job other than unemployed gets a badge card with the job, the grade and a badge number. BadgeJobTypes narrows this to some job types, using the type field of a QBCore or Qbox job (for example { 'leo', 'ems' }). Left empty, every job gets a badge. A framework whose jobs have no type (ESX) cannot be filtered this way, so there every job gets a badge whatever the list says.

#Blood type

The blood type on the ID and the licences is the one from the Health app's Medical ID; see Health. ShowBloodType = false takes it off the cards.

#Custom cards

Other scripts add cards with AddCard: concert tickets, gym memberships, coupons, keys, passes. A card has a kind (ticket, coupon, membership, pass, key, other), a title, optional fields, a code shown as a barcode, an issuer and an expiry date. The player gets the card at once if they are online, otherwise the next time they open the Wallet.

  • A card past its expiry date stays in the Wallet with an Expired flag. The player can remove it. The daily clean-up deletes it Config.Retention.wallet days (default 7) after it expired.
  • The player can remove a custom card with Remove Card. Built-in cards cannot be removed.
  • A card marked transferable = true can be handed to another player.

The exports are on Server exports: wallet: AddCard, RemoveCard, GetCards.

#Showing and handing over a card

  1. The player opens a card and taps Show, or Give on a card that can be handed over.
  2. The phone looks for people within ShowRange metres and lists them as "Person nearby 1", "Person nearby 2" with the distance. Names are never shown: you see a person, not who they are. At most 8 people are listed.
  3. The player picks one.

Show. The other player gets a notification "Someone showed you a card". If their phone is open and unlocked, the card opens on their screen at once, marked "Verified by the server". The card stays with its owner. A card shown to a player stays under Shown to you at the top of their Wallet for ShownMinutes minutes (default 2), and can be opened from its notification for that long. It leaves the list earlier when the player closes it with Done. At most the last 5 are listed.

Give. The card moves to the other player's Wallet and they get a notification with its title. Only custom cards with transferable = true can be given; the ID, licences and badge never can.

The copy the other player sees is built on the server from the owner's real data. The phone that shows the card sends only which card and to whom, so a player cannot forge an ID with a modified page.

#Requiring the items

With RequireItems = true, a built-in card only appears while the matching item is in the player's inventory:

luaItems = { identity = 'id_card', driver = 'driver_license', weapon = 'weaponlicense' },

The keys are identity for the ID card and the licence keys from Licences (driver, weapon, …). A licence with no entry in Items (by default hunting, fishing, business, pilot) needs no item. The job badge never needs one.

#Options

Option Default What it does
Enabled true false switches Wallet off: the icon goes and every request (list, show, give, photo, remove) is refused. Cards scripts added stay stored, and AddCard / RemoveCard keep working
ShowBloodType true Prints the Medical ID's blood type on the ID card and the licences
ShowRange 3.0 Metres: how close someone has to stand to be shown or given a card
ShownMinutes 2 Minutes a card someone showed you stays in the "Shown to you" list and can be opened from its notification
RequireItems false Built-in cards only appear while the matching item is in the inventory
Items identity = 'id_card', driver = 'driver_license', weapon = 'weaponlicense' Item per card, used with RequireItems
Licences driver, weapon, business, hunting, fishing, pilot Framework licence name and the card title it uses
BadgeJobTypes {} Job types that carry a badge. Empty: every job. On ESX (no job types) every job
MaxCustomCards 40 Custom cards one character can hold

#Good to know

  • A licence does not show. Its framework name is not a key in Licences, or (ESX) esx_license is not started, or RequireItems = true and the item is missing.
  • Every job has a badge on ESX although BadgeJobTypes is set. ESX jobs have no type to filter by, so the list is ignored there.
  • The document number on the ID card is the character id (the citizenid on QBCore and Qbox, the identifier on ESX). Keep this in mind if you treat identifiers as private.
  • AddCard returns nil, 'limit' when the player already holds MaxCustomCards cards. Handing a card to a player whose Wallet is full fails with "Their wallet is full."
  • "They are no longer next to you." The other player walked away after the list was made. The list is valid for 60 seconds and the player must still be within ShowRange (plus 1.5 m).
  • Expired custom cards are deleted by the daily clean-up Config.Retention.wallet days after they expired. Set it to 0 to keep them; remove one earlier with RemoveCard.