# Event Leaderboards

**URL:** https://heroiclabs.com/docs/hiro/server-framework/event-leaderboards/
**Keywords:** event leaderboards, hiro
**Categories:** hiro, event-leaderboards, server-framework

---


# Event Leaderboards

Read more about the Event Leaderboards system in Hiro [here](../../concepts/event-leaderboards/).

## 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.

```go
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.

```go
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.

```go
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.

```go
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.

```go
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.

```go
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.

```go
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
}
```

### DebugUnenroll

Remove a user from their current event leaderboard cohort. Cleans up pointer storage, cohort membership, and tournament records, allowing the user to re-enroll.

```go
userId := "userId"
eventLeaderboardId := "eventLeaderboardId"

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

## Hooks

### SetOnEventLeaderboardsReward

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

```go
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:
```go
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:
```go

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
}
```