# Currencies Currencies are database entries that define types of money or points in your game. Characters hold currencies in wallets, and currencies can be added, removed, transferred, and automatically converted. ## Creating a Currency Entry Open the Spark Editor, go to **Currency > Currencies** and click **Create New**. Each currency entry defines: | Field | Description | | ---------------- | --------------------------------------------------------------------------- | | Display Name | Name shown in-game (e.g., "Gold", "Gems", "Honor Points"). | | Description | Tooltip or info panel text. | | Icon | Sprite for UI display. | | Currency Symbol | Symbol shown alongside amounts (e.g., "$", "G", "₡"). | | Max Amount | Maximum amount a wallet can hold. Set to 0 for unlimited. | | Starting Amount | Default amount when a new wallet is created (default: 0). | | Display Color | UI color used when displaying this currency. | | Display Format | How amounts are formatted in UI. See below. | | Conversion Entry | Optional reference to a conversion entry for automatic overflow conversion. | ### Display Formats | Format | Description | | ---------- | --------------------------------------------------------------------- | | Full | Shows the full number with thousand separators (e.g., "1,250"). | | Abbreviate | Abbreviates large numbers with suffixes (e.g., "1.2K", "3.5M", "1B"). | ## Setting Up a Wallet Entity To give a character (or any GameObject) a wallet at runtime, add a **WalletEntity** component in the Inspector. | Field | Description | | -------------------- | --------------------------------------------------------------------------------------- | | Custom Wallet Id | Optional custom ID. Leave empty for auto-generated. | | Auto Create On Start | Automatically create the wallet when the component starts (default: true). | | Destroy On Disable | Destroy the wallet when the component is disabled (default: false). | | Is Persistent | Save and load wallet contents across sessions (default: false). | | Auto Save On Change | Automatically save whenever the wallet changes (default: true). Requires Is Persistent. | | Load On Create | Load saved data when creating the wallet (default: true). Requires Is Persistent. | | Spark Entity | Reference to the SparkEntity on this character. Required for persistence. | When a wallet is created, it initializes each currency to its **Starting Amount** value. ## Auto-Conversion on Overflow If a currency has a **Max Amount** set and a **Conversion Entry** assigned, Spark automatically converts overflow currency when the maximum is reached. For example, if you have a "Copper" currency with a max of 100 and a conversion to "Silver" (100 Copper → 1 Silver), then when a character gains copper that would exceed 100, the excess is automatically converted to silver. Auto-conversion supports chains. If Silver also has a max and converts to Gold, then overflow from Copper → Silver → Gold happens automatically. Spark prevents infinite conversion loops by limiting chain depth. ## Currency Items Items can be configured with the **Currency** item type (see [Items](/documentation/user-guide/plugins/items/items.md)). Currency items bypass the inventory entirely — when a character picks them up, the item is automatically converted to the corresponding currency and added to the character's wallet. The item's stack size determines the amount granted. This is useful for currency drops in loot tables. Instead of taking up inventory space, the currency is added to the wallet immediately. ## Currency-Related Triggers | Trigger | Description | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Gain Currency | Adds or removes a specified amount of a currency from the player's wallet. Configure the currency entry, amount, whether to remove instead of add, and an optional delay. | ## Currency-Related Requirements | Requirement | Description | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Currency Amount | Checks if the character's wallet has a specific amount of a currency. Configure the target currency, comparison type (equal, not equal, greater than, greater or equal, less than, less or equal), and target amount. | ## Quest Integration When both the Currency and Quests plugins are installed, additional quest features become available: **Quest Objectives:** | Objective | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------ | | Gain Currency | Tracks how much of a specific currency the player has gained. Progress increases each time the currency is added. | | Reach Currency Total | Completes when the player's total amount of a specific currency reaches a target value. Supports retroactive completion. | **Quest Rewards:** | Reward | Description | | ------------- | ------------------------------------------------------------------------- | | Gain Currency | Grants a specified amount of a currency when the quest reward is claimed. | ## UI Components The Currency plugin includes two UI components for displaying wallet information: **Wallet UI** — Displays all currencies in a wallet. Attach it to a UI panel and configure: | Field | Description | | ----------------------- | ------------------------------------------------------------------ | | Wallet Entity | Reference to the WalletEntity to display. | | Currency Display Prefab | Prefab spawned for each currency. | | Container | Parent transform for display items. | | Filter Currencies | Optional list to show only specific currencies (empty = show all). | | Show Only Non-Zero | Only display currencies with amounts greater than zero. | | Auto Update | Automatically refresh when the wallet changes. | **Currency Display** — Displays a single currency amount. Useful for HUD elements showing gold count, etc. | Field | Description | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | Connection Type | How to find the WalletEntity: **Scene Reference** (drag and drop), **Find By Tag** (auto-find by tag), or **By Code** (set at runtime). | | Wallet Entity | Direct reference when using Scene Reference. | | Container Tag | Tag to search for when using Find By Tag (e.g., "Player"). | | Currency | The currency entry to display. | | Text Component | TextMeshPro text for the amount. | | Icon Image | Image component for the currency icon. | | Use Currency Format | Use the currency's own display format settings. | | Prefix / Suffix | Optional text before or after the amount. | | Update On Change | Automatically update when the wallet changes. | | Show Tooltip | Show a tooltip on hover with currency info. | | Tooltip Delay | Seconds before the tooltip appears. | ## Persistence When **Is Persistent** is enabled on the WalletEntity, all currency amounts are saved and loaded through Spark's save system. What is saved per wallet includes the entity ID, wallet ID, and all currency amounts. If **Auto Save On Change** is enabled, the wallet saves automatically whenever any currency changes. --- # 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/currencies.md?ask= ``` 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.