# Challenges

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

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

## Managing Challenges

### Creating a Challenge

Create new challenges with custom parameters:

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

var challenge = await hiro.challenge_create(session, create_request)
print("Challenge created: %s" % 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:

```gdscript
var list_request = ChallengeListRequest.new()
list_request.categories = ["racing"]
list_request.with_scores = true

var challenges = await hiro.challenges_list(session, list_request)
for challenge in challenges.challenges:
    print("Challenge: %s" % challenge.name)
```

### Searching Challenges

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

```gdscript
var search_request = ChallengeSearchRequest.new()
search_request.name = "weekly"
search_request.category = "racing"
search_request.limit = 5

var challenges = await hiro.challenges_search(session, search_request)
for challenge in challenges.challenges:
    print("Found challenge: %s" % challenge.name)
```

### Inviting Players

Add participants to existing challenges:

```gdscript
var invite_request = ChallengeInviteRequest.new()
invite_request.challenge_id = "CHALLENGE_123"
invite_request.invitees = ["player4"]

var challenge = await hiro.challenge_invite(session, invite_request)
print("Invited to challenge: %s" % challenge.id)
```

## Tracking Progress

### Submitting Scores

Update player standings in a challenge:

```gdscript
var submit_score_request = ChallengeSubmitScoreRequest.new()
submit_score_request.challenge_id = "CHALLENGE_123"
submit_score_request.score = 1500
submit_score_request.subscore = 0
submit_score_request.metadata = '{"lap_times":[120]}'

var challenge = await hiro.challenge_submit_score(session, submit_score_request)
print("Score submitted to challenge: %s" % challenge.id)
```

### Joining/Leaving

Manage player participation:

```gdscript
// Join an open challenge
var join_request = ChallengeJoinRequest.new()
join_request.challenge_id = "CHALLENGE_456"

var challenge = await hiro.challenge_join(session, join_request)
print("Joined challenge: %s" % challenge.id)


// Leave a challenge
var leave_request = ChallengeLeaveRequest.new()
leave_request.challenge_id = "CHALLENGE_456"

var challenge = await hiro.challenge_leave(session, leave_request)
print("Left challenge: %s" % challenge.id)
```

## Rewards

### Claiming Rewards

Claim earned rewards after challenge completion:

```gdscript
var claim_request = ChallengeClaimRequest.new()
claim_request.challenge_id = "CHALLENGE_123"

var challenge = await hiro.challenge_claim(session, claim_request)
print("Claimed reward for challenge: %s" % challenge.id)
```