# Challenges

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

- C++ project set up with Hiro SDK
- Nakama System integrated

## Managing Challenges

### Creating a Challenge

Create new challenges with custom parameters:

```cpp
ChallengeCreateRequest createRequest;
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";

auto onChallengeCreate = [](const Challenge& challenge) {
    std::cout << "Created challenge: " << challenge.name << std::endl;
};

auto onError = [](const Nakama::NError& error) {
    std::cout << Nakama::toString(error.code) << ": " << error.message << std::endl;
};

hiroClient->challengeCreate(session, createRequest, onChallengeCreate, onError);

```

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

```cpp
ChallengeListRequest listRequest;
listRequest.categories = { "racing" };
listRequest.withScores = true;

auto onChallengesList = [](const ChallengesList& challenges) {
    for (const auto& challenge : challenges.challenges) {
        std::cout << "Challenge: " << challenge.name << std::endl;
    }
};

hiroClient->challengesList(session, listRequest, onChallengesList, onError);
```

### Searching Challenges

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

```cpp
ChallengeSearchRequest searchRequest;
searchRequest.name = "weekly";
searchRequest.category = "racing";
searchRequest.limit = "5";

auto onChallengesSearch = [](const ChallengesList& challenges) {
    for (const auto& challenge : challenges.challenges) {
        std::cout << "Found challenge: " << challenge.name << std::endl;
    }
};

hiroClient->challengesSearch(session, searchRequest, onChallengesSearch, onError);
```

### Inviting Players

Add participants to existing challenges:

```cpp
ChallengeInviteRequest inviteRequest;
inviteRequest.challengeId = "CHALLENGE_123";
inviteRequest.invitees = { "player4" };

auto onChallengeInvite = [](const Challenge& challenge) {
    std::cout << "Invited players to challenge: " << challenge.id << std::endl;
};

hiroClient->challengeInvite(session, inviteRequest, onChallengeInvite, onError);
```

## Tracking Progress

### Submitting Scores

Update player standings in a challenge:

```cpp
ChallengeSubmitScoreRequest submitScoreRequest;
submitScoreRequest.challengeId = "CHALLENGE_123";
submitScoreRequest.score = "1500";
submitScoreRequest.subscore = "0";
submitScoreRequest.metadata = "{\"lap_times\":[120]}";

auto onSubmitScore = [](const Challenge& challenge) {
    std::cout << "Score submitted to challenge: " << challenge.id << std::endl;
};

hiroClient->challengeSubmitScore(session, submitScoreRequest, onSubmitScore, onError);
```

### Joining/Leaving

Manage player participation:

```cpp
// Join an open challenge
ChallengeJoinRequest joinRequest;
joinRequest.challengeId = "CHALLENGE_456";

auto onChallengeJoin = [](const Challenge& challenge) {
    std::cout << "Joined challenge: " << challenge.id << std::endl;
};

hiroClient->challengeJoin(session, joinRequest, onChallengeJoin, onError);

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

auto onChallengeLeave = [](const Challenge& challenge) {
    std::cout << "Left challenge: " << challenge.id << std::endl;
};

hiroClient->challengeLeave(session, leaveRequest, onChallengeLeave, onError);
```

## Rewards

### Claiming Rewards

Claim earned rewards after challenge completion:

```cpp
ChallengeClaimRequest claimRequest;
claimRequest.challengeId = "CHALLENGE_123";

auto onChallengeClaim = [](const Challenge& challenge) {
    std::cout << "Claimed reward for challenge: " << challenge.id << std::endl;
};

hiroClient->challengeClaim(session, claimRequest, onChallengeClaim, onError);

// Refresh the economy system to see new rewards
hiroClient->economyRefresh(session, onEconomyRefresh, onError);
```