> ## 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.

# Passives Configuration

> How to configure RPG Leveling passives - PassivesConfig.json, tiers, triggers, and display names.

# Passives Configuration

Passives are **per-class abilities** that unlock by tier (T0–T4) and trigger in combat (e.g. on damage dealt, damage taken, or on kill). You can add, remove, or edit passives and assign them to any class.

## Config location

* **Passives definitions:** `mods/Zuxaw_RPGLeveling/Classes/PassivesConfig.json`
* **Which passives a class has:** In each class file, the `Passives` array (e.g. `["HighGuard", "ThickSkin", "Overkill"]`)
* **Display names and descriptions:** Overridable via [MessagesLanguageMapping](config-messages); keys follow the passive id (lowercase, e.g. `highguard`, `thickskin`)

## PassivesConfig.json structure

* **Passives** - Array of passive objects. Each has:
  * **Id** - Unique id (e.g. `"HighGuard"`). Referenced in class `Passives` arrays.
  * **Unlock** - Tier at which this passive unlocks (0–4).
  * **T** - Tiered values (keys `"0"`–`"4"`). Each tier can define different numbers (e.g. `DamagePercent`, `ChancePercent`, `HpThresholdPercent`, `DurationSeconds`). The mod uses these when resolving the passive effect at a given class tier.

## Adding or swapping passives

* **Add a passive:** Add a new object to `PassivesConfig.json` with `Id`, `Unlock`, and `T`. Add its `Id` to a class’s `Passives` array in the class JSON (and to the tier where it should appear).
* **Swap passives on a class:** Edit the class’s `Passives` array: remove one passive id and add another (the new id must exist in `PassivesConfig.json`).
* **Remove a passive:** Remove it from every class that uses it, then you can delete or leave the definition in `PassivesConfig.json` (unused passives are simply not used).

## Triggers

Passives are checked by the mod when:

* **Damage dealt** - Player hits a target (e.g. damage bonus when HP above/below threshold, lifesteal, opening strike).
* **Damage taken** - Player is hit (e.g. chance to heal on hit when low HP).
* **On kill** - Player kills an entity (e.g. movement speed buff).

The exact trigger for each passive is hardcoded by passive id; config only supplies the numeric values per tier.

## PassivesConfig.json root structure

The file is a single JSON object with a **Version** and a **Passives** array. Each element of **Passives** is one passive definition.

```json theme={null}
{
  "Version": "0.3.2",
  "Passives": [
    { ... },
    { ... }
  ]
}
```

## Full passive examples

Each passive has **Id**, **Unlock** (tier 0–4 at which it becomes available), and **T** (tiered values). The keys inside each `"0"`–`"4"` object depend on the passive (e.g. `DamagePercent`, `ChancePercent`, `HpThresholdPercent`, `DurationSeconds`, `HealPercent`, `CooldownSeconds`). Higher tiers often override or add to lower-tier values.

### Example: damage-based passive (HighGuard)

Bonus damage when the player is above an HP threshold. Uses `DamagePercent` and `HpThresholdPercent`.

```json theme={null}
{
  "Id": "HighGuard",
  "Unlock": 0,
  "T": {
    "0": { "DamagePercent": 5.0, "HpThresholdPercent": 70.0 },
    "1": { "DamagePercent": 10.0 },
    "2": { "DamagePercent": 15.0 },
    "3": { "DamagePercent": 20.0 },
    "4": { "DamagePercent": 25.0 }
  }
}
```

### Example: chance + heal (ThickSkin)

Chance to heal when hit, below an HP threshold. Uses `ChancePercent`, `HealPercent`, `HpThresholdPercent`. Later tiers increase chance and heal amount.

```json theme={null}
{
  "Id": "ThickSkin",
  "Unlock": 1,
  "T": {
    "0": { "ChancePercent": 15.0, "HealPercent": 80.0, "HpThresholdPercent": 40.0 },
    "1": { "ChancePercent": 25.0 },
    "2": { "ChancePercent": 35.0, "HealPercent": 100.0 },
    "3": { "ChancePercent": 50.0, "HealPercent": 120.0 },
    "4": { "ChancePercent": 65.0, "HealPercent": 150.0 }
  }
}
```

### Example: on-kill buff (Overkill)

On kill, consume stamina and grant a short speed buff. Uses `StaminaPercent`, `SpeedPercent`, `DurationSeconds`.

```json theme={null}
{
  "Id": "Overkill",
  "Unlock": 2,
  "T": {
    "0": { "StaminaPercent": 50.0, "SpeedPercent": 25.0, "DurationSeconds": 2.0 },
    "1": { "StaminaPercent": 60.0, "SpeedPercent": 28.0 },
    "2": { "StaminaPercent": 75.0, "SpeedPercent": 35.0 },
    "3": { "StaminaPercent": 80.0, "SpeedPercent": 50.0 },
    "4": { "StaminaPercent": 85.0, "SpeedPercent": 65.0 }
  }
}
```

### Example: complex passive (LastStand)

Low-HP defensive buff with damage reduction, lifesteal, duration and cooldown. Uses `HpThresholdPercent`, `ReductionPercent`, `LifestealPercent`, `DurationSeconds`, `CooldownSeconds`.

```json theme={null}
{
  "Id": "LastStand",
  "Unlock": 2,
  "T": {
    "0": {
      "HpThresholdPercent": 20.0,
      "ReductionPercent": 20.0,
      "LifestealPercent": 10.0,
      "DurationSeconds": 4.0,
      "CooldownSeconds": 60.0
    },
    "1": { "ReductionPercent": 25.0, "LifestealPercent": 12.0 },
    "2": { "ReductionPercent": 30.0, "LifestealPercent": 15.0 },
    "3": { "ReductionPercent": 35.0, "LifestealPercent": 18.0 },
    "4": { "ReductionPercent": 40.0, "LifestealPercent": 18.0 }
  }
}
```

You do not need to repeat every key in every tier; the mod merges or uses defaults for missing keys. Add a new passive by appending an object like the above to the **Passives** array, then reference its **Id** in a class's **Passives** array.

## Minimal passive example

Minimal definition for a simple passive (e.g. flat damage bonus). All five tier keys (`"0"`–`"4"`) should be present if the passive scales with class tier.

```json theme={null}
{
  "Id": "MyCustomPassive",
  "Unlock": 0,
  "T": {
    "0": { "DamagePercent": 5.0 },
    "1": { "DamagePercent": 8.0 },
    "2": { "DamagePercent": 12.0 },
    "3": { "DamagePercent": 16.0 },
    "4": { "DamagePercent": 20.0 }
  }
}
```

The exact keys (e.g. `DamagePercent`) are defined by the mod per passive id; config only supplies the numeric values per tier.

## Names and localization

Use **MessagesLanguageMapping** to override passive names and descriptions without editing JSON. Keys are the passive id in lowercase (e.g. `highguard`). This lets you localize or rename passives for your server.