Documentation
Using Trading Cards on FiveM: opening booster packs, the card album, showing cards, NPC shops, PSA grading and the card trader, plus the in-game creator for cards, rarities, drop rates, themes and NPCs.
Trading Cards has two sides. Players meet it through items and NPCs: they buy packs, open them, keep cards in albums, show them, grade them and trade them. Admins shape all of it from one window, the creator, opened with /cardcreator.
Piece | What it is | Where it is made |
|---|---|---|
Card | One collectible: artwork, name, lore, stats. Handed out as an item with the card's data as metadata. | Creator → Card Creator |
A tier — its colours, effects, how often it drops and which item it is handed out as. |
Creator → Rarities |
Booster pack | An item that, when opened, draws a number of cards from the ones assigned to it. | The |
Theme | The design a card is drawn with. | Creator → Customize theme |
NPC | A shop, a PSA grader or a card trader standing in the world. | Creator → Peds |
Every save in the creator is written to the database and pushed to every player straight away. Nothing needs a restart.
Using a pack starts a progress bar (Config.OpeningTime, 2.5 seconds by default) with the pack in the player's hands. When it finishes the pack is taken from the inventory, the cards are drawn on the server, added to the inventory, and the reveal opens:
Slide the top tab of the pack across to tear it.
Click each card to turn it over, or press Reveal all. The background glows in the colour of the rarest card in the pack, and holographic and sparkling rarities shine as they come out. Click a turned card to look at it up close.
Open Inventory goes straight to the inventory to use the next pack, and Close finishes. The cards are already in the inventory by the time the reveal opens, so closing early loses nothing.
Each pack draws its cards per pack (five by default) one at a time. For each one, a rarity is picked first — weighted by each rarity's Weight, among the rarities that actually have cards in that pack — and then a card of that rarity is picked at random from the pack. Disabled cards never drop.
The starter weights are Basic 55, Rare 32 and Legendary 13. A weight is relative, not a percentage: with only those three rarities in a pack, a Legendary comes out 13 times in every 100 draws. Add a rarity of weight 10 and every share shrinks to make room.
Using a card item opens the Card Interaction panel:
Option | What it does |
|---|---|
View or Show | Shows the card full screen. With |
Store in Album | Lists every album the player carries with its free slots. Pick one and the card moves from the inventory into that album. |
tradingcard_stash is a binder of 180 slots, laid out nine to a page, two pages to a spread. Each album item gets its own id the first time it is used, so a player can carry several and they never mix — and an album handed to someone else takes its cards with it.
Control | What it does |
|---|---|
Search | Finds a card by name. |
Rarity chips | All, or one rarity at a time. |
Previous / Next | Turns the page. |
Click a card | Take puts it back in the inventory as its rarity's item; Show shows it to the players around you, as above. |
Cards inside an album are kept in the database, not in the item, so a full album weighs the same as an empty one and never bloats the inventory.
A shop NPC sells whatever you list on it — booster packs, albums, or any other item — paid in cash or bank. The player talks to the clerk, browses the shelf with their balance on screen, picks an item and a quantity (up to 10 at a time), and pays. Prices are checked and charged on the server.
A shop with no items of its own sells Config.ShopItems: the Booster Pack for 500 and the album for 2,500.
A grader NPC inspects one card at a time for a fee. The player hands over an ungraded card, the grader looks it over for the inspection time, and stamps a rating from 1 to 10 in half steps onto the card itself. A graded card shows its rating on every theme that has a PSA layer, and cannot be graded again.
Bracket | Ratings | Default odds |
|---|---|---|
Poor | 1 – 3 | 30% |
Fair | 3.5 – 6 | 40% |
Good | 6.5 – 9.5 | 27% |
Gem mint | 10 | 3% |
The price (5,000 by default), the account it is charged to and the inspection time are set on the NPC. The brackets above are the defaults for every grader; they can be overridden per grader in the data column of qs_tradingcards_peds.
A trader NPC swaps cards. Its deal is "N of yours for M of mine": the player picks the cards they want to give from their inventory, and receives the trader's cards in return, drawn from its binder.
Setting | What it does |
|---|---|
Cards it asks for | How many cards the player must hand over (1–20, default 2). |
Cards it gives back | How many it hands out (1–20, default 1). |
Only accepts | Any card, or only cards of one rarity. |
Cards it can hand out | Every card in the catalogue, or only the ones you pick. |
Rare card difficulty | 0% keeps the normal rarity weights. Each step up the rarity ladder becomes this much less likely, so 100% means only the commonest cards ever come out. Default 50%. |
/cardcreator opens the creator for anyone with access (see Installation). It has four tabs and opens on Peds.
Tab | What it is for |
|---|---|
Peds | Placing and configuring shop, grader and trader NPCs. |
Card Creator | Every card: making, editing, enabling, deleting and giving them out. |
Rarities | The rarity tiers, their look, their weight and their item. |
Customize theme | The theme editor. |
Press + to create an NPC and fill in its sections:
Section | What you set |
|---|---|
What it is | The role (Shop, PSA Grader or Card Trader), a label shown on the prompt and the blip, the ped model and an idle animation. |
Where it stands | Place in the world hides the window and drops a translucent ghost of the ped where you aim: |
Map blip | Show it on the map, its icon, size and colour. |
Stock (shop) | Payment account, and a list of items, each with the label it is shown as and its price. |
Grading (grader) | Price per card, payment account and inspection time. |
Trading (trader) | The trader settings described above. |
Availability | Switch an NPC off to keep it saved without spawning it. |
Players reach an NPC with an [E] prompt from 3 metres, or through your target resource with Config.UseTarget. The server refuses any purchase, grade or trade from more than 5 metres away.
A searchable list of every card on the left, the form in the middle and a live preview on the right, drawn with the theme that card will really use.
Section | Fields |
|---|---|
Identity | Card name, rarity and artwork URL. |
Stats | Health, attack, height and weight. |
Lore | The description printed on the card body, and an optional secondary line. |
Drop settings | The booster pack it drops from, its card theme (or the rarity's default), its quality (0–100) and Available in packs. |
Give hands a saved card to any online player by server id — or to yourself — as its rarity's item. Delete removes a card from the catalogue: copies players already own keep working, it just never drops again. To keep it but stop it dropping, switch Available in packs off instead.
Section | Fields |
|---|---|
Identity | The id (cannot change once cards use it), the name, and the inventory item its cards are handed out as. |
Look | Four colours that every theme reads, the border colour and width, Holographic (holo sheen, foil sweep and prism layers) and Sparkling (sparkle layers, and the glow when the card comes out of a pack). |
Drops | The weight against the other rarities, and the default theme for its cards. |
The order of the list is the rarity ladder, from commonest to rarest: it decides which card lights up a pack and how the trader's difficulty applies. A new rarity is added at the top of the ladder.
The theme editor builds the card's design out of layers, drawn on a canvas at the card's real size with a rarity of your choice previewed.
Layer | What it draws |
|---|---|
Shape | A rectangle or ellipse with a solid, linear, radial or conic fill, a border, a shadow and blur. |
Text | A fixed text, or bound to the card: name, rarity, lore, secondary line, health, attack, height, weight, quality, PSA rating, serial or card number — with font, size, weight, alignment, a gradient fill and a shadow. |
Image | The card's own artwork or a fixed URL, with cover, contain or stretch, filters and a fade into the card. |
Icon | One of fourteen icons — heart, sword, shield, star, bolt, fire, skull, crown, gem and more. |
Effect | Holographic sheen, foil sweep, sparkles, rotating prism, edge glow, scanlines, grain or vignette. |
Any colour can be a fixed colour or one of the rarity tokens (colours 1–4 and the border), so one theme fits every rarity. Each layer can be limited to some rarities, or shown only once graded or only while ungraded — the way the PSA slab appears on a graded card. Layers can be renamed, hidden, locked, duplicated and reordered, and the arrow keys nudge the selected one (Shift for bigger steps).
Three themes ship built in — Quasar Classic, Neon Prism and Royal Foil. They cannot be deleted; Duplicate one to make your own version. Deleting one of your themes moves every card and rarity that used it back to the default.
Two packs are created on the first start: Booster Pack (tradingcard_booster_pack) and Legends Pack (tradingcard_booster_legends), five cards each. A card belongs to exactly one pack, chosen in its Drop settings.
Packs are rows in qs_tradingcards_boosters, read on start. To add one, insert a row with its item, label and cards per pack, add that item to your inventory, restart the resource, and assign cards to it in the creator:
INSERT INTO qs_tradingcards_boosters (id, item, label, image, zip_image, cards, sort_order)
VALUES ('halloween', 'tradingcard_booster_halloween', 'Halloween Pack', 'opened-pack.png', 'zip_of_pack.png', 3, 3);image and zip_image are the artwork of the pack in the reveal: one of the shipped file names, or a full https:// URL to your own.
With qs-inventory running, every player is given two quests in its quest book: Card Collector (open packs) and PSA Grading (have a card graded), worth 200 and 250. Without qs-inventory this is skipped silently.