Achievements Blueprint

This blueprint contains an achievements folder, that contains the assets for all achievement-related things. The two files you will most likely be working on the most are achievements.lua and icons.png. The former holds all the information about the achievements, like their name, description, difficulty, order, etc. as well as the code that controls times the achievements should be granted. The latter file contains the icon images of the achievements.

The achievements.lua script is divided into five functions: 

• achievementOptions - Set options like:

  • hiddenAchievementIcon - Icon ID that should be used as the hidden achievement icon,

  • iconSheetX & iconSheetY - Size of the icons.png sheet,

  • iconSize - Size of an icon in the icons.png sheet in pixels,

  • goldenDifficulty - The difficulty of achievements that should make the golden toast pop up upon granting instead of the default one.

• setupAchievements - Set up achievement properties:

  • Method 1 (exact method):

--in this example, "100balls" is the achievement id (important!)

achievement["100balls"] = {} --setup

achievement["100balls"]["icon"] = 1 --icon id

achievement["100balls"]["name"] = "ball collector" --name

achievement["100balls"]["subtitle"] = "reach a ballcount of 100" --subtitle

achievement["100balls"]["desc1"] = "reach a ballcount of 100" --description line 1

achievement["100balls"]["desc2"] = "" --description line 2

achievement["100balls"]["desc3"] = "" --description line 3

achievement["100balls"]["difficulty"] = 2 --difficulty

achievement["100balls"]["hidden"] = false --is the achievement hidden?

• • Method 2 (shorthand method):

--parameters of the registerAchievement function:

--registerAchievement( id , icon id , name , subtitle , { desc line 1 , desc line 2 , desc line 3 } , difficulty , hidden parameter )

--the description list can have up to 3 entries; if you pass less, then the missing lines will be ignored

--if you pass an empty list ( {} ) as the description list parameter, the description will reuse the subtitle text

--the hidden parameter can either be set to false (not hidden), or a list of achievement id's, that have to be completed before being unhidden (dependency list)

registerAchievement("perfect",4,"perfectionist","go from start to mediocre rank without making mistakes",{"go from start to mediocre (14000) without","missing crystals or crashing into obstacles"},5,{"endless"})

• • Order list:

--the order in which the achievements will appear in the menu

menuList = {"100crystals","endless","perfect"}

• frameAchievementsMenu & frameAchievementsHud - Code that gets executed every frame in the menu,

• restartAchievements - Code that gets executed when the temporary variables and registers used for checks are reset.

The blueprint also provides a couple of other functions that you will use when granting achievements:

• grantAchievement(id,notify) - Grant achievement; the notify parameter controls whether the toast should be shown or not,

• revokeAchievement(id) - Revoke achievement,

• isCompleted(id) - Returns true if the achievement is completed,

• isUnlocked(id) - Returns true if the achievement is unlocked (used for hidden achievements),

• mgCommand("achievements show") - Show achievements menu,

• mgCommand("achievements hide") - Hide achievements menu.

Achievements Blueprint © 2025 by Smash Hit Lab is licensed under CC BY-SA 4.0