Leaderboards API Reference¶

IntelliVerseX leaderboard features combine Nakama leaderboards (scores, metadata, expiry, sort order) with Unity Games SDK helpers (IVXGLeaderboardManager) that call server RPCs (submit_score_and_sync, get_all_leaderboards, get_time_period_leaderboard). Hiro event leaderboards are a separate surface for time-limited competitions.

Unity Games SDK namespace¶

using IntelliVerseX.Games.Leaderboard;

Nakama leaderboard concepts¶

SubmitScoreAsync (Unity)¶

Behavior: Resolves API user id, Nakama user id, gameId, and deviceId, then calls RPC submit_score_and_sync. Maintains an internal win streak counter on successful submissions.

Example:

var response = await IVXGLeaderboardManager.SubmitScoreAsync(
    score: 15000,
    subscore: 0,
    metadata: new Dictionary<string, string> {
        { "mode", "weekly_tournament" },
        { "build", "1.2.0" }
    });

if (response != null && response.success) {
    Debug.Log("Score accepted");
} else {
    Debug.LogWarning(response?.error ?? "Submit failed");
}

Error handling: Returns null on session failure, missing ids, RPC errors, or exceptions. Subscribe to IVXGLeaderboardManager.OnError for diagnostics.

GetLeaderboardAsync (aggregate fetch)¶

The Unity SDK exposes GetAllLeaderboardsAsync rather than a single-id GetLeaderboardAsync:

Fallback: If the aggregate RPC fails, the manager falls back to per-period RPC get_time_period_leaderboard for daily, weekly, monthly, alltime × game / global.

Example:

var all = await IVXGLeaderboardManager.GetAllLeaderboardsAsync(limit: 25);
if (all != null && all.success) {
    var topAllTime = all.alltime?.records;
    // Bind to UI
}

For a Nakama-native read by explicit id (other engines), use the client’s list-records API or your server RPC.

GetAroundMeAsync (player-relative records)¶

Nakama supports owner / cursor APIs to fetch records around the current player. The Unity IVXGLeaderboardManager does not expose a method named GetAroundMeAsync; instead:

• Use GetPlayerRankAsync(bool global) for rank summary.
• Use GetPlayerBestScoreAsync(bool global) for best score from fetched data.
• For true “around me” windows, call Nakama ListLeaderboardRecordsAroundOwnerAsync with your session and target leaderboard id (from IVXGAllLeaderboardsResponse / server config).

Example (conceptual Nakama):

// After resolving leaderboardId from server config or RPC response
var around = await client.ListLeaderboardRecordsAroundOwnerAsync(
    session, leaderboardId, session.UserId, limit: 10);

DeleteScoreAsync¶

Score deletion is server-dependent (permissions and hooks). Many games never delete competitive scores; for test accounts, use Nakama console or a privileged RPC. If your project adds delete_score RPC, wrap it the same way as submit_score_and_sync. Document the RPC id in your game backend.

Additional Unity static API¶

Events:

Metadata usage¶

• Keep metadata small (string keys/values or compact JSON).
• Use it for display (username hints) or segmentation (mode), not large blobs (use storage).
• Unity RPC path passes metadata through to the server payload as serialized fields.

Hiro event leaderboards¶

For limited-time events, use the Hiro integration:

• Type: IVXEventLeaderboardSystem (ListAsync, etc.) under Assets/_IntelliVerseXSDK/Hiro/.
• See Hiro API and Hiro integration guide.

Event leaderboards complement Nakama period leaderboards; configure both in backend and keep ids documented per game.

Cross-platform notes¶

Always authenticate before submit/fetch.

See also¶

• Leaderboard module
• Leaderboard demo
• Hiro API