|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectgreenfoot.PlayerData
public class PlayerData
The PlayerData class can be used to store data permanently on a server, and to share this data between different users, when the scenario runs on the Greenfoot web site. This can be used to implement shared high score tables or other examples of shared data.
Storage is only available when the current user is logged in on the Greenfoot site, so for some users storage will not be available. Always use PlayerData.isStorageAvailable() to check before accessing the player data.
A typical code snippet for storing a high score is as follows:
if (PlayerData.isStorageAvailable()) { PlayerData myData = PlayerData.getMyData(); if (newScore > myData.getScore()) { myData.setScore(newScore); myData.store(); // write back to server } }
Methods to retrieve user data include getting data for the current user (getMyData()), the top scorers (e.g. getTop(10) for the top 10), and data for users with scores near my own score (e.g. getNearby(10)).
The data that can be stored for each player consists of a score, 10 additional general purpose integers, and 10 strings. In addition, the user name and user's image can be retrieved from the player data.
For testing purposes, while running within Greenfoot (not on the web site), the player name can be set in the preferences (CTRL-SHIFT-P / CMD-SHIFT-P). This allows to simulate different players during development. When running on the web site, the player name is the user name used to log in to the site.
Field Summary | |
---|---|
static int |
NUM_INTS
The number of integers that can be stored |
static int |
NUM_STRINGS
The number of Strings that can be stored |
static int |
STRING_LENGTH_LIMIT
The maximum number of characters that can be stored in each String |
Method Summary | |
---|---|
int |
getInt(int index)
Get the value of the int at the given index (0 to NUM_INTS-1, inclusive). |
static PlayerData |
getMyData()
Get the data stored for the current user. |
static java.util.List |
getNearby(int maxAmount)
Get a sorted list of the PlayerData items for this scenario surrounding the current user. |
int |
getRank()
Get the players overall rank for this scenario. |
int |
getScore()
Get the player's score. |
java.lang.String |
getString(int index)
Get the value of the String at the given index (0 to NUM_STRINGS-1, inclusive). |
static java.util.List |
getTop(int maxAmount)
Get a sorted list of the PlayerData items for this scenario, starting at the top. |
GreenfootImage |
getUserImage()
Return an image of the user. |
java.lang.String |
getUserName()
Get the username of the user that this storage belongs to. |
static boolean |
isStorageAvailable()
Indicate whether storage is available. |
void |
setInt(int index,
int value)
Set the value of the int at the given index (0 to NUM_INTS-1, inclusive). |
void |
setScore(int score)
Set the player's score. |
void |
setString(int index,
java.lang.String value)
Get the value of the String at the given index (0 to NUM_STRINGS-1, inclusive). |
boolean |
store()
Store the data to the server. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static final int NUM_INTS
public static final int NUM_STRINGS
public static final int STRING_LENGTH_LIMIT
Method Detail |
---|
public java.lang.String getUserName()
public int getInt(int index)
The default value is zero.
public java.lang.String getString(int index)
The default value is the empty String.
public void setInt(int index, int value)
Note that to store this value permanently, you must later call store().
public void setString(int index, java.lang.String value)
Note that to store this value permanently, you must later call store().
public int getScore()
public void setScore(int score)
Note that this really does set the player's score. If you want to record only the player's highest score, you must code that yourself, using something like:
if (latestScore > userData.getScore()) { userData.setScore(latestScore); }Without some code like this, you'll always overwrite the player's previous score.
Note that to store this value permanently, you must later call store().
public int getRank()
The player with the highest score will return 1, the player with the second highest score will return 2, and so on. Players with equal scores will get equal ranks, so rank will not necessarily be unique. To find the rank, scores are sorted in descending order (highest score first). If your scores need to be lowest-first, one trick is to store them as negative numbers.
If the rank is unavailable (e.g. because the data hasn't been stored yet), this function will return -1.
public static boolean isStorageAvailable()
Storage is unavailable if the scenario is run as an applet outside the Greenfoot website, or as a stand-alone application, or if the user is not logged in to the Greenfoot website. This last case is very common, so you should check this function before attempting to use the other static storage functions. If this function returns false, your scenario should proceed without using storage.
public static PlayerData getMyData()
public boolean store()
You can only store data for the current user (that is, data retrieved using getMyData). If you try to store data for any user other than the current user, it is guaranteed to fail.
public static java.util.List getTop(int maxAmount)
This will return one PlayerData item per user, and it will be sorted in descending order by the score (i.e. the return of getScore()). The parameter allows you to specify a limit on the amount of users' data to retrieve. If there is lots of data stored for users in your app, it may take some time (and bandwidth) to retrieve all users' data, and often you do not need all the users' data.
For example, if you want to show the high-scores, store the score with setScore(score) and store(), and then use getTop(10) to get the users with the top ten scores.
Returns null if:
maxAmount
- The maximum number of data items to retrieve.
Passing zero or a negative number will get all the data, but see the note above.
public static java.util.List getNearby(int maxAmount)
This will be one item per user, and it will be sorted in descending order by the score (i.e. the return of getScore()). The parameter allows you to specify a limit on the amount of users' data to retrieve. If there is lots of data stored for users in your app, this may take some time (and bandwidth) to retrieve all users' data, and often you do not need all the users' data.
The items will be those surrounding the current user. So for example, imagine that the player is 50th of 100 total users (when sorted by getScore()). Calling getNearby(5) will get the 48th, 49th, 50th, 51st and 52nd users in that order. Do not rely on the player being at a fixed location in the middle of the list: calling getNearby(5) when the user is 2nd overall will get the 1st, 2nd, 3rd, 4th and 5th users, so the user will be 2nd in the list, and a similar thing will happen if the user is near the end of the list.
For example, if you want to show the high-scores surrounding the player, store the score with setScore(score) and store(), and then use getNearby(10) to get the ten users with scores close to the current player.
Returns null if:
maxAmount
- The maximum number of data items to retrieve.
Passing zero or a negative number will get all the data, but see the note above.
public GreenfootImage getUserImage()
On the Greenfoot website, this is their profile picture. If running locally (or a profile picture is unavailable), this method returns a dummy image with the username drawn on the image.
|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |