Resolution
Because the Photon Engine Leaderboard API documentation is ambiguous regarding indexing, you must treat the page parameter as zero-based for initial implementation, as this is the industry standard for offset-based pagination in backend engines. When the requested page exceeds the total available pages, the API typically returns an empty result set ([]) rather than an error code.
Likely Behavior vs. Confirmed Facts
While the API's internal logic is not explicitly documented, the following behavior is observed in similar high-scale leaderboard implementations:
- Indexing: Most engines calculate the offset as
page * pageSize. If page=0 returns the first set of results, it is zero-based. If page=1 returns the first set, it is one-based.
- Out-of-Bounds Requests: Requesting a page beyond the total count usually results in a successful HTTP 200 response with an empty list, as the query technically executes but finds no matching rows for that offset.
- Score Filtering:
minScore and maxScore filters are generally applied at the database query level before pagination occurs. This ensures that the page index refers to the filtered subset, not the global list.
Verification Steps
To resolve the ambiguity for your specific environment, execute these three scoped tests:
- Test Indexing: Request
page=0, pageSize=1 and page=1, pageSize=1. If the results are different and page=0 contains the top-ranked player, the API is zero-based.
- Test Bounds: Request a
page number significantly higher than your total user count (e.g., page=999999). Verify if the response is an empty array or a 404/400 error.
- Test Filter Consistency: Apply a narrow
minScore and maxScore range that you know contains only 5 players. Request page=0, pageSize=10. If you receive exactly 5 players, the filter is applied before pagination.
Required Diagnostic Detail
To provide a definitive confirmation on filter consistency, please specify the underlying data store (e.g., Redis, MongoDB, or a relational SQL DB) being used for the leaderboard, as pagination behavior differs significantly between memory-store offsets and disk-based queries.
photonengine