Economy #

The Economy features enable you to define multiple in-game currencies and rewards, allow players to spend soft or hard currency in exchange for in-game energy, inventory, and rewards, and offer video ad watches as a way for players to obtain rewards.

Customization parameters #

The following JSON represents the customization parameters you can use to configure the default user experience for the economy system.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
{
  "initialize_user": {
    "currencies": {
      "<currencyName1>": 100,
      "<currencyName2>": 50
    },
    "collectible_ids": [ "<collectibleId1>", "<collectibleId2>" ],
    "consumables": {
      "<consumableId1>": 1,
      "<consumableId2>": 10
    }
  },
  "store_items": {
    "<itemId1>": {
      "name": "Item one",
      "description": "The description for item one",
      "category": "<categoryName>",
      "cost": {
        "currencies": {},
        "sku": "com.example.item1"
      },
      "reward": {
        "currencies": {},
        "consumables": {},
        "collectables": []
      },
      "resource_id": "store_item_1"
    }
  },
  "placements": {
    "<placementId1>": {
      "resource_id": "placement_1",
      "reward": {
        "currencies": {},
        "consumables": {},
        "energies": {},
        "collectables": []
      }
    }
  },
  "collectables": {
    "<collectibleId1>": {
      "name": "Collectible one",
      "description": "The description for collectible one",
      "category": "<categoryName>",
      "removeable": false,
      "resource_id": "collectible_1"
    }
  },
  "consumables": {
    "<consumableId1>": {
      "name": "Consumable one",
      "description": "The description for consumable one",
      "category": "<categoryName>",
      "max_count": 10,
      "resource_Id": "consumable_1"
    }
  },
  "donations": {
    "<donationId1>": {
      "name": "Donation one",
      "description": "Description for donation one",
      "count": 1,
      "max_count": 10,
      "user_contribution_max_count": 2,
      "duration_sec": 10000,
      "reward": {
        "currencies": {},
        "consumables": {},
        "collectables": []
      },
      "sender_reward": {
        "currencies": {},
        "consumables": {},
        "collectables": []
      },
      "resource_id": "donation_1"
    }
  }
}

The JSON schema defines several objects which define the various store items, collectables, consumables, placements and donations that will be available in your game. You can configure as few or as many of each as needed for your desired gameplay. It also defines an initialize_user object which defines what currencies, collectables and consumables a user starts with.

initialize_user #

The initialize_user object is structured as follows:

PropertyDescription
currenciesA string:int dictionary of currencies and quantities the user should start with.
consumablesA string:int dictionary of consumables and quantities the user should start with.
collectable_idsAn array of collectables the user should start with.

store_items #

Each item inside the store_items object is keyed by id and may define the following::

PropertySubpropertyDescription
nameThe name for this store item.
descriptionThe description for this store item.
categoryThe category for this store item.
costThe cost for this store item, either in soft currency using the currencies subproperty or via IAP using the sku subproperty.
currenciesA string:int dictionary of currencies and quantities the user must pay to purchase this item.
skuThe SKU code of the in-app purchase the user must complete to obtain this item.
rewardAn object that defines what rewards a player should receive once they purchase this item.
currenciesA string:int dictionary of currencies and quantities the user should receive as a reward.
consumablesA string:int dictionary of consumables and quantities the user should receive as a reward.
collectablesAn array of collectables the user should receive as a reward.
resource_idA string hint for the client (e.g. addressable id).

placements #

Each placement inside the placements object is keyed by id and may define the following:

PropertySubpropertyDescription
resource_idA string hint for the client (e.g. addressable id).
rewardAn object that defines what rewards a player should receive once they purchase this item.
currenciesA string:int dictionary of currencies and quantities the user should receive as a reward.
consumablesA string:int dictionary of consumables and quantities the user should receive as a reward.
energiesA string:int dictionary of energies and quantities the user should receive as a reward.
collectablesAn array of collectables the user should receive as a reward.

collectables #

Each collectible inside the collectables object is keyed by id and may define the following:

PropertyDescription
nameThe name for this collectable.
descriptionThe description for this collectable.
categoryThe category for this collectable.
removableA bool indicating whether or not this collectable can be removed from the user’s collection.
resource_idA string hint for the client (e.g. addressable id).

consumables #

Each consumable inside the consumables object is keyed by id and may define the following:

PropertyDescription
nameThe name for this consumable.
descriptionThe description for this consumable.
categoryThe category for this consumable.
max_countThe maximum amount of this consumable a user can own.
resource_idA string hint for the client (e.g. addressable id).

donations #

Each donation inside the donations object is keyed by id and may define the following:

PropertySubpropertyDescription
nameThe name for this donation.
descriptionThe description for this donation.
countThe initial count to start this donation with.
max_countThe maximum amount of donations required for this to be completed.
user_contribution_max_countThe maximum amount of times each user can donate towards this donation.
duration_secHow long (in seconds) this donation is active.
rewardAn object that defines what rewards a player should receive once the donation is fulfilled.
currenciesA string:int dictionary of currencies and quantities the user should receive as a reward.
consumablesA string:int dictionary of consumables and quantities the user should receive as a reward.
collectablesAn array of collectables the user should receive as a reward.
sender_rewardAn object that defines what rewards the sender should receive once the donation is fulfilled.
currenciesA string:int dictionary of currencies and quantities the sender should receive as a reward.
consumablesA string:int dictionary of consumables and quantities the sender should receive as a reward.
collectablesAn array of collectables the sender should receive as a reward.
resource_idA string hint for the client (e.g. addressable id).

Initializing the economy system #

The economy system relies on the Nakama System which must be passed in as dependencies via the constructor. You must also specify which StoreType you wish to work with.

1
2
var economySystem = new EconomySystem(_nakamaSystem, EconomyNakamaSystem.StoreType.AppleAppStore);
systems.Add(economySystem);

Subscribing to changes in the economy system #

You can listen for changes in the economy system so that you can respond appropriately, such as updating the UI, by implementing the appropriate interface.

1
2
3
4
5
var disposer = SystemObserver<EconomySystem>.Create(leaderboardsSystem, system => {
  Instance.Logger.Info($"System updated.");

  // Update UI elements etc as necessary here...
});

Refreshing the economy system #

To ensure the economy system has the latest information from Nakama you can refresh it.

1
await economySystem.RefreshAsync();