# Challenges

**URL:** https://heroiclabs.com/docs/hiro/dart/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, dart, 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

- Dart project set up with Hiro SDK
- Nakama System integrated

## Managing Challenges

### Creating a Challenge

Create new challenges with custom parameters:

```dart
var createRequest = ChallengeCreateRequest();
createRequest.templateId = "daily_race";
createRequest.name = "Daily Race Challenge";
createRequest.description = "Compete for top daily times";
createRequest.invitees = ["player2", "player3"];
createRequest.open = true;
createRequest.maxScores = 3;
createRequest.startDelaySec = 0; // Start immediately
createRequest.durationSec = 86400; // 24 hours
createRequest.maxParticipants = 10;
createRequest.category = "racing";

var challenge = await hiro.challengeCreate(session, createRequest);
print("Challenge created: ${challenge.name}");
```

**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:

```dart
var listRequest = ChallengeListRequest();
listRequest.categories = ["racing"];
listRequest.withScores = true;

var challenges = await hiro.challengesList(session, listRequest);
challenges.challenges?.forEach((challenge) {
  print("Challenge: ${challenge.name}");
});
```

### Searching Challenges

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

```dart
var searchRequest = ChallengeSearchRequest();
searchRequest.name = "weekly";
searchRequest.category = "racing";
searchRequest.limit = 5;

var challenges = await hiro.challengesSearch(session, searchRequest);
challenges.challenges?.forEach((challenge) {
  print("Found challenge: ${challenge.name}");
});

```

### Inviting Players

Add participants to existing challenges:

```dart
var inviteRequest = ChallengeInviteRequest();
inviteRequest.challengeId = "CHALLENGE_123";
inviteRequest.invitees = ["player4"];

var challenge = await hiro.challengeInvite(session, inviteRequest);
print("Invited to challenge: ${challenge.id}");
```

## Tracking Progress

### Submitting Scores

Update player standings in a challenge:

```dart
var submitScoreRequest = ChallengeSubmitScoreRequest();
submitScoreRequest.challengeId = "CHALLENGE_123";
submitScoreRequest.score = 1500;
submitScoreRequest.subscore = 0;
submitScoreRequest.metadata = '{"lap_times":[120]}';

var challenge = await hiro.challengeSubmitScore(session, submitScoreRequest);
print("Score submitted to challenge: ${challenge.id}");
```

### Joining/Leaving

Manage player participation:

```dart
// Join an open challenge
var joinRequest = ChallengeJoinRequest();
joinRequest.challengeId = "CHALLENGE_456";

var challenge = await hiro.challengeJoin(session, joinRequest);
print("Joined challenge: ${challenge.id}");

// Leave a challenge
var leaveRequest = ChallengeLeaveRequest();
leaveRequest.challengeId = "CHALLENGE_456";

var challenge = await hiro.challengeLeave(session, leaveRequest);
print("Left challenge: ${challenge.id}");
```

## Rewards

### Claiming Rewards

Claim earned rewards after challenge completion:

```dart
var claimRequest = ChallengeClaimRequest();
claimRequest.challengeId = "CHALLENGE_123";

var challenge = await hiro.challengeClaim(session, claimRequest);
print("Claimed reward for challenge: ${challenge.id}");
```