Achievements System
Update: The system had undergone a major refactor in Sprint 4, and this documentation has been updated accordingly.
Relevant Files:
- AchievementsDisplay.java: Responsible for displays the achievement UI popups on the screen.
/* Listen to achievement events*/
// Incoming achievement
entity.getEvents().addListener("updateAchievement", this::updateAchievementsUI);
// Event to clear achievement after RENDER_INTERVAL
entity.getEvents().addListener("clear", this::clear);
// Event to display achievement in render queue
entity.getEvents().addListener("display", this::display);/**
* Renders the current achievement notification on the table
*
* @param achievement Configuration with properties and conditions for corresponding achievement
*/
private void renderAchievement(BaseAchievementConfig achievement) {
CharSequence text = achievement.message;
achievementLabel = new Label(text, skin, "small");
achievementImg = new Image(ServiceLocator.getResourceService()
.getAsset(achievement.iconPath, Texture.class));
table.add(achievementImg).size(300f, 150f);
table.row();
table.add(achievementLabel);
}-
AchievementStatsComponent.java: This file can be found here. Responsible for dispatching updateAchievement calls to the achievement display file. Keeps track of the game time, and listens to events from the AchievementsHelper. Based on the payload of events, it validates all the achievements. (done per frame) since there are many variables at play. The
AchievementsHelperfile can be found here and a reference of all the events tracked can be found here.
@Override
public void create() {
super.create();
AchievementsHelper.getInstance().getEvents()
.addListener(AchievementsHelper.HEALTH_EVENT, this::setHealth);
AchievementsHelper.getInstance().getEvents()
.addListener(AchievementsHelper.ITEM_PICKED_UP_EVENT, this::setItemCount);
}The isValid method: This is the most important snippet of the Achievements System. The isValid(achievement) method is regularly called to check whether an achievement is valid or not. The logic is as follows:-
- If the achievement is unlocked, it is valid by default. But do not emit an event to render it on the in game screen.
- If the achievement is unlocked, check if it is valid. If valid, emit an event to render it on the in game screen and unlock it.
- If it is invalid, do not emit any events or mark it as unlocked.
/**
* Checks if an achievement is valid
* Unlocks the achievement if it is valid and triggers an event
* pertaining to a new unlocked achievement
*
* @param achievement
* @return valid returns true if valid, false otherwise
*/
private boolean isValid(BaseAchievementConfig achievement) {
boolean valid = false;
if (achievement.unlocked) {
return true;
}
if (achievement.condition.time != -1) {
valid = achievement.condition.time * 1000L <= time;
if (!valid) {
return false;
}
}
if (achievement.condition.health != -1) {
valid = achievement.condition.health <= health;
if (!valid) {
return false;
}
if (valid) {
achievement.unlocked = true;
entity.getEvents().trigger("updateAchievement", achievement);
}
return true;
}- AchievementsHelper.java: Tracks important events like item pickup, health updates etc across the game. Has its own handler which triggers important events. AchievementStatsComponent Component then listens to this handler for events and then unlocks achievements when e.g the player survives for 10 minutes with full health and other such events.
/**
* Triggers an event when an item is picked up for
* the achievements system
*/
public void trackItemPickedUpEvent() {
handler.trigger(ITEM_PICKED_UP_EVENT);
}
/**
* Tracks changes in the health property of the player
* and triggers an event for the achievements system
* @param health the player's health
*/
public void trackHealthEvent(int health) {
handler.trigger(HEALTH_EVENT, health);
}Usage:
// Notify the Achievements System when an item is picked up
AchievementsHelper.getInstance().trackItemPickedUpEvent();
// Notify the Achievements System when the health is updated
AchievementsHelper.getInstance().trackHealthEvent(int health);- AchievementFactory.java: Responsible for inflating an arraylist of achievements with the condition and other properties
/**
* Factory to create Achievement entities with predefined conditions.
*
* <p>Each Achievement entity type should have a creation method that returns a corresponding entity.
* Predefined achievement entity conditions can be loaded from configs stored as json files
* which are defined in "achieve.json".
*/
public class AchievementFactory {
private static final AchievementConfigs configs =
FileLoader.readClass(AchievementConfigs.class, "configs/achieve.json");
/**
* Returns a list of achievements from the "achieve.json" file
* @return achievements - A list of achievements inflated from the JSON file
*/
public static Entity createAchievementEntity(){
return new Entity()
.addComponent(new AchievementsStatsComponent())
.addComponent(new AchievementsDisplay());
}
public static List<BaseAchievementConfig> getAchievements(){
return configs.achievements;
}
/**
* Returns a list of paths to corresponding achievement texture images
* @return paths - A list of paths inflated from achievement list generated using getAchievements()
*/
public static String[] getTextures(){
return configs.achievements
.stream().map(achievement -> achievement.iconPath).collect(Collectors.toList())
.toArray(new String[configs.achievements.size()]);
}
}- AchievementsConfig.java: Gets inflated by the "achievement" property of "achieve.json"
/**
* Defines an Arraylist to store a basic set of achievement properties stored in
* achievement config files (achieve.json) to be loaded by Achievement Factory
*/
public class AchievementConfigs {
public List<BaseAchievementConfig> achievements = new ArrayList<>();
}- BaseAchievementConfig.java: Represents each item of the "achievements" array in "achieve.json"
- ConditionConfig.java: Gets inflated by the "condition" property of "achieve.json"
- achieve.json: Houses an array of achievements with relevant names and conditions. To unlock a gold trophy veteran achievement, the user has to survive for 20 minutes in game. It holds 20 bonus points which can be added to the score.
{
"name": "Veteran",
"type": "GOLD",
"iconPath": "images/achievements/veteranGold.png",
"message": "Survived for 20 minutes!",
"bonus": 20,
"condition": {
"time": 20
}
}- AsyncTaskQueue.java: For dispatching sequential long running tasks (Each achievement popup has to be rendered for 5 seconds)
/**
* Achievement UI updates are guaranteed to execute sequentially,
* and no more than one update will be active at any given time
*
* @param achievement Configuration with properties and conditions for corresponding achievement
*/
private void updateAchievementsUI(BaseAchievementConfig achievement) {
/* Queue expensive task to run on a separate single thread
* to run asynchronously. */
AsyncTaskQueue.enqueueTask(() -> {
try {
/* Render achievement card */
renderAchievement(achievement);
/* Wait for some time */
Thread.sleep(RENDER_DURATION);
/* Remove card from screen */
table.clear();
} catch (InterruptedException ignored) {
} catch (Exception e) {
e.printStackTrace();
}
});
} @Override
public void dispose() {
super.dispose();
/* If the in game screen is out of focus, cancel all future tasks. This has to be
* done in order to prevent memory leaks, unforeseen exceptions and
* other nasty bugs.*/
AsyncTaskQueue.cancelFutureTasksNow();
// ...
}For displaying achievement popups and pushing long running rendering tasks.
