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 #

Retrieve active challenges with optional filters:

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 challenges by name or category:

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}")