API

Assembly: Spark.Currency Interface: ICurrencyPlugin Implementation: CurrencyPlugin

Interface

public interface ICurrencyPlugin
{
    // Wallet management
    WalletInstance CreateWallet(string walletId = null);
    WalletInstance CreateEntityWallet(string entityId, string walletId = null);
    WalletInstance GetWallet(string walletId);
    WalletInstance GetEntityWallet(string entityId);
    bool DestroyWallet(string walletId);

    // Currency operations
    bool AddCurrency(string walletId, string currencyId, long amount,
        bool suppressEvents = false, GameObject source = null);
    bool RemoveCurrency(string walletId, string currencyId, long amount,
        bool suppressEvents = false, GameObject source = null);
    bool SetCurrency(string walletId, string currencyId, long amount,
        bool suppressEvents = false, GameObject source = null);
    bool HasCurrency(string walletId, string currencyId, long amount);
    long GetCurrencyAmount(string walletId, string currencyId);

    // Transfer
    bool TransferCurrency(string sourceWalletId, string targetWalletId,
        string currencyId, long amount);

    // Conversion
    bool ProcessConversion(string walletId, string conversionEntryId,
        long count = -1);

    // Database queries
    List<CurrencyEntry> GetAllCurrencies();
    CurrencyEntry GetCurrency(string currencyId);
    List<CurrencyConversionEntry> GetAllConversions();
    CurrencyConversionEntry GetConversion(string conversionId);
}

CurrencyEntry

Extends SparkDatabaseEntry. Defines a currency type.

Field	Type	Description
currencySymbol	string	Display symbol (e.g., "G", "$")
maxAmount	long	Maximum amount (0 = unlimited)
startingAmount	long	Initial wallet amount
displayColor	Color	UI display color
displayFormat	CurrencyDisplayFormat	Full or Abbreviate
conversionEntry	CurrencyConversionEntry	Auto-conversion rule

Methods:

string FormatAmount(long amount)
bool HasMaximumLimit()
long GetMaxAmount()
long GetStartingAmount()

CurrencyConversionEntry

Extends SparkDatabaseEntry. Defines an exchange rate between currencies.

Field	Type	Description
sourceCurrency	CurrencyEntry	Currency to convert from
targetCurrency	CurrencyEntry	Currency to convert to
sourceAmount	long	How much source is consumed
targetAmount	long	How much target is produced

WalletInstance

Runtime wallet managing currency balances.

Methods:

bool Add(string currencyId, long amount)
bool Remove(string currencyId, long amount)
bool Has(string currencyId, long amount)
long GetAmount(string currencyId)
void SetAmount(string currencyId, long amount)
bool TryConvert(string conversionEntryId, long count)
Dictionary<string, long> GetAllCurrencies()

Events: OnCurrencyChanged, OnCurrencyConverted

Auto-conversion is supported with a maximum chain depth of 10 to prevent infinite loops.

Events

Event	Fields	Description
CurrencyAddedEvent	WalletId, EntityId, CurrencyId, Amount, NewTotal	Currency added
CurrencyRemovedEvent	WalletId, EntityId, CurrencyId, Amount, NewTotal	Currency removed
CurrencySetEvent	WalletId, EntityId, CurrencyId, OldAmount, NewAmount	Currency set directly
CurrencyConvertedEvent	WalletId, SourceCurrencyId, TargetCurrencyId, Amounts	Conversion executed
CurrencyTransferredEvent	SourceWalletId, TargetWalletId, CurrencyId, Amount	Transfer between wallets
WalletCreatedEvent	WalletId, EntityId	New wallet created
WalletDestroyedEvent	WalletId, EntityId	Wallet destroyed

All currency events are struct-based ISparkEvent implementations.

Commands

Command	Description
AddCurrencyCommand	Add currency to a wallet
RemoveCurrencyCommand	Remove currency from a wallet
SetCurrencyCommand	Set currency to a specific amount
ConvertCurrencyCommand	Execute a currency conversion
TransferCurrencyCommand	Transfer between wallets
CreateWalletCommand	Create a new wallet
DestroyWalletCommand	Destroy a wallet

Components

Component	Description
WalletEntity	Manages a wallet on a character entity
CurrencyDisplay	UI component for showing currency amounts

Save Data

CurrencyPluginSaveData stores serialized wallet data per entity, including currency amounts.

Usage

var currency = Spark.GetPlugin<ICurrencyPlugin>();
if (currency != null)
{
    // Create a wallet for an entity
    var wallet = currency.CreateEntityWallet(entityId);

    // Add gold
    currency.AddCurrency(wallet.WalletId, "gold", 100);

    // Check if player can afford something
    if (currency.HasCurrency(wallet.WalletId, "gold", 50))
    {
        currency.RemoveCurrency(wallet.WalletId, "gold", 50);
    }

    // Transfer between wallets
    currency.TransferCurrency(playerWalletId, shopWalletId, "gold", 200);

    // Convert currency (e.g., 100 copper -> 1 silver)
    currency.ProcessConversion(wallet.WalletId, "copper_to_silver");
}