All resources

rsg-cards – documentation#

For server owners and developers. Player-facing overview and install steps are in README.md.

Contents#

  1. Architecture
  2. Data formats
  3. Exports
  4. Events and callbacks
  5. Integration examples
  6. Configuration reference
  7. Flows
  8. NUI reference
  9. Locales
  10. Useful SQL
  11. Persistence
  12. Security model
  13. Database schema
  14. Server owner how-tos
  15. Vendor and card boxes
  16. Troubleshooting

Architecture#

FilePurpose
fxmanifest.luaResource manifest. Locales are loaded by rsg-core (@rsg-core/shared/locale.lua)
shared/config.luaAll settings: sets, prices, pack chances, cooldowns, NPC locations
shared/cards_points.luaConfig.CardPoints: starting world locations. Only copied into the database on the first start; the database is the source of truth afterwards
shared/cards.luaBuilds the global Cards lookup tables from Config.Sets
server/server.luaDatabase setup, shared server helpers (CardsServer), packs, world pickups, collection tracking, storage box, inspect usable items
server/points.luaCard locations in rsg_cards_points, the CardsServer.points registry, sync to clients and the admin editor (/cardplace, /cardmove, /cardremove, /cardedit, /cardmissing)
server/collection.luaSet completion (bonus, first collector), collection viewer and leaderboard data, /cardcollection, leaderboard names
server/vendor.luaCard vendor: selling cards and sets, making sets from 12 cards, rsg-inventory shop for packs and boxes
server/trades.luaCard collectors: rotating requests and trades, /refreshcardtrades
server/ptrade.luaPlayer to player trading: sessions, offers, ready flags and the exchange, /cardtrade
client/client.luaNUI bridge (focus, push-to-talk whitelist, closes the UI on death or when walking away, Config.CloseDistance), pack / vendor / collector UI, card inspect, shared CardsClient.loadModel
client/world.luaNPCs, blips, prompts, world card props, pickups, Eagle Eye hint, cleanup
html/NUI (house "leather & gold" style). html/img holds the card artwork, named <item>.png
locales/*.json11 languages with identical keys
install.sqlManual database install (same schema the script creates itself)
installation/Items for rsg-core and images for rsg-inventory

Flow of a reward (the same pattern everywhere): the client only asks ("flip card 2", "pick up point 17", "sell 3 of X at shop Y"); the server validates, decides the result, changes the inventory or money, and returns what the UI should show.

Data formats#

Items#

ItemTypeNotes
card_package_cardsuseable, category cardpackCard pack
card_storage_boxuseable, unique, shouldClose = falseinfo.serie holds the box serial once registered
card_cigcard_<set>_c<1-12>useable, category cardSingle card
card_cigcard_<set>not useable, category cardsetComplete set. Made from one each of that set's 12 cards

Set ids: act, amer, aml, inv, art, grl, lnd, plt, gun, hrs, spt, veh.

Config.Sets entry#

{ id = 'aml', tier = 'basic', cardPrice = 0.50, deckPrice = 15.00, landscape = true }

tier is one of basic, rare, ultra, v, vmax and must match a tier in Config.Pack.Chances. landscape picks the wide-card inspect animation.

Cards (global, client and server)#

FieldContent
Cards.Info[item]{ set, tier, price, order, deck } for sets; plus number, model, landscape for single cards
Cards.ListEvery single-card item name, in set order
Cards.DecksEvery complete-set item name
Cards.ByTier[tier]Single-card item names of that tier
Cards.TotalNumber of single cards (144)

Card location (CardsServer.points[id], server) / points[id] (client)#

{ id = 17, item = 'card_cigcard_plt_c1', coords = vector4(2238.9, -768.7, 43.4, 77.0), exact = false }

exact = true means the location was set with the gizmo, so the prop is not snapped to the ground. Locations seeded from the config use exact = false.

Config.CardPoints entry (only used to seed the database)#

{ item = 'card_cigcard_plt_c1', coords = vector4(2238.9089, -768.6769, 43.4078, 77.0264) }

One entry per card; the item name is also the cooldown key, so don't list the same card twice.

Collector request (server memory)#

{ id = '3:1', set = 'act', reward = 'card_cigcard_act', amount = 1, cards = { 'card_cigcard_act_c2', ... } }

id is <rotation>:<index>, so a request from an old rotation can't be redeemed.

Storage box stash#

Stash id box_<serial>, opened with exports['rsg-inventory']:OpenInventory. Contents are stored by rsg-inventory.

  • Open / close: using the box opens it beside the player inventory. Using the same box again while it is open calls OpenInventory(src) with no stash, which removes the box panel and leaves the inventory open.
  • Bundle Sets: with Config.Storage.BundleSets = true the box is opened with actions = { { id = 'bundle_sets', label = locale('bundle_sets') } }, which rsg-inventory (3.2.0+) shows as a button under the box name. A click arrives as the local server event rsg-inventory:stashAction (src, stashId, actionId). rsg-cards then counts the single cards in the box and, for each set, removes n of every card (n = the lowest count of any card in that set) and adds n complete-set items to the box. If the set can't be stored in the box it goes to the player, then to the ground; if a removal fails the cards already taken are put back. Only cards inside the box count, not the ones in the satchel. On an older rsg-inventory the actions option is ignored and the button simply doesn't appear.
  • Sort & Stack: with Config.Storage.SortButton = true the box also gets a sort_box button (Config.Storage.SortOnOpen = true runs the same sort every time the box opens). The server reads the box contents, merges identical non-unique items (same name and same info) into one entry, orders them (complete sets, single cards by set and card number, packs, anything else by name) and, if the box is not already stacked and in order, takes every item out and adds them back in that order so rsg-inventory fills slots 1, 2, 3... Nothing is deleted: if a removal or add fails, the items already taken out are put back in the box, else given to the player, else dropped. Unique items are never merged. Rate limited to once every 2 s and only works on the box that player has open.
  • Card-only rule: rsg-inventory has no per-stash item filter, so rsg-cards checks the box itself: when it opens, after every move in or out of it (it listens to rsg-inventory:server:move), and when the inventory closes. Anything that is not a rsg-cards card, set or pack, and whose category is not in Config.Storage.AllowedCategories, is removed from the box and given back to the player, or dropped at their feet if they can't carry it.

Exports#

rsg-cards has no exports. Other resources work with the items directly through rsg-inventory (see the integration examples). The Cards table only exists inside this resource.

Events and callbacks#

Other resources normally don't need these. They are listed so you know what each one checks.

Server callbacks (RSGCore.Functions.CreateCallback)#

NameArgumentsReturnsChecks
rsg-cards:server:flipCardindexcard data or falsePlayer has an open pack, index valid and not flipped yet
rsg-cards:server:getPickups–{ [item] = secondsLeft }–
rsg-cards:server:getPoints–list of { id, item, x, y, z, w, exact }Waits (up to 10 s) until the points are loaded from the database
rsg-cards:server:pickupCardpointIdcard data + cooldown, { cooldown } or falseDistance to the point, per-character cooldown, rate limit, inventory space
rsg-cards:server:getVendorshopId{ items, sets, boxesOnly } or falseDistance to the vendor, rate limit (0.5 s). sets = sets the player holds all 12 cards of; boxesOnly mirrors Config.Shop.BoxesOnly (the UI uses it to explain an empty list)
rsg-cards:server:sellshopId, item, amount{ message, type, items, sets } or falseDistance, item is a card, whole amount ≥ 1 and owned, rate limit. Price from Config.Sets
rsg-cards:server:sellAllshopId{ message, type, items, sets } or falseDistance, rate limit. Only cards and sets are sold
rsg-cards:server:makeSetshopId, setId{ message, type, items, sets } or falseDistance, Config.Shop.CraftSets, set exists, all 12 cards owned, inventory space, rate limit. A failed removal refunds
rsg-cards:server:sellDuplicatesshopId{ message, type, items, sets, duplicates } or falseDistance, Config.Shop.SellDuplicates, rate limit. Sells everything beyond one of each single card (complete sets are never touched) and saves each box once
rsg-cards:server:getCollection–{ sets, found, total, board, myRank } or falseRate limit (1 s). sets = every set with its 12 cards and whether the player found each, first (name of the first player to complete it), firstMe; board = top collectors (cached Config.Collection.CacheSeconds); myRank only when the player is not in the top list
rsg-cards:server:getTradeslocationId{ offers, refresh } or falseDistance to the collector, rate limit (0.5 s). Each offer has done = true when the player already completed it
rsg-cards:server:tradelocationId, offerId{ message, type, offers, refresh } or falseDistance, request still active, not already completed by this player (Config.Trades.OncePerPlayer), every card owned, inventory space, rate limit. A failed removal or reward refunds the cards

Card data: { item, label, image, tier, deck, isNew, collected, total, setComplete }. setComplete is true when this card was the last one the character needed to find in its set.

Server net events#

NameArgumentsPurpose
rsg-cards:server:closePack–Pack UI closed: gives the cards that were not turned over
rsg-cards:server:claimUnclaimed–Sent by the client on login: gives the cards queued in rsg_cards_unclaimed (rate limited, stops when the inventory is full and keeps the rest queued)
rsg-cards:server:ptradeRequesttargetIdAsk a player to trade. Checks the feature is on, the target is another online player, neither is in a trade, they are within Config.PlayerTrade.Distance, rate limit (3 s)
rsg-cards:server:ptradeRespondacceptThe invited player accepts or declines (only valid for the invited player of an open request)
rsg-cards:server:ptradeOffername, amountSet how many of a card/set the player offers (0 takes it back). Checks it is a card item, whole amount, owned (minus the copy kept when DuplicatesOnly) and within MaxPerSide. Clears both Ready flags
rsg-cards:server:ptradeReadyreadySets the player's Ready flag. When both are ready the server re-checks everything and swaps the cards
rsg-cards:server:ptradeCancel–Leave the trade (also sent when the window is closed)
rsg-cards:server:pointAdditem, x, y, z, headingAdmin: add a card location. Checks Config.Editor, permission, rate limit (1 s), finite numbers, admin within Config.Editor.Distance, single card, no location yet for that card
rsg-cards:server:pointMoveid, x, y, z, headingAdmin: move a location (same checks, the id must exist)
rsg-cards:server:pointRemoveidAdmin: delete a location (same checks, admin near the location)
rsg-cards:server:openShopshopIdOpens the rsg-inventory shop (distance checked)
rsg-cards:server:boxClosed–Inventory closed: checks the box contents one last time
rsg-inventory:server:move–Also handled here (read-only) to check the open box after a move

Server local events (not net events)#

NameArgumentsPurpose
rsg-inventory:stashActionsrc, stashId, actionIdSent by rsg-inventory when a stash header button is clicked. rsg-cards acts on actionId = 'bundle_sets' and 'sort_box' for the box that player has open

Client events#

NameArgumentsPurpose
rsg-cards:client:openPackamount(net) Sent by the server after a pack was consumed
rsg-cards:client:inspectCarditem(net) Hold and look at a card
rsg-cards:client:boxOpened–(net) Starts watching for the inventory to close
rsg-cards:client:openCollection–(net) Open the collection viewer
rsg-cards:client:tradeInvitename(net) Another player wants to trade: shows the accept / decline window
rsg-cards:client:tradeStatestate(net) Current offers of a player trade (opens or updates the window)
rsg-cards:client:tradeClosedreason(net) Trade ended: declined, cancelled, done, expired, distance, full or changed (each has an ptrade_<reason> locale text)
rsg-cards:client:openVendorshopId(local) Open the vendor UI
rsg-cards:client:openTradeslocationId(local) Open the collector UI
rsg-cards:client:takecardpointIndex(local) Pick up a world card (used by prompts)
rsg-cards:client:revealCardcard data(local) Show a found card
rsg-cards:client:setPointid, dataA card location was added, moved (data = { id, item, x, y, z, w, exact }) or removed (data = nil)
rsg-cards:client:editorPlaceitemAdmin: start placing a card with rsg-gizmo
rsg-cards:client:editorMove / editorRemove / editorToggle–Admin: move or remove the nearest spawned card, or toggle showing all cards

Commands#

CommandPermissionPurpose
/refreshcardtradesadminNew collector requests immediately
/cardcollectioneveryoneOpen your collection and the leaderboard (Config.Collection.Command)
/cardtrade [id]everyoneAsk a nearby player to trade cards (Config.PlayerTrade.Command)
/cardplace [card]Config.Editor.PermissionPlace a card with rsg-gizmo (grl_c1 or the full item name)
/cardmoveConfig.Editor.PermissionMove the nearest spawned world card with rsg-gizmo
/cardremoveConfig.Editor.PermissionDelete the nearest spawned world card
/cardeditConfig.Editor.PermissionToggle showing all world cards regardless of your cooldowns
/cardmissingConfig.Editor.PermissionList cards without a world location

Integration examples#

Give a pack as a reward from another script (server side):

if exports['rsg-inventory']:CanAddItem(src, 'card_package_cards', 1) then
    exports['rsg-inventory']:AddItem(src, 'card_package_cards', 1, nil, nil, 'my-script:reward')
end

Check whether a player holds a complete set (server side):

local hasSet = exports['rsg-inventory']:HasItem(src, 'card_cigcard_gun', 1)

Query a character's collection progress:

local found = MySQL.scalar.await('SELECT COUNT(*) FROM rsg_cards_collection WHERE citizenid = ?', { citizenid })

Pay a card reward from another script, with a notification (rsg-core notify, server side):

RegisterNetEvent('my-script:server:reward', function()
    local src = source
    local Player = RSGCore.Functions.GetPlayer(src)
    if not Player then return end
    -- validate everything here (distance, cooldown...) - never trust the client

    local card = 'card_cigcard_act_c1'
    if exports['rsg-inventory']:CanAddItem(src, card, 1) then
        exports['rsg-inventory']:AddItem(src, card, 1, nil, nil, 'my-script:reward')
        TriggerClientEvent('RSGCore:Client:Notify', src, {
            title = 'Reward', description = 'You received a card', type = 'success', duration = 5000,
        })
    end
end)

Count a player's cards, including cards inside card boxes (rsg-cards helpers are local to the resource, so use rsg-inventory from outside):

local items = exports['rsg-inventory']:GetItemsByName(src, 'card_cigcard_act_c1') or {}
local total = 0
for _, item in pairs(items) do total = total + (item.amount or 0) end

Add an item reward to the set bonus (shared/config.lua):

Config.SetBonus = {
    Enabled = true, Payment = 'cash', Multiplier = 2.0,
    Items = { { name = 'goldbar', amount = 1 } },
}

Add a new set (items card_cigcard_xyz and card_cigcard_xyz_c1..c12, the artwork html/img/<item>.png and an entry in rsg-core shared items are needed):

{ id = 'xyz', tier = 'rare', cardPrice = 0.50, deckPrice = 65.00 },

Add a vendor (unique id):

{ id = 'CardshopValentine', coords = vector3(-282.5, 804.9, 119.4),
  npcmodel = `mp_u_f_m_nat_traveler_01`, npccoords = vector4(-282.5, 804.9, 119.4, 100.0) },

Start a trade from another script (client side, same as the target):

TriggerServerEvent('rsg-cards:server:ptradeRequest', GetPlayerServerId(NetworkGetPlayerIndexFromPed(ped)))

Open the collection viewer from a radial menu or another script:

TriggerEvent('rsg-cards:client:openCollection')

Configuration reference#

Every option in shared/config.lua. Tables list the default.

General#

OptionDefaultDescription
Config.DebugfalseExtra console output
Config.VersionChecktrueCheck GitHub for a new version on start
Config.AutoDatabasetrueCreate the tables on start. false = import install.sql yourself
Config.AllowPushToTalkWhileOpentrueKeep voice keys working while a UI is open
Config.PushToTalkControls{ 0x4BC9DABB }Control hashes passed through to the game while the UI has focus
Config.CloseDistance6.0Vendor, collector and trade UIs close when the player walks this far away (or dies)
Config.ImagePathnui://rsg-inventory/html/images/Where item thumbnails come from
Config.Items.Pack / Boxcard_package_cards / card_storage_boxItem names of the pack and the storage box
Config.EnableTargettruetrue = rsg-target, false = rsg-core prompts
Config.FadeIntrueFade NPCs and card props in and out
Config.DistanceSpawn20.0Distance at which NPCs and world cards spawn

Sets, packs and world cards#

OptionDefaultDescription
Config.CardsPerSet12Cards in a set. Items are card_cigcard_<id>_c1..cN
Config.Sets[]12 sets{ id, tier, cardPrice, deckPrice, landscape? }. id forms the item names, tier is basic rare ultra v vmax, landscape = true renders the cards sideways
Config.Pack.Cards4Cards per pack
Config.Pack.OpenTime3000Progress time in ms
Config.Pack.Chances[]sums to 1000{ tier, weight }. tier = 'deck' can give a complete set. Weights are relative
Config.Card.Key'J'Prompt key (prompt mode)
Config.Card.PickupTime / PickupDistance3000 / 3.0World pickup progress (ms) and server distance check
Config.Card.Cooldown360Minutes before the same character can take the same world card again
Config.Card.InspectTime15000Maximum time a card is held when used from the inventory
Config.Card.EagleEyeenabled, 50.0{ enabled, distance, soundRef, soundName }: heartbeat hint when a card is near
Config.Blipsee fileshowblipShop, showblipCollect, showblipCards and sprite/scale for each
Config.Soundsenabled, 0.8{ enabled, volume, open, flip }. Needs interact-sound

Storage box#

OptionDefaultDescription
Config.Storage.MaxWeight / MaxSlots500 / 156Stash size
Config.Storage.OpenDelay300ms between use and opening, so the inventory can close first
Config.Storage.BundleSetstrueShow the Bundle Sets button
Config.Storage.SortButtontrueShow the Sort & Stack button
Config.Storage.SortOnOpenfalseSort and stack every time the box opens
Config.Storage.AllowedCategoriescard, cardset, cardpackItem categories a box accepts

Vendors, collectors and bonuses#

OptionDefaultDescription
Config.Shop.Key'J'Prompt key
Config.Shop.Payment'cash'cash or bloodmoney, used for buying and selling
Config.Shop.InteractDistance5.0Server distance check
Config.Shop.PersistStocktrueKeep vendor stock across restarts
Config.Shop.CraftSetstrueAllow making a set from 12 cards
Config.Shop.SellDuplicatestrueSell Duplicates button (keeps one of each card)
Config.Shop.BoxesOnlytrueVendors only look in carried card boxes
Config.Shop.Items[]pack, box{ name, amount, price } stock of the rsg-inventory shop
Config.Shop.Locations[]2{ id, coords, npcmodel, npccoords } (ids must be unique)
Config.Trades.*see fileKey, Refresh (min), MaxActive, MinCards, MaxCards, RewardAmount, OncePerPlayer, InteractDistance, Locations[]
Config.Collection.Command'cardcollection'Opens the collection and leaderboard
Config.Collection.LeaderboardSize10Rows on the leaderboard
Config.Collection.CacheSeconds60Leaderboard cache time
Config.Collection.AnnounceFirsttrueNotify everyone when someone is first to complete a set
Config.SetBonus.EnabledtruePay a bonus the first time a character completes a set
Config.SetBonus.Payment'cash'cash or bloodmoney
Config.SetBonus.Multiplier2.0Money = the set's deckPrice x this (0 = no money)
Config.SetBonus.Items[]{}Extra items { name, amount }
Config.PlayerTrade.EnabledtruePlayer to player trading
Config.PlayerTrade.Command'cardtrade'/cardtrade [id]
Config.PlayerTrade.Distance5.0Both players must be this close (server checked; +3.0 tolerance during the swap)
Config.PlayerTrade.InviteSeconds30How long a request stays open
Config.PlayerTrade.MaxPerSide30Most cards one player can offer
Config.PlayerTrade.DuplicatesOnlytrueOnly spare copies can be offered; one of each single card is kept
Config.PlayerTrade.CountAsFoundtrueReceived cards count for the collection, set bonus and leaderboard
Config.Editor.EnabledtrueAdmin card editor and the commands
Config.Editor.Permission'admin'Permission for the editor commands (also checked on the server for every edit)
Config.Editor.SeedFromConfigtrueCopy Config.CardPoints into the database when rsg_cards_points is empty
Config.Editor.Distance10.0Admin must be this close to the location (server checked)
Config.Webhookrsg-cards{ Name, Title, Colour }; Name must match an rsg-log webhook

Flows#

Editing a card location#

/cardplace grl_c1 -> server validates the name and sends rsg-cards:client:editorPlace -> client exports['rsg-gizmo']:Place(model, { rotation = 'z' }) -> on confirm rsg-cards:server:pointAdd(item, x, y, z, heading) -> server checks permission, throttle, that the numbers are finite, the admin is within Config.Editor.Distance, the card is a single card with no location yet -> inserts the row -> rsg-cards:client:setPoint to everyone. pointMove and pointRemove work the same way on an existing id.

Opening a pack#

  1. Player uses card_package_cards; the server removes the pack, the client opens the NUI (mode pack) and the server and rolls Config.Pack.Cards cards from Config.Pack.Chances (all decided server side).
  2. The client posts flip with a slot; the server hands out that card (grantCard), records it (CardsServer.markFound) and returns the card plus setComplete.
  3. Unflipped cards are given when the UI closes, the player drops, or the resource stops. Cards that can't be given are stored in rsg_cards_unclaimed.

World card pickup#

Client asks pickup <pointId> (the rsg_cards_points id) -> server checks the point exists, distance (Config.Card.PickupDistance), cooldown (rsg_cards_pickups) and throttle -> gives the card -> markFound.

Sell, sell all, sell duplicates, make set#

Client posts the action with names/amounts only. The server takes the prices from Config.Sets, checks distance (CardsServer.findLocation), counts cards (countCards), removes them (removeCards, all-or-nothing, refund on failure) and pays with AddMoney. Sell Duplicates keeps one of each single card; Make Set removes cards 1-N and adds the set item (refunds if it can't be added).

Set completion#

CardsServer.markFound -> recordCard (insert into rsg_cards_collection) -> if the card is new, checkSetComplete: counts the set's cards, INSERT IGNORE into rsg_cards_bonuses (unique citizenid, set_id, so it can only pay once), pays giveBonus, logs, and announces when the lowest id for that set is this character.

Player trade#

A: /cardtrade 12 (or target)      server: session{a, b, phase='invite'} + timeout
B: tradeInvite  -> Accept         server: phase='open', push state to both
A/B: ptradeOffer(name, amount)    server: validates against own cards, clears BOTH ready flags
A/B: ptradeReady(true)            server: when both ready and anything is offered -> execute()
execute(): re-check ownership, distance, CanAddItem -> remove from both (rollback on failure)
           -> hand over (refund on failure) -> log -> close 'done' -> mark received cards found

Close reasons (locale ptrade_<reason>): declined, cancelled, done, expired, distance, full, changed.

NUI reference#

Messages from Lua to the page (SendNUIMessage):

actionFieldsPurpose
openmode, data, strings, imagePathShow a view. mode is pack, reveal, vendor, trade, collection or ptrade
updatemode = 'ptrade', dataLive update of the trade window
closeHide everything

NUI callbacks (page -> RegisterNUICallback, each is validated again on the server):

CallbackBodyServer side
closeReleases focus, finishes an open pack, cancels a trade
flip{ index }Reveals one pack card (rsg-cards:server:flipCard)
sell / sellAll / sellDuplicates{ name, amount } / noneVendor sales
makeSet{ id }Make a complete set (set id)
buyCloses the UI and opens the rsg-inventory vendor shop
collectionOpens the collection viewer (rsg-cards:server:getCollection)
trade{ id }Complete a collector request (rsg-cards:server:trade)
ptradeRespond / ptradeOffer / ptradeReady{ accept } / { name, amount } / { ready }Player trade

Locales#

Language comes from rsg-core's rsg:locale convar (for example setr rsg:locale de). The 10 files in locales/ (en, de, el, es, fr, ja, nl, pl, pt-br, ro, ru) must keep identical keys and the same %s/%d placeholders in the same order.

To add a text: add the key to en.json, translate it into the other nine, use locale('key', ...) on the server or client. If the UI needs it, also add it to getStrings() in client/client.lua and read it from strings in html/script.js. Some keys are built at runtime (ptrade_<reason>, vendor_empty*, inventory_full_dropped), so keep them even if a search for the full key finds no use.

Useful SQL#

-- how many cards a character has found
SELECT COUNT(*) FROM rsg_cards_collection WHERE citizenid = 'ABC12345';

-- first collector of each set
SELECT b.set_id, p.name FROM rsg_cards_bonuses b
JOIN (SELECT set_id, MIN(id) id FROM rsg_cards_bonuses GROUP BY set_id) f ON f.id = b.id
LEFT JOIN rsg_cards_profiles p ON p.citizenid = b.citizenid;

-- top collectors
SELECT p.name, COUNT(*) found FROM rsg_cards_collection c
LEFT JOIN rsg_cards_profiles p ON p.citizenid = c.citizenid
GROUP BY c.citizenid, p.name ORDER BY found DESC LIMIT 10;

-- cards waiting to be handed over
SELECT * FROM rsg_cards_unclaimed;

Persistence#

DataWhereNotes
Cards a character has ever foundrsg_cards_collectionWritten when a single card is given by a pack or a pickup
World card locationsrsg_cards_pointsOne row per card location. Filled from Config.CardPoints when the table is empty, then edited in game. Changes are sent to every client straight away
World card cooldownsrsg_cards_pickupsUnix time of the last pickup per character and card. Cached in memory while the player is online
Storage box registryrsg_cards_boxesSerial, creator, last user. Box contents live in rsg-inventory's stash storage
Collector requestsmemoryRegenerated on resource start and every Config.Trades.Refresh minutes. Who completed which request is kept in memory until the next refresh
Open packsmemoryCards not yet turned over are given when the UI closes, the player leaves, or the resource stops
Set completionsrsg_cards_bonusesOne row per character and set the first time all cards were found. Pays the set bonus once (unique key), and the lowest id per set is the "first collector". Characters who had already completed a set when the table was added are recorded on start without a bonus
Leaderboard namesrsg_cards_profilesCharacter name per citizenid, updated on login, when a new card is found and when the collection is opened
Player tradesmemoryA trade only exists while both players are online and in the window; nothing is written until the swap
Cards that could not be handed overrsg_cards_unclaimedA pack card that can't be given (player already gone when they disconnect, inventory full and nowhere to drop it) is stored here by citizenid and given on the next login (rsg-cards:server:claimUnclaimed), so it is never lost
Vendor stockrsg-inventoryPersistent when Config.Shop.PersistStock = true

Security model#

What the script enforces:

  • The client never names a reward, price or amount of money. Packs are rolled on the server when the pack item is removed; flipping a card only reveals a card the server already chose.
  • Every callback and event resolves the player and returns early if there is none.
  • Location actions (pickup, vendor, shop, collector) are distance-checked against the server's own coordinates for the player.
  • Amounts are checked for type, whole numbers, range and ownership. Only items in Cards.Info can be sold or traded.
  • Sell prices and trade contents come from server config / server memory.
  • Reward, sale and vendor/collector callbacks are rate limited per player (millisecond precision).
  • Collectors count and take cards from the player's inventory and the card boxes they carry (vendors follow Config.Shop.BoxesOnly). Sell All, Make Set and trades remove cards first and save each touched box once, and hand everything back if a step fails.
  • Player trading: the server owns the trade. Clients only send "offer N of X", "ready" and "cancel"; every offer is checked against what the player really carries (inventory and boxes), changing an offer clears both Ready flags so a card can't be swapped in after the other side confirmed, and the swap re-checks ownership, distance and inventory space before moving anything. Cards are removed from both players first and everything is handed back if a step fails. Requests are rate limited and expire.
  • Set bonus: paid at most once per character and set (database unique key), amounts come from Config.SetBonus and the set's deckPrice, never from the client.
  • Collector requests can only be completed once per player (Config.Trades.OncePerPlayer); completed requests are remembered in memory until the requests refresh. Without this a player could trade the same few cheap cards for a set worth up to $60 over and over.
  • World pickups have a per-character cooldown, set before the card is given.
  • CanAddItem is checked before items are given; a failed removal aborts and refunds a trade.
  • All SQL uses ? parameters. Box serials are validated (%w+) before being used in a stash id.
  • Sort & Stack: like Bundle Sets, the click carries no data from the client; it is rate limited (2 s), only acts on the player's own open box, and never deletes items (failures return them).
  • Bundle Sets: the click carries no data from the client. rsg-inventory only passes it on for a button registered on the stash the player has open; rsg-cards then checks it is that player's open box, rate limits it (2 s) and works out the sets from the box contents on the server.
  • /refreshcardtrades requires the admin permission.

What you must look after:

  • Anyone holding a storage box item can open that box. Giving away the item gives away its contents.
  • The card-only rule on boxes is enforced by rsg-cards after the move, not by rsg-inventory before it, so a rejected item is in the box for a fraction of a second before it is handed back.
  • Sell prices are in Config.Sets; check them against your economy before going live. Vendors buy without limit.

Database schema#

CREATE TABLE IF NOT EXISTS `rsg_cards_boxes` (
    `serial`  VARCHAR(20) NOT NULL,
    `creator` VARCHAR(50) NOT NULL,
    `owner`   VARCHAR(50) NOT NULL,
    PRIMARY KEY (`serial`),
    INDEX `idx_creator` (`creator`),
    INDEX `idx_owner` (`owner`)
);

CREATE TABLE IF NOT EXISTS `rsg_cards_collection` (
    `citizenid`   VARCHAR(50) NOT NULL,
    `card`        VARCHAR(50) NOT NULL,
    `obtained_at` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (`citizenid`, `card`)
);

CREATE TABLE IF NOT EXISTS `rsg_cards_points` (
    `id`         INT UNSIGNED NOT NULL AUTO_INCREMENT,
    `item`       VARCHAR(50) NOT NULL,
    `x`          DOUBLE NOT NULL,
    `y`          DOUBLE NOT NULL,
    `z`          DOUBLE NOT NULL,
    `heading`    DOUBLE NOT NULL DEFAULT 0,
    `exact`      TINYINT(1) NOT NULL DEFAULT 0,
    `created_by` VARCHAR(50) NOT NULL DEFAULT 'config',
    PRIMARY KEY (`id`),
    INDEX `idx_item` (`item`)
);

CREATE TABLE IF NOT EXISTS `rsg_cards_pickups` (
    `citizenid` VARCHAR(50) NOT NULL,
    `card`      VARCHAR(50) NOT NULL,
    `picked_at` INT UNSIGNED NOT NULL,
    PRIMARY KEY (`citizenid`, `card`)
);

CREATE TABLE IF NOT EXISTS `rsg_cards_bonuses` (
    `id`           INT UNSIGNED NOT NULL AUTO_INCREMENT,
    `citizenid`    VARCHAR(50) NOT NULL,
    `set_id`       VARCHAR(20) NOT NULL,
    `completed_at` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (`id`),
    UNIQUE KEY `uniq_set` (`citizenid`, `set_id`),
    INDEX `idx_set` (`set_id`)
);

CREATE TABLE IF NOT EXISTS `rsg_cards_profiles` (
    `citizenid` VARCHAR(50) NOT NULL,
    `name`      VARCHAR(100) NOT NULL,
    PRIMARY KEY (`citizenid`)
);

CREATE TABLE IF NOT EXISTS `rsg_cards_unclaimed` (
    `id`         INT UNSIGNED NOT NULL AUTO_INCREMENT,
    `citizenid`  VARCHAR(50) NOT NULL,
    `card`       VARCHAR(50) NOT NULL,
    `created_at` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (`id`),
    INDEX `idx_citizenid` (`citizenid`)
);

With Config.AutoDatabase = true these are created on start, and a legacy hdrp_boxes table is renamed to rsg_cards_boxes. A table that came from hdrp_boxes also has an unused position column; it is harmless.

Server owner how-tos#

Change what cards sell for – edit cardPrice / deckPrice in Config.Sets.

Change pack odds – edit the weights in Config.Pack.Chances. They are relative whole numbers; the defaults add up to 1000, so 5 means 0.5%.

Let boxes hold other items – add the item's category to Config.Storage.AllowedCategories.

Turn off set making at vendors – Config.Shop.CraftSets = false.

Let vendors use loose cards too – Config.Shop.BoxesOnly = false (default true: vendors only look in the player's card boxes).

Turn off the Bundle Sets button on boxes – Config.Storage.BundleSets = false.

Change or turn off the set bonus – Config.SetBonus.Enabled = false, or change Multiplier (money = the set's deckPrice x this) and Items (extra rewards).

Turn off player trading – Config.PlayerTrade.Enabled = false. Allow offering every copy instead of only spares with DuplicatesOnly = false. Stop received cards counting for the collection and set bonus with CountAsFound = false (recommended if you worry about alt accounts farming set bonuses).

Hide the Sell Duplicates button – Config.Shop.SellDuplicates = false.

Reset the leaderboard or titles – DELETE FROM rsg_cards_bonuses WHERE set_id = '...' removes a set's completions and first-collector title; DELETE FROM rsg_cards_collection resets what everyone has found.

Turn off the Sort & Stack button – Config.Storage.SortButton = false. Sort every time a box opens – Config.Storage.SortOnOpen = true.

Move or add a vendor / collector – add an entry to Config.Shop.Locations or Config.Trades.Locations with a unique id, coords, npcmodel and npccoords.

Move or add a world card – in game as an admin: /cardplace grl_c1 (opens the gizmo, confirm to save), or stand next to a card and use /cardmove / /cardremove (use /cardedit first if the card is on cooldown for you). /cardmissing lists cards without a location (card_cigcard_grl_c1 has none in the shipped data). Edits are saved in rsg_cards_points and sent to all players immediately. To start over from the config, empty the table and restart the resource (TRUNCATE rsg_cards_points).

Make world cards one-time only – set Config.Card.Cooldown to a very large number of minutes.

Add cards from a script – read CardsServer.points inside this resource, or SELECT * FROM rsg_cards_points from another one; other resources should not write the table directly (use the commands, so every client is updated).

Reset a character's cooldowns or collection – DELETE FROM rsg_cards_pickups WHERE citizenid = '...' / DELETE FROM rsg_cards_collection WHERE citizenid = '...', then have the player relog.

Use prompts instead of targeting – Config.EnableTarget = false. Keys are Config.Card.Key, Config.Shop.Key, Config.Trades.Key.

Turn off voice passthrough – Config.AllowPushToTalkWhileOpen = false.

Allow repeat trades with collectors – Config.Trades.OncePerPlayer = false (check your set prices first).

Turn off the update check – Config.VersionCheck = false.

Vendor and card boxes#

Vendors (server/vendor.lua) work on everything the player carries: the inventory and every card storage box in it (stash box_<serial>).

  • CardsServer.countCards(src, scope) returns { [itemName] = amount }. scope is nil (inventory only), true (inventory + boxes) or 'boxes' (boxes only). Vendors use 'boxes' when Config.Shop.BoxesOnly = true, otherwise true; collectors and player trades use true.
  • CardsServer.getBoxIds(src) returns the stash ids of the boxes the player carries (only boxes that have been registered, i.e. have a serial).
  • CardsServer.removeCards(src, name, amount, reason, scope, touched) removes from the inventory first, then from the boxes (scope = 'boxes' skips the inventory). It is all-or-nothing: if any step fails the cards already taken are handed back. Box stashes that were changed are saved, or collected in the optional touched table so the caller can save them once with CardsServer.saveStashes(touched).
  • Make Set removes cards 1-12 (from inventory/boxes) and gives one complete-set item to the inventory. Sell and Sell All pay cardPrice per card and deckPrice per set from Config.Sets.

Troubleshooting#

SymptomCause / fix
Console: N item(s) missing from rsg-core shared itemsAdd installation/shared_items.lua to rsg-core and restart
Using a pack does nothingThe item must be named card_package_cards and be useable = true
Using a card does nothingSingle cards need useable = true in rsg-core items (older installs had false)
Card faces are blank in the UIArtwork is html/img/<item name>.png; the resource folder must be named rsg-cards
Item thumbnails missing in vendor / collector UICopy installation/images to rsg-inventory, or fix Config.ImagePath
No soundinteract-sound must be running and have the dealfour and flip sounds, or set Config.Sounds.enabled = false
No world cards appearThey only spawn after the character has loaded, within Config.DistanceSpawn, and not while on cooldown
Console: database setup failedCheck oxmysql, or set Config.AutoDatabase = false and import install.sql
No Bundle Sets button on the boxUpdate rsg-inventory to 3.2.0 or newer and check Config.Storage.BundleSets = true
Bundle Sets says there are no complete setsAll 12 cards of a set must be inside the box (cards in the satchel don't count)
Items jump back out of a storage boxOnly cards, sets, packs and Config.Storage.AllowedCategories are allowed
The inventory flickers when the box is usedSet the box item to shouldClose = false in rsg-core items
Using a storage box closes the inventory and nothing opensThe box opens Config.Storage.OpenDelay ms after use, once rsg-inventory has closed the inventory. Raise the delay if the box flashes open and shut
Old boxes are empty after upgradingThe box table must be rsg_cards_boxes (auto-renamed from hdrp_boxes); stash ids are unchanged (box_<serial>)
No Discord logsAdd a rsg-cards webhook to rsg-log
Vendor says it only buys cards from a card boxConfig.Shop.BoxesOnly = true (default): put cards in a card box and carry the box. Set it to false to also buy loose cards from the inventory
Collector request shows CompletedThe player already did it; new requests arrive every Config.Trades.Refresh minutes or with /refreshcardtrades
Vendor has nothing to buyStock is amount in Config.Shop.Items; with persistent stock it only refills when rsg-inventory restocks

Support the Project : https://rexshack.tebex.store/

<!-- BEGIN AUTO-REFERENCE (generated from the code; re-run the generator instead of editing by hand) -->

Technical reference#

Generated from the source of rsg-cards 3.2.0. Names, arguments and defaults below are read straight from the code.

Dependencies#

rsg-core, rsg-inventory, oxmysql, rsg-target, rsg-gizmo

Database#

Tables: rsg_cards_boxes, rsg_cards_collection, rsg_cards_bonuses, rsg_cards_profiles, rsg_cards_unclaimed, rsg_cards_pickups, rsg_cards_points.

Tables are created automatically on start while Config.AutoDatabase = true (default). Nothing is ever dropped or overwritten. For a manual install set Config.AutoDatabase = false and import install.sql once.

-- shared/config.lua
Config.AutoDatabase = true -- false = import the SQL file yourself

Configuration#

OptionDefaultNotes
Config.CardPointstablecoords = vector4(x, y, z, heading)
Config.Debugfalse
Config.VersionChecktruePrints a console message on start when a newer version is available on GitHub.
Config.AutoDatabasetrueSet to false to import install.sql manually instead.
Config.AllowPushToTalkWhileOpentrueWhile the NUI is open, block game controls but allow push-to-talk.
Config.PushToTalkControlstable
Config.CloseDistance6.0The vendor / collector window closes by itself when the player walks further than this from where it was opene
Config.ImagePath'nui://rsg-inventory/html/images/'Inventory image folder used for item thumbnails in the UI
Config.ItemstableItem names (must exist in rsg-core shared items, see installation/shared_items.lua)
Config.Pack'card_package_cards'
Config.Box'card_storage_box'
Config.EnableTargettruetrue = rsg-target, false = rsg-core prompts
Config.FadeIntruefade NPCs and card props in/out
Config.DistanceSpawn20.0distance at which NPCs and card props spawn
Config.Bliptable
Config.ShopSprite'blip_rc'
Config.ShopScale0.2
Config.CollectSprite'blip_ambient_secret'
Config.CollectScale0.2
Config.CardsPerSet12
Config.Setstable
Config.Cards4
Config.OpenTime3000
Config.ChancestableWeights must be whole numbers; these add up to 1000.
Config.Cardtable
Config.Key'J'
Config.PickupTime3000
Config.PickupDistance3.0
Config.Cooldown360
Config.InspectTime15000
Config.EagleEyetableEagle Eye: cards glow and a heartbeat plays when one is close
Config.StoragetableUse the box to open it beside your inventory; use it again to close just the box.
Config.MaxWeight500
Config.MaxSlots156
Config.OpenDelay300
Config.BundleSetstrueinside the box into the complete-set item (needs rsg-inventory 3.2.0 or newer).
Config.SortButtontrueand puts the box in order: complete sets, then single cards by set and number, then packs.
Config.SortOnOpenfalse
Config.AllowedCategories{ 'card', 'cardset', 'cardpack' }Anything else put in a box is handed straight back to the player.
Config.SoundstableSounds (interact-sound). Skipped automatically if interact-sound isn't running.
Config.Shoptable
Config.Payment'cash'
Config.InteractDistance5.0
Config.PersistStocktrue
Config.CraftSetstrue
Config.SellDuplicatestrue
Config.BoxesOnlytrue
Config.Locationstable
Config.Tradestable
Config.Refresh90
Config.MaxActive3
Config.MinCards3
Config.MaxCards8
Config.RewardAmount1
Config.OncePerPlayertrue
Config.Collectiontable
Config.Command'cardcollection'
Config.LeaderboardSize10
Config.CacheSeconds60
Config.AnnounceFirsttrue
Config.SetBonustableReward the first time a character has found all cards of a set.
Config.Enabledtrue
Config.Multiplier2.0
Config.PlayerTradetable
Config.Distance5.0
Config.InviteSeconds30
Config.MaxPerSide30
Config.DuplicatesOnlytrue
Config.CountAsFoundtrue
Config.EditortableLocations are stored in the database (rsg_cards_points). shared/cards_points.lua is only used to fill an empty
Config.Permission'admin'
Config.SeedFromConfigtrue
Config.Webhooktable
Config.Name'rsg-cards'
Config.Title'CARDS'
Config.Colour'default'

Callbacks#

CallbackSideArgumentsFile
rsg-cards:server:getCollectionserversource, cbserver/collection.lua
rsg-cards:server:getPointsserversource, cbserver/points.lua
rsg-cards:server:flipCardserversource, cb, indexserver/server.lua
rsg-cards:server:getPickupsserversource, cbserver/server.lua
rsg-cards:server:pickupCardserversource, cb, indexserver/server.lua
rsg-cards:server:getTradesserversource, cb, locationIdserver/trades.lua
rsg-cards:server:tradeserversource, cb, locationId, offerIdserver/trades.lua
rsg-cards:server:getVendorserversource, cb, shopIdserver/vendor.lua
rsg-cards:server:sellserversource, cb, shopId, name, amountserver/vendor.lua
rsg-cards:server:sellAllserversource, cb, shopIdserver/vendor.lua
rsg-cards:server:sellDuplicatesserversource, cb, shopIdserver/vendor.lua
rsg-cards:server:makeSetserversource, cb, shopId, setIdserver/vendor.lua
-- client side
RSGCore.Functions.TriggerCallback('rsg-cards:server:getCollection', function(result)
    -- use result
end)

Events#

Server events can be fired by any client, so every handler re-validates the player, the arguments and any permission, distance or cooldown on the server. Never add a reward to a handler without those checks.

EventSideArgumentsFile
rsg-cards:client:openPackclientamountclient/client.lua
rsg-cards:client:openCollectionclient``client/client.lua
rsg-cards:client:tradeInviteclientnameclient/client.lua
rsg-cards:client:tradeStateclientstateclient/client.lua
rsg-cards:client:tradeClosedclientreasonclient/client.lua
rsg-cards:client:boxOpenedclient``client/client.lua
rsg-cards:client:inspectCardclientcardclient/client.lua
RSGCore:Client:OnPlayerLoadedclient``client/client.lua
RSGCore:Client:OnPlayerUnloadclient``client/client.lua
rsg-cards:client:setPointclientid, dataclient/world.lua
rsg-cards:client:editorToggleclient``client/world.lua
rsg-cards:client:editorPlaceclientitemclient/world.lua
rsg-cards:client:editorMoveclient``client/world.lua
rsg-cards:client:editorRemoveclient``client/world.lua
rsg-cards:server:pointAddserveritem, x, y, z, headingserver/points.lua
rsg-cards:server:pointMoveserverid, x, y, z, headingserver/points.lua
rsg-cards:server:pointRemoveserveridserver/points.lua
rsg-cards:server:ptradeRequestservertargetIdserver/ptrade.lua
rsg-cards:server:ptradeRespondserveracceptserver/ptrade.lua
rsg-cards:server:ptradeOfferservername, amountserver/ptrade.lua
rsg-cards:server:ptradeReadyserverreadyserver/ptrade.lua
rsg-cards:server:ptradeCancelserver``server/ptrade.lua
rsg-cards:server:claimUnclaimedserver``server/server.lua
rsg-cards:server:closePackserver``server/server.lua
rsg-inventory:server:moveserverdataserver/server.lua
rsg-cards:server:boxClosedserver``server/server.lua
rsg-cards:server:openShopservershopIdserver/vendor.lua
-- from a client script
TriggerServerEvent('rsg-cards:server:pointAdd', item, x, y, z, heading)
-- from a server script
TriggerClientEvent('rsg-cards:client:openPack', source, amount)

Commands#

CommandNotesFile
/cardplacelocale('command_cardplace')server/points.lua
/cardmovelocale('command_cardmove')server/points.lua
/cardremovelocale('command_cardremove')server/points.lua
/cardeditlocale('command_cardedit')server/points.lua
/cardmissinglocale('command_cardmissing')server/points.lua
/refreshcardtradeslocale('command_refresh')server/trades.lua

Locales#

Language files in locales/: de, el, en, es, fr, ja, nl, pl, pt-br, ro, ru. Set the language with setr rsg:locale "en".

<!-- END AUTO-REFERENCE -->