Event Leaderboards

Read more about the Event Leaderboards system in Hiro here.

Functions #

ListEventLeaderboard #

Returns all available event leaderboards for the user. These can be filtered by categories, if these filter is empty it will include all event leaderboards.

1
2
3
4
5
6
7

userId := "userId"
categories := []

eventLeaderboard, err := systems.GetEventLeaderboardsSystem().ListEventLeaderboard(ctx, logger, nk, userId, categories)
if err != nil {
  return err
}

GetEventLeaderboard #

Get a specified event leaderboard’s cohort for a user.

1
2
3
4
5
6
7

userId := "userId"
eventLeaderboardId := "eventLeaderboardId"

eventLeaderboard, err := systems.GetEventLeaderboardsSystem().GetEventLeaderboard(ctx, logger, nk, userId, eventLeaderboardId)
if err != nil {
  return err
}

RollEventLeaderboard #

Place a user into a new cohort for the specified event leaderboard if possible.

1
2
3
4
5
6
7
8
9

userId := "userId"
eventLeaderboardId := "eventLeaderboardId"
tier := 1
matchmakerProperties := map[string]interface{}{}

eventLeaderboard, err := systems.GetEventLeaderboardsSystem().RollEventLeaderboard(ctx, logger, nk, userId, eventLeaderboardId, &tier, matchmakerProperties)
if err != nil {
  return err
}

UpdateEventLeaderboard #

Update a user’s score in the specified event leaderboard, and returns the user’s updated cohort information.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

userId := "userId"
username := "username"
eventLeaderboardId := "eventLeaderboardId"
var score int64 = 100
var subscore int64 = 10
metadata := map[string]interface{}{}

eventLeaderboard, err := systems.GetEventLeaderboardsSystem().UpdateEventLeaderboard(ctx, logger, nk, userId, username, eventLeaderboardId, score, subscore, metadata)
if err != nil {
  return err
}

ClaimEventLeaderboard #

Claim a user’s reward for the given event leaderboard.

1
2
3
4
5
6
7

userId := "userId"
eventLeaderboardId := "eventLeaderboardId"

eventLeaderboard, err := systems.GetEventLeaderboardsSystem().ClaimEventLeaderboard(ctx, logger, nk, userId, eventLeaderboardId)
if err != nil {
  return err
}

DebugFill #

Fill a user’s current cohort with dummy users for all remaining available slots.

1
2
3
4
5
6
7
8

userId := "userId"
eventLeaderboardId := "eventLeaderboardId"
targetCount := 100

eventLeaderboard, err := systems.GetEventLeaderboardsSystem().DebugFill(ctx, logger, nk, userId, eventLeaderboardId, targetCount)
if err != nil {
  return err
}

DebugRandomScores #

Assign random scores to the participants of a user’s current cohort, except to the user themselves.

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

userId := "userId"
eventLeaderboardId := "eventLeaderboardId"
var scoreMin int64 = 1
var scoreMax int64 = 100
var subscoreMin int64 = 1
var subscoreMax int64 = 10
operator := int(api.Operator_SET)

eventLeaderboard, err := systems.GetEventLeaderboardsSystem().DebugRandomScores(ctx, logger, nk, userId, eventLeaderboardId, scoreMin, scoreMax, subscoreMin, subscoreMax, &operator)
if err != nil {
  return err
}

Hooks #

SetOnEventLeaderboardsReward #

Set a custom reward function which will run after an event leaderboard’s reward is rolled.

1
2
3
4
5
6

systems.GetEventLeaderboardsSystem().SetOnEventLeaderboardsReward(OnEventLeaderboardsReward)

func OnEventLeaderboardsReward(ctx context.Context, logger runtime.Logger, nk runtime.NakamaModule, userID, sourceID string, source *hiro.EventLeaderboardsConfigLeaderboard, rewardConfig *hiro.EconomyConfigReward, reward *hiro.Reward) (*hiro.Reward, error) {
	// Modify reward or take additional actions.
	return reward, nil
}

SetOnEventLeaderboardCohortSelection #

Set a custom function to override or modify the cohort/opponent selection process for event leaderboards.

The default Nakama behavior for cohort selection is preserved for any of the returned values (cohortID, cohortUserIDs, newCohort) that are set to "", nil, or are empty.

To manually handle cohort/opponent selection:

1
2
3
4
5
6

systems.GetEventLeaderboardsSystem().SetOnEventLeaderboardCohortSelection(OnEventLeaderboardCohortSelection)

func OnEventLeaderboardCohortSelection(ctx context.Context, logger runtime.Logger, nk runtime.NakamaModule, storageIndex string, eventID string, config *hiro.EventLeaderboardsConfigLeaderboard, userID string, tier int, matchmakerProperties map[string]interface{}) (cohortID string, cohortUserIDs []string, newCohort *hiro.EventLeaderboardCohortConfig, err error) {
	// Manually handle cohort/opponent selection.
	return cohortID, cohortUserIDs, newCohort, nil
}

To preserve Nakama behavior:

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


systems.GetEventLeaderboardsSystem().SetOnEventLeaderboardCohortSelection(OnEventLeaderboardCohortSelection)

func OnEventLeaderboardCohortSelection(ctx context.Context, logger runtime.Logger, nk runtime.NakamaModule, storageIndex string, eventID string, config *hiro.EventLeaderboardsConfigLeaderboard, userID string, tier int, matchmakerProperties map[string]interface{}) (cohortID string, cohortUserIDs []string, newCohort *hiro.EventLeaderboardCohortConfig, err error) {

  // To preserve the default behavior for a value, return:
  // - cohortID: ""
  // - cohortUserIDs: nil
  // - newCohort: nil
  
  // Example: Override only the cohort ID.
  cohortID = "my_custom_cohort_id"
  
  // Returning nil for the others preserves the default Nakama behavior 
  // for opponent selection and new cohort creation.
  return cohortID, nil, nil, nil
}