Exports

Exports & API

The Cue Coin System provides a comprehensive API through exports and events, allowing seamless integration with your other resources.

Server Exports

GetPlayerCoins

Returns the player's current coin balance.

local coins = exports['coinsystem_esx']:GetPlayerCoins(source)

Parameters:

• source - Player server ID

Returns:

• number - Player's coin balance

Example:

RegisterServerEvent('myshop:checkBalance')
AddEventHandler('myshop:checkBalance', function()
    local source = source
    local balance = exports['coinsystem_esx']:GetPlayerCoins(source)
    TriggerClientEvent('chat:addMessage', source, {args = {"Balance", "You have " .. balance .. " coins"}})
end)

AddPlayerCoins

Adds coins to a player's account.

exports['coinsystem_esx']:AddPlayerCoins(source, amount, reason)

Parameters:

• source - Player server ID

• amount - Number of coins to add

• reason - String describing the reason (for logging)

Example:

RegisterServerEvent('myjob:taskCompleted')
AddEventHandler('myjob:taskCompleted', function()
    local source = source
    exports['coinsystem_esx']:AddPlayerCoins(source, 50, "Job task completed")
    TriggerClientEvent('chat:addMessage', source, {args = {"Job", "You earned 50 coins!"}})
end)

RemovePlayerCoins

Removes coins from a player's account.

exports['coinsystem_esx']:RemovePlayerCoins(source, amount, reason)

Parameters:

• source - Player server ID

• amount - Number of coins to remove

• reason - String describing the reason (for logging)

Example:

RegisterServerEvent('myshop:buySpecialItem')
AddEventHandler('myshop:buySpecialItem', function()
    local source = source
    local price = 100
    local playerCoins = exports['coinsystem_esx']:GetPlayerCoins(source)
    
    if playerCoins >= price then
        exports['coinsystem_esx']:RemovePlayerCoins(source, price, "Special item purchase")
        -- Give the item to player here
        TriggerClientEvent('chat:addMessage', source, {args = {"Shop", "Item purchased!"}})
    else
        TriggerClientEvent('chat:addMessage', source, {args = {"Shop", "Not enough coins!"}})
    end
end)

GetPlayerVIP

Returns player's VIP status and remaining days.

local vipData = exports['coinsystem_esx']:GetPlayerVIP(source)

Parameters:

• source - Player server ID

Returns:

• table - VIP data object with properties:

  • isVip - Boolean indicating VIP status

  • daysRemaining - Number of VIP days left

  • expireDate - VIP expiration date

Example:

RegisterServerEvent('myresource:useVIPFeature')
AddEventHandler('myresource:useVIPFeature', function()
    local source = source
    local vipData = exports['coinsystem_esx']:GetPlayerVIP(source)
    
    if vipData and vipData.isVip and vipData.daysRemaining > 0 then
        TriggerClientEvent('myresource:enableVIPFeature', source)
        TriggerClientEvent('chat:addMessage', source, {args = {"VIP", "VIP feature activated! " .. vipData.daysRemaining .. " days remaining."}})
    else
        TriggerClientEvent('chat:addMessage', source, {args = {"VIP", "This feature requires active VIP membership!"}})
    end
end)

SetPlayerVIP

Sets a player's VIP status for a specified number of days.

exports['coinsystem_esx']:SetPlayerVIP(source, days)

Parameters:

• source - Player server ID

• days - Number of VIP days to grant

Example:

RegisterCommand('givevip', function(source, args)
    if source == 0 then -- Console command
        local targetId = tonumber(args[1])
        local days = tonumber(args[2]) or 30
        
        if targetId then
            exports['coinsystem_esx']:SetPlayerVIP(targetId, days)
            print("Granted " .. days .. " VIP days to player " .. targetId)
        end
    end
end, true)

LogTransaction

Manually logs a transaction to the database.

exports['coinsystem_esx']:LogTransaction(identifier, action, itemName, amount, oldBalance, newBalance)

Parameters:

• identifier - Player identifier

• action - Action type (e.g., "purchase", "reward", "admin_give")

• itemName - Item involved (can be nil)

• amount - Coin amount

• oldBalance - Balance before transaction

• newBalance - Balance after transaction

Example:

RegisterServerEvent('customshop:logPurchase')
AddEventHandler('customshop:logPurchase', function(itemName, price)
    local source = source
    local xPlayer = ESX.GetPlayerFromId(source)
    local oldBalance = exports['coinsystem_esx']:GetPlayerCoins(source)
    
    exports['coinsystem_esx']:RemovePlayerCoins(source, price, "Custom shop purchase")
    local newBalance = exports['coinsystem_esx']:GetPlayerCoins(source)
    
    exports['coinsystem_esx']:LogTransaction(xPlayer.identifier, "custom_purchase", itemName, price, oldBalance, newBalance)
end)

