Achievement System Developer Guide
This is the developer guide for the Source Academy's Achievement System.
This developer guide assumes basic familiarity with React, Redux-Saga
- Important Notes to know
- Achievement System Structure
- Achievement Dashboard Components
- Achievement Control Components
- Interactions of Components
- Achievement Store
- Events
- Assessment Achievements
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.
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 and bugs report should be reported normally through Github Issues. Please tag the issue with achievement label so the team can identify it easily.
The Achievement system consists of 2 main features:
- Achievement Dashboard
- Achievement Control
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.
The Achievement Control is the control panel of the Achievement system for the staffs to create, edit and remove achievements. It can be accessed by admin like this: https://sourceacademy.nus.edu.sg/courses/66/achievements/control
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.
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.
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.
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.
The achievement control can be accessed by admin like this: https://sourceacademy.nus.edu.sg/courses/66/achievements/control
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.
The Achievement Dashboard & Control containers use a helper function called Achievement Inferencer to encapsulate and infer useful information for the child components.
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 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.
- Add the event to the enum in the
EventTypeenum in\features\achievement\AchievementTypes.ts - Locate where in the code the event should be produced and dispatch an action of
addEventwith 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.
Assessment achievements are necessary in order to have the achievement system provide an accurate and full summary of XP that the user has.
Currently, assessment achievements are automatically generated for students in the achievement dashboard, using the function in \commons\achievement\utils\InsertFakeAchievements.ts. The assessment achievements created in achievement control don't have a way to be obtained.
Bear in mind that this is not ideal for a few reasons:
- Staff are unable to view the XP count of other users.
- Assessments that don't give XP just add unnecessary clutter. (e.g. My Room)
- We don't have a single source of truth for the total XP student has earned. It has to be obtained by adding the assessment XP and the achievement XP.
Would be nice if future batches could work on improving this part of the system. Perhaps automatically create an achievement when an assessment is posted, and update the progress when an assessment is submitted/graded.