Achievements System

Achievements System

Note: A typical game, at the time of writing the code guideline will see a bunch of achievement popups for the first 30-35 seconds. This is because the time condition for each achievement has been reduced. 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.

/**
 * 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:

AchievementsHelper.getInstance().trackItemPickedUpEvent();

Entities (ECS)

• AchievementFactory.java: Responsible for inflating an arraylist of achievements with the condition and other properties
• AchievementsConfig.java: Gets inflated by the "achievement" property of "achieve.json"
• 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();

       // ...
}

Sequence diagram - Achievements popup rendering

For displaying achievement popups and pushing long running rendering tasks.

Sequence diagram - Achievements health update event

Sequence diagram - Achievements item pickup event