Energy #

Time based energies are used in Blocks and Cities by Kyoso Interactive.
Time based energies are used in Blocks and Cities by Kyoso Interactive.

Energy is any resource that can be used to limit the number of times a player can perform an action in a game. For example, a player may have a limited number of lives, and each time they die they lose a life. When they run out of lives, they can no longer play the game until they have been given more lives. This can be done by watching an ad, donations, or by waiting for a period of time.

The Hiro GDK enables you to manage energy in your game. You can define multiple energy types, each with their own configuration. Energy amounts are stored per user, and the real-time value of the current energy amount is computed on get or spend. Players can spend one or more energy amounts and return all current energy values.

Customization parameters #

The following JSON represents the customization parameters you can use to configure the default user experience for the energy 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

{
  "energies": {
    "<energyName1>": {
      "start_count": 5,
      "max_count": 5,
      "refill_count": 1,
      "refill_time_sec": 600,
      "implicit": true
    },
    "<energyName2>": {
      "start_count": 0,
      "max_count": 5,
      "refill_count": 1,
      "refill_time_sec": 3600,
      "implicit": false,
      "reward": {
        "collectables": [],
        "consumables": {},
        "currencies": {
          "<currencyName>": 1
        }
      }
    }
  }
}

The JSON schema defines an energies object which must contain an individual object for each energy you wish to define in the system. You can configure as few or as many energy types as needed for your desired gameplay.

Each energy is keyed by name and may define the following:

PropertySubpropertyDescription
start_countThe initial amount of this energy a user should start with.
max_countThe maximum amount of this energy a user can possess at any time.
refill_countThe amount of this energy refilled after each interval (defined in refill_time_sec).
refill_time_secThe time in seconds it takes for this energy to refill by refill_count amount.
implicitIf true the user starts with this energy, if false they must be granted this energy.
rewardAn object that defines what rewards a player should receive once they complete this achievement.
collectablesAn array of collectables the user should receive as a reward.
consumablesAn string:int dictionary of consumables and quantities the user should receive as a reward.
currenciesAn string:int dictionary of currencies and quantities the user should receive as a reward.

Initializing the energy system #

The energy system relies on the Nakama System and the Economy System, both must be passed in as dependencies via the constructor.

1
2

var energySystem = new EnergySystem(nakamaSystem, economySystem)
systems.Add(energySystem);

Subscribing to changes in the energy system #

You can listen for changes in the energy 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<EnergySystem>.Create(leaderboardsSystem, system => {
  Instance.Logger.Info($"System updated.");

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

Refreshing the energy system #

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

1

await energySystem.RefreshAsync();

Listing available energy #

You can list the available energies for a user.

1
2
3
4
5
6
7
8

foreach (var energyKvp in energySystem.Energies)
{
  var name = energyKvp.Key;
  var energy = energyKvp.Value;

  Debug.Log($"Energy {name} ({energy.Current}/{energy.Max})");
  Debug.Log($"Next refill in {(energy.NextRefillTime - energy.CurrentTime) / 1000}s");
}

Spending energy #

You can spend energy as a user, either as a single energy at a time or as multiple at once.

1
2
3
4
5
6
7
8
9

// Spend a single energy
await energySystem.SpendEnergyAsync("lives", 1);

// Spend multiple energies
await energySystem.SpendEnergyAsync(new Dictionary<string, int>
{
  { "lives", 1 },
  { "hearts", 5 }
});