Client Exports

OpenShop

Opens the coin shop UI for the player.

exports['coinsystem_esx']:OpenShop()

Example:

RegisterCommand('openshop', function()
    exports['coinsystem_esx']:OpenShop()
end)

-- Or with key mapping
RegisterKeyMapping('customshop', 'Open Coin Shop', 'keyboard', 'F11')
RegisterCommand('customshop', function()
    exports['coinsystem_esx']:OpenShop()
end)

CloseShop

Closes the coin shop UI.

exports['coinsystem_esx']:CloseShop()

Example:

-- Close shop when entering vehicle
AddEventHandler('gameEventTriggered', function(name, args)
    if name == 'CEventNetworkPlayerEnteredVehicle' then
        if exports['coinsystem_esx']:IsShopOpen() then
            exports['coinsystem_esx']:CloseShop()
        end
    end
end)

IsShopOpen

Returns whether the coin shop UI is currently open.

local isOpen = exports['coinsystem_esx']:IsShopOpen()

Returns:

• boolean - True if shop is open, false otherwise

Example:

RegisterCommand('dosomething', function()
    if not exports['coinsystem_esx']:IsShopOpen() then
        -- Do something only if shop is closed
        DoSomeAction()
    else
        exports['coinsystem_esx']:ShowNotification("Close the shop first!", "error")
    end
end)

Events

Server Events

Listening for Events

-- Listen for coin balance changes
RegisterNetEvent('coinsystem:playerCoinsChanged')
AddEventHandler('coinsystem:playerCoinsChanged', function(newBalance, oldBalance, reason)
    local source = source
    print("Player " .. source .. " coins changed from " .. oldBalance .. " to " .. newBalance .. ". Reason: " .. reason)
    
    -- Send notification to admins about large transactions
    if math.abs(newBalance - oldBalance) > 1000 then
        TriggerEvent('admin:logLargeTransaction', source, newBalance - oldBalance, reason)
    end
end)

-- Listen for VIP status changes
RegisterNetEvent('coinsystem:playerVIPChanged')
AddEventHandler('coinsystem:playerVIPChanged', function(isVip, daysRemaining)
    local source = source
    if isVip then
        TriggerClientEvent('chat:addMessage', source, {args = {"VIP", "VIP activated! " .. daysRemaining .. " days remaining."}})
    else
        TriggerClientEvent('chat:addMessage', source, {args = {"VIP", "VIP membership expired."}})
    end
end)

-- Listen for mission completions
RegisterNetEvent('coinsystem:missionCompleted')
AddEventHandler('coinsystem:missionCompleted', function(missionId, reward)
    local source = source
    print("Player " .. source .. " completed mission " .. missionId .. " for " .. reward .. " coins")
    
    -- Give bonus for completing certain missions
    if missionId == 'special_mission' then
        exports['coinsystem_esx']:AddPlayerCoins(source, 50, "Special mission bonus")
    end
end)

-- Listen for purchases
RegisterNetEvent('coinsystem:purchaseCompleted')
AddEventHandler('coinsystem:purchaseCompleted', function(itemType, itemName, price)
    local source = source
    print("Player " .. source .. " purchased " .. itemName .. " for " .. price .. " coins")
end)

Available Server Events

Event Name	Parameters	Description
coinsystem:playerCoinsChanged	newBalance, oldBalance, reason	Triggered when player's coin balance changes
coinsystem:playerVIPChanged	isVip, daysRemaining	Triggered when player's VIP status changes
coinsystem:missionCompleted	missionId, reward	Triggered when player completes a mission
coinsystem:purchaseCompleted	itemType, itemName, price	Triggered when player makes a purchase

Client Events

Available Client Events

Event Name	Parameters	Description
coinsystem:shopOpened	None	Triggered when shop UI opens
coinsystem:shopClosed	None	Triggered when shop UI closes
coinsystem:balanceUpdated	newBalance	Triggered when player's coin balance updates

-- Listen for shop events
RegisterNetEvent('coinsystem:shopOpened')
AddEventHandler('coinsystem:shopOpened', function()
    print("Coin shop opened")
end)

RegisterNetEvent('coinsystem:shopClosed') 
AddEventHandler('coinsystem:shopClosed', function()
    print("Coin shop closed")
end)

