# Conversions

Currency conversions define exchange rates between two currencies. They are used both for manual currency exchange and for automatic overflow conversion.

## Creating a Conversion Entry

Open the Spark Editor, go to **Currency > Conversions** and click **Create New**.

Each conversion entry defines:

| Field           | Description                                                                  |
| --------------- | ---------------------------------------------------------------------------- |
| Display Name    | Label for this conversion (e.g., "Copper to Silver").                        |
| Source Currency | The currency to convert from.                                                |
| Target Currency | The currency to convert to.                                                  |
| Source Amount   | How much of the source currency is needed for one conversion (default: 100). |
| Target Amount   | How much of the target currency is received per conversion (default: 1).     |

**Example:** To set up "100 Copper = 1 Silver", set Source Currency to Copper, Target Currency to Silver, Source Amount to 100, and Target Amount to 1.

## How Conversions Are Used

### Automatic Overflow Conversion

When a currency entry has a **Max Amount** and a **Conversion Entry** assigned, Spark automatically converts excess currency using that conversion whenever the maximum would be exceeded.

For example, if Copper has a max of 100 and a conversion of 100 Copper → 1 Silver, then earning 150 Copper when you already have 50 would result in: 100 Copper converted to 1 Silver, leaving 50 Copper remaining.

### Conversion Chains

If the target currency also has a max amount and its own conversion, the overflow cascades. For example:

* 100 Copper → 1 Silver (Copper max: 100)
* 100 Silver → 1 Gold (Silver max: 100)

Earning a large amount of Copper could cascade through Silver and into Gold. Spark limits chain depth to 10 steps to prevent infinite loops.

### Manual Conversion

Conversions can also be triggered manually through the currency system. This is useful for shops or exchange NPCs where the player can convert currencies on demand.

## Conversion Validation

A conversion entry is valid when both the source and target currencies are assigned and both amounts are greater than zero. Invalid conversions are ignored by the system.


---

# 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/currency/conversions.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.