CU Containers

Container auction resource for FiveM with Qbox, QBCore, ESX, and standalone adapter support.

Players bid on placed containers, win a random vehicle from the configured prize pool, then claim the vehicle into their garage or sell the prize for money. Containers can use standard framework money accounts such as cash or bank, or any custom server currency you connect through editable integration hooks, for example coins, credits, tokens, points, or another economy resource.

Prize Pools

Edit shared/prizes.lua:

PrizePools = {
    low = {
        {
            model = 'comet2',
            labelKey = 'vehicles.comet2',
            chance = 30,
            rarity = 'purple',
            price = 250000
        }
    }
}

Prize fields:

• model: spawn name.
• labelKey: locale key shown in UI.
• chance: weighted chance inside the pool.
• rarity: UI color key: gray, blue, purple, pink, red, gold, or unique.
• price: payout if the player sells the prize.
• image: optional custom image path or URL.
• currencyType: optional custom currency key for prize values, such as premium, coins, credits, or another configured currency.

Vehicle labels are stored in locales/*.json under vehicles.

Premium And Custom Currency Containers

CU Containers supports both standard framework money accounts and custom server currencies.

By default, regular containers can use framework payment accounts such as cash or bank. You can also connect any custom currency instead of cash or bank, for example:

• premium coins
• credits
• tokens
• points
• VIP balance
• battle pass currency
• any custom economy resource

Use a container type configured for your custom currency, for example:

Config.Types.premium = {
    nameKey = 'container_types.premium',
    currencyType = 'premium',
    containerModel = 'prop_container_01mb',
    leftDoorModel = 'prop_cntrdoor_ld_l',
    rightDoorModel = 'prop_cntrdoor_ld_r',
    prizePool = 'premium'
}

Then set a container row to use that type:

type = 'premium'

Custom-currency bids use the payment methods configured in Config.Economy.paymentMethods. For example:

Config.Economy = {
    paymentMethods = {
        regular = { 'cash', 'bank' },
        premium = { 'premium' },
        credits = { 'credits' }
    }
}

You can replace premium, credits, or any other key with the currency name used by your own server economy.

Implement custom currency hooks in server/editable_integrations.lua:

function EditableIntegrations.hasCustomCurrency(source, currencyType, amount, context)
    return exports['my_currency_system']:GetBalance(source, currencyType) >= amount
end

function EditableIntegrations.removeCustomCurrency(source, currencyType, amount, context)
    return exports['my_currency_system']:RemoveBalance(
        source,
        currencyType,
        amount,
        context and context.reason or 'container_bid'
    )
end

function EditableIntegrations.addCustomCurrency(source, currencyType, amount, context)
    return exports['my_currency_system']:AddBalance(
        source,
        currencyType,
        amount,
        context and context.reason or 'container_refund'
    )
end

Alternatively, set Config.Integrations.customCurrency.resource and export names if another resource already exposes the expected functions.

This allows server owners to use their own economy system without being limited to cash or bank.

Server Exports

Use server exports from server-side code:

local containers = exports['cu_containers']:GetContainers()
local state = exports['cu_containers']:GetContainerState(1)
local ok, reason = exports['cu_containers']:StartAuction(1)

Available server exports:

• GetContainers(): returns all serialized container states.
• GetContainer(containerId): returns the internal server container table.
• GetContainerState(containerId): returns one serialized container state.
• GetSupportedLocales(): returns locale codes that loaded successfully.
• SetPlayerLocale(source, locale): sets a player's locale and refreshes their client.
• OpenContainerForPlayer(source, containerId): opens a container UI for a player.
• PlaceBid(source, containerId, amount, paymentType): places a bid. paymentType can be cash, bank, or any configured custom currency such as premium, credits, coins, or another server-specific currency.
• ClaimPrize(source, containerId): claims the current prize for the winner.
• SellPrize(source, containerId): sells the current prize for the winner.
• StartAuction(containerId): starts one container auction.
• StartAllAuctions(): starts all available container auctions.
• FinishAuction(containerId): force-finishes one active auction.
• ReloadConfig(): reloads runtime state after config changes.

Example:

local ok, reason = exports['cu_containers']:PlaceBid(source, 1, 2500000, 'bank')

Custom currency example:

local ok, reason = exports['cu_containers']:PlaceBid(source, 1, 1000, 'credits')

Compatibility exports are also available while Config.Compatibility.currencyExportShim = true:

• hasCustomCurrency(source, currencyType, amount, context)
• removeCustomCurrency(source, currencyType, amount, context)
• addCustomCurrency(source, currencyType, amount, context)