Table of Contents

• modApi
  • achievements
    • add
    • addProgress
    • canBeAdded
    • get
    • getProgress
    • getSquadAchievements
    • isComplete
    • isProgress
    • reset
    • trigger

 

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.