> For the complete documentation index, see [llms.txt](https://dragon-heart-studios.gitbook.io/dragonheartstudios/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dragon-heart-studios.gitbook.io/dragonheartstudios/scripts/dhs-bankingsim/configuration.md).

# Configuration

## Configuration

All main settings live in `config/config.lua`. This file is not locked — you can edit everything in it freely.

***

### General Settings

| Key                           | Default         | Description                                                           |
| ----------------------------- | --------------- | --------------------------------------------------------------------- |
| `Config.Debug`                | `true`          | Print debug messages to server console. Set to `false` in production. |
| `Config.BankingName`          | `"Fleeca Bank"` | Name shown in UI headers and notifications                            |
| `Config.PedDistanceSpawn`     | `15.0`          | Distance (metres) at which bank peds spawn and despawn                |
| `Config.MaxTransactionAmount` | `10000000`      | Hard cap on any single transaction ($10M)                             |

***

### Currency

```lua
Config.Currency = {
    Code     = 'USD',     -- 'EUR', 'GBP', 'JPY', etc.
    Locale   = 'en-US',   -- 'de-DE' → "1.000,00 €"
    Symbol   = '$',       -- Overrides locale default. Leave nil to use locale symbol.
    Position = 'prefix',  -- 'prefix' ($100) or 'suffix' (100 €)
    Decimals = 2,
}
```

Changing `Locale` and `Symbol` is all that's needed for most servers. The locale controls thousand/decimal separators.

***

### Blips

```lua
Config.Blips = {
    Enabled = true,   -- Bank blips on the map
    ATMs = {
        Enabled = false,  -- ATM blips (can clutter the map)
        Sprite  = 108,
        Color   = 2,
        Scale   = 0.5,
        Label   = 'ATM',
    },
}
```

***

### Card Settings

| Key                      | Default | Description                                                                                                                |
| ------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------- |
| `UniqueCards`            | `true`  | Each card gets its own unique number, expiry date, and PIN                                                                 |
| `RequireCardInInventory` | `true`  | Player must hold the physical card item in inventory to use it. Set to `false` if you don't use inventory items for cards. |

***

### Overdraft

| Key               | Default  | Description                                     |
| ----------------- | -------- | ----------------------------------------------- |
| `Enabled`         | `true`   | Allow accounts to go negative up to their limit |
| `Limits.checking` | `500`    | Maximum overdraft for checking accounts         |
| `Limits.savings`  | `0`      | Savings accounts cannot go negative             |
| `Limits.business` | `1000`   | Business account overdraft limit                |
| `Limits.joint`    | `250`    | Joint account overdraft limit                   |
| `Fee`             | `$35.00` | Flat fee charged per overdraft event            |

***

### Business Banking

| Key                       | Default    | Description                                    |
| ------------------------- | ---------- | ---------------------------------------------- |
| `MaxBusinessesPerPlayer`  | `1`        | How many business accounts a player can own    |
| `DefaultPayrollFrequency` | `'weekly'` | `'daily'`, `'weekly'`, or `'biweekly'`         |
| `EntityLinkingEnabled`    | `true`     | Link business accounts to framework jobs/gangs |
| `MinInitialDeposit`       | `0`        | Required deposit to open a business account    |
| `Tax.Enabled`             | `true`     | Enable payroll tax                             |
| `Tax.Rate`                | `0.10`     | 10% tax deducted from business payroll         |

#### Default Spending Caps by Role

| Role      | Spending Cap | Daily Limit |
| --------- | ------------ | ----------- |
| Owner     | $999,999     | $100,000    |
| Treasurer | $50,000      | $25,000     |
| Manager   | $15,000      | $10,000     |
| Employee  | $2,500       | $2,000      |

#### Suspicious Activity Detection

Business accounts are monitored for unusual transaction patterns:

| Setting                   | Default   | Description                                                                |
| ------------------------- | --------- | -------------------------------------------------------------------------- |
| `HighVolumeThreshold`     | `$5,000`  | Amount that counts as "high volume"                                        |
| `HighVolumeCount`         | `3`       | Flag after this many high-volume transactions in the window                |
| `HighVolumeWindowHours`   | `24`      | Window for high-volume detection                                           |
| `RepetitiveTransferCount` | `4`       | Same-recipient transfers within `RepetitiveTransferDays` to trigger a flag |
| `RepetitiveTransferDays`  | `7`       | Lookback period for repetitive transfer detection                          |
| `OffHoursStart`           | `2`       | Off-hours window start (24h clock)                                         |
| `OffHoursEnd`             | `5`       | Off-hours window end                                                       |
| `OffHoursMinAmount`       | `$10,000` | Off-hours transfers above this are flagged                                 |

***

### Credit Scores

| Key            | Default | Description                    |
| -------------- | ------- | ------------------------------ |
| `MinScore`     | `300`   | Minimum possible credit score  |
| `MaxScore`     | `850`   | Maximum possible credit score  |
| `DefaultScore` | `600`   | Starting score for new players |

#### Credit Score Tiers

| Tier      | Range   |
| --------- | ------- |
| Poor      | 300–549 |
| Fair      | 550–669 |
| Good      | 670–749 |
| Excellent | 750–850 |

#### Score Calculation Weights

| Factor             | Weight |
| ------------------ | ------ |
| Payment History    | 40%    |
| Credit Utilization | 30%    |
| Account Age        | 15%    |
| Defaults & Fraud   | 15%    |

#### Penalties & Recovery

| Event                      | Change |
| -------------------------- | ------ |
| Missed payment             | −25    |
| Default                    | −75    |
| Fraud flag                 | −50    |
| Hard inquiry               | −5     |
| On-time payment            | +8     |
| Account tenure (per month) | +1     |
| Balance reduction          | +5     |

***

### Loans

| Key                           | Default   | Description                                                |
| ----------------------------- | --------- | ---------------------------------------------------------- |
| `GracePeriodDays`             | `3`       | Days past due before a late fee is charged                 |
| `DefaultAfterMissed`          | `3`       | Consecutive missed payments before the loan defaults       |
| `LateFee.Flat`                | `$50`     | Flat late fee                                              |
| `LateFee.Percent`             | `0.05`    | Alternative: 5% of the missed payment                      |
| `AutoApproval.MinCreditScore` | `700`     | Loans below this score require manual review               |
| `AutoApproval.MaxAmount`      | `$25,000` | Loans above this require manual review regardless of score |

#### Loan Types

| Type          | APR   | Min     | Max        | Max Term   |
| ------------- | ----- | ------- | ---------- | ---------- |
| Personal      | 8.9%  | $1,000  | $50,000    | 60 months  |
| Vehicle       | 6.5%  | $5,000  | $150,000   | 84 months  |
| Business      | 9.2%  | $10,000 | $500,000   | 120 months |
| Property      | 5.5%  | $50,000 | $2,000,000 | 360 months |
| Emergency     | 14.9% | $500    | $10,000    | 24 months  |
| Consolidation | 7.8%  | $2,000  | $80,000    | 60 months  |

***

### Phone Banking

| Key                           | Default                  | Description                                              |
| ----------------------------- | ------------------------ | -------------------------------------------------------- |
| `Enabled`                     | `true`                   | Master switch for phone banking                          |
| `DailyLimit`                  | `$50,000`                | Max total phone transfers per day per player             |
| `MaxTransactionAmount`        | `$25,000`                | Max single phone transfer                                |
| `TransferFee`                 | `flat $5`                | Fee per phone transfer (`type`: `'flat'` or `'percent'`) |
| `StepUpThreshold`             | `$10,000`                | Transfers above this require PIN re-entry                |
| `MaxPinAttempts`              | `3`                      | Failed PIN attempts before lockout                       |
| `LockoutMinutes`              | `15`                     | Lockout duration after too many failed PINs              |
| `DefaultPin`                  | `'1234'`                 | PIN assigned to newly enrolled accounts                  |
| `VelocityLimit.count`         | `10`                     | Max transactions per time window                         |
| `VelocityLimit.windowMinutes` | `60`                     | Velocity check window in minutes                         |
| `SessionTimeoutMinutes`       | `30`                     | Idle time before the phone session expires               |
| `AuthorizedJobs`              | `police, doj, bankstaff` | Jobs that can view phone banking records                 |

See Phone Banking Integration for setup.

***

### Employee Roles

| Role               | Pay Rate     | Key Permissions                                   |
| ------------------ | ------------ | ------------------------------------------------- |
| Teller             | $50/cycle    | Deposits, withdrawals, cash conversion            |
| Vault Manager      | $100/cycle   | Teller + large transaction auth, vault access     |
| Loan Officer       | $80/cycle    | Loan review and approval                          |
| Compliance Officer | $90/cycle    | Fraud tools, account freezing, transaction review |
| Manager            | $150/cycle   | All of the above + hiring/firing/promoting        |
| Owner              | Profit share | All permissions                                   |

The owner earns from bank profits, not a fixed payroll.

***

### Teller Queue

| Key                         | Default   | Description                                              |
| --------------------------- | --------- | -------------------------------------------------------- |
| `MaxQueueSize`              | `20`      | Max customers waiting at once                            |
| `RequestTimeoutSeconds`     | `600`     | Unhandled requests expire after this                     |
| `LargeTransactionThreshold` | `$50,000` | Above this, a Vault Manager must approve the transaction |

***

### Operational Modes

Branch operational modes control which services are available based on staffing level. Set via `Config.OperationalModes.DefaultMode`.

| Mode             | Description                                                          |
| ---------------- | -------------------------------------------------------------------- |
| `automated`      | All services available, no staff needed                              |
| `hybrid`         | All services available, at least 1 staff member online               |
| `staff_required` | Full service requires at least 3 staff online                        |
| `offline`        | Only account inquiries work; deposits/withdrawals/transfers disabled |

**Auto-detection:** When `AutoDetectEnabled = true`, the mode switches automatically based on online staff count:

| Staff Online | Auto-Mode        |
| ------------ | ---------------- |
| 0            | `automated`      |
| 1–2          | `hybrid`         |
| 3+           | `staff_required` |

Staff presence in `hybrid`/`staff_required` modes provides an efficiency bonus: 10% fee reduction and 20% faster processing.

***

### Reputation System

Bank reputation affects NPC customer traffic and revenue.

| Key                      | Default | Description                                     |
| ------------------------ | ------- | ----------------------------------------------- |
| `MinScore`               | `0`     | Minimum reputation                              |
| `MaxScore`               | `1000`  | Maximum reputation                              |
| `DefaultScore`           | `500`   | Starting reputation for new banks               |
| `PassiveRecoveryPerHour` | `1`     | Points regained per hour while the bank is open |
| `MigrationThreshold`     | `200`   | Below this score, customers may stop visiting   |

#### Reputation Tiers

| Tier      | Range    | NPC Spawn Multiplier |
| --------- | -------- | -------------------- |
| Poor      | 0–200    | 0.3×                 |
| Fair      | 201–400  | 0.6×                 |
| Good      | 401–600  | 1.0×                 |
| Excellent | 601–800  | 1.3×                 |
| Elite     | 801–1000 | 1.6×                 |

#### Reputation Events

| Event                      | Change |
| -------------------------- | ------ |
| Successful transaction     | +1     |
| Loan repayment             | +3     |
| NPC service completed      | +1     |
| High customer satisfaction | +2     |
| Loan default               | −15    |
| Fraud flag                 | −10    |
| Customer complaint         | −5     |
| NPC service timeout        | −2     |
| Low customer satisfaction  | −3     |

***

### NPC Customer System

NPC customers spawn near the bank entrance and generate service revenue for the vault.

| Key                      | Default | Description                                                                       |
| ------------------------ | ------- | --------------------------------------------------------------------------------- |
| `Enabled`                | `true`  | Master switch for NPC customers                                                   |
| `ServerSynced`           | `false` | `false` = each player sees their own NPCs; `true` = all players see the same NPCs |
| `SpawnIntervalSeconds`   | `45`    | Base time between spawn attempts                                                  |
| `MaxConcurrentNPCs`      | `6`     | Max NPCs at the bank at one time                                                  |
| `QueueTimeoutSeconds`    | `180`   | How long an NPC waits in queue before leaving                                     |
| `ServiceDurationSeconds` | `20`    | How long an NPC transaction takes                                                 |
| `DailyTransactionCap`    | `500`   | Max NPC transactions per real day per bank (caps vault income)                    |
| `SpawnDistance`          | `150.0` | Max distance from a player to a spawn point to still spawn                        |
| `DespawnDistance`        | `30.0`  | Distance from bank at which an NPC is removed                                     |
| `MaxLifetimeSeconds`     | `600`   | Hard lifetime cap for any NPC                                                     |

#### Spawn Rate by Hour (24h)

| Hours       | Multiplier       |
| ----------- | ---------------- |
| 00:00–05:00 | 0.0× (no spawns) |
| 06:00       | 0.1×             |
| 07:00       | 0.3×             |
| 08:00       | 0.7×             |
| 09:00–10:00 | 1.0×–1.2×        |
| 11:00       | 1.3×             |
| 12:00       | 1.5× (peak)      |
| 13:00–17:00 | 0.9×–1.3×        |
| 18:00–21:00 | 0.1×–0.6×        |
| 22:00–23:00 | 0.0×             |

#### Service Revenue (per completed NPC transaction)

| Service         | Revenue |
| --------------- | ------- |
| Transfer        | $25     |
| Deposit         | $15     |
| Withdrawal      | $10     |
| Account Inquiry | $5      |

Revenue is scaled by the branch's current reputation multiplier.

***

### Bank Ownership

| Key                           | Default    | Description                                                   |
| ----------------------------- | ---------- | ------------------------------------------------------------- |
| `Enabled`                     | `true`     | Allow players to buy and own bank branches                    |
| `LicenseCost`                 | `$500,000` | One-time cost for a banking license                           |
| `MinimumCapitalDeposit`       | `$100,000` | Required starting capital when buying                         |
| `MaxBanksPerPlayer`           | `1`        | Max branches a single player can own                          |
| `TransferCooldownHours`       | `72`       | Cooldown after transferring ownership before another transfer |
| `DissolutionGracePeriodHours` | `48`       | How long a dissolved bank lingers before removal              |
| `PrimaryBankSwitchFee`        | `$500`     | Fee for switching the primary bank brand                      |

See Bank Ownership & Upgrades for full details.

***

### Interbank Clearing

| Key                    | Default       | Description                                             |
| ---------------------- | ------------- | ------------------------------------------------------- |
| `Enabled`              | `true`        | Enable clearing house for cross-bank transfers          |
| `BatchIntervalSeconds` | `300`         | How often pending transfers are batched (5 minutes)     |
| `ClearingDelaySeconds` | `600`         | Delay before funds land at the destination (10 minutes) |
| `InterbankFeePercent`  | `0.5`         | Fee on interbank transfers (0.5%)                       |
| `MaxTransferAmount`    | `$10,000,000` | Per-transfer limit through clearing                     |
| `MaxPendingPerBank`    | `50`          | Max queued transfers per bank                           |

***

### Central Reserve

The central reserve acts as a federal banking layer. Most servers don't need to change these values.

| Key                            | Default                        | Description                                      |
| ------------------------------ | ------------------------------ | ------------------------------------------------ |
| `Enabled`                      | `true`                         | Enable central reserve                           |
| `InitialBalance`               | `$10,000,000`                  | Starting reserve balance on first setup          |
| `ReserveRequirementPercent`    | `10`                           | % of deposits banks must hold in reserve         |
| `MinimumReserveBalance`        | `$1,000,000`                   | Hard floor for the reserve                       |
| `EmergencyLiquidityMaxPercent` | `25`                           | Max % of reserve that can be lent in emergencies |
| `AuthorityRoles`               | `government (grade 3+), judge` | Jobs/grades that can manage the central reserve  |

Access is controlled by `/reserve` — see Admin Commands.

***

### Fraud Detection

> **Coming in a future update.** The configuration keys exist in `config.lua` but the fraud detection system is **not active in v1.0.1**. `Config.Fraud.Enabled` is `false` by default. Do not enable it until the oversight UI is finished.

***

### Multi-Bank Locations

Bank branches are set up in `Config.Banks`. Each bank has a `brand` (e.g. `fleeca`) and one or more branch locations with numeric IDs. Player accounts, cards, loans, and transactions belong to the brand; employees, teller queues, reputation, and upgrades belong to the individual branch location.

Default locations included: **Fleeca Downtown** (ID 1), **Fleeca Vinewood** (ID 2), **Fleeca Burton** (ID 3).

See `config/config.lua` → `Config.Banks` for the full coordinate and door configuration for each branch.