Tipos de dinheiro em FiveM: cash, bank e black money em ESX, QBCore e QBox

Os jogadores têm mais de um tipo de dinheiro: o dinheiro no bolso, a conta bancária, e em muitos servidores um saldo de dinheiro sujo. Cada framework os nomeia e os manipula de forma diferente, e ox_inventory adiciona uma terceira maneira. Este artigo mostra os nomes das contas, as funções para adicionar e remover dinheiro, como ox_inventory trata cash, e por que a string de razão importa.

#Contas ESX

ESX tem três contas padrão:

No servidor, com o objeto do jogador:

ESX = exports['es_extended']:getSharedObject()
local xPlayer = ESX.GetPlayerFromId(source)

-- read
local cash = xPlayer.getAccount('money').money
local bank = xPlayer.getAccount('bank').money
local black = xPlayer.getAccount('black_money').money

-- add / remove
xPlayer.addAccountMoney('bank', 500, 'job-payout')
xPlayer.removeAccountMoney('black_money', 200, 'drug-purchase')

xPlayer.addAccountMoney(account, amount, reason) e removeAccountMoney pegam o nome da conta primeiro. Apenas para cash, existem atalhos:

xPlayer.addMoney(100, 'sold-item')
xPlayer.removeMoney(100, 'bought-item')
local cash = xPlayer.getMoney()

removeAccountMoney não verifica o saldo para você. Verifique primeiro, ou a conta pode ficar negativa em algumas versões:

if xPlayer.getAccount('money').money >= price then
    xPlayer.removeAccountMoney('money', price, 'shop')
end

Se o objeto do jogador for nil, veja ESX xPlayer is nil.

#Dinheiro QBCore

QBCore mantém seu dinheiro em PlayerData.money, com cash, bank e crypto:

local QBCore = exports['qb-core']:GetCoreObject()
local Player = QBCore.Functions.GetPlayer(source)

-- read
local cash = Player.PlayerData.money.cash
local bank = Player.PlayerData.money.bank

-- add / remove
Player.Functions.AddMoney('bank', 500, 'job-payout')
Player.Functions.RemoveMoney('cash', 50, 'shop-purchase')

Player.Functions.AddMoney(type, amount, reason) e Player.Functions.RemoveMoney(type, amount, reason) pegam o tipo primeiro. RemoveMoney retorna false quando o jogador não tem o suficiente, então use o resultado:

if Player.Functions.RemoveMoney('cash', price, 'shop-purchase') then
    Player.Functions.AddItem('burger', 1)
else
    TriggerClientEvent('QBCore:Notify', source, 'Not enough cash', 'error')
end

Não há conta de dinheiro preto integrada no QBCore. Servidores que precisam de uma geralmente usam um item (marked bills) ou um tipo customizado adicionado a Config.Money, e a próxima seção cobre a opção de item. Se QBCore for nil em seu script, veja the GetCoreObject fix.

#QBox

QBox é baseado em QBCore, então as mesmas chamadas Player.Functions.AddMoney e RemoveMoney funcionam no objeto do jogador, e os tipos de dinheiro são os mesmos. QBox também tem exports em qbx_core, então verifique os exports de sua versão qbx_core para as funções de dinheiro antes de usá-las em novo código. A forma é a mesma: um tipo, um valor e uma razão.

#ox_inventory: cash como um item

Com ox_inventory, o cash pode ser um item em vez de um número. O item padrão é chamado money, e dinheiro sujo é black_money. Ambos estão em ox_inventory/data/items.lua.

-- give cash as an item
exports.ox_inventory:AddItem(source, 'money', 500)

-- count it
local cash = exports.ox_inventory:Search(source, 'count', 'money')

-- take it
exports.ox_inventory:RemoveItem(source, 'money', 100)

-- dirty money
exports.ox_inventory:AddItem(source, 'black_money', 1000)

Em um servidor ESX com ox_inventory, as contas money e black_money são mostradas como itens no inventário, e xPlayer.addAccountMoney('money', ...) acaba nesses itens. Use apenas uma maneira. Se um script adiciona cash com a função ESX e outro com AddItem, teste se os dois concordam em sua configuração antes de lançar. O banco não é um item e permanece um número.

Atenção: cash como um item tem peso e pode ser derrubado, roubado ou armazenado em um estoque. Isso é intencional, mas muda como scripts de roubo e loja se comportam. Veja stashes in ox_inventory.

#A string de razão

reason é o último argumento das funções de dinheiro. Não muda o valor. É passado juntamente com a mudança para que o framework, ou um script de logging, possa registrar por que o dinheiro se moveu.

Player.Functions.AddMoney('cash', 250, 'taxi-job-payout')
xPlayer.addAccountMoney('bank', 250, 'taxi-job-payout')

Use um texto curto e consistente que nomeie o script e a ação. Quando o saldo de um jogador parece errado, uma pesquisa por taxi-job-payout nos logs encontra a linha em segundos. Se você também enviar logs para Discord, veja Discord webhook logs. Para o lado do saldo da economia, veja balancing a FiveM economy.

#Regras para código seguro de dinheiro

• Mude o dinheiro apenas no servidor. Nunca aceite um valor enviado pelo cliente.
• Verifique o saldo antes de remover, e use o valor de retorno em QBCore.
• Passe uma razão toda vez.
• Escolha uma fonte de dinheiro por conta, para que o cash não seja armazenado duas vezes, uma como número e outra como item.

#Lista de verificação