Economy Model Objects

Boris Spektor edited this page Mar 21, 2016 · 3 revisions

unity3d-store uses modelV3 which is a complete data model implementation for Virtual Economies. We intend to provide you with objects that support you every need and will make it easier for you to handle virtual items and virtual economy processes.

Virtual Items

Almost every entity in your virtual economy will be a VirtualItem. There are many types of VirtualItems and you can select the ones that fits your needs. Each one of the various types extends VirtualItem and adds its own behavior on top of it.

Among other features, all VirtualItems (Goods, Packs, Currencies …) has 2 functions to help you easily interact with them: give and take. Use these functions to give your user (or take from him) a specific amount of a specific VirtualItem. (You can also use StoreInventory for these purposes… both ways will work.)

VirtualItem Members:

name and description are pretty obvious.

itemId - Every VirtualItem has an itemId. This is a unique string that we use to identify between the different VirtualItems. Don't be confused, this has nothing to do with Google or Apple's productId. We'll get to that when we talk about MarketItem.


Not all VirtualItems you can actually purchase. For example, a VirtualCurrency is not Purchasable but a VirtualCurrencyPack is. PurchasableVirtualItems has the function buy that makes the actual purchase using the provided PurchaseType.

PurchasableVirtualItem Members:

purchaseType - defined the way the PurchasableVirtualItem is purchased.


How can one talk about PurchasableVirtualItems without menthioning PurchaseTypes. We wanted to provide game devs with multiple purchase types. When we first implemented modelV3 we added 2 PurchaseTypes and we're going to add more options from time to type.

PurchaseWithMarket (extends PurchaseType)

This kind of PurchaseType should be attached to PurchasableVirtualItems that you want to be purchased with Google Play or the App Store.

When you create a new PurchaseWithMarket, you need to provide an associated MarketItem which contains a price and the productId you defined in Google Play or in the App Store. You have to define the associated VirtualItem in Google Play Developer Console or in iTunes Connect and provide unity3d-store with the same product id.

PurchaseWithVirtualItem (extends PurchaseType)

One of the main differences in modelV3 is that it introduces the notion that every PurchasableVirtualItems can be purchased by any VirtualItem. When PurchaseWithVirtualItem is attached to a PurchasableVirtualItems it allows just that.

PurchaseWithVirtualItem is instantiated with the target virtual item and with the amount that you consider the value of the associated PurchasableVirtualItems.


Every game has at least one VirtualCurrency and Some has even more than one. Use the VirtualCurrency class to represent your game's virtual currency.


In game stores, you never buy just a "Gold Coin" or a "Muffin". You actually always buy a pack of the game's VirtualCurrency. VirtualCurrencyPack represents exactly that: a pack of VirtualCurrency.

VirtualCurrencyPack is a PurchasableVirtualItem and because of that, your users will be able to buy it according to the PurchaseType that you'll define.


VirtualGoods are the heart of every virtual economy. These are the game objects you want to sell in your game's store. When we worked on modelV3, we realized that there are many possible virtual economies and thus that differ in the types of VirtualGoods in them. So, in modelV3 we also introduced those types of VirtualGoods so everyone will be able to create his own custom virtual economy that fits his game specific needs. The types of VirtualGoods are: "Single Use", "Lifetime", "Equippable", "Single Use Pack" and "Upgrade".

Every virtual good is a PurchasableVirtualItem. You can buy it with another VirtualItem or in Google Play as described above.


The most basic and common kind of a VirtualGood is SingleUseVG. SingleUseVG is a VirtualGood your users can buy multiple times and use multiple time. No limits!

The SingleUseVG's characteristics are:
1. Can be purchased unlimited number of times.
2. Has a balance and saved in the database. Its balance goes up when you "give" it or "buy" it. The balance goes down when it's taken or refunded (in case of an unfriendly refund (see StoreConfig)).

Usage Examples: 'Hat', 'Sword'


Sometimes, you want to to sell packs of SingleUseVGs. To support these cases, we've created SingleUsePackVG. SingleUsePackVGs are just bundles of SingleUseVGs.

The SingleUsePackVG's characteristics are:
1. Can be purchased unlimited number of times.
2. Doesn't Have a balance in the database. The SingleUseVG there's associated with this pack has its own balance. When your users buy a SingleUsePackVG, the balance of the associated SingleUseVG goes up in the amount you defined for the pack (in the code: mGoodAmount).

Usage Examples: 'Box Of Chocolates', '10 Swords'


Who wouldn't want to live forever? When you define a LifetimeVG you give him eternal life. How amazing is that? A LifetimeVG is allows you to offer VirtualGoods that are bought only once and kept forever.

The LifetimeVG's characteristics are:
1. Can only be purchased once.
2. Your users can't have more than one of this item. In other words, (0 <= [LifetimeVG's balance] <= 1) == true.

Example usage: 'No Ads', 'Double Coins'


An EquippableVG is a special type of LifetimeVG. In addition to the fact that EquippableVG can be purchased once, it can also be equipped by your users. Equipping means that the user decides to currently use a specific EquippableVG.

The EquippableVG's characteristics are:
1. Can be purchased only once.
2. Can be equipped by the user.
3. Inherits the definition of LifetimeVG.

There are 3 ways to equip an EquippableVG:
1. LOCAL - The current EquippableVG's equipping status doesn't affect any other EquippableVG.
2. CATEGORY - In the containing category, if this EquippableVG is equipped, all other EquippableVGs are unequipped.
3. GLOBAL - In the whole game, if this EquippableVG is equipped, all other EquippableVGs are unequipped.

Example Usage:

  • multiple characters (play with a specific character)
  • 'binoculars' (users might only want to take them at night)


An UpgradeVG is one VG in a series of UpgradeVGs that define an upgrade sequence for a given VirtualGood. The associated VirtualGood can be any VirtualGood.

This type of virtual good is best explained with an example: Lets say you have a strength attribute to your character in the game and that strength is on the scale 1-5. You want to provide your users with the ability to upgrade that strength. This is what you'll need to create:
1. SingleUseVG for 'strength'
2. UpgradeVG for strength 'level 1'
3. UpgradeVG for strength 'level 2'
4. UpgradeVG for strength 'level 3'
5. UpgradeVG for strength 'level 4'
6. UpgradeVG for strength 'level 5'

Now, when the user buys this UpgradeVG, we check and make sure the appropriate conditions are met and buy it for you (which actually means we upgrade the associated VirtualGood).

The UpgradeVG characteristics are:
1. Can be purchased whenever it's not the current upgrade.
2. Doesn't Have a balance in the database.

Other Objects


A VirtualCategory is used to categorize VirtualGoods. For Example: Your game can have categories of virtual goods like: "Power Ups", "Fruits", "Swords", "Hats" ...


MarketItem is a representation of an item in Google Play or the App Store. MarketItem is only used for PurchaseWithMarket purchase type.

You have to define MarketItems in Google Play or iTunes Connect. Don't forget that.

A word about StoreInfo

On runtime, StoreInfo keeps all the virtual items. You can query it for the different virtual items using their itemIds.

Usage Example

See MuffinRushAssets