# Progression Instances

Progression instances are individual progression tracks that can be assigned to characters. Each instance references a leveling entry for its XP curve and defines rewards that trigger at specific levels.

## Creating a Progression Instance Entry

Open the Spark Editor, go to **Progression > Progression Instances** and click **Create New**.

Each progression instance defines:

| Field                    | Description                                                                                                   |
| ------------------------ | ------------------------------------------------------------------------------------------------------------- |
| Display Name             | Name for this progression track (e.g., "Character Level", "Crafting Skill", "Fishing").                       |
| Leveling Template        | Reference to a Leveling entry that defines the XP curve for this progression.                                 |
| Allow Runtime Assignment | Whether this progression can be assigned to characters during gameplay (default: true).                       |
| Default Unlocked         | If enabled, this progression is automatically unlocked for all characters on initialization (default: false). |
| Level Up Rewards         | List of rewards that trigger at specific levels (see below).                                                  |

## Level Up Rewards

Each level up reward fires triggers when the character reaches certain levels. Add as many rewards as needed.

| Field       | Description                                                            |
| ----------- | ---------------------------------------------------------------------- |
| Reward Type | When this reward triggers. See reward types below.                     |
| Description | Player-readable description of the reward.                             |
| Triggers    | List of trigger entries to execute when the reward conditions are met. |

### Reward Types

| Type           | Description                                           | Extra Fields                                                                                                                                                 |
| -------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Any Level      | Triggers on every level up.                           | None.                                                                                                                                                        |
| Specific Level | Triggers when the character reaches a specific level. | **Required Level** — the target level.                                                                                                                       |
| Every X Levels | Triggers every N levels (e.g., every 5 levels).       | **Level Interval** — how often (default: 5). **Skip Level One** — exclude level 1 from the interval. **Starting Level** — the base for interval calculation. |
| Max Level      | Triggers when the character reaches the level cap.    | None.                                                                                                                                                        |

**Example:** To grant a talent point every 5 levels starting from level 5, set Reward Type to "Every X Levels", Level Interval to 5, and Skip Level One to true.

## Setting Up a Progression Entity

To give a character progression tracking, add a **ProgressionEntity** component in the Inspector.

| Field               | Description                                                                          |
| ------------------- | ------------------------------------------------------------------------------------ |
| Is Persistent       | Save and load progression data across sessions (default: false).                     |
| Auto Save On Change | Automatically save when XP or level changes (default: true). Requires Is Persistent. |
| Load On Start       | Load saved progression data on Start (default: true). Requires Is Persistent.        |
| Spark Entity        | Reference to the SparkEntity. Required for persistence.                              |

Progressions marked as **Default Unlocked** are automatically created when the entity initializes. Other progressions must be unlocked through triggers or gameplay logic.

## Progression-Related Triggers

| Trigger         | Description                                                                                                            |
| --------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Gain Experience | Grants XP to a specific progression instance. Configure the progression instance entry, XP amount, and optional delay. |

## Progression-Related Requirements

| Requirement       | Description                                                                                                                                                                |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Progression Level | Checks if a progression instance has reached a specific level. Configure the target progression, comparison type (equal, greater than, less than, etc.), and target level. |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sparkframework.dev/documentation/user-guide/plugins/progression/progression-instances.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.