Achievement Platform Overview

The Scorbit Achievement Platform enables game developers to create engaging achievement systems that reward players for accomplishing specific goals, tracking progress, and unlocking special badges. Achievements are defined via the Scorbit web portal and automatically synchronized to connected machines.

Key Concepts

Achievement Rules

Achievements are defined by one or more rules that specify unlock conditions. The SDK receives these rules as a nested array from the v2 API, enabling sophisticated multi-condition achievements.

Rule Type	Evaluated By	Description
MODE	SDK (in-session)	Mode completed
MODE_START	SDK (in-session)	Mode started
MODE_STACK	SDK (in-session)	Mode stacked
SCORE	SDK (in-session)	Score threshold reached
GAME_CODE	Game code	Custom game-specific logic
ACHIEVEMENT	Server (post-game)	Another achievement must be unlocked first
PROGRESS	Server (post-game)	Counter-based progress tracking

Multi-rule achievements require all evaluable rules to be satisfied simultaneously. For example, an achievement with both a MODE and SCORE rule requires the player to complete the mode and reach the target score.

Input Types

Achievements have two input types that determine how they track progress:

Input Type	Description
Limited	Count-based achievements with a target value (e.g., "Complete 10 multiballs")
Unlimited	Single-completion achievements (e.g., "Reach Wizard Mode")

Special Properties

Property	Description
Trophy	A special achievement that can be revoked if conditions change
Obscured	Hidden achievement with masked name/description until unlocked
Visible	Whether the achievement appears in lists before being unlocked

SDK Capabilities

The SDK provides comprehensive achievement management:

Real-Time Events

The SDK receives real-time notifications via WebSocket when achievements are:

• Unlocked - Player earns an achievement
• Locked - Trophy achievement is revoked
• Progress Updated - Incremental progress toward a limited achievement

Caching and Local Matching

For optimal performance, the SDK caches achievement definitions locally:

CC++Python

// Check if achievements are cached
if (sb_has_achievements(gs)) {
    size_t count = sb_get_cached_achievements_count(gs);
    printf("Cached %zu achievements\n", count);
}

// Check if achievements are cached
if (gs.hasAchievements()) {
    auto achievements = gs.getAchievements();
    std::cout << "Cached " << achievements.size() << " achievements\n";
}

# Check if achievements are cached
if gs.has_achievements():
    achievements = gs.get_achievements()
    print(f"Cached {len(achievements)} achievements")

Local Achievement Matching

The SDK can locally check which achievements a player might earn based on current game state. The SDK evaluates in-session rules (MODE, MODE_START, MODE_STACK, SCORE) and skips server-evaluated rules (ACHIEVEMENT, PROGRESS):

CC++Python

// Check mode-based achievements
const char* keys[32];
size_t count = sb_check_mode_achievements(gs, "multiball", "complete", user_id, keys, 32);

// Check score-based achievements
count = sb_check_score_achievements(gs, current_score, user_id, keys, 32);

// Check mode-based achievements
auto modeKeys = gs.checkModeAchievements("multiball", "complete", userId);

// Check mode+score combined achievements
auto combinedKeys = gs.checkModeAchievementsWithScore(
    "multiball", "complete", userId, currentScore);

// Check score-based achievements
auto scoreKeys = gs.checkScoreAchievements(currentScore, userId);

# Check mode-based achievements
mode_keys = gs.check_mode_achievements("multiball", "complete", user_id)

# Check score-based achievements
score_keys = gs.check_score_achievements(current_score, user_id)

Server Authority

Local matching is for UI anticipation only. The Scorbit server is the authoritative source for achievement unlocks. Server-evaluated rules (ACHIEVEMENT chains, PROGRESS counters) and global-scope post-game achievements are processed server-side after game completion. Always wait for server confirmation via events before showing "unlocked" status.

Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Game Code     │────▶│   Scorbit SDK    │────▶│  Scorbit API v2 │
│                 │     │  (Achievement    │     │                 │
│ - Mode changes  │     │   Manager)       │     │ - Rule engine   │
│ - Score updates │     │                  │     │ - Post-game eval│
│ - Event handler │◀────│ - Local cache    │◀────│ - Centrifugo WS │
└─────────────────┘     │ - Rule matching  │     └─────────────────┘
                        │ - Event dispatch │
                        └──────────────────┘

The SDK communicates with the Scorbit API v2 endpoints (/api/v2/achievements/...). Achievement definitions include nested rules that the SDK caches and evaluates locally for real-time matching. Server-side evaluation handles post-game achievements and cross-session rules.

Getting Started

1. Define Achievements - Create achievements in the Scorbit web portal
2. Initialize SDK - Achievements are fetched automatically on connection
3. Handle Events - Register callbacks for achievement notifications
4. Display Progress - Show achievement status and progress to players

Best Practices

• Pre-cache achievement icons for smooth display
• Use local matching for UI anticipation, but always confirm with server events
• Handle all three event types: unlocked, locked, and progress