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:
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
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.
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). 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
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
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:
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:
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:
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.
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.
Last updated
Was this helpful?