Skip to content
Lemonymous edited this page Mar 29, 2022 · 10 revisions

Table of Contents

 

modApi.achievements

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

 

add

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.

 

objective

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.

 

tooltip

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]

 

addProgress

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.

 

canBeAdded

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.

 

get

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.

 

getProgress

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.

 

getSquadAchievements

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.

 

isComplete

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.

isProgress

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.

 

reset

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.

 

trigger

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.

 

Clone this wiki locally