Tipos de dinero en FiveM: efectivo, banco y dinero sucio en ESX, QBCore y QBox

Los jugadores tienen más de un tipo de dinero: el efectivo en su bolsillo, la cuenta bancaria, y en muchos servidores un saldo de dinero sucio. Cada framework los nombra y maneja diferente, y ox_inventory añade una tercera forma. Este artículo muestra los nombres de cuentas, las funciones para añadir y remover dinero, cómo ox_inventory trata el efectivo, y por qué la cadena de razón importa.

#Cuentas ESX

ESX tiene tres cuentas estándar:

En el servidor, con el objeto del jugador:

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) y removeAccountMoney toman el nombre de cuenta primero. Solo para efectivo, hay atajos:

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

removeAccountMoney no comprueba el saldo por ti. Comprueba primero, o la cuenta puede volverse negativa en algunas versiones:

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

Si el objeto del jugador es nil, ver ESX xPlayer es nil.

#Dinero en QBCore

QBCore guarda su dinero en PlayerData.money, con cash, bank y 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) y Player.Functions.RemoveMoney(type, amount, reason) toman el tipo primero. RemoveMoney devuelve false cuando el jugador no tiene suficiente, así que usa el 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

No hay una cuenta de dinero sucio integrada en QBCore. Los servidores que necesitan una normalmente usan un objeto (billetes marcados) o un tipo personalizado añadido a Config.Money, y la siguiente sección cubre la opción de objeto. Si QBCore es nil en tu script, ver la solución GetCoreObject.

#QBox

QBox está basado en QBCore, así que las mismas llamadas Player.Functions.AddMoney y RemoveMoney funcionan en el objeto del jugador, y los tipos de dinero son los mismos. QBox también tiene exports en qbx_core, así que comprueba los exports de tu versión de qbx_core para las funciones de dinero antes de usarlas en código nuevo. La forma es la misma: un tipo, una cantidad y una razón.

#ox_inventory: efectivo como objeto

Con ox_inventory, el efectivo puede ser un objeto en lugar de un número. El objeto estándar se llama money, y el dinero sucio es black_money. Ambos están en 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)

En un servidor ESX con ox_inventory, las cuentas money y black_money se muestran como objetos en el inventario, y xPlayer.addAccountMoney('money', ...) termina en esos objetos. Usa solo una forma. Si un script añade efectivo con la función ESX y otro con AddItem, prueba que los dos estén de acuerdo en tu configuración antes de desplegarlo. El banco no es un objeto y se queda como número.

Cuidado: el efectivo como objeto tiene peso y puede ser soltado, robado o almacenado en un escondite. Esto es intencional, pero cambia cómo se comportan los scripts de robo y tienda. Ver escondites en ox_inventory.

#La cadena de razón

reason es el último argumento de las funciones de dinero. No cambia la cantidad. Se pasa junto con el cambio para que el framework, o un script de registro, pueda registrar por qué se movió el dinero.

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

Usa un texto corto y consistente que nombre el script y la acción. Cuando el saldo de un jugador se ve incorrecto, una búsqueda de taxi-job-payout en los registros encuentra la línea en segundos. Si también envías registros a Discord, ver registros de webhook de Discord. Para el lado del balance de la economía, ver equilibrando una economía FiveM.

#Reglas para código de dinero seguro

• Cambia dinero en el servidor solo. Nunca aceptes una cantidad enviada por el cliente.
• Comprueba el saldo antes de remover, y usa el valor de retorno en QBCore.
• Pasa una razón cada vez.
• Elige una fuente de dinero por cuenta, así el efectivo no se almacena dos veces, una como número y otra como objeto.

#Checklist