Before You Begin#

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
`oxmysql`	Required	Database access. The tables create themselves.
`ox_lib`	Required	Callbacks, notifications and the progress bar.
Inventory	Required	`ox_inventory`, `qs-inventory`, `qb-inventory`, `core_inventory`, `origen_inventory`, `codem-inventory` or `tgiann-inventory`. It must support item metadata.
`tradingcards_props`	Required	Ships in the download. The pack, album and card models held in hand.
Framework	Optional	`es_extended`, `qb-core` or `qbx_core` — auto-detected. With none, the standalone bridge takes over (with `ox_inventory` or `qs-inventory`).
Target	Optional	`ox_target`, `qtarget` or `qb-target`, only if you switch `Config.UseTarget` on. Otherwise NPCs use an `[E]` prompt.
`qs-interface` / `qs-textui`	Optional	Notifications and progress bar, and the 3D `[E]` prompt. ox_lib and a drawn label are used without them.

The resource picks the right bridge by looking at what is already running:

Layer	Detected from
Framework	`es_extended` → `esx` · `qb-core` / `qbx_core` → `qb` · nothing → `standalone`
Inventory	`ox_inventory` · `qs-inventory` · `qb-inventory` · `core_inventory` · `origen_inventory` · `codem-inventory` · `tgiann-inventory`
Target	`ox_target` → `qtarget` → `qb-target` (only with `Config.UseTarget = true`)

Integrations has the details and how to force one by hand.

github.comReleases · overextended/oxmysqlMySQL resource for FXServer.github.comReleases · overextended/ox_libA FiveM resource and script library for Lua and JS.

Downloading Trading Cards#

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:

lua

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 built

Installing the Resource#

Move qs-tradingcards and tradingcards_props into your server's resources directory. They can live anywhere inside it, including a category folder:

lua

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:

bash

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-tradingcards

The 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.

The Database#

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
`qs_tradingcards_cards`	Every card: name, artwork, rarity, lore, stats, the pack it drops from, its theme and whether it is enabled.
`qs_tradingcards_rarities`	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.
`qs_tradingcards_boosters`	The booster packs — item, label, artwork and cards per pack. Seeded with Booster Pack and Legends Pack, five cards each.
`qs_tradingcards_themes`	Card designs made in the theme editor.
`qs_tradingcards_peds`	The shop, grader and trader NPCs you place.
`qs_tradingcard_stashes`	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.

Inventory Items#

Trading Cards uses six items. Ready-to-paste definitions ship in the [items] folder, and their icons in [img].

Item	What it is	Stackable
`tradingcard_basic`	A card of the Basic rarity.	No — every card carries its own metadata.
`tradingcard_rare`	A card of the Rare rarity.	No
`tradingcard_legendary`	A card of the Legendary rarity.	No
`tradingcard_booster_pack`	The standard Booster Pack.	Yes
`tradingcard_booster_legends`	The Legends Pack.	Yes
`tradingcard_stash`	The card album.	No — each album has its own id.

Add to ox_inventory/data/items.lua:

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:

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'] = '' },

Copy the PNGs from [img] to qs-inventory/html/images/.

Add to qb-core/shared/items.lua (or your Qbox item file):

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'] = '' },

Copy the PNGs from [img] to your inventory's image folder — qb-inventory/html/images/ for qb-inventory.

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.

Claiming Creator Access#

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:

bash

add_ace group.admin command.cardcreator allow
# or for a single player
add_ace identifier.license:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx command.cardcreator allow

Automatic. 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.

bash

add_principal identifier.license:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx group.admin

Configuring the Resource#

Almost 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:

lua

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)

Verifying the Installation#

Restart your server and read the console. A healthy start looks like this:

bash

[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:

Open a pack
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.
Store a card
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.
Place a shop
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.

Before You Begin#

Downloading Trading Cards#

Installing the Resource#

The Database#

Inventory Items#

Claiming Creator Access#

Configuring the Resource#

Verifying the Installation#

Open a pack

Store a card

Place a shop

Before You Begin#

Downloading Trading Cards#

Installing the Resource#

The Database#

Inventory Items#

Claiming Creator Access#

Configuring the Resource#

Verifying the Installation#

Open a pack

Store a card

Place a shop

Before You Begin#

Downloading Trading Cards#

Installing the Resource#

The Database#

Inventory Items#

Claiming Creator Access#

Configuring the Resource#

Verifying the Installation#

Open a pack

Store a card

Place a shop

Before You Begin#

Downloading Trading Cards#

Installing the Resource#

The Database#

Inventory Items#

Claiming Creator Access#

Configuring the Resource#

Verifying the Installation#

Open a pack

Store a card

Place a shop