Tutorials #

The tutorial system is a feature of the Hiro GDK that enables you to create a series of steps (a ‘sequence’) that a new user must complete before they can play your game. This is a great way to introduce new users to your game and to help them understand how to play.

Tutorial steps can be configured to be either mandatory or optional. Mandatory steps must be completed before the user can play the game. Optional steps can be skipped by the user.

Multiple tutorial sequences can be configured for a game, each with its own ID. Each sequence can have a different set of steps and can be triggered by different events, for example one for the first time a user logs in, another for when they first join a guild or tournament, and so on.

Configuration Parameters #

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "sequences": {
    "<sequenceName1>": {
      "start_step": 0,
      "max_step": 5
    },
    "<sequenceName2>": {
      "start_step": 0,
      "max_step": 20
    }
  }
}

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

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

Initializing the tutorial system #

The tutorial system relies on the Nakama System which must be passed in as a dependency via the constructor.

1
2

var tutorialSystem = new TutorialSystem(nakamaSystem)
systems.Add(tutorialSystem);

Subscribing to changes in the tutorial system #

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

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

Refreshing the tutorial system #

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

1

await tutorialSystem.RefreshAsync();

Listing available sequences #

You can list the available sequences for a user.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

foreach (var tutorialKvp in tutorial.Sequences)
{
    var name = tutorialKvp.Key;
    var tutorial = tutorialKvp.Value;
    
    Debug.Log($"Tutorial Sequence {tutorial.Id} - {name}");
    Debug.Log($"Step {tutorial.Current} of {tutorial.Max}");

    if (tutorial.Completed)
    {
        var completedAt = DateTimeOffset.FromUnixTimeMilliseconds(tutorial.CompleteTime).DateTime;
        Debug.Log($"Completed at {completedAt.ToShortDateString()}");
    }
}

Updating a sequence #

You can update the current step of a sequence.

1

await tutorialSystem.UpdateSequenceAsync(tutorial.Id, 3);