Skip to content

Achievement System Developer Guide

Jump to bottom
jonas-chow edited this page Jul 5, 2021 · 6 revisions

This is the developer guide for the Source Academy's Achievement System.

This developer guide assumes basic familiarity with React, Redux-Saga

Table of Content

  1. Important Notes to know
  2. Achievement System Structure
  3. Achievement Dashboard Components
  4. Achievement Control Components
  5. Interactions of Components
  6. Achievement Store
  7. Events

Important Notes to Know

Source Code

All the source code of the achievement system can be found in src/commons/achievement, src/features/achievement and src/pages/achievement of this repository.

Objectives and Guidelines

The key objectives of the Achievement system are:

  • Create a sense of progress for the students
  • Incentivize good learning behavior
  • Monitor student's academic performance

All the development of the Achievement system follows two main guidelines:

  • The Achievement system UI should be useful, intuitive and user-friendly without having to read a user guide or ask the developer.
  • Exercise good software principles and strictly adhere to the Source Academy Coding Standard.

Issues, Bugs, Progress, and Reach Goals

Issues and bugs report should be reported normally through Github Issues. Please tag the issue with achievement label so the team can identify it easily.

Achievement System Structure

The Achievement system consists of 2 main features:

  1. Achievement Dashboard
  2. Achievement Control

Achievement Dashboard

The Achievement Dashboard is the homepage of the Achievement system. Students can view their current XP progress and detail of every achievement such as completion criteria, potential XP reward, difficulty and other relevant information. Staffs can modify student's achievement progress via the Achievement Dashboard.

Achievement Control

The Achievement Control is the control panel of the Achievement system for the staffs to create, edit and remove achievements.

Achievement Dashboard Components

Below is a screenshot of the Achievement Dashboard Beta testing page annotated with the name of React components. The actual site should look similar to the Beta page.

image

The main React function of the Achievement Dashboard is located at \pages\achievement\subcomponents\AchievementDashboard.tsx. You should be able to identify the React components from there.

Achievement Control Components

Below is a screenshot of the Achievement Control Beta testing page annotated with the name of React components. The actual site should look similar to the Beta page.

image

The main React function of the Achievement Control is located at \pages\achievement\control\AchievementControl.tsx. You should be able to identify the React components from there.

Interactions of Components

Interaction between Achievement Store and Source Academy Backend

image

Achievement related data are fetched and updated to the Source Academy Backend. Additionally, image assets such as achievement card background, cover image, etc. are uploaded to the AWS S3 server for performance issue.

Interaction between Achievement Dashboard/Control and Achievement Store

image

The Achievement Dashboard & Control containers use a helper function called Achievement Inferencer to encapsulate and infer useful information for the child components.

Achievement Store

The Achievement State in the frontend Redux Store consists of 2 arrays: achievements[] and goals[]

Each AchievementItem in the achievements[] represents an achievement.

AchievementItem Data Type Description
uuid string unique uuid of the achievement item
title string title of the achievement item
xp number xp earned upon completion of the achievement
isVariableXp boolean if true, the amount of xp earned will be the sum of its goals' counts
ability AchievementAbility ability of the achievement
deadline (Optional) Date deadline of the achievement
release (Optional) Date release date of the achievement
isTask boolean if true, the achievement is rendered as an achievement task
position number ordering of the achievement task, 0 for non-task
prerequisiteUuids string[] an array of prerequisite uuids
goalUuids string[] an array of goal uuids
cardBackground string background image URL of the achievement card
view AchievementView the achievement view

Each AchievementGoal in the goals[] represents a goal.

AchievementGoal Data Type Description
uuid number unique id of the goal
text string goal description
achievementUuids string[] an array of achievement uuids
meta GoalMeta metadata of the goal

For more information please refer to \features\achievement\AchievementTypes.ts

Events

Events are spawned in real time based on the user's actions. Currently, we have the following events:

  • Run Code which is spawned when code is run from the editor
  • Error which is spawned when code that is run results in error(s)
  • Infinite Loop which is spawned when code that is run results in an infinite loop error
  • Run testcase which is spawned when a testcase is run

Events spawned are then registered by adding them to the count of the relevant Event type goals, which can lead to completion of goals and achievements. These changes are computed every 3 seconds if there are any events that have not been registered yet.

Adding Events

  1. Add the event to the enum in the EventType enum in \features\achievement\AchievementTypes.ts
  2. Locate where in the code the event should be produced and dispatch an action of addEvent with an array of all the events that should be spawned

Currently, all events are to do with running code, and the code that spawns events are all located in \commons\sagas\WorkspaceSaga.ts.

Clone this wiki locally