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.

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)

Managing Challenges #

Creating a Challenge #

Create a new challenge with specific parameters:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
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:

1
2
3
4
5
6
7
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:

1
2
3
4
5
6
7
8
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:

1
2
3
4
5
6
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:

1
2
3
4
5
6
7
8
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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# 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:

1
2
3
4
5
request = ChallengeClaimRequest()
request.challenge_id = "CHALLENGE_123"

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

Heroic Cloud