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:


Property	Description
`currencies`	A `string:int` dictionary of currencies and quantities the user should start with.
`consumables`	A `string:int` dictionary of consumables and quantities the user should start with.
`collectable_ids`	An 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::


Property	Subproperty	Description
`name`		The name for this store item.
`description`		The description for this store item.
`category`		The category for this store item.
`cost`		The cost for this store item, either in soft currency using the `currencies` subproperty or via IAP using the `sku` subproperty.
	`currencies`	A `string:int` dictionary of currencies and quantities the user must pay to purchase this item.
	`sku`	The SKU code of the in-app purchase the user must complete to obtain this item.
`reward`		An object that defines what rewards a player should receive once they purchase this item.
	`currencies`	A `string:int` dictionary of currencies and quantities the user should receive as a reward.
	`consumables`	A `string:int` dictionary of consumables and quantities the user should receive as a reward.
	`collectables`	An array of collectables the user should receive as a reward.
`resource_id`		A 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:


Property	Subproperty	Description
`resource_id`		A string hint for the client (e.g. addressable id).
`reward`		An object that defines what rewards a player should receive once they purchase this item.
	`currencies`	A `string:int` dictionary of currencies and quantities the user should receive as a reward.
	`consumables`	A `string:int` dictionary of consumables and quantities the user should receive as a reward.
	`energies`	A `string:int` dictionary of energies and quantities the user should receive as a reward.
	`collectables`	An 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:


Property	Description
`name`	The name for this collectable.
`description`	The description for this collectable.
`category`	The category for this collectable.
`removable`	A `bool` indicating whether or not this collectable can be removed from the user’s collection.
`resource_id`	A 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:


Property	Description
`name`	The name for this consumable.
`description`	The description for this consumable.
`category`	The category for this consumable.
`max_count`	The maximum amount of this consumable a user can own.
`resource_id`	A 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:


Property	Subproperty	Description
`name`		The name for this donation.
`description`		The description for this donation.
`count`		The initial count to start this donation with.
`max_count`		The maximum amount of donations required for this to be completed.
`user_contribution_max_count`		The maximum amount of times each user can donate towards this donation.
`duration_sec`		How long (in seconds) this donation is active.
`reward`		An object that defines what rewards a player should receive once the donation is fulfilled.
	`currencies`	A `string:int` dictionary of currencies and quantities the user should receive as a reward.
	`consumables`	A `string:int` dictionary of consumables and quantities the user should receive as a reward.
	`collectables`	An array of collectables the user should receive as a reward.
`sender_reward`		An object that defines what rewards the sender should receive once the donation is fulfilled.
	`currencies`	A `string:int` dictionary of currencies and quantities the sender should receive as a reward.
	`consumables`	A `string:int` dictionary of consumables and quantities the sender should receive as a reward.
	`collectables`	An array of collectables the sender should receive as a reward.
`resource_id`		A 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();

Economy #

Customization parameters #

initialize_user #

store_items #

placements #

collectables #

consumables #

donations #