Bucky Reserve

#Overview

Bucky Reserve is a central bank and economy manager for QBCore servers. It moves your economy off uncontrolled money printing and onto a closed loop that runs through one Central Reserve:

• Government payroll is paid out of the Reserve instead of being created by qb-core.
• Loans are paid out of the Reserve and priced by each player's credit score.
• Taxes, repayments and fees flow back into the Reserve.
• The Mint register records every dollar staff create or destroy with a command.
• The city's money supply, inflation and vault backing are public on the Economy page.

Bucky Fuel is included with Bucky Reserve. With both running, the Marketplace lists all 26 fuel stations, and station sales, upgrades and taxes are paid into the Reserve.

#Requirements

Works on FiveM and FiveM Enhanced. No qb-core files are edited.

#Installation

#1. Place the resources

Put both resources in your resources folder, for example:

resources/
└── [bucky-scripts]/
    ├── bucky-reserve/
    └── bucky-fuel/

#2. Database

Bucky Reserve creates and migrates all of its tables on first start and seeds the Reserve with Config.StartingReserve. No manual import is needed.

Its tables are rbi_account, rbi_loans, rbi_loan_transactions, rbi_credit_scores, rbi_credit_logs, rbi_tax_logs, rbi_wealth_tax_consent, rbi_economy_snapshots and rbi_mint_log. If you'd rather create the schema yourself, rbi.sql and rbi_tax_logs.sql are included and safe to re-run (they never drop data).

For Bucky Fuel, import bucky-fuel/sql/install.sql.

#3. server.cfg

oxmysql, qb-core and qb-target must start first:

ensure oxmysql
ensure qb-core
ensure qb-target

ensure bucky-reserve
ensure bucky-fuel

#4. Secrets

Set a staff login code before going live (see Secrets). The staff login stays locked until a code of 6 or more characters is set.

#Central Reserve

Every loan is drawn from the Reserve balance. The balance check and the deduction happen in one database statement, so two loans approved at the same moment can never overdraw it.

Repayments, interest, municipal fees and wealth tax are deposited back. Staff watch inflows, outflows and the balance on the tablet, and admins adjust it with /rbiadd and /rbiremove.

Starting balance: Config.StartingReserve is only used once, on first start. After that, change the balance with /rbiadd and /rbiremove.

#Government payroll

Stock QBCore creates every paycheck from nothing. Bucky Reserve patches QBCore.Shared.Jobs in memory only at startup: the configured public-sector salaries are set to zero for qb-core's own timer, and the real salaries are paid from the Reserve on Bucky Reserve's schedule.

• Only players on duty are paid.
• Payroll always pays in full, even if the Reserve goes negative. Top it up with /rbiadd.
• If the Reserve is at or below Config.GovernmentPayroll.AlertThreshold after a run, online bank staff get an in-game alert (and a Discord alert when a webhook is set).
• /payrollnow runs one cycle on demand.

Config.GovernmentPayroll = {
    Enabled = true,
    Interval = 10 * 60 * 1000,  -- ms between payroll runs (10 minutes)
    Jobs = { 'police', 'ambulance' },
    AlertThreshold = 0,         -- alert staff when the Reserve is at or below this after payroll
}

Job names must match qb-core/shared/jobs.lua exactly. The console warns about unknown jobs at startup.

#Credit and loans

Every citizen has a persistent credit score from 300 to 850. It moves with how they borrow:

Each tier sets the weekly interest rate and the loan limit (Config.CreditTiers):

At 850, each fully repaid loan adds a permanent +5 % limit bonus (Config.RevisionBonus), up to +50 % and never above Config.MaxLoanLimitAfterRevision.

• Billing cycles: players choose 3-day or weekly billing. Each cycle charges the tier rate scaled to its length (3-day billing is 3/7 of the weekly rate). The loan calculator uses the same rates, so the quote matches the charge.
• Daily limit: Config.DailyLoanLimit (default 3) auto-approved loans per player per 24 hours. /rbinolimit exempts a player.
• Custom loans are staff-approved, need a stated reason, are billed weekly and accrue 1.5 % compound interest daily at midnight.

#Wealth tax

A recurring, progressive tax on the very rich that pulls excess money back into the Reserve.

1. When a player's total wealth (bank plus savings, crypto excluded) reaches the lowest bracket, they get a one-time consent notice.
2. After consenting, tax is collected every Config.WealthTax.CheckInterval, online or offline.
3. It never takes a balance below zero. Every collection is written to the ledger and can post a Discord receipt.

The brackets are set in Config.WealthTax.Brackets, and receipt labels are generated from them. Set Config.WealthTax.Enabled = false to turn off both the notices and the collection.

#Mint register

Every time staff create or destroy money with an admin command, it is written to the rbi_mint_log table. Bank staff see it on the Mint register tab, with a 14-day chart, an issuer leaderboard and a banknote-style record for each entry.

It works by matching qb-core's QBCore:Server:PreCommandExecution (who ran it) with QBCore:Server:OnMoneyChange (what changed). Both are server-only events that clients can't trigger, and no qb-core edits are needed.

