# Configuration

**Version:** 1.0.0

Guilds is configured in `mods/kyuubisoft_guilds/config.json`. The file is written with the default values on the first start.

- **Most options are also in the admin window** (`/ksguild admin`, sections **Levels** and **Rules**, **Names** for the word lists). Changes there apply at once and are written to the file right away.
- **The file is read when the server starts.** There is no reload command. Edit the file while the server is stopped; a change made in the admin window later writes the whole file again.
- **Values out of range are repaired** at the start (for example a negative limit or a level table with gaps), so a hand-edited file never stops the mod. The ranges are listed below.

---

## Overview

```json
{
  "configVersion": 1,
  "general": { ... },
  "levels": { "enabled": true, "table": [ ... ], "fixed": { ... }, "bonusEnabled": false, "bonuses": [ ... ] },
  "experience": { ..., "farmBrake": { ... } },
  "locks": { ... },
  "lager": { ... },
  "home": { ... },
  "combat": { ... },
  "integration": { ... },
  "defaultRights": { ... }
}
```

`configVersion` is managed by the mod; leave it as it is.

---

## General

Names, tags, invitations and the word filter. In the admin window: **Rules** → **Guilds**, and **Names**.

| Option | Default | Range | Meaning |
|--------|---------|-------|---------|
| `general.nameMin` | `3` | 1–48 | Shortest guild name |
| `general.nameMax` | `24` | `nameMin`–48 | Longest guild name |
| `general.tagMin` | `2` | 1–8 | Shortest tag |
| `general.tagMax` | `4` | `tagMin`–8 | Longest tag |
| `general.rankNameMax` | `16` | 1–32 | Longest name a guild can give a rank |
| `general.announcementMax` | `200` | 1–1000 | Longest announcement |
| `general.homeLabelMax` | `24` | 1–48 | Longest label of a guild home |
| `general.inviteMinutes` | `10` | 1–1440 | How long an invitation is valid, in minutes |
| `general.foundingFee` | `0` | 0 or more | Price for founding a guild. `0` = free. See [Economy options](#economy-options) |
| `general.wordFilter` | `admin`, `moderator`, `server`, `kyuubisoft`, `support`, `team`, `offiziell`, `staff` | list | Names, tags, rank names and announcements that contain one of these words are refused. Part of a word counts, upper and lower case do not matter |
| `general.reservedTags` | `ADM`, `MOD`, `KS`, `GM`, `DEV` | list | Tags no guild can take |

Guild names may contain letters, digits, spaces and `' - . &`. Tags contain only letters and digits and are written in capitals. Names and tags are unique, without regard to upper and lower case.

---

## Levels

In the admin window: **Levels**.

| Option | Default | Meaning |
|--------|---------|---------|
| `levels.enabled` | `true` | The level system. Off: every guild gets the fixed limits below, all colours and crest symbols and the Veteran rank, and material can no longer be handed in |
| `levels.table` | 10 levels | The level table, see below |
| `levels.fixed.members` | `30` | Member slots when the level system is off (1–500) |
| `levels.fixed.guildLocks` | `200` | Guild locks per guild when the level system is off |
| `levels.fixed.lagerPages` | `3` | Storage pages when the level system is off (0–20) |
| `levels.fixed.homes` | `1` | Guild homes when the level system is off (0–2) |
| `levels.bonusEnabled` | `false` | Level bonuses, see [Economy options](#economy-options) |
| `levels.bonuses` | `[{ "fromLevel": 5, "xpPercent": 10 }]` | The bonus rows; only used while `bonusEnabled` is `true` |

Switching the level system off keeps the table saved. Guilds keep their level and experience.

### The level table

A guild reaches the next level when its **total experience** has reached the level's threshold **and** all of the level's **building material** is handed in. A guild never loses a level by itself.

| Level | Experience | Building material | Members | Storage pages | Guild locks | Adds |
|------:|-----------:|-------------------|--------:|--------------:|------------:|------|
| 1 | 0 | – | 10 | 1 | 50 | Colours gold, red, orange, yellow, green, teal, blue, grey, brown; crests moon, star, sword, tree, flame |
| 2 | 2,000 | – | 15 | 1 | 75 | Guild home, colour white |
| 3 | 6,000 | `Wood_Oak_Trunk` × 200 | 20 | 2 | 100 | Crests wave, mountain |
| 4 | 12,000 | `Wood_Oak_Trunk` × 300, `Ingredient_Bar_Iron` × 100 | 25 | 3 | 150 | Colours violet, pink |
| 5 | 25,000 | `Wood_Oak_Trunk` × 500, `Ingredient_Bar_Iron` × 200, `Rock_Stone` × 1,000 | 30 | 4 | 200 | Crest crown |
| 6 | 40,000 | `Rock_Stone` × 800, `Ingredient_Bar_Iron` × 300 | 32 | 4 | 225 | Rank Veteran |
| 7 | 60,000 | `Rock_Stone` × 1,000, `Ingredient_Bar_Gold` × 400 | 34 | 5 | 250 | Second guild home |
| 8 | 85,000 | `Ingredient_Bar_Gold` × 200, `Rock_Gem_Diamond` × 50 | 36 | 5 | 275 | Silver crest frame |
| 9 | 115,000 | `Ingredient_Bar_Gold` × 500, `Rock_Gem_Diamond` × 100 | 38 | 6 | 300 | Gold crest frame |
| 10 | 150,000 | `Rock_Gem_Diamond` × 250, `Ingredient_Fire_Essence` × 50 | 40 | 6 | 300 | Hall of fame (highlighted in the list of all guilds) |

Each storage page has 36 slots. What a row adds (colours, crests, homes, the Veteran rank, frames, hall of fame) stays for every higher level.

One row in the file:

```json
{
  "level": 3,
  "xp": 6000,
  "materials": [ { "item": "Wood_Oak_Trunk", "amount": 200 } ],
  "members": 20,
  "lagerPages": 2,
  "guildLocks": 100,
  "homes": 0,
  "veteranRank": false,
  "colors": [],
  "symbols": [ "wave", "mountain" ],
  "frame": "",
  "hallOfFame": false
}
```

| Field | Meaning |
|-------|---------|
| `level` | Level number. Rows are sorted and numbered 1, 2, 3, ... without gaps; at most 50 levels |
| `xp` | Total guild experience for this level. Level 1 is always `0`; a lower value than the level before is raised |
| `materials` | Item id and amount (1 to 1,000,000) to hand in before this level is reached |
| `members` | Member slots (1–500) |
| `lagerPages` | Storage pages (0–20) |
| `guildLocks` | Guild locks the guild may own |
| `homes` | Guild homes from this level (0–2) |
| `veteranRank` | The Veteran rank is active from this level |
| `colors`, `symbols` | Colours and crest symbols added at this level. Unknown ids are dropped |
| `frame` | Crest frame from this level: `""`, `"silver"` or `"gold"` |
| `hallOfFame` | Highlight in the list of all guilds from this level |

Colour ids: `gold`, `red`, `orange`, `yellow`, `green`, `teal`, `blue`, `violet`, `pink`, `white`, `grey`, `brown`. Crest ids: `moon`, `star`, `sword`, `tree`, `flame`, `wave`, `mountain`, `crown`.

In the admin window, click a row of the table to change experience, slots, storage pages, guild locks, the experience bonus from that level and the materials (picked from the item list).

---

## Experience

In the admin window: **Levels** → **Experience for the guild** and **Against farming**.

### Sources

| Option | Default | Experience for |
|--------|---------|----------------|
| `experience.creature` | `2` | A creature the world spawned, defeated by a member |
| `experience.boss` | `50` | A boss (a creature whose role id contains an entry of `bosses`) |
| `experience.ore` | `1` | An ore block nobody placed, mined by a member |
| `experience.quest` | `25` | A finished quest (with KyuubiSoft Quests) |
| `experience.achievement` | `40` | An unlocked achievement (with KyuubiSoft Achievements) |
| `experience.playtime` | `5` | Every `playtimeMinutes` minutes of play with movement |
| `experience.playtimeMinutes` | `10` | Minutes of play with movement for one play time award (1–1440) |

Values go from 0 to 100,000; `0` switches a source off.

- **Creatures** count when a member defeats them with a hit or an arrow, or when a pet's hit is booked on its owner. Only creatures the world spawned count: natural spawns, spawn markers, spawn beacons and world generation. Creatures from spawn eggs, commands or other mods do not, and players never do.
- **Ores** are blocks tagged as ore, gathered as ore, or with an id starting with `Ore_`. Ore blocks a player placed are remembered (folder `placed-ores/`) and earn nothing when mined.
- **Play time** is sampled once a minute. A minute counts when the player moved at least `playtimeMinMove` blocks since the last sample. The minutes need not be in a row; logging out starts over.

### Lists

| Option | Default | Meaning |
|--------|---------|---------|
| `experience.bosses` | `goblin_duke`, `goblin_ogre`, `dragon_fire`, `dragon_frost`, `golem_guardian_void`, `scarak_broodmother`, `trork_chieftain`, `shadow_knight`, `zombie_aberrant_big` | A creature whose role id contains one of these counts as a boss |
| `experience.ignoredCreatures` | `tamed_`, `temple_`, `edible_`, `quest_master`, `ks_pet_`, `ks_mount_`, `ks_npc_`, `ks_path_` | A creature whose role id contains one of these never counts (tamed animals, temple and quest creatures, pets and NPCs of KyuubiSoft mods) |

These lists are only in the file, not in the admin window.

### Anti-farm settings

| Option | Default | Meaning |
|--------|---------|---------|
| `experience.dailyCapPerMember` | `500` | Experience one member can earn for the guild per day. The day starts at 00:00 server time |
| `experience.newMemberDelayHours` | `24` | New members only earn experience after this many hours in the guild (0–720). Joining again starts the wait again |
| `experience.playtimeMinMove` | `1.5` | Blocks a player has to move between two play time samples for the minute to count (0–64) |
| `experience.farmBrake.radius` | `8` | Blocks around a spot that count as the same farm (0–128) |
| `experience.farmBrake.windowSeconds` | `120` | How long counts stay in the farm history |
| `experience.farmBrake.freeKills` | `20` | Creatures within `radius` and `windowSeconds` that count in full |
| `experience.farmBrake.freeOres` | `60` | Ore blocks within `radius` and `windowSeconds` that count in full |
| `experience.farmBrake.keepEvery` | `4` | After the free counts, only every n-th one still counts. `1` switches the farm brake off |

- Bosses are never slowed down by the farm brake.
- Quests, achievements and play time also count against the daily limit.
- `dailyCapPerMember`, `newMemberDelayHours` and `playtimeMinutes` are in the admin window. The farm brake and `playtimeMinMove` are only in the file.
- The weekly ranking on the **Level** tab ("This week") starts on Monday at 00:00 server time.

---

## Locks

In the admin window: **Rules** → **Locks** and **Limits for locks**.

| Option | Default | Meaning |
|--------|---------|---------|
| `locks.containers` | `true` | Containers can be locked (chests, barrels, cupboards, crates) |
| `locks.doors` | `true` | Doors and gates can be locked, double doors too |
| `locks.explosions` | `true` | Locked blocks, and the blocks they stand on, take no damage from explosions. It does not help against fire |
| `locks.surroundings` | `true` | The block below a lock is protected like the lock, and strangers cannot place a chest or door of the same kind right next to a foreign lock |
| `locks.benchesAskLock` | `true` | A workbench with a locked container in its reach can only be used, or set down there, by players who may open that container |
| `locks.autoLockAllowed` | `true` | Players may lock new chests and doors automatically when they place them |
| `locks.privatePerPlayer` | `50` | Private locks per player |
| `locks.expiryDays` | `0` | Days without a visit after which a lock falls away. Private locks count from when the owner was last seen on the server, guild locks from the guild's last activity. `0` = never (0–3650) |
| `locks.denyMessageSeconds` | `3` | At most one "Locked" message per player and lock in this many seconds (0–60) |

The number of guild locks comes from the level table (or `levels.fixed.guildLocks`). A double chest or a double door counts once.

---

## Guild storage

In the admin window: **Rules** → **Guild storage · taking out per day**.

| Option | Default | Meaning |
|--------|---------|---------|
| `lager.dailyWithdraw.LEADER` | `-1` | Items the leader may take out per day. `-1` = no limit |
| `lager.dailyWithdraw.OFFICER` | `256` | Per day for Officers |
| `lager.dailyWithdraw.VETERAN` | `128` | Per day for Veterans |
| `lager.dailyWithdraw.MEMBER` | `64` | Per day for Members |
| `lager.dailyWithdraw.NOVICE` | `0` | Per day for Novices |
| `lager.logDays` | `30` | Days the storage log keeps its entries (1–365) |

The limit counts single items. Taking out also needs the rank right **Take items from the guild storage**. The number of pages comes from the level table.

---

## Guild home

In the admin window: **Rules** → **Combat and guild home** and **Trip to the guild home**.

| Option | Default | Meaning |
|--------|---------|---------|
| `home.enabled` | `true` | Guilds can set a home and travel there |
| `home.warmupSeconds` | `5` | Seconds of standing still before the trip (0–120) |
| `home.cooldownSeconds` | `600` | Seconds until the same player can travel again (0–86400) |
| `home.cancelDistance` | `1.0` | Moving further than this many blocks during the warm-up cancels the trip (0.1–16). Only in the file |

---

## Combat

| Option | Default | Meaning |
|--------|---------|---------|
| `combat.friendlyFireSettingAllowed` | `true` | Guilds may switch on "No damage between members". Off: members can hurt each other in every guild |

New guilds start with "No damage between members" switched on. The leader changes it on the **Settings** tab.

---

## Integration

| Option | Default | Meaning |
|--------|---------|---------|
| `integration.voiceChannel` | `true` | With KyuubiSoft VoiceHub 2.0.3 or newer, every guild gets its own voice channel, only for its members. Off: the guild channels are removed within a minute |

The channel is named "Guild: <name>" in the server language and follows renames.

---

## Default rank rights

`defaultRights` sets which rights each rank gets in a **newly founded** guild. Existing guilds keep their own table, which the leader changes on the **Ranks** tab. The leader always has every right, whatever the file says.

```json
"defaultRights": {
  "OFFICER": [ "INVITE", "ACCEPT_REQUESTS", "KICK", "PROMOTE", "ANNOUNCE", "LOCK", "MANAGE_LOCKS",
               "LAGER_DEPOSIT", "LAGER_WITHDRAW", "HOME_USE" ],
  "VETERAN": [ "INVITE", "LOCK", "LAGER_DEPOSIT", "LAGER_WITHDRAW", "HOME_USE", "ACCEPT_REQUESTS" ],
  "MEMBER":  [ "INVITE", "LOCK", "LAGER_DEPOSIT", "LAGER_WITHDRAW", "HOME_USE" ],
  "NOVICE":  [ "LAGER_DEPOSIT", "HOME_USE" ]
}
```

| Id | Right in the window |
|----|---------------------|
| `INVITE` | Invite members |
| `ACCEPT_REQUESTS` | Accept join requests |
| `KICK` | Remove lower ranks |
| `PROMOTE` | Promote and demote, up to below their own rank |
| `ANNOUNCE` | Write the announcement |
| `LOCK` | Lock chests and doors for the guild |
| `MANAGE_LOCKS` | Change and remove other members' guild locks |
| `LAGER_DEPOSIT` | Put items into the guild storage |
| `LAGER_WITHDRAW` | Take items from the guild storage |
| `HOME_USE` | Travel to the guild home |
| `HOME_SET` | Set the guild home |
| `LAND` | Manage guild land |

The file also contains a `LEADER` entry with every right; it is informative only.

---

## Economy options

Both are **off by default**. Turn them on in the admin window or in the file.

| Option | Default | Meaning |
|--------|---------|---------|
| `general.foundingFee` | `0` | Founding a guild costs this amount. It is only charged when a currency is connected through KyuubiSoft Core; without one, founding stays free whatever the value is. If founding fails after the fee was taken, it is given back. The **Found a guild** tab shows the price |
| `levels.bonusEnabled` | `false` | Level bonuses: a guild gets extra experience from a level on |
| `levels.bonuses` | `fromLevel 5`, `xpPercent 10` | Each row: from `fromLevel` on, the guild gets `xpPercent` % on top of what its members earn (0–1000 %). The highest row the guild has reached counts. Only works while the level system is on |

The bonus is added on top of what counted for the member, so it is not limited by the member's daily cap. In the admin window, set it per level in the level editor (**Experience bonus from here**).

---

## Languages

The texts of all windows, commands and messages are in `mods/kyuubisoft_guilds/localization/<area>/<language>.json` (areas `admin`, `core`, `crossmod`, `integration`, `protect`, `ui`; languages `en`, `de`, `es`, `fr`, `it`, `pl`, `pt-BR`, `ru`, `tr`). Missing files are written at the start. When a newer version brings newer texts, the file is replaced and your old one is kept as `<language>.json.backup-v<old version>`.

Each player's language comes from `/kslang`, which all KyuubiSoft mods share.