# Challenges **URL:** https://heroiclabs.com/docs/hiro/concepts/challenges/ **Summary:** Challenges are player-driven events, encouraging players to invite friends while fostering community and friendly rivalry. **Keywords:** challenges, hiro **Categories:** hiro, challenges, concepts --- # Challenges ## Overview Challenges are player-driven competitions that encourage players to invite their friends to compete for prizes and prestige, boosting retention and engagement in your game. Developers pre-configure Challenge templates on the server, each with specific rules and scoring systems. Players then choose from these templates and may optionally customize certain parameters like participant count and duration before inviting their friends to play with them. Add Challenges to your game to create dynamic social competitions and foster a sense of community and friendly rivalry, providing replayable content that keeps players engaged over time. {{< note "outline" "" hide_icon>}} Ready to try it yourself? Explore the [Challenges sample project](../../../sample-projects/unity/hiro-challenges/). {{}} ## Use Cases Game developers are often tasked with keeping players engaged beyond single sessions. Players complete content and move on, resulting in declining retention rates and stagnant growth. Challenges transform this dynamic by turning score-based or timed solo gameplay into shared social experiences. Instead of playing alone and leaving, players now have reasons to return, compete, and bring friends along. ### Speedrunning Challenges A player has just finished your platformer's campaign - instead of uninstalling, they can now challenge friends to beat their best completion time on their favorite stage. This creates a cycle where completed content becomes the foundation for new competitive experiences. Winners might earn profile badges that showcase their skills and motivate others to challenge them. ### Kill Streak Challenges Rather than players having isolated matches that only they remember, these challenges let them prove their skills in friendly competitions. Players compete to see who can achieve the highest damage numbers or most KOs across multiple matches, with top performers earning exclusive rewards that demonstrate their prowess. Every Challenge transforms individual achievements into shared experiences, incentivizng players to return and introduce new players to your game. ## Key Terms - **ChallengesConfig:** The configuration object that defines all available Challenges, each with its own rules, rewards, and properties (see JSON example below). - **Reward Tiers:** Structured brackets that determine what rewards players receive based on their final rank or score, if any. - **Operators:** Determines how scores are evaluated by default (see Operators table). Can be overriden when making a score update request. - **Player Limits:** Minimum and maximum player counts for each Challenge, supporting either duo (two players) or group (more than two players) competitions. - **Duration and Scheduling:** Challenges can be scheduled with flexible start delays, durations and a min/max amount of participants. - **Additional Properties:** Custom metadata fields for each Challenge. Consider adding these to enable deep integration with game lore or progression systems e.g., image URLs. ## Challenges vs Event Leaderboards While both Challenges and Event Leaderboards provide competitive gameplay features, they serve different purposes and have distinct characteristics. Challenges are designed for on-demand social competitions where players control when, how, and with whom they compete. Event Leaderboards, on the other hand, are structured systems for large-scale competitive events with automated matchmaking and scheduled tournaments. {{< table name="gdk.concepts.challenges.challenges-comparison" >}} The key distinction is that Challenges prioritize social relationships and community building over competitive ranking systems. ## Configuring Challenges ### Challenge Properties {{< table name="gdk.concepts.challenges.challenge" >}} ### Challenge Reward Tier {{< table name="gdk.concepts.challenges.challenge-reward-tier" >}} ### Duration {{< table name="gdk.concepts.challenges.duration" >}} ### Players {{< table name="gdk.concepts.challenges.players" >}} ### Operators {{< table name="gdk.concepts.challenges.challenges-operators" >}} ### Example: Challenges JSON The JSON schema defines a `challenges` object which _must contain an individual object for each challenge_ you wish to define in the system. You can configure as few or as many challenges as needed for your desired gameplay. {{< table name="gdk.concepts.challenges.challenges-system" >}} The following JSON showcases the customization parameters you can use to configure the default user experience for a particular Challenge. ```json { "challenges": { "speed_runner": { "reward_tiers": [ { "rank_min": 1, "rank_max": 3, "reward": { "guaranteed": { "currencies": { "coins": { "min": 300 }, "gems": { "min": 15 } }, "items": { "speed_boots": { "min": 1, "max": 1, "multiple": 1 }, "time_crystal": { "min": 1, "max": 1, "multiple": 1 } } } } }, { "rank_min": 4, "rank_max": 10, "reward": { "guaranteed": { "currencies": { "coins": { "min": 150 }, "gems": { "min": 8 } }, "items": { "speed_boots": { "min": 1, "max": 1, "multiple": 1 } } } } } ], "additional_properties": { "description": "Complete the dungeon in record time", "category": "speedrun", "difficulty": "expert", "dungeon_id": "crystal_caverns" }, "max_num_score": 3, "start_delay_max_sec": 60, "ascending": false, "operator": "best", "duration": { "min_sec": 1800, "max_sec": 3600 }, "players": { "min": 2, "max": 100 } } } } ``` ## Additional Information - [Hiro Challenges sample project](../../../sample-projects/unity/hiro-challenges) - [Mage Mayhem sample project](../../../sample-projects/games/mage-mayhem)