> ## 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.
# Tax
> Charge tax on player transactions, run a scheduled business tax, or both.
Awoken Banking has **two separate taxes** in `config/tax.lua`, each with its own on/off switch: a **player transaction tax** taken from everyday banking as it happens, and a **business tax** billed on a scheduled tax day using income-tax brackets. To tax only businesses, leave `enabled = false` and set `business.enabled = true` - the two are independent.
Both taxes are **off by default** (`enabled = false` and `business.enabled = false`). Nothing is charged until you turn one on.
## Player transaction tax
A percentage taken from each taxable player transaction the moment it happens.
```lua config/tax.lua theme={"dark"}
Config.Tax = {
enabled = true,
rate = 0.05, -- default 5% (0..1)
}
```
| Option | What it does | Default |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `enabled` | Turn player tax on. | `false` |
| `rate` | Default cut per taxable transaction, as a fraction (`0.05` = 5%). | `0.05` |
| `rates` | Per-kind overrides, e.g. `{ interest = 0.10 }`. Unlisted kinds use `rate`. Built-in kinds: `deposit`, `withdraw`, `transfer`, `interest`. Add custom kinds (e.g. `sales`) for other scripts to charge via the tax exports. | `{}` |
| `mode` | How tax is collected when the balance can't cover amount + tax. See below. | `'ontop'` |
| `taxable` | Which types are taxed: `{ deposit = false, withdraw = true, transfer = true, interest = true }`. | withdraw, transfer, interest on |
| `exemptions` | Jobs and players that skip the tax: `{ jobs = {...}, citizenids = {...} }`. | none |
| `label` | Name shown on the transaction (the "to"/"from"). Does not decide where money lands. | `'Government'` |
| `destination` | Where tax lands: `'sink'` (destroyed), or a split list of `{ account = 'job:police', share = 0.7 }` entries. Shares total at most 1; any remainder is destroyed. | `'sink'` |
**Collection modes** (`mode`):
| Mode | What it does |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ontop` | Tax is charged **on top**, capped at the balance. The player always gets their full withdrawal; if there isn't enough left, it collects what it can. Lenient default. |
| `block` | The action is **rejected** unless the balance covers both amount and tax. |
| `deduct` | Tax comes **out of** the amount, never capped. Withdraw 20k, get 19k plus 1k tax. Always fully collected. |
## Business tax
A scheduled tax on shared business accounts (jobs and gangs), billed on a fixed **calendar tax day** using marginal brackets like real income tax. Independent of the player tax; controlled by the `business` block.
```lua config/tax.lua theme={"dark"}
business = {
enabled = true,
}
```
| Option | What it does | Default |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| `enabled` | Turn business tax on. | `false` |
| `period` | How often each business is billed: `'day'` (00:00 daily), `'week'` (a chosen weekday), `'month'` (the 1st). Server local time; one synchronised billing moment for all. | `'week'` |
| `dayHour` | Hour the tax day sits at, `0`–`23` (`0` = midnight). | `0` |
| `weekday` | Which day the **weekly** period bills on, `1`=Mon … `7`=Sun. Monthly always bills the 1st. | `1` |
| `base` | What the brackets apply to: `'profit'` (balance growth since last run; no growth = no tax) or `'balance'` (whole balance every period). | `'profit'` |
| `allowance` | Tax-free amount before any bracket applies. | `50000` |
| `brackets` | Marginal bands: each taxes from the previous ceiling up to `upTo` at its `rate`. A final `upTo = nil` covers everything above. | see below |
| `accountTypes` | Which shared account types are taxed: `{ job = true, gang = true, shared = false }`. | job, gang |
| `exemptJobs` | Jobs or gangs that never pay (typically public services). | `{ 'police', 'ambulance', ... }` |
| `account` | Where business tax lands: `nil` = use the player tax `destination`; or a single key like `'job:government'`; or a split list in the same format. | `nil` |
```lua config/tax.lua theme={"dark"}
allowance = 50000,
brackets = {
{ upTo = 100000, rate = 0.20 }, -- 50k-100k at 20%
{ upTo = nil, rate = 0.40 }, -- above 100k at 40%
},
```
Only the money in each band is taxed at that band's rate. A business with **150,000** to tax under the settings above pays: first 50k free, next 50k at 20% = 10,000, final 50k at 40% = 20,000, for **30,000** total.
## Running it manually
| Command | What it does |
| ----------------------- | ----------------------------------------------- |
| `/bank_run businesstax` | Bills every un-taxed business right now. |
| `/bank_advance ` | Fast-forwards the schedule by a number of days. |