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 achievement to be validated
* @return valid returns true if valid, false otherwise
*/
private boolean isValid(BaseAchievementConfig achievement) {
if (achievement.unlocked) {
return true;
}
boolean valid = false;
for (String cond : propertyList.keySet()) {
// Operation to perform when checking if achievement property has been satisfied or not
String operation = propertyList.get(cond).operation;
// Default game variable values
double defaultConditionVal = propertyList.get(cond).defaultValue;
// Current game variable values (current time, score etc)
double currentPropertyVal = gameConditions.getOrDefault(cond, defaultConditionVal);
int conditionVal = achievement.getConditionMap().get(cond);
if (conditionVal != -1) {
if (cond.equals("time")) {
// Convert minutes to milliseconds, since the time in config is supplied in minutes
conditionVal = conditionVal * 60000;
}
// Perform comparisons to check if conditions of the achievement have been satisfied
switch (operation) {
case "==":
valid = conditionVal == currentPropertyVal;
break;
case "<=":
valid = conditionVal <= currentPropertyVal;
break;
default:
// Unknown operation
valid = false;
break;
}
// Stop looping if a condition of achievement was not satisfied
if (!valid) {
break;
}
}
}
// Finally, if the achievement is valid, unlock it.
if (valid) {
achievement.unlocked = true;
// Emit an event if the achievement is valid
entity.getEvents().trigger("updateAchievement", achievement);
}
return valid;
}- 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 conditions, and
propertyListwith the default in game values for each condition. Default values are needed in theachievements.jsonconfig because there might be a case where there are no updates to certain in game variables, like health remains constant at 100, no items picked up etc. This is needed because theAchievementStatsComponentusesgamePropertiesas a mapping ofconditionandvalue.
/**
* 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()]);
}
}There is also a method to get the list of all conditions which are used across achievements with necessary defaults, as mentioned:
- 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
achievementsarray inachievements.json. Looping through the condition props and values of aConditionConfigobject in achievements is quite tedious. Hence, a utility method calledgetConditionMapwas created, the usage of which can be seen in theisValidfunction ofAchievementStatsComponent.
Using JAVA reflection to loop through all the properties of a ConditionConfig object:
/**
* Returns a mapping of the achievement name and value for easy processing
* This makes it very easy to iterate through all the properties and fetch
* the values, and saves a lot of technical debt. In simple words, a mapping
* of member variables and values of the 'ConditionConfig' object is
* returned by this function.
*
* @return conditionProps mapping of condition name and associated value
*/
public Map<String, Integer> getConditionMap() {
Map<String, Integer> conditionProps = new LinkedHashMap<>();
// Get all the member fields of the condition object
Field[] fields = ConditionConfig.class.getFields();
for (Field field : fields) {
String name = field.getName();
// Get value of the fields
int value = -1;
try {
value = field.getInt(condition);
} catch (IllegalAccessException e) {
e.printStackTrace();
}
conditionProps.put(name, value);
}
return conditionProps;
}-
ConditionConfig.java: Gets inflated by the
conditionproperty of each achievement inachievements.json. The conditions which are not being used are given a default value of-1, to specify the fact that those conditons are to be ignored when checking whether an achievement has been unlocked or not.
- achievements.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
}
}The list of conditions and unlock logic also has to be specified in propertyList struct of this config. Notice how health has been given a default value of 100.
"propertyList": {
"class": "java.util.LinkedHashMap",
"distance": {
"operation": "<=",
"defaultValue": 0
},
// ...
"gold": {
"operation": "==",
"defaultValue": 0
},
// ...
"health": {
"operation": "<=",
"defaultValue": 100
}
// ...
}-
PropertyListDefaults.java: Struct within a
propertyList.
public class PropertyListDefaults {
public String operation = "NONE";
public int defaultValue = 0;
}propertyList is a mapping of condition names and their default values and operations. Note that for discrete values, a == operation is used, and for continuous values like time, a <= operation has been used. This means that the in game time does not need to have a strict equality with the time specified in the JSON. Taking the Veteran achievement, as long as the in game time is greater than condition time, the achievement will be unlocked.
- 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.
