Game Records - UQdeco2800/2021-ext-studio-2 GitHub Wiki
Note: Updated with Sprint 4 changes
Keeps a track of important game data like the number of games played, the achievements and the score in a particular game and the date and time of games. FileLoader
is used to persist data in JSON files stored in the Users
folder on Windows and the Home
directory in UNIX based operating systems.
- GameInfo.java: For now, only keeps a tab of the number of games played. Can be expanded to include more metadata soon. This can be found here.
- GameRecords.java: Stores a mapping of a particular game and its achievement records and scores. This can be found here.
-
GameRecordUtils.java: Set of important and widely used utility functions which were previously in
GameRecords.java
. This can be found here.
// Get number of unique gold achievements unlocked by the user across games
GameRecordUtils.getGoldAchievementsCount();
// Get all the scores of the user, sorted in desc order
List<Score> persistedScores = GameRecordUtils.getHighestScores();
// Distance travelled by the user in the most recent game played
double distance = GameRecords.getLatestDistance();
// Number of games that the user has played
int gameNumber = GameInfo.getGameCount();
// Increment the number of games that the user has played and persist the same in file storage
GameInfo.incrementGameCount();
Function name | Return type | Description |
getAchievementsByGame(int game) | List: BaseAchievementConfig | Returns the unlocked achievements of a particular game, represented by the game number. |
getScoreByGame(int game) | Score | Returns the final score of a particular game, represented by the game number. |
getLatestScore | Score | Returns the final score of the latest game played. |
getDistanceByGame(int game) | double | Returns the distance travelled in a particular game, represented by the game number. |
getLatestDistance | double | Returns the distance travelled of the latest game played. |
getAllScores | List: Score | Returns the list of all the scores, across all games played by the user. |
Function name | Return type | Description |
getHighestScores | List: Score | Returns the list of all the scores, sorted in descending order by score, across all games played by the user. |
getAllTimeBestAchievements | List: BaseAchievementConfig | Returns the most difficult to achieve achievement records of the user, i.e, the best gold, silver and bronze achievements unlocked. |
getBestAchievementsByGame(int game) | List: BaseAchievementConfig | Returns the most difficult to achieve achievement records of the user, i.e, the best gold, silver and bronze achievements unlocked, but of a particular game. If the user has unlocked Veteran Gold, for example, the bronze and silver counterparts will not be returned in the list. |
getNextUnlockAchievements() | List: BaseAchievementConfig | List of bronze achievements that the user is yet to unlock. |
getGoldAchievementsCount | int | Number of unique gold achievements that the user has unlocked. |
This can act as a reference for other feature teams who do not have the bandwidth to understand the whole GameRecords
and GameInfo
storage system.
SampleUsage:
// Get number of unique gold achievements unlocked by the user across games
GameRecords.getGoldAchievementsCount();
// Get all the scores of the user, sorted in desc order
List<Score> persistedScores = GameRecords.getHighestScores();
// Distance travelled by the user in the most recent game played
double distance = GameRecords.getLatestDistance();
// Number of games that the user has played
int gameNumber = GameInfo.getGameCount();
// Increment the number of games that the user has played and persist the same in file storage
GameInfo.incrementGameCount();
Function name | Return type | Description |
getAchievementsByGame(int game) | List: BaseAchievementConfig | Returns the unlocked achievements of a particular game, represented by the game number. |
getScoreByGame(int game) | Score | Returns the final score of a particular game, represented by the game number. |
getLatestScore | Score | Returns the final score of the latest game played. |
getDistanceByGame(int game) | double | Returns the distance travelled in a particular game, represented by the game number. |
getLatestDistance | double | Returns the distance travelled of the latest game played. |
getAllScores | List: Score | Returns the list of all the scores, across all games played by the user. |
getHighestScores | List: Score | Returns the list of all the scores, sorted in descending order by score, across all games played by the user. |
getAllTimeBestAchievements | List: BaseAchievementConfig | Returns the most difficult to achieve achievement records of the user, i.e, the best gold, silver and bronze achievements unlocked. |
getBestAchievementsByGame(int game) | List: BaseAchievementConfig | Returns the most difficult to achieve achievement records of the user, i.e, the best gold, silver and bronze achievements unlocked, but of a particular game. If the user has unlocked Veteran Gold, for example, the bronze and silver counterparts will not be returned in the list. |
getNextUnlockAchievements() | List: BaseAchievementConfig | List of bronze achievements that the user is yet to unlock. |
getGoldAchievementsCount | int | Number of unique gold achievements that the user has unlocked. |
Stored in the gameRecords.json
file in an EXTERNAL
location, as mentioned above.
/**
* @param game the game number (nth game played)
* @return unlocked achievements of that particular game
*/
public static List<BaseAchievementConfig> getAchievementsByGame(int game) {
return getRecords().findByGame(game).achievements;
}
Get the list of best achievement types unlocked by the user.
GameRecords.getBestRecords();
Get a list of achievements that have not been unlocked:
GameRecords.getNextUnlockAchievements();
/**
* Returns a list of achievements that can be unlocked next
*
* @return list of bronze achievements yet to be unlocked
*/
public static List<BaseAchievementConfig> getNextUnlockAchievements() {
List<BaseAchievementConfig> betterAchievements = new LinkedList<>();
Set<String> nextUnlocks = new LinkedHashSet<>();
getBestRecords().forEach(achievement -> {
nextUnlocks.add(achievement.name);
});
AchievementFactory.getAchievements().forEach(achievement -> {
if (!nextUnlocks.contains(achievement.name) && achievement.type.equals("BRONZE")) {
betterAchievements.add(achievement);
}
});
return betterAchievements;
}
Get the number of unlocked gold achievements:
GameRecords.getGoldAchievementsCount();
// Get the score of a particular game
GameRecords.getScoreByGame(int game);
// List of all scores
GameRecords.getAllScores();
// List of all scores in desc order
GameRecords.getHighestScores();
GameInfo.getGameCount();
if (playerStats.isDead()) {
logger.info("Performing Post Game Tasks");
/* NOTE: Call this method first before displaying the game over screen
* and performing other tasks. This method has to be called as soon as
* the player dies. */
performPostGameTasks();
logger.info("Display Game Over Screen");
game.setScreen(GdxGame.ScreenType.GAME_OVER);
return;
}
/**
* Tasks to perform when the game is over.
* The game is considered to be over when the player dies.
* <p>
* NOTE: Make sure this method is called as soon as the player dies,
* and before the game over screen is displayed.
*/
private void performPostGameTasks() {
/* Increment the number of games that have been played
* NOTE: Perform all subsequent tasks after this has been called */
GameInfo.incrementGameCount();
/* Store the achievements record and in a JSON file and then reset achievements */
GameRecords.storeGameRecord();
}
This is how a typical in game record is stored:
/**
* Stores the records of the most recent game played into a JSON file
* Note: Run this method only after the in game count has updated
*/
public static void storeGameRecord() {
Record record = new Record();
// Storing game count
int gameCount = GameInfo.getGameCount();
record.game = gameCount;
// Storing achievements
record.achievements = AchievementsStatsComponent.getUnlockedAchievements();
// Fetching the score
ScoringSystemV1 scoringSystemV1 = new ScoringSystemV1();
record.scoreData.score = scoringSystemV1.getScore();
record.scoreData.game = gameCount;
// Add the record
Records records = getRecords();
records.add(record);
// Write updated records list JSON
setRecords(records);
}
Each record is mapped to a game and has a certain score and set of achievements.
/**
* A mapping of the game number (nth game played) and associated record,
* i.e, the score and list of unlocked achievements.
*/
public static class Records {
/**
* An ordered mapping of the game number and associated achievements
*/
public Map<Integer, Record> records = new LinkedHashMap<>();
/**
* @param game the game number
* @return records of a particular game (null if absent)
*/
public Record findByGame(int game) {
return records.get(game);
}
/**
* Add a new record to the mapping
*
* @param record the record to be added
*/
public void add(Record record) {
records.put(record.game, record);
}
}
/**
* The Record class keeps a tab of the score, game number and
* achievements unlocked in that particular game.
* Games are identified based on the game numbers.
*/
public static class Record {
/**
* The game number (nth game played)
*/
public int game = 0;
/**
* A unique record id
*/
public String id = UUID.randomUUID().toString();
/**
* List of unlocked achievements
*/
public List<BaseAchievementConfig> achievements = new LinkedList<>();
/**
* Score details of that particular game
*/
public Score scoreData = new Score();
}
LocalDateTime
is very useful when it comes to storing records in the local time zone.
public static class Score {
/**
* Score of that particular game
**/
public int score = 0;
/**
* The game number, for ease of access
*/
public int game = 0;
/**
* Time when the game ended, i.e, the player died.
*/
public String dateTime = LocalDateTime.now().toString();
/**
* Returns local date and time object of when the game ended, i.e,
* the time of player's death.
* <p>
* LocalDateTime objects are easier to work with. Parse the
* given dateTime string into a LocalDateTime object.
* <p>
* Note: This could be mapped to the JSON but the FileLoader
* gives SEVERE type errors when reading the file.
*
* @return LocalDateTime object of the dateTime property
*/
public LocalDateTime getDateTime() {
return LocalDateTime.parse(this.dateTime);
}
/**
* In game score
*
* @return the score of the particular game
*/
public Integer getScore() {
return score;
}
}
Score history can be fetched like so:
// Get the score of a particular game
GameRecords.getScoreByGame(int game);
// List of all scores
GameRecords.getAllScores();
// List of all scores in desc order
GameRecords.getHighestScores();
This is how the GameRecords functionality fits into the Achievements ecossytem.
This involves communicating with a bunch of different service like GameInfo
, ScoringSystem
etc.