-
Notifications
You must be signed in to change notification settings - Fork 17
achievements
- modApi
A table containing all functions to add and manipulate achievements.
All added achievements will be displayed in-game the mod content's achievement screen located in:
Main Menu > Mod Contents > Achievemenets
If Development Mode is enabled, achievements can be toggled in the achievement screen by clicking them with the mouse button. This can be useful when developing mods with achievements in them.
Main Menu > Mod Contents > Configure Mod Loader > Development Mode
void modApi.achievements:add(achievement)
| Argument name | Type | Description |
|---|---|---|
achievement |
table | A table with fields describing the achievement being added |
The achievement object, passed as first argument, has the following necessary fields:
| Field | Type | Description |
|---|---|---|
id |
string | Id of the achievement |
name |
string | Name of the achievement |
image |
string | Path to the achievement's displayed image |
The achievement object can have the following additional optional fields:
| Field | Type | Description |
|---|---|---|
tooltip |
string | The achievement's displayed tooltip when hovered |
objective |
varies | The achievement's objective |
global |
string | The global bucket to place this achievement in |
squad |
string | The squad bucket to place this achievement in |
secret |
boolean | Whether the this achievement is hidden or not |
addReward |
function | A function that will be invoked when the achievement goes from incomplete to complete |
remReward |
function | A function that will be invoked when the achievement goes from complete to incomplete |
Adds an achievement with the specified id, name and image to the mod content's achievement screen.
If global is specified, then the achievement will be placed in a bucket with the same name, on the right side on the achievement screen. Different mods can put achievements in the same bucket.
If squad is specified, then the achievement will be placed in a bucket with the name of the associated squad, on the left side on the achievement screen. See modApi:addSquad on how to set a squad id for your squad.
If secret is specified, then the achievement will not reveal its image or description until after the achievement has been completed.
An achievement's initial progress and the completion goal depends on the type of objective it has.
| Objective | Initial state | Completion goal |
|---|---|---|
true |
false |
true |
number |
0 |
Greater than or equal to the objective |
string |
false |
true |
If an achievement has no specified objective, it will be given the objective: true.
A string objective is functionally the same as a boolean objective. The difference is how the former can customize the substituted tooltip text.
The objective can also be a table of subobjectives. The subobjectives will follow the same rules as a single objective; but all subobjectives must be completed for an achievement to count as complete.
While the tooltip can be a plain string, it can also include substitution keys to display an achievement's progress in a variety of ways.
For single objective achievements, the substitution key is $, and for multi-objective achievements, the substitution key for a single subobjective is $ followed by its key in the objective table.
Depending on an objective's type, the substitued text will vary:
| Objective type | Substitution text when incomplete | Substitution text when completed |
|---|---|---|
boolean |
Incomplete | Complete |
string |
[objective's text up until "` | `"] |
number |
[progress] / [objective] | [progress] / [objective] |
void modApi.achievements:addProgress(mod_id, achievement_id, progress)
| Argument name | Type | Description |
|---|---|---|
mod_id |
string | Id of mod |
achievement_id |
string | Id of achievement |
progress |
boolean or table | The progress to add |
Adds the specified progress for the achievement with the specified achievement_id added by mod with the specified mod_id.
The data type for progress must match the achievement's objective. This progress is added to the current progress of the achievement. If all entries in progress becomes equal to or greater than the corresponding entries in objective, then the achievement's completion state is set to complete.
boolean modApi.achievements:canBeAdded()
Returns true if achievements can be added, or false if they can't.
Achievements can't be added after mods have finished initialization.
table modApi.achievements:get()
Returns a table of all achievments, arranged by mod_id's
table modApi.achievements:get(mod_id)
| Argument name | Type | Description |
|---|---|---|
mod_id |
string | Id of mod |
Returns a table of all achievements added by mod with specified mod_id.
table modApi.achievements:get(mod_id, achievement_id)
| Argument name | Type | Description |
|---|---|---|
mod_id |
string | Id of mod |
achievement_id |
string | Id of achievement |
Returns the achievement table for the specified achievement_id added by mod with specified mod_id.
table modApi.achievements:getProgress(mod_id, achievement_id)
| Argument name | Type | Description |
|---|---|---|
mod_id |
string | Id of mod |
achievement_id |
string | Id of achievement |
Returns the current progress table of the achievement with the specified achievement_id added by mod with the specified mod_id.
table modApi.achievements:getSquadAchievements(squad_id)
| Argument name | Type | Description |
|---|---|---|
squad_id |
string | Id of squad |
Returns a table of all achievements added for squad with specified squad_id.
boolean modApi.achievements:isComplete(mod_id, achievement_id)
| Argument name | Type | Description |
|---|---|---|
mod_id |
string | Id of mod |
achievement_id |
string | Id of achievement |
Checks the completion state of the achievement with the specified achievement_id added by mod with the specified mod_id. Returns true if it is complete, or false if it is not.
boolean modApi.achievements:isProgress(mod_id, achievement_id, progress)
| Argument name | Type | Description |
|---|---|---|
mod_id |
string | Id of mod |
achievement_id |
string | Id of achievement |
progress |
boolean or table | The progress to compare |
Checks the progress state of the achievement with the specified achievement_id added by mod with the specified mod_id.
The data type for progress must match the achievement's objective. This progress is compared to the achievement's objective. If all entries in progress is equal to or greater than the corresponding entries in objective, then it returns true; otherwise false.
void modApi.achievements:reset(mod_id, achievement_id)
| Argument name | Type | Description |
|---|---|---|
mod_id |
string | Id of mod |
achievement_id |
string | Id of achievement |
Resets the progress on for achievement with specified achievement_id added by mod with specified mod_id.
void modApi.achievements:trigger(mod_id, achievement_id)
| Argument name | Type | Description |
|---|---|---|
mod_id |
string | Id of mod |
achievement_id |
string | Id of achievement |
Sets the completion status of an achievement to completed.
void modApi.achievements:trigger(mod_id, achievement_id, status)
| Argument name | Type | Description |
|---|---|---|
mod_id |
string | Id of mod |
achievement_id |
string | Id of achievement |
status |
boolean or table | New achievement completion state |
Modifies the completion state of the achievement with the specified achievement_id added by mod with the specified mod_id.
Sets the completion status of an achievement to completed if status is true, or incompleted if false.
If status is a table, it carries on to call addProgress with the same arguments.