-- Listen for balance updates
RegisterNetEvent('coinsystem:balanceUpdated')
AddEventHandler('coinsystem:balanceUpdated', function(newBalance)
    print("New coin balance: " .. newBalance)
end)

Integration Examples

Job System Integration

-- ESX Job Integration
RegisterServerEvent('esx_jobs:jobCompleted')
AddEventHandler('esx_jobs:jobCompleted', function(jobName, payment)
    local source = source
    local xPlayer = ESX.GetPlayerFromId(source)
    
    -- Give normal job payment
    xPlayer.addMoney('cash', payment)
    
    -- Calculate coin bonus based on job
    local coinBonus = 0
    if jobName == 'trucker' then
        coinBonus = 25
        TriggerEvent('coinsystem:missionProgress', source, 'trucker_mission', 1)
    elseif jobName == 'taxi' then
        coinBonus = 15
        TriggerEvent('coinsystem:missionProgress', source, 'taxi_mission', 1)
    elseif jobName == 'delivery' then
        coinBonus = 20
        TriggerEvent('coinsystem:missionProgress', source, 'delivery_mission', 1)
    end
    
    if coinBonus > 0 then
        exports['coinsystem_esx']:AddPlayerCoins(source, coinBonus, jobName .. " job completed")
    end
end)

Shop System Integration

-- Custom shop with coin payment option
RegisterServerEvent('customshop:purchase')
AddEventHandler('customshop:purchase', function(itemId, paymentMethod)
    local source = source
    local itemData = GetItemData(itemId) -- Your function to get item data
    
    if paymentMethod == 'coins' then
        local playerCoins = exports['coinsystem_esx']:GetPlayerCoins(source)
        
        if playerCoins >= itemData.coinPrice then
            exports['coinsystem_esx']:RemovePlayerCoins(source, itemData.coinPrice, "Custom shop purchase")
            GiveItemToPlayer(source, itemData) -- Your function to give item
            TriggerClientEvent('customshop:purchaseSuccess', source, itemData.name)
        else
            TriggerClientEvent('customshop:purchaseFailed', source, "Insufficient coins")
        end
    else
        -- Handle cash payment
        local xPlayer = ESX.GetPlayerFromId(source)
        if xPlayer.getMoney() >= itemData.cashPrice then
            xPlayer.removeMoney(itemData.cashPrice)
            GiveItemToPlayer(source, itemData)
        end
    end
end)

Housing System Integration

-- Housing rent payment with coins
RegisterServerEvent('housing:payRentWithCoins')
AddEventHandler('housing:payRentWithCoins', function(houseId)
    local source = source
    local rentAmount = GetHouseRent(houseId) -- Your function
    local coinRentAmount = rentAmount / 10 -- 10:1 cash to coin ratio
    
    local playerCoins = exports['coinsystem_esx']:GetPlayerCoins(source)
    
    if playerCoins >= coinRentAmount then
        exports['coinsystem_esx']:RemovePlayerCoins(source, coinRentAmount, "House rent payment")
        SetHouseRentPaid(houseId) -- Your function
        TriggerClientEvent('housing:rentPaid', source)
    else
        TriggerClientEvent('housing:rentFailed', source, "Insufficient coins for rent")
    end
end)

Vehicle Shop Integration

-- Custom vehicle shop with coin discounts
RegisterServerEvent('vehicleshop:purchaseWithCoins')
AddEventHandler('vehicleshop:purchaseWithCoins', function(vehicleModel, useCoinsDiscount)
    local source = source
    local xPlayer = ESX.GetPlayerFromId(source)
    local vehiclePrice = GetVehiclePrice(vehicleModel) -- Your function
    
    if useCoinsDiscount then
        local coinCost = 100 -- Cost in coins for discount
        local playerCoins = exports['coinsystem_esx']:GetPlayerCoins(source)
        
        if playerCoins >= coinCost then
            exports['coinsystem_esx']:RemovePlayerCoins(source, coinCost, "Vehicle purchase discount")
            vehiclePrice = vehiclePrice * 0.9 -- 10% discount
        end
    end
    
    if xPlayer.getMoney() >= vehiclePrice then
        xPlayer.removeMoney(vehiclePrice)
        GiveVehicleToPlayer(source, vehicleModel) -- Your function
    end
end)

Casino/Gambling Integration

