# Configuration

# Configuration

:::caution[In development]
This page describes the current development build (4.4.3). Files and keys can still change before release.
:::

KS Dungeons keeps its files in the mod's data folder: `config.json`, the biome files and the loot tables.

## File Structure

```
config.json              — Main configuration
biomes/
  stone_caves.json
  forest_ruins.json
  desert_tombs.json
  frozen_crypts.json
  lava_depths.json
  void_sanctum.json
loot/
  <biome>.json           — Loot table per biome
  <biome>_boss.json      — Boss loot table per biome
  boss_common.json
localization/
  en-US.json
  de-DE.json
```

## config.json

```json
{
  "dungeon": {
    "maxPartySize": 4,
    "defaultTeamLives": 3
  },
  "cooldown": {
    "defaultMinutes": 30
  },
  "permissions": {
    "adminPermission": "kyuubisoft.dungeons.admin"
  },
  "mapDrops": {
    "chance": 0.05,
    "defaultLevel": 5
  },
  "stoneDrops": {
    "chance": 0.02
  }
}
```

| Key | Default | Description |
|-----|---------|-------------|
| `dungeon.maxPartySize` | `4` | Maximum party size |
| `dungeon.defaultTeamLives` | `3` | Team lives at Normal difficulty; Easy adds 2, Hard removes 1, Heroic removes 2 (at least 1) |
| `cooldown.defaultMinutes` | `30` | Biome cooldown after a completed run (shown in the browser, not enforced yet) |
| `permissions.adminPermission` | `kyuubisoft.dungeons.admin` | Extra node checked by the admin commands; see [Permissions](./permissions) |
| `mapDrops.chance` | `0.05` | Chance per open-world mob kill to drop a dungeon map (0.05 = 5 %) |
| `mapDrops.defaultLevel` | `5` | Map level when the mob's level cannot be read |
| `stoneDrops.chance` | `0.02` | Chance per mob kill to drop a crafting stone |

The shipped file does not contain `mapDrops` and `stoneDrops`; add these blocks to change the defaults. It does contain `dungeon.defaultFloors`, `dungeon.reconnectWindowSeconds`, `dungeon.roomClearPercentForStairs` and a `performance` block. They are left over from earlier builds and have no effect.

## Biome Files

Each biome file defines one biome:

| Field | Description |
|-------|-------------|
| `id`, `displayName`, `color` | ID, name and colour shown in maps and the browser |
| `instanceTemplate` | The arena world template |
| `environmentId` | The world environment used in the arena |
| `terrainMaterials` | Block materials for the arena terrain |
| `centerAnchor`, `bossArena` | Prefabs placed at the center and for the boss arena |
| `structures` | Prefabs scattered across the arena |
| `regularMobs` | Mob pool, each entry with an NPC `role` and a `weight` |
| `bossMobs` | NPC roles that spawn as bosses |
| `lootTableId` | The biome's loot table |

Example from `stone_caves.json`: the regular pool includes `Skeleton_Knight` (weight 25) and `Skeleton_Soldier` (weight 20); the boss is `Skeleton_Praetorian`.

:::note
Hytale 0.7 renamed some vanilla NPC roles (for example `Spectre_Void` → `Void_Spectre`). Biome files that were already extracted on your server are mapped to the new names automatically while loading.
:::

## Loot Tables

Loot tables ship for every biome and its boss. In this build they are loaded but not handed out yet: a completed run gives tokens, and bosses drop dungeon maps.