greenfoot
Class PlayerData

java.lang.Object
  extended by greenfoot.PlayerData

public class PlayerData
extends java.lang.Object

The PlayerData class allows you to store and load data for Greenfoot scenarios, even when the scenario has been uploaded to the Greenfoot website.

You should always check if storage is currently available by PlayerData.isStorageAvailable(). Storage is not always available, and in particular, if the user is not logged in to the Greenfoot website (a very common case), storage will not be available.

When storage is available, you can use PlayerData.getMyData() to get the data for the current user, or PlayerData.getTop(10) or PlayerData.getNearby(10) to get items to show on a scoreboard. These give you back PlayerData items, where you can get the players' image or get/set the current data.

A player's data consists of a score integer, 10 general integers and 5 strings. getTop and getNearby use the score for sorting. You are free to use the general integers and strings as you need for your scenario: things like which level the player reached last time they were playing.

Version:
2.3
Author:
Neil Brown

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
 
Method Summary
 int getInt(int index)
          Gets the value of the int at the given index (0 to NUM_INTS-1, inclusive)
static PlayerData getMyData()
          Gets the data stored for the current user.
static java.util.List getNearby(int maxAmount)
          Gets a sorted list of the PlayerData items for this scenario surrounding the current user.
 int getRank()
          Gets the players overall rank for this scenario.
 int getScore()
          Gets the player's score
 java.lang.String getString(int index)
          Gets the value of the String at the given index (0 to NUM_STRINGS-1, inclusive)
static java.util.List getTop(int maxAmount)
          Gets a sorted list of the PlayerData items for this scenario, starting at the top.
 GreenfootImage getUserImage()
          Returns a 50x50 image of the user.
 java.lang.String getUserName()
          Gets the username of the user that this storage belongs to.
static boolean isStorageAvailable()
          A boolean indicating whether storage is available.
 void setInt(int index, int value)
          Sets the value of the int at the given index (0 to NUM_INTS-1, inclusive)
 void setScore(int score)
          Sets the player's score.
 void setString(int index, java.lang.String value)
          Gets the value of the String at the given index (0 to NUM_STRINGS-1, inclusive) Passing null is treated as a blank string.
 boolean store()
          Stores the data.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NUM_INTS

public static final int NUM_INTS
The number of integers that can be stored

See Also:
Constant Field Values

NUM_STRINGS

public static final int NUM_STRINGS
The number of Strings that can be stored

See Also:
Constant Field Values
Method Detail

getUserName

public java.lang.String getUserName()
Gets the username of the user that this storage belongs to.


getInt

public int getInt(int index)
Gets the value of the int at the given index (0 to NUM_INTS-1, inclusive)

Default value is zero.


getString

public java.lang.String getString(int index)
Gets the value of the String at the given index (0 to NUM_STRINGS-1, inclusive)

Default value is the empty String.


setInt

public void setInt(int index,
                   int value)
Sets the value of the int at the given index (0 to NUM_INTS-1, inclusive)


setString

public void setString(int index,
                      java.lang.String value)
Gets the value of the String at the given index (0 to NUM_STRINGS-1, inclusive) Passing null is treated as a blank string.


getScore

public int getScore()
Gets the player's score


setScore

public void setScore(int score)
Sets the player's 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 > getScore())
   {
     setScore(latestScore);
   }
 
Without some code like this, you'll always overwrite the player's previous score.


getRank

public int getRank()
Gets the players overall rank for this scenario.

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


isStorageAvailable

public static boolean isStorageAvailable()
A boolean indicating whether storage is available.

Storage is unavailable if it is an applet outside the Greenfoot website, or a stand-alone application, or if the user is not logged in to the Greenfoot website. This last case is very common, so you must check this function before attempting to use the other static storage functions. If this function returns false, your scenario must proceed without using storage.


getMyData

public static PlayerData getMyData()
Gets the data stored for the current user. Returns null if: The last case is very common, so you should always be ready to handle a null return from this function.

Returns:
the user's data, or null if there was a problem.

store

public boolean store()
Stores the data.

If you try to store data for any user other than the current user, it is guaranteed to fail.

Returns:
true if stored successfully, false if there was a problem.

getTop

public static java.util.List getTop(int maxAmount)
Gets a sorted list of the PlayerData items for this scenario, starting at the top.

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, this 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 then use getTop(10) to get the users with the top ten scores.

Returns null if:

The last case is very common, so you should always be ready to handle a null return from this function.

Parameters:
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.
Returns:
A list where each item is a PlayerData, or null if there was a problem

getNearby

public static java.util.List getNearby(int maxAmount)
Gets a sorted list of the PlayerData items for this scenario surrounding the current user.

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 then use getNearby(10) to get the ten users with scores close to the current player.

Returns null if:

The last case is very common, so you should always be ready to handle a null return from this function.

Parameters:
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.
Returns:
A list where each item is a PlayerData, or null if there was a problem

getUserImage

public GreenfootImage getUserImage()
Returns a 50x50 image of the user.

On the Greenfoot website, this is their profile picture. If running locally, always returns a dummy image, with their username drawn on the image.

Returns null if:

The last case is very common, so you should always be ready to handle a null return from this function.

Returns:
a 50x50 GreenfootImage, or null if there was a problem accessing the image


Greenfoot homepage