Skip to content

Custom Math Achievements

Math Achievements (or Mathchievements) are an optional WeBWorK module.


Achievements (or Mathchievements) are gamification features designed to reward students for solving homework problems and for practicing good WeBWorK behavior. In a nutshell, students can earn achievements by meeting preset goals. For example, they might earn an achievement for solving 3 homework problems in a row without any incorrect submissions, or for solving a problem after taking an 8 hour break. Earning achievements and solving problems earns students points and after a student gets enough points they will be given a new Level. Depending on settings the math level may come with an Achievement Items. Students can view their current level and their progress towards various achievements by visiting the Achievements page. Instructors can modify and administer achievements by using the Achievement Editor page.
- Achievements - WeBWorK Wiki

This page is an introduction to writing custom Math Achievements.


It is strongly suggested that you initially assign achievements to no users and only assign achievements to the students once all of your customizations and configurations are done.

Checking and tracking achievements can be resource intensive, be sparing with the achievemnts that you assign to your students.

Enable Math Achievements

In your course, in Course Configuration, select the Optional Modules tab:

  • Enable Course Achievements (default False): set to True
  • Achievement Points Per Problem (default 5): can be left unchanged
  • Enable Achievement Rewards (default False): can be left unchanged
  • List of sets excluded from achievements (default - no sets excluded): can be left unchanged
  • Save Changes

Use Achievements Out of the Box

Once Achievements are enabled in a course, an Achievements summary is available to everyone in the course, and an Achievement Editor is available to instructors.

In the Achievement Editor, select the Import tab:

  • Import from where default_achievements.axp
  • Assign this achievement to which users? no users
  • Take Action

Create a New Achievement

By modifying an existing achievement

In the Achievement Editor, choose an existing achievement, select Edit Evaluator:

  • select the Save As tab
  • Use in new achievement:
    • Enter a new achievement ID in the text box, e.g. MT_Bonus
  • Save as: Enter a filename (ending in .at) in the text box, e.g.
  • Take Action

Now the new achievement evaluator can be modified as desired.

Example - Specific questions on a specific set

The following code in an achievement evaluator gives credit for the achievement if any of problem numbers 1, 3, or 5 in set Custom_Math_Achievements are correct.

# This problem checks to see if particular problems
# of a particular set have been solved

# Define valid problems using this nested hash
my %validproblems = (
       'Custom_Math_Achievements' => { 
           '1' => 1, 
           '3' => 1, 
           '5' => 1, }, 

# Check and see if any of these problems were solved
if ($validproblems{$problem->set_id} &&
    $validproblems{$problem->set_id}{$problem->problem_id} &&
    $problem->status == 1 &&
    $problem->num_correct == 1) {
        return 1;

return 0;

Upload a custom achievement icon

In File Manager:

  • Go up one level from Templates by clicking the up-arrow to the left of Templates
  • Select the html subdirectory,
  • then the achievements subdirectory,
  • upload an image file, for example hanamaru.png

Edit the achievement

In the Achievements Editor, click the pencil icon next to your new achievement ID:

  • Name: The achievement title displayed to students
  • Category: challenge, secret, level, etc
  • Points: The number of points gained by attaining this achievement
  • Description: The achievement explanation displayed to students. For example, Finish at least one of the odd-numbered challenge problems.
  • Icon File: The file name of any of the icons in /html/achievemnts/. hanamaru.png for example.

Remember to press the Take Action button to save your changes.

More information

Last update: 2022-11-20