#import <OFDistributedScoreEnumerator.h>
Public Member Functions | |
(BOOL) | - nextPage |
(BOOL) | - previousPage |
(void) | - jumpToPage: |
Static Public Member Functions | |
(void) | + setDelegate: |
(OFDistributedScoreEnumerator *) | + scoreEnumeratorForLeaderboard:pageSize:scoreDelta:startScore:delegate: |
Protected Attributes | |
NSInteger | lastPage |
NSMutableDictionary * | scores |
NSString * | leaderboardId |
OFRequestHandle * | activeRequest |
Properties | |
NSInteger | pageSize |
NSInteger | currentPage |
NSInteger | scoreDelta |
NSInteger | startScore |
BOOL | hasScores |
NSArray * | scores |
OFDistributedScoreEnumerator objects provide a convenient way to enumerate large sets of scores for a particular leaderboard that are evenly distributed at a given delta. This is useful if you want to show scores during gameplay to indicate the players progress. OFDistributedScoreEnumerator allows you to show interesting scores without having to download a prohibitively large score set. It relies heavily on server side caching so there are certain restrictions that must be followed.
Distributed score enumeration works by downloading one 'page' at a time. A page is simply a fixed-size array of scores. When initializing the enumerator you must in addition to the page size also supply the desired score delta. With a page size of 50 and a score delta of 1000 the first page would contain 50 scores as evenly distributed between 0 and 50000 as possible. Since you may not always want to start at 0 you may also specify a start score. The score delta and start score MUST be constant across game sessions to ensure efficient server caching. Distributed scores are only available for descending leaderboards and do not work for friends leaderboards.
For performance reasons distributed scores rely heavily on caching. It is important that you always use the same score delta and start score or this will break. The returned objects are OFAbridgedHighScores which is a smaller version of OFHighScores.
- (void) jumpToPage: | (NSInteger) | page |
Retrieve a given page of scores.
- (BOOL) nextPage |
Retrieve the next page of scores.
YES
if the next page is being downloaded or already exist in memory, NO
if the current page is already the last page. If the next page is already in memory this will return YES but the success delegate will first be called. If you show a loading screen depending on the result of this call, also check that hasScores returns false before showing the loading screen since the success delegate may already have been called.- (BOOL) previousPage |
Retrieve the previous page of scores.
YES
if the previous page is being downloaded, NO
if the current page is already the first page. If the previous page is already in memory this will return YES but the success delegate will first be called. If you show a loading screen depending on the result of this call, also check that hasScores returns false before showing the loading screen since the success delegate may already have been called+ (OFDistributedScoreEnumerator*) scoreEnumeratorForLeaderboard: | (OFLeaderboard *) | leaderboard | |
pageSize: | (NSInteger) | pageSize | |
scoreDelta: | (NSInteger) | scoreDelta | |
startScore: | (NSInteger) | startScore | |
delegate: | (id< OFDistributedScoreEnumeratorDelegate >) | delegate | |
Returns an initialized enumerator which will enumerate a set of scores of a given leaderboard trying to find scores evenly distributed with the given delta. The enumerator object will immediately fetch the first set of scores, but they will not be available when this method returns. Distributed scores are cached so the local players score will no be in any result sets for a while after it has been submitted.
Example: An enumerator with pageSize:5, scoreDelta: 1000, startScore: 5000 will try to find scores near the values 5000, 6000, 7000, 8000, 9000, 10000 for the first page and scores near the values 11000, 12000, 13000, 14000, 15000 for the second page.
IMPORTANT: pageSize and scoreDelta MUST be constant across all game sessions. Without this caching will fail and the server requests will start getting rejected.
leaderboard | The leaderboard to enumerator over |
pageSize | Number of scores contained in each page. Max 100. The returned page may contain less than 100 scores if not enough scores in the valid range were found. |
scoreDelta | The ideal difference in value between each score. ScoreDelta must be constant so that the server requests can be cached. Never initialize this value from the players score or any other dynamic source. Example: If passing in a scoreDelta of 50 the returned scores will have as close values as possible to the following (startScore + 50, startScore + 100, startScore + 150, ...) |
startScore | The desired value of the first score on the first page. This value must be constant so that the server requests can be cached. |
+ (void) setDelegate: | (id< OFDistributedScoreEnumeratorDelegate >) | delegate |
Set a delegate for all OFDistributedScoreEnumerator related actions. Must adopt the OFDistributedScoreEnumeratorDelegate protocol.
- (OFRequestHandle*) activeRequest [protected] |
- (NSInteger) lastPage [protected] |
- (NSString*) leaderboardId [protected] |
- (NSMutableDictionary*) scores [protected] |
- (NSInteger) currentPage [read, assign] |
The current page of scores contained in the scores property.
- (BOOL) hasScores [read, assign] |
YES
if the enumerator has a valid set of scores, NO
otherwise
- (NSInteger) pageSize [read, assign] |
The number of scores requested at one time.
- (NSInteger) scoreDelta [read, assign] |
The ideal delta between each score
- (NSArray*) scores [read, assign] |
The current page of scores. The score objects contained in the array are instances of the OFAbridgedHighScores class.
- (NSInteger) startScore [read, assign] |
The desired value of the first score on the first page.