Economy

The Economy system provides a complete monetization and progression framework for your game. It handles virtual currencies, in-app purchases, rewarded video ads, donations, and complex reward mechanics.

Key features #

Virtual currencies #

Define multiple in-game currencies that players can earn through gameplay or purchase with real money. The system tracks player balances and handles all currency transactions atomically.

Learn more about virtual currencies

Virtual store #

Create stores where players can purchase items, consumables, or currency packs using soft currency (earned in-game) or hard currency (real money via App Store, Google Play, etc.). The system handles receipt validation, purchase intents, and reward grants.

Learn more about the virtual store

Rewarded video #

Integrate rewarded video ads from ironSource or AppLovin MAX. Players watch ads in exchange for in-game rewards. Hiro handles server-side webhook verification and provides automatic fallbacks if callbacks don’t arrive.

Learn more about rewarded video

Donations #

Enable social features where players can request help and receive contributions from other players. Donors and recipients both receive configurable rewards.

Learn more about donations

Rewards #

Configure complex reward structures with guaranteed drops, weighted random loot tables, and time-limited modifiers. Rewards can include currencies, items, energy, and more.

Learn more about rewards

Economy configuration #

The Economy system is configured via a JSON file. Here’s an example showing the main sections:

 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
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

{
  "initialize_user": {
    "currencies": {
      "GalacticCredits": 100,
      "PlasmaCores": 10
    },
    "items": {
      "StarterKit": 1
    }
  },
  "store_items": {
    "PlasmaCorePack": {
      "name": "Plasma Core Pack",
      "description": "Power your gear with concentrated plasma energy.",
      "category": "powerups",
      "cost": {
        "currencies": {
          "GalacticCredits": 100
        }
      },
      "reward": {
        "guaranteed": {
          "currencies": {
            "PlasmaCores": {
              "min": 5
            }
          }
        }
      }
    },
    "CoinPack": {
      "name": "Coin Pack",
      "description": "A pack of premium currency.",
      "category": "coin packs",
      "cost": {
        "sku": "com.spacegame.coinpack"
      },
      "reward": {
        "guaranteed": {
          "currencies": {
            "GalacticCredits": {
              "min": 500
            }
          }
        }
      }
    }
  },
  "placements": {
    "daily_reward_video": {
      "reward": {
        "guaranteed": {
          "currencies": {
            "GalacticCredits": {
              "min": 25,
              "max": 50
            }
          }
        }
      }
    }
  },
  "donations": {
    "resource_request": {
      "name": "Resource Request",
      "description": "Request plasma cores from your allies.",
      "cost": {
        "currencies": {
          "PlasmaCores": 1
        }
      },
      "max_count": 10,
      "duration_sec": 86400,
      "user_contribution_max_count": 2,
      "recipient_reward": {
        "guaranteed": {
          "currencies": {
            "PlasmaCores": {
              "min": 1
            }
          }
        }
      },
      "contributor_reward": {
        "guaranteed": {
          "currencies": {
            "GalacticCredits": {
              "min": 10
            }
          }
        }
      }
    }
  }
}
PropertyTypeDescription
initialize_userInitializeUserThe currencies and items a user should start with when their account is created.
donationsstring:DonationA map of all donations.
store_itemsstring:StoreItemA map of all store items.
placementsstring:PlacementA map of all placements.
allow_fake_receiptsboolShould fake receipts be allowed? A receipt is fake if it contains the string: fake receipt.

Initialize user #

The initialize_user section defines what currencies and items players start with when they first create an account.

When initialize_user is updated, players who created an account prior to the change won’t receive the new updates. For example, if version 1.0 of your game initializes players with 100 coins and in version 2.0 this amount is increased to 200 coins, then players who signed up prior to version 2 won’t receive the additional 100 coins.
PropertyTypeDescription
currenciesstring:int64A map of currency IDs and quantities that a user account should be created with.
itemsstring:int64A map of item IDs and quantities that a user account should be created with.