> For the complete documentation index, see [llms.txt](https://docs.cuxial.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cuxial.com/scripts/core/cuxial-banking/configuration.md). # Configuration Every option of Cuxial Banking explained: where settings live, the data files and shared/config.lua. The bank is configured in two places: the files of the resource, which hold the starting values, and the Config tab of `/bankadmin`, which edits most of them live. ## Where settings live `shared/config.lua` builds the configuration. It reads most values from the files in `data/` and keeps a few of its own. On the first start, the bank copies eleven sections into the database: general, accounts, cards, loans, savings, cheques, rewards, credit score, ATM, admin and logs. From then on the database copy is the one in use. {% hint style="info" %} After the first start, change those sections in `/bankadmin` → Config. To load the values of a file again, edit the file, restart the resource and press the reset button of that section in the panel. {% endhint %} | What you want to change | Where | | ------------------------------------------------------- | ----------------------------------------------------------- | | Anything in the eleven sections, before the first start | `data/*.lua` and `shared/config.lua` | | Anything in the eleven sections, afterwards | `/bankadmin` → Config | | `debug`, `ui`, `commands`, `world`, `wealth`, `limits` | `shared/config.lua`, then restart the resource | | `admin.permission` and `logs.convar` | `shared/config.lua` only; the panel shows them as read-only | | Branches and ATM points | `/bankadmin` → Points | The Config tab can export the changed sections to a text and import them on another server. ## General · `data/general.lua` | Option | Type | Default | What it does | | ------------------------ | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Currency` | string | `'USD'` | Currency code shown in the interface and in the logs. | | `UseCashAsItem` | boolean | `true` | `true` handles cash as an inventory item (`general.cashItem`). `false` uses the cash account of your framework. | | `LogExternalBankChanges` | boolean | `true` | `true` writes to the history every change another resource makes to a player's bank money. `false` records only the bank's own operations. Requires QBox or QBCore. | | `AdminMaxAdjust` | number | `100000000` | Largest amount staff can add or remove in one balance adjustment. | These options of the same section are set in `shared/config.lua`, under `general`: | Option | Type | Default | What it does | | -------------- | --------- | ---------------------------- | ------------------------------------------------------------------------------- | | `cashItem` | string | `'money'` | Name of the cash item. Only used with `UseCashAsItem = true`. | | `bankDistance` | number | `5.0` | Metres from a branch within which the server accepts bank operations. | | `atmDistance` | number | `3.0` | Metres from an ATM within which the server accepts ATM operations. | | `moneyItems` | string\[] | `{ 'money', 'black_money' }` | Items counted as money, at face value, in the wealth report of the staff panel. | | `valuedItems` | table | `{}` | Items counted in the wealth report at a price each: `{ gold_bar = 5000 }`. | ## Accounts · `data/accounts.lua` | Option | Type | Default | What it does | | ------------------------------------- | ------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `PINChangeCost` | number | `200` | Fee for changing the PIN of an account. | | `PrintReceiptPrice` | number | `100` | Fee for printing a receipt. | | `NewAccountCost` | number | `500` | Fee shown in the window that creates a shared account. Keep it equal to `CustomAccounts.CreationFee`, which is the amount charged. | | `MaxTransactionsPerPlayer` | number | `nil` (50) | Movements kept in the history shown to the player. | | `ReceiptItem` | string | `'printerdocument'` | Item given as printed receipt. | | `MaxTransferContactsFavorites` | number | `3` | Contacts a player can mark as favourite. | | `CustomAccounts.Enabled` | boolean | `true` | `false` removes shared accounts. | | `CustomAccounts.MaxAccountsPerPlayer` | number | `3` | Shared accounts one character can own. | | `CustomAccounts.CreationFee` | number | `500` | Fee charged for creating a shared account. | Set in `shared/config.lua`, under `accounts`: | Option | Type | Default | What it does | | -------------------------- | ------ | ------- | ----------------------------------------------------------------------------------- | | `transactionRetentionDays` | number | `0` | Days a movement is kept before the daily clean-up deletes it. `0` keeps everything. | | `pin.maxAttempts` | number | `5` | Wrong account PINs allowed before the lock. | | `pin.lockSeconds` | number | `30` | Seconds the account PIN stays locked. | ## Cards · `data/cards.lua` | Option | Type | Default | What it does | | --------------------------- | -------- | ----------- | ------------------------------------------------------------------- | | `EnableCards` | boolean | `true` | `false` disables cards. | | `RenewCardTime` | number | `8` | Years until the expiry date printed on a new card. | | `MaxTotalCreditCards` | number | `10` | Cards one character can have in total, any state. | | `MaxActiveCreditCards` | number | `3` | Active cards one character can have. | | `PlayerCanChangeDailyLimit` | boolean | `false` | `true` lets the owner change the daily limit of a card. | | `MaxDailyLimit` | number | `100000` | Highest daily limit a card can have. | | `CreditCards` | table\[] | three tiers | Card tiers. Each one has `label`, `dailyLimit`, `price` and `item`. | Each tier is its own inventory item. `item` must be the name of an item registered in your inventory, with its image. {% code title="data/cards.lua" %} ```lua CreditCards = { { label = 'Standard Card', dailyLimit = 2500, price = 100, item = 'card_standard' }, { label = 'Premium Card', dailyLimit = 5000, price = 200, item = 'card_premium' }, { label = 'Gold Card', dailyLimit = 10000, price = 300, item = 'card_elite' }, }, ``` {% endcode %} Set in `shared/config.lua`, under `cards`: | Option | Type | Default | What it does | | -------------------- | ------ | ---------- | --------------------------------------------------------------------------- | | `posMaxCharge` | number | `10000000` | Largest amount another resource can charge or refund on a card in one call. | | `pin.maxAttempts` | number | `5` | Wrong card PINs allowed before the card locks. | | `pin.lockMinutes` | number | `15` | Minutes a card stays locked. | | `pin.cooldownMs` | number | `3000` | Milliseconds between two PIN attempts. | | `pin.sessionSeconds` | number | `300` | Seconds an ATM session stays valid after the PIN. | ## Loans · `data/loans.lua` | Option | Type | Default | What it does | | -------------------------------- | ------- | ---------- | ---------------------------------------------------------------------- | | `EnableLoans` | boolean | `true` | `false` disables loans. | | `AccountsWithLoans` | table | all `true` | Account types that can borrow: `personal`, `business`, `custom`. | | `TimeScale.gameMonthRealSeconds` | number | `86400` | Real seconds in one game month. One instalment is due each game month. | | `LoanPlans` | table | five plans | Loan plans. See below. | | `MaxActiveLoans` | number | `4` | Loans one account can have open at once. | | `LoanSchedulerInterval` | number | `1800` | Seconds between two runs of the collection process. Minimum 60. | Set in `shared/config.lua`, under `loans`: `minRate` (`0.5`), the lowest interest rate a loan can end up with after the credit score and reward discounts. ### Plans · `LoanPlans` A plan with a fixed term has `label`, `maxAmount`, `interestRate`, `months` and `enabled`. A plan with `options` lets the player pick the term, each with its own rate. {% code title="data/loans.lua" %} ```lua LoanPlans = { starter = { label = 'Starter Loan', maxAmount = 5000, interestRate = 5.5, months = 12, enabled = true }, custom = { label = 'Custom Loan', maxAmount = 500000, options = { { months = 12, interestRate = 8.5 }, { months = 24, interestRate = 9.0 }, }, enabled = true, }, }, ``` {% endcode %} ### Payments · `Payments` | Option | Type | Default | What it does | | ----------------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------- | | `graceHours` | number | `6` | Hours after the due time before an instalment counts as late. | | `defaultHours` | number | `72` | Hours late after which the loan is in default. | | `blockNewLoansWhenLate` | boolean | `true` | `true` refuses new loans while one is late. | | `penalty.pct` | number | `2.0` | Penalty per interval, as a percentage of what is still owed. | | `penalty.scoreLoss` | number | `5` | Credit score points lost with each penalty. | | `penalty.mode` | string | `'flat'` | `'flat'` adds the same percentage each interval. `'compounding'` applies it on top of the previous ones. | | `penalty.intervalHours` | number | `24` | Hours between two penalties. | | `penalty.capPct` | number | `30.0` | Ceiling of the accumulated penalties, as a percentage of the total of the loan. | ### Borrowing capacity · `Capacity` The most a player can borrow is the lower of two limits, never below zero: one from the account balance, one from income. | Option | Type | Default | What it does | | ------------------------ | -------- | --------- | ----------------------------------------------------------------------------------------------------------- | | `equityMultiplier` | number | `3.0` | Balance limit: (account balance − pending debt) × this value. | | `income.enabled` | boolean | `true` | `true` adds the income limit on personal accounts. Business and shared accounts only use the balance limit. | | `income.recentPaychecks` | number | `5` | Collected paychecks averaged to work out the income. | | `income.factor` | number | `8.0` | Income limit: average income × this value × score multiplier − pending debt. | | `scoreMultipliers` | table\[] | six bands | Multiplier of the income limit by credit score. Each entry has `min` and `mult`. | ### Garnishment · `Garnishment` | Option | Type | Default | What it does | | ---------- | ------- | --------------------- | -------------------------------------------------------------------------- | | `enabled` | boolean | `true` | `false` stops the bank from withholding income. | | `pct` | number | `25.0` | Percentage withheld from each paycheck while a loan is late or in default. | | `statuses` | table | both `true` | Loan states that trigger it: `[1]` late, `[2]` in default. | | `sources` | table | `{ paycheck = true }` | Income the withholding applies to. | ## Credit score · `data/creditscore.lua` | Option | Type | Default | What it does | | ------------- | -------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `Enable` | boolean | `true` | `false` disables the credit score. | | `default` | number | `500` | Score of a new account. | | `min` / `max` | number | `300` / `850` | Limits of the score. | | `bands` | table\[] | six bands | Each band has `min`, `label` and `modifier`: points added to the interest rate of a loan. Negative lowers it. | | `deltas` | table | `onTime = 5`, `late = -10`, `defaulted = -60` | Points gained or lost with each event. | Set in `shared/config.lua`, under `creditScore`: `onTimeCooldownHours` (`0`), the hours that must pass before another payment on time adds points again. `0` means every payment counts. ## Savings · `data/savings.lua` | Option | Type | Default | What it does | | ----------------------------- | ------- | ---------- | ----------------------------------------------------------------------- | | `EnableSavings` | boolean | `true` | `false` disables savings. | | `SavingsWeekEquivalent` | number | `8` | Real hours in one savings week. Interest is paid once per savings week. | | `SavingsInterestRate` | number | `2.5` | Interest percentage of personal goals. | | `MaxActiveGoals` | number | `4` | Goals a personal account can have. | | `BusinessSavingsInterestRate` | number | `3.0` | Interest percentage of business goals. | | `BusinessMaxActiveGoals` | number | `5` | Goals a business account can have. | | `CustomSavingsInterestRate` | number | `2.5` | Interest percentage of shared account goals. | | `CustomMaxActiveGoals` | number | `5` | Goals a shared account can have. | | `AccountsWithSavings` | table | all `true` | Account types that can save: `personal`, `business`, `custom`. | ## Cheques · `data/cheques.lua` | Option | Type | Default | What it does | | ------------- | ------ | ------------------- | ---------------------------------------------------------------------------------------- | | `Item` | string | `'bank_cheque'` | Item given as cheque. | | `BookItem` | string | `'bank_chequebook'` | Item bosses use to issue business cheques. | | `BookSeconds` | number | `30` | Seconds the option to issue a cheque stays on nearby players after using the chequebook. | Set in `shared/config.lua`, under `cheques`: `maxAmount` (`100000000`), the largest amount of one cheque. {% hint style="info" %} Changes to the cheque items need a restart of the resource, also when made from the panel. {% endhint %} ## Rewards · `data/rewards.lua` | Option | Type | Default | What it does | | ------------------------------------ | -------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Enabled` | boolean | `true` | `false` disables rewards. | | `EarnRates` | table | five actions | Points per action: `base` fixed points plus 1 point for every `per` of the amount. `per = 0` gives the base only. Actions: `deposit`, `withdraw`, `transfer`, `atm_use`, `loan_payment`. | | `ActionLabels` | table | five labels | Name of each action in the points history. | | `AntiFarm.Enabled` | boolean | `true` | `false` turns the three protections off. | | `AntiFarm.ActionCooldown` | table | 0 to 60 | Seconds between two awards of the same action, per player. `0` = no cooldown. | | `AntiFarm.DailyPointsCap` | number | `500` | Points a player can earn per day. `0` = no cap. | | `AntiFarm.RoundTrip.windowSeconds` | number | `300` | Window in which the opposite action cancels the points. | | `AntiFarm.RoundTrip.amountTolerance` | number | `0.25` | How close the two amounts must be to count as the same money: `0.25` = ±25 %. | | `AntiFarm.RoundTrip.pairs` | table | deposit ↔ withdraw | Which action is the opposite of which. | | `Categories` | table\[] | five | Tabs of the catalogue: `key` and `label`. | | `Catalog` | table\[] | ten rewards | Rewards on offer. See below. | Each reward has `id` (unique), `name`, `description`, `cost` in points, `icon`, `category` and `type`: | `type` | What the player gets | Fields | | ------------------ | -------------------------------------------- | ------------------------------- | | `'cash'` | `value` paid into the bank at once. | `value` | | `'fee_waiver'` | The next bank fee is free. | `uses`, `durationDays` | | `'interest_boost'` | `value` % more interest on personal savings. | `value`, `durationDays` | | `'loan_discount'` | `value` % less on the rate of the next loan. | `value`, `uses`, `durationDays` | ## ATMs · `data/atms.lua` | Option | Type | Default | What it does | | ------------- | -------- | ----------- | ------------------------------------------------------------------------------------------ | | `ATMDistance` | number | `1.5` | Target distance of an ATM, in metres. | | `ATM` | table\[] | four models | Prop models that work as ATM. Each entry is `{ model = hash }`, with the hash as a number. | ## Branches · `data/banks.lua` | Option | Type | Default | What it does | | ------------------ | -------- | ------------ | ---------------------------------------------------------------------------------------------------------- | | `ShowBankBlips` | boolean | `true` | `false` hides every bank blip. Part of the general section: after the first start, change it in the panel. | | `DebugTargetZones` | boolean | `false` | `true` draws the target zones of the branches. | | `BankLocations` | table\[] | example list | Branches created on the first start. | {% hint style="warning" %} `BankLocations` is read once, when the points table is empty. After that, manage branches and ATM points from `/bankadmin` → Points. The list in the file is an example for the default map: replace it before the first start if your banks are somewhere else. {% endhint %} ## Interface · `data/interface.lua` and `ui` | Option | Type | Default | What it does | | ------------------------------------ | ------------ | ------------ | -------------------------------------------- | | `AccentColor` (`data/interface.lua`) | string (hex) | `'#e53935'` | Accent colour of the bank and ATM interface. | | `ui.accent` (`shared/config.lua`) | string (hex) | configurable | Accent colour of the staff panel. | ## Discord logs · `data/webhook.lua` | Option | Type | Default | What it does | | ------------ | ------ | ---------------------- | --------------------------------------------------- | | `BotName` | string | `'CuxialBank'` | Name the messages are posted under. | | `ServerName` | string | `'My Server'` | Name shown as author of each message. | | `IconURL` | string | `''` | Icon next to the author. | | `DateFormat` | string | `'%d/%m/%Y [%X]'` | Date format of the footer. | | `Webhook` | table | one entry per log type | For each log type: `enabled` and `color` (decimal). | Set in `shared/config.lua`, under `logs`: | Option | Type | Default | What it does | | ----------- | ------- | -------------------------- | --------------------------------------------------------------------------------------------------------------- | | `enabled` | boolean | `true` | `false` sends no logs at all. | | `convar` | string | `'cuxial_banking_webhook'` | Name of the convar that holds the webhook URL. A convar named `_` overrides it for that type. | | `auditDays` | number | `90` | Days the audit log of the staff panel is kept. `0` keeps everything. | The URL itself is never written in a file. See [Installation](/scripts/core/cuxial-banking/installation.md). ## The rest of `shared/config.lua` | Option | Type | Default | What it does | | ---------------------------- | --------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------- | | `debug` | boolean | `false` | Prints traces to the console. Also enabled by setting the convar `cuxial_banking_debug` to `1`. | | `commands.admin.name` | string | `'bankadmin'` | Command that opens the staff panel. An empty string removes the command. | | `commands.admin.restricted` | string \| false | `false` | ACE group required by the command, for example `'group.admin'`. `false` leaves only the check of `admin.permission`. | | `admin.permission` | string | `'admin'` | Permission of your framework that makes a player bank staff. | | `world.targetDistance` | number | `1.5` | Target distance of a branch, in metres. | | `world.chequeTargetDistance` | number | `2.0` | Distance at which a boss can target a player to issue a business cheque. | | `world.nearbyRadius` | number | `12.0` | Radius in which nearby players are offered as transfer recipients. | | `world.interactions` | string | `'cuxial_interactions'` | Name of the resource that shows branches as NPCs. | | `wealth.cacheSeconds` | number | `15` | Seconds a wealth report is reused before it is worked out again. | | `wealth.providerTimeoutMs` | number | `2000` | Milliseconds each source of the wealth report has to answer. | | `wealth.containerDepth` | number | `3` | Levels of containers inside containers that the wealth report opens. | | `limits.reasonLength` | number | `100` | Characters of a transfer reason. | | `limits.accountNameLength` | number | `100` | Characters of a shared account name. | | `limits.goalNameLength` | number | `100` | Characters of a savings goal name. | | `limits.chequePayToLength` | number | `100` | Characters of the payee of a cheque. | | `limits.chequeMemoLength` | number | `120` | Characters of the note of a cheque. | | `limits.contactNameLength` | number | `48` | Characters of a contact name. | | `limits.maxContacts` | number | `50` | Contacts per player. | | `limits.maxMultiTransfer` | number | `20` | Recipients of one transfer to several contacts. | | `limits.savingsMaxTarget` | number | `4294967295` | Highest target of a savings goal. | | `limits.lockWaitMs` | number | `5000` | Milliseconds an operation waits for another one on the same account to finish. | ## Common changes ### Move the bank to a different cash item In `/bankadmin` → Config → General, set the cash item to the one your inventory uses, or turn cash as item off to use the cash account of your framework. ### Make loans faster or slower `TimeScale.gameMonthRealSeconds` sets the pace. With `43200`, an instalment is due every 12 real hours. ### Add a card tier Register a new item in your inventory. Before the first start, add a line to `CreditCards`; afterwards, add the tier in `/bankadmin` → Config, in the cards section. ```lua { label = 'Black Card', dailyLimit = 50000, price = 1000, item = 'card_black' }, ``` ### Translate the texts Every text is in `locales/en.json` and `locales/es.json`. The names of loan plans, card tiers, credit score bands and rewards are in the data files. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.cuxial.com/scripts/core/cuxial-banking/configuration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.