Achievements

Updated for version 3.38.

Module Definition

The module is inherited from ItemModuleBase. So base parameters can be found there.

This module will allow you to add your own achievements within your mods. They will appear in the Custom Achievements menu which can be accessed next to the button to check on BeardLib mods.

Module Name

The name of the module you use as the meta of the module definition is 'Achievements' or 'AchievementsModule' if _force_search is set to true in the module definition.

XML Structure

<Achievements id name desc icon banner>
    <achievement id name_id desc_id objective_id icon rank amount reward_type reward_amount hidden_achievement />
</Achievements>

`<Achievements id name desc icon banner>`

Parameter Type Description

Parameter	Type	Description
id	String	The ID of your achievement package, which will hold all your achievements.
name	String	A localized string ID for the package's name. Default : `<package_id>_name`
desc	String	A localized string ID for the package's description. Default : `<package_id>_desc`
icon	String	The path to a custom icon for your achievement package. It has to be added through the AddFiles module beforehand. Default: `"guis/textures/achievement_package_default"`.
banner	String	The path to a custom banner for your achievement package. It has to be added through the AddFiles module beforehand. Ideal scale: 820x90

String

The ID of your achievement package, which will hold all your achievements.

name

String

A localized string ID for the package's name. Default : <package_id>_name

desc

String

A localized string ID for the package's description. Default : <package_id>_desc

icon

String

The path to a custom icon for your achievement package. It has to be added through the AddFiles module beforehand. Default: "guis/textures/achievement_package_default".

banner

String

The path to a custom banner for your achievement package. It has to be added through the AddFiles module beforehand. Ideal scale: 820x90

The name, desc, icon and banner options are optional.

`<achievement id name_id desc_id objective_id icon rank amount reward_type reward_amount hidden_achievement />`

Parameter Type Description

Parameter	Type	Description
id	String	The ID of your achievement, which is used to manipulate that particular achievement later.
name_id	String	A localized string ID for the achievement's name. Default : `<achievement_id>_name`
desc_id	String	A localized string ID for the achievement's description. Default : `<achievement_id>_desc`
objective_id	String	A localized string ID for the achievement's objective. Default : `<achievement_id>_objective`
icon	String	The path to a custom icon for your achievement. It has to be added through the AddFiles module beforehand. Default: `"guis/textures/achievement_trophy_white"`. Required scale: 128x128
rank	Integer	Integer from 1 to 4. Defines the achievement rank based on Custom Achievement API: 1 = Bronze, 2 = Silver, 3 = Gold, 4 = Platinum
amount	Integer	Useful for counting things, and saving the progress each time it increases. Once amount is reached, the achievement is automatically unlocked.
reward_type	String	Can be `xp`, `cc`, `cash`, `offshore`. Defines what type of reward the player will get when the achievement is unlocked.
reward_amount	Integer	Has to be an integer that defines how much of `xp`, `cc`, `cash`, or `offshore` the player is going to receive.
hidden_achievement	Boolean	Hides the details of the achievement such as the description, objective, icon and rank. Once unlocked, the details will appear.

String

The ID of your achievement, which is used to manipulate that particular achievement later.

name_id

String

A localized string ID for the achievement's name. Default : <achievement_id>_name

desc_id

String

A localized string ID for the achievement's description. Default : <achievement_id>_desc

objective_id

String

A localized string ID for the achievement's objective. Default : <achievement_id>_objective

icon

String

The path to a custom icon for your achievement. It has to be added through the AddFiles module beforehand. Default: "guis/textures/achievement_trophy_white". Required scale: 128x128

rank

Integer

Integer from 1 to 4. Defines the achievement rank based on Custom Achievement API: 1 = Bronze, 2 = Silver, 3 = Gold, 4 = Platinum

amount

Integer

Useful for counting things, and saving the progress each time it increases. Once amount is reached, the achievement is automatically unlocked.

reward_type

String

Can be xp, cc, cash, offshore. Defines what type of reward the player will get when the achievement is unlocked.

reward_amount

Integer

Has to be an integer that defines how much of xp, cc, cash, or offshore the player is going to receive.

hidden_achievement

Boolean

Hides the details of the achievement such as the description, objective, icon and rank. Once unlocked, the details will appear.

Example

<Achievements id="test_package" icon="guis/tamamo">
        <achievement id="something" rank="2" name_id="third_ach_test_name" icon="guis/tamamo"/>
        <achievement id="another_blablabla" rank="3"/>
        <achievement id="fourth_new_achievement" rank="4"/>
</Achievements>

CustomAchievementManager - Functions

Function Description

Function	Description
HasPackage( String package_id )	Returns `true` or `false`, if the `package_id` specified exists.
HasAchievement( String package_id, String achievement_id )	Returns `true` or `false`, if the `achievement_id` within `package_id` exists.
NumberOfPackages()	Returns a integer on the number of packages the user currently has.
NumberOfAchievements()	Returns a integer on the number of all the achievements the player has, unlocked or not.
CompletedAchievementsTotal()	Returns a integer on the number of all the achievements the player has unlocked only.

HasPackage( String package_id )

Returns true or false, if the package_id specified exists.

HasAchievement( String package_id, String achievement_id )

