# Challenges

**URL:** https://heroiclabs.com/docs/hiro/unity/challenges/
**Summary:** Challenges enable social and competitive experiences by allowing players to compete in time-bound events with friends.
**Keywords:** challenge, player progression
**Categories:** hiro, unity, challenges

---


# Challenges

_Challenges enable social and competitive experiences by allowing players to compete in time-bound events with friends._ Learn more in the [Challenges concept guide](../../concepts/challenges/_index.md).

## Overview

Challenges provide time-bound competitive experiences where players can:

- Compete against friends or other players
- Track progress through leaderboards
- Earn rewards for participation and performance

## Prerequisites

- Unity project set up with Hiro SDK
- Nakama System integrated ([guide](../getting-started/nakama-system))

## Initializing the Challenges System

```cs
var challengesSystem = new ChallengesSystem(logger, nakamaSystem);
systems.Add(challengesSystem);
```

## Managing Challenges

### Creating a Challenge

Create new challenges with custom parameters:

```cs
var newChallenge = await challengesSystem.CreateChallengeAsync(
    templateId: "daily_race",
    name: "Daily Race Challenge",
    description: "Compete for top daily times",
    invitees: new[] {"player2", "player3"},
    open: true,
    maxScores: 3,
    startDelaySec: 0, // Start immediately
    durationSec: 86400, // 24 hours
    maxParticipants: 10,
    category: "racing"
);
```

**Parameters:**

- `open`: Allow any player to join without an invitation
- `maxScores`: Max submissions per player
- `durationSec`: 0 = unlimited duration

### Listing Challenges

Get all the challenges the player is a participant in or was invited to, with optional filtering:

```cs
var racingChallenges = await challengesSystem.ListChallengesAsync(
categories: new[] {"racing"}
);
```

### Searching Challenges

Find public challenges by name/category. 
Calling this function with empty or `null` arguments returns all the public challenges:

```cs
var results = await challengesSystem.SearchChallengesAsync(
name: "weekly",
category: "racing",
limit: 5
);
```

### Inviting Players

Add participants to existing challenges:

```cs
await challengesSystem.InviteChallengeAsync(
challengeId: "CHALLENGE_123",
userIds: new[] {"player4"}
);
```

## Tracking Progress

### Submitting Scores

Update player standings in a challenge:

```cs
await challengesSystem.SubmitChallengeScoreAsync(
challengeId: "CHALLENGE_123",
score: 1500,
subscore: 0,
metadata: "{"lap_times":[120]}"
);
```

### Joining/Leaving

Manage player participation:

```cs
// Join an open challenge
var joinedChallenge = await challengesSystem.JoinChallengeAsync("CHALLENGE_456");

// Leave a challenge
var leftChallenge = await challengesSystem.LeaveChallengeAsync("CHALLENGE_456");
```

## Rewards

### Claiming Rewards

Claim earned rewards after challenge completion:

```cs
var claimedChallenge = await challengesSystem.ClaimChallengeAsync("CHALLENGE_123");

// Refresh economy system to see new rewards
await economySystem.RefreshAsync();
```
## Additional information

- [Hiro Challenges sample project](../../../../sample-projects/unity/hiro-challenges)