View as Markdown

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

The allow_fake_receipts field is deprecated. It remains in the config schema for backwards compatibility but has no effect. Use SetAllowFakeReceipts in your server module initialization code instead.

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:

base-economy.json
 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.

Initialize user #

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

By default, initialize_user only applies when a player first creates an account. Players who created an account before an initialize_user change won’t receive the new items or currencies automatically. For example, if version 1.0 of your game initializes players with 100 coins and version 2.0 increases this to 200 coins, players who signed up before version 2.0 won’t receive the additional 100 coins unless you ReapplyInitializeUser .
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.

Reapply initialize user to existing players #

Use ReapplyInitializeUser to apply the current initialize_user configuration to an existing account. This grants only the currencies the player has never held and the items they don’t currently own, so existing progress and balances are preserved.

Hiro tracks a version hash of the initialize_user configuration for each player. If the configuration hasn’t changed since the player was last initialized, calling ReapplyInitializeUser is a no-op. See the server framework economy reference for usage.