Currency

Currencies are money, tokens, or any other thing that a user may accumulate.

Currencies differ from items in a major way: they are tracked in a wallet and the user accumulates a quantity. The currency itself has no inherent properties, functions, or UI.

Design Goals

Virtual pet games typically have at least one type of money: some kind of points, credits, or gold coins. Kitto² is no exception: out of the box, the game features a single “Money” currency.

It’s common for games to have several additional currencies: specific dungeons may reward their own points redeemable in a special store, for example. This allows game developers to introduce fresh content that isn’t immediately completable by users with massive reserves of existing currencies.

Kitto² allows you to add as many currencies as you want. In shops, the currency type is configurable, making it easy to build out special shops to go with those currencies.

Or, your own code can reference specific CurrencyTypeEnum cases to award & consume currencies in whatever way you need.

Implementation

Users do not have a currency entry until they’ve had a transaction to add/subtract it. This is meant to minimize database space and keep migrations fast: there’s no point in inserting ten thousand useless user_currencies rows for 0 when you add a new currency. Requesting the balance for a currency will detect the absence of a row and correctly return 0.

Transactions

To use currencies, the User::getBalance(CurrencyTypeEnum $type) method can be used to look up a specific currency’s value.

When using this method, the User::currencies relationship should be eager-loaded. The logged-in user will have this automatically loaded, since the site navigation has to display the user’s money.

To add or subtract, the UserCurrencyTransaction class offers a pair of methods that will ensure your transaction is valid, handle initializing “new” currencies for a user, and audit log the change. These should be used instead of directly manipulating the user_currencies table values:

Display

To display currency, use the <x-currency/> component. This will correctly render any type of currency, so your shops and other views can remain general-purpose:

{{-- $stock is a ShopInventory --}}
<x-currency :type="$stock->cost_currency_type" :amount="$stock->cost_amount"/>

Adding a Currency

New currency types must be added by a developer. These cannot be added in the admin panel.

Currencies do not inherently have any behaviour. There is not much required to add one:

1. Add a new case to the CurrencyTypeEnum
   • The next time you deploy changes, the CurrencyTypeSeeder will detect the new case and add it to the database
2. Update the resources/views/components/currency.blade.php component to display it correctly
   • This includes an icon & formatting

The new currency will not inherently do anything or be displayed anywhere. You will likely want to display the balance somewhere and include it as a reward.

New currency types can be used in loot tables and shop inventories via the admin panel without any additional setup. You (or other staff) can immediately go and build out a shop for spending the new currency.