> For the complete documentation index, see [llms.txt](https://docs.sparkframework.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sparkframework.dev/documentation/user-guide/plugins/progression/progression-instances.md). # 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 This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.sparkframework.dev/documentation/user-guide/plugins/progression/progression-instances.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.