Game Records

Game Records

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.

Usage (Sprint 4)

// 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();

Game Records

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.

Game Record Utils

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.

Usage (Deprecated)

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.

Fetch Achievements

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();

Fetch Score History

// 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();

Fetch Number of Games Played

GameInfo.getGameCount();

How is the metadata stored after each game?

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);
    }

What does a record look like?

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();
}

Time of player's death in a particular game

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();

UML Diagram

This is how the GameRecords functionality fits into the Achievements ecossytem.

Sequence Diagrams - Storing a game record when the player dies

This involves communicating with a bunch of different service like GameInfo, ScoringSystem etc.