Leaderboard Core

LeaderboardCore is a lightweight, logic-only component that powers real-time score tracking via Snapchat's leaderboard system. This component exposes all core leaderboard APIs — including initialization, score submission, and user rank queries — while letting developers handle their own custom visuals and game logic.

Usage

In the Scene Panel:

1. Add the Leaderboard Core component to the scene hierarchy.
2. Use your own script with Leaderboard Core as an input to interact with the component.
3. Use the provided APIs to submit scores and subscribe to updates.

Subscribing on score updates

//@input Component.ScriptComponent Leaderboard

script.Leaderboard.onLeaderboardRecordsUpdated.add(
  (leaderboardRecordsWrapper) => {
    print(leaderboardRecordsWrapper.userRecords);
    print(leaderboardRecordsWrapper.currentUserRecord);
  }
);

Submitting score

//@input Component.ScriptComponent Leaderboard

/*
For example some custom logic for calculating score
*/

let score = Math.ceil(Math.random() * 100); // creating random score

script.Leaderboard.submitScoreAsync(score)
script.Leaderboard.onScoreSubmittedSuccess.addOnce(() => {
    print("Score submitted successfully")
})

Using async functions

//@input Component.ScriptComponent Leaderboard

script.Leaderboard.getLeaderboard()
  .then((leaderboard) => {
    print('Leaderboard loaded');
    print('Leaderboard ' + leaderboard);
  })
  .catch(() => {
    print('Error loading leaderboard');
  });

API

submitScore(score: number) : void

Submits score to leaderboard. This method does not wait for the score to be submitted. Check onScoreSubmittedSuccess and submitScoreAsync.

---

submitScoreAsync(score: number) : Promise<void>

Submits score to leaderboard asynchronously. The Promise is resolved once the score is submitted successfully, it is rejected in case of failure.

---

initializeWithOptions(leaderboardInitializationOptions: LeaderboardInitializationOptions) : void

Initializes leaderboard from code.

Usage example

//@input Component.ScriptComponent Leaderboard

script.Leaderboard.initializeWithOptions({
  name: 'name',
  userType: Leaderboard.UsersType.Friends,
  scoreOrdering: Leaderboard.OrderingType.Descending,
  userLimit: 10,
  scoreResetInterval: script.Leaderboard.ScoreResetIntervalOption.Week,
  useTimer: true,
  leaderboardStartDate: '9/27/2024',
});

const tap = script.createEvent('TapEvent');
tap.bind(() => {
  script.Leaderboard.submitScore(Math.ceil(Math.random() * 100));
});

Declarations

export type LeaderboardInitializationOptions = {
    name: string;
    userType: Leaderboard.UsersType;
    scoreOrdering: Leaderboard.OrderingType;
    scoreResetInterval: ScoreResetIntervalOption;
    userLimit: number;
    useTimer: boolean;
    leaderboardStartDate?: string; // format "mm/dd/yyyy"
};

export enum ScoreResetIntervalOption {
    Day = 0,
    Week = 1,
    Month = 2,
    Year = 3
}

---

async getLeaderboard() : Promise<Leaderboard>

Returns Leaderboard object.

---

async getCurrentUser() : Promise<SnapchatUser>

Returns the SnapchatUser object for the current user.

---

async getCurrentUserBitmoji() : Promise<Texture>

Returns texture with current user bitmoji sticker.

---

API Events

onLeaderboardRecordsUpdated : Event<LeaderboardRecordsWrapper>

Triggers when any records are updated and returns a LeaderboardRecordsWrapper object. This object contains two properties:

• userRecords: UserRecord[] – An array of records for all players.
• currentUserRecord: UserRecord | null – The record for the current user, or null if none exists.

---

onScoreSubmittedSuccess : Event<LeaderboardRecordsWrapper>

Triggers when a score has been submitted successfully and returns a LeaderboardRecordsWrapper object like onLeaderboardRecordsUpdated

---

Restrictions

When using Leaderboard Lenses, some APIs will be restricted in order to protect the user's privacy. For the full list of restricted APIs, see Privacy Restrictions.