Introduction to resources in Economy

The Economy service works by allowing you to create different in-game units that define an economy system. Each type of unit you add to a game is called a resource. Economy comes with the following built-in configuration resource types:

Additionally, each resource type can have Custom data.

All fields that require numerical input (for example, amounts, balances) have a limit of 15 digits (integers only).

Currency

A currency in Economy defines virtual money that exists within your game. When defining currencies, there is the option to set an initial balance (the amount a player receives when you initialize the currency), and a maximum currency balance (the limit to how much of that currency a player can have). For each defined currency, Economy stores a balance against each player account, which the game manages.

Economy initializes currencies per player upon the first interaction with that currency. This includes currencies that become available after the player has already interacted with the currency system.

For example, a player plays a game with a Coins virtual currency, then you add a Gems currency in a new version of the game with a configured initial balance set to 10. When the player first interacts with currencies after gems are available, Economy creates a balance of 10 for the player’s gems, while coins remain unaffected. Enter a value of zero to not have a currency initialized per player.

You can define a maximum balance for a currency. This is the maximum balance any player can hold for that currency in the system. This has the effect of returning an error in the game APIs when trying to increment a balance over the maximum value. If you don’t want the currency to have an upper limit, remove the maximum value or enter zero.

Inventory item

Inventory items are objects that a player can own in-game. You don’t need to set any property for your resources, but it is always possible to add Custom data to them.

You can associate an inventory item with a player by using the SDK or as part of a purchase (using virtual or real money). The instance of the inventory item associated with the player can have its own instance data. See Player data.

Virtual purchase

A virtual purchase is a transactional resource used to implement a shop or trade feature. Virtual purchases allow players to purchase previously defined in-game currencies or inventory items using their in-game currency balances or items already in their inventory, rather than real money.

Use cases for virtual purchases include:

  • In-game shops
  • Exchanging an inventory item for another
  • Exchanging an inventory item for in-game currency
  • Converting one type of currency for another (for example, exchanging 10 gold coins for one gem)

Although virtual purchases are composed of a cost and a reward, it’s not mandatory to define either component. Depending on how you want to define a virtual purchase, it can be made up of either no cost or no reward.

For example:

  • A situation of a purchase with no cost can happen when you want to give your players a resource as a gift
  • A situation of a purchase with no reward can occur when you want your players to lose a resource

Real money purchase

A real money purchase is a transactional resource allowing players to purchase in-game currencies or items using real money through an app store. Use cases for real money purchases include:

  • Buying an item or a bundle of items from an online storefront
  • Buying virtual currencies using real money

In-app purchase (IAP) integration

To fully integrate real money transactions in your game, you must create the purchase in your game’s economy. Then, the IAP integration in Economy:

  • Validates each purchase with the relevant vendor API
  • Securely applies currency and in-game item rewards to the player's account
  • Validates the receipt for a purchase

However, developers still need to support the connection to the store. The recommended best practice is to use the IAP plug-in to perform this integration.

The IAP plug-in and Economy perform two different roles in creating a purchase that requires players to buy resources with real money. Economy performs the validation of a receipt against a purchase and awards the resource(s) to the player, while the IAP plug-in integrates the game with the store for store initialization and collects the receipt.

Store settings configuration

Before you can configure the Economy service to redeem and verify in-app purchases, you must add some products to both the Apple App Store and the Google Play Store (depending on where you plan to make your game available).

For both stores, you must set up a Product ID in the configuration. The same Product ID is then used in the configuration of real money purchases. The two stores have different steps to follow, so refer to their documentation for the full setup instructions.

Google Play Store configuration requires additional IAP settings.

Unity IAP plug-in integration and receipt validation

Once Economy receives the receipt data from the Unity IAP plug-in, it uses that receipt data to call the Redeem function for the appropriate store (for example, redeemAppleAppStore and redeemGooglePlayStore). The Economy call does all the validation, and rewards the player with the currency balances or the inventory item instance(s) as configured in the Real Money Purchase.

Additional resources