# Configuration

**Version:** 2.0.0 (not released yet)

The configuration is `mods/kyuubisoft_claims/config.json`. It is written with all defaults at the first start.

You have two ways to change it:

- **In the game:** the **Rules and protection** page of the [admin window](./ui-pages#rules-and-protection) has the quota, abandoned claims, the economy, the worlds, the protection switches, the notice timers, the home timers and the exceptions. A switch saves at once, each group of numbers has its own **Save** button. The file is written right away, everything else in it stays as it is.
- **In the file:** edit `config.json`, then run `/ksclaimadmin reload` (or the reload button of the Claims tile in the `/ksadmin` hub).

Values out of range are corrected when the file is read, and the corrected file is written back. A missing section or key gets its default.

---

## Default configuration

```json
{
  "configVersion": 1,
  "general": {
    "nameMin": 3,
    "nameMax": 24,
    "greetingMax": 80,
    "blockedWorlds": [],
    "maxSelectionChunks": 64,
    "maxZonesPerClaim": 10,
    "maxPeoplePerClaim": 0,
    "transferAcceptSeconds": 300,
    "deleteConfirmSeconds": 60,
    "serverZoneRadiusMax": 16
  },
  "quota": {
    "startChunks": 25,
    "maxChunks": 200,
    "maxClaims": 5,
    "growthChunks": 0,
    "growthEveryHours": 5,
    "chunkTiers": [25, 50, 100, 200, 500, 1000],
    "claimTiers": [1, 2, 3, 5, 10, 20],
    "bufferChunks": 0
  },
  "economy": {
    "enabled": false,
    "chunkCost": 100.0,
    "worldChunkCosts": {},
    "chunkUnclaimRefund": 50.0,
    "purchaseChunkCost": 500.0
  },
  "decay": {
    "days": 0,
    "warningDays": 7,
    "abandonedListDays": 60,
    "enabledAt": 0
  },
  "home": {
    "warmupSeconds": 3,
    "cooldownSeconds": 10,
    "cancelDistance": 1.0
  },
  "protection": {
    "explosions": true,
    "creatures": true,
    "attach": true,
    "underContainers": true,
    "benches": true,
    "fireOnlyAllowed": true,
    "denyMessages": true,
    "denyCooldownSeconds": 3,
    "allowFly": false,
    "allowKeepInventory": false,
    "useExceptions": ["gravestone", "mailbox"],
    "breakExceptions": []
  },
  "display": {
    "enterToastCooldownSeconds": 10,
    "borderSeconds": 10,
    "mapTerrain": true
  },
  "log": {
    "keepDays": 30,
    "maxEntriesPerClaim": 500,
    "mergeSeconds": 60
  }
}
```

`configVersion` is set by the plugin. Leave it as it is.

---

## General

| Key | Default | Range | Meaning |
|-----|---------|-------|---------|
| `nameMin` | `3` | 1–24 | Shortest name of a claim, a zone or a server zone |
| `nameMax` | `24` | `nameMin`–48 | Longest name |
| `greetingMax` | `80` | 0–200 | Longest greeting |
| `blockedWorlds` | `[]` | | Worlds where nobody can claim land (names, any case). Land claimed there before stays. Instance worlds are always locked and need no entry |
| `maxSelectionChunks` | `64` | 1–1024 | Most chunks one claim action may take (map selection) |
| `maxZonesPerClaim` | `10` | 0–100 | Zones per claim |
| `maxPeoplePerClaim` | `0` | 0–10000 | People with a role (trusted and co-owners) per claim. `0` = no limit |
| `transferAcceptSeconds` | `300` | 10–3600 | How long a hand-over offer waits for `/ksclaim accept` |
| `deleteConfirmSeconds` | `60` | 5–600 | How long the confirmation code of `delete` stays valid |
| `serverZoneRadiusMax` | `16` | 0–64 | Largest radius (in chunks) of `/ksclaimadmin zone create <name> <radius>` |

In the admin window the **Worlds** list switches claiming per world on and off, and **Lock world** adds a world by name.

---

## Quota

| Key | Default | Range | Meaning |
|-----|---------|-------|---------|
| `startChunks` | `25` | 0–1,000,000 | Chunks every player starts with |
| `maxChunks` | `200` | 0–1,000,000 | Most chunks a player reaches by start quota, growth and buying |
| `maxClaims` | `5` | 0–10000 | Claims per player |
| `growthChunks` | `0` | 0–10000 | Chunks added per growth step. `0` = no growth |
| `growthEveryHours` | `5` | 1–10000 | Hours of active play time per growth step |
| `chunkTiers` | `[25, 50, 100, 200, 500, 1000]` | | Values tested for `ks.claims.chunks.<n>` |
| `claimTiers` | `[1, 2, 3, 5, 10, 20]` | | Values tested for `ks.claims.claims.<n>` |
| `bufferChunks` | `0` | 0–16 | Distance in chunks a new claim must keep to foreign claims. `0` = off |

How the quota of a player is worked out:

```
start   = highest ks.claims.chunks.<n> the player has, else startChunks
maximum = the larger of maxChunks and start
quota   = the smaller of maximum and (start + growth + bought) + bonus
claims  = highest ks.claims.claims.<n> the player has, else maxClaims
```

- **Growth:** `growthChunks` per `growthEveryHours` of play time. Only minutes in which the player moved at least one block count. The player gets a notice `Quota grew`.
- **Bought:** chunks bought with `/ksclaim buychunks`, only up to the maximum.
- **Bonus:** set by an admin (`/ksclaimadmin quota <player> bonus <n>` or **Change quota** in the admin window). It comes on top, also above the maximum.
- `ks.claims.chunks.unlimited` and `ks.claims.claims.unlimited` remove the limits. See [Permissions](./permissions#quota-tiers).
- **Distance to foreign land:** your own claims, claims where you have a role and guild land you may use do not count. Server zones do not count either. `/ksclaimadmin claimfor` ignores the distance.
- Tier lists keep only whole numbers from 1 to 1,000,000, sorted, without doubles.

---

## Economy

The economy is **off by default**. It only works when `enabled` is `true` and KyuubiSoft Core is installed with a currency its economy bridge can use. The start log shows `economy on` or `economy off`.

| Key | Default | Meaning |
|-----|---------|---------|
| `enabled` | `false` | Claiming costs money, released chunks are refunded, quota can be bought |
| `chunkCost` | `100.0` | Price of one claimed chunk |
| `worldChunkCosts` | `{}` | Price per world, for example `{"arena": 0, "world": 150}`. A missing world or a negative value uses `chunkCost` |
| `chunkUnclaimRefund` | `50.0` | Paid back per released chunk, at most what was paid for it |
| `purchaseChunkCost` | `500.0` | Price of one extra chunk of quota (`/ksclaim buychunks`) |

- The price is taken before the chunks are claimed. If claiming fails afterwards, the money is given back.
- Every paid chunk goes into the claim's cost book. Releasing a chunk or dissolving the claim refunds only chunks in the cost book. Chunks claimed while the economy was off, chunks given by `/ksclaimadmin claimfor` and chunks taken over from an older Claims version refund nothing.
- Handing a claim over empties its cost book: the new owner gets no refund for chunks the old owner paid.
- Negative prices count as `0`. In the admin window prices are whole numbers up to 10,000,000. Prices per world stay in the file.
- With the server currency [Kronen](https://wiki.kyuubisoft.com/hytale/core/kronen/) (Core 2.10.0, not released yet), every payment names its reason in the player's history, in the reader's language: `2 chunks bought`, `3 chunks of extra quota bought`, `Refund for 1 released chunk`, `Claim dissolved, refund for 2 chunks`. A different economy and an older Core are paid as before, without a reason.

---

## Abandoned claims (decay)

Abandoned claims are **off by default** (`days` = `0`): nothing expires.

| Key | Default | Range | Meaning |
|-----|---------|-------|---------|
| `days` | `0` | 0–3650 | Days without a login of the owner or a co-owner until the claim is dissolved. `0` = never |
| `warningDays` | `7` | 0–365 | Warning at login this many days before |
| `abandonedListDays` | `60` | 1–3650 | The admin filter **Abandoned** lists claims without activity for at least this many days |
| `enabledAt` | `0` | | Set by the server: when decay was switched on. Do not edit |

- A login of the owner or a co-owner keeps the claim alive. When they log in inside the warning time, they see `Your login keeps the claim alive.`. Trusted players see `Expires in 5 days unless the owner or a co-owner logs in.`
- When decay is switched on, the countdown starts at that moment for every claim, so quiet claims are not dissolved at once.
- Expired claims are dissolved once an hour. Blocks stay, the log stays for `log.keepDays`.
- The **Abandoned** filter of the admin window works also while `days` is `0`.

---

## Home

| Key | Default | Range | Meaning |
|-----|---------|-------|---------|
| `warmupSeconds` | `3` | 0–120 | Seconds of standing still before the trip. `0` = at once |
| `cooldownSeconds` | `10` | 0–3600 | Seconds until the next trip |
| `cancelDistance` | `1.0` | 0.1–32 | Moving farther than this (blocks) cancels the warmup |

Getting hurt, changing worlds and logging out cancel the warmup too.

---

## Protection

These switches apply to every claim. In the admin window they are under **Protection for every claim**.

| Key | Default | In the admin window | Meaning |
|-----|---------|---------------------|---------|
| `explosions` | `true` | Stop explosions | Explosions break nothing in claims, unless the claim switches **Explosions damage blocks** on. `false`: explosions break blocks in every claim. Server zones keep their own explosion rule either way |
| `creatures` | `true` | Creatures break nothing | Creatures do not break, place or use blocks in claims and server zones |
| `attach` | `true` | Prevent attaching | Nobody places a chest next to a container, or a door next to a door, that they may not use |
| `underContainers` | `true` | Protect what is below | The block under a container that reaches across a chunk border is protected like the container |
| `benches` | `true` | Workbenches ask the claim | Nobody uses or places a workbench within its reach of containers they may not open |
| `fireOnlyAllowed` | `true` | Only people with rights light fires | In claims with **Fire only with the build right** on, lighting a fire needs the right to build. `false`: everyone who is not banned may light fires in claims |
| `denyMessages` | `true` | Message on a refusal | A notice at the top and one chat line when something is refused |
| `denyCooldownSeconds` | `3` | Refusal message | At most one refusal message per player in this many seconds (0–60) |
| `allowFly` | `false` | Allow flying in claims | Owners and co-owners may fly in their claims, and a claim can allow it for trusted players with **Flying for trusted people** |
| `allowKeepInventory` | `false` | Allow keeping the inventory | Claims can switch on **Keep inventory on death** |
| `useExceptions` | `["gravestone", "mailbox"]` | Exceptions · Use | Blocks whose ID contains one of these words may be used by everybody, also in claims and server zones |
| `breakExceptions` | `[]` | Exceptions · Break | Blocks whose ID contains one of these words may be broken by everybody |

- Exception words are compared without case. In the admin window a word has 2 to 40 letters, digits or `_`.
- Refused actions are always written to the claim log, also with `denyMessages` off.
- Fire that spreads by itself, flowing water and lava, and picking up items by walking over them cannot be stopped.

---

## Display

| Key | Default | Range | Meaning |
|-----|---------|-------|---------|
| `enterToastCooldownSeconds` | `10` | 0–600 | The notice for entering a claim or server zone shows at most once per this many seconds per player and place |
| `borderSeconds` | `10` | 1–120 | How long the border glows (**Show border**, `/ksclaim border`, **Border when entering**) |
| `mapTerrain` | `true` | `true`/`false` | The map in the claims window shows the terrain of the world map under the claims (4 × 4 colours per chunk). `false` = the flat map without terrain. Only in the config file, not in the admin window |

---

## Log

| Key | Default | Range | Meaning |
|-----|---------|-------|---------|
| `keepDays` | `30` | 1–365 | Days a log line is kept, also after the claim is dissolved |
| `maxEntriesPerClaim` | `500` | 10–10000 | Most lines per claim |
| `mergeSeconds` | `60` | 0–3600 | The same refusal by the same person within this many seconds becomes one line with a count |

---

## Other files

| File | Content |
|------|---------|
| `claims/<claim id>.json` | One file per claim |
| `zones.json` | Server zones |
| `players.json` | Quota parts, play time and the last known name of every player |
| `logs/<claim id>.json` | The log of a claim |
| `localization/<area>/<language>.json` | Texts, see [Getting Started](./getting-started#8-languages) |
| `config-1.x.json`, `claims-1.x.db`, `migration-report.txt` | Only after taking over an older Claims version, see [Getting Started](./getting-started#3-coming-from-an-older-claims-version) |

Every file is written to a temporary file first and then moved into place, so a crash never leaves half a file.