View as Markdown

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 #

  • Unity project set up with Hiro SDK
  • Nakama System integrated (guide)

Initializing the Challenges System #

1
2

var challengesSystem = new ChallengesSystem(logger, nakamaSystem);
systems.Add(challengesSystem);

Managing Challenges #

Creating a Challenge #

Create new challenges with custom parameters:

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

var newChallenge = await challengesSystem.CreateChallengeAsync(
    templateId: "daily_race",
    name: "Daily Race Challenge",
    description: "Compete for top daily times",
    invitees: new[] {"player2", "player3"},
    open: true,
    maxScores: 3,
    startDelaySec: 0, // Start immediately
    durationSec: 86400, // 24 hours
    maxParticipants: 10,
    category: "racing"
);

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

var racingChallenges = await challengesSystem.ListChallengesAsync(
categories: new[] {"racing"}
);

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

var results = await challengesSystem.SearchChallengesAsync(
name: "weekly",
category: "racing",
limit: 5
);

Inviting Players #

Add participants to existing challenges:

1
2
3
4

await challengesSystem.InviteChallengeAsync(
challengeId: "CHALLENGE_123",
userIds: new[] {"player4"}
);

Tracking Progress #

Submitting Scores #

Update player standings in a challenge:

1
2
3
4
5
6

await challengesSystem.SubmitChallengeScoreAsync(
challengeId: "CHALLENGE_123",
score: 1500,
subscore: 0,
metadata: "{"lap_times":[120]}"
);

Joining/Leaving #

Manage player participation:

1
2
3
4
5

// Join an open challenge
var joinedChallenge = await challengesSystem.JoinChallengeAsync("CHALLENGE_456");

// Leave a challenge
var leftChallenge = await challengesSystem.LeaveChallengeAsync("CHALLENGE_456");

Rewards #

Claiming Rewards #

Claim earned rewards after challenge completion:

1
2
3
4

var claimedChallenge = await challengesSystem.ClaimChallengeAsync("CHALLENGE_123");

// Refresh economy system to see new rewards
await economySystem.RefreshAsync();

Additional information #