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

# Instance Level Config

> InstanceLevelConfig.json - Instance/dungeon level mapping and entity overrides.

# Instance Level Config

**File:** `mods/Zuxaw_RPGLeveling/InstanceLevelConfig.json`

This file defines **level ranges and entity overrides for instances and dungeons** - places where zone/biome are unknown (e.g. instanced dungeons). When a player or mob is in such a world, the plugin uses this config for:

* **Mob level calculation** - Monsters get levels within the instance's `LevelMin`–`LevelMax` range
* **HUD display** - The HUD shows the instance id and level range (e.g. *"Yungs\_HyDungeons\_Skeleton\_Dungeon (Lvl 55–75)"*) and uses the same color logic as zones (green/white/orange/red by level gap)
* **XP and entity overrides** - Per-instance entity overrides (e.g. boss level/XP) are checked first; global `ZoneLevelConfig` entity overrides are used as fallback

***

## Instance Configuration Fields

Instances are defined under the top-level `Instances` array with PascalCase keys:

| Field             | Type    | Description                                                                                                                                                                                                           |
| ----------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Id`              | String  | Full instance id (e.g. `Yungs_HyDungeons_Skeleton_Dungeon`). Used for lookup and HUD display; the game may return a longer name - the plugin still matches by this id.                                                |
| `LevelMin`        | Integer | Minimum monster level for this instance.                                                                                                                                                                              |
| `LevelMax`        | Integer | Maximum monster level for this instance.                                                                                                                                                                              |
| `EntityOverrides` | Array   | Per-entity overrides for this instance only (same structure as ZoneLevelConfig: `EntityId`, `Level`, `DisableLevelScaling`, `XP`). Instance overrides take precedence over global `ZoneLevelConfig` entity overrides. |

***

## Entity Override Fields

Per-instance entity overrides use the same structure as [ZoneLevelConfig](config-zones):

| Field                 | Type              | Description                                                |
| --------------------- | ----------------- | ---------------------------------------------------------- |
| `EntityId`            | String            | NPC type ID (e.g. `Skeleton_Boss`)                         |
| `Level`               | Integer           | Fixed level for this entity                                |
| `DisableLevelScaling` | Boolean           | If `true`, ignore all bonus stats per level                |
| `XP`                  | Double (optional) | Precise XP amount to award (still multiplied by `RateExp`) |

**Priority:** Instance entity overrides > Global zone entity overrides.

***

## Example Config

```json theme={null}
{
  "Version": "0.2.0",
  "Instances": [
    {
      "Id": "default",
      "LevelMin": 1,
      "LevelMax": 25,
      "EntityOverrides": []
    },
    {
      "Id": "Yungs_HyDungeons_Skeleton_Dungeon",
      "LevelMin": 55,
      "LevelMax": 75,
      "EntityOverrides": [
        {
          "EntityId": "Skeleton_Boss",
          "Level": 80,
          "DisableLevelScaling": false,
          "XP": 8000.0
        }
      ]
    },
    {
      "Id": "Yungs_HyDungeons_Dragon_Lair",
      "LevelMin": 85,
      "LevelMax": 100,
      "EntityOverrides": [
        {
          "EntityId": "Dragon_Ancient",
          "Level": 150,
          "DisableLevelScaling": true,
          "XP": 50000.0
        }
      ]
    }
  ]
}
```

***

## Adding a New Dungeon

To add a dungeon or modded instance:

1. Find the **instance id** - Check the HUD when inside the dungeon, or look at server logs
2. Add an entry with the **Id**, **LevelMin**, and **LevelMax**
3. Optionally add **EntityOverrides** for bosses or special NPCs

**Example:**

```json theme={null}
{
  "Id": "MyMod_CustomDungeon",
  "LevelMin": 40,
  "LevelMax": 60,
  "EntityOverrides": [
    {
      "EntityId": "CustomDungeon_FinalBoss",
      "Level": 70,
      "DisableLevelScaling": false,
      "XP": 15000.0
    }
  ]
}
```

***

## Default Instance

The `default` instance is used when the plugin cannot determine the specific instance:

```json theme={null}
{
  "Id": "default",
  "LevelMin": 1,
  "LevelMax": 25,
  "EntityOverrides": []
}
```

This provides fallback level ranges for unknown instances.

***

## HUD Display

The HUD shows the instance name and level range with color coding:

| Color                     | Meaning                 | XP       | Action                      |
| ------------------------- | ----------------------- | -------- | --------------------------- |
| **White**                 | Too easy (−26+ levels)  | 10%      | Move to harder content      |
| **Green**                 | Good match (±25 levels) | 100–150% | **Stay here**               |
| **Orange / Red / Purple** | Too hard (+26+ levels)  | 20–50%   | Come back when higher level |

**Example HUD display:** `Yungs_HyDungeons_Skeleton_Dungeon (Lvl 55–75)` in green text.

***

## Monster Level Variation

Just like zones, monsters in instances have **±5 level variation** around their base level for variety.

***

## Use Cases

### Dungeon with Boss Override

Set a skeleton dungeon with a level 80 boss:

```json theme={null}
{
  "Id": "Yungs_HyDungeons_Skeleton_Dungeon",
  "LevelMin": 55,
  "LevelMax": 75,
  "EntityOverrides": [
    {
      "EntityId": "Skeleton_Boss",
      "Level": 80,
      "DisableLevelScaling": false,
      "XP": 8000.0
    }
  ]
}
```

### High-Level End-Game Dungeon

Create an extreme difficulty dungeon with a level 150 boss:

```json theme={null}
{
  "Id": "EndGame_UltimateDungeon",
  "LevelMin": 95,
  "LevelMax": 100,
  "EntityOverrides": [
    {
      "EntityId": "UltimateBoss",
      "Level": 150,
      "DisableLevelScaling": true,
      "XP": 100000.0
    }
  ]
}
```

***

## See Also

* [Configuration Overview](config-overview) - All config files
* [Zone Config](config-zones) - Zone level mapping
* [Dungeon Mod Setup](dungeon-mod-setup) - Step-by-step guide for dungeons
* [Override entity xp and level](override-for-mod) - Override entities from any mod