achievementExt
- AchievementExt
- modApi.achievements
A module adding a single function to modApi.achievements, addExt, allowing the creation of achievements that are tracked on multiple difficulties.
Internal functions in AchievementExt will update the achievement and tooltip when the difficulty changes.
A global variable of the same name (AchievementExt) will also be created, keeping track of versioning of this module.
Requires difficultyEvents being initialized first.
void modApi.achievements:addExt(table achievement)
| Argument name | Type | Description |
|---|---|---|
achievement |
table | A table with fields describing the achievement being added |
This function is used much like modApi.achievements.add. The difference is that the achievement created will be tracked separately on all three difficulties, easy, normal and hard; and that a separate highscore can be tracked independent of the achievement objectives.
The achievment object, passed as the first argument can also have the following fields in addition to the fields described for the function add. They can also be manually set for the returned achievement object after creating the achievement.
| Field | Type | Description |
|---|---|---|
retoastHighscore |
boolean | Whether or not the achievement should be re-toasted when reaching a new highscore |
textDiffComplete |
string | Display text when complete |
textDiffIncomplete |
string | Display text when incomplete |
textFailed |
string | Display text for when failed |
The achievement object will have the following changed/new functions:
void achievement:completeWithHighscore(number highscore)
Completes the achievement and sets a new highscore for it on the current difficulty. If the achievement has already been completed, it will be re-toasted if the flag retoastHighscore is true and the highscore given is greater than the current highscore (default 0). Otherwise, the highscore will be updated silently.
void achievement:getHighscore()
Returns the achievement's highscore for the current difficulty.
void achievement:getHighscoreOnDifficulty(number difficultyId)
Returns the achievement's highscore for the specified difficulty.
void achievement:getProgressOnDifficulty(number difficultyId)
Returns the achievement's objective progress for the specified difficulty.
void achievement:getTextDiffComplete(number difficultyId, table difficultyProgress)
Returns the achievement's display text when complete.
By default, it will display achievement.textDiffComplete with "$highscore" substituted for the current highscore on the specified difficulty or "Complete" if achievement.textDiffComplete is not set.
This method is intended to be overridden if a more detailed display text is desired.
void achievement:getTextDiffIncomplete(number difficultyId, table difficultyProgress)
Returns the achievement's display text when complete.
By default, it will display achievement.textDiffIncomplete or "Complete" if achievement.textDiffIncomplete is not set.
This method is intended to be overridden if a more detailed display text is desired.
void achievement:getTextFailed()
Returns the achievement's display text when failed. An achievement is considered failed if achievement:isFailed returns true.
By default, it will display achievement.textFailed or "Objective failed" if achievement.textFailed is not set.
This method is intended to be overridden if a more detailed display text is desired.
void achievement:getTextProgress()
Returns the achievement's display text for it's progress in the current game. This is intended for displaying non-persistent progress that is not directly saved in the achievement's progress across games.
By default, it will not display anything.
This method is intended to be overridden if progress display text is desired.
void achievement:getTooltip()
The original achievement.getTooltip is overridden in order to display additional text for progress, highscore and completion state for all difficulties.
The original achievement.getTooltip is saved in achievement.getTooltip_orig.
void achievement:isComplete(string objectiveId)
The original achievement.isComplete is overridden. If called while in the main menu without the optional argument objectiveId, it will return true if the achievement is complete on any difficulty. This is in order to display the achievement as complete on the achievement screen from the main menu.
Calling the achievement anywhere else will return the completion state for the current difficulty.
The original achievement.isComplete is saved in achievement.isComplete_orig.
void achievement:isCompleteOnDifficulty(number difficultyId)
Returns true if the achievement is complete on the specified difficulty.
void achievement:isFailed()
Returns nil by default. If this method returns true while in a game, the achievement will display the additional text returned by getTextFailed.
This method is intended to be overridden if a fail state is desired.
void achievement:isNotFailed()
Returns the opposite of isFailed.
void achievement:setProgress(table newState)
The original achievement.setProgress is overridden in order for this method to set the progress for the current difficulty. If achievement.retoastOnHighscore is set, it will also allow this method to re-toast achievements if newState.highscore is greater than the current highscore for the current difficulty.
The original achievement.setProgress is saved in achievement.setProgress_orig.