Developer Preview

Economy natives

Money with a paper trail: payments, transfers, bills and transaction history.

Developer Preview. Scripting is live on Neighborly servers – everything on these pages works today. The API is young, so tell us what you need next on Discord.

Money with a paper trail: payments, transfers, bills and transaction history. All amounts are whole simoleons.

Open in the natives browser Search all 199 natives at once.

GetBalance

Server
int GetBalance(Player player)

Returns how much money a player has.

The balance is the player's household funds, read from their game. Read it right before you decide – never trust a balance a client sends you.

Parameters

ParameterTypeDescription
playerPlayerServer id of the player.

Returns

int Funds of the player's household.

Example

RegisterNetEvent('rtx_shop:checkout', function(itemId)
    local src = source
    local item = Config.Items[itemId]
    if not item then
        return
    end
    if GetBalance(src) < item.price then
        return TriggerClientEvent('neighborly:notify', src, {
            text = ('You need %s more.'):format(FormatMoney(item.price - GetBalance(src))),
            type = 'warning'
        })
    end
    TakeMoney(src, item.price, 'Shop: ' .. item.label)
end)

GiveMoney

Server
boolean GiveMoney(Player player, int amount, string reason)

Gives a player money, logged in their transaction history.

Every call is written to the player's transaction history with your reason. Amounts are whole simoleons; decimals are rounded down.

Parameters

ParameterTypeDescription
playerPlayerServer id of the player.
amountintPositive amount.
reasonstringShown in the history.

Returns

boolean true on success.

Example

RegisterNetEvent('rtx_cafe:finishShift', function()
    local src = source
    local state = Player(src).state
    if not state.onDuty then
        return
    end
    local earned = math.min((state.servedThisShift or 0) * Config.PayPerDrink, Config.MaxShiftPay)
    state:set('onDuty', false, true)
    state:set('servedThisShift', 0, true)
    if earned > 0 then
        GiveMoney(src, earned, 'Café shift')
    end
end)

TakeMoney

Server
boolean TakeMoney(Player player, int amount, string reason)

Takes money if the player has enough.

Checks and takes in one step, so two events can't spend the same simoleons twice. Always use the return value instead of checking GetBalance first.

Parameters

ParameterTypeDescription
playerPlayerServer id of the player.
amountintPositive amount.
reasonstringShown in the history.

Returns

boolean false if they can't afford it.

Example

if not TakeMoney(source, 12, 'Latte') then
    TriggerClientEvent('neighborly:notify', source, { text = 'Not enough simoleons.', type = 'error' })
end

TransferMoney

Server
boolean TransferMoney(Player from, Player to, int amount, string reason)

Moves money between two players in one safe step.

Atomic: either both sides change or nothing happens. Both players get a history entry with your reason.

Parameters

ParameterTypeDescription
fromPlayerPayer.
toPlayerReceiver.
amountintAmount.
reasonstringShown to both.

Returns

boolean false if the payer can't afford it.

Example

RegisterNetEvent('rtx_cafe:tip', function(target, amount)
    local src = source
    if type(target) ~= 'number' or type(amount) ~= 'number' or target == src or not GetPlayerName(target) then
        return
    end
    amount = math.floor(amount)
    if amount < 1 or amount > 500 or GetPlayerLot(target) ~= GetPlayerLot(src) then
        return
    end
    if TransferMoney(src, target, amount, 'Tip') then
        TriggerClientEvent('rtx_cafe:tipReceived', target, amount)
    end
end)

CreateBill

Server
int CreateBill(Player player, table bill)

Creates a bill for a player. Bills are kept by the server; show them in your own UI (see the phone example) and pay them with PayBill. Fires billCreated with the bill on the server.

Bills survive restarts. A bill with a payee pays that player when it is paid.

Parameters

ParameterTypeDescription
playerPlayerServer id of the player.
billtable{ label, amount, dueDays, payee } – payee is an optional player who gets the money.

Returns

int Bill id.

Example

RegisterNetEvent('rtx_cafe:openTab', function(customer, amount)
    local src = source
    if not Player(src).state.onDuty or type(customer) ~= 'number' or not GetPlayerName(customer) then
        return
    end
    if type(amount) ~= 'number' or amount < 1 or amount > 500 then
        return
    end
    local billId = CreateBill(customer, { label = 'Bluejay Café tab', amount = math.floor(amount), dueDays = 2, payee = src })
    print(('Bill %d sent to %s'):format(billId, GetPlayerName(customer)))
end)

GetBills

Server
table GetBills(Player player)

Returns a player's open bills.

Only open bills. Paid and cancelled bills are gone from this list; payments show up in GetTransactions.

Parameters

ParameterTypeDescription
playerPlayerServer id of the player.

Returns

table List of { id, label, amount, due, payee, from }. due is a Unix time or nil, payee the payee's server id while they are online, from the resource that created it.

Example

for _, bill in ipairs(GetBills(source)) do
    print(bill.id, bill.label, bill.amount)
end

PayBill

Server
boolean PayBill(int billId)

Pays a bill from the debtor's funds and, if it has a payee, gives the money to them – if the payee is offline they get it the next time they play. Fires billPaid. The debtor must be connected.

Takes the money from the debtor and, if the bill has a payee, gives it to them – in one safe step.

Parameters

ParameterTypeDescription
billIdintBill id.

Returns

boolean false if not enough funds.

Example

RegisterNetEvent('rtx_phone:payBill', function(billId)
    local src = source
    for _, bill in ipairs(GetBills(src)) do
        if bill.id == billId then
            local ok = PayBill(billId)
            TriggerClientEvent('neighborly:notify', src, {
                text = ok and 'Bill paid.' or 'Not enough simoleons for this bill.',
                type = ok and 'success' or 'error'
            })
            return
        end
    end
end)

CancelBill

Server
boolean CancelBill(int billId)

Cancels an open bill.

Server only: the change happens on the server and Neighborly syncs it to every player who can see it. Validate anything that came from a client before you call it.

Parameters

ParameterTypeDescription
billIdintBill id.

Returns

boolean true if an open bill was cancelled.

Example

RegisterCommand('forgivebills', function(source, args)
    local target = tonumber(args[1])
    if not target or not GetPlayerName(target) then
        return print('Usage: forgivebills <player id>')
    end
    for _, bill in ipairs(GetBills(target)) do
        CancelBill(bill.id)
    end
    TriggerClientEvent('neighborly:notify', target, { text = 'Your bills were forgiven!', type = 'success' })
end, true)

GetTransactions

Server
table GetTransactions(Player player, int? limit)

Returns a player's transaction history.

Includes every change made through GiveMoney, TakeMoney, TransferMoney and PayBill, with your reason texts. The server keeps the last 250 entries per player.

Parameters

ParameterTypeDescription
playerPlayerServer id of the player.
limitint?How many, newest first. Default 20.

Returns

table List of { amount, reason, time }, newest first. Negative amounts are payments.

Example

for _, t in ipairs(GetTransactions(source, 5)) do
    print(os.date('%H:%M', t.time), t.amount, t.reason)
end

FormatMoney

Shared
string FormatMoney(int amount)

Formats an amount as simoleons.

Uses the simoleon sign and thousands separators: FormatMoney(1250) returns §1,250.

Parameters

ParameterTypeDescription
amountintAmount.

Returns

string Formatted like §1,250.

Example

RegisterCommand('wallet', function(source)
    TriggerClientEvent('neighborly:notify', source, {
        title = 'Wallet',
        text = 'You have ' .. FormatMoney(GetBalance(source)) .. '.',
        icon = 'money'
    })
end, false)