Achievements System

Relevant Files:

UI Components

AchievementsDisplay.java: Responsible for displays the achievement UI popups on the screen.

/* Listen to achievement events*/
entity.getEvents().addListener("updateAchievement", this::updateAchievementsUI);

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

Components

AchievementStatsComponent.java: 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.

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

/**
 * 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;
}

Event Tracking

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

Entities (ECS)

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"

Config

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

Other

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

       // ...
}