Skip to main content

Leaderboards

Compete across daily, weekly, monthly, and all-time periods. Submit scores, query rankings, and get sorted snapshots — all backed by SwiftData with CloudKit sync.

Periods

PrismLeaderboardPeriod

Submitting Scores

Submit Score
  • Creates a new record if none exists for the user/period pair
  • Updates the existing record if one exists
  • Returns the entry with its computed rank

Updating Scores

Update Score
Throws PrismGamificationError.leaderboardEntryNotFound if no record exists for the user in that period. Use submitScore for upsert behavior.

Querying the Leaderboard

Leaderboard Snapshot
Default limit is 100. Entries are sorted by score descending and ranked automatically.

Rank Lookup

Single User Rank

PrismLeaderboardEntry

Sendable, Comparable (by rank ascending), and Identifiable:
Sorting

PrismLeaderboardSnapshot

Resetting

Reset Period
Deletes all entries for the given period. Other periods are unaffected.

Leaderboard Events

Events
Events fire on both submitScore and updateScore.

Multi-Period Pattern

Submit to Multiple Periods
Submit scores to all relevant periods after each scoring event. Each period maintains its own independent rankings.