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 #

  • Dart 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 createRequest = ChallengeCreateRequest();
createRequest.templateId = "daily_race";
createRequest.name = "Daily Race Challenge";
createRequest.description = "Compete for top daily times";
createRequest.invitees = ["player2", "player3"];
createRequest.open = true;
createRequest.maxScores = 3;
createRequest.startDelaySec = 0; // Start immediately
createRequest.durationSec = 86400; // 24 hours
createRequest.maxParticipants = 10;
createRequest.category = "racing";

var challenge = await hiro.challengeCreate(session, createRequest);
print("Challenge created: ${challenge.name}");

Parameters:

  • open: Allow any player to join without an invitation
  • maxScores: Max submissions per player
  • durationSec: 0 = unlimited duration

Listing Challenges #

Get active challenges with optional filtering:

1
2
3
4
5
6
7
8

var listRequest = ChallengeListRequest();
listRequest.categories = ["racing"];
listRequest.withScores = true;

var challenges = await hiro.challengesList(session, listRequest);
challenges.challenges?.forEach((challenge) {
  print("Challenge: ${challenge.name}");
});

Searching Challenges #

Find public challenges by name/category:

1
2
3
4
5
6
7
8
9

var searchRequest = ChallengeSearchRequest();
searchRequest.name = "weekly";
searchRequest.category = "racing";
searchRequest.limit = 5;

var challenges = await hiro.challengesSearch(session, searchRequest);
challenges.challenges?.forEach((challenge) {
  print("Found challenge: ${challenge.name}");
});

Inviting Players #

Add participants to existing challenges:

1
2
3
4
5
6

var inviteRequest = ChallengeInviteRequest();
inviteRequest.challengeId = "CHALLENGE_123";
inviteRequest.invitees = ["player4"];

var challenge = await hiro.challengeInvite(session, inviteRequest);
print("Invited to challenge: ${challenge.id}");

Tracking Progress #

Submitting Scores #

Update player standings in a challenge:

1
2
3
4
5
6
7
8

var submitScoreRequest = ChallengeSubmitScoreRequest();
submitScoreRequest.challengeId = "CHALLENGE_123";
submitScoreRequest.score = 1500;
submitScoreRequest.subscore = 0;
submitScoreRequest.metadata = '{"lap_times":[120]}';

var challenge = await hiro.challengeSubmitScore(session, submitScoreRequest);
print("Score submitted to challenge: ${challenge.id}");

Joining/Leaving #

Manage player participation:

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

// Join an open challenge
var joinRequest = ChallengeJoinRequest();
joinRequest.challengeId = "CHALLENGE_456";

var challenge = await hiro.challengeJoin(session, joinRequest);
print("Joined challenge: ${challenge.id}");

// Leave a challenge
var leaveRequest = ChallengeLeaveRequest();
leaveRequest.challengeId = "CHALLENGE_456";

var challenge = await hiro.challengeLeave(session, leaveRequest);
print("Left challenge: ${challenge.id}");

Rewards #

Claiming Rewards #

Claim earned rewards after challenge completion:

1
2
3
4
5

var claimRequest = ChallengeClaimRequest();
claimRequest.challengeId = "CHALLENGE_123";

var challenge = await hiro.challengeClaim(session, claimRequest);
print("Claimed reward for challenge: ${challenge.id}");