# Challenges

**URL:** https://heroiclabs.com/docs/hiro/python/challenges/
**Summary:** Challenges enable social and competitive experiences by allowing players to compete in time-bound events with friends.
**Keywords:** challenges, player progression
**Categories:** hiro, python, 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 let players engage in competitive activities by:

* Competing against friends or other players.
* Tracking progress with leaderboards.
* Earning rewards based on participation and performance.

## Before You Start

Make sure you have:

* Unity project configured with Hiro SDK
* Nakama System integrated ([guide](../getting-started/_index.md))

## Managing Challenges

### Creating a Challenge

Create a new challenge with specific parameters:

```py
request = ChallengeCreateRequest()
request.template_id = "daily_race"
request.name = "Daily Race Challenge"
request.description = "Compete for top daily times"
request.invitees = ["player2", "player3"]
request.open = True
request.max_scores = 3
request.start_delay_sec = 0  # Start immediately
request.duration_sec = 86400  # 24 hours
request.max_participants = 10
request.category = "racing"

challenge = await hiro_client.challenge_create(request)
print(f"Challenge created: {challenge.name}")
```

**Parameters:**

* `open`: Allow any player to join without invitation.
* `max_scores`: Maximum submissions per player.
* `duration_sec`: `0` indicates unlimited duration.

### Listing Challenges

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

```py
request = ChallengeListRequest()
request.categories = ["racing"]
request.with_scores = True

challenges = await hiro_client.challenges_list(request)
for challenge in challenges.challenges:
    print(f"Challenge: {challenge.name}")
```

### Searching Challenges

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

```py
request = ChallengeSearchRequest()
request.name = "weekly"
request.category = "racing"
request.limit = 5

challenges = await hiro_client.challenges_search(request)
for challenge in challenges.challenges:
    print(f"Found challenge: {challenge.name}")
```

### Inviting Players

Invite additional participants to existing challenges:

```py
request = ChallengeInviteRequest()
request.challenge_id = "CHALLENGE_123"
request.invitees = ["player4"]

challenge = await hiro_client.challenge_invite(request)
print(f"Invited to challenge: {challenge.id}")
```

## Tracking Progress

### Submitting Scores

Update standings by submitting scores:

```py
request = ChallengeSubmitScoreRequest()
request.challenge_id = "CHALLENGE_123"
request.score = 1500
request.subscore = 0
request.metadata = '{"lap_times":[120]}'

challenge = await hiro_client.challenge_submit_score(request)
print(f"Score submitted to challenge: {challenge.id}")
```

### Joining or Leaving Challenges

Manage participation status:

```py
# Join a challenge
join_request = ChallengeJoinRequest()
join_request.challenge_id = "CHALLENGE_456"

challenge = await hiro_client.challenge_join(join_request)
print(f"Joined challenge: {challenge.id}")

# Leave a challenge
leave_request = ChallengeLeaveRequest()
leave_request.challenge_id = "CHALLENGE_456"

challenge = await hiro_client.challenge_leave(leave_request)
print(f"Left challenge: {challenge.id}")
```

## Claiming Rewards

### Claiming Challenge Rewards

Claim rewards after completing a challenge:

```py
request = ChallengeClaimRequest()
request.challenge_id = "CHALLENGE_123"

challenge = await hiro_client.challenge_claim(request)
print(f"Claimed reward for challenge: {challenge.id}")
```