Other admin menus can mark the issuer right before they change money:

exports['bucky-reserve']:MarkIssuer(adminSrc, targetSrc, 'bank', 'note')

Changes whose reason contains a word from Config.MintAudit.FlagReasons are logged as "Unattributed".

#Economy and marketplace

The Economy page is public. Every citizen can see:

• the money supply (live: online players from memory, offline players from the database)
• inflation, from hourly snapshots
• vault backing: the Reserve divided by the money held by citizens (0.23× means $23 behind every $100)
• tax sources, top taxpayers, the loan book and fuel economy

The Marketplace lists all 26 Bucky Fuel stations, each with a valuation, estimated daily volume and revenue, weekly municipal tax, upgrade levels, a GPS waypoint button and one-click financing that pre-fills a loan application with the station's value.

If you change a station's price in bucky-fuel/config.lua, update the same station in Bucky Reserve's Config.FuelIntegration.Stations so the Marketplace shows the same figure.

#Configuration

Everything is in config.lua, and every option is commented in the file. config.lua stays editable in the escrowed release.

#Secrets

server/config_secrets.lua is a server-only file: players can't download it.

-- Staff login code for the dashboard (at least 6 characters).
-- It ships blank, and the staff login stays locked until you set one.
Config.LoginCode = ""

-- Discord webhook for wealth tax receipts and Reserve alerts (blank = off)
Config.WealthTax.DiscordWebhook = ""

Or keep them out of the resource folder entirely. Lines in server.cfg win over the file:

set bucky_reserve_login_code "your-code"
set bucky_reserve_tax_webhook "https://discord.com/api/webhooks/..."
set bucky_reserve_mint_webhook "https://discord.com/api/webhooks/..."

Use set, not setr or sets. Those two send the value to every player.

#Commands

The dashboard opens by targeting the teller NPC at Config.TargetLocation. All commands below need QBCore's admin permission.

On the tablet, bank staff approve or deny loan requests, send reminders, seize or forgive loans, track players, send tax notices and view the Economy, Accounts and Payroll tabs. Deleting ledger entries needs the Chairman grade or admin. Resetting the economy graph needs admin.

Keys: Esc goes from a station dossier back to the grid, or closes the tablet.

#Exports

Other resources move Reserve money only through these server exports, so every movement is written to the ledger (rbi_tax_logs). Amounts are whole dollars.

-- Example: a business pays a licence fee into the Reserve
local ok, err = exports['bucky-reserve']:DepositToReserve(2500, 'Business licence', citizenid, name)
if not ok then print('Reserve deposit failed: ' .. tostring(err)) end

A job registered with RegisterPayrollJob keeps its qb-core payments at 0 and gets them back if Bucky Reserve stops. Don't also list it in Config.GovernmentPayroll.Jobs.

#Tuning your economy

#Realistic, low-money servers

• Set Config.StartingReserve = 10000000 ($10M) before the first start.
• Scale Config.CreditTiers loan limits to $20,000 (Poor) through $500,000 (Excellent).
• Set the first wealth tax bracket's minBalance to 500000. The notice threshold follows it.
• In Bucky Fuel, set station prices to $75,000–$750,000 and mirror them in Config.FuelIntegration.Stations.

#High-money servers

• Set Config.StartingReserve = 5000000000 ($5B).
• Scale loan limits to $10M–$50M and raise Config.MaxLoanLimitAfterRevision.
• Keep the wealth tax aggressive (15–30 % above $250M) to absorb excess money.

#Performance

• The tablet uses no blur filters and animates only transform and opacity. Charts are hand-built SVG, with no chart library.
• Tabs are created when opened and removed when you leave them, and the whole interface is removed when the tablet closes.
• Economy statistics are cached for 30 seconds and shared by every viewer. Loan and Reserve changes clear the cache straight away.
• The 26 station photos are WebP, about 4 MB in total.

#Troubleshooting

Government employees aren't being paid. Check the job names in Config.GovernmentPayroll.Jobs match qb-core/shared/jobs.lua exactly (the console warns at startup) and that the players are on duty.

The staff login doesn't work. Set a code of at least 6 characters in config_secrets.lua or with set bucky_reserve_login_code. It ships blank and stays locked until you do.

Discord receipts don't post. Check the webhook URL and look for HTTP 400/404 errors in the server console. Config.WealthTax.LogoURL must be a permanent public image. Discord attachment links expire.

Station photos are black. Make sure the images exist in html/img/stations/ as named in Config.FuelIntegration.Stations. Only .webp files in that folder are sent to players.

"Illegal mix of collations" SQL errors. This happens on MariaDB 10.10+ and MySQL 8 when the players table uses a different collation from the database default. On start, Bucky Reserve converts any of its own tables that don't match players.citizenid, so starting the resource fixes it.

Admin commands stop working after restart bucky-reserve. Do one full server restart after updating. The commands are registered by the resource itself, so later restarts are fine.