> ## Documentation Index
> Fetch the complete documentation index at: https://docs.awokenlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Loans & credit

> Borrow against a credit limit, repay in fixed installments, and build a credit score that unlocks bigger loans and better savings.

Every player has one **credit line**. Their **credit score** (0-1000) sets a single **borrowing limit**, and everything they owe - a bank cash loan, or a car/house financed through another script - draws from it. Paying debt down frees the limit back up. Everything here is in `config/loans.lua`.

* The player borrows up to their available limit; the bank works out the **interest** for the whole term up front and adds it to what's owed.
* The total splits into **fixed installments**, auto-collected from the borrower's **personal account** on a schedule.
* Interest is **simple** and charged over the **full term**, baked in at the start - settling early doesn't dodge it.
* Paying on time **raises** credit; missing payments **lowers** it and adds fees.

## Master switches

```lua config/loans.lua theme={"dark"}
Config.Loans = {
    enabled          = true,   -- the whole loans system
    borrowingEnabled = true,   -- allow NEW debt
    ...
}
```

`enabled` turns the feature on or off. `borrowingEnabled = false` blocks **new** loans while **existing loans keep running** (installments still collect, credit still updates) - use it to freeze lending without wiping live debt.

## How interest works

Flat percentage **per day** on the amount borrowed (not an APR): `interest = amount × daily rate × days`. The daily rate is a **base rate** from the player's credit band plus a **surcharge** on larger loans:

```lua config/loans.lua theme={"dark"}
dailyRate = {
    -- Base daily rate by credit band - highest band the score reaches wins (better score = cheaper).
    byScore = {
        { minScore = 0,   pct = 1.6  },
        { minScore = 300, pct = 1.2  },
        { minScore = 500, pct = 0.8  },
        { minScore = 700, pct = 0.5  },
        { minScore = 850, pct = 0.35 },
    },
    -- Extra %/day on bigger loans - first band the amount fits into (upTo = nil catches the rest).
    sizeSurcharge = {
        { upTo = 100000, add = 0.0 },
        { upTo = 500000, add = 0.1 },
        { upTo = nil,    add = 0.2 },
    },
    allowOverride = true,   -- let an integrating script pass its own rate…
    overrideMin   = 0.0,    -- …clamped between this floor…
    overrideMax   = 3.0,    -- …and this ceiling
}
```

## The credit score

Runs **0-1000**, starts at `creditScoreStart` for new players, and does two jobs: sets the **borrowing limit** and unlocks **savings tiers**.

* **Borrowing limit** - the `limit` bands map score to a total credit cap (most a player can owe across all debt at once). Highest reached band wins; **available** credit is that limit minus current debt.
* **Savings** - higher tiers with better rates and caps require a minimum score. See [Savings & interest](/resources/awoken-banking/configuration/savings).
* **What moves it** - `creditDeltas` reward on-time payments and completed loans, and penalise overdue debt daily (worsening each day down to a cap). Always clamped to 0-1000.

## When a payment is missed

A staged pipeline, each stage configurable:

* **Grace** (`gracePeriodDays`) - a short window before any penalty lands.
* **Late fee** (`lateFeesEnabled`, `latePenaltyPercent`) - a one-time fee, a percentage of the outstanding balance, added **once** when the payment goes late.
* **Overdue** - credit bleeds daily (the `delinquent…` deltas) and the bank **auto-collects** toward the debt, on bank open and on a timer.
* **Default** (`autoDefaultAfterDays`) - an **asset** loan (financed car/house) is handed back to the originating script to be **repossessed** and the player takes the `loanDefaulted` hit. A plain cash loan has nothing to repossess, so it just stays overdue - collected and decaying credit - until cleared. Set `assetRepossession = false` to make **everything** use the cash model (nothing is ever repossessed).

<Warning>
  Auto-collection only ever touches **bank** balances, never cash on hand. Holding wealth as cash is the deliberate way to stall an overdue debt - the trade-off is a credit score that keeps sinking the whole time.
</Warning>

## Editable options

| Option                                  | What it does                                                                                                       | Default                                                  |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- |
| `enabled`                               | Master switch for the whole loans system.                                                                          | `true`                                                   |
| `borrowingEnabled`                      | Allow **new** loans. `false` freezes new lending but keeps existing loans running.                                 | `true`                                                   |
| `paymentEveryDaysDefault`               | How often an installment is collected, in days. `1` is daily. `0` (or ≥ the term) makes it one payment at the end. | `1`                                                      |
| `maxTermDays`                           | Longest loan term, and the default term. `0` = no cap (falls back to 30).                                          | `30`                                                     |
| `limit`                                 | Credit-score → borrowing-limit bands. Highest reached band wins.                                                   | Ladder from `5000` at score 0 to `1000000` at score 1000 |
| `dailyRate.byScore`                     | Base daily interest rate per credit band. Better score = cheaper.                                                  | `1.6%`/day at the bottom down to `0.35%`/day at the top  |
| `dailyRate.sizeSurcharge`               | Extra daily rate on larger loans.                                                                                  | `0%` under 100k, up to `0.2%` above 500k                 |
| `dailyRate.allowOverride`               | Let an integrating script supply its own daily rate (clamped).                                                     | `true`                                                   |
| `dailyRate.overrideMin` / `overrideMax` | Floor and ceiling for an override rate.                                                                            | `0.0` / `3.0`                                            |
| `lateFeesEnabled`                       | Charge a fee when a payment goes late.                                                                             | `true`                                                   |
| `gracePeriodDays`                       | Days of grace before a late payment is penalised.                                                                  | `1`                                                      |
| `latePenaltyPercent`                    | One-time late fee, as a fraction of the outstanding balance.                                                       | `0.05` (5%)                                              |
| `autoDefaultAfterDays`                  | Days overdue before an asset loan is repossessed.                                                                  | `14`                                                     |
| `assetRepossession`                     | Repossess asset-backed loans on default. `false` = everything uses the cash model.                                 | `true`                                                   |
| `creditScoreEnabled`                    | Turn the credit score on or off.                                                                                   | `true`                                                   |
| `creditScoreStart`                      | The score new players begin with.                                                                                  | `600`                                                    |
| `creditDeltas.onTimePayment`            | Credit gained per installment paid on time.                                                                        | `15`                                                     |
| `creditDeltas.loanCompleted`            | Credit gained when a loan is fully paid off.                                                                       | `50`                                                     |
| `creditDeltas.loanDefaulted`            | One-time credit lost when an asset loan is repossessed.                                                            | `-200`                                                   |
| `creditDeltas.delinquentBase`           | Credit lost on the first overdue day.                                                                              | `-10`                                                    |
| `creditDeltas.delinquentStep`           | How much worse each further overdue day gets.                                                                      | `-5`                                                     |
| `creditDeltas.delinquentCap`            | Floor on the daily overdue penalty.                                                                                | `-40`                                                    |