-- Casino betting with coins
RegisterServerEvent('casino:placeCoinBet')
AddEventHandler('casino:placeCoinBet', function(gameType, betAmount)
    local source = source
    local playerCoins = exports['coinsystem_esx']:GetPlayerCoins(source)
    
    if playerCoins >= betAmount then
        exports['coinsystem_esx']:RemovePlayerCoins(source, betAmount, "Casino bet - " .. gameType)
        
        -- Simple gambling logic (50% win chance)
        local winChance = math.random()
        
        if winChance > 0.5 then
            local winAmount = betAmount * 2
            exports['coinsystem_esx']:AddPlayerCoins(source, winAmount, "Casino win - " .. gameType)
            TriggerClientEvent('casino:win', source, winAmount)
        else
            TriggerClientEvent('casino:lose', source)
        end
    else
        TriggerClientEvent('casino:insufficientFunds', source)
    end
end)

VIP Benefits Integration

-- Job with VIP multiplier
RegisterServerEvent('job:completeTask')
AddEventHandler('job:completeTask', function(taskType, baseReward)
    local source = source
    local xPlayer = ESX.GetPlayerFromId(source)
    local vipData = exports['coinsystem_esx']:GetPlayerVIP(source)
    
    -- Give base cash reward
    xPlayer.addMoney('cash', baseReward)
    
    -- Calculate coin reward with VIP multiplier
    local coinReward = 25
    if vipData and vipData.isVip then
        coinReward = coinReward * 2 -- VIP gets double coins
        TriggerClientEvent('chat:addMessage', source, {args = {"VIP", "VIP Bonus: Double coin rewards!"}})
    end
    
    exports['coinsystem_esx']:AddPlayerCoins(source, coinReward, "Task completion")
end)

Admin Commands

-- Admin commands for coin management
RegisterCommand('givecoins', function(source, args)
    if source == 0 or IsPlayerAceAllowed(source, 'admin') then
        local targetId = tonumber(args[1])
        local amount = tonumber(args[2])
        local reason = table.concat(args, " ", 3) or "Admin grant"
        
        if targetId and amount then
            exports['coinsystem_esx']:AddPlayerCoins(targetId, amount, reason)
            print("Gave " .. amount .. " coins to player " .. targetId)
        end
    end
end, true)

RegisterCommand('removecoins', function(source, args)
    if source == 0 or IsPlayerAceAllowed(source, 'admin') then
        local targetId = tonumber(args[1])
        local amount = tonumber(args[2])
        local reason = table.concat(args, " ", 3) or "Admin removal"
        
        if targetId and amount then
            exports['coinsystem_esx']:RemovePlayerCoins(targetId, amount, reason)
            print("Removed " .. amount .. " coins from player " .. targetId)
        end
    end
end, true)

RegisterCommand('checkcoins', function(source, args)
    if source == 0 or IsPlayerAceAllowed(source, 'admin') then
        local targetId = tonumber(args[1])
        
        if targetId then
            local coins = exports['coinsystem_esx']:GetPlayerCoins(targetId)
            print("Player " .. targetId .. " has " .. coins .. " coins")
        end
    end
end, true)

Database Queries

Custom Database Operations

-- Get top coin holders
RegisterServerEvent('admin:getTopCoinHolders')
AddEventHandler('admin:getTopCoinHolders', function()
    local source = source
    
    if IsPlayerAceAllowed(source, 'admin') then
        local query = 'SELECT identifier, credits FROM users ORDER BY credits DESC LIMIT 10'
        MySQL.Async.fetchAll(query, {}, function(result)
            local topHolders = {}
            for i = 1, #result do
                table.insert(topHolders, {
                    identifier = result[i].identifier,
                    coins = result[i].credits
                })
            end
            TriggerClientEvent('admin:receiveTopCoinHolders', source, topHolders)
        end)
    end
end)

-- Get player transaction history
RegisterServerEvent('admin:getPlayerTransactions')
AddEventHandler('admin:getPlayerTransactions', function(targetId)
    local source = source
    
    if IsPlayerAceAllowed(source, 'admin') then
        local xTarget = ESX.GetPlayerFromId(targetId)
        if xTarget then
            local query = 'SELECT * FROM coinsystem_logs WHERE identifier = ? ORDER BY timestamp DESC LIMIT 20'
            MySQL.Async.fetchAll(query, {xTarget.identifier}, function(result)
                TriggerClientEvent('admin:receivePlayerTransactions', source, result)
            end)
        end
    end
end)

Integration Tips

• Always check coin balance before deducting coins

• Use meaningful reasons when logging transactions

• Consider VIP multipliers for enhanced user experience

• Test all integrations thoroughly before deploying

• Use events to create seamless integration between resources

Framework Compatibility

All exports work with both ESX and QBCore frameworks. The system automatically detects your framework and adapts accordingly.