Documentation
Install Trading Cards on your FiveM server: requirements, server.cfg load order, the automatic database setup, the starter cards, inventory items for ox_inventory, qs-inventory and QBCore, and creator access.
Before installing Trading Cards, make sure your server meets the minimum requirements. Three things are mandatory — the database driver, ox_lib and an inventory with item metadata, because every card, pack and album is an item. Everything else is optional and detected on its own.
Requirement | Status | Notes |
|---|---|---|
| Required | Database access. The tables create themselves. |
|
Required
Callbacks, notifications and the progress bar. |
Inventory | Required |
|
| Required | Ships in the download. The pack, album and card models held in hand. |
Framework | Optional |
|
Target | Optional |
|
| Optional | Notifications and progress bar, and the 3D |
The resource picks the right bridge by looking at what is already running:
Layer | Detected from |
|---|---|
Framework |
|
Inventory |
|
Target |
|
Integrations has the details and how to force one by hand.
After purchasing Trading Cards, the resource is automatically linked to your CFX Portal account.
Sign in to the CFX Portal using the same account used during checkout, open Granted Assets, and download Trading Cards.
After extracting the download, you should have the following folders:
tradingcards/
├── [img]/ -- inventory icons for the six items
├── [items]/ -- item definitions: ox_inventory, qs-inventory, qb-core
├── tradingcards_props/ -- the pack, album and card models (streamed)
└── qs-tradingcards/
├── shared/config.lua -- what you may edit
├── client/custom/ -- bridges to other resources (editable)
├── server/custom/ -- bridges to other resources (editable)
├── server/webhook.lua -- Discord logs
├── locales/ -- 41 languages
├── database/sql.sql -- optional starter cards
└── web/ -- the interface, already builtMove qs-tradingcards and tradingcards_props into your server's resources directory. They can live anywhere inside it, including a category folder:
resources/
└── [qs]/
├── tradingcards_props/
└── qs-tradingcards/Then open your server.cfg and make sure every dependency — and everything it should detect — starts before Trading Cards:
ensure oxmysql
ensure ox_lib
# Framework (or none, for standalone)
ensure es_extended
# ensure qb-core
# ensure qbx_core
# Inventory, target, interface
ensure ox_inventory
# ensure ox_target
# ensure qs-interface
# ensure qs-textui
ensure tradingcards_props
ensure qs-tradingcardsThe loading order matters. Detection only sees resources that are already started: a framework that starts after Trading Cards is not found and the standalone bridge is used, and an inventory that starts after it stops the resource with No inventory found.
There is nothing you must import. On its first start Trading Cards creates its own tables and writes the starter rarities and booster packs:
Table | Holds |
|---|---|
| Every card: name, artwork, rarity, lore, stats, the pack it drops from, its theme and whether it is enabled. |
| The rarities — colours, holographic and sparkle effects, drop weight and the inventory item each one is handed out as. Seeded with Basic, Rare and Legendary. |
| The booster packs — item, label, artwork and cards per pack. Seeded with Booster Pack and Legends Pack, five cards each. |
| Card designs made in the theme editor. |
| The shop, grader and trader NPCs you place. |
| The contents of every card album. |
A brand-new server has rarities and packs but no cards yet. You have two ways to fill the catalogue:
qs-tradingcards/database/sql.sql adds 82 ready-made cards — 44 in the Booster Pack and 38 in the Legends Pack, across all three rarities, with artwork and lore — plus the three built-in themes. Import it with HeidiSQL or any MySQL/MariaDB client before or after the first start. Every insert skips rows that already exist, so it never overwrites your own data.
Skip the file and make every card in game with /cardcreator → Card Creator. Until there is at least one card, the console prints No cards found on start and packs refuse to open — see Usage.
Trading Cards uses six items. Ready-to-paste definitions ship in the [items] folder, and their icons in [img].
Item | What it is | Stackable |
|---|---|---|
| A card of the Basic rarity. | No — every card carries its own metadata. |
| A card of the Rare rarity. | No |
| A card of the Legendary rarity. | No |
| The standard Booster Pack. | Yes |
| The Legends Pack. | Yes |
| The card album. | No — each album has its own id. |
Add to ox_inventory/data/items.lua:
['tradingcard_basic'] = {
label = 'Basic Card',
weight = 10,
stack = false,
close = true,
},
['tradingcard_rare'] = {
label = 'Rare Card',
weight = 10,
stack = false,
close = true,
},
['tradingcard_legendary'] = {
label = 'Legendary Card',
weight = 10,
stack = false,
close = true,
},
['tradingcard_booster_pack'] = {
label = 'Booster Pack',
weight = 100,
stack = true,
close = true,
},
['tradingcard_booster_legends'] = {
label = 'Legends Pack',
weight = 100,
stack = true,
close = true,
},
['tradingcard_stash'] = {
label = 'Card Album',
weight = 500,
stack = false,
close = true,
},Copy the PNGs from [img] to ox_inventory/web/images/. Running ox_inventory without a framework? Also read the standalone note in Integrations.
Add to qs-inventory/shared/items.lua:
['tradingcard_basic'] = { ['name'] = 'tradingcard_basic', ['label'] = 'Basic Card', ['weight'] = 10, ['type'] = 'item', ['image'] = 'tradingcard_basic.png', ['unique'] = true, ['useable'] = true, ['shouldClose'] = true, ['combinable'] = nil, ['description'] = '' },
['tradingcard_rare'] = { ['name'] = 'tradingcard_rare', ['label'] = 'Rare Card', ['weight'] = 10, ['type'] = 'item', ['image'] = 'tradingcard_rare.png', ['unique'] = true, ['useable'] = true, ['shouldClose'] = true, ['combinable'] = nil, ['description'] = '' },
['tradingcard_legendary'] = { ['name'] = 'tradingcard_legendary', ['label'] = 'Legendary Card', ['weight'] = 10, ['type'] = 'item', ['image'] = 'tradingcard_legendary.png', ['unique'] = true, ['useable'] = true, ['shouldClose'] = true, ['combinable'] = nil, ['description'] = '' },
['tradingcard_booster_pack'] = { ['name'] = 'tradingcard_booster_pack', ['label'] = 'Booster Pack', ['weight'] = 100, ['type'] = 'item', ['image'] = 'tradingcard_booster_pack.png', ['unique'] = false, ['useable'] = true, ['shouldClose'] = true, ['combinable'] = nil, ['description'] = '' },
['tradingcard_booster_legends'] = { ['name'] = 'tradingcard_booster_legends', ['label'] = 'Legends Pack', ['weight'] = 100, ['type'] = 'item', ['image'] = 'tradingcard_booster_legends.png', ['unique'] = false, ['useable'] = true, ['shouldClose'] = true, ['combinable'] = nil, ['description'] = '' },
['tradingcard_stash'] = { ['name'] = 'tradingcard_stash', ['label'] = 'Card Album', ['weight'] = 500, ['type'] = 'item', ['image'] = 'tradingcard_stash.png', ['unique'] = true, ['useable'] = true, ['shouldClose'] = true, ['combinable'] = nil, ['description'] = '' },Add to qb-core/shared/items.lua (or your Qbox item file):
['tradingcard_basic'] = { ['name'] = 'tradingcard_basic', ['label'] = 'Basic Card', ['weight'] = 10, ['type'] = 'item', ['image'] = 'tradingcard_basic.png', ['unique'] = true, ['useable'] = true, ['shouldClose'] = true, ['combinable'] = nil, ['description'] = '' },
['tradingcard_rare'] = { ['name'] = 'tradingcard_rare', ['label'] = 'Rare Card', ['weight'] = 10, ['type'] = 'item', ['image'] = 'tradingcard_rare.png', ['unique'] = true, ['useable'] = true, ['shouldClose'] = true, ['combinable'] = nil, ['description'] = '' },
['tradingcard_legendary'] = { ['name'] = 'tradingcard_legendary', ['label'] = 'Legendary Card', ['weight'] = 10, ['type'] = 'item', ['image'] = 'tradingcard_legendary.png', ['unique'] = true, ['useable'] = true, ['shouldClose'] = true, ['combinable'] = nil, ['description'] = '' },
['tradingcard_booster_pack'] = { ['name'] = 'tradingcard_booster_pack', ['label'] = 'Booster Pack', ['weight'] = 100, ['type'] = 'item', ['image'] = 'tradingcard_booster_pack.png', ['unique'] = false, ['useable'] = true, ['shouldClose'] = true, ['combinable'] = nil, ['description'] = '' },
['tradingcard_booster_legends'] = { ['name'] = 'tradingcard_booster_legends', ['label'] = 'Legends Pack', ['weight'] = 100, ['type'] = 'item', ['image'] = 'tradingcard_booster_legends.png', ['unique'] = false, ['useable'] = true, ['shouldClose'] = true, ['combinable'] = nil, ['description'] = '' },
['tradingcard_stash'] = { ['name'] = 'tradingcard_stash', ['label'] = 'Card Album', ['weight'] = 500, ['type'] = 'item', ['image'] = 'tradingcard_stash.png', ['unique'] = true, ['useable'] = true, ['shouldClose'] = true, ['combinable'] = nil, ['description'] = '' },core_inventory, origen_inventory, codem-inventory and tgiann-inventory each have their own item format. Register the same six names with the same rules: the three cards and the album unique / not stackable and usable, the two packs stackable and usable. The icons are in [img].
A rarity you create later in the creator is handed out as the item you name on it, so that item has to exist in your inventory too. The same goes for any extra booster pack.
Everything about the collection is edited in the creator, opened with /cardcreator. It is checked on the server, and any of these routes lets a player in:
Add the permission to a group or a single identifier in server.cfg, then restart the resource:
add_ace group.admin command.cardcreator allow
# or for a single player
add_ace identifier.license:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx command.cardcreator allowAutomatic. A player whose framework group is admin, superadmin or god is let in — the ESX group, or the QBCore/Qbox permission. Change the list in Config.CardCreator.adminGroups.
Without a framework there are no groups, so the same list is read from aces: a player in group.admin, group.superadmin or group.god is let in.
add_principal identifier.license:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx group.adminAlmost nothing is configured in files. Cards, rarities, drop weights, themes, shops, graders and traders are all edited in game. shared/config.lua is for plumbing:
Config.Language = GetConvar('qs:locale', 'es') -- or set `setr qs:locale "en"` in server.cfg
Config.Framework = ... -- auto-detected; 'esx', 'qb' or 'standalone' to force one
Config.Inventory = ... -- auto-detected; see Integrations
Config.UseTarget = false -- third eye on the NPCs instead of the [E] prompt
Config.EnableControlsWhenFocus = true -- the game keeps reading keys while an overlay is open
Config.OpeningTime = 2500 -- pack opening progress bar, in ms
Config.ShowToPlayers = true -- "Show" displays the card to every player within 3 m
Config.ShowAnimation = true -- hold a physical card prop while showing it
Config.ShopItems = { -- stock for shop NPCs that have none of their own
{ name = 'tradingcard_booster_pack', price = 500 },
{ name = 'tradingcard_stash', price = 2500 },
}
Config.CardCreator = {
command = 'cardcreator',
permission = 'command.cardcreator',
adminGroups = { 'admin', 'superadmin', 'god' },
}
Config.Debug = true -- [DEBUG] lines in the console; set false in production
Config.VisualMode = false -- open packs without taking the pack or giving the cards (testing)Restart your server and read the console. A healthy start looks like this:
[INFO] Seeded default rarities.
[INFO] Seeded default booster packs.
[INFO] Catalog loaded: 82 cards, 3 rarities, 2 boosters, 3 themes.
[INFO] Loaded 0 NPC(s).The two Seeded lines only appear on the very first start. 0 cards with a red No cards found line means the starter cards were not imported and none have been created yet.
Then join the server and work through the first loop:
Give yourself a tradingcard_booster_pack and use it. The progress bar runs with the pack in your hands, then slide the top tab to tear it open and flip the five cards.
Give yourself a tradingcard_stash, use one of the cards you pulled and pick Store in Album. Use the album to see it on the first page.
Type /cardcreator. It opens on the Peds tab: create a Shop NPC, press Place in the world, aim, click, and save. Usage covers everything from there.
Nothing needs a restart from here on. Cards, rarities, themes and NPCs are saved to the database and pushed to every player as you save them.
Copy the PNGs from [img] to qs-inventory/html/images/.
Copy the PNGs from [img] to your inventory's image folder — qb-inventory/html/images/ for qb-inventory.