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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

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:

1
2
3
4
5
6
7

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:

1
2
3
4
5
6
7
8

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:

1
2
3
4
5
6

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:

1
2
3
4
5
6
7
8

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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

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

1
2
3
4
5

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)