New SDK Preview

This section is a preview of the new SDK. The new SDK is still in development, and we are actively working on improving it. We value your feedback, so if you have any questions or suggestions, please reach out to us. If you are not using the new SDK, please refer to another documentation section.

Battle Pass¶

Balancy provides a comprehensive Battle Pass system that allows developers to create engaging progression-based events. Battle Pass is a specialized type of Game Event that features level-based progression, multiple reward lines (tracks), and timed mechanics. Players earn progression points to advance through levels and claim rewards from different tracks.

Battle Pass Structure¶

The Battle Pass system is organized hierarchically:

Battle Pass Game Event: A time-limited event containing battle pass configuration
Battle Pass Config: Defines progression requirements, levels, and reward lines
Reward Lines: Different tracks (e.g., Free Track, Premium Track) with rewards for each level
Progression System: Score-based advancement through levels
Reward Status: Tracks what rewards are available, claimed, or locked

Accessing Battle Pass Events¶

Battle Pass events are a subtype of Game Events. To access active battle pass events:

C#TypeScript

var smartInfo = Balancy.Profiles.System.SmartInfo;
var activeGameEvents = smartInfo.GameEvents;

foreach (var eventInfo in activeGameEvents)
{
    if (eventInfo.GameEvent is Balancy.Models.LiveOps.BattlePass.GameEvent battlePassEvent)
    {
        Debug.Log($"Battle Pass: {battlePassEvent.Name}");
        var config = battlePassEvent.Config;
        // Work with battle pass...
    }
}

const smartInfo = Balancy.Profiles.system.smartInfo;
const activeGameEvents = smartInfo.gameEvents;

for (let i = 0; i < activeGameEvents.count; i++) {
  const eventInfo = activeGameEvents.get(i);
  const gameEvent = eventInfo.gameEvent;
  if (gameEvent instanceof LiveOpsBattlePassGameEvent) {
    console.log(`Battle Pass: ${gameEvent.name?.value}`);
    const config = gameEvent.config;
    // Work with battle pass...
  }
}

Battle Pass Progress Information¶

To access player's progress in battle passes:

C#TypeScript

var battlePassesInfo = Balancy.Profiles.System.BattlePassesInfo;
var battlePassInfo = battlePassesInfo.FindBattlePassInfo(battlePassEvent);

if (battlePassInfo != null)
{
    var currentLevel = battlePassInfo.Level;
    var currentScore = battlePassInfo.Scores;
    var isFinished = battlePassInfo.Finished;

    Debug.Log($"Level: {currentLevel}, Score: {currentScore}");
}

const battlePassesInfo = Balancy.Profiles.system.battlePassesInfo;
const battlePassInfo = battlePassesInfo.findBattlePassInfo(battlePassEvent);

if (battlePassInfo) {
    const currentLevel = battlePassInfo.level;
    const currentScore = battlePassInfo.scores;
    const isFinished = battlePassInfo.finished;

    console.log(`Level: ${currentLevel}, Score: ${currentScore}`);
}

Battle Pass Configuration¶

The Battle Pass configuration contains essential information about progression and rewards:

C#TypeScript

var config = battlePassEvent.Config;
if (config != null)
{
    var battlePassName = config.Name;
    var progressionType = config.Type;
    var progressionItem = config.ProgressionItem; // Item used for scoring
    var levelScores = config.Scores; // Score requirements for each level
    var rewardLines = config.Rewards; // Available reward tracks

    Debug.Log($"Battle Pass: {battlePassName}");
    Debug.Log($"Progression Type: {progressionType}");
    Debug.Log($"Total Levels: {levelScores.Length}");
}

const config = battlePassEvent.config;
if (config) {
    const battlePassName = config.name?.value;
    const progressionType = config.type;
    const progressionItem = config.progressionItem; // Item used for scoring
    const levelScores = config.scores; // Score requirements for each level
    const rewardLines = config.rewards; // Available reward tracks

    console.log(`Battle Pass: ${battlePassName}`);
    console.log(`Progression Type: ${progressionType}`);
    console.log(`Total Levels: ${levelScores.length}`);
}

Working with Reward Lines¶

Battle Pass reward lines represent different tracks (e.g., Free, Premium) that players can progress through:

C#TypeScript

var rewardLines = config.Rewards;

foreach (var rewardLine in rewardLines)
{
    if (rewardLine != null)
    {
        var lineName = rewardLine.Name;
        var accessItem = rewardLine.AccessItem; // Item required to unlock this track
        var rewards = rewardLine.Rewards; // Rewards for each level

        Debug.Log($"Reward Line: {lineName}");
        Debug.Log($"Access Item: {accessItem?.Name}");
        Debug.Log($"Total Rewards: {rewards.Length}");
    }
}

const rewardLines = config.rewards;

rewardLines.forEach((rewardLine, lineIndex) => {
    if (rewardLine) {
        const lineName = rewardLine.name?.value;
        const accessItem = rewardLine.accessItem; // Item required to unlock this track
        const rewards = rewardLine.rewards; // Rewards for each level

        console.log(`Reward Line: ${lineName}`);
        console.log(`Access Item: ${accessItem?.name?.value}`);
        console.log(`Total Rewards: ${rewards.length}`);
    }
});

Reward Status and Claiming¶

Each reward line has progress information that tracks availability and claim status:

C#TypeScript

var progressInfos = battlePassInfo.ProgressInfo;

for (int lineIndex = 0; lineIndex < progressInfos.Count; lineIndex++)
{
    var progressInfo = progressInfos[lineIndex];
    var isTrackAvailable = progressInfo.Available; // Player has access to this track

    // Check each level's reward status
    for (int levelIndex = 0; levelIndex < levelScores.Length; levelIndex++)
    {
        var rewardStatus = progressInfo.GetRewardStatus(levelIndex);

        switch (rewardStatus)
        {
            case Balancy.Data.SmartObjects.BattlePassRewardStatus.NotAvailable:
                Debug.Log($"Level {levelIndex + 1}: Not Available");
                break;
            case Balancy.Data.SmartObjects.BattlePassRewardStatus.Available:
                Debug.Log($"Level {levelIndex + 1}: Ready to Claim!");
                break;
            case Balancy.Data.SmartObjects.BattlePassRewardStatus.Claimed:
                Debug.Log($"Level {levelIndex + 1}: Already Claimed");
                break;
        }
    }
}

const progressInfos = battlePassInfo.progressInfo;

for (let lineIndex = 0; lineIndex < progressInfos.count; lineIndex++) {
    const progressInfo = progressInfos.get(lineIndex);
    const isTrackAvailable = progressInfo.available; // Player has access to this track

    // Check each level's reward status
    for (let levelIndex = 0; levelIndex < levelScores.length; levelIndex++) {
        const rewardStatus = progressInfo.getRewardStatus(levelIndex);

        switch (rewardStatus) {
            case SmartObjectsBattlePassRewardStatus.NotAvailable:
                console.log(`Level ${levelIndex + 1}: Not Available`);
                break;
            case SmartObjectsBattlePassRewardStatus.Available:
                console.log(`Level ${levelIndex + 1}: Ready to Claim!`);
                break;
            case SmartObjectsBattlePassRewardStatus.Claimed:
                console.log(`Level ${levelIndex + 1}: Already Claimed`);
                break;
        }
    }
}

Claiming Rewards¶

To claim available rewards from the battle pass:

C#TypeScript

// Claim reward for specific level and reward line
bool claimSuccess = progressInfo.ClaimReward(levelIndex);

if (claimSuccess)
{
    Debug.Log($"Successfully claimed reward for level {levelIndex + 1}!");
}
else
{
    Debug.Log("Failed to claim reward - not available or already claimed");
}

// Claim reward for specific level and reward line
const claimSuccess = progressInfo.claimReward(levelIndex);

if (claimSuccess) {
    console.log(`Successfully claimed reward for level ${levelIndex + 1}!`);
} else {
    console.log("Failed to claim reward - not available or already claimed");
}

Time Management¶

Battle Pass events have time-based mechanics. Use these methods to check timing:

C#TypeScript

// Check if battle pass is currently active
bool isActive = battlePassEvent.GetSecondsLeftBeforeDeactivation() > 0;

// Get remaining time
int secondsLeft = battlePassEvent.GetSecondsLeftBeforeDeactivation();

// Get time until activation (if not yet started)
int secondsUntilStart = battlePassEvent.GetSecondsBeforeActivation(false);

Debug.Log($"Active: {isActive}");
Debug.Log($"Time left: {secondsLeft} seconds");

// Check if battle pass is currently active
const isActive = battlePassEvent.getSecondsLeftBeforeDeactivation() > 0;

// Get remaining time
const secondsLeft = battlePassEvent.getSecondsLeftBeforeDeactivation();

// Get time until activation (if not yet started)
const secondsUntilStart = battlePassEvent.getSecondsBeforeActivation(false);

console.log(`Active: ${isActive}`);
console.log(`Time left: ${secondsLeft} seconds`);

Battle Pass Progression Types¶

Battle Pass supports different progression mechanics:

Progression Type	Description
Collect	Players earn points by collecting specific items
Spend	Players earn points by spending specific items
Custom	Custom progression logic defined by your game

Best Practices¶

Check event timing before displaying battle pass UI
Validate reward status before allowing claim attempts
Handle track access - check if players have access to premium tracks
Subscribe to updates to keep progress synchronized
Provide clear progression feedback showing current level and next level requirements
Display time remaining prominently to create urgency
Handle edge cases like finished battle passes or expired events
Cache battle pass data temporarily but refresh on updates
Implement proper error handling for failed reward claims
Show preview of upcoming rewards to motivate progression

Using these methods, you can create an engaging Battle Pass system that encourages regular player engagement through time-limited, level-based progression with multiple reward tracks.