Returns true or false, if the achievement_id within package_id exists.

NumberOfPackages()

Returns a integer on the number of packages the user currently has.

NumberOfAchievements()

Returns a integer on the number of all the achievements the player has, unlocked or not.

CompletedAchievementsTotal()

Returns a integer on the number of all the achievements the player has unlocked only.

CustomAchievementPackage - Functions

Function Description

Function	Description
init( String package_id )	Initialize a new achievement package with the given `package_id`. The initialization is necessary before using any other function of this class.
GetName()	Get the name of the package. The returned value is already passed through `managers.localization:text()`.
GetDesc()	Get the description of the package. The returned value is already passed through `managers.localization:text()`. If no description was defined, this will return an empty string.
GetIcon()	Get the current package icon path.
GetBanner()	Get the current package banner path.
ManualAchievementAddition( String achievement_id, Table config )	Allows to add an achievement to the package manually. This is useful for multiple mods adding achievements to a unique package.
HasAchievement( String achievement_id )	Returns `true` or `false`, depending on if `achievement_id` exists in the current package.
Achievement (String achievement_id )	Initialize the class CustomAchievement with the provided achievement ID.
GetTotalAchievements()	Returns an integer of the current total of all the achievements within the package.
GetCompletedAchievements()	Returns an integer of the unlocked achievements within the package.
AllAchievementsCompletedExceptOne()	Returns `true` or `false`, depending on if all achievements excepted one are unlocked. This is useful for achievements, such as "complete all achievements to unlock this one".

init( String package_id )

Initialize a new achievement package with the given package_id. The initialization is necessary before using any other function of this class.

GetName()

Get the name of the package. The returned value is already passed through managers.localization:text().

GetDesc()

Get the description of the package. The returned value is already passed through managers.localization:text(). If no description was defined, this will return an empty string.

GetIcon()

Get the current package icon path.

GetBanner()

Get the current package banner path.

ManualAchievementAddition( String achievement_id, Table config )

Allows to add an achievement to the package manually. This is useful for multiple mods adding achievements to a unique package.

HasAchievement( String achievement_id )

Returns true or false, depending on if achievement_id exists in the current package.

Achievement (String achievement_id )

Initialize the class CustomAchievement with the provided achievement ID.

GetTotalAchievements()

Returns an integer of the current total of all the achievements within the package.

GetCompletedAchievements()

Returns an integer of the unlocked achievements within the package.

AllAchievementsCompletedExceptOne()

Returns true or false, depending on if all achievements excepted one are unlocked. This is useful for achievements, such as "complete all achievements to unlock this one".

CustomAchievement - Functions

Function Description

Function	Description
init( Table config, String package )	Initialize the class in order to use all other functions. It's better to first initialize the package in order to bypass the manual initialization, through `CustomAchievementPackage:Achievement(achievement_id)`.
GetName()	Get the name of the achievement. The returned value is already passed through `managers.localization:text()`.
GetDesc()	Get the description of the achievement. The returned value is already passed through `managers.localization:text()`.
GetObjective()	Get the objective of the achievement. The returned value is already passed through `managers.localization:text()`.
GetIcon()	Get the current achievement icon path.
GetUnlockTimestamp()	Get the UNIX timestamp of the unlocked achievement. If the achievement isn't unlocked, this will return `0`.
Package()	Initialize CustomAchievementPackage of this achievement.
IncreaseAmount( Integer amount, Boolean to_max )	Calling this function will increase the `amount` saved value of the achievement by `amount`. If `to_max` is true, it will automatically set the amount to the maximum, in order to unlock the achievement right away.
Unlock()	Unlocks the achievement.
Lock()	Lock the achievement.
IsUnlocked()	Returns `true` or `false` depending on if the achievement is unlocked or not.
IsHidden()	Returns `true` or `false` depending on if the achievement is hidden or not.
HasReward()	Returns `true` or `false` depending on if the achievement has a reward or not.

init( Table config, String package )

Initialize the class in order to use all other functions. It's better to first initialize the package in order to bypass the manual initialization, through CustomAchievementPackage:Achievement(achievement_id).

GetName()

Get the name of the achievement. The returned value is already passed through managers.localization:text().

GetDesc()

Get the description of the achievement. The returned value is already passed through managers.localization:text().

GetObjective()

Get the objective of the achievement. The returned value is already passed through managers.localization:text().

GetIcon()

Get the current achievement icon path.

GetUnlockTimestamp()

Get the UNIX timestamp of the unlocked achievement. If the achievement isn't unlocked, this will return 0.

Package()

Initialize CustomAchievementPackage of this achievement.

IncreaseAmount( Integer amount, Boolean to_max )

Calling this function will increase the amount saved value of the achievement by amount. If to_max is true, it will automatically set the amount to the maximum, in order to unlock the achievement right away.

Unlock()

Unlocks the achievement.

Lock()

Lock the achievement.

IsUnlocked()

Returns true or false depending on if the achievement is unlocked or not.

IsHidden()

Returns true or false depending on if the achievement is hidden or not.

HasReward()

Returns true or false depending on if the achievement has a reward or not.

PreviousModules NextAdd Files

Last updated 